Joseph Magly
afc9dad1b2
* docs(policy): allow low-impact contributor courtesy cleanup * chore(aiwg): migrate to shared BT6 maintainer plugin * chore: reconcile delivery validation
79 lines
3.7 KiB
Markdown
79 lines
3.7 KiB
Markdown
# UC-004 — Analyze a Source Code Repository
|
|
|
|
## Metadata
|
|
|
|
- **ID:** UC-004
|
|
- **Status:** Baselined; multi-language coverage remains experimental
|
|
- **Level:** User goal
|
|
- **Scope:** Repository ingest, structural extraction, white-box analysis, evidence, and finding verification
|
|
- **Primary actor:** Security researcher
|
|
- **Goal:** Ingest an authorized repository and identify evidence-backed vulnerability candidates without overstating language or analysis maturity.
|
|
- **Related story:** US-07
|
|
- **Quality drivers:** NFR-03, NFR-08, NFR-09, NFR-11
|
|
|
|
## Preconditions
|
|
|
|
- The researcher is authorized to analyze the repository.
|
|
- Input size and file types satisfy configured containment limits.
|
|
- Required parser grammars or safe fallback behavior are available.
|
|
|
|
## Trigger
|
|
|
|
The researcher selects a repository or supported source input for white-box analysis.
|
|
|
|
## Main Success Scenario
|
|
|
|
1. The system enumerates eligible files under configured containment and size limits.
|
|
2. Ingest identifies the language and selects the corresponding structural parser.
|
|
3. The parser extracts bounded code blocks with source locations.
|
|
4. Analysis processes the blocks and emits candidate observations with source evidence.
|
|
5. Candidate findings are graded, refuted, or verified against the cited code.
|
|
6. Results report language/parser maturity and verification status.
|
|
|
|
## Alternate Flows
|
|
|
|
- A supported Tree-sitter grammar extracts structural blocks for the detected language.
|
|
- The Python-specific path uses its specialized parser where configured.
|
|
- A safe documented fallback may produce reduced-fidelity blocks while marking the limitation.
|
|
|
|
## Exception Flows
|
|
|
|
- Unsupported input: fail safely with an explicit unsupported-language result.
|
|
- Oversized, recursive, binary, or escaping input: containment limits reject or bound processing.
|
|
- Parser failure: record the error and do not fabricate structural evidence.
|
|
- Unverified candidate: retain as a candidate or refuted result, never silently promote to verified.
|
|
|
|
## Postconditions
|
|
|
|
- Each reported code observation can identify its source file and region.
|
|
- Parser limitations and experimental maturity remain visible.
|
|
- Repository content never grants authority to override analysis or safety instructions.
|
|
|
|
## Acceptance Criteria
|
|
|
|
- [ ] Supported grammars extract source blocks with stable file and line context.
|
|
- [ ] Unsupported or malformed input fails explicitly and safely.
|
|
- [ ] Ingest limits prevent unbounded traversal or oversized processing.
|
|
- [ ] Findings preserve source evidence and verification state.
|
|
- [ ] Documentation does not generalize benchmark success beyond the evaluated corpus/language path.
|
|
|
|
## Design and Test Traceability
|
|
|
|
| Concern | Implementation | Verification |
|
|
| --- | --- | --- |
|
|
| Input containment | `src/recon/code-ingest.ts`, `src/recon/whitebox.ts` | Ingest-limit and white-box-containment tests |
|
|
| Structural parsing | `src/recon/ts-parse.ts`, grammar registry | Parser, grammar, fallback, and adversarial tests |
|
|
| Evidence-backed output | `src/analysis/`, finding verification scripts | Verification and report-redaction tests |
|
|
|
|
## References
|
|
|
|
- @.aiwg/architecture/software-architecture-doc.md — Reconnaissance and source-ingest component design.
|
|
- @.aiwg/architecture/vision-alignment.md — Maturity boundary for source analysis claims.
|
|
- @src/recon/code-ingest.ts — Repository ingest and limits.
|
|
- @src/recon/ts-parse.ts — Structural parser implementation.
|
|
- @src/recon/whitebox.ts — White-box analysis composition.
|
|
- @src/__tests__/ingest-limits.test.ts — Resource-containment evidence.
|
|
- @src/__tests__/ts-parse-adversarial.test.ts — Adversarial parser evidence.
|
|
- @src/__tests__/whitebox-containment.test.ts — Path and analysis containment evidence.
|
|
- @scripts/verify-finding.mjs — Finding-verification path.
|