specshift 1.1.0__tar.gz → 1.2.0__tar.gz

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

@@ -1,14 +1,14 @@
 Metadata-Version: 2.4
 Name: specshift
-Version: 1.1.0
-Summary: Detects, classifies, and optionally summarizes breaking changes in OpenAPI/Swagger and GraphQL contracts using AI
+Version: 1.2.0
+Summary: Detects, classifies, and optionally summarizes breaking changes 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,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
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Environment :: Console
 Classifier: Intended Audience :: Developers
@@ -96,6 +96,10 @@ requirement.
 - **GraphQL support**: diff GraphQL SDL schemas with `specshift diff-graphql`,
   covering types, fields, arguments, enum values, interfaces, unions, and
   deprecations, no external GraphQL library required.
+- **Protobuf/gRPC support**: diff `.proto` files with `specshift diff-proto`,
+  using protobuf's own documented wire-compatibility rules (field numbers,
+  wire type categories, zigzag encoding) rather than generic JSON-shape
+  heuristics, so severity reflects what will actually break on the wire.
 - **Context-aware classification**: the same change is weighted
   differently depending on whether it occurs in a request or a response
   (or, for GraphQL, an input type versus an object type).
@@ -116,6 +120,10 @@ requirement.
 - **Live monitoring**: the `specshift watch` command periodically checks
   a remote API's specification and sends a Slack or Discord notification
   when it changes.
+- **Local web dashboard**: `specshift serve` opens a browser-based tool
+  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.
@@ -235,6 +243,33 @@ an http(s) URL, or raw SDL text. Supports the same `--format`, `--output`,
 specshift diff-graphql old_schema.graphql new_schema.graphql
 ```
 
+### `specshift diff-proto <old> <new>`
+
+Compares two Protobuf/gRPC `.proto` schemas using protobuf's own
+wire-compatibility rules (field numbers, wire type categories) rather
+than generic JSON-shape heuristics. Supports the same `--format`,
+`--output`, `--ai`, and `--fail-on` options as `diff`.
+
+```bash
+specshift diff-proto old_service.proto new_service.proto
+```
+
+### `specshift serve`
+
+Starts a local, dependency-free web dashboard for comparing specs
+interactively. Opens a browser tab where you can drag in or paste two
+files (OpenAPI, GraphQL, or Protobuf, auto-detected), and view the same
+styled HTML report the CLI produces, with a short history of past
+comparisons in the current session.
+
+```bash
+specshift serve
+# or: specshift serve --port 9000 --no-browser
+```
+
+Everything runs in-process on your machine; nothing is uploaded anywhere,
+and the server binds to `127.0.0.1` by default.
+
 ### `specshift check`
 
 Designed for CI/CD. Compares the current specification file against a git
@@ -368,14 +403,21 @@ common scenarios:
 The same table applies to GraphQL: `input` types behave like requests,
 `type`/`interface` fields behave like responses.
 
+Protobuf/gRPC follows a different model, based on the wire format rather
+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).
+
 ## Comparison with other tools
 
 | | SpecShift | Raw JSON/YAML diff | oasdiff / openapi-diff style tools |
 |---|---|---|---|
 | Context-aware classification | Yes | No | Partially |
 | GraphQL support | Yes | No | Rarely |
+| Protobuf/gRPC support (wire-aware) | Yes | No | Rarely |
 | Natural-language summary | Yes (optional) | No | No |
 | Standalone HTML report | Yes | No | Rarely |
+| Local interactive dashboard | 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 |
@@ -384,11 +426,13 @@ The same table applies to GraphQL: `input` types behave like requests,
 
 This project is under active development. Some planned areas:
 
-- Support for gRPC/Protobuf contracts
 - Path parameter pattern (regex) and discriminator-level rule refinements
-- A hosted, shareable web viewer (beyond the offline HTML report)
 - 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)
 
 Feel free to open an issue if you have a feature request.
 

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

@@ -57,6 +57,10 @@ requirement.
 - **GraphQL support**: diff GraphQL SDL schemas with `specshift diff-graphql`,
   covering types, fields, arguments, enum values, interfaces, unions, and
   deprecations, no external GraphQL library required.
+- **Protobuf/gRPC support**: diff `.proto` files with `specshift diff-proto`,
+  using protobuf's own documented wire-compatibility rules (field numbers,
+  wire type categories, zigzag encoding) rather than generic JSON-shape
+  heuristics, so severity reflects what will actually break on the wire.
 - **Context-aware classification**: the same change is weighted
   differently depending on whether it occurs in a request or a response
   (or, for GraphQL, an input type versus an object type).
@@ -77,6 +81,10 @@ requirement.
 - **Live monitoring**: the `specshift watch` command periodically checks
   a remote API's specification and sends a Slack or Discord notification
   when it changes.
+- **Local web dashboard**: `specshift serve` opens a browser-based tool
+  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.
@@ -196,6 +204,33 @@ an http(s) URL, or raw SDL text. Supports the same `--format`, `--output`,
 specshift diff-graphql old_schema.graphql new_schema.graphql
 ```
 
