diffguard 0.1.3__py3-none-any.whl

diffguard/languages/typescript/__init__.py

@@ -0,0 +1,184 @@
+"""TypeScript/JavaScript language support."""
+
+from __future__ import annotations
+
+import tree_sitter
+import tree_sitter_javascript
+import tree_sitter_typescript
+
+from diffguard.engine._types import Symbol, compute_body_hash
+from diffguard.languages._utils import node_text
+
+# Default to TypeScript grammar (superset of JS)
+_ts_lang = tree_sitter.Language(tree_sitter_typescript.language_typescript())
+_js_lang = tree_sitter.Language(tree_sitter_javascript.language())
+
+
+def get_language() -> tree_sitter.Language:
+    """Return the tree-sitter Language object for TypeScript."""
+    return _ts_lang
+
+
+def get_js_language() -> tree_sitter.Language:
+    """Return the tree-sitter Language object for JavaScript."""
+    return _js_lang
+
+
+def extract_symbols(tree: tree_sitter.Tree, source: bytes) -> list[Symbol]:
+    """Extract symbols from a parsed JavaScript/TypeScript tree."""
+    symbols: list[Symbol] = []
+    _walk_node(tree.root_node, source, symbols, parent_class=None)
+    return symbols
+
+
+def _walk_node(
+    node: tree_sitter.Node,
+    source: bytes,
+    symbols: list[Symbol],
+    parent_class: str | None,
+) -> None:
+    """Recursively walk the tree and extract symbols."""
+    for child in node.children:
+        if child.type == "function_declaration":
+            _extract_function(child, symbols)
+        elif child.type == "class_declaration":
+            _extract_class(child, source, symbols)
+        elif child.type in ("lexical_declaration", "variable_declaration"):
+            _extract_arrow_functions(child, symbols)
+        elif child.type == "export_statement":
+            _walk_node(child, source, symbols, parent_class)
+
+
+def _extract_function(
+    node: tree_sitter.Node,
+    symbols: list[Symbol],
+) -> None:
+    """Extract a function declaration."""
+    name_node = node.child_by_field_name("name")
+    if name_node is None:
+        return
+    name = node_text(name_node)
+    params_node = node.child_by_field_name("parameters")
+    params = node_text(params_node) if params_node else "()"
+    signature = f"function {name}{params}"
+    body_node = node.child_by_field_name("body")
+    body_text = node_text(body_node) if body_node else ""
+
+    symbols.append(
+        Symbol(
+            name=name,
+            kind="function",
+            signature=signature,
+            start_line=node.start_point.row + 1,
+            end_line=node.end_point.row + 1,
+            body_hash=compute_body_hash(body_text),
+        )
+    )
+
+
+def _extract_class(
+    node: tree_sitter.Node,
+    source: bytes,
+    symbols: list[Symbol],
+) -> None:
+    """Extract a class declaration and its methods."""
+    name_node = node.child_by_field_name("name")
+    if name_node is None:
+        return
+    class_name = node_text(name_node)
+    body_node = node.child_by_field_name("body")
+    body_text = node_text(body_node) if body_node else ""
+
+    heritage = ""
+    for child in node.children:
+        if child.type == "class_heritage":
+            heritage = f" {node_text(child)}"
+            break
+
+    symbols.append(
+        Symbol(
+            name=class_name,
+            kind="class",
+            signature=f"class {class_name}{heritage}",
+            start_line=node.start_point.row + 1,
+            end_line=node.end_point.row + 1,
+            body_hash=compute_body_hash(body_text),
+        )
+    )
+
+    if body_node:
+        for child in body_node.children:
+            if child.type == "method_definition":
+                _extract_method(child, symbols, class_name)
+
+
+def _extract_method(
+    node: tree_sitter.Node,
+    symbols: list[Symbol],
+    class_name: str,
+) -> None:
+    """Extract a method definition."""
+    name_node = node.child_by_field_name("name")
+    if name_node is None:
+        return
+    name = node_text(name_node)
+    params_node = node.child_by_field_name("parameters")
+    params = node_text(params_node) if params_node else "()"
+    signature = f"{name}{params}"
+    body_node = node.child_by_field_name("body")
+    body_text = node_text(body_node) if body_node else ""
+
+    symbols.append(
+        Symbol(
+            name=name,
+            kind="method",
+            signature=signature,
+            start_line=node.start_point.row + 1,
+            end_line=node.end_point.row + 1,
+            body_hash=compute_body_hash(body_text),
+            parent=class_name,
+        )
+    )
+
+
+def _extract_arrow_functions(
+    node: tree_sitter.Node,
+    symbols: list[Symbol],
+) -> None:
+    """Extract arrow functions assigned to variables."""
+    # Detect keyword (const/let/var)
+    keyword = "const"
+    for sib in node.children:
+        if not sib.is_named:
+            t = node_text(sib)
+            if t in ("const", "let", "var"):
+                keyword = t
+                break
+
+    for child in node.children:
+        if child.type == "variable_declarator":
+            name_node = child.child_by_field_name("name")
+            value_node = child.child_by_field_name("value")
+            if name_node and value_node and value_node.type == "arrow_function":
+                name = node_text(name_node)
+                params_node = value_node.child_by_field_name("parameters")
+                if params_node:
+                    params = node_text(params_node)
+                else:
+                    param_node = value_node.child_by_field_name("parameter")
+                    params = f"({node_text(param_node)})" if param_node else "()"
+
+                signature = f"{keyword} {name} = {params} =>"
+                body_node = value_node.child_by_field_name("body")
+                body_text = node_text(body_node) if body_node else ""
+
+                symbols.append(
+                    Symbol(
+                        name=name,
+                        kind="function",
+                        signature=signature,
+                        start_line=node.start_point.row + 1,
+                        end_line=node.end_point.row + 1,
+                        body_hash=compute_body_hash(body_text),
+                    )
+                )

