Add -v/--version flag, derived from the git tag

.github/workflows/release.yml

@@ -34,6 +34,8 @@ jobs:
         run: echo "TAG=${TAG_INPUT}" >> "$GITHUB_ENV"
 
       - name: Build artifact (frontend bundle + single-file)
+        env:
+          REPO_INTEL_VERSION: ${{ env.TAG }} # bakes the tag into the released binary
         run: make build
 
       - name: Create release and attach the single-file artifact
@@ -57,7 +59,14 @@ jobs:
           curl -fsSL "https://github.com/${GITHUB_REPOSITORY}/releases/download/${TAG}/repo-intel" -o /tmp/repo-intel
           chmod +x /tmp/repo-intel
           /tmp/repo-intel --help >/dev/null
-          echo "Published artifact runs."
+          # The published binary must report the tag's version (no leading v).
+          got="$(/tmp/repo-intel --version)"
+          want="repo-intel ${TAG#v}"
+          if [ "$got" != "$want" ]; then
+            echo "::error::version mismatch — got '$got', expected '$want'"
+            exit 1
+          fi
+          echo "Published artifact runs and reports ${got}."
 
       - name: Update the floating major tag (e.g. v1)
         if: ${{ !contains(inputs.tag || github.ref_name, '-') }} # skip prereleases like v1.0.0-rc1

README.md

@@ -137,7 +137,8 @@ repo-intel [N] [REPO] [options]
 - `REPO` — `owner/repo`, `https://github.com/owner/repo`, or
   `remote:owner/repo`. Omit to use the cwd's git repo.
 
-Run `repo-intel --help` for the full flag reference.
+Run `repo-intel --help` for the full flag reference, or `repo-intel --version`
+(`-v`) to print the version.
 
 ### Modes
 

build.py

@@ -13,6 +13,7 @@
 
 TEMPLATE_PLACEHOLDER = 'TEMPLATE = "__TEMPLATE_PLACEHOLDER__"'
 TECHDATA_PLACEHOLDER = 'TECHDATA = "__TECHDATA_PLACEHOLDER__"'
+VERSION_PLACEHOLDER = 'VERSION = "0.0.0-dev"'
 
 
 def main():
@@ -51,6 +52,19 @@ def main():
     bundled = script.replace(TEMPLATE_PLACEHOLDER, f"TEMPLATE = {template!r}").replace(
         TECHDATA_PLACEHOLDER, f"TECHDATA = {techdata!r}"
     )
+
+    # Bake the version only when given one (release builds pass the tag via
+    # $REPO_INTEL_VERSION). Without it the sentinel is left untouched, so the
+    # committed dist/repo-intel rebuilds byte-for-byte — CI gates that.
+    version = os.environ.get("REPO_INTEL_VERSION", "").strip().lstrip("v")
+    if version:
+        if bundled.count(VERSION_PLACEHOLDER) != 1:
+            sys.exit(
+                f"error: expected exactly one version sentinel ({VERSION_PLACEHOLDER!r}) "
+                "in repo-intel.py"
+            )
+        bundled = bundled.replace(VERSION_PLACEHOLDER, f"VERSION = {version!r}")
+
     out_path.parent.mkdir(parents=True, exist_ok=True)
     out_path.write_text(bundled, encoding="utf-8")
     out_path.chmod(0o755)

dist/repo-intel

@@ -1,12 +1,21 @@
 #!/usr/bin/env python3
 """repo-intel — generate a contributor stats dashboard for a git repo."""
 
