specshift 1.2.0__tar.gz → 1.3.0__tar.gz

{specshift-1.2.0/specshift.egg-info → specshift-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: specshift
-Version: 1.2.0
+Version: 1.3.0
 Summary: Detects, classifies, and optionally summarizes breaking changes in OpenAPI/Swagger, GraphQL, and Protobuf/gRPC contracts using AI
 Author: Lethe044
 License: MIT
@@ -8,7 +8,7 @@ Project-URL: Homepage, https://github.com/Lethe044/specshift
 Project-URL: Repository, https://github.com/Lethe044/specshift
 Project-URL: Issues, https://github.com/Lethe044/specshift/issues
 Project-URL: Changelog, https://github.com/Lethe044/specshift/blob/main/CHANGELOG.md
-Keywords: openapi,swagger,graphql,grpc,protobuf,api,breaking-changes,contract-testing,api-diff,devtools,cli,ci-cd,github-actions
+Keywords: openapi,swagger,graphql,grpc,protobuf,api,breaking-changes,contract-testing,api-diff,devtools,cli,ci-cd,github-actions,sarif,changelog
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Environment :: Console
 Classifier: Intended Audience :: Developers
@@ -124,9 +124,14 @@ requirement.
   for comparing specs interactively (drag in files or paste text), with
   zero extra dependencies since it runs entirely on Python's standard
   library and stays on localhost.
-- **Four output formats**: a colored console table, a Markdown report
-  (ideal for PR comments), JSON (for integrating with other tools), and a
-  standalone, filterable HTML report you can open in any browser.
+- **Auto-generated changelog**: `specshift changelog` walks your spec
+  file's history across git tags and produces a single Markdown document
+  summarizing what changed (and whether it was breaking) between every
+  release, plus an "Unreleased" section for the current working tree.
+- **Five output formats**: a colored console table, a Markdown report
+  (ideal for PR comments), JSON (for integrating with other tools), a
+  standalone filterable HTML report, and SARIF 2.1.0 for GitHub Code
+  Scanning.
 
 ## Installation
 
@@ -226,7 +231,7 @@ Useful options:
 
 | Option | Description |
 |---|---|
-| `--format console\|markdown\|json\|html` | Output format (default: console) |
+| `--format console\|markdown\|json\|html\|sarif` | Output format (default: console) |
 | `--output <file>` | Writes the output to a file |
 | `--ai` | Adds a natural-language summary |
 | `--ai-provider groq\|gemini\|openai_compatible` | Chooses the AI provider |
@@ -290,6 +295,21 @@ specshift watch https://api.example.com/openapi.json \
   --slack-webhook "$SLACK_WEBHOOK_URL"
 ```
 
+### `specshift changelog <spec-path>`
+
+Walks the given file's history across git tags and generates a single
+Markdown changelog, diffing each consecutive pair of tagged versions. By
+default it also appends an "Unreleased" section comparing the latest tag
+to the current working tree, if they differ.
+
+```bash
+specshift changelog openapi.yaml --output CHANGELOG-API.md
+```
+
+Options: `--tag-pattern` (glob, default `*`, e.g. `v*` to only consider
+tags starting with `v`), `--no-working-tree` to skip the "Unreleased"
+section, and `--output` to write to a file instead of stdout.
+
 ### `specshift init`
 
 Creates a sample `.specshift.yml` file.
@@ -330,9 +350,32 @@ jobs:
 
 Available inputs: `spec-path`, `base-ref` (defaults to the PR base branch),
 `fail-on` (`breaking` | `warning` | `none`), `ai-summary` (`true`/`false`),
-`ai-provider`, `comment-on-pr` (`true`/`false`), `github-token`, and
-`specshift-version` to pin a specific release. Outputs: `has-breaking-changes`,
-`breaking-count`, `warning-count`, `info-count`, and `report-path`.
+`ai-provider`, `comment-on-pr` (`true`/`false`), `upload-sarif`
+(`true`/`false`, see below), `github-token`, and `specshift-version` to
+pin a specific release. Outputs: `has-breaking-changes`, `breaking-count`,
+`warning-count`, `info-count`, `report-path`, and `sarif-path`.
+
+To also surface results in GitHub's Code Scanning tab, enable
+`upload-sarif` and grant the extra permission it needs:
+
+```yaml
+permissions:
+  pull-requests: write
+  security-events: write
+
+jobs:
+  contract-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: Lethe044/SpecShift@v1
+        with:
+          spec-path: openapi.yaml
+          upload-sarif: 'true'
+```
 
 ### Option 2: calling the CLI directly
 
@@ -418,6 +461,8 @@ judged by wire type category (see the `diff-proto` section above).
 | Natural-language summary | Yes (optional) | No | No |
 | Standalone HTML report | Yes | No | Rarely |
 | Local interactive dashboard | Yes | No | Rarely |
+| Auto-generated changelog across git tags | Yes | No | Rarely |
+| GitHub Code Scanning (SARIF) integration | Yes | No | Rarely |
 | Free to use | Fully free | Free | Usually free |
 | CI integration | Built-in (`check` + official Action) | Manual | Varies |
 | Live URL monitoring | Built-in (`watch`) | No | Rarely |
@@ -429,10 +474,10 @@ This project is under active development. Some planned areas:
 - Path parameter pattern (regex) and discriminator-level rule refinements
 - Deeper GraphQL support: directive-aware deprecation reasons, custom
   scalar compatibility hints, and federation-aware schema composition
-- Protobuf `reserved` statement awareness, so a properly reserved field
-  number isn't flagged the same way as an unreserved removal
 - Optional shared/hosted history for the `serve` dashboard (currently
   in-memory and per-session by design)
+- Changelog generation from raw commit history (not just tags), for
+  repositories that don't tag every release
 
 Feel free to open an issue if you have a feature request.
 

{specshift-1.2.0 → specshift-1.3.0}/README.md

@@ -85,9 +85,14 @@ requirement.
   for comparing specs interactively (drag in files or paste text), with
   zero extra dependencies since it runs entirely on Python's standard
   library and stays on localhost.
-- **Four output formats**: a colored console table, a Markdown report
-  (ideal for PR comments), JSON (for integrating with other tools), and a
-  standalone, filterable HTML report you can open in any browser.
+- **Auto-generated changelog**: `specshift changelog` walks your spec
+  file's history across git tags and produces a single Markdown document
+  summarizing what changed (and whether it was breaking) between every
+  release, plus an "Unreleased" section for the current working tree.
+- **Five output formats**: a colored console table, a Markdown report
+  (ideal for PR comments), JSON (for integrating with other tools), a
+  standalone filterable HTML report, and SARIF 2.1.0 for GitHub Code
+  Scanning.
 
 ## Installation
 
@@ -187,7 +192,7 @@ Useful options:
 
 | Option | Description |
 |---|---|
-| `--format console\|markdown\|json\|html` | Output format (default: console) |
+| `--format console\|markdown\|json\|html\|sarif` | Output format (default: console) |
 | `--output <file>` | Writes the output to a file |
 | `--ai` | Adds a natural-language summary |
 | `--ai-provider groq\|gemini\|openai_compatible` | Chooses the AI provider |
@@ -251,6 +256,21 @@ specshift watch https://api.example.com/openapi.json \
   --slack-webhook "$SLACK_WEBHOOK_URL"
 ```
 
+### `specshift changelog <spec-path>`
+
+Walks the given file's history across git tags and generates a single
+Markdown changelog, diffing each consecutive pair of tagged versions. By
+default it also appends an "Unreleased" section comparing the latest tag
+to the current working tree, if they differ.
+
+```bash
+specshift changelog openapi.yaml --output CHANGELOG-API.md
+```
+
+Options: `--tag-pattern` (glob, default `*`, e.g. `v*` to only consider
+tags starting with `v`), `--no-working-tree` to skip the "Unreleased"
+section, and `--output` to write to a file instead of stdout.
+
 ### `specshift init`
 
 Creates a sample `.specshift.yml` file.
@@ -291,9 +311,32 @@ jobs:
 
 Available inputs: `spec-path`, `base-ref` (defaults to the PR base branch),
 `fail-on` (`breaking` | `warning` | `none`), `ai-summary` (`true`/`false`),
-`ai-provider`, `comment-on-pr` (`true`/`false`), `github-token`, and
-`specshift-version` to pin a specific release. Outputs: `has-breaking-changes`,
-`breaking-count`, `warning-count`, `info-count`, and `report-path`.
+`ai-provider`, `comment-on-pr` (`true`/`false`), `upload-sarif`
+(`true`/`false`, see below), `github-token`, and `specshift-version` to
+pin a specific release. Outputs: `has-breaking-changes`, `breaking-count`,
+`warning-count`, `info-count`, `report-path`, and `sarif-path`.
+
+To also surface results in GitHub's Code Scanning tab, enable
+`upload-sarif` and grant the extra permission it needs:
+
+```yaml
+permissions:
+  pull-requests: write
+  security-events: write
+
+jobs:
+  contract-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: Lethe044/SpecShift@v1
+        with:
+          spec-path: openapi.yaml
+          upload-sarif: 'true'
+```
 
 ### Option 2: calling the CLI directly
 
@@ -379,6 +422,8 @@ judged by wire type category (see the `diff-proto` section above).
 | Natural-language summary | Yes (optional) | No | No |
 | Standalone HTML report | Yes | No | Rarely |
 | Local interactive dashboard | Yes | No | Rarely |
+| Auto-generated changelog across git tags | Yes | No | Rarely |
+| GitHub Code Scanning (SARIF) integration | Yes | No | Rarely |
 | Free to use | Fully free | Free | Usually free |
 | CI integration | Built-in (`check` + official Action) | Manual | Varies |
 | Live URL monitoring | Built-in (`watch`) | No | Rarely |
@@ -390,10 +435,10 @@ This project is under active development. Some planned areas:
 - Path parameter pattern (regex) and discriminator-level rule refinements
 - Deeper GraphQL support: directive-aware deprecation reasons, custom
   scalar compatibility hints, and federation-aware schema composition
-- Protobuf `reserved` statement awareness, so a properly reserved field
-  number isn't flagged the same way as an unreserved removal
 - Optional shared/hosted history for the `serve` dashboard (currently
   in-memory and per-session by design)
+- Changelog generation from raw commit history (not just tags), for
+  repositories that don't tag every release
 
 Feel free to open an issue if you have a feature request.
 

{specshift-1.2.0 → specshift-1.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "specshift"
-version = "1.2.0"
+version = "1.3.0"
 description = "Detects, classifies, and optionally summarizes breaking changes in OpenAPI/Swagger, GraphQL, and Protobuf/gRPC contracts using AI"
 readme = "README.md"
 requires-python = ">=3.9"
@@ -24,6 +24,8 @@ keywords = [
     "cli",
     "ci-cd",
     "github-actions",
+    "sarif",
+    "changelog",
 ]
 classifiers = [
     "Development Status :: 5 - Production/Stable",

{specshift-1.2.0 → specshift-1.3.0}/specshift/__init__.py

@@ -3,18 +3,21 @@ specshift - a CLI tool that detects, classifies, and (optionally)
 summarizes changes in OpenAPI and Swagger contracts using AI.
 """
 
+from specshift.changelog import build_changelog, relevant_tags
 from specshift.differ import diff_specs
 from specshift.graphql_differ import diff_graphql, load_sdl as load_graphql_sdl
 from specshift.models import Change, Severity, ChangeType, DiffResult
 from specshift.protobuf_differ import diff_protos, load_proto
 from specshift.spec_loader import load_spec
 
-__version__ = "1.2.0"
+__version__ = "1.3.0"
 
 __all__ = [
     "diff_specs",
     "diff_graphql",
     "diff_protos",
+    "build_changelog",
+    "relevant_tags",
     "load_spec",
     "load_graphql_sdl",
     "load_proto",

specshift-1.3.0/specshift/changelog.py

@@ -0,0 +1,164 @@
+"""
+Walks a spec file's history across git tags and generates a single
+Markdown changelog document summarizing what changed (and whether it was
+breaking) between each consecutive release.
+
+This turns specshift from a point-in-time diff tool into something that
+can answer "what changed across all our releases", which is a common
+maintenance task most API teams currently do by hand.
+"""
+
+from __future__ import annotations
+
+import fnmatch
+from datetime import datetime, timezone
+from pathlib import Path
+
+from specshift.differ import diff_specs
+from specshift.git_utils import (
+    GitError,
+    current_branch,
+    file_exists_at_ref,
+    list_tags_chronological,
+    read_file_at_ref,
+    tag_date,
+)
+from specshift.graphql_differ import diff_graphql
+from specshift.models import DiffResult
+from specshift.protobuf_differ import diff_protos
+from specshift.spec_loader import SpecLoadError, parse_spec_text
+
+_GRAPHQL_EXTENSIONS = {".graphql", ".gql"}
+_PROTO_EXTENSIONS = {".proto"}
+
+
+class ChangelogError(Exception):
+    """Raised when a changelog cannot be generated."""
+
+
+def _detect_engine(spec_path: str) -> str:
+    suffix = Path(spec_path).suffix.lower()
+    if suffix in _GRAPHQL_EXTENSIONS:
+        return "graphql"
+    if suffix in _PROTO_EXTENSIONS:
+        return "proto"
+    return "openapi"
+
+
+def _diff_by_engine(engine: str, old_text: str, new_text: str) -> DiffResult:
+    if engine == "graphql":
+        return diff_graphql(old_text, new_text)
+    if engine == "proto":
+        return diff_protos(old_text, new_text)
+    old_spec = parse_spec_text(old_text, hint="old")
+    new_spec = parse_spec_text(new_text, hint="new")
+    return diff_specs(old_spec, new_spec)
+
+
+def relevant_tags(spec_path: str, pattern: str = "*", repo_path: str = ".") -> list[str]:
+    """Returns, in chronological order, the tags where the given file exists and matches the pattern."""
+    all_tags = list_tags_chronological(repo_path=repo_path)
+    matching = [tag for tag in all_tags if fnmatch.fnmatch(tag, pattern)]
+    return [tag for tag in matching if file_exists_at_ref(spec_path, tag, repo_path=repo_path)]
+
+
+def build_changelog(
+    spec_path: str,
+    tags: list[str],
+    repo_path: str = ".",
+    include_working_tree: bool = True,
+) -> str:
+    """
+    Builds a single Markdown changelog document by diffing the spec file
+    across each consecutive pair of tags, and optionally a final section
+    comparing the latest tag to the current working tree state.
+    """
+    engine = _detect_engine(spec_path)
+
+    if len(tags) < 1 and not include_working_tree:
+        raise ChangelogError(
+            f"No tags contain '{spec_path}'. Nothing to compare. "
+            "Try a different --tag-pattern, or pass --include-working to compare against the current file."
+        )
+
+    sections: list[str] = []
+    transitions: list[tuple[str, str, str, str]] = []  # (old_label, new_label, old_text, new_text)
+
+    for old_tag, new_tag in zip(tags, tags[1:]):
+        try:
+            old_text = read_file_at_ref(spec_path, old_tag, repo_path=repo_path)
+            new_text = read_file_at_ref(spec_path, new_tag, repo_path=repo_path)
+        except GitError as exc:
+            raise ChangelogError(str(exc)) from exc
+        transitions.append((old_tag, new_tag, old_text, new_text))
+
+    if include_working_tree:
+        current_path = Path(repo_path) / spec_path
+        if current_path.exists():
+            current_text = current_path.read_text(encoding="utf-8")
+            baseline_tag = tags[-1] if tags else None
+            if baseline_tag is not None:
+                try:
+                    baseline_text = read_file_at_ref(spec_path, baseline_tag, repo_path=repo_path)
+                except GitError as exc:
+                    raise ChangelogError(str(exc)) from exc
+                if baseline_text.strip() != current_text.strip():
+                    branch = current_branch(repo_path=repo_path)
+                    transitions.append((baseline_tag, f"Unreleased ({branch})", baseline_text, current_text))
+
+    if not transitions:
+        raise ChangelogError(
+            f"Found no version transitions to compare for '{spec_path}'. "
+            "The file may not have changed across the available tags."
+        )
+
+    generated_at = datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M UTC")
+    header = [
+        f"# API Changelog: {spec_path}",
+        "",
+        f"Generated {generated_at} from {len(transitions)} version transition(s).",
+        "",
+    ]
+
+    for old_label, new_label, old_text, new_text in reversed(transitions):
+        try:
+            result = _diff_by_engine(engine, old_text, new_text)
+        except SpecLoadError as exc:
+            raise ChangelogError(f"Could not parse '{spec_path}' at '{old_label}' or '{new_label}': {exc}") from exc
+
+        sections.append(_render_section(old_label, new_label, result, repo_path=repo_path))
+
+    return "\n".join(header) + "\n" + "\n".join(sections)
+
+
+def _render_section(old_label: str, new_label: str, result: DiffResult, repo_path: str) -> str:
+    counts = result.summary_counts()
+    date_str = tag_date(new_label, repo_path=repo_path) if not new_label.startswith("Unreleased") else ""
+    date_suffix = f" ({date_str})" if date_str else ""
+
+    lines = [f"## {old_label} -> {new_label}{date_suffix}", ""]
+
+    if result.is_empty:
+        lines.append("No changes detected in this file between these versions.")
+        lines.append("")
+        return "\n".join(lines)
+
+    lines.append(
+        f"**{counts['breaking']} breaking, {counts['warning']} warning, {counts['info']} info** change(s)."
+    )
+    lines.append("")
+
+    for severity_label, changes in (
+        ("Breaking", result.breaking_changes),
+        ("Warnings", result.warnings),
+        ("Additions & other changes", result.info_changes),
+    ):
+        if not changes:
+            continue
+        lines.append(f"**{severity_label}:**")
+        lines.append("")
+        for change in changes:
+            lines.append(f"- `{change.location}`: {change.message}")
+        lines.append("")
+
+    return "\n".join(lines)

{specshift-1.2.0 → specshift-1.3.0}/specshift/cli.py

@@ -12,6 +12,7 @@ from typing import Optional
 
 from specshift import __version__
 from specshift.ai_summary import generate_summary
+from specshift.changelog import ChangelogError, build_changelog, relevant_tags
 from specshift.config import SpecShiftConfig, write_default_config
 from specshift.differ import diff_specs
 from specshift.git_utils import GitError, load_spec_from_git
@@ -24,6 +25,7 @@ from specshift.reporter import (
     render_html_report,
     render_json_report,
     render_markdown_report,
+    render_sarif_report,
 )
 from specshift.spec_loader import SpecLoadError, load_spec
 
@@ -73,6 +75,20 @@ def build_parser() -> argparse.ArgumentParser:
     watch_parser.add_argument("--ai", action="store_true", help="Add an AI summary to notifications")
     watch_parser.add_argument("--ai-provider", choices=["groq", "gemini", "openai_compatible"], default=None)
 
+    changelog_parser = subparsers.add_parser(
+        "changelog", help="Generates a Markdown changelog of breaking changes across git tags"
+    )
+    changelog_parser.add_argument("spec", help="Path to the specification file (OpenAPI, GraphQL, or .proto)")
+    changelog_parser.add_argument(
+        "--tag-pattern", default="*", help="Glob pattern to filter tags, e.g. 'v*' (default: all tags)"
+    )
+    changelog_parser.add_argument(
+        "--no-working-tree",
+        action="store_true",
+        help="Don't include an 'Unreleased' section comparing the latest tag to the current file",
+    )
+    changelog_parser.add_argument("--output", default=None, help="Write the changelog to a file instead of stdout")
+
     init_parser = subparsers.add_parser("init", help="Creates a sample .specshift.yml configuration file")
     init_parser.add_argument("--path", default=".specshift.yml", help="Path of the file to create")
     init_parser.add_argument("--force", action="store_true", help="Overwrite an existing file")
@@ -89,7 +105,7 @@ def build_parser() -> argparse.ArgumentParser:
 
 def _add_common_diff_args(parser: argparse.ArgumentParser) -> None:
     parser.add_argument(
-        "--format", choices=["console", "markdown", "json", "html"], default="console", help="Output format"
+        "--format", choices=["console", "markdown", "json", "html", "sarif"], default="console", help="Output format"
     )
     parser.add_argument("--output", help="Write the output to a file (stdout if omitted)")
     parser.add_argument("--ai", action="store_true", help="Generate a natural-language AI summary")
@@ -104,6 +120,11 @@ def _add_common_diff_args(parser: argparse.ArgumentParser) -> None:
         help="Determines at which severity level a non-zero exit code is returned",
     )
     parser.add_argument("--quiet", action="store_true", help="Only print the summary line")
+    parser.add_argument(
+        "--artifact-path",
+        default=None,
+        help="File path recorded in --format sarif output (defaults to the 'new' spec argument, when available)",
+    )
 
 
 def main(argv: Optional[list[str]] = None) -> int:
@@ -121,6 +142,8 @@ def main(argv: Optional[list[str]] = None) -> int:
             return _run_check(args)
         if args.command == "watch":
             return _run_watch(args)
+        if args.command == "changelog":
+            return _run_changelog(args)
         if args.command == "init":
             return _run_init(args)
         if args.command == "serve":
@@ -128,6 +151,9 @@ def main(argv: Optional[list[str]] = None) -> int:
     except (SpecLoadError, GitError, GraphQLLoadError, ProtoLoadError) as exc:
         print(f"Error: {exc}", file=sys.stderr)
         return 2
+    except ChangelogError as exc:
+        print(f"Error: {exc}", file=sys.stderr)
+        return 2
     except KeyboardInterrupt:
         print("\nStopped.")
         return 130
@@ -161,6 +187,7 @@ def _run_check(args: argparse.Namespace) -> int:
     config = SpecShiftConfig.load(args.config)
     spec_path = args.spec or config.spec_path
     base_ref = args.base_ref or config.base_ref
+    args.spec = spec_path  # resolved path, used as the SARIF artifact location if --artifact-path isn't set
 
     old_spec = load_spec_from_git(spec_path, base_ref)
     new_spec = load_spec(spec_path)
@@ -197,6 +224,9 @@ def _emit_result(result: DiffResult, args: argparse.Namespace) -> int:
         output_text = render_markdown_report(result, ai_summary=ai_summary)
     elif args.format == "html":
         output_text = render_html_report(result, ai_summary=ai_summary)
+    elif args.format == "sarif":
+        artifact_path = args.artifact_path or getattr(args, "new", None) or getattr(args, "spec", None) or "specification"
+        output_text = render_sarif_report(result, artifact_path=artifact_path)
     else:
         output_text = None  # console format is printed directly
 
@@ -215,6 +245,8 @@ def _emit_result(result: DiffResult, args: argparse.Namespace) -> int:
         output_path = args.output
         if args.format == "html" and not output_path:
             output_path = "specshift-report.html"
+        if args.format == "sarif" and not output_path:
+            output_path = "specshift-results.sarif"
         if output_path:
             Path(output_path).write_text(output_text, encoding="utf-8")
             print(f"Report written to: {output_path}")
@@ -250,6 +282,23 @@ def _run_serve(args: argparse.Namespace) -> int:
     return 0
 
 
+def _run_changelog(args: argparse.Namespace) -> int:
+    tags = relevant_tags(args.spec, pattern=args.tag_pattern)
+    markdown = build_changelog(
+        args.spec,
+        tags,
+        include_working_tree=not args.no_working_tree,
+    )
+
+    if args.output:
+        Path(args.output).write_text(markdown, encoding="utf-8")
+        print(f"Changelog written to: {args.output}")
+    else:
+        print(markdown)
+
+    return 0
+
+
 def _run_watch(args: argparse.Namespace) -> int:
     CACHE_DIR.mkdir(exist_ok=True)
     cache_key = hashlib.sha256(args.url.encode("utf-8")).hexdigest()[:16]

{specshift-1.2.0 → specshift-1.3.0}/specshift/git_utils.py

@@ -37,22 +37,25 @@ def is_git_repo(path: str = ".") -> bool:
         return False
 
 
-def load_spec_from_git(file_path: str, ref: str, repo_path: str = ".") -> dict:
-    """
-    Reads the content of a file at a given git reference (e.g. 'main',
-    'HEAD~1', a tag, or a commit hash) and parses it as a specification.
-    """
+def _resolve_git_path(file_path: str, repo_path: str = ".") -> str:
+    """Normalizes a file path to be relative to the repository root, as git expects."""
     relative_path = Path(file_path)
     try:
-        # The command may be invoked from outside the repo root, so
-        # normalize the path relative to the repository root.
         toplevel = _run_git(["rev-parse", "--show-toplevel"], cwd=repo_path).strip()
         repo_root = Path(toplevel)
         abs_target = (Path(repo_path).resolve() / relative_path).resolve()
         rel_to_root = abs_target.relative_to(repo_root)
-        git_path = str(rel_to_root).replace("\\", "/")
+        return str(rel_to_root).replace("\\", "/")
     except (GitError, ValueError):
-        git_path = str(relative_path).replace("\\", "/")
+        return str(relative_path).replace("\\", "/")
+
+
+def load_spec_from_git(file_path: str, ref: str, repo_path: str = ".") -> dict:
+    """
+    Reads the content of a file at a given git reference (e.g. 'main',
+    'HEAD~1', a tag, or a commit hash) and parses it as a specification.
+    """
+    git_path = _resolve_git_path(file_path, repo_path)
 
     try:
         content = _run_git(["show", f"{ref}:{git_path}"], cwd=repo_path)
@@ -68,6 +71,57 @@ def load_spec_from_git(file_path: str, ref: str, repo_path: str = ".") -> dict:
         raise GitError(str(exc)) from exc
 
 
+def read_file_at_ref(file_path: str, ref: str, repo_path: str = ".") -> str:
+    """Reads the raw text content of a file at a given git reference, without parsing it."""
+    git_path = _resolve_git_path(file_path, repo_path)
+    try:
+        return _run_git(["show", f"{ref}:{git_path}"], cwd=repo_path)
+    except GitError as exc:
+        raise GitError(
+            f"Could not read '{ref}:{git_path}'. Make sure the file path and reference are correct. "
+            f"Details: {exc}"
+        ) from exc
+
+
+def file_exists_at_ref(file_path: str, ref: str, repo_path: str = ".") -> bool:
+    """Returns True if the given file exists at the given git reference."""
+    git_path = _resolve_git_path(file_path, repo_path)
+    try:
+        _run_git(["cat-file", "-e", f"{ref}:{git_path}"], cwd=repo_path)
+        return True
+    except GitError:
+        return False
+
+
+def list_tags_chronological(repo_path: str = ".") -> list[str]:
+    """
+    Returns all git tags in chronological (creation) order, oldest first.
+    Uses for-each-ref rather than 'git tag --sort', which behaves more
+    consistently across both lightweight and annotated tags.
+    """
+    try:
+        output = _run_git(
+            ["for-each-ref", "--sort=creatordate", "--format=%(refname:short)", "refs/tags"],
+            cwd=repo_path,
+        )
+    except GitError:
+        return []
+
+    return [line.strip() for line in output.splitlines() if line.strip()]
+
+
+def tag_date(tag: str, repo_path: str = ".") -> str:
+    """Returns the ISO creation date of a tag, or an empty string if unavailable."""
+    try:
+        output = _run_git(
+            ["for-each-ref", "--format=%(creatordate:short)", f"refs/tags/{tag}"],
+            cwd=repo_path,
+        )
+        return output.strip()
+    except GitError:
+        return ""
+
+
 def current_branch(repo_path: str = ".") -> str:
     try:
         return _run_git(["rev-parse", "--abbrev-ref", "HEAD"], cwd=repo_path).strip()