verscan 0.1.0__py3-none-any.whl

verscan/__init__.py

@@ -0,0 +1 @@
+"""verscan — verify package.json / CHANGELOG.md / git tag versions match."""

verscan/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+main()

verscan/cli.py

@@ -0,0 +1,246 @@
+"""verscan CLI — verify package.json / CHANGELOG.md / git tag versions match."""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+from typing import Dict, Optional, Tuple
+
+from . import core
+
+VERSION = "0.1.0"
+
+HELP = """\
+verscan — verify package.json / CHANGELOG.md / git tag all share the same version.
+
+Usage:
+  verscan [options] [dir]
+
+Options:
+  --no-git            skip git tag check
+  --no-changelog      skip CHANGELOG.md check
+  --manifest <file>   manifest path (default: auto-detect package.json or pyproject.toml)
+  --changelog <file>  changelog path (default: CHANGELOG.md)
+  --json              output JSON
+  --version, -v       print verscan version
+  --help, -h          show this help
+
+Exit codes: 0 all match  1 mismatch  2 error
+"""
+
+_USE_COLOR = sys.stdout.isatty() and os.environ.get("NO_COLOR") is None
+
+
+def _col(code: str, s: str) -> str:
+    return f"\x1b[{code}m{s}\x1b[0m" if _USE_COLOR else s
+
+
+def _green(s: str) -> str: return _col("32", s)
+def _red(s: str) -> str: return _col("31", s)
+def _yellow(s: str) -> str: return _col("33", s)
+def _dim(s: str) -> str: return _col("2", s)
+def _bold(s: str) -> str: return _col("1", s)
+def _cyan(s: str) -> str: return _col("36", s)
+
+
+def _die(msg: str, code: int = 2) -> None:
+    sys.stderr.write(_red(f"verscan: {msg}\n"))
+    sys.exit(code)
+
+
+def _try_read(path: Path) -> Optional[str]:
+    try:
+        return path.read_text(encoding="utf-8")
+    except OSError:
+        return None
+
+
+def _resolve_manifest(
+    directory: Path, explicit: Optional[str]
+) -> Tuple[str, Path, str]:
+    """Returns (type, path, content) where type is 'package' or 'pyproject'."""
+    if explicit:
+        p = (directory / explicit).resolve()
+        content = _try_read(p)
+        if content is None:
+            _die(f"manifest not found: {p}")
+        base = p.name
+        if base == "pyproject.toml":
+            return "pyproject", p, content  # type: ignore[return-value]
+        if base == "package.json":
+            return "package", p, content  # type: ignore[return-value]
+        _die(f"unrecognised manifest type: {base} (use package.json or pyproject.toml)")
+
+    pkg = directory / "package.json"
+    pyproj = directory / "pyproject.toml"
+    pkg_content = _try_read(pkg)
+    if pkg_content:
+        return "package", pkg, pkg_content
+    py_content = _try_read(pyproj)
+    if py_content:
+        return "pyproject", pyproj, py_content
+    _die(f"no package.json or pyproject.toml found in {directory}")
+    raise SystemExit(2)  # unreachable, satisfies type checker
+
+
+def _read_manifest_version(mtype: str, content: str) -> str:
+    if mtype == "package":
+        return core.read_pkg_version(content)
+    return core.read_pyproject_version(content)
+
+
+def _read_git_tag(directory: Path) -> str:
+    try:
+        result = subprocess.run(
+            ["git", "describe", "--tags", "--abbrev=0"],
+            cwd=str(directory),
+            capture_output=True,
+            text=True,
+            timeout=5,
+        )
+        if result.returncode != 0:
+            msg = result.stderr.strip()
+            if "no names found" in msg or "no tag" in msg or result.returncode == 128:
+                raise ValueError(
+                    "no git tags found in this repository (create one with `git tag v0.1.0`)"
+                )
+            raise ValueError(f"git describe failed: {msg}")
+        return core.parse_git_tag(result.stdout)
+    except FileNotFoundError:
+        raise ValueError("git executable not found")
+
+
+def _label(mtype: str) -> str:
+    return {"package": "package.json", "pyproject": "pyproject.toml"}.get(mtype, mtype)
+
+
+def main() -> None:
+    argv = sys.argv[1:]
+
+    if not argv or "--help" in argv or "-h" in argv:
+        sys.stdout.write(HELP)
+        sys.exit(0)
+    if "--version" in argv or "-v" in argv:
+        sys.stdout.write(VERSION + "\n")
+        sys.exit(0)
+
+    skip_git = "--no-git" in argv
+    skip_changelog = "--no-changelog" in argv
+    json_mode = "--json" in argv
+
+    def _flag_val(name: str) -> Optional[str]:
+        try:
+            i = argv.index(name)
+            return argv[i + 1]
+        except (ValueError, IndexError):
+            return None
+
+    manifest_flag = _flag_val("--manifest")
+    changelog_flag = _flag_val("--changelog")
+
+    flag_names = {"--manifest", "--changelog"}
+    consumed = set()
+    for i, a in enumerate(argv):
+        if a in flag_names:
+            consumed.add(i + 1)
+    positional = [
+        a for i, a in enumerate(argv)
+        if not a.startswith("-") and i not in consumed
+    ]
+    directory = Path(positional[0]).resolve() if positional else Path.cwd()
+
+    errors: Dict[str, str] = {}
+    versions: Dict[str, Optional[str]] = {}
+
+    # 1. Manifest version
+    mtype, mpath, mcontent = _resolve_manifest(directory, manifest_flag)  # exits on error
+    try:
+        versions[mtype] = _read_manifest_version(mtype, mcontent)
+    except ValueError as exc:
+        errors[mtype] = str(exc)
+
+    # 2. CHANGELOG version
+    if not skip_changelog:
+        cl_path = (directory / (changelog_flag or "CHANGELOG.md")).resolve()
+        cl_content = _try_read(cl_path)
+        if cl_content is None:
+            errors["changelog"] = f"CHANGELOG.md not found at {cl_path} (use --no-changelog to skip)"
+        else:
+            try:
+                versions["changelog"] = core.read_changelog_version(cl_content)
+            except ValueError as exc:
+                errors["changelog"] = str(exc)
+
+    # 3. Git tag version
+    if not skip_git:
+        try:
+            versions["git"] = _read_git_tag(directory)
+        except ValueError as exc:
+            errors["git"] = str(exc)
+
+    has_errors = bool(errors)
+    result = core.compare_versions(versions)
+
+    if json_mode:
+        out = {
+            "ok": result["ok"] and not has_errors,
+            "versions": {k: v for k, v in versions.items() if v is not None},
+            "errors": errors,
+            "mismatches": result["mismatches"],
+        }
+        sys.stdout.write(json.dumps(out, indent=2) + "\n")
+        sys.exit(0 if result["ok"] and not has_errors else (2 if has_errors else 1))
+
+    src_label = {
+        "package": _label(mtype),
+        "pyproject": _label(mtype),
+        "changelog": "CHANGELOG.md",
+        "git": "git tag",
+    }
+    all_keys = list(versions.keys()) + list(errors.keys())
+    max_len = max((len(src_label.get(k, k)) for k in all_keys), default=0)
+
+    def _pad(s: str) -> str:
+        return s.ljust(max_len)
+
+    sys.stdout.write("\n")
+
+    for idx, (src, ver) in enumerate(result["entries"]):
+        marker = _dim("  (reference)") if idx == 0 else ""
+        sys.stdout.write(
+            f"  {_green('✓')} {_bold(_pad(src_label.get(src, src)))}  {_cyan(ver)}{marker}\n"
+        )
+    for src, err in errors.items():
+        sys.stdout.write(
+            f"  {_yellow('!')} {_bold(_pad(src_label.get(src, src)))}  {_yellow(f'[{err}]')}\n"
+        )
+
+    if not result["ok"] and not has_errors:
+        sys.stdout.write("\n")
+        for src in result["mismatches"]:
+            ver = versions.get(src, "?")
+            sys.stdout.write(
+                f"  {_red('✗')} {_bold(src_label.get(src, src))} "
+                f"is {_red(str(ver))} — expected {_cyan(str(result['reference']))}\n"
+            )
+
+    sys.stdout.write("\n")
+
+    if has_errors:
+        sys.stderr.write(_red(f"verscan: {len(errors)} source(s) could not be read\n"))
+        sys.exit(2)
+
+    if not result["ok"]:
+        sys.stderr.write(
+            _red(
+                f"verscan: version mismatch — "
+                f"{', '.join(result['mismatches'])} differ from {result['reference']}\n"
+            )
+        )
+        sys.exit(1)
+
+    sys.stdout.write(_green(f"verscan: all sources match → {_cyan(str(result['reference']))}\n"))
+    sys.exit(0)

