codestamp 0.1.9__tar.gz → 0.2.0__tar.gz

codestamp-0.2.0/PKG-INFO

@@ -0,0 +1,238 @@
+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

codestamp-0.2.0/README.md

@@ -0,0 +1,210 @@
+# 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

{codestamp-0.1.9 → codestamp-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "codestamp"
-version = "0.1.9"
+version = "0.2.0"
 description = "CLI tool to manage copyright headers in source-code files"
 readme = "README.md"
 license = { text = "MIT" }

{codestamp-0.1.9 → codestamp-0.2.0}/src/codestamp/cli.py

@@ -5,11 +5,12 @@ Manage copyright headers in source-code files.
 
 Usage examples
 --------------
-  codestamp                           # git-diff mode (last commit)
-  codestamp --bulk                    # all source files in tree
-  codestamp --staged                  # only staged files
-  codestamp --dry-run                 # preview, no writes
-  codestamp update "Copyright 2026…"  # update existing headers
+  codestamp                              # git-diff mode (last commit)
+  codestamp --bulk                       # all source files in tree
+  codestamp --staged                     # only staged files
+  codestamp --dry-run                    # preview, no writes
+  codestamp --exclude .csignore          # skip paths listed in a file
+  codestamp update "Copyright 2026…"    # update existing headers
 """
 
 from __future__ import annotations
@@ -41,14 +42,13 @@ _LOGO_LINES = [
     "  ╚═════╝ ╚═════╝ ╚═════╝ ╚══════╝╚══════╝   ╚═╝   ╚═╝  ╚═╝╚═╝     ╚═╝╚═╝      ",
 ]
 
-# Gradient: magenta → blue → cyan → green (top to bottom)
 _LOGO_COLORS = [
-    ("magenta",       True),
-    ("bright_magenta",True),
-    ("bright_blue",   True),
-    ("bright_cyan",   True),
-    ("cyan",          True),
-    ("bright_green",  True),
+    ("magenta",        True),
+    ("bright_magenta", True),
+    ("bright_blue",    True),
+    ("bright_cyan",    True),
+    ("cyan",           True),
+    ("bright_green",   True),
 ]
 
 _DIVIDER = "  " + "─" * 76
@@ -58,23 +58,73 @@ def _print_banner() -> None:
     click.echo()
     for line, (color, bold) in zip(_LOGO_LINES, _LOGO_COLORS):
         click.echo(click.style(line, fg=color, bold=bold))
-
     click.echo()
-
-    # Tagline — each segment in its own accent color
     by_label   = click.style("  ✦  ", fg="bright_yellow", bold=True)
     org        = click.style("Medhavee Inc", fg="bright_yellow", bold=True)
     pipe1      = click.style("   │   ", fg="bright_black")
     auth_label = click.style("author ", fg="bright_black")
     author     = click.style("Shardul Kulkarni", fg="bright_white", bold=True)
     pipe2      = click.style("   │   ", fg="bright_black")
-    version    = click.style("v0.1.0", fg="bright_green")
-
+    version    = click.style("v0.2.0", fg="bright_green")
     click.echo(by_label + org + pipe1 + auth_label + author + pipe2 + version)
     click.echo(click.style(_DIVIDER, fg="bright_black"))
     click.echo()
 
 
+# ---------------------------------------------------------------------------
+# Exclusion list loader
+# ---------------------------------------------------------------------------
+
+def _load_exclusions(exclude_file: str | None) -> set[str]:
+    """
+    Parse an exclusion file and return a set of normalised path strings.
+
+    Each line can be:
+      - a file path   e.g.  vendor/lib.py
+      - a directory   e.g.  third_party/
+      - a glob-style  e.g.  *.min.js        (matched against the full path)
+      - a comment     e.g.  # this is ignored
+      - blank line    (ignored)
+    """
+    if not exclude_file:
+        return set()
+
+    p = Path(exclude_file)
+    if not p.exists():
+        click.echo(click.style(f"  ✖  Exclusion file '{exclude_file}' not found.", fg="bright_red"), err=True)
+        sys.exit(1)
+
+    exclusions: set[str] = set()
+    for raw in p.read_text(encoding="utf-8").splitlines():
+        line = raw.strip()
+        if not line or line.startswith("#"):
+            continue
+        exclusions.add(line.rstrip("/"))   # normalise trailing slash on dirs
+    return exclusions
+
+
+def _is_excluded(filepath: str, exclusions: set[str]) -> bool:
+    """Return True if *filepath* matches any entry in *exclusions*."""
+    if not exclusions:
+        return False
+    p = Path(filepath)
+    for entry in exclusions:
+        entry_path = Path(entry)
+        # Exact file match
+        if p == entry_path:
+            return True
+        # Directory prefix match  (e.g. "vendor" excludes "vendor/foo/bar.py")
+        try:
+            p.relative_to(entry_path)
+            return True
+        except ValueError:
+            pass
+        # Glob match against full path string
+        if p.match(entry):
+            return True
+    return False
+
+
 # ---------------------------------------------------------------------------
 # Helpers
 # ---------------------------------------------------------------------------
@@ -101,12 +151,12 @@ def _collect_all_files(root: str = ".") -> list[str]:
 def _read_license(license_path: str) -> str:
     p = Path(license_path)
     if not p.exists():
-        click.echo(click.style(f"  ✖  '{license_path}' not found.", fg="red", bold=True), err=True)
+        click.echo(click.style(f"  ✖  '{license_path}' not found.", fg="bright_red", bold=True), err=True)
         click.echo(click.style("     Tip: run from the project root, or pass --license <path>", fg="bright_black"), err=True)
         sys.exit(1)
     first = p.read_text(encoding="utf-8").splitlines()[0].strip()
     if not first:
-        click.echo(click.style(f"  ✖  '{license_path}' is empty.", fg="red", bold=True), err=True)
+        click.echo(click.style(f"  ✖  '{license_path}' is empty.", fg="bright_red", bold=True), err=True)
         sys.exit(1)
     return first
 
@@ -136,13 +186,13 @@ def _print_results(results: list[Result]) -> None:
     errors  = sum(1 for r in results if r.status == Status.ERROR)
 
     click.echo()
-    click.echo(click.style("  " + "─" * 50, fg="bright_black"))
+    click.echo(click.style("  " + "─" * 55, fg="bright_black"))
     click.echo(
         "  "
         + click.style(f"✅ {added} added   ", fg="bright_green",  bold=True)
         + click.style(f"🔄 {updated} updated  ", fg="bright_cyan",   bold=True)
         + click.style(f"⏭  {skipped} skipped  ", fg="yellow",       bold=True)
-        + click.style(f"❌ {errors} errors",  fg="bright_red" if errors else "bright_black", bold=bool(errors))
+        + click.style(f"❌ {errors} errors",     fg="bright_red" if errors else "bright_black", bold=bool(errors))
     )
     click.echo()
 
@@ -153,12 +203,15 @@ def _print_results(results: list[Result]) -> None:
 
 @click.group(invoke_without_command=True, context_settings={"help_option_names": ["-h", "--help"]})
 @click.pass_context
-@click.option("--license", "license_path", default="license.txt", show_default=True,
+@click.option("--license",  "license_path",  default="license.txt", show_default=True,
               help="Path to license.txt (first line = copyright text).")
+@click.option("--exclude",  "exclude_file",  default=None,
+              help="Path to a file listing paths/dirs to exclude (one per line).")
 @click.option("--bulk",    is_flag=True, help="Process ALL source files in the current tree.")
 @click.option("--staged",  is_flag=True, help="Process only currently staged git files.")
 @click.option("--dry-run", is_flag=True, help="Preview actions without writing any files.")
-def cli(ctx: click.Context, license_path: str, bulk: bool, staged: bool, dry_run: bool) -> None:
+def cli(ctx: click.Context, license_path: str, exclude_file: str | None,
+        bulk: bool, staged: bool, dry_run: bool) -> None:
     """Stamp copyright headers onto your source-code files.\n
     Default mode: processes files added/modified in the last git commit.
     """
@@ -168,7 +221,11 @@ def cli(ctx: click.Context, license_path: str, bulk: bool, staged: bool, dry_run
         return
 
     copyright_text = _read_license(license_path)
+    exclusions     = _load_exclusions(exclude_file)
+
     _kv("Copyright :", copyright_text, "bright_white")
+    if exclusions:
+        _kv("Excluding :", f"{len(exclusions)} rule(s) from {exclude_file}", "yellow")
 
     if dry_run:
         click.echo(click.style("\n  ⚠  Dry-run mode — no files will be changed.", fg="bright_yellow"))
@@ -191,6 +248,10 @@ def cli(ctx: click.Context, license_path: str, bulk: bool, staged: bool, dry_run
             mode  = "GIT DIFF — files in last commit"
             files = get_last_commit_files()
 
+    # Apply exclusions
+    if exclusions:
+        files = [f for f in files if not _is_excluded(f, exclusions)]
+
     _kv("Mode      :", mode, "bright_cyan")
     _kv("Files     :", str(len(files)), "bright_white")
 
@@ -210,26 +271,34 @@ def cli(ctx: click.Context, license_path: str, bulk: bool, staged: bool, dry_run
 @click.argument("new_header")
 @click.option("--license", "license_path", default="license.txt", show_default=True,
               help="Path to license.txt (first line is the OLD copyright text).")
+@click.option("--exclude", "exclude_file", default=None,
+              help="Path to a file listing paths/dirs to exclude (one per line).")
 @click.option("--dry-run", is_flag=True, help="Preview without writing.")
-def update(new_header: str, license_path: str, dry_run: bool) -> None:
+def update(new_header: str, license_path: str, exclude_file: str | None, dry_run: bool) -> None:
     """Replace existing copyright headers with NEW_HEADER across all source files.
 
     Also rewrites license.txt with the new header (unless --dry-run).
 
     \b
     Example:
-      codestamp update "Copyright (c) 2026 Acme Inc. All rights reserved."
+      codestamp update "Copyright (c) 2026 Medhavee Foundation. All rights reserved."
     """
     old_copyright = _read_license(license_path)
+    exclusions    = _load_exclusions(exclude_file)
 
     _kv("Old :", old_copyright, "bright_black")
     _kv("New :", new_header,    "bright_white")
+    if exclusions:
+        _kv("Excluding :", f"{len(exclusions)} rule(s) from {exclude_file}", "yellow")
 
     if dry_run:
         click.echo(click.style("\n  ⚠  Dry-run mode — no files will be changed.", fg="bright_yellow"))
     click.echo()
 
     files = _collect_all_files()
+    if exclusions:
+        files = [f for f in files if not _is_excluded(f, exclusions)]
+
     if not files:
         click.echo(click.style("  No files found.", fg="yellow"))
         return