scala-semantic-harness

Experimental semantic tooling for Scala and functional-programming projects used by coding agents.

The harness is a bounded semantic evidence layer, not a replacement for the Scala compiler, sbt, tests, Metals, or other IDE/LSP tooling. Compiler, build, and test results remain the final correctness oracle. See docs/project-status.md for current evidence and readiness limits and docs/semantic-tooling-positioning.md for the product boundary. Technical evaluators can use docs/early-feedback.md to report a concrete real-project comparison.

The current tree is the standalone experimental public-alpha source product under the Apache-2.0 license. It was published from an independently constructed, audited clean root followed only by reviewed public-product commits. The earlier mixed development history is retained separately in a private archive and is not part of this public repository.

Mutable source main reports 0.1.0-alpha.4-SNAPSHOT for source development only. No Alpha 4 Central artifact, supported channel, tag, GitHub Release, or release-readiness claim is established. The exact eight-module 0.1.0-alpha.3 release is published on Maven Central, and the public main two-application Coursier channel selects it. Fresh outsider-like JDK 21 install/runtime/update/uninstall through the actual public raw-GitHub URL and Maven Central passed, as did commit-pinned reproduction. Both exact Alpha 2 and Alpha 3 application routes now have bounded supported- distribution READY evidence. The immutable 0.1.0-alpha.3 lightweight tag identifies commit 075a60bfb7d7677d7fdfcc2369c9ffe41c8b32a8, whose two clean builds reproduced all 32 public Maven primaries. Its GitHub prerelease has normal generated source archives plus the exact Linux x86_64 MCPB used by the active official Registry record. The immutable 0.1.0-alpha.2 tag and prerelease retain the independently qualified supported route and source identity for its 32 Central primaries.

Agent quick start

The current supported packaged route is exact 0.1.0-alpha.3 on JDK 21. Install the CLI and generic stdio MCP server first:

cs install --default-channels=false \
  --channel https://raw.githubusercontent.com/DmytroMitin/scala-semantic-harness/main/distribution/coursier/channel.json \
  semantic-scala semantic-scala-mcp
semantic-scala version

Then choose the integration that the agent client supports: the complete CLI, the curated exact-eight MCP projection, and/or the immutable alpha-2 agent skill. Copying this repository's thin skill wrappers into another project is not supported; install the canonical skill from the 0.1.0-alpha.2 tag.

docs/agent-onboarding.md gives copy-ready Codex, Claude Code, Cursor, and VS Code/Copilot recipes, exact local qualification statuses, skill installation, the CLI/MCP surface matrix, and troubleshooting. Alpha-3 project and target-JDK selectors are explicitly excluded from the alpha-2 packaged contract. The qualified mutable main channel selects Alpha 3; Alpha 2 remains reproducible through its immutable tag-pinned channel.

What is included

• structured compile, test, and diagnostic reports;
• SemanticDB inventory, coverage, symbol, and exact-symbol usage evidence;
• bounded Presentation Compiler symbol and type queries;
• reconciliation of dynamic compiler evidence with an explicit SemanticDB artifact;
• a public point-evidence composition that preserves source-artifact discovery, safe selection, live symbol evidence, and conditional reconciliation;
• Alpha 3 opt-in build-target-aware SemanticDB source mapping v4 with a validated optional Scala axis and root-only receipt, alongside target-aware point-evidence v4 with a non-compiling partial existing-output context and explicit v5 existing-internal-Compile-output opt-in, plus strict v6 content-fresh internal-output gating;
• an Alpha 3 CLI-only, same-request post-compile TASTy point-evidence operation with exact stable Scala 3 child-inspector provenance;
• bounded Alpha 3 sbt-backed command, classpath, and TASTy-receipt compatibility proven on sbt 1.12.15 and 2.0.6 fixtures;
• conservative syntax-first FP effect summaries;
• a stdio MCP server exposing exactly eight public tools;
• small external example projects and benchmark infrastructure; and
• a client-neutral semantic-scala agent skill with thin Codex and Claude Code wrappers;
• source templates and a deterministic assembler for a self-contained Agent Plugins 1.0 package containing that skill and the exact-eight MCP server; and
• a supported, independently qualified exact-eight Maven/Coursier application route for exact versions 0.1.0-alpha.2 and 0.1.0-alpha.3, with Alpha 3 current on the public main channel and Alpha 2 retained at its release tag.