+### `specshift diff-proto <old> <new>`
+
+Compares two Protobuf/gRPC `.proto` schemas using protobuf's own
+wire-compatibility rules (field numbers, wire type categories) rather
+than generic JSON-shape heuristics. Supports the same `--format`,
+`--output`, `--ai`, and `--fail-on` options as `diff`.
+
+```bash
+specshift diff-proto old_service.proto new_service.proto
+```
+
+### `specshift serve`
+
+Starts a local, dependency-free web dashboard for comparing specs
+interactively. Opens a browser tab where you can drag in or paste two
+files (OpenAPI, GraphQL, or Protobuf, auto-detected), and view the same
+styled HTML report the CLI produces, with a short history of past
+comparisons in the current session.
+
+```bash
+specshift serve
+# or: specshift serve --port 9000 --no-browser
+```
+
+Everything runs in-process on your machine; nothing is uploaded anywhere,
+and the server binds to `127.0.0.1` by default.
+
 ### `specshift check`
 
 Designed for CI/CD. Compares the current specification file against a git
@@ -329,14 +364,21 @@ common scenarios:
 The same table applies to GraphQL: `input` types behave like requests,
 `type`/`interface` fields behave like responses.
 
+Protobuf/gRPC follows a different model, based on the wire format rather
+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).
+
 ## Comparison with other tools
 
 | | SpecShift | Raw JSON/YAML diff | oasdiff / openapi-diff style tools |
 |---|---|---|---|
 | Context-aware classification | Yes | No | Partially |
 | GraphQL support | Yes | No | Rarely |
+| Protobuf/gRPC support (wire-aware) | Yes | No | Rarely |
 | Natural-language summary | Yes (optional) | No | No |
 | Standalone HTML report | Yes | No | Rarely |
+| Local interactive dashboard | 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 |
@@ -345,11 +387,13 @@ The same table applies to GraphQL: `input` types behave like requests,
 
 This project is under active development. Some planned areas:
 
-- Support for gRPC/Protobuf contracts
 - Path parameter pattern (regex) and discriminator-level rule refinements
-- A hosted, shareable web viewer (beyond the offline HTML report)
 - 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)
 
 Feel free to open an issue if you have a feature request.
 

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

@@ -4,8 +4,8 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "specshift"
-version = "1.1.0"
-description = "Detects, classifies, and optionally summarizes breaking changes in OpenAPI/Swagger and GraphQL contracts using AI"
+version = "1.2.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"
 license = { text = "MIT" }
