Skip to main content

Contributing

Contributing to Path Header Scanner

Review Checklist

Develop language-aware scanning changes with evidence that preview, apply, and dry-run remain safe.

Commandmake check

Category

Developer Guide

Quick Command

scope -> implement -> validate -> document -> hand off
qualitytestspreviewdry-runpre-commit
Quality Helper
make check
Package Runtime
Python 3.11+
Default Scan
Read-only preview
Write Opt-In
--apply

Overview​

Keep CLI interaction under app/cli, reusable scanning under app/core/scan, and language syntax under app/languages. A contribution must not silently turn preview into apply behavior or allow configuration to bypass dry-run.

Contribution Workflow

Workflow Timeline

1
Trace the scan path
Follow target and workdir resolution through discovery, language selection, validation, processing, update, and presentation.
completed
2
Define the file contract
List discovered files, exclusions, expected headers, allowed writes, failures, and dry-run behavior.
completed
3
Implement with tests
Keep scanner and language responsibilities focused and cover preview plus approved mutation paths.
current
4
Run widening validation
Run focused scanner tests, pre-commit checks, make check, and the complete suite.
pending
5
Synchronize documentation
Update commands, supported languages, configuration, output, safety, troubleshooting, and architecture as needed.
pending
6
Prepare the handoff
Report affected files, test targets, quality outcomes, safety evidence, and known limits.
pending

Implementation Standards

Before You Begin

  • Resolve paths onceRequired

    Determine workdir and target before discovery and keep output tied to that resolved identity.

  • Preserve previewRequired

    Default scan behavior must not write target files.

  • Keep apply narrowRequired

    Only selected files with supported language strategies may be updated.

  • Protect dry-runRequired

    Dry-run must override CLI and configured apply values without prompting or file writes.

  • Document language behaviorRequired

    Synchronize syntax, examples, supported extensions, errors, and recovery guidance.

Quality Gates

Contributor validation
bash
# Focused examples
python -m pytest tests/core/scan
python -m pytest tests/languages

# Complete validation

python -m pytest
make check

# Hook validation

make pre-commit-validate
make pre-commit-run-staged
make pre-commit-run

Final Review Checklist

Before You Begin

  • Scope is focusedRequired

    Every change supports the scanner contract, its tests, or documentation.

  • Preview is read-onlyRequired

    Tests prove ordinary scan and dry-run do not modify target files.

  • Apply is preciseRequired

    Only intended files and headers change, with useful success and failure summaries.

  • Quality results are recordedRequired

    Focused tests, full tests, formatting, lint, and relevant builds have explicit outcomes.

  • Release actions remain separateRequired

    Versions, changelogs, tags, pushes, and publication are untouched unless explicitly requested.

Related Commands

Commands commonly used together with this command.

Testing

Validate scanner and language contracts.