change-firewall

✓ Authentication added
✓ Tests passing
✓ Build successful

- return user;
+ return { user };

npx change-firewall

npx change-firewall --open

npx change-firewall

npm install --save-dev change-firewall
# or
pnpm add -D change-firewall
# or
yarn add -D change-firewall

{
  "scripts": {
    "firewall": "change-firewall",
    "firewall:watch": "change-firewall watch",
    "preflight": "change-firewall preflight",
    "dashboard": "change-firewall open"
  }
}

npm install -g change-firewall
change-firewall

# Standard terminal report
npx change-firewall

# Analyze and automatically open browser dashboard (http://localhost:4783)
npx change-firewall --open

# Analyze only staged changes (git add)
npx change-firewall --staged

# Compare against a specific base branch or commit (e.g., origin/main)
npx change-firewall --base origin/main

# Output machine-readable JSON (great for AI agents or scripts)
npx change-firewall --json

# Run dashboard on a custom port
npx change-firewall --open -p 5000

# Standard preflight gate (fails if risk > 60 or high-risk findings exist)
npx change-firewall preflight

# Set a custom risk score threshold (0-100)
npx change-firewall preflight --max-risk 75

# Ignore high severity findings if overall score is below threshold
npx change-firewall preflight --no-fail-on-high

# Compare PR against base branch in CI
npx change-firewall preflight --base origin/main

# Emit JSON result for CI parsing
npx change-firewall preflight --json

# Start watch mode with auto-opened dashboard
npx change-firewall watch

# Watch mode on custom port without auto-opening browser
npx change-firewall watch -p 8080 --no-open

npx change-firewall impact src/middleware/auth.ts

npx change-firewall why src/services/userService.ts

npx change-firewall open

npx change-firewall demo

npx change-firewall mcp

import {
  analyzeChanges,
  evaluatePreflight,
  computeBlastRadius,
  buildDependencyGraph,
  startWatchMode,
} from 'change-firewall';

import { analyzeChanges } from 'change-firewall';

async function run() {
  const report = await analyzeChanges({
    cwd: process.cwd(),      // Project root path (defaults to process.cwd())
    // base: 'origin/main',  // Base ref to compare against (defaults to HEAD)
    // staged: false,        // True to analyze only staged files
  });

  console.log(`Repository: ${report.repoName} (${report.branch})`);
  console.log(`Risk Score: ${report.risk.score}/100 [${report.risk.level}]`);
  console.log(`Files Changed: ${report.summary.totalFilesChanged}`);
  console.log(`Behavioral Shifts: ${report.summary.behavioralChangeCount}`);

  // Inspect specific behavioral findings
  for (const finding of report.findings) {
    console.log(`\n[${finding.severity}] ${finding.title}`);
    console.log(`File: ${finding.filePath}`);
    console.log(`Confidence: ${finding.confidence}%`);
    console.log(`Evidence:`, finding.evidence);
    console.log(`Recommendation: ${finding.recommendation}`);
  }
}

run();

import { analyzeChanges, evaluatePreflight } from 'change-firewall';

async function checkMerge() {
  const report = await analyzeChanges({ cwd: process.cwd() });

  const preflight = evaluatePreflight(report, {
    maxRisk: 60,          // Maximum allowed risk score (0-100, default: 60)
    blockOnHighRisk: true, // Block if any HIGH severity finding exists (default: true)
    allowWarnings: true,   // Allow medium/low warnings if risk <= maxRisk
  });

  if (preflight.readyToMerge) {
    console.log('✅ Changes are safe to merge! Risk score:', preflight.riskScore);
    process.exit(0);
  } else {
    console.error('❌ MERGE BLOCKED:');
    preflight.blockers.forEach((b) => console.error(`  - 🛑 ${b}`));

    if (preflight.recommendations.length > 0) {
      console.log('\nRecommendations:');
      preflight.recommendations.forEach((r) => console.log(`  - 💡 ${r}`));
    }

    process.exit(1);
  }
}

checkMerge();

import { buildDependencyGraph, computeBlastRadius } from 'change-firewall';

async function checkImpact(targetFilePath: string) {
  // 1. Build project reverse import graph
  const { reverse } = await buildDependencyGraph(process.cwd());

  // 2. Traverse BFS up to 3 hops deep
  const blast = computeBlastRadius(targetFilePath, reverse, 3);

  console.log(`File: ${targetFilePath}`);
  console.log(`Total Consumers Affected: ${blast.totalDependents}`);
  console.log(`Direct Dependents:`, blast.directDependents);
  console.log(`Indirect Dependents (2-3 hops):`, blast.indirectDependents);

  if (blast.totalDependents > 5) {
    console.warn(`⚠️ High blast radius: ${blast.totalDependents} files depend on this!`);
  }
}

checkImpact('src/services/auth.ts');

import { startWatchMode } from 'change-firewall';

async function runLiveWatcher() {
  const handle = await startWatchMode({
    cwd: process.cwd(),
    port: 4783,          // Dashboard port
    open: true,          // Automatically open browser
    debounceMs: 350,     // Debounce delay for rapid edits
    onUpdate: (report) => {
      // Triggered whenever code is modified
      console.log(`[${new Date().toLocaleTimeString()}] Tree updated!`);
      console.log(`Risk Score: ${report.risk.score}/100`);
      console.log(`Modified: ${report.diffs.map((d) => d.filePath).join(', ')}`);
    },
  });

  console.log(`Watcher active on port ${handle.port}`);

  // Clean shutdown
  process.on('SIGINT', async () => {
    await handle.stop();
    process.exit(0);
  });
}

runLiveWatcher();

import { createMcpServer, startMcpServer } from 'change-firewall';

// Option A: Start standard stdio MCP server for AI clients
await startMcpServer();

// Option B: Create McpServer instance for custom transports (e.g. SSE / testing)
const server = createMcpServer({ name: 'custom-firewall', version: '0.1.3' });

{
  "mcpServers": {
    "change-firewall": {
      "command": "npx",
      "args": ["-y", "change-firewall", "mcp"]
    }
  }
}

{
  "mcpServers": {
    "change-firewall": {
      "command": "npx",
      "args": ["-y", "change-firewall", "mcp"]
    }
  }
}

### Change Verification & Safety Protocol:
Before committing or completing any code change:
1. Run `npx change-firewall preflight --json` to evaluate merge safety.
2. If `readyToMerge` is false, inspect the `blockers` and `highRiskCount` in the output.
3. Automatically self-correct any breaking API contract mutations or missing test coverage.
4. For targeted inspection of affected callers, run `npx change-firewall impact <modified-file>`.

{
  "risk": {
    "score": 74,
    "level": "HIGH"
  },
  "summary": {
    "totalFilesChanged": 3,
    "behavioralChangesCount": 1
  },
  "findings": [
    {
      "category": "API_CONTRACT",
      "title": "API Response Contract Mutated",
      "filePath": "src/controllers/user.ts",
      "severity": "HIGH",
      "confidence": 92,
      "evidence": [
        "Return statement modified: return user -> return { user }",
        "7 client consumers depend on root-level User object structure."
      ],
      "affectedFiles": [
        "src/client/userClient.ts",
        "src/views/profile.tsx"
      ],
      "recommendation": "Update client response deserializers or revert wrapper."
    }
  ]
}

name: Change Firewall

on:
  pull_request:
    branches: [ main, master, develop ]

permissions:
  contents: read
  pull-requests: write

jobs:
  verify-changes:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Code
        uses: actions/checkout@v4
        with:
          fetch-depth: 0 # Full history needed to compare against base branch

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20

      - name: Run Preflight Check
        run: npx change-firewall preflight --base origin/${{ github.base_ref }}

npx husky add .husky/pre-commit "npx change-firewall preflight --staged"

+-----------------------+     +--------------------------+     +-------------------------+
|   Working Tree Diff   | --> | TypeScript AST Analysis  | --> | Reverse Dependency Graph|
+-----------------------+     +--------------------------+     +-------------------------+
                                                                             │
                                                                             ▼
                                                               +-------------------------+
                                                               | Deterministic Risk Score|
                                                               |       (0 - 100)         |
                                                               +-------------------------+