pygienium/tasks/02-recon.md

02. Deterministic code reconnaissance module

meta: id: pygienium-02 feature: pygienium priority: P1 depends_on: [pygienium-01] tags: [infrastructure, no-model]

objective:

• Build src/recon.ts: a deterministic, no-model pass that walks the target repo and writes a compact markdown report (languages, manifests, file counts, dead-file candidates) so every check has stable ground truth.

deliverables:

• src/recon.ts exporting runRecon(cwd), runReconAsync(cwd, opts), reconReportPath(cwd), ReconResult
• Writes pygienium/recon/report.md under cwd
• Detects: languages by extension, build manifests, total files/bytes, git head/branch, and a "candidate files" list (source files not under skip dirs) written to pygienium/recon/candidates.jsonl + summary
• Soft caps (MAX_FILES, MAX_BYTES) and SIGINT-safe async walk mirroring piolium's recon

steps:

• Port piolium's recon.ts structure: MANIFEST_FILES, LANGUAGE_BY_EXT, SKIP_DIRS, safe git exec, walkAndTally + async variant with yieldToEventLoop
• Adapt skip dirs to include pygienium (own output dir)
• Add a candidates.jsonl emitter listing source files (by language) for the check runners to consume; cap entries to keep it bounded
• Export buildReconReport for unit testing

tests:

• Unit: buildReconReport on a fake ReconResult produces expected markdown sections (Arrange a result, Act build, Assert headers present)
• Integration: run recon against this repo; assert report.md + candidates.jsonl exist and counts > 0

acceptance_criteria:

• runRecon(cwd) returns a ReconResult and writes report.md + candidates.jsonl
• A repo without .git does not throw (graceful degradation)
• Very large trees are capped without wedging

validation:

• Inspect pygienium/recon/report.md and pygienium/recon/candidates.jsonl after a run

notes:

• Recon is Q0-equivalent: deterministic, runs in-process, no model calls
• This is the foundation every check consumes for targeting