verscan/core.py

@@ -0,0 +1,110 @@
+"""
+verscan core — pure parsing and comparison logic. No I/O, no subprocess.
+
+Each function takes raw string content so it is trivially testable.
+Version numbers always use millisecond-epoch timestamps for state files
+when sharing state with the Node.js counterpart (verscan).
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from typing import Dict, List, Optional, Tuple
+
+
+def read_pkg_version(content: str) -> str:
+    """Extract ``version`` from a package.json string."""
+    try:
+        pkg = json.loads(content)
+    except json.JSONDecodeError as exc:
+        raise ValueError(f"invalid JSON in package.json: {exc}") from exc
+    version = pkg.get("version")
+    if not isinstance(version, str) or not version:
+        raise ValueError('no "version" field in package.json')
+    return version.strip()
+
+
+def read_pyproject_version(content: str) -> str:
+    """Extract version from a pyproject.toml string via regex.
+
+    Matches ``version = "x.y.z"`` (or single-quoted) inside the ``[project]``
+    section without importing tomllib (which requires Python ≥ 3.11).
+    """
+    m = re.search(
+        r'^\[project\][^[]*?\bversion\s*=\s*["\']([^"\'\\r\\n]+)["\']',
+        content,
+        re.MULTILINE | re.DOTALL,
+    )
+    if not m:
+        raise ValueError("no version in [project] section of pyproject.toml")
+    return m.group(1).strip()
+
+
+def read_changelog_version(content: str) -> str:
+    """Extract the first version heading from CHANGELOG.md content.
+
+    Understands Keep-a-Changelog ``## [1.2.3]`` and bare forms
+    ``## 1.2.3``, ``## v1.2.3``, ``## [v1.2.3]``.
+    Returns the bare semver (v-prefix and brackets stripped).
+    """
+    m = re.search(
+        r'^##\s+\[?v?(\d+\.\d+(?:\.\d+)?(?:[-+][^\]\s]*)?)(\])?(?:\s|$)',
+        content,
+        re.MULTILINE,
+    )
+    if not m:
+        raise ValueError(
+            "no version heading found in CHANGELOG.md "
+            "(expected `## [x.y.z]` or `## x.y.z`)"
+        )
+    return m.group(1).strip()
+
+
+def parse_git_tag(output: str) -> str:
+    """Strip leading ``v`` and whitespace from ``git describe`` output."""
+    tag = output.strip()
+    if not tag:
+        raise ValueError("no git tags found in this repository")
+    return tag.lstrip("v")
+
+
+def normalize_version(v: str) -> str:
+    """Strip leading ``v`` and whitespace."""
+    return str(v).strip().lstrip("v")
+
+
+def compare_versions(
+    versions: Dict[str, Optional[str]],
+) -> Dict:
+    """Compare a dict of named version strings.
+
+    Returns::
+
+        {
+            "ok": bool,
+            "reference": str | None,
+            "mismatches": [str, ...],
+            "entries": [(name, version), ...],
+        }
+
+    Null/None values are skipped.
+    """
+    entries: List[Tuple[str, str]] = [
+        (k, v) for k, v in versions.items() if v is not None
+    ]
+    if len(entries) < 2:
+        return {
+            "ok": True,
+            "reference": entries[0][1] if entries else None,
+            "mismatches": [],
+            "entries": entries,
+        }
+    ref = entries[0][1]
+    mismatches = [k for k, v in entries if v != ref]
+    return {
+        "ok": len(mismatches) == 0,
+        "reference": ref,
+        "mismatches": mismatches,
+        "entries": entries,
+    }

verscan-0.1.0.dist-info/METADATA

@@ -0,0 +1,84 @@
+Metadata-Version: 2.4
+Name: verscan
+Version: 0.1.0
+Summary: Zero-dependency CLI to verify package.json, CHANGELOG.md, and git tag all share the same version — catch release mistakes before they ship.
+Author: yyfjj
+License: MIT
+Project-URL: Homepage, https://github.com/jjdoor/verscan-py
+Project-URL: Repository, https://github.com/jjdoor/verscan-py
+Project-URL: Issues, https://github.com/jjdoor/verscan-py/issues
+Keywords: version,release,changelog,git,semver,cli,devops,ci,lint,check
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Version Control :: Git
+Classifier: Topic :: Utilities
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# verscan
+
+Zero-dependency CLI to verify that `package.json` (or `pyproject.toml`), `CHANGELOG.md`, and your latest git tag all agree on the same version number — before you ship.
+
+```
+$ verscan
+
+  ✓ pyproject.toml  0.3.1  (reference)
+  ✓ CHANGELOG.md    0.3.1
+  ✓ git tag         0.3.1
+
+verscan: all sources match → 0.3.1
+```
+
+## Install
+
+```bash
+pip install verscan
+```
+
+No dependencies. Python ≥ 3.8 required.
+
+## Usage
+
+```bash
+verscan [options] [dir]
+```
+
+| Option | Description |
+|--------|-------------|
+| `--no-git` | Skip git tag check |
+| `--no-changelog` | Skip CHANGELOG.md check |
+| `--manifest <file>` | Custom manifest path (default: auto-detect) |
+| `--changelog <file>` | Custom changelog path (default: `CHANGELOG.md`) |
+| `--json` | Output JSON |
+| `--version` | Print verscan version |
+| `--help` | Show help |
+
+**Exit codes:** `0` all match · `1` mismatch · `2` parse/read error
+
+## Examples
+
+```bash
+verscan                      # check current directory
+verscan --no-git             # skip git tag (before tagging)
+verscan ./packages/api       # check a sub-package
+verscan --json | python3 -c "import sys,json; d=json.load(sys.stdin); sys.exit(0 if d['ok'] else 1)"
+```
+
+## CI integration
+
+```yaml
+- name: Verify versions aligned
+  run: pip install verscan && verscan
+```
+
+For the Node.js CLI counterpart, see [verscan](https://github.com/jjdoor/verscan).
+
+## License
+
+MIT

verscan-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+verscan/__init__.py,sha256=odbbKlfPDmA_4t2RLsxJl_Uk7mjWkClBecNZdD-jQC0,79
+verscan/__main__.py,sha256=bYt9eEaoRQWdejEHFD8REx9jxVEdZptECFsV7F49Ink,30
+verscan/cli.py,sha256=5Suj2vn2sPmLojr5-OQwbqTObsiP0tXufPU4dWmNXMc,7860
+verscan/core.py,sha256=TZwY2eNc6-MZ3nmh-GUINbNsPpYxM-igqdjaBF9MMB4,3242
+verscan-0.1.0.dist-info/licenses/LICENSE,sha256=fgx5TFKqwm0KYEWedI7KffCOvMfWFqoPSuXZ_-RyoiI,1080
+verscan-0.1.0.dist-info/METADATA,sha256=e1T5P7NuMLE_WlVaBWJmFyIsQzZhZrQs_jYEJWAia5A,2374
+verscan-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+verscan-0.1.0.dist-info/entry_points.txt,sha256=M8DNihWzaS5OQ2Q6qjQiz3ZbiYaygne4dTesMd6xZL8,45
+verscan-0.1.0.dist-info/top_level.txt,sha256=mqBeND8owR27qE97cTTOsMdtaO85iLfIGSqc8mV5RTk,8
+verscan-0.1.0.dist-info/RECORD,,

verscan-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

verscan-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+verscan = verscan.cli:main

verscan-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 cron-watch contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

verscan-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+verscan