Metadata-Version: 2.4
Name: codestamp
Version: 0.2.0
Summary: CLI tool to manage copyright headers in source-code files
Author: Shardul Kulkarni
License: MIT
Project-URL: Homepage, https://github.com/Medhavee-Inc/codestamp
Project-URL: Issues, https://github.com/Medhavee-Inc/codestamp/issues
Keywords: copyright,license,header,cli,source-code
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Version Control
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: click>=8.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"

# codestamp

> Stamp and manage copyright headers across your source-code files.

[![PyPI](https://img.shields.io/pypi/v/codestamp)](https://pypi.org/project/codestamp/)
[![Python](https://img.shields.io/pypi/pyversions/codestamp)](https://pypi.org/project/codestamp/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

Built by **Medhavee Inc** · Author **Shardul Kulkarni**

---

## Installation

```bash
pip install codestamp
```

Or for local development:

```bash
git clone https://github.com/yourusername/codestamp
cd codestamp
pip install -r requirements-dev.txt
pip install -e .
```

---

## Quick start

1. Create a `license.txt` in your project root whose **first line** is your copyright statement:

```
Copyright (c) 2026 Medhavee Inc. All rights reserved. Proprietary and confidential.
```

2. Run from the project root:

```bash
# Add headers to files changed in the last git commit (CI-friendly default)
codestamp

# Add headers to ALL source files in the tree
codestamp --bulk

# Add headers to staged files only
codestamp --staged

# Skip specific files or directories using an exclusion file
codestamp --bulk --exclude .csignore

# Preview without writing anything
codestamp --bulk --dry-run

# Update every file's copyright to a new statement
codestamp update "Copyright (c) 2026 Medhavee Foundation. All rights reserved."

# See all supported file types
codestamp list-types
```

---

## Commands

| Command | Description |
|---|---|
| `codestamp` | Process files added/modified in the last git commit (default) |
| `codestamp --bulk` | Process all source files in the project tree |
| `codestamp --staged` | Process only currently git-staged files |
| `codestamp --dry-run` | Preview all actions without writing any files |
| `codestamp update "<text>"` | Replace old copyright header with new text everywhere |
| `codestamp list-types` | Show all supported file extensions and comment styles |

### Options

| Flag | Default | Description |
|---|---|---|
| `--license <path>` | `license.txt` | Custom path to your license/copyright file |
| `--exclude <path>` | _(none)_ | Path to an exclusion file (see below) |
| `--dry-run` | off | Preview mode — no files are written |

---

## Excluding files and directories

Pass `--exclude <file>` to point codestamp at a plain-text exclusion list. Each line can be a file path, a directory, a glob pattern, or a comment:

```bash
# .csignore  — paths codestamp should never touch

# Third-party files
vendor/google_utils.py
lib/react_helpers.js

# Entire directories
vendor/
third_party/
node_modules/

# Glob patterns
*.min.js
*.generated.py
```

Then run:

```bash
codestamp --bulk --exclude .csignore
```

Rules supported per line:

| Pattern | Matches |
|---|---|
| `vendor/lib.py` | Exact file path |
| `vendor/` or `vendor` | Any file inside that directory |
| `*.min.js` | Glob matched against the full file path |
| `# comment` | Ignored |
| _(blank line)_ | Ignored |

---

## Output & status codes

Every file processed is reported with a status icon:

| Icon | Status | Meaning |
|---|---|---|
| ✅ | `ADDED` | Copyright header successfully stamped |
| 🔄 | `UPDATED` | Existing header replaced with new text |
| ⏭ | `SKIPPED` | File already has your copyright — left untouched |
| ➖ | `UNSUPPORTED` | File extension not recognised |
| ❌ | `ERROR` | Could not read or write the file |

---

## Supported file types

| Style | Extensions |
|---|---|
| `# comment` | `.py` `.sh` `.bash` `.zsh` `.rb` `.pl` `.r` `.yaml` `.yml` `.toml` `.conf` `.tf` `.tfvars` |
| `// comment` | `.js` `.ts` `.jsx` `.tsx` `.java` `.go` `.swift` `.kt` `.kts` `.rs` `.cs` `.cpp` `.cc` `.c` `.h` `.hpp` `.dart` `.scala` `.groovy` `.php` |
| `/* comment */` | `.css` `.scss` `.less` |
| `<!-- comment -->` | `.html` `.svelte` `.vue` `.xml` `.svg` |

Run `codestamp list-types` to see the full up-to-date list.

---

## How headers are inserted

- **Shebang lines** (`#!/usr/bin/env python3`) are always respected — the header is inserted on line 2, never before the shebang.
- Files that already contain your copyright text are silently **skipped**.
- The `update` command rewrites `license.txt` with the new header text after updating all files.

---

## Git integration

The default mode (no flags) processes files from the **last commit**, making it a perfect fit for CI pipelines:

```yaml
# .github/workflows/copyright.yml
name: Copyright Headers

on: [push]

jobs:
  stamp:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 2       # needed so HEAD~1 diff works

      - name: Install codestamp
        run: pip install codestamp

      - name: Stamp new files
        run: |
          codestamp --exclude .csignore
          git diff --quiet || (
            git config user.email "bot@ci"
            git config user.name "CI Bot"
            git commit -am "chore: add copyright headers"
            git push
          )
```

---

## Contributing

```bash
git clone https://github.com/yourusername/codestamp
cd codestamp
pip install -r requirements-dev.txt
pip install -e .
pytest
```

Pull requests are welcome! Please open an issue first for larger changes.

---

## License

MIT © Shardul Kulkarni / Medhavee Inc
