A clean and lightweight developer utility for automatically inserting, validating, and updating file path headers across source code and documentation files.
Supports:
- Python
- JavaScript / TypeScript
- Shell scripts
- PHP
- HTML
- Markdown
Designed for:
- local development
- Docker workflows
- CI/CD pipelines
- multi-language repositories
- Recursive directory scanning
- Automatic path header generation
- Missing header insertion
- Invalid header replacement
- Dry-run support
- Debug logging
- Docker support
- Docker Compose support
- Makefile integration
- Multi-language support
- Markdown support
- Safe header migration
- Shebang preservation
- Encoding declaration preservation
- PHP opening tag preservation
Before:
print("hello")After:
# app/main.py
print("hello")Markdown example:
<!-- docs/user-guide/overview.md -->
# User GuideRuntime compatibility is Python 3.11+; the standard development and container runtime is Python 3.14.
Choose a version already published in the target project's registry. In an activated virtual environment, replace the placeholders:
python -m pip install --index-url "https://gitlab.com/api/v4/projects/<project-id>/packages/pypi/simple" "path-header-scanner==<package-version>"
path-header-scanner --help
Use a deploy token with read_package_registry. Supply credentials through
pip authentication,
not committed files or shared command history. The package version is PEP 440:
v1.0.0-rc.1 becomes 1.0.0rc1; v1.0.0 becomes 1.0.0.
Use --index-url, not --extra-index-url; review
GitLab package forwarding
if dependencies must stay private.
See installation and registry guidance for authentication, other installation methods, and registry setup.
Create and activate a virtual environment in the source checkout, then run:
python -m pip install -e .
path-header-scanner --helpFor contributor tooling and pre-commit setup, follow the development guide.
Preview is the default. Select the directory you want to scan; only --apply
(or configured apply mode) permits file changes. --dry-run overrides both.
path-header-scanner scan appApply changes:
path-header-scanner scan app --applyDebug mode:
path-header-scanner scan app --debugExplicit dry-run (overrides --apply):
path-header-scanner init --dry-run
path-header-scanner scan app --apply --dry-runFrom the source checkout, build the production image using the project helper:
make d-build-prodThe default image is path-header-scanner-prod:latest. The following mounted
workspace examples use a POSIX shell; see the Docker workflow guide
for the Make and Compose alternatives.
Run scanner:
docker run -it --rm \
-w /workspace \
-v "${PWD}:/workspace" \
path-header-scanner-prod:latest \
scan appApply changes:
docker run -it --rm \
-w /workspace \
-v "${PWD}:/workspace" \
path-header-scanner-prod:latest \
scan app --applyDisplay the grouped command reference:
make help
make help-local
make help-docker
make help-compose
make help-remotePreview or apply a scan:
make l-scan TARGET=src
make l-scan-apply TARGET=srcBuild and validate through Docker Compose:
make c-build-all
make c-checkSee docs/developer-guide/make-workflow.md
for local, Docker, Compose, and published-image workflows.
app/
├── cli/
├── config/
├── constants/
├── core/
├── languages/
├── models/
├── services/
├── templates/
├── ui/
├── utils/
└── __main__.py
See full structure in project_structure.md.
| Language | Extensions |
|---|---|
| Python | .py |
| JavaScript / TypeScript | .js, .jsx, .ts, .tsx |
| Shell | .sh, .bash, .zsh |
| PHP | .php |
| HTML | .html, .htm |
| Markdown | .md, .markdown |
See full documentation in supported_languages.md.
The optional metadata sync script is source-checkout tooling, not an installed application command. Run it from this repository's root:
python scripts/repository/src/sync_metadata.py --dry-runIt reads [project].description and the separate
[tool.devalltect.github].topics / [tool.devalltect.gitlab].topics tables
in pyproject.toml. Package keywords are not repository topics.
Review GITHUB_REMOTES and GITLAB_REMOTES in the script: the current
defaults are origin and backup. Each list contains fallback candidates;
the first valid fetch URL selects one repository per provider. Both providers
must resolve. This helper currently targets GitHub.com and GitLab.com.
Dry-run uses Python and read-only Git discovery; it does not call provider
APIs. Live synchronization additionally needs authenticated gh and glab
with access to update those repositories.
Before removing --dry-run, review the targets and metadata carefully:
the live helper does not ask for confirmation, replaces the topic lists, and
clears existing topics when a list is empty or missing. A failure can leave
earlier updates applied; there is no cross-provider rollback.
Known follow-up: the script's docstring still shows the old path, and its GitHub topic-limit constant is 50 despite GitHub's maximum of 20 topics. Use the path above and keep the GitHub list within 20 until corrected. These issues and isolated test coverage are tracked in the TODO history.
CHANGELOG.md is prepared during the reviewed release process. For current
development milestones, see the TODO tracking history.
See SECURITY.md
See CONTRIBUTING.md
This project is licensed under the MIT License.
See LICENSE
- Paths use POSIX-style separators.
- Docker workflows support mounted workspaces.
- Markdown headers use HTML comments intentionally.
- Existing special lines are preserved safely.
- File updates preserve trailing newlines.