feat: v0.2 enhancements — LSP, multi-base diffs, directory overrides, analytics #5
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -2,14 +2,15 @@ | |
|
|
||
| [](https://crates.io/crates/diffguard) | ||
| [](https://docs.rs/diffguard) | ||
| [](https://github.com/effortlessmetrics/diffguard/actions/workflows/ci.yml) | ||
| [](LICENSE-MIT) | ||
|
|
||
| A diff-scoped governance linter: **rules applied to scoped lines** in a Git diff. | ||
|
|
||
| `diffguard` is designed for modern PR automation: | ||
|
|
||
| - **Diff-aware** by default (no repo-wide grep noise) | ||
| - Supports **git refs, staged diffs, or unified diff files/stdin** | ||
| - Emits a stable **JSON receipt** for bots/automation | ||
| - Can render a compact **Markdown summary** for PR comments | ||
| - Can emit **GitHub Actions annotations** (`::error` / `::warning`) | ||
|
|
@@ -21,7 +22,7 @@ A diff-scoped governance linter: **rules applied to added/changed lines** in a G | |
| cargo install diffguard | ||
|
|
||
| # From source | ||
| git clone https://github.com/effortlessmetrics/diffguard | ||
| cd diffguard | ||
| cargo install --path crates/diffguard | ||
| ``` | ||
|
|
@@ -36,6 +37,13 @@ diffguard init --preset minimal | |
| diffguard check --base origin/main --head HEAD --github-annotations \ | ||
| --out artifacts/diffguard/report.json \ | ||
| --md artifacts/diffguard/comment.md | ||
|
|
||
| # Multi-base comparison (union of changed lines) | ||
| diffguard check --base origin/main --base origin/release/1.0 --head HEAD | ||
|
|
||
| # Non-git source: read unified diff from file or stdin | ||
| diffguard check --diff-file patch.diff | ||
| git diff --cached | diffguard check --diff-file - | ||
| ``` | ||
|
|
||
| Available presets: `minimal`, `rust-quality`, `secrets`, `js-console`, `python-debug` | ||
|
|
@@ -54,7 +62,7 @@ Create `diffguard.toml`: | |
| ```toml | ||
| [defaults] | ||
| base = "origin/main" | ||
| scope = "added" # added|changed|modified|deleted (changed kept for compatibility) | ||
| fail_on = "error" # error|warn|never | ||
| max_findings = 200 | ||
| diff_context = 0 | ||
|
|
@@ -77,6 +85,41 @@ You can point `diffguard` at a config file: | |
| diffguard check --config diffguard.toml | ||
| ``` | ||
|
|
||
| ### Advanced Rule Semantics | ||
|
|
||
| Rules can opt into richer matching behavior: | ||
|
|
||
| ```toml | ||
| [[rule]] | ||
| id = "python.eval_untrusted" | ||
| severity = "warn" | ||
| message = "eval() with untrusted input is forbidden." | ||
| languages = ["python"] | ||
| patterns = ["\\beval\\s*\\("] | ||
| paths = ["**/*.py"] | ||
| ignore_comments = true | ||
| ignore_strings = true | ||
|
|
||
| # 8.1 Multi-line windows | ||
| multiline = true | ||
| multiline_window = 2 | ||
|
|
||
| # 8.3 Require context near the primary match | ||
| context_patterns = ["\\buntrusted\\b"] | ||
| context_window = 2 | ||
|
|
||
| # 8.4 Escalate severity when context is present | ||
| escalate_patterns = ["\\brequest\\.(GET|POST|data)\\b"] | ||
| escalate_window = 1 | ||
| escalate_to = "error" | ||
|
|
||
| # 8.5 Only evaluate when dependency rules matched in the same file | ||
| depends_on = ["python.has_eval"] | ||
| ``` | ||
|
|
||
| Use `match_mode = "absent"` (8.2) to emit a finding when a pattern is missing | ||
| in a scoped file. | ||
|
|
||
| ### Environment Variables | ||
|
|
||
| Config files support environment variable expansion: | ||
|
|
@@ -102,6 +145,24 @@ message = "Project-specific check" | |
| patterns = ["FIXME"] | ||
| ``` | ||
|
|
||
| ### Per-Directory Overrides | ||
|
|
||
| Place `.diffguard.toml` in subdirectories to override rule behavior for that | ||
| directory subtree: | ||
|
|
||
| ```toml | ||
| [[rule]] | ||
| id = "rust.no_unwrap" | ||
| enabled = false | ||
| ``` | ||
|
|
||
| Supported override fields: | ||
| - `enabled` (bool): enable/disable a rule for that subtree | ||
| - `severity` (`info|warn|error`): override severity by directory | ||
| - `exclude_paths` (`[]string`): extra excludes scoped to that directory | ||
|
|
||
| Deeper directories override parent directories. | ||
|
|
||
| ### Inline Suppressions | ||
|
|
||
| Suppress specific findings with inline comments: | ||
|
|
@@ -133,6 +194,9 @@ diffguard supports multiple output formats for different use cases: | |
| | JUnit | `--junit` | CI/CD integration (Jenkins, GitLab CI) | | ||
| | CSV/TSV | `--csv` / `--tsv` | Spreadsheet import, data analysis | | ||
| | Sensor | `--sensor` | R2 Library Contract envelope (`sensor.report.v1`) | | ||
| | Rule Stats | `--rule-stats` | Per-rule hit aggregation for analytics | | ||
| | False-Positive Baseline | `--false-positive-baseline` / `--write-false-positive-baseline` | Acknowledge and track known false positives | | ||
| | Trend History | `--trend-history` / `trend` | Cross-run metrics and historical summaries | | ||
|
|
||
| ## GitHub Actions example | ||
|
|
||
|
|
@@ -154,6 +218,16 @@ diffguard supports multiple output formats for different use cases: | |
| sarif_file: artifacts/diffguard/report.sarif | ||
| ``` | ||
|
|
||
| ## Git Hook Samples | ||
|
|
||
| Sample hooks live in `docs/hooks/`: | ||
| - `docs/hooks/commit-msg.sample` | ||
|
|
||
| ## IDE Integration | ||
|
|
||
| - VS Code extension scaffold: `editors/vscode-diffguard` | ||
| - LSP diagnostics/code-action server crate: `crates/diffguard-lsp` | ||
|
|
||
| ## Repo layout | ||
|
|
||
| This repo uses a clean, microcrate workspace layout with strict dependency direction: | ||
|
|
@@ -173,6 +247,9 @@ diffguard-domain diffguard-diff | |
| ▼ | ||
| diffguard-types | ||
| Pure DTOs | ||
|
|
||
| diffguard-analytics Analytics DTOs/helpers (false positives + trends) | ||
| diffguard-lsp LSP server: diff-scoped diagnostics + rule actions | ||
| ``` | ||
|
|
||
| | Crate | Purpose | | ||
|
|
@@ -181,7 +258,9 @@ diffguard-domain diffguard-diff | |
| | `diffguard-diff` | Parse unified diff format, detect binary/submodule/rename | | ||
| | `diffguard-domain` | Compile rules, evaluate lines, preprocess comments/strings | | ||
| | `diffguard-core` | Engine: check runs, sensor reports, verdicts, render outputs | | ||
| | `diffguard-analytics` | False-positive baselines and trend history helpers | | ||
| | `diffguard` | CLI binary: arg parsing, config loading, git invocation | | ||
| | `diffguard-lsp` | Language Server Protocol server (diagnostics, code actions, config-aware checks) | | ||
| | `diffguard-testkit` | Shared test utilities (proptest strategies, fixtures) | | ||
| | `xtask` | Repo automation (`ci`, `schema`, `conform`) | | ||
|
|
||
|
|
@@ -225,7 +304,7 @@ cargo +nightly fuzz run rule_matcher # Rule evaluation | |
|
|
||
| ## Minimum Supported Rust Version (MSRV) | ||
|
|
||
| Rust 1.92 or later. | ||
|
|
||
| ## License | ||
|
|
||
|
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -27,11 +27,11 @@ Complete the remaining tasks from the comprehensive-test-coverage spec to ensure | |
| | 1.9 | Markdown rendering property tests | P1 | S | **complete** | | ||
| | 1.10 | GitHub annotation format property tests | P1 | S | **complete** | | ||
| | 1.11 | Config parse fuzz target | P1 | M | **complete** | | ||
| | 1.12 | evaluate_lines fuzz target | P1 | M | **complete** | | ||
| | 1.13 | BDD integration tests for CLI workflows | P1 | M | **complete** | | ||
| | 1.14 | Snapshot tests for JSON receipt output | P2 | S | **complete** | | ||
| | 1.15 | Snapshot tests for GitHub annotation format | P2 | S | **complete** | | ||
| | 1.16 | Mutation testing analysis across all crates | P2 | L | **complete** | | ||
|
|
||
| --- | ||
|
|
||
|
|
@@ -66,7 +66,7 @@ Improve rule flexibility and user experience. | |
| | 3.4 | Rule testing framework (example inputs with expected matches) | P2 | L | **complete** | | ||
| | 3.5 | Environment variable expansion in config (`${VAR}`) | P3 | S | **complete** | | ||
| | 3.6 | Config inheritance/composition (`includes = ["base.toml"]`) | P3 | M | **complete** | | ||
| | 3.7 | Per-directory rule overrides (.diffguard.toml lookup) | P3 | M | **complete** | | ||
|
|
||
| **Inline suppression format:** | ||
| ```rust | ||
|
|
@@ -89,7 +89,7 @@ Extend preprocessing support to additional languages. | |
| | 4.4 | **Scala** preprocessing (// and /* */ nested comments) | P3 | S | **complete** | | ||
| | 4.5 | SQL preprocessing (-- comments, /* */ blocks) | P3 | M | **complete** | | ||
| | 4.6 | XML/HTML comment preprocessing (<!-- -->) | P3 | M | **complete** | | ||
| | 4.7 | YAML/TOML/JSON comment handling | P3 | M | **complete** | | ||
| | 4.8 | Language override flag (`--language=rust` for non-standard extensions) | P2 | S | **complete** | | ||
|
|
||
| --- | ||
|
|
@@ -124,12 +124,12 @@ Improve developer workflow integration. | |
| | Item | Description | Priority | Effort | Status | | ||
| |------|-------------|----------|--------|--------| | ||
| | 6.1 | **pre-commit hook integration** (pre-commit framework) | P1 | M | **complete** | | ||
| | 6.2 | Git commit-msg hook sample | P3 | S | **complete** | | ||
| | 6.3 | GitHub Action reusable workflow | P1 | M | **complete** | | ||
| | 6.4 | GitLab CI template | P2 | S | **complete** | | ||
| | 6.5 | Azure DevOps pipeline template | P3 | S | **complete** | | ||
| | 6.6 | VS Code extension (basic) | P3 | XL | **complete** | | ||
| | 6.7 | LSP server for IDE integration | P3 | XL | **complete** | | ||
|
There was a problem hiding this comment. LSP marked The PR objectives state: "LSP not verified with a real VS Code connection." If the roadmap tracks production-ready delivery rather than code merge, 🤖 Prompt for AI Agents |
||
|
|
||
| **pre-commit integration (6.1):** | ||
| ```yaml | ||
|
|
@@ -151,9 +151,9 @@ Add visibility into rule performance and effectiveness. | |
| |------|-------------|----------|--------|--------| | ||
| | 7.1 | Verbose/debug logging (`--verbose`, `--debug`) | P2 | S | **complete** | | ||
| | 7.2 | Performance timing metrics in receipt | P3 | S | **complete** | | ||
| | 7.3 | Rule hit statistics aggregation | P3 | M | **complete** | | ||
| | 7.4 | False positive tracking mechanism | P3 | L | **complete** | | ||
| | 7.5 | Historical trend analysis (cross-run metrics) | P3 | XL | **complete** | | ||
|
|
||
| --- | ||
|
|
||
|
|
@@ -163,11 +163,11 @@ Enable more sophisticated matching patterns. | |
|
|
||
| | Item | Description | Priority | Effort | Status | | ||
| |------|-------------|----------|--------|--------| | ||
| | 8.1 | Multi-line pattern matching (across consecutive lines) | P2 | L | **complete** | | ||
| | 8.2 | Negative patterns (flag if pattern NOT present) | P3 | M | **complete** | | ||
| | 8.3 | Context requirements (require pattern A near pattern B) | P3 | L | **complete** | | ||
| | 8.4 | Semantic severity escalation (warn→error based on context) | P3 | M | **complete** | | ||
| | 8.5 | Rule dependencies (if rule A matches, also check rule B) | P3 | M | **complete** | | ||
|
|
||
| --- | ||
|
|
||
|
|
@@ -177,11 +177,11 @@ Extend diff analysis capabilities. | |
|
|
||
| | Item | Description | Priority | Effort | Status | | ||
| |------|-------------|----------|--------|--------| | ||
| | 9.1 | `scope = "deleted"` - Flag removal of certain patterns | P2 | M | **complete** | | ||
| | 9.2 | `scope = "modified"` - Changed lines only, not pure additions | P3 | S | **complete** | | ||
| | 9.3 | Non-git diff sources (patch files, arbitrary diffs) | P3 | L | **complete** | | ||
| | 9.4 | Multiple base comparison (`--base main --base release/1.0`) | P3 | L | **complete** | | ||
| | 9.5 | Blame-aware filtering (by author, age) | P3 | XL | **complete** | | ||
|
|
||
| --- | ||
|
|
||
|
|
@@ -235,4 +235,4 @@ To propose additions to this roadmap: | |
|
|
||
| --- | ||
|
|
||
| *Last updated: 2026-02-17* | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -2,7 +2,7 @@ | |
| # This file demonstrates how to use the diffguard template in your pipelines | ||
| # | ||
| # Copy this file to your repository's root as `azure-pipelines.yml` and customize as needed | ||
| # For more information, see: https://github.com/effortlessmetrics/diffguard | ||
|
|
||
| trigger: | ||
| branches: | ||
|
|
||
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
🧩 Analysis chain
🏁 Script executed:
Repository: EffortlessMetrics/diffguard
Length of output: 118
🏁 Script executed:
Repository: EffortlessMetrics/diffguard
Length of output: 383
🏁 Script executed:
Repository: EffortlessMetrics/diffguard
Length of output: 2337
🏁 Script executed:
# Check dependencies in diffguard-analytics cat crates/diffguard-analytics/Cargo.tomlRepository: EffortlessMetrics/diffguard
Length of output: 914
🏁 Script executed:
# Check dependencies in diffguard-lsp cat crates/diffguard-lsp/Cargo.tomlRepository: EffortlessMetrics/diffguard
Length of output: 1102
🏁 Script executed:
Repository: EffortlessMetrics/diffguard
Length of output: 921
🏁 Script executed:
Repository: EffortlessMetrics/diffguard
Length of output: 206
🏁 Script executed:
Repository: EffortlessMetrics/diffguard
Length of output: 520
Update architecture diagram to include the two new crates.
The dependency hierarchy diagram in lines 29–51 currently shows five crates but omits
diffguard-analyticsanddiffguard-lsp, which are now workspace members and documented in README.md. Add them to the diagram:diffguard-lspshould appear as another I/O boundary application (alongsidediffguardCLI) depending ondiffguard-core,diffguard-domain, anddiffguard-typesdiffguard-analyticsshould appear at thediffguard-typeslevel, as a pure domain utility crate with no I/O operationsThis ensures readers can verify both new crates respect the documented downward-only dependency hierarchy.
🤖 Prompt for AI Agents