specshift 1.2.0__tar.gz → 1.4.0__tar.gz

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

@@ -1,14 +1,14 @@
 Metadata-Version: 2.4
 Name: specshift
-Version: 1.2.0
-Summary: Detects, classifies, and optionally summarizes breaking changes in OpenAPI/Swagger, GraphQL, and Protobuf/gRPC contracts using AI
+Version: 1.4.0
+Summary: Detects, classifies, and optionally summarizes breaking changes and best-practice issues in OpenAPI/Swagger, GraphQL, and Protobuf/gRPC contracts using AI
 Author: Lethe044
 License: MIT
 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,api-linter,devtools,cli,ci-cd,github-actions,sarif,changelog
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Environment :: Console
 Classifier: Intended Audience :: Developers
@@ -124,9 +124,19 @@ 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.
+- **Spec linting**: `specshift lint` reviews a single OpenAPI document for
+  spec-validity problems (undeclared path parameters, missing response
+  descriptions, undefined security schemes, duplicate operationIds) and
+  best-practice gaps (missing summaries, missing error responses,
+  inconsistent path naming, unused schemas), independent of any diff.
+- **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 +236,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 +300,47 @@ 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 lint <spec>`
+
+Reviews a single OpenAPI/Swagger document for spec-validity problems and
+best-practice gaps, independent of comparing it to any other version.
+Supports the same `--format`, `--output`, `--ai`, `--fail-on`, and
+`--artifact-path` options as `diff`.
+
+```bash
+specshift lint openapi.yaml
+```
+
+```
+Bookstore API : 1.0.0
+2 breaking, 3 warning, 1 info issues found.
+
+[BREAKING] GET /books/{bookId} :: Path template parameter '{bookId}' is used in the path but not declared as a path parameter for this operation.
+[BREAKING] GET /books/{bookId} > response 200 :: Response has no description. The OpenAPI spec requires every response to have one.
+[WARNING] POST /books :: Operation has no operationId; many code generators rely on this to name functions.
+...
+
+Result: 2 issue(s) should be fixed for spec validity.
+```
+
+See [When SpecShift calls something breaking](#when-specshift-calls-something-breaking)
+below for what each severity means in lint results specifically.
+
 ### `specshift init`
 
 Creates a sample `.specshift.yml` file.
@@ -330,9 +381,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
 
@@ -408,6 +482,16 @@ than request/response direction: adding fields or rpc methods is always
 safe, changing a field's number is always breaking, and type changes are
 judged by wire type category (see the `diff-proto` section above).
 
+`specshift lint` follows a different model too, since it reviews one
+document rather than comparing two: **breaking** means the document
+violates something the OpenAPI spec itself requires (undeclared path
+parameters, a response with no description, an undefined security
+scheme), which can cause strict tooling or code generators to reject the
+document outright; **warning** means a common best-practice gap (missing
+summaries, missing operationIds, undocumented error responses,
+inconsistent naming); **info** means a minor, low-priority suggestion
+(an apparently unused schema).
+
 ## Comparison with other tools
 
 | | SpecShift | Raw JSON/YAML diff | oasdiff / openapi-diff style tools |
@@ -415,9 +499,12 @@ judged by wire type category (see the `diff-proto` section above).
 | Context-aware classification | Yes | No | Partially |
 | GraphQL support | Yes | No | Rarely |
 | Protobuf/gRPC support (wire-aware) | Yes | No | Rarely |
+| Single-document linting (not just diffing) | Yes | No | Rarely |
 | 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 +516,11 @@ 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
+- Extending `specshift lint` to GraphQL and Protobuf schemas
 - 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.4.0}/README.md

@@ -85,9 +85,19 @@ 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.
+- **Spec linting**: `specshift lint` reviews a single OpenAPI document for
+  spec-validity problems (undeclared path parameters, missing response
+  descriptions, undefined security schemes, duplicate operationIds) and
+  best-practice gaps (missing summaries, missing error responses,
+  inconsistent path naming, unused schemas), independent of any diff.
+- **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 +197,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 +261,47 @@ 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 lint <spec>`
+
+Reviews a single OpenAPI/Swagger document for spec-validity problems and
+best-practice gaps, independent of comparing it to any other version.
+Supports the same `--format`, `--output`, `--ai`, `--fail-on`, and
+`--artifact-path` options as `diff`.
+
+```bash
+specshift lint openapi.yaml
+```
+
+```
+Bookstore API : 1.0.0
+2 breaking, 3 warning, 1 info issues found.
+
+[BREAKING] GET /books/{bookId} :: Path template parameter '{bookId}' is used in the path but not declared as a path parameter for this operation.
+[BREAKING] GET /books/{bookId} > response 200 :: Response has no description. The OpenAPI spec requires every response to have one.
+[WARNING] POST /books :: Operation has no operationId; many code generators rely on this to name functions.
+...
+
+Result: 2 issue(s) should be fixed for spec validity.
+```
+
+See [When SpecShift calls something breaking](#when-specshift-calls-something-breaking)
+below for what each severity means in lint results specifically.
+
 ### `specshift init`
 
 Creates a sample `.specshift.yml` file.
@@ -291,9 +342,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
 
@@ -369,6 +443,16 @@ than request/response direction: adding fields or rpc methods is always
 safe, changing a field's number is always breaking, and type changes are
 judged by wire type category (see the `diff-proto` section above).
 
+`specshift lint` follows a different model too, since it reviews one
+document rather than comparing two: **breaking** means the document
+violates something the OpenAPI spec itself requires (undeclared path
+parameters, a response with no description, an undefined security
+scheme), which can cause strict tooling or code generators to reject the
+document outright; **warning** means a common best-practice gap (missing
+summaries, missing operationIds, undocumented error responses,
+inconsistent naming); **info** means a minor, low-priority suggestion
+(an apparently unused schema).
+
 ## Comparison with other tools
 
 | | SpecShift | Raw JSON/YAML diff | oasdiff / openapi-diff style tools |
@@ -376,9 +460,12 @@ judged by wire type category (see the `diff-proto` section above).
 | Context-aware classification | Yes | No | Partially |
 | GraphQL support | Yes | No | Rarely |
 | Protobuf/gRPC support (wire-aware) | Yes | No | Rarely |
+| Single-document linting (not just diffing) | Yes | No | Rarely |
 | 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 +477,11 @@ 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
+- Extending `specshift lint` to GraphQL and Protobuf schemas
 - 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.4.0}/pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "specshift"
-version = "1.2.0"
-description = "Detects, classifies, and optionally summarizes breaking changes in OpenAPI/Swagger, GraphQL, and Protobuf/gRPC contracts using AI"
+version = "1.4.0"
+description = "Detects, classifies, and optionally summarizes breaking changes and best-practice issues in OpenAPI/Swagger, GraphQL, and Protobuf/gRPC contracts using AI"
 readme = "README.md"
 requires-python = ">=3.9"
 license = { text = "MIT" }
@@ -20,10 +20,13 @@ keywords = [
     "breaking-changes",
     "contract-testing",
     "api-diff",
+    "api-linter",
     "devtools",
     "cli",
     "ci-cd",
     "github-actions",
+    "sarif",
+    "changelog",
 ]
 classifiers = [
     "Development Status :: 5 - Production/Stable",

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

@@ -3,18 +3,23 @@ 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.linter import lint_spec
 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.4.0"
 
 __all__ = [
     "diff_specs",
     "diff_graphql",
     "diff_protos",
+    "lint_spec",
+    "build_changelog",
+    "relevant_tags",
     "load_spec",
     "load_graphql_sdl",
     "load_proto",

{specshift-1.2.0 → specshift-1.4.0}/specshift/ai_summary.py

@@ -36,13 +36,18 @@ def generate_summary(
     provider: Optional[str] = None,
     model: Optional[str] = None,
     timeout: int = 30,
+    context: str = "diff",
 ) -> str:
     """
     Returns a natural-language summary using a configured AI provider when
     possible, otherwise falls back to a rule-based summary. Never raises an
     exception that would halt execution; failures fall back silently.
+
+    context is either "diff" (comparing two versions, the default) or
+    "lint" (findings about a single specification), and selects which
+    prompt and fallback wording is used.
     """
-    prompt = _build_prompt(result)
+    prompt = _build_prompt(result, context=context)
 
     chosen_provider = provider or _detect_provider()
 
@@ -64,7 +69,7 @@ def generate_summary(
         except AISummaryError:
             pass
 
-    return build_template_summary(result)
+    return build_template_summary(result, context=context)
 
 
 def _detect_provider() -> Optional[str]:
@@ -77,19 +82,40 @@ def _detect_provider() -> Optional[str]:
     return None
 
 
-def _build_prompt(result: DiffResult) -> str:
+def _build_prompt(result: DiffResult, context: str = "diff") -> str:
     counts = result.summary_counts()
+
+    if context == "lint":
+        intro = (
+            "Below is a list of issues found while linting a single OpenAPI "
+            "specification for correctness and best practices. This is NOT a "
+            "comparison between two versions, it is a quality review of one "
+            "document. Read this list and write a short, clear, professional "
+            "summary in English that a developer maintaining this API would "
+            "understand. First highlight any spec-validity issues (things that "
+            "could break tooling or fail parsing), then best-practice gaps, "
+            "then minor style suggestions. Do not use lists or headings, write "
+            "in flowing paragraphs. Do not invent information, base the "
+            "summary only on the findings given.",
+        )
+        total_label = "issues"
+    else:
+        intro = (
+            "Below is a list of contract changes detected between two versions "
+            "of an API. Read this list and write a short, clear, professional "
+            "summary in English that a developer consuming this API would "
+            "understand. First highlight the most important breaking changes, "
+            "then anything worth paying attention to, and finally briefly "
+            "mention minor additions. Do not use lists or headings, write in "
+            "flowing paragraphs. Do not invent information, base the summary "
+            "only on the changes given.",
+        )
+        total_label = "changes"
+
     lines = [
-        "Below is a list of contract changes detected between two versions "
-        "of an API. Read this list and write a short, clear, professional "
-        "summary in English that a developer consuming this API would "
-        "understand. First highlight the most important breaking changes, "
-        "then anything worth paying attention to, and finally briefly "
-        "mention minor additions. Do not use lists or headings, write in "
-        "flowing paragraphs. Do not invent information, base the summary "
-        "only on the changes given.",
+        intro[0],
         "",
-        f"Total: {counts['breaking']} breaking, {counts['warning']} warning, {counts['info']} informational changes.",
+        f"Total: {counts['breaking']} breaking, {counts['warning']} warning, {counts['info']} informational {total_label}.",
         "",
     ]
     for change in result.sorted_changes()[:60]:
@@ -160,8 +186,14 @@ def _call_openai_compatible(prompt: str, model: Optional[str], timeout: int) ->
         raise AISummaryError(f"Custom endpoint request failed: {exc}") from exc
 
 
-def build_template_summary(result: DiffResult) -> str:
+def build_template_summary(result: DiffResult, context: str = "diff") -> str:
     """A deterministic, rule-based summary that works without any API key."""
+    if context == "lint":
+        return _build_lint_template_summary(result)
+    return _build_diff_template_summary(result)
+
+
+def _build_diff_template_summary(result: DiffResult) -> str:
     counts = result.summary_counts()
 
     if result.is_empty:
@@ -199,3 +231,38 @@ def build_template_summary(result: DiffResult) -> str:
         )
 
     return " ".join(parts)
+
+
+def _build_lint_template_summary(result: DiffResult) -> str:
+    counts = result.summary_counts()
+
+    if result.is_empty:
+        return "No issues were found; this specification looks clean."
+
+    parts: list[str] = []
+
+    if counts["breaking"] > 0:
+        top_issues = result.breaking_changes[:5]
+        issue_desc = "; ".join(f"{c.location} ({c.message.rstrip('.')})" for c in top_issues)
+        extra = counts["breaking"] - len(top_issues)
+        extra_note = f" and {extra} more" if extra > 0 else ""
+        parts.append(
+            f"This specification has {counts['breaking']} spec-validity issue(s) that should be "
+            f"fixed first, since they can break tooling or code generation. Notably: {issue_desc}{extra_note}."
+        )
+    else:
+        parts.append("This specification has no spec-validity issues.")
+
+    if counts["warning"] > 0:
+        parts.append(
+            f"There are {counts['warning']} best-practice recommendation(s), such as missing "
+            "descriptions, operation IDs, or documented error responses, that would improve the "
+            "developer experience for anyone consuming this API."
+        )
+
+    if counts["info"] > 0:
+        parts.append(
+            f"The remaining {counts['info']} finding(s) are minor style or cleanup suggestions."
+        )
+
+    return " ".join(parts)