@codapult/guard 0.1.0 → 0.2.0

package/README.md

@@ -2,6 +2,7 @@
 
 [![CI](https://github.com/codapult/codapult-guard/actions/workflows/ci.yml/badge.svg)](https://github.com/codapult/codapult-guard/actions/workflows/ci.yml)
 [![Fixtures](https://github.com/codapult/codapult-guard/actions/workflows/guard-fixtures.yml/badge.svg)](https://github.com/codapult/codapult-guard/actions/workflows/guard-fixtures.yml)
+[![npm](https://img.shields.io/npm/v/@codapult/guard?logo=npm)](https://www.npmjs.com/package/@codapult/guard)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 [![Node.js >=20.19](https://img.shields.io/badge/node-%3E%3D20.19-339933.svg?logo=node.js&logoColor=white)](package.json)
 [![TypeScript](https://img.shields.io/badge/TypeScript-first-3178C6.svg?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
@@ -11,8 +12,43 @@
 `@codapult/guard` is a local-first, model-agnostic architecture guard for JavaScript and
 TypeScript projects.
 
-It learns what already exists, records the project’s architectural memory, and protects future
-changes from introducing regressions.
+It learns what already exists, records the project’s architectural memory, and can protect future
+changes from introducing regressions covered by the project’s approved policy.
+
+### See the value in one change
+
+Suppose a SaaS project has an established boundary:
+
+```text
+Client → Server Action → Service → Repository → Database
+```
+
+An AI agent can still produce code that is valid TypeScript but crosses that boundary:
+
+```text
+Client → Database
+```
+
+After the project has explicitly approved a matching import rule or deterministic contract, Guard
+checks the changed files and reports matching violations deterministically:
+
+```text
+Codapult Guard (changed files)
+Scanned 1 source file(s); suppressed 12 baseline finding(s).
+
+src/app/settings/page.tsx:1 [client-no-persistence-import]
+  Client modules should not import persistence-layer modules.
+  import: @/lib/db/client
+
+✗ 1 issue(s) found
+Exit code: 1
+```
+
+The file path, rule ID, message, and counts depend on the project. This is the actual CLI output
+shape: Guard does not infer that every `Client → Database` edge is forbidden, and it does not
+activate proposals silently. The team approves the relevant policy first; then existing findings
+can be baselined while newly matching violations fail the gate and give the agent bounded evidence
+to repair.
 
 > **Guard does not tell every project to use the same architecture.**
 > It discovers the architecture that is already there, then lets the team decide what becomes policy.
@@ -164,6 +200,12 @@ init once → edit → check --changed → review → verify → commit / merge
    contract validation.
 5. `audit` inspects the complete current state, including findings accepted by the baseline.
 
+For a focused change explanation, use `codapult-guard impact <file...>` or the equivalent
+`codapult_guard_impact` MCP tool. It reports both directions of the dependency graph: what the
+changed module uses and which transitive callers may be affected. `review` includes the same
+impact packet plus typed Git changes (`added`, `modified`, `deleted`, and `renamed`) for the AI
+host.
+
 Guard state is stored in `.codapult/guard/`:
 
 ```text
@@ -194,6 +236,25 @@ Start the standalone MCP server over stdio:
 pnpm exec codapult-guard mcp-server
 ```
 
+Register that command in the MCP client from the project root. For example, Cursor can use
+`.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "codapult-guard": {
+      "command": "pnpm",
+      "args": ["exec", "codapult-guard", "mcp-server"],
+      "cwd": "."
+    }
+  }
+}
+```
+
+For clients that accept a generic stdio server, use the same command and set its working
+directory to the project root. Guard reads local files only; no API key or model provider is
+required. Host-specific examples are in [`docs/integrations/`](docs/integrations/).
+
 Recommended agent loop:
 
 ```text
@@ -225,19 +286,20 @@ real project shapes.
 
 ## CLI surface
 
-| Command                    | Purpose                                                         |
-| -------------------------- | --------------------------------------------------------------- |
-| `init`                     | Create project memory and the initial baseline.                 |
-| `analyze`                  | Refresh facts without changing policy or baseline.              |
-| `propose`                  | Generate evidence-based rule and contract proposals.            |
-| `check --changed`          | Enforce active policy on changed and untracked files.           |
-| `audit`                    | Scan the complete current project, including baseline findings. |
-| `review`                   | Create a bounded semantic-review packet for an AI host.         |
-| `verify`                   | Run the configured completion gate.                             |
-| `doctor`                   | Diagnose invalid or missing Guard artifacts.                    |
-| `history` / `history-diff` | Inspect project model evolution.                                |
-| `rules` / `contracts`      | Approve or reject proposed policy.                              |
-| `baseline`                 | Review or intentionally accept existing findings.               |
+| Command                    | Purpose                                                                                     |
+| -------------------------- | ------------------------------------------------------------------------------------------- |
+| `init`                     | Create project memory and the initial baseline.                                             |
+| `analyze`                  | Refresh facts without changing policy or baseline.                                          |
+| `propose`                  | Generate evidence-based rule and contract proposals.                                        |
+| `check --changed`          | Enforce active policy on changed and untracked files.                                       |
+| `audit`                    | Scan the complete current project, including baseline findings.                             |
+| `review`                   | Create a bounded semantic-review packet for an AI host.                                     |
+| `verify`                   | Run the configured completion gate.                                                         |
+| `doctor`                   | Diagnose invalid or missing Guard artifacts.                                                |
+| `history` / `history-diff` | Inspect project model, module graph, and architecture-edge evolution.                       |
+| `impact <files...>`        | Explain dependencies, transitive dependents, capabilities, and contracts affected by files. |
+| `rules` / `contracts`      | Approve or reject proposed policy.                                                          |
+| `baseline`                 | Review or intentionally accept existing findings.                                           |
 
 Run `pnpm exec codapult-guard <command> --help` for command-specific options.
 

package/dist/cli/commands/guard.d.ts

@@ -13,6 +13,9 @@ export declare function guardDoctorCommand(options?: {
     json?: boolean;
 }): void;
 export declare function guardHistoryCommand(): void;
+export declare function guardImpactCommand(files: string[], options?: {
+    json?: boolean;
+}): void;
 export declare function guardHistoryDiffCommand(from: string, to: string, options?: {
     json?: boolean;
 }): void;

package/dist/cli/commands/guard.js

@@ -7,6 +7,7 @@ import { diffGuardSnapshots, listGuardSnapshots } from '../../core/history/histo
 import { guardAgentTargets, installGuardAgentInstructions, installGuardAgentTargets, } from '../../adapters/agents/agent-integration.js';
 import { dim, fail, heading, info, success, warn } from '../ui.js';
 import { guardFindingsToSarif } from '../../core/output/sarif.js';
+import { analyzeProjectImpact } from '../../core/analysis/impact.js';
 function renderFindings(findings) {
     for (const finding of findings) {
         const printer = finding.severity === 'error' ? fail : finding.severity === 'warning' ? warn : info;
@@ -166,6 +167,26 @@ export function guardHistoryCommand() {
         info(`${snapshot.revision}: ${snapshot.files} files, ${snapshot.modules} modules, ${snapshot.cycles} cycles`);
     }
 }
+export function guardImpactCommand(files, options = {}) {
+    const root = getRoot();
+    if (files.length === 0) {
+        fail('Specify at least one project-relative file.');
+        process.exitCode = 1;
+        return;
+    }
+    const result = analyzeProjectImpact(discoverProject(root), files, loadGuardConfig(root)?.contracts ?? []);
+    if (options.json) {
+        console.log(JSON.stringify({ status: 'ok', ...result }, null, 2));
+        return;
+    }
+    heading('Codapult Guard Impact');
+    info(`Requested: ${result.requestedFiles.join(', ')}`);
+    info(`Direct modules: ${result.directModules.join(', ') || 'none'}`);
+    info(`Dependencies: ${result.dependencies.join(', ') || 'none'}`);
+    info(`Transitive dependents: ${result.dependents.join(', ') || 'none'}`);
+    info(`Capabilities: ${result.capabilities.join(', ') || 'none'}`);
+    info(`Relevant contracts: ${result.relevantContracts.map((contract) => contract.id).join(', ') || 'none'}`);
+}
 export function guardHistoryDiffCommand(from, to, options = {}) {
     const diff = diffGuardSnapshots(getRoot(), from, to);
     if (!diff) {
@@ -181,6 +202,9 @@ export function guardHistoryDiffCommand(from, to, options = {}) {
         info(`Removed files: ${diff.removedFiles.length}`);
         info(`Added dependencies: ${diff.addedDependencies.join(', ') || 'none'}`);
         info(`Removed dependencies: ${diff.removedDependencies.join(', ') || 'none'}`);
+        info(`Modules: +${diff.addedModules.length} / -${diff.removedModules.length}`);
+        info(`Dependency edges: +${diff.addedDependencyEdges.length} / -${diff.removedDependencyEdges.length}`);
+        info(`Layer edges: +${diff.addedLayerEdges.length} / -${diff.removedLayerEdges.length}`);
         info(`Capabilities: +${diff.addedCapabilities.join(', ') || 'none'} / -${diff.removedCapabilities.join(', ') || 'none'}`);
         info(`Cycles: ${diff.cycles.from} → ${diff.cycles.to}`);
     }

package/dist/cli/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { Command } from 'commander';
 import pc from 'picocolors';
-import { guardAnalyzeCommand, guardAuditCommand, guardBaselineCommand, guardCheckCommand, guardContractsApproveCommand, guardContractsRejectCommand, guardDoctorCommand, guardHistoryCommand, guardHistoryDiffCommand, guardInitCommand, guardInstallAgentCommand, guardProposeCommand, guardReviewCommand, guardRulesApproveCommand, guardVerifyCommand, } from './commands/guard.js';
+import { guardAnalyzeCommand, guardAuditCommand, guardBaselineCommand, guardCheckCommand, guardContractsApproveCommand, guardContractsRejectCommand, guardDoctorCommand, guardHistoryCommand, guardHistoryDiffCommand, guardImpactCommand, guardInitCommand, guardInstallAgentCommand, guardProposeCommand, guardReviewCommand, guardRulesApproveCommand, guardVerifyCommand, } from './commands/guard.js';
 import { config } from '../core/config.js';
 const program = new Command()
     .name(config.commandName)
@@ -21,6 +21,7 @@ guard.command('install-agent [target]').option('--json').action(guardInstallAgen
 guard.command('doctor').option('--json').action(guardDoctorCommand);
 guard.command('history').action(guardHistoryCommand);
 guard.command('history-diff <from> <to>').option('--json').action(guardHistoryDiffCommand);
+guard.command('impact <files...>').option('--json').action(guardImpactCommand);
 guard
     .command('check')
     .option('--changed')

package/dist/core/analysis/impact.d.ts

@@ -0,0 +1,22 @@
+import type { GuardContract } from '../guard.js';
+import { type ProjectModel } from '../discovery/discovery.js';
+export interface GuardImpactAnalysis {
+    requestedFiles: string[];
+    directModules: string[];
+    dependencies: string[];
+    dependents: string[];
+    affectedModules: string[];
+    impactPaths: ProjectModel['insights']['impactPaths'];
+    capabilities: string[];
+    relevantContracts: GuardContract[];
+    dependencyEdges: ProjectModel['insights']['dependencyEdges'];
+    layerEdges: ProjectModel['insights']['layerEdges'];
+}
+/**
+ * Computes the blast radius of a change from the discovered graph.
+ *
+ * The graph direction is importer -> imported module. Therefore `dependencies` are what the
+ * changed code relies on, while `dependents` are callers that can regress when the changed
+ * code changes. Both directions matter for an AI review packet.
+ */
+export declare function analyzeProjectImpact(model: ProjectModel, files: Iterable<string>, contracts?: GuardContract[]): GuardImpactAnalysis;

package/dist/core/analysis/impact.js

@@ -0,0 +1,73 @@
+import { buildModuleTargetGraph } from '../discovery/discovery.js';
+function matchesScope(path, scope) {
+    return path === scope || path.startsWith(`${scope.replace(/\\/g, '/')}/`);
+}
+function walk(graph, starts) {
+    const visited = new Set();
+    const queue = [...starts];
+    while (queue.length > 0) {
+        const current = queue.shift();
+        if (!current || visited.has(current))
+            continue;
+        visited.add(current);
+        for (const next of graph.get(current) ?? []) {
+            if (!visited.has(next))
+                queue.push(next);
+        }
+    }
+    return visited;
+}
+/**
+ * Computes the blast radius of a change from the discovered graph.
+ *
+ * The graph direction is importer -> imported module. Therefore `dependencies` are what the
+ * changed code relies on, while `dependents` are callers that can regress when the changed
+ * code changes. Both directions matter for an AI review packet.
+ */
+export function analyzeProjectImpact(model, files, contracts = []) {
+    const requestedFiles = [...new Set([...files].map((file) => file.replace(/\\/g, '/')))].sort();
+    const modulePaths = new Set(model.modules.map((module) => module.path));
+    const directModules = requestedFiles.filter((file) => modulePaths.has(file));
+    const graph = buildModuleTargetGraph(model.modules);
+    const reverse = new Map();
+    for (const [from, targets] of graph) {
+        for (const to of targets) {
+            const callers = reverse.get(to) ?? [];
+            callers.push(from);
+            reverse.set(to, callers);
+        }
+    }
+    const dependencies = walk(graph, directModules);
+    const dependencyList = [...dependencies].filter((path) => !directModules.includes(path)).sort();
+    const dependents = walk(reverse, directModules);
+    const dependentList = [...dependents].filter((path) => !directModules.includes(path)).sort();
+    const affected = new Set([...directModules, ...dependencyList, ...dependentList]);
+    const impactPaths = model.insights.impactPaths.filter((impact) => impact.entrypoint &&
+        (affected.has(impact.entrypoint) || impact.files.some((file) => affected.has(file))));
+    const capabilities = Object.entries(model.capabilities)
+        .filter(([, signal]) => signal.files.some((file) => affected.has(file)))
+        .map(([id]) => id)
+        .sort();
+    const relevantContracts = contracts.filter((contract) => {
+        const scopes = [...(contract.scope ?? []), ...(contract.entrypoints ?? [])];
+        return (scopes.length === 0 ||
+            scopes.some((scope) => [...affected].some((file) => matchesScope(file, scope))));
+    });
+    const dependencyEdges = model.insights.dependencyEdges.filter((edge) => affected.has(edge.from) || affected.has(edge.to));
+    const affectedLayers = new Set(Object.entries(model.insights.layers)
+        .filter(([, paths]) => paths.some((path) => affected.has(path)))
+        .map(([layer]) => layer));
+    const layerEdges = model.insights.layerEdges.filter((edge) => affectedLayers.has(edge.from) || affectedLayers.has(edge.to));
+    return {
+        requestedFiles,
+        directModules,
+        dependencies: dependencyList,
+        dependents: dependentList,
+        affectedModules: [...affected].sort(),
+        impactPaths,
+        capabilities,
+        relevantContracts,
+        dependencyEdges,
+        layerEdges,
+    };
+}

package/dist/core/discovery/discovery.d.ts

@@ -123,6 +123,13 @@ export interface DiscoveryMetrics {
     reusedModules: number;
 }
 export declare function findGuardRoot(from?: string): string;
+/** Build the internal module graph from AST resolution plus conservative fallback resolution.
+ *
+ * TypeScript resolution is authoritative when available, but it is not complete for every
+ * JavaScript/configuration shape. The fallback must be additive: using it only when there are
+ * no resolved imports silently drops unresolved edges from mixed projects.
+ */
+export declare function buildModuleTargetGraph(modules: ModuleRecord[]): Map<string, string[]>;
 export declare function discoverProject(root: string, options?: {
     persistCache?: boolean;
 }): ProjectModel;

package/dist/core/discovery/discovery.js

@@ -337,16 +337,23 @@ function layerForPath(path) {
     }
     return 'other';
 }
-function buildModuleTargetGraph(modules) {
+/** Build the internal module graph from AST resolution plus conservative fallback resolution.
+ *
+ * TypeScript resolution is authoritative when available, but it is not complete for every
+ * JavaScript/configuration shape. The fallback must be additive: using it only when there are
+ * no resolved imports silently drops unresolved edges from mixed projects.
+ */
+export function buildModuleTargetGraph(modules) {
     const moduleSet = new Set(modules.map((candidate) => candidate.path));
-    return new Map(modules.map((module) => [
-        module.path,
-        module.resolvedImports.length > 0
-            ? module.resolvedImports
-            : module.imports
-                .map((importPath) => resolveInternalImport(module.path, importPath, moduleSet))
-                .filter((path) => path !== undefined),
-    ]));
+    return new Map(modules.map((module) => {
+        const targets = new Set(module.resolvedImports.filter((path) => moduleSet.has(path)));
+        for (const importPath of [...module.imports, ...module.dynamicImports]) {
+            const target = resolveInternalImport(module.path, importPath, moduleSet);
+            if (target)
+                targets.add(target);
+        }
+        return [module.path, [...targets].sort()];
+    }));
 }
 function findCycles(modules) {
     const graph = buildModuleTargetGraph(modules);

package/dist/core/guard.d.ts

@@ -1,5 +1,6 @@
 import type { ProjectModel } from './discovery/discovery.js';
 import { discoverProject, discoverProjectWithMetrics, findGuardRoot } from './discovery/discovery.js';
+import { type GuardImpactAnalysis } from './analysis/impact.js';
 export type GuardSeverity = 'error' | 'warning' | 'info';
 export type GuardOutcomeStatus = 'pass' | 'fail' | 'warning' | 'needs-review' | 'not-configured';
 export declare function classifyGuardOutcome(input: {
@@ -91,6 +92,11 @@ export interface GuardFinding {
     message: string;
     fingerprint: string;
 }
+export interface GuardFileChange {
+    path: string;
+    status: 'added' | 'modified' | 'deleted' | 'renamed';
+    previousPath?: string;
+}
 export interface GuardContractIssue {
     contractId: string;
     field: 'scope' | 'reference' | 'definition';
@@ -114,6 +120,7 @@ export interface GuardReviewPacket {
     outcome: GuardOutcomeStatus;
     diffBase?: string;
     changedFiles: string[];
+    changes: GuardFileChange[];
     diff: string;
     truncated: boolean;
     redacted: boolean;
@@ -122,6 +129,7 @@ export interface GuardReviewPacket {
     contracts: GuardContract[];
     requirement?: string;
     deterministicFindings: GuardFinding[];
+    impact: GuardImpactAnalysis;
     reviewInstructions: string[];
 }
 export declare const GUARD_DIR: string;

package/dist/core/guard.js

@@ -1,11 +1,12 @@
 import { execFileSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
 import { existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, renameSync, writeFileSync, } from 'node:fs';
-import { extname, relative, resolve, sep } from 'node:path';
+import { dirname, extname, relative, resolve, sep } from 'node:path';
 import { Project, SyntaxKind } from 'ts-morph';
 import { discoverProject, discoverProjectWithMetrics, findGuardRoot, } from './discovery/discovery.js';
 import { config } from './config.js';
 import { assessGuardPacks, detectGuardPacks } from './analysis/packs.js';
+import { analyzeProjectImpact } from './analysis/impact.js';
 import { guardAgentConfigSchema, guardConfigSchema, guardContractsFileSchema, guardProposalSchema, } from './policy/schemas.js';
 export function classifyGuardOutcome(input) {
     if (input.configured === false)
@@ -715,15 +716,55 @@ function isSafeReviewFile(file) {
         /\.(?:pem|key|p12|pfx)$/i.test(file));
 }
 function isSafeReviewPath(root, file) {
+    const normalizedFile = file.replace(/\\/g, '/');
+    if (normalizedFile.startsWith('/') || normalizedFile.split('/').includes('..'))
+        return false;
     try {
         const projectRoot = `${realpathSync(root)}${sep}`;
-        const target = realpathSync(resolve(root, file));
+        const targetPath = resolve(root, normalizedFile);
+        let target;
+        try {
+            target = realpathSync(targetPath);
+        }
+        catch {
+            // Deleted files have no realpath. Validate their nearest existing parent instead.
+            target = realpathSync(dirname(targetPath));
+        }
         return target === projectRoot.slice(0, -1) || target.startsWith(projectRoot);
     }
     catch {
         return false;
     }
 }
+function parseGitChanges(root, args) {
+    try {
+        return execFileSync('git', ['diff', '--name-status', '-M', ...args], {
+            cwd: root,
+            stdio: 'pipe',
+        })
+            .toString()
+            .trim()
+            .split('\n')
+            .filter(Boolean)
+            .flatMap((line) => {
+            const [rawStatus, first, second] = line.split('\t');
+            if (!rawStatus || !first || !isSafeReviewFile(first) || !isSafeReviewPath(root, first)) {
+                return [];
+            }
+            const status = rawStatus[0];
+            if (status === 'R') {
+                if (!second || !isSafeReviewFile(second) || !isSafeReviewPath(root, second))
+                    return [];
+                return [{ path: second, previousPath: first, status: 'renamed' }];
+            }
+            const mapped = status === 'A' ? 'added' : status === 'D' ? 'deleted' : 'modified';
+            return [{ path: first, status: mapped }];
+        });
+    }
+    catch {
+        return [];
+    }
+}
 /** @internal Redacts common credential shapes before a diff enters an AI review packet. */
 export function redactSensitiveText(value) {
     let redacted = false;
@@ -753,6 +794,7 @@ function reviewDiff(root, maxChars, base) {
                 truncated: false,
                 redacted: false,
                 changedFiles: [],
+                changes: [],
                 error: `Unsafe Git base ref rejected: ${base}`,
             };
         }
@@ -835,6 +877,10 @@ function reviewDiff(root, maxChars, base) {
             truncated: fullDiff.length > maxChars,
             redacted: redactedDiff.redacted || redactedUntracked,
             changedFiles: [...new Set([...trackedFilesForBase, ...trackedFiles, ...untracked])].sort(),
+            changes: [
+                ...parseGitChanges(root, base ? [`${base}...HEAD`] : ['HEAD']),
+                ...untracked.map((path) => ({ path, status: 'added' })),
+            ].filter((change, index, all) => all.findIndex((candidate) => candidate.path === change.path && candidate.previousPath === change.previousPath) === index),
         };
     }
     catch (error) {
@@ -844,6 +890,7 @@ function reviewDiff(root, maxChars, base) {
             truncated: false,
             redacted: false,
             changedFiles: [],
+            changes: [],
             error: base
                 ? `Unable to resolve or read Git base ref: ${base}${detail}`
                 : `Unable to read Git diff.${detail}`,
@@ -886,11 +933,13 @@ export function buildGuardReviewPacket(root, guardConfig, baseline = new Set(),
         baseline,
         includeArchitectureInsights: true,
     });
+    const impact = analyzeProjectImpact(project, diff.changedFiles, guardConfig.contracts ?? []);
     return {
         version: 1,
         outcome: classifyGuardOutcome({ errors: diff.error ? 1 : 0, needsReview: !diff.error }),
         ...(base ? { diffBase: base } : {}),
         changedFiles: diff.changedFiles,
+        changes: diff.changes,
         diff: diff.diff,
         truncated: diff.truncated,
         redacted: diff.redacted,
@@ -899,6 +948,7 @@ export function buildGuardReviewPacket(root, guardConfig, baseline = new Set(),
         contracts: guardConfig.contracts ?? [],
         ...(requirement ? { requirement } : {}),
         deterministicFindings: report.findings,
+        impact,
         reviewInstructions: [
             ...(requirement
                 ? [

package/dist/core/history/history.d.ts

@@ -15,6 +15,12 @@ export interface GuardHistoryDiff {
     removedDependencies: string[];
     addedCapabilities: string[];
     removedCapabilities: string[];
+    addedModules: string[];
+    removedModules: string[];
+    addedDependencyEdges: string[];
+    removedDependencyEdges: string[];
+    addedLayerEdges: string[];
+    removedLayerEdges: string[];
     cycles: {
         from: number;
         to: number;

package/dist/core/history/history.js

@@ -1,6 +1,19 @@
 import { existsSync, readdirSync, readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { GUARD_HISTORY_DIR } from '../guard.js';
+function snapshotInsights(model) {
+    return model.insights ?? {};
+}
+function dependencyEdges(model) {
+    return (snapshotInsights(model).dependencyEdges ?? [])
+        .map((edge) => `${edge.from} -> ${edge.to}`)
+        .sort();
+}
+function layerEdges(model) {
+    return (snapshotInsights(model).layerEdges ?? [])
+        .map((edge) => `${edge.from} -> ${edge.to}`)
+        .sort();
+}
 function readSnapshot(root, revision) {
     if (!/^[A-Za-z0-9._-]+$/.test(revision))
         return undefined;
@@ -29,7 +42,7 @@ export function listGuardSnapshots(root) {
                     files: model.files.length,
                     modules: model.modules.length,
                     capabilities: Object.keys(model.capabilities).sort(),
-                    cycles: model.insights.cycles.length,
+                    cycles: snapshotInsights(model).cycles?.length ?? 0,
                 },
             ]
             : [];
@@ -51,6 +64,8 @@ export function diffGuardSnapshots(root, from, to) {
         ...after.project.dependencies,
         ...after.project.devDependencies,
     });
+    const beforeModules = before.modules.map((module) => module.path);
+    const afterModules = after.modules.map((module) => module.path);
     return {
         from,
         to,
@@ -60,6 +75,15 @@ export function diffGuardSnapshots(root, from, to) {
         removedDependencies: difference(afterDependencies, beforeDependencies),
         addedCapabilities: difference(Object.keys(before.capabilities), Object.keys(after.capabilities)),
         removedCapabilities: difference(Object.keys(after.capabilities), Object.keys(before.capabilities)),
-        cycles: { from: before.insights.cycles.length, to: after.insights.cycles.length },
+        addedModules: difference(beforeModules, afterModules),
+        removedModules: difference(afterModules, beforeModules),
+        addedDependencyEdges: difference(dependencyEdges(before), dependencyEdges(after)),
+        removedDependencyEdges: difference(dependencyEdges(after), dependencyEdges(before)),
+        addedLayerEdges: difference(layerEdges(before), layerEdges(after)),
+        removedLayerEdges: difference(layerEdges(after), layerEdges(before)),
+        cycles: {
+            from: snapshotInsights(before).cycles?.length ?? 0,
+            to: snapshotInsights(after).cycles?.length ?? 0,
+        },
     };
 }

package/dist/index.d.ts

@@ -7,4 +7,5 @@ export * from './core/history/history.js';
 export * from './core/output/sarif.js';
 export * from './core/analysis/doctor.js';
 export * from './core/analysis/packs.js';
+export * from './core/analysis/impact.js';
 export * from './adapters/project-checks.js';

package/dist/index.js

@@ -6,4 +6,5 @@ export * from './core/history/history.js';
 export * from './core/output/sarif.js';
 export * from './core/analysis/doctor.js';
 export * from './core/analysis/packs.js';
+export * from './core/analysis/impact.js';
 export * from './adapters/project-checks.js';

package/dist/mcp/tools/guard.js

@@ -1,4 +1,5 @@
 import { buildArchitectureMemory, buildConventionsMemory, buildGeneratedGuardConfig, buildGuardProposals, buildGuardReviewPacket, discoverProject, discoverProjectWithMetrics, findGuardRoot, GUARD_ARCHITECTURE_FILE, GUARD_CONVENTIONS_FILE, loadBaseline, loadGuardArtifact, loadGuardConfig, loadGuardAgentConfig, loadGuardProposals, getGuardProposalFreshness, loadProjectModel, writeGuardProposals, initializeGuard, GuardAlreadyInitializedError, recordGuardProposalDecision, writeGuardConfig, scanGuard, validateGuardContracts, classifyGuardOutcome, } from '../../core/guard.js';
+import { analyzeProjectImpact } from '../../core/analysis/impact.js';
 import { z } from 'zod';
 import { runGuardVerification } from '../../core/verification/verify.js';
 const rootSchema = z.string().trim().min(1).optional().describe('Project path or workspace root.');
@@ -330,20 +331,10 @@ export function registerGuardTools(server) {
     }, ({ root: requestedRoot, files }) => {
         const root = getGuardRoot(requestedRoot);
         const model = discoverProject(root);
-        const changed = new Set(files);
-        const paths = model.insights.impactPaths.filter((impact) => impact.files.some((file) => changed.has(file)) || changed.has(impact.entrypoint));
-        const modules = model.modules.filter((module) => changed.has(module.path) || module.resolvedImports.some((file) => changed.has(file)));
-        const capabilities = Object.entries(model.capabilities)
-            .filter(([, signal]) => signal.files.some((file) => changed.has(file)))
-            .map(([id]) => id);
-        const contracts = (loadGuardConfig(root)?.contracts ?? []).filter((contract) => [...(contract.scope ?? []), ...(contract.entrypoints ?? [])].some((scope) => [...changed].some((file) => file === scope || file.startsWith(`${scope}/`))));
+        const impact = analyzeProjectImpact(model, files, loadGuardConfig(root)?.contracts ?? []);
         return jsonToolResult({
             status: 'ok',
-            files,
-            affectedModules: modules.map((module) => module.path),
-            impactPaths: paths,
-            capabilities,
-            relevantContracts: contracts,
+            ...impact,
         });
     });
     server.registerTool('codapult_guard_explain', {

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@codapult/guard",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Local-first architecture guardrails for JavaScript and TypeScript projects, with first-class support for Next.js SaaS and AI-assisted development",
   "license": "MIT",
-  "packageManager": "pnpm@11.22.0+sha512.1ff870c4c6133dfd88fb2afc46dd13d47f09c9794b438c6fdb47ca98caf3bc16381ee0be93a091b8e3824cf01f889f46d7d9e20910fb0be1ab0fb5baa80dd621",
+  "packageManager": "pnpm@12.4.2+sha512.08adc6613180275c7c9edada39dcf08c9c61ad4e7eaf330a4f3461f102b0f907423454d117f98e72d47fef0616070644d7bffc973a6a57f5090a6d7c368b07c9",
   "engines": {
     "node": ">=20.19.0"
   },
@@ -95,23 +95,23 @@
     "semver": "^7.8.5",
     "ts-morph": "^28.0.0",
     "typescript": "npm:@typescript/typescript6@^6.0.2",
-    "zod": "^4.4.3"
+    "zod": "^4.6.5"
   },
   "devDependencies": {
     "@js-toolkit/config-utils": "^1.0.1",
-    "@js-toolkit/eslint-config": "^1.1.4",
+    "@js-toolkit/eslint-config": "^1.3.0",
     "@js-toolkit/prettier-config": "^1.0.1",
     "@js-toolkit/tsconfig": "^1.0.1",
-    "@release-it/conventional-changelog": "^12.0.0",
-    "@types/node": "^26.2.0",
+    "@release-it/conventional-changelog": "^12.0.2",
+    "@types/node": "^26.6.1",
     "@typescript/native": "npm:typescript@^7.0.2",
-    "@vitest/coverage-v8": "^4.1.11",
-    "eslint": "^9.39.4",
+    "@vitest/coverage-v8": "^5.0.1",
+    "eslint": "^10.10.0",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-prettier": "^5.5.6",
-    "prettier": "^3.9.6",
-    "release-it": "^21.0.2",
-    "typescript-eslint": "^8.67.0",
-    "vitest": "^4.1.11"
+    "prettier": "^3.9.7",
+    "release-it": "^21.0.3",
+    "typescript-eslint": "^8.70.0",
+    "vitest": "^5.0.1"
   }
 }