Modules

• modules/core: shared JSON models and codecs.
• modules/cli: the semantic-scala command entry point.
• modules/sbt-runner: sbt compile/test subprocess integration.
• modules/semanticdb-reader: SemanticDB inventory and usage evidence.
• modules/presentation-compiler: bounded dynamic semantic queries.
• modules/semantic-reconciliation: static/dynamic symbol comparison and the point-evidence composition and reconciliation contracts.
• modules/fp-analyzers: syntax-first effect summaries.
• modules/mcp-server: CLI-backed MCP stdio adapter.
• modules/benchmark: benchmark models and fixtures.

Build and test

The project uses Scala 3 and sbt. A fresh source setup requires JDK 21, sbt, Git, and Python 3; CI uses Temurin JDK 21. A newer local JDK may work, but it is not the documented baseline.

Scala 3 describes the harness implementation, not a blanket target-language promise. A bounded JDK 21 matrix has verified build/test/error delegation, SemanticDB discovery/symbol/usages, and syntax-first effect summaries on Scala 2.13.18 and Scala 3.3.8 fixtures. The harness is built with Scala 3.9.0 and its dynamic point operations use the linked Scala 3.9.0 Presentation Compiler. That host compiler resolved the matrix's shared-syntax Scala 2 points, but this is not general Scala 2 dialect or compiler support. Target builds still use their selected target compiler; static SemanticDB and post-compile TASTy evidence remain target-artifact evidence. Reconciliation and point evidence inherit the dynamic-source limitation. See docs/project-status.md and docs/semantic-api.md for the exact boundary.

Two maintained real-project Stage-A checks now cover frozen Scala 2.13.18 revisions without source or build changes. scala/scala-java8-compat produced no SemanticDB, so its otherwise-passing alpha-2 matrix preserved truthful degraded point evidence. A bounded production row of scalacenter/scalafix produced target-owned SemanticDB; static symbol discovery, bounded dynamic lookup, exact static/dynamic reconciliation, complete point evidence, and the ordered exact-eight MCP projection passed. Scalafix's aggregated sbt build also exposed that the alpha-2 build oracle cannot select one project row. The Alpha 3 release closes that routing gap with an optional validated project selector; the immutable alpha-2 distribution remains unchanged. These two projects are complementary bounded evidence, not general Scala 2 support or semantic superiority.

The Alpha 3 release sbt subprocess boundary sends project selection plus one product-owned task as a single fixed command sequence. Its injected classpath/receipt adapters use sbt's fileConverter for sbt 2 virtual references and preserve sbt 1 file-backed entries. Readable extensionless sbt 2 CAS JARs are copied directly, without cache scanning, into an owner-only content-addressed area under the selected workspace's generated target tree. A disposable sbt 2.0.6 fixture, a disposable sbt 2.0.7 multi-project fixture, frozen sbt 1.12.15 and sbt 2.0.6 plugin projects, and a frozen Chimney sbt 2.0.7 / Scala 3.8.4 selected row pass their bounded gates. The shared runner uses a request-owned foreground sbt server lifecycle, and structured sbt suite counters preserve ignored/skipped tests in the existing Test JSON fields. This is version-specific evidence, not universal sbt 2 or compiler-plugin compatibility. Chimney's macro-heavy PC points remain neutrally unresolved because target compiler options and plugins are not replayed.

sbt -batch test
sbt cli/stage
sbt mcpServer/stage

The source-checkout wrapper runs the CLI through sbt:

./semantic-scala --help
./semantic-scala version
./semantic-scala compile --json
./semantic-scala compile --sbt-project core2_13 --json
./semantic-scala compile --sbt-project plugin --sbt-java-home /absolute/path/to/installed-jdk --json
./semantic-scala test --json
./semantic-scala errors --json

compile, errors, test, semanticdb-for-source, and point-evidence accept an optional --sbt-project <id> where the ID matches [A-Za-z][A-Za-z0-9_-]*. Without it they preserve ordinary root behavior. With it, compile/errors run that project's fixed Compile scope and test runs its fixed Test scope. The selector is not arbitrary sbt syntax, and a successful selected invocation proves only that bounded project operation, not whole-workspace correctness.