stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 1 Releases Wiki Activity
Files
55464f84984ae579eca18456874ba5ccac6ccf29
git.stella-ops.org/docs/dev/java-analyzer-observation-plan.md
Vladimir Moushkov 55464f8498
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
Details
up
2025-10-29 19:24:20 +02:00

3.2 KiB
Raw Blame History

Java Analyzer Observation Writer Plan

Status: 2025-10-29

SCANNER-ANALYZERS-JAVA-21-008 (resolver + AOC writer) is blocked by upstream heuristics that need to settle before we can emit observation JSON. This note itemises the remaining work so the analyzer guild can sequence delivery without re-opening design discussions in every stand-up.

Prerequisite summary

  • SCANNER-ANALYZERS-JAVA-21-004 (reflection / dynamic loader heuristics) – must emit normalized reflection edges with confidence + call-site metadata. Outstanding items: TCCL coverage for servlet containers and resource-based plugin hints. Owners: Java Analyzer Guild.
  • SCANNER-ANALYZERS-JAVA-21-005 (framework config extraction) – required to surface Spring/Jakarta entrypoints that feed observation entrypoint metadata. Add YAML/property parsing fixtures and document reason codes (config-spring, config-jaxrs, etc.).
  • SCANNER-ANALYZERS-JAVA-21-006 (JNI/native hints) – optional but highly recommended before observation writer so JNI edges land alongside static ones. Coordinate with native analyzer on reason codes.
  • Advisory core – ensure AOC writer schema (JavaObservation.json) is frozen before we serialise to avoid churn downstream.

Deliverables for SCANNER-ANALYZERS-JAVA-21-008

  1. Observation projection (JavaObservationWriter)
    • Inputs: normalised workspace + analyzer outputs (classpath graph, SPI table, reflection edges, config hints, JNI hints).
    • Outputs: deterministic JSON containing entrypoints, components, edges, warnings, provenance. Align with docs/aoc/java-observation-schema.md once published.
  2. AOC guard integration
    • Serialize observation documents through Scanner.Aoc guard pipeline; add unit tests covering required fields and forbidden derived data.
  3. Fixture updates
    • Expand fixtures/lang/java/ set to include reflection-heavy app, Spring Boot sample, JNI sample, modular app. Record golden outputs with UPDATE_JAVA_FIXTURES=1.
  4. Metrics & logging
    • Emit counters (scanner.java.observation.edges_total, etc.) to trace observation completeness during CI runs.
  5. Documentation
    • Update docs/scanner/java-analyzer.md with reason code matrix and observation field definitions.

Action items

Owner Task Due Notes
Java Analyzer Guild Land reflection TODOs (TCCL + resource plugin hints) 2025-11-01 Required for reliable dynamic edges.
Java Analyzer Guild Finish config extractor for Spring/Jakarta 2025-11-02 Use sample apps in fixtures/lang/java/config-*.
Java Analyzer Guild Draft observation writer spike PR using new schema 2025-11-04 PR can be draft but should include JSON schema + sample.
Scanner AOC Owners Validate observation JSON against AOC guard + schema 2025-11-05 Blocker for marking 21-008 as DOING.
QA Guild Prepare regression harness + performance gate (<300 ms per fat jar) 2025-11-06 Align with SCANNER-ANALYZERS-JAVA-21-009.

Reporting

  • Track these checkpoints in the Java analyzer weekly sync; once prerequisites are green, flip SCANNER-ANALYZERS-JAVA-21-008 to DOING.
  • Store schema and sample output under docs/scanner/java-observations/ so AOC reviewers have a stable reference.