38 lines
3.2 KiB
Markdown
38 lines
3.2 KiB
Markdown
# 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.
|