Metadata-Version: 2.4
Name: autoheader
Version: 10.0.0
Summary: Enterprise-grade file header tool that injects repo-relative path headers into Python files
Author-email: dhruv13x <dhruv13x@gmail.com>
License: MIT © dhruv13x
Project-URL: Homepage, https://github.com/dhruv13x/autoheader
Project-URL: Source, https://github.com/dhruv13x/autoheader
Project-URL: Issues, https://github.com/dhruv13x/autoheader/issues
Keywords: headers,cli,utilities,tooling,automation,python-files
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Environment :: Console
Classifier: Topic :: Software Development :: Documentation
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: tomli; python_version < "3.11"
Requires-Dist: rich>=13.0.0
Requires-Dist: rich-argparse>=1.0.0
Provides-Extra: lsp
Requires-Dist: pygls>=2.0.0; extra == "lsp"
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0.0; extra == "dev"
Requires-Dist: pytest-timeout>=2.2.0; extra == "dev"
Requires-Dist: pytest-json-report>=1.5.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
Requires-Dist: pytest-mock>=3.10.0; extra == "dev"
Requires-Dist: pyfakefs>=5.0.0; extra == "dev"
Requires-Dist: ruff>=0.6.0; extra == "dev"
Requires-Dist: black>=24.3.0; extra == "dev"
Requires-Dist: mypy>=1.11.0; extra == "dev"
Requires-Dist: PyYAML>=6.0; extra == "dev"
Requires-Dist: types-PyYAML>=6.0; extra == "dev"
Provides-Extra: precommit
Requires-Dist: pyyaml>=6.0; extra == "precommit"

<div align="center">
  <img src="https://raw.githubusercontent.com/dhruv13x/autoheader/main/autoheader_logo.png" alt="autoheader logo" width="200"/>
</div>

<div align="center">

<!-- Package Info -->
[![PyPI version](https://img.shields.io/pypi/v/autoheader.svg)](https://pypi.org/project/autoheader/)
[![Python](https://img.shields.io/badge/python-3.8%2B-blue.svg)](https://www.python.org/)
![Wheel](https://img.shields.io/pypi/wheel/autoheader.svg)
[![Release](https://img.shields.io/badge/release-PyPI-blue)](https://pypi.org/project/autoheader/)

<!-- Build & Quality -->
[![Build status](https://github.com/dhruv13x/autoheader/actions/workflows/publish.yml/badge.svg)](https://github.com/dhruv13x/autoheader/actions/workflows/publish.yml)
[![Codecov](https://codecov.io/gh/dhruv13x/autoheader/graph/badge.svg)](https://codecov.io/gh/dhruv13x/autoheader)
[![Test Coverage](https://img.shields.io/badge/coverage-90%25%2B-brightgreen.svg)](https://github.com/dhruv13x/autoheader/actions/workflows/test.yml)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
[![Ruff](https://img.shields.io/badge/linting-ruff-yellow.svg)](https://github.com/astral-sh/ruff)
![Security](https://img.shields.io/badge/security-CodeQL-blue.svg)

<!-- Usage -->
![Downloads](https://img.shields.io/pypi/dm/autoheader.svg)
![OS](https://img.shields.io/badge/os-Linux%20%7C%20macOS%20%7C%20Windows-blue.svg)
![Languages](https://img.shields.io/badge/languages-Python%20%7C%20JavaScript%20%7C%20TypeScript-green.svg)
[![Python Versions](https://img.shields.io/pypi/pyversions/autoheader.svg)](https://pypi.org/project/autoheader/)

<!-- License -->
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

</div>

# 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:

```bash
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):

```bash
# 1. Initialize a default config
autoheader --init

# 2. Preview changes (Safe by default)
autoheader
```

Apply the changes:

```bash
autoheader --no-dry-run
```

**What it does:**
It transforms this:
```python
import os
def main(): pass
```
Into this:
```python
# 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`.

```toml
[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.

```python
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:
```python
# autoheader: ignore
```

---

## 🏗️ Architecture

`autoheader` follows a strict Separation of Concerns.

```text
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