+# The git tag is the single source of truth for the version. build.py bakes the
+# tag into the released artifact (from $REPO_INTEL_VERSION); a raw source
+# checkout falls back to `git describe` against this file's own directory (see
+# resolve_version). The committed dist/repo-intel keeps this "0.0.0-dev"
+# sentinel so `make build` stays byte-for-byte reproducible — CI gates that —
+# while the released asset carries the real version.
+VERSION = "0.0.0-dev"
+
 HELP = """\
 repo-intel — generate a contributor stats dashboard for a git repo.
 
 Usage:
   repo-intel [N] [REPO] [-o PATH] [--format LIST] [--no-open] [--clone]
   repo-intel -h | --help
+  repo-intel -v | --version
 
 Arguments:
   N       Number of top contributors to include (default: 10)
@@ -35,6 +44,7 @@ Options:
   --since DATE        Only include commits on or after DATE (YYYY-MM-DD, inclusive).
   --until DATE        Only include commits on or before DATE (YYYY-MM-DD, inclusive).
   -h, --help          Show this help message and exit.
+  -v, --version       Show the version and exit.
 
 Examples:
   repo-intel                       # local repo (cwd), top 10
@@ -194,10 +204,32 @@ def parse_formats(val, acc):
     return acc
 
 
+def resolve_version():
+    # Released builds carry the tag baked in by build.py. A raw source checkout
+    # has the sentinel, so derive from the git tag (the source of truth) using
+    # this file's own directory — cwd is the repo being analysed, not ours.
+    if VERSION != "0.0.0-dev":
+        return VERSION
+    try:
+        out = subprocess.run(
+            ["git", "describe", "--tags", "--always", "--dirty"],
+            cwd=Path(__file__).resolve().parent,
+            capture_output=True,
+            text=True,
+            check=True,
+        ).stdout.strip()
+        return out or VERSION
+    except (OSError, subprocess.CalledProcessError):
+        return VERSION
+
+
 def parse_args(argv):
     if any(tok in ("-h", "--help") for tok in argv):
         sys.stdout.write(HELP)
         sys.exit(0)
+    if any(tok in ("-v", "--version") for tok in argv):
+        sys.stdout.write(f"repo-intel {resolve_version()}\n")
+        sys.exit(0)
     top_n, remote, output, no_open, no_cache = 10, None, None, False, False
     clone = False
     commits_filter, since, until = None, None, None

repo-intel.py

@@ -1,12 +1,21 @@
 #!/usr/bin/env python3
 """repo-intel — generate a contributor stats dashboard for a git repo."""
 
+# The git tag is the single source of truth for the version. build.py bakes the
+# tag into the released artifact (from $REPO_INTEL_VERSION); a raw source
+# checkout falls back to `git describe` against this file's own directory (see
+# resolve_version). The committed dist/repo-intel keeps this "0.0.0-dev"
+# sentinel so `make build` stays byte-for-byte reproducible — CI gates that —
+# while the released asset carries the real version.
+VERSION = "0.0.0-dev"
+
 HELP = """\
 repo-intel — generate a contributor stats dashboard for a git repo.
 
 Usage:
   repo-intel [N] [REPO] [-o PATH] [--format LIST] [--no-open] [--clone]
   repo-intel -h | --help
+  repo-intel -v | --version
 
 Arguments:
   N       Number of top contributors to include (default: 10)
@@ -35,6 +44,7 @@
   --since DATE        Only include commits on or after DATE (YYYY-MM-DD, inclusive).
   --until DATE        Only include commits on or before DATE (YYYY-MM-DD, inclusive).
   -h, --help          Show this help message and exit.
+  -v, --version       Show the version and exit.
 
 Examples:
   repo-intel                       # local repo (cwd), top 10
@@ -194,10 +204,32 @@ def parse_formats(val, acc):
     return acc
 
 
+def resolve_version():
+    # Released builds carry the tag baked in by build.py. A raw source checkout
+    # has the sentinel, so derive from the git tag (the source of truth) using
+    # this file's own directory — cwd is the repo being analysed, not ours.
+    if VERSION != "0.0.0-dev":
+        return VERSION
+    try:
+        out = subprocess.run(
+            ["git", "describe", "--tags", "--always", "--dirty"],
+            cwd=Path(__file__).resolve().parent,
+            capture_output=True,
+            text=True,
+            check=True,
+        ).stdout.strip()
+        return out or VERSION
+    except (OSError, subprocess.CalledProcessError):
+        return VERSION
+
+
 def parse_args(argv):
     if any(tok in ("-h", "--help") for tok in argv):
         sys.stdout.write(HELP)
         sys.exit(0)
+    if any(tok in ("-v", "--version") for tok in argv):
+        sys.stdout.write(f"repo-intel {resolve_version()}\n")
+        sys.exit(0)
     top_n, remote, output, no_open, no_cache = 10, None, None, False, False
     clone = False
     commits_filter, since, until = None, None, None