diffguard/languages/typescript/queries.scm

@@ -0,0 +1 @@
+; TypeScript tree-sitter queries — placeholder

diffguard/schema.py

@@ -0,0 +1,97 @@
+"""DiffGuard output schema — Pydantic v2 models."""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Literal
+
+from pydantic import BaseModel
+
+
+class DiffStats(BaseModel):
+    """Diff statistics."""
+
+    files: int
+    additions: int
+    deletions: int
+
+
+class Meta(BaseModel):
+    """Run metadata."""
+
+    ref_range: str
+    stats: DiffStats
+    warnings: list[str] = []
+    timing_ms: float | None = None
+
+
+class SymbolChange(BaseModel):
+    """A single symbol-level change."""
+
+    kind: Literal[
+        "function_added",
+        "function_removed",
+        "function_modified",
+        "class_added",
+        "class_removed",
+        "class_modified",
+        "signature_changed",
+        "moved",
+    ]
+    name: str
+    signature: str | None = None
+    before_signature: str | None = None
+    after_signature: str | None = None
+    file_from: str | None = None
+    line: int | None = None
+    breaking: bool = False
+    detail: dict[str, Any] | None = None
+
+
+class FileChange(BaseModel):
+    """A changed file with its symbol-level changes."""
+
+    path: str
+    language: str | None = None
+    change_type: Literal["added", "removed", "modified", "renamed"]
+    generated: bool = False
+    binary: bool = False
+    parse_error: bool = False
+    unsupported_language: bool = False
+    changes: list[SymbolChange] = []
+
+
+class Summary(BaseModel):
+    """Aggregate summary of changes.
+
+    Migration note (v1.0 → v1.1): Added ``focus`` field — a short list of
+    the most important items for reviewer agents.  Existing consumers that
+    ignore unknown fields are unaffected.
+    """
+
+    change_types: dict[str, int] = {}
+    breaking_changes: list[SymbolChange] = []
+    focus: list[str] = []
+
+
+class TieredSummary(BaseModel):
+    """Multi-tier human-readable summary."""
+
+    oneliner: str = ""
+    short: str = ""
+    detailed: str = ""
+
+
+class DiffGuardOutput(BaseModel):
+    """Top-level DiffGuard output."""
+
+    schema_version: str = "1.1"
+    meta: Meta
+    files: list[FileChange] = []
+    summary: Summary = Summary()
+    tiered: TieredSummary = TieredSummary()
+
+
+def export_json_schema() -> str:
+    """Export the JSON schema as a string."""
+    return json.dumps(DiffGuardOutput.model_json_schema(), indent=2)

