scalameta: The Foundation Library for Scala Tooling

A Metaprogramming Foundation for Scala Tooling Authors

scalameta is a Scala library for working with Scala source code as a data structure. The repository's own description states its purpose directly: it is a library to read, analyze, transform, and generate Scala programs. This description defines four distinct operations, each targeting tooling authors rather than application developers.

The library is not a compiler. It does not produce JVM bytecode or execute Scala programs. Its output is either a transformed representation of the original source code or new Scala code generated from a description. Engineers who need to build formatters, linters, style checkers, refactoring tools, code generators, or IDE language server features on top of Scala source code are the target users.

scalameta operates at the source level. It represents Scala code as trees that correspond to the syntactic structure of the source file. This makes it different from the Scala compiler's own internal representations, which are designed for compilation correctness and not for source-fidelity preservation.

Four Operations: Read, Analyze, Transform, Generate

Reading a Scala program means parsing Scala source text into a tree representation that scalameta can work with. The tree preserves whitespace, comments, and syntactic details that a compiler might discard. This fidelity is necessary for tools that need to reproduce the original source with precise modifications, such as a formatter that changes only indentation or a refactoring tool that renames a single identifier.

Analyzing means traversing the tree to extract information: finding all method definitions, collecting import statements, checking for patterns, or comparing the structure of two code files. The analysis operates over the tree without modifying it.

Transforming means producing a modified version of the tree. A transformation rewrites specific tree nodes while leaving others unchanged, producing a new tree that represents modified Scala source.

Generating means constructing a Scala program from scratch by building a tree node by node and emitting it as source text. This covers use cases like code scaffolding tools and macro expansion frameworks that produce Scala code as output.

All four operations are described in the tutorial at scalameta.org/tutorial, which the README directs users to for learning how to use the library.

SemanticDB: Semantic Information Beyond Syntax Trees

The repository contains a semanticdb/ directory alongside the main scalameta/ directory. SemanticDB is a separate component of the project: a data model and format for storing semantic information about Scala programs, including type information, definition locations, symbol references, and cross-file relationships.

Syntax trees describe the structure of individual source files. SemanticDB extends this by capturing what symbols mean across a codebase: where a method is defined, what type a variable has, and which callsites reference which definitions. This information requires the compiler to produce; it is richer than what parsing alone can provide.

The related searches for this project prominently include SemanticDB alongside Metals (a Scala language server for editors) and Scalafmt (a Scala code formatter). This pattern in the search data reflects that SemanticDB is widely used by IDE and editor tooling that needs go-to-definition, find-references, and hover-type information in Scala projects.

The semanticdb/ directory, the ScalaDB tests in tests-semanticdb/, and the community-test/ directory all indicate that SemanticDB is a first-class part of the project with its own test coverage.

Getting Started: Documentation and Compatibility

The README for scalameta is intentionally minimal; it points to the project website at scalameta.org and the tutorial at scalameta.org/tutorial. The tutorial is the primary resource for understanding the API and getting a first program running. The README does not include build file snippets for adding scalameta as a dependency, which is covered in the documentation website instead.

The repository includes two files that are important for adopters: COMPATIBILITY.md and VERSIONING.md. COMPATIBILITY.md documents which Scala compiler versions and Scala 3 dialects each scalameta release supports. This matters because scalameta parses Scala source, and the syntax has changed significantly between Scala 2 and Scala 3. VERSIONING.md explains the project's versioning scheme and binary compatibility promises, which is relevant for library authors who include scalameta as a transitive dependency.

The build system is sbt, visible from the top-level build.sbt. The project uses GitHub Actions for CI (the .github/ directory) and includes bench/ for benchmarks and community-test/ for cross-project compatibility checks.

What scalameta Does Not Cover

scalameta is a source-level library. It does not produce type-checked ASTs with resolved types unless SemanticDB data is brought in from a compiler run. A pure parse of Scala source through scalameta gives the syntactic structure but not the semantic layer. Tools that need full type information, such as a linter that flags type mismatches, require SemanticDB or must integrate with the Scala compiler directly.

The library does not run Scala code. It has no connection to the JVM runtime and cannot evaluate expressions. Tools that need both structural analysis and execution (for example, a testing framework that parses test definitions and then runs them) must combine scalameta with the Scala runtime separately.

Scala 2 and Scala 3 syntax differ, and COMPATIBILITY.md documents which combinations scalameta supports. Not all Scala 3 syntax extensions are supported in every scalameta release. Tooling authors building against the latest Scala 3 features should check COMPATIBILITY.md before relying on a specific release.

scalameta Versus IntelliJ IDEA's Scala PSI

IntelliJ IDEA provides a plugin API called PSI (Program Structure Interface) that allows IntelliJ plugins to parse, traverse, and modify Java and Scala source code. IntelliJ's Scala PSI is tied to the IntelliJ platform: code that uses it can only run inside IntelliJ. It gives access to the full IntelliJ IDE infrastructure, including the VFS, the project model, and the type-aware analysis backed by IntelliJ's type inference.

scalameta is the standalone alternative. Because scalameta is a library rather than a platform API, code that uses it runs anywhere a JVM is available: in a build tool, in a CI pipeline, in a standalone command-line tool, or in an editor language server that is not IntelliJ. The trade-off is that scalameta requires explicit SemanticDB integration to get the type information that IntelliJ's PSI provides automatically through the IDE's compiler integration.

For tooling that must work outside IntelliJ (a Gradle or sbt plugin, a standalone refactoring command, or a language server for editors other than IntelliJ), scalameta is the practical choice. For IntelliJ plugin authors who need tight IDE integration and are willing to stay within the IntelliJ ecosystem, the IntelliJ Scala PSI is richer but not portable.

Versioning, License, and Active Maintenance

scalameta is licensed under BSD-3-Clause, which permits use in both open-source and proprietary products without requiring derivative works to disclose their source. The LICENSE.md file is in the top-level repository.

The project follows a documented versioning scheme described in VERSIONING.md. Recent releases include v4.17.4 on September 11, 2026, v4.17.3 on July 24, 2026, and v4.17.2 on July 9, 2026. The last push to the repository was on September 23, 2026, indicating active development. The project has a team of seven listed maintainers: David Dudson, Ólafur Páll Geirsson, Krzysztof Bochenek, Mikhail Mutcianko, Max Ovsiankin, Gabriele Petronella, and Denys Shabalin.

The official documentation and roadmap are at scalameta.org. The repository has a separate website/ directory for the documentation site. The CONTRIBUTING.md file describes the contribution process, and the .scala-steward.conf file indicates the project uses Scala Steward for automated dependency updates.

Editorial conclusion

scalameta is the right choice for engineers building Scala tooling: formatters, linters, refactoring tools, IDE plugins, or code generators that need to parse, inspect, modify, or emit Scala source. Application developers who just want to write Scala do not need scalameta; it is a library for tools that operate on Scala code, not for code that runs Scala applications. Before building on scalameta, read COMPATIBILITY.md: each release documents which Scala compiler versions and Scala 3 dialects are supported, and the versioning scheme in VERSIONING.md governs binary compatibility promises.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes