scala-semantic-harness

# 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`](docs/project-status.md) for current evidence and
readiness limits and
[`docs/semantic-tooling-positioning.md`](docs/semantic-tooling-positioning.md)
for the product boundary. Technical evaluators can use
[`docs/early-feedback.md`](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](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](https://github.com/DmytroMitin/scala-semantic-harness/releases/tag/0.1.0-alpha.3)
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:

```bash
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`](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`](docs/project-status.md) and
[`docs/semantic-api.md`](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.

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

The source-checkout wrapper runs the CLI through sbt:

```bash
./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.

All eight sbt-backed forms (`compile`, `errors`, `test`, target-aware
`semanticdb-for-source`, target-aware `point-evidence`, sbt-backed `infer-type`,
`infer-type-batch`, and `tasty-point-evidence`) also accept an
optional `--sbt-java-home <absolute-directory>`. The harness itself remains on the
supported JDK 21 runtime; only the target sbt child receives the selected
canonical `JAVA_HOME` and a matching `PATH` prefix. The home must already be
installed and pass bound