diffguard-0.1.3.dist-info/METADATA

@@ -0,0 +1,142 @@
+Metadata-Version: 2.4
+Name: diffguard
+Version: 0.1.3
+Summary: Catches the structural breaks that pass code review
+Project-URL: Homepage, https://github.com/ostehost/diffguard
+Project-URL: Repository, https://github.com/ostehost/diffguard
+Project-URL: Issues, https://github.com/ostehost/diffguard/issues
+Author: ostehost
+License: BSL-1.1
+License-File: LICENSE
+Keywords: agents,ai,code-intelligence,code-review,git,tree-sitter
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: Other/Proprietary License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Version Control :: Git
+Requires-Python: >=3.11
+Requires-Dist: click>=8.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: rich>=13.0
+Requires-Dist: tree-sitter-go
+Requires-Dist: tree-sitter-javascript
+Requires-Dist: tree-sitter-python
+Requires-Dist: tree-sitter-typescript>=0.23.2
+Requires-Dist: tree-sitter>=0.24
+Description-Content-Type: text/markdown
+
+[![PyPI](https://img.shields.io/pypi/v/diffguard)](https://pypi.org/project/diffguard/)
+[![License](https://img.shields.io/badge/license-BSL%201.1-blue)](LICENSE)
+[![Python](https://img.shields.io/badge/python-3.11%2B-blue)](https://pypi.org/project/diffguard/)
+
+# DiffGuard
+
+**Catches the structural breaks that pass code review.**
+
+## A real bug, in one line
+
+This diff shipped in Flask ([PR #5898](https://github.com/pallets/flask/pull/5898)):
+
+```diff
+-def redirect(location, code=302, ...):
++def redirect(location, code=303, ...):
+```
+
+One line. Looks fine. A reviewer approves it.
+
+**The real impact:** 7 endpoints silently change HTTP behavior. POST-to-POST redirects become POST-to-GET. No errors. No warnings. Just broken APIs in production.
+
+**DiffGuard catches it:**
+
+```
+$ diffguard review eca5fd1d~1..eca5fd1d
+
+⚠ DiffGuard: 2 changes need review
+
+  DEFAULT VALUE CHANGED: redirect(location, code=302) → redirect(location, code=303)
+  src/flask/helpers.py:241 — 7 callers rely on the default
+
+  DEFAULT VALUE CHANGED: App.redirect(self, location, code=302) → App.redirect(self, location, code=303)
+  src/flask/sansio/app.py:935 — 7 callers rely on the default
+```
+
+Tree-sitter AST analysis. No LLM. No network calls. Runs in seconds.
+
+## What it catches
+
+Function signature changes, removed/renamed symbols, default value changes — and shows you every caller affected.
+
+## What it doesn't catch
+
+Logic bugs, behavioral changes beyond signatures, performance issues, security vulnerabilities. DiffGuard detects **structural breaks**, not all bugs.
+
+When there's nothing structural to report, it stays silent (exit code 0, no output).
+
+## Quick Start
+
+```bash
+pip install diffguard
+diffguard review main..feature
+```
+
+Exit codes: `0` = nothing noteworthy, `1` = findings, `2` = error.
+
+## How It Works
+
+1. **Parses the diff** using tree-sitter AST analysis (not regex)
+2. **Extracts symbols** — functions, classes, signatures
+3. **Detects high-signal changes** — signature changes, removed symbols, default value changes
+4. **Scans for callers** — finds every file that references changed symbols
+5. **Outputs actionable context** — or stays silent if nothing matters
+
+## Agent Integration
+
+Works with **Claude Code**, **Cursor**, **GitHub Actions**, or any agent that can run a CLI command.
+
+Add one line to your agent config — DiffGuard is silent when nothing matters.
+
+See the full [Agent Integration Guide](docs/agent-integration.md) for hooks, CI patterns, and snippets for [Claude Code](docs/claude-md-snippet.md) and [Cursor](docs/cursor-rule-snippet.md).
+
+## GitHub Action
+
+```yaml
+# .github/workflows/diffguard.yml
+name: DiffGuard PR Review
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+permissions:
+  contents: read
+  pull-requests: write
+jobs:
+  diffguard:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: ostehost/diffguard@main
+```
+
+## Languages
+
+- **Python** (most mature — extensive real-world validation)
+- TypeScript / JavaScript
+- Go
+- More planned (Rust, Java, C#)
+
+## Philosophy
+
+1. **Silence is a feature.** No findings? No output. Most diffs don't need structural analysis.
+2. **Local-first.** Your code never leaves your machine. No SaaS, no API keys, no accounts.
+3. **Agent-native.** CLI + JSON output. `pip install` and go.
+4. **Precision over recall.** We'd rather miss a minor issue than cry wolf on every PR.
+
+## License
+
+BSL 1.1 — see [LICENSE](LICENSE) for details.

diffguard-0.1.3.dist-info/RECORD

@@ -0,0 +1,26 @@
+diffguard/__init__.py,sha256=_vw6s8kAEZEWKaqdJTNGBUPL6gW1ywfRcUIcq-hbtYs,87
+diffguard/cli.py,sha256=GqmApvmyNXnR1lxuVH4CoXnkg7U7P7MdMPJWzDCQbYk,23389
+diffguard/git.py,sha256=b8SvW0jDh91NHslqbIVsGaGeM7jW3Ew9jjqVQ2laBP4,9786
+diffguard/schema.py,sha256=aQPtehSqeA0UjKnuBhiNbSOZ8Pjv67QI9lyZ-xx8NYs,2258
+diffguard/engine/__init__.py,sha256=8KkxYzAC3ZMTBiP5ysv1LlPXW4XMNf5GJ6K7aTyXmlc,33
+diffguard/engine/_types.py,sha256=LgzAH20Z7a4mRezb_DodPBcD5ldnS4wDSRrd4NiGwo4,990
+diffguard/engine/classifier.py,sha256=OXjvXnn3x5O99DPAg9nXFQ2LPkR4hQNP0gHl0_HoBOY,2637
+diffguard/engine/deps.py,sha256=6rZiwm2MdicefKbveD2-2fIq2A7DtkU2r5M9dvuTjOY,6214
+diffguard/engine/matcher.py,sha256=iYhLGLRGEt0qTejuWQB-AWKU5Y_2Fg9J7kFjZHmKbJ4,4220
+diffguard/engine/parser.py,sha256=hzSNAI1c4rCboPLLszGF_Dil1EygFAXdE5PpDcB_B4c,1338
+diffguard/engine/pipeline.py,sha256=-hhOyP7YyUoxfuCZWhoOc-zkoxJLSnKtRONvpv540gM,6508
+diffguard/engine/signatures.py,sha256=cybi_p1pmWW_UOergRmRLM32xKOBc3GPLdOjHJcHcAU,8545
+diffguard/engine/summarizer.py,sha256=ffkotlB_XwLP_YcREL5CI88L9j4etvXRT9_WwyQcZHs,13387
+diffguard/languages/__init__.py,sha256=1vjO-694V0j6rBI5erxr5G2ctMl03_WpAC-xSsjTLy0,1485
+diffguard/languages/_utils.py,sha256=XVStFVZpdcSVLgOxvpti9dT548SSNF8M_DralHO9Bts,294
+diffguard/languages/go/__init__.py,sha256=kJOi4WWgrVSejQHegPBkHzTRrPuhjItfeIzO0u-r4B4,3466
+diffguard/languages/go/queries.scm,sha256=5mEellIGMjVR7qA4Xt9LlpNEok7G1nfpxPg0vhcW2iQ,41
+diffguard/languages/python/__init__.py,sha256=93M37cZwFjmGLdeXozVVtzBysRTuYTT77LrsZd3jSEo,6480
+diffguard/languages/python/queries.scm,sha256=bv8GYn2bpL6lXW3OcVOEow-nZE3bdX1s3N2QYmyn21s,45
+diffguard/languages/typescript/__init__.py,sha256=bkYxwkcxCCgRsdrUQ5zFjCbU_y4Lm6GFRZN74gHd1bc,6001
+diffguard/languages/typescript/queries.scm,sha256=dJ6ZUwxpwDfDlj7e6irC5ivILomaocttuvAEcf5Nqz8,49
+diffguard-0.1.3.dist-info/METADATA,sha256=OY8KSTYzKCB4MbPrqsDJqtgXNiyEqnYgw3DZ4teYtU4,4783
+diffguard-0.1.3.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+diffguard-0.1.3.dist-info/entry_points.txt,sha256=iWYD-Yd6-jOpBE08rQv8I1SQsfCJ3BNWp4jh4sSPy84,49
+diffguard-0.1.3.dist-info/licenses/LICENSE,sha256=lOYMmmcw26-zTcgA3ptu-f653iWyb9qO2LRPgu0R9gg,2508
+diffguard-0.1.3.dist-info/RECORD,,

diffguard-0.1.3.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

diffguard-0.1.3.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+diffguard = diffguard.cli:main

diffguard-0.1.3.dist-info/licenses/LICENSE

@@ -0,0 +1,53 @@
+Business Source License 1.1
+
+Parameters
+
+Licensor:             ostehost
+Licensed Work:        DiffGuard v0.1.1 (and all subsequent versions)
+Additional Use Grant: You may use the Licensed Work for any purpose other
+                      than offering the functionality of the Licensed Work
+                      to third parties as a managed or hosted service.
+Change Date:          2029-02-11
+Change License:       Apache License 2.0
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative
+works, redistribute, and make non-production use of the Licensed Work. The
+Licensor may make an Additional Use Grant, above, permitting limited
+production use.
+
+Effective on the Change Date, or the fourth anniversary of the first publicly
+available distribution of a specific version of the Licensed Work under this
+License, whichever comes first, the Licensor hereby grants you rights under
+the terms of the Change License, and the rights granted in the paragraph
+above terminate.
+
+If your use of the Licensed Work does not comply with the requirements
+currently in effect as described in this License, you must purchase a
+commercial license from the Licensor, its affiliated entities, or authorized
+resellers, or you must refrain from using the Licensed Work.
+
+All copies of the original and modified Licensed Work, and derivative works
+of the Licensed Work, are subject to this License. This License applies
+separately for each version of the Licensed Work and the Change Date may vary
+for each version of the Licensed Work released by Licensor.
+
+You must conspicuously display this License on each original or modified copy
+of the Licensed Work. If you receive the Licensed Work in original or
+modified form from a third party, the terms and conditions set forth in this
+License apply to your use of that work.
+
+Any use of the Licensed Work in violation of this License will automatically
+terminate your rights under this License for the current and all other
+versions of the Licensed Work.
+
+This License does not grant you any right in any trademark or logo of
+Licensor or its affiliates (provided that you may use a trademark or logo of
+Licensor as expressly required by this License).
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON
+AN "AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS,
+EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND
+TITLE.