Inspectie-scanner patronen voor projectanalyse
Definitie
Terugkerende patronen en valkuilen bij het bouwen van scripts die een projectdirectory inspecteren om stack, dependencies, env vars, git-state en secrets automatisch te detecteren. Gebaseerd op de ervaring met handoff_inspect.py uit de project-handoff skill.
Context
Een inspectie-scanner krijgt een directory en moet daaruit machine-leesbare metadata produceren. De naïve implementatie (os.walk plus een paar regex-checks) loopt in de praktijk tegen meerdere categorieën bugs aan: onbedoelde shadowing, fixture-pollution, bare script repos, relatieve paden met lege namen. Dit artikel verzamelt de lessen.
Kernpunten
Fixture-isolatie
Paden die test-fixtures of gegenereerde output bevatten moeten uit alle scans worden uitgesloten: env-vars, secrets, TODO-count, LOC-estimate. Anders vervuilen de test-data de hoofdinventaris van het project dat je eigenlijk inspecteert.
Blocklist pad-segmenten:
tests/fixtures,test/fixturestests/output,tests/dogfood__fixtures__,fixtures/
Implementatie: een helper die rel_path.replace('\\', '/') checkt op segment in rel.
Stack-detectie fallback
Als alle primaire detectors (Node via package.json, Python via pyproject.toml, Hugo via hugo.toml, Go via go.mod) niks vinden, tel dan file-extensies en maak de dominante taal leidend. Zonder fallback blijft een pure-script repo (losse .py of .sh bestanden zonder manifest) volledig onzichtbaar.
Volgorde: draai alle primaire detectors eerst, dan de fallback als inv.stack['languages'] leeg is. Zet een duidelijke package_managers: "none (bare scripts)" zodat downstream templates weten dat er geen install-step is.
Script-naamgeving
Een script dat inspect.py heet botst met Python’s stdlib module inspect, die indirect door dataclasses wordt geimporteerd. Circular import error bij runtime. Les: namen die stdlib-modules overlappen altijd vermijden. Prefix met project-scope (handoff_inspect.py).
Andere bekende shadowings om te vermijden: email.py, types.py, json.py, string.py, logging.py.
Relatieve paden en project-naam
Als de CLI python3 script.py . accepteert en daarna Path('.').name gebruikt, krijg je een lege string terug. Pathlib geeft voor een dot-path geen naam. Fix: altijd .resolve() aanroepen voordat je .name gebruikt.
inv = inspect(args.project.resolve()) # ipv inspect(args.project)Default ignore dirs
Naast secrets-blocklist horen deze directories standaard buiten de scan:
.git, node_modules, __pycache__, .venv, venv, .mypy_cache, .pytest_cache,
dist, build, .next, .nuxt, target, .idea, .vscode, public, resources,
_site, vendor, .turbo, .cache, coverage
public en resources zijn specifiek voor Hugo (gegenereerd). vendor voor Go en PHP. target voor Rust en Maven.
Tree depth
Voor een handoff-document is depth=2 met max 12 entries per directory genoeg om de structuur te tonen zonder 200+ regels. Truncatie-indicator ... (N more) als de directory langer is. Depth 3+ produceert onoverzichtelijke dumps.
Smoke test selectie
Voor een reproduce-script dat op een schone machine draait: kies een build-commando als smoke test, nooit een run-commando. Build commando’s exit na voltooiing; run commando’s (hugo server -D, npm run dev) blokkeren de foreground en laten het setup-script hangen.
Volgorde in code: scripts.build[0] > scripts.test[0] > fallback echo.
Verbanden
- Zie ook: wiki-secrets-safeguard-project-handoffs
- Zie ook: wiki-agent-entrypoint-conventies
- Gerelateerd project: project-handoff-skill
Bronnen
Interne ervaring uit project-handoff skill development. Geen externe bronnen.