@@ -14,6 +14,8 @@ keywords = [
     "openapi",
     "swagger",
     "graphql",
+    "grpc",
+    "protobuf",
     "api",
     "breaking-changes",
     "contract-testing",

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

@@ -6,15 +6,18 @@ summarizes changes in OpenAPI and Swagger contracts using AI.
 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.1.0"
+__version__ = "1.2.0"
 
 __all__ = [
     "diff_specs",
     "diff_graphql",
+    "diff_protos",
     "load_spec",
     "load_graphql_sdl",
+    "load_proto",
     "Change",
     "Severity",
     "ChangeType",

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

@@ -18,6 +18,7 @@ from specshift.git_utils import GitError, load_spec_from_git
 from specshift.graphql_differ import GraphQLLoadError, diff_graphql, load_sdl
 from specshift.models import DiffResult
 from specshift.notifier import NotifyError, notify_discord, notify_slack
+from specshift.protobuf_differ import ProtoLoadError, diff_protos, load_proto
 from specshift.reporter import (
     print_console_report,
     render_html_report,
@@ -32,7 +33,7 @@ CACHE_DIR = Path(".specshift_cache")
 def build_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(
         prog="specshift",
-        description="Detects and classifies changes in OpenAPI/Swagger and GraphQL contracts.",
+        description="Detects and classifies changes in OpenAPI/Swagger, GraphQL, and Protobuf/gRPC contracts.",
     )
     parser.add_argument("--version", action="version", version=f"specshift {__version__}")
 
@@ -48,6 +49,11 @@ def build_parser() -> argparse.ArgumentParser:
     graphql_parser.add_argument("new", help="New GraphQL schema: file path or URL")
     _add_common_diff_args(graphql_parser)
 
+    proto_parser = subparsers.add_parser("diff-proto", help="Compare two Protobuf/gRPC .proto schemas")
+    proto_parser.add_argument("old", help="Old .proto schema: file path or URL")
+    proto_parser.add_argument("new", help="New .proto schema: file path or URL")
+    _add_common_diff_args(proto_parser)
+
     check_parser = subparsers.add_parser(
         "check", help="For CI: compares the current specification against a git reference"
     )
@@ -71,6 +77,13 @@ def build_parser() -> argparse.ArgumentParser:
     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")
 
+    serve_parser = subparsers.add_parser(
+        "serve", help="Starts a local web dashboard for comparing specs interactively in the browser"
+    )
+    serve_parser.add_argument("--host", default="127.0.0.1", help="Host to bind to (default: 127.0.0.1)")
+    serve_parser.add_argument("--port", type=int, default=8787, help="Port to listen on (default: 8787)")
+    serve_parser.add_argument("--no-browser", action="store_true", help="Don't automatically open a browser tab")
+
     return parser
 
 
@@ -102,13 +115,17 @@ def main(argv: Optional[list[str]] = None) -> int:
             return _run_diff(args)
         if args.command == "diff-graphql":
             return _run_diff_graphql(args)
+        if args.command == "diff-proto":
+            return _run_diff_proto(args)
         if args.command == "check":
             return _run_check(args)
         if args.command == "watch":
             return _run_watch(args)
         if args.command == "init":
             return _run_init(args)
-    except (SpecLoadError, GitError, GraphQLLoadError) as exc:
+        if args.command == "serve":
+            return _run_serve(args)
+    except (SpecLoadError, GitError, GraphQLLoadError, ProtoLoadError) as exc:
         print(f"Error: {exc}", file=sys.stderr)
         return 2
     except KeyboardInterrupt:
@@ -133,6 +150,13 @@ def _run_diff_graphql(args: argparse.Namespace) -> int:
     return _emit_result(result, args)
 
 
+def _run_diff_proto(args: argparse.Namespace) -> int:
+    old_proto = load_proto(args.old)
+    new_proto = load_proto(args.new)
+    result = diff_protos(old_proto, new_proto)
+    return _emit_result(result, args)
+
+
 def _run_check(args: argparse.Namespace) -> int:
     config = SpecShiftConfig.load(args.config)
     spec_path = args.spec or config.spec_path
@@ -219,6 +243,13 @@ def _run_init(args: argparse.Namespace) -> int:
     return 0
 
 
+def _run_serve(args: argparse.Namespace) -> int:
+    from specshift.webapp import run_server
+
+    run_server(host=args.host, port=args.port, open_browser=not args.no_browser)
+    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]