feat: L1 emission in canonical schema v2 (opt-in via --schema v2) (#188)

* feat(schema): can:// id + byte-offset span utils for v2 (#180)

* test: add real-world Java app fixtures as git submodules (#180)

* feat(schema): v2 L1 module/type tree — AST-driven modular builders (#180)

* build: exclude test-application fixtures from spotless formatting (#180)

* feat(schema): nested member types via containment; drop nesting field (D4) (#180)

* feat(schema): callable/field/param builders; call sites keyed by local id (#180)

Key body nodes by bare local id (line:col) per the keystone, and emit call nodes for constructor
invocations and this()/super() chaining so L2 can resolve those edges.

* feat(schema): v2 JSON config, module imports/hash/span, field kind, is_variadic (#180)

Add V2Json (snake_case keys, no nulls emitted), module span/imports/
content_hash, field kind discriminator and parameter is_variadic, with a
serialization-contract test covering the emitted key names.

* feat(schema): type/param modifiers, field initializer, declaration, code_start_line, comments (#180)

* feat(schema): local variables on callable (#180)

* feat(schema): resolve types via the JavaParser symbol solver at L1 (#180)

Types, supertypes, error_channel and refs.types are now resolved to
qualified names, and callable signatures use erased resolved parameter
types, matching the v1 symbol table. Tests parse with a symbol solver so
the resolution path is actually exercised; unresolvable types degrade to
their AST spelling.

* feat(schema): enum constants, record components, initializer-block callables (#180)

* feat(schema): rich call-site facts on call nodes (receiver/arg types, callee signature, flags) (#180)

* feat(schema): entrypoint flags, qualified field refs, broader type refs, AstScopes (#180)

* feat(schema): L1 extractor — v2 modules from the project parse loop (#180)

* feat(cli): --schema v2 emits the canonical envelope, with flag validation (#180)

v2 is opt-in (v1 stays the default until the rest of the migration lands).
Unsupported combinations (-a > 1, --emit neo4j, --source-analysis,
--target-files, unknown --schema) fail with a clear non-zero error rather
than silently emitting a different shape. stdout carries compact JSON only.

* test: L1 conformance gate against the canonical v2 JSON Schema (#180)

Adds the strict in-repo schema used as the L1 oracle until the SDK's v2
models exist, a gate over the in-repo fixtures in the default suite, and a
realWorldConformanceTest task for the submodule applications (too slow for
the inner loop, but required).

* fix(schema): resolve library types at L1; omit unknown static-call flag (#180)

L1 now downloads the project's dependencies and puts a JarTypeSolver on the
solver path, so third-party types resolve to qualified names as they do in
v1 (verified on spring-petclinic: Model, Pageable, Page<Owner>, and
callee_signature on 99% of call sites). Reflection is restricted to the JRE
so the analyzer's own dependencies can no longer be resolved as if the
analysed project depended on them. is_static_call becomes a Boolean that is
omitted when the callee is unresolved rather than reported as false.

* test: drop the daytrader-microservices fixture (contains no Java source)

The repo is deployment tooling (Makefile, docker-compose, helm charts) with
zero .java files, so it cannot exercise the analyzer. Also ignores output/,
used for ad-hoc v1/v2 comparison runs.

* feat(schema): model anonymous classes; add callable body_span (#180)

Anonymous class bodies now get their own type node ($anon$N) under the
callable that declares them, like named local classes — v1 mis-attributed
their initializers and locals to the enclosing type and the first v2 attempt
dropped them. Re-measured, initializer blocks and local variables are back
at parity with v1.

body_span delimits the { ... } block so source[body_span.bytes] reproduces
v1's per-callable code byte for byte without duplicating the text; the
callable's own span covers the whole declaration. Pinned by a test that
compares against the v1 emitter directly.

* feat(schema): model anonymous classes in field initializers; add comparison report

Anonymous classes occur in two places: inside a callable body and inside a
field initializer, which belongs to no callable. The latter was missed, so
commons-lang's AnnotationUtils lost the double-brace initializer configuring
its ToStringStyle.

Adds docs/design/notes/l1-v1-v2-comparison.md, generated from twenty runs
(ten applications x both schemas). v2 matches or exceeds v1 on every
structural metric; the two remaining negative deltas are v1 counting bugs
(anonymous-class fields reported as method locals, nested initializer blocks
counted twice) that v2 does not reproduce.

* feat(cli): incremental L1 cache keyed on content_hash (-c/--cache-dir, --eager)

Reuses modules whose files are byte-for-byte unchanged, skipping the parse
as well as the build: commons-lang goes from 130s cold to 4s warm. Caching
is opt-in, and the cache is discarded wholesale when the app name or
analyzer version changes since both are baked into every can:// id.

The extractor now enumerates and hashes files itself instead of parsing
whole source roots up front; module discovery is unchanged (commons-lang
still yields 625 modules, matching v1).

* fix(schema): six correctness fixes from code review

- Constructor callee_signature normalises to <init> so it joins against the
  target callable's signature; otherwise L2 drops every constructor edge
  (88 of petclinic's call sites).
- Expression-type resolution no longer memoises failures by expression text:
  the same text can denote different types in different scopes of one file,
  so a failure blanked later resolvable occurrences.
- metrics.cyclomatic is scope-filtered like every other callable fact, so
  branches inside a nested or anonymous class are no longer double-counted.
- Call sites with no source range are skipped rather than colliding on 0:0
  and silently overwriting one another.
- Module span end position is computed for universal newlines and for files
  with no trailing newline.
- Corrected the byteOffsets javadoc: the range is end-exclusive.

* fix(schema): emit dropped constructs; restore v1 call-site facts

Constructs L1 was silently dropping:
- compact constructors (CompactConstructorDeclaration is not a
  CallableDeclaration; signature comes from the record components)
- enum-constant class bodies, as $enum$<NAME> types whose overrides are
  their own callables
- nested anonymous classes in field initializers were double-emitted
- partial parses are now announced instead of accepted silently

Lapsed v1 parity on call sites: method_name, return_type, comment, and
accessibility as a single enum replacing v1's four booleans (which
conflated unknown with package-private). Initializer error_channel now
reaches throws nested inside catch blocks.

Also: per-parameter signature degradation instead of all-or-nothing,
drop the redundant code_start_line, fix stale javadocs.

* feat(schema): model type parameters on generic types and callables

A generic signature was not reconstructable from the emitted facts: a
parameter declared `T` resolves to the bare spelling `T` (a type variable
has no qualified name), and `declaration` omits the clause because
JavaParser's getDeclarationAsString does. So `type: "T"` appeared with no
record of what T ranges over.

type_parameters on `type` and `callable` carries the name, resolved bounds,
span and annotations, in declaration order (a type argument binds by
position). An unbounded parameter gets no bounds rather than a fabricated
java.lang.Object. Genericity is keyed off NodeWithTypeParameters, so enums,
annotation types, anonymous classes and enum-constant bodies are excluded
by the language rule rather than an instanceof chain.

Purely additive: signatures, ids and call-site joins are untouched.

* fix(schema): fully erase signatures; synthesize implicit constructors

Erasure was one level deep, so a type variable's bound kept its own type
arguments: `<T extends Consumer<?>> copy(T...)` was keyed
`copy(java.util.function.Consumer<?>[])`, and `<T extends Comparable<T>>`
leaked `T` into a durable name. Iterate to a fixpoint. Also repairs v1,
whose WALA join compares these keys against fully-erased ASM descriptors.
55 of 4688 callables change across the fixtures, all in commons-lang.

L1 now emits the constructors the language guarantees but the source
never writes, so a `new Foo()` site names a callable instead of a
dangling id: classes and enums declaring none, a record's canonical
constructor, and an anonymous class's generated one. Identity only.

Enum constant bodies are excluded: which constructor a constant invokes
is not recoverable, and a constant is not a call site.

Author: sinha108

.claude/SCHEMA_DECISIONS.md

@@ -196,3 +196,6 @@ gradle-app.setting
 bin/
 etc/
 /src/test/resources/sample_apps/daytrader8/output/
+
+# Ad-hoc analysis output from manual v1/v2 comparison runs
+output/

.gitignore

@@ -0,0 +1,24 @@
+[submodule "src/test/resources/test-applications/spring-petclinic"]
+	path = src/test/resources/test-applications/spring-petclinic
+	url = https://github.com/spring-projects/spring-petclinic.git
+[submodule "src/test/resources/test-applications/cargotracker"]
+	path = src/test/resources/test-applications/cargotracker
+	url = https://github.com/eclipse-ee4j/cargotracker.git
+[submodule "src/test/resources/test-applications/commons-lang"]
+	path = src/test/resources/test-applications/commons-lang
+	url = https://github.com/apache/commons-lang.git
+[submodule "src/test/resources/test-applications/quarkuscoffeeshop-counter"]
+	path = src/test/resources/test-applications/quarkuscoffeeshop-counter
+	url = https://github.com/quarkuscoffeeshop/quarkuscoffeeshop-counter.git
+[submodule "src/test/resources/test-applications/quarkuscoffeeshop-barista"]
+	path = src/test/resources/test-applications/quarkuscoffeeshop-barista
+	url = https://github.com/quarkuscoffeeshop/quarkuscoffeeshop-barista.git
+[submodule "src/test/resources/test-applications/quarkuscoffeeshop-kitchen"]
+	path = src/test/resources/test-applications/quarkuscoffeeshop-kitchen
+	url = https://github.com/quarkuscoffeeshop/quarkuscoffeeshop-kitchen.git
+[submodule "src/test/resources/test-applications/quarkuscoffeeshop-inventory"]
+	path = src/test/resources/test-applications/quarkuscoffeeshop-inventory
+	url = https://github.com/quarkuscoffeeshop/quarkuscoffeeshop-inventory.git
+[submodule "src/test/resources/test-applications/quarkuscoffeeshop-domain"]
+	path = src/test/resources/test-applications/quarkuscoffeeshop-domain
+	url = https://github.com/quarkuscoffeeshop/quarkuscoffeeshop-domain.git

.gitmodules

@@ -142,21 +142,48 @@ dependencies {
     testRuntimeOnly 'org.junit.jupiter:junit-jupiter-engine:5.10.1'
 
     // SLF4J - for TestContainers logging
+    // Validates emitted analysis.json against the canonical v2 JSON Schema (the L1 conformance oracle
+    // until the SDK's v2 models exist).
+    testImplementation 'com.networknt:json-schema-validator:1.5.1'
     testImplementation 'org.slf4j:slf4j-api:2.0.9'
     testImplementation 'org.slf4j:slf4j-simple:2.0.9'
     implementation "org.jetbrains.kotlin:kotlin-stdlib-jdk8"
 
 }
 
 test {
-    useJUnitPlatform()
+    useJUnitPlatform {
+        // Whole-application conformance runs take minutes (full symbol resolution over real projects),
+        // so they are opt-in via `realWorldConformanceTest` rather than part of the inner loop.
+        excludeTags 'realworld'
+    }
     // Optional: Enable TestContainers reuse to speed up tests
     systemProperty 'testcontainers.reuse.enable', 'true'
 }
 
+// The L1 conformance gate over the real-world fixture applications (git submodules).
+tasks.register('realWorldConformanceTest', Test) {
+    description = 'Runs the L1 conformance gate over the real-world fixture applications.'
+    group = 'verification'
+    testClassesDirs = sourceSets.test.output.classesDirs
+    classpath = sourceSets.test.runtimeClasspath
+    useJUnitPlatform {
+        includeTags 'realworld'
+    }
+    // These projects are large; give the JVM room and do not let a slow app fail the run spuriously.
+    maxHeapSize = '4g'
+    testLogging {
+        events 'passed', 'failed', 'skipped'
+        showStandardStreams = false
+    }
+}
+
 spotless {
     java {
-        target 'src/**/*.java'
+        // Format only the analyzer's own sources. Test-application fixtures under
+        // src/test/resources (vendored apps and git submodules) are third-party inputs and must
+        // not be reformatted — doing so mutates test inputs and dirties submodule working trees.
+        target 'src/main/java/**/*.java', 'src/test/java/**/*.java'
         trimTrailingWhitespace()
         endWithNewline()
         importOrder()

build.gradle

@@ -0,0 +1,179 @@
+# L1 output comparison: legacy v1 schema vs canonical schema v2
+
+Generated 2026-08-19 from `codeanalyzer-2.4.1`. Each of ten real-world fixture applications was analysed
+twice — once with the default (v1) emitter, once with `--schema v2` — and the payloads diffed field by
+field. The purpose is to catch silent information loss in the migration: every metric where v2 records
+less than v1 is either explained or fixed.
+
+## How to reproduce
+
+```bash
+./gradlew fatJar
+JAR=build/libs/codeanalyzer-2.4.1.jar
+APP=src/test/resources/test-applications/spring-petclinic
+java -jar $JAR -i $APP -o output/spring-petclinic/v1 -a 1           # legacy
+java -jar $JAR -i $APP -o output/spring-petclinic/v2 --schema v2    # canonical
+```
+
+Payloads land in `output/<app>/<schema>/analysis.json` (`output/` is git-ignored). The figures in this
+document are generated from those files, so it cannot drift from the data.
+
+## Runs
+
+All twenty runs exited 0 and left the fixture submodules clean.
+
+| Application | v1 time | v2 time | v1 size | v2 size |
+| --- | --- | --- | --- | --- |
+| `spring-petclinic` | 5s | 4s | 2.4M | 2.9M |
+| `cargotracker` | 17s | 4s | 4.7M | 5.8M |
+| `commons-lang` | 623s | 148s | 128M | 142M |
+| `quarkuscoffeeshop-counter` | 3s | 3s | 1.5M | 1.9M |
+| `quarkuscoffeeshop-barista` | 3s | 2s | 425K | 575K |
+| `quarkuscoffeeshop-kitchen` | 2s | 2s | 342K | 460K |
+| `quarkuscoffeeshop-inventory` | 3s | 3s | 415K | 581K |
+| `quarkuscoffeeshop-domain` | 2s | 2s | 343K | 491K |
+| `daytrader8` | 5s | 4s | 8.5M | 10M |
+| `plantsbywebsphere` | 3s | 2s | 3.0M | 3.7M |
+
+**v2 is consistently faster.** It never builds per-callable `code` strings, so it never invokes
+JavaParser's `LexicalPreservingPrinter` — the dominant cost on large projects. (A second-order effect:
+each v2 run reused dependency jars the preceding v1 run had already downloaded.)
+
+**Incremental caching** (`-c/--cache-dir`) reuses modules whose files are byte-for-byte unchanged,
+skipping both the parse and the build: a second `commons-lang` run drops from 130s to 4s. The timings
+above are all cold runs, so they measure the emitters rather than the cache.
+
+**v2 payloads are somewhat larger** even though per-callable `code` is gone: source text is stored once
+per module rather than duplicated per callable, but that saving is outweighed by spans on every node
+(`start`/`end`/`bytes`), per-node comments, local variables, and the resolved call-site facts.
+
+## Totals across all ten applications
+
+| Metric | v1 | v2 | Delta |
+| --- | --- | --- | --- |
+| modules | 1081 | 1081 | +0 |
+| types | 1581 | 1814 | +233 |
+| callables | 13594 | 13850 | +256 |
+| fields | 3727 | 3761 | +34 |
+| parameters | 9877 | 10077 | +200 |
+| call sites | 94501 | 94917 | +416 |
+| local variables | 11650 | 11639 | -11 * |
+| comment entries | 39170 | 9710 | -29460 * |
+| enum constants | 338 | 338 | +0 |
+| record components | 2 | 2 | +0 |
+| initializer blocks | 30 | 29 | -1 * |
+| entrypoint types | 95 | 95 | +0 |
+| entrypoint callables | 258 | 258 | +0 |
+| CRUD facts | 107 | 0 | -107 * |
+
+\* explained below. Of the four, two (`local variables`, `initializer blocks`) turn out to be v1
+over-counting rather than v2 losses; one (`comment entries`) is mostly v1 duplication with a small real
+gap; and one (`CRUD facts`) is deliberately deferred.
+
+**Type resolution is at parity:** 95.7% of v1 parameter types and 95.8% of v2 parameter types are
+fully qualified. v2 additionally resolves a callee signature on 94152 of 94917 call sites (99%), which v1
+recorded only on its separate `call_sites` entries.
+
+**Identity:** all 1081 v1 `symbol_table` keys are absolute filesystem paths; v2 has 0 absolute keys —
+every key is project-relative, which the canonical schema requires for stable caching and SDK lookups.
+
+**Anonymous classes:** 215 are modelled as their own `type` nodes across the ten applications.
+**Body text:** 13589 callables carry a `body_span`.
+
+## Per-application detail
+
+Metrics where the two schemas differ, per application. Blank means exact parity.
+
+| Application | types | callables | call sites | locals | initializers | comments | CRUD |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| `spring-petclinic` | +3 | +2 |  |  |  | -225 |  |
+| `cargotracker` | +2 | +4 | +78 | +3 |  | -501 | -77 |
+| `commons-lang` | +218 | +237 | +296 | -14 | -1 | -25342 |  |
+| `quarkuscoffeeshop-counter` | +3 | +3 | +3 |  |  | -71 |  |
+| `quarkuscoffeeshop-barista` | +1 | +1 | +2 |  |  | -16 |  |
+| `quarkuscoffeeshop-kitchen` | +1 | +1 | +3 |  |  | -65 |  |
+| `quarkuscoffeeshop-inventory` | +1 | +1 | +3 |  |  | -23 |  |
+| `quarkuscoffeeshop-domain` |  |  | +12 |  |  | -6 |  |
+| `daytrader8` | +4 | +7 | +17 |  |  | -2244 | -30 |
+| `plantsbywebsphere` |  |  | +2 |  |  | -967 |  |
+
+## Where v2 recovers more than v1
+
+- **Types, callables and call sites.** v1 keyed its flat type map by fully-qualified name and skipped
+  declarations without one, so **local classes declared inside method bodies were dropped entirely**;
+  v2 nests them under the enclosing callable. v1's call-site scan also missed **explicit constructor
+  chaining** (`this(...)` / `super(...)`), which v2 emits as `call` nodes so L2 can resolve those edges.
+- **Anonymous inner classes** are modelled as `type` nodes (`$anon$0`, `$anon$1`, … in declaration
+  order) under the callable that declares them, so their methods, initializers, locals and call sites
+  are attributed to them. v1 recursed into anonymous bodies and mis-attributed those facts to the
+  *enclosing type*.
+- **Resolved call-site facts** — callee signature, receiver expression and type, argument types — sit on
+  the body `call` nodes.
+- **Structured annotation arguments.** v1 stored annotations as flat strings (`@RequestMapping("/x")`);
+  v2 records `{name, args[], span}`, so routes and column names are machine-readable without re-parsing.
+
+## Where v2 records less, and why
+
+### Comment entries (-29460): v1 double-counting, plus one real gap
+
+v1 filled every node's `comments` with `getAllContainedComments()`, so a comment inside a method was
+also listed on that method's type and on the compilation unit. On `spring-petclinic` v1 emits 341
+comment entries of which only **163 are distinct** (a 2.09x duplication factor); v2 emits 116, each
+attached to exactly one node.
+
+The remaining ~47 distinct comments v2 does not carry are **comments inside method bodies**, which
+have no declaration to attach to. They stay recoverable from `module.source`, and they belong on the
+statement nodes that arrive at L3 — but today they are absent from the tree. This is the one
+outstanding information gap.
+
+### Local variables (-11) and initializer blocks (-1): v1 over-counting
+
+Both remaining deltas are **v1 defects**, not v2 losses — v2 is the more accurate of the two.
+
+*Locals.* v1 collected a callable's locals with a recursive `findAll(VariableDeclarator)`, which also
+matches **field declarations inside anonymous classes**. In `AtomicInitializerObjectTest`:
+
+```java
+final AtomicInitializer<Object> initializer = new AtomicInitializer<Object>() {
+    final AtomicBoolean firstRun = new AtomicBoolean(true);   // a field of the anonymous class
+    ...
+};
+```
+
+v1 reports the enclosing method's locals as `[initializer, firstRun]`, promoting the anonymous class's
+field to a method local. v2 reports `[initializer]` and records `firstRun` under
+`$anon$0.fields`, where it belongs. Every one of the remaining local-variable differences is this
+pattern.
+
+*Initializer blocks.* v1 populated a type's `initialization_blocks` with a recursive `findAll`, so a
+`static { ... }` block in a nested class was counted **twice**: once on the nested class and again on
+its enclosing type. `LocaleUtils` shows this — v1 reports one block on `LocaleUtils` and one on
+`LocaleUtils.SyncAvoid`, though only `SyncAvoid` has a block. v2 counts it once, on `SyncAvoid`.
+
+### CRUD facts (-107): tracked separately
+
+v2 carries no CRUD data yet. This is deliberate and tracked in codeanalyzer-java issue 187, which also
+covers the Neo4j `JCrudOperation`/`JCrudQuery` families that the graph projection needs.
+
+## Body text: v1 `code` versus a v2 slice
+
+v2 has no per-callable `code` string — body text is a slice of `module.source`. That equivalence needs
+care, because a callable's own `span` covers the **whole declaration** (modifiers, signature and body),
+whereas v1's `code` was the `{ … }` **block alone**. `callable.body_span` delimits the block, so:
+
+```
+source[body_span.bytes]   ==   v1 callable.code      (byte for byte)
+source[span.bytes]        ==   declaration + body
+```
+
+A test compares the two emitters directly on the same source for methods, constructors and initializer
+blocks, so this cannot regress silently. Note that the canonical schema defines `get_method_body(sig)`
+as `module.source[callable.span.bytes]`, which is *not* v1's `code` semantics — a discrepancy worth
+resolving upstream.
+
+## Outstanding follow-ups
+
+1. **Attach body-internal comments** to the statement nodes introduced at L3.
+2. **CRUD enrichment** — codeanalyzer-java issue 187.
+3. Consider a more compact span encoding if payload size becomes a concern.
+