specshift 1.3.0__tar.gz → 1.4.0__tar.gz

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

@@ -1,14 +1,14 @@
 Metadata-Version: 2.4
 Name: specshift
-Version: 1.3.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,sarif,changelog
+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
@@ -128,6 +128,11 @@ requirement.
   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
@@ -310,6 +315,32 @@ 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.
@@ -451,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 |
@@ -458,6 +499,7 @@ 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 |
@@ -474,6 +516,7 @@ 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
+- 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

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

@@ -89,6 +89,11 @@ requirement.
   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
@@ -271,6 +276,32 @@ 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.
@@ -412,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 |
@@ -419,6 +460,7 @@ 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 |
@@ -435,6 +477,7 @@ 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
+- 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

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

@@ -4,8 +4,8 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "specshift"
-version = "1.3.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,6 +20,7 @@ keywords = [
     "breaking-changes",
     "contract-testing",
     "api-diff",
+    "api-linter",
     "devtools",
     "cli",
     "ci-cd",

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

@@ -6,16 +6,18 @@ 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.3.0"
+__version__ = "1.4.0"
 
 __all__ = [
     "diff_specs",
     "diff_graphql",
     "diff_protos",
+    "lint_spec",
     "build_changelog",
     "relevant_tags",
     "load_spec",

{specshift-1.3.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)

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

@@ -17,6 +17,7 @@ from specshift.config import SpecShiftConfig, write_default_config
 from specshift.differ import diff_specs
 from specshift.git_utils import GitError, load_spec_from_git
 from specshift.graphql_differ import GraphQLLoadError, diff_graphql, load_sdl
+from specshift.linter import lint_spec
 from specshift.models import DiffResult
 from specshift.notifier import NotifyError, notify_discord, notify_slack
 from specshift.protobuf_differ import ProtoLoadError, diff_protos, load_proto
@@ -35,7 +36,8 @@ CACHE_DIR = Path(".specshift_cache")
 def build_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(
         prog="specshift",
-        description="Detects and classifies changes in OpenAPI/Swagger, GraphQL, and Protobuf/gRPC contracts.",
+        description="Detects and classifies changes in OpenAPI/Swagger, GraphQL, and Protobuf/gRPC contracts, "
+        "and lints a single OpenAPI specification for best practices.",
     )
     parser.add_argument("--version", action="version", version=f"specshift {__version__}")
 
@@ -56,6 +58,12 @@ def build_parser() -> argparse.ArgumentParser:
     proto_parser.add_argument("new", help="New .proto schema: file path or URL")
     _add_common_diff_args(proto_parser)
 
+    lint_parser = subparsers.add_parser(
+        "lint", help="Checks a single OpenAPI/Swagger specification for validity and best-practice issues"
+    )
+    lint_parser.add_argument("spec", help="Specification to lint: file path or URL")
+    _add_common_diff_args(lint_parser)
+
     check_parser = subparsers.add_parser(
         "check", help="For CI: compares the current specification against a git reference"
     )
@@ -138,6 +146,8 @@ def main(argv: Optional[list[str]] = None) -> int:
             return _run_diff_graphql(args)
         if args.command == "diff-proto":
             return _run_diff_proto(args)
+        if args.command == "lint":
+            return _run_lint(args)
         if args.command == "check":
             return _run_check(args)
         if args.command == "watch":
@@ -183,6 +193,12 @@ def _run_diff_proto(args: argparse.Namespace) -> int:
     return _emit_result(result, args)
 
 
+def _run_lint(args: argparse.Namespace) -> int:
+    spec = load_spec(args.spec)
+    result = lint_spec(spec)
+    return _emit_result(result, args, context="lint")
+
+
 def _run_check(args: argparse.Namespace) -> int:
     config = SpecShiftConfig.load(args.config)
     spec_path = args.spec or config.spec_path
@@ -212,18 +228,18 @@ def _run_check(args: argparse.Namespace) -> int:
     return exit_code
 
 
-def _emit_result(result: DiffResult, args: argparse.Namespace) -> int:
+def _emit_result(result: DiffResult, args: argparse.Namespace, context: str = "diff") -> int:
     ai_summary = None
     if args.ai:
-        ai_summary = generate_summary(result, provider=args.ai_provider, model=args.ai_model)
+        ai_summary = generate_summary(result, provider=args.ai_provider, model=args.ai_model, context=context)
 
     output_text: str
     if args.format == "json":
         output_text = render_json_report(result, ai_summary=ai_summary)
     elif args.format == "markdown":
-        output_text = render_markdown_report(result, ai_summary=ai_summary)
+        output_text = render_markdown_report(result, ai_summary=ai_summary, context=context)
     elif args.format == "html":
-        output_text = render_html_report(result, ai_summary=ai_summary)
+        output_text = render_html_report(result, ai_summary=ai_summary, context=context)
     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)
@@ -234,11 +250,11 @@ def _emit_result(result: DiffResult, args: argparse.Namespace) -> int:
         if args.output:
             from specshift.reporter import render_plain_text_report
 
-            Path(args.output).write_text(render_plain_text_report(result), encoding="utf-8")
+            Path(args.output).write_text(render_plain_text_report(result, context=context), encoding="utf-8")
             if not args.quiet:
                 print(f"Report written to: {args.output}")
         else:
-            print_console_report(result, verbose=not args.quiet)
+            print_console_report(result, verbose=not args.quiet, context=context)
             if ai_summary:
                 print(f"\nAI Summary:\n{ai_summary}")
     else: