scanner-protocol

Scanner — Operational Protocol

Protocol

1. DISCOVER

1. Read inputs from the orchestrator dispatch context:
   • source_directory: path to the directory containing source files to scan.
   • metrics_output_path: path where scanner-metrics.json must be written.
   • state_path: path to pipeline-state.json for status updates.
   • run_id: current run identifier.
   • root: resolved scope root.
2. Verify source_directory exists and is a readable directory. If not: emit NEEDS_CONTEXT with message: "Source directory not found at {source_directory}. Provide a valid path and re-run."
3. Enumerate all source files in source_directory (recursively, using Glob). Common source extensions: .py, .js, .ts, .go, .java, .rb, .rs, .cs. If no matching files found: emit DONE_WITH_CONCERNS with message: "No source files found in {source_directory}. Metrics file written with zero entries."

2. PROCESS

For each source file discovered:

1. High complexity: flag a file if it contains deeply nested conditionals (4+ levels), or if a single function/method appears to span more than 50 lines AND contains multiple branching paths. Record:

   {"file": "{relative_path}", "complexity_score": <integer>, "reason": "<brief reason>"}
   

2. Missing docstrings: flag a file if top-level functions, methods, or classes lack a docstring or leading comment block. Record:

   {"file": "{relative_path}", "locations": ["<class or function signature>"]}