autoheader 10.0.0

Enterprise-grade file header tool that injects repo-relative path headers into Python files

autoheader

The enterprise-grade standard for adding, refreshing, and managing repo-relative file headers.

autoheader automatically manages file headers containing repo-relative paths for source code projects. Whether you are working in a massive monorepo or a small microservice, it ensures every file is traceable, standardizing your codebase and improving developer navigation.

"Where is this file located?" — Never ask this again.

---

🚀 Quick Start

Prerequisites

• Python 3.8+
• Basic understanding of your project structure (e.g., where pyproject.toml or .git lives).

Installation

Install instantly via pip:

pip install "autoheader[precommit]"

Note: The [precommit] extra is recommended for full feature support (like hook installation).

Usage Example

Scan your project and verify what needs to change (Dry Run):

# 1. Initialize a default config
autoheader --init

# 2. Preview changes (Safe by default)
autoheader

Apply the changes:

autoheader --no-dry-run

What it does: It transforms this:

import os
def main(): pass

Into this:

# src/utils/main.py

import os
def main(): pass

---

✨ Key Features

• 🌐 Polyglot Support: God Level. Manages headers for Python, JavaScript, Go, CSS, and any other language via a simple TOML configuration.
• 🛡️ Pre-commit Integration: God Level. Automatically enforce headers on every commit with autoheader --check or the built-in hook installer.
• ⚙️ Smart Setup: God Level. Get started in seconds with autoheader --init to generate a battle-tested default configuration.
• 🧩 LSP Support: God Level. Includes a Language Server (autoheader --lsp) for real-time diagnostics directly in your IDE.
• ⚡ Rich UX: Beautiful, modern output with emojis, progress bars, and visual diffs (powered by Rich).
• 🧠 Smart Copyright: Automatically updates year ranges (e.g., 2020-2025) in existing headers instead of overwriting them.
• 🚀 Performance: Supports passing specific files, parallel execution, and caching for blazing fast speed in CI pipelines.
• 📂 Team Configuration: Centralize settings using autoheader.toml or a remote config URL (--config-url) to keep your team aligned.
• 💻 Official SDK: Import autoheader in your own Python scripts (from autoheader import AutoHeader) for custom integrations.
• 🤖 GitHub Action: Use the official action uses: dhruv13x/autoheader@v1 to check headers in your CI/CD pipelines.
• 🤖 Auto-Installer: Setup hooks instantly with autoheader --install-precommit or autoheader --install-git-hook.
• 🔍 SARIF Support: Output results in SARIF format (--format sarif) for integration with GitHub Security and other scanning tools.
• 📜 Native SPDX Support: Easily use standard licenses (e.g., MIT, Apache-2.0) by setting license_spdx in your config.
• Smart Filtering: .gitignore aware, inline ignores (autoheader: ignore), and robust depth/exclusion controls.

---

⚙️ Configuration & Advanced Usage

1. The autoheader.toml File

The primary way to configure autoheader is via the autoheader.toml file. Generate one with autoheader --init.

[general]
workers = 8
backup = false
exclude = ["tests/fixtures/*"]

[language.python]
file_globs = ["*.py"]
prefix = "# "
template = "# {path}\n#\n{license}"
license_spdx = "MIT"

2. CLI Arguments

All configuration can be overridden via CLI arguments.

Argument	Description	Default
Main Actions
files	Specific files to process (space separated). Scans root if empty.	(all)
-d, --dry-run	Preview changes without writing.	True
-nd, --no-dry-run	Apply changes to disk.	False
--override	Force rewrite of existing headers.	False
--remove	Remove all autoheader lines from files.	False
CI / Integration
--check	Exit 1 if changes needed.	False
--check-hash	Verify content integrity.	False
--install-precommit	Install pre-commit hook.	False
--install-git-hook	Install native .git/hooks.	False
--init	Generate default config.	False
--lsp	Start Language Server.	False
Configuration
--config-url	Remote config URL.	None
--root	Project root path.	cwd
--workers	Parallel workers.	8
--timeout	File processing timeout (s).	60.0
--clear-cache	Reset internal cache.	False
Filtering
--depth	Max directory scan depth.	None
--exclude	Glob patterns to skip.	[]
--markers	Project root markers.	['.gitignore', ...]
Header Customization
--blank-lines-after	Blank lines after header.	1
Output
--format	default or sarif.	default
-v, --verbose	Increase verbosity.	0
-q, --quiet	Suppress info output.	False
--no-color	Disable colors.	False
--no-emoji	Disable emojis.	False

3. Python SDK

You can use autoheader directly in your Python scripts.

from autoheader import AutoHeader

ah = AutoHeader(root=".")

# Apply headers to all files
results = ah.apply(dry_run=False)

# Check compliance
check_results = ah.check(["src/main.py"])

4. Environment Variables

While autoheader primarily uses autoheader.toml, standard environment variables like NO_COLOR=1 are respected.

5. Inline Ignores

To skip a specific file without complex config, simply add this comment anywhere in the file:

# autoheader: ignore

---

🏗️ Architecture

autoheader follows a strict Separation of Concerns.

src/autoheader/
├── cli.py         # Entry Point: UI, args parsing, mode selection
├── api.py         # The SDK: Official public API wrapper
├── core.py        # Execution: File writing, diffing, safety checks
├── planner.py     # The Brain: Pure business logic, decision making (PlanItem)
├── config.py      # Config: TOML loading, merging, validation
├── walker.py      # Discovery: File scanning, gitignore processing
├── headerlogic.py # Parsing: Header detection, SPDX handling
├── ui.py          # The Face: Rich output, visual diffs
├── lsp.py         # Language Server: Real-time IDE integration
└── hooks.py       # Integration: Native git hook installer

Core Flow:

1. Initialize: cli.py determines project root.
2. Configuration: config.py loads local/remote TOML.
3. Discovery: walker.py scans files, filtering by exclude and .gitignore.
4. Planning: planner.py analyzes files in parallel to create a PlanItem (Add, Override, Skip).
5. Execution: core.py executes the plan using a ThreadPoolExecutor, updating files safely.

---

🗺️ Roadmap

We are actively building the future of code standardization.

• ✅ v9.0: Native LSP Support, Pre-commit auto-installer, Rich CLI, Official SDK, GitHub Action.
• ✅ v10.0 (Pre-release): Native Git Hook Installer, SARIF reporting, Remote Configuration.

Check ROADMAP.md for the full list of future goals like Semantic License Analysis.

---

🤝 Contributing & License

Contributions are welcome!

1. Fork the repository.
2. Clone: git clone ...
3. Install dev deps: pip install -e ".[dev,precommit]"
4. Run tests: pytest

License: MIT © dhruv13x