dg check

Analyze uncommitted or staged changes in your working tree against HEAD. This is the fastest way to see what you have broken before committing.

Usage

npx dg check              # Analyze all uncommitted changes
npx dg check --staged     # Analyze only staged files (git add'd)
npx dg check src/payments # Scope analysis to a directory

How it works

In working tree mode(default), Diff Guardian reads the current file on disk as the "new" source and HEADas the "old" source. It compares every exported symbol between the two versions.

In staged mode (--staged), it reads the git index (what you have git add'd) instead of the working tree. This is what will actually land in your next commit.

Path scoping

You can pass a path argument to limit the analysis to a specific directory. This is useful in monorepos where you only want to check one package:

npx dg check src/api      # Only analyze files under src/api/
npx dg check packages/core # Monorepo: scope to one package

Exit codes

CodeMeaning
0No breaking changes. Safe to proceed.
1Breaking changes detected. Review required.
2Pipeline error (missing grammar, parse failure).

Flags

FlagDescription
--stagedAnalyze only staged (git add'd) files instead of the full working tree.
--report-file <path>Write a JSON report to the specified file path.
--format <type>Output format: terminal (default), json, or sarif. Use sarif to produce a SARIF 2.1.0 log for GitHub Code Scanning — see CI/CD Integration.
--help, -hShow help message.

Example output

$ npx dg check --staged

  Diff-Guardian Check (staged)

  [BREAKING] Changes (1)

  > processPayment (signature_change)
    src/api/payments.ts:42
    Parameter 'currency' was removed. Callers providing this argument will fail.

  ──────────────────────────────────────────────────────────
  [STRICT MODE]
  1 breaking change found. Exiting with code 1.

SARIF output example

Piping --format sarif to a file produces a standards-compliant SARIF 2.1.0 log instead of the terminal report:

$ npx dg check --format sarif > diffguardian.sarif

# diffguardian.sarif
{
  "version": "2.1.0",
  "$schema": "https://raw.githubusercontent.com/oasis-tcs/sarif-spec/master/Schemata/sarif-schema-2.1.0.json",
  "runs": [
    {
      "tool": { "driver": { "name": "Diff-Guardian", "rules": [ /* ... */ ] } },
      "results": [
        {
          "ruleId": "signature_change",
          "level": "error",
          "message": { "text": "processPayment: Parameter 'currency' was removed." },
          "locations": [
            { "physicalLocation": { "artifactLocation": { "uri": "src/api/payments.ts" }, "region": { "startLine": 42 } } }
          ]
        }
      ]
    }
  ]
}

Upload the file with github/codeql-action/upload-sarif in a workflow step to surface breaking changes directly in the GitHub Security tab, alongside CodeQL findings.