@codapult/guard 0.1.0 → 0.3.0

package/dist/core/guard.js

@@ -1,11 +1,13 @@
 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 { createHash, randomUUID } from 'node:crypto';
+import { existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, renameSync, statSync, unlinkSync, writeFileSync, } from 'node:fs';
+import { dirname, extname, relative, resolve, sep } from 'node:path';
 import { Project, SyntaxKind } from 'ts-morph';
-import { discoverProject, discoverProjectWithMetrics, findGuardRoot, } from './discovery/discovery.js';
+import { buildModuleTargetGraph } from './discovery/discovery.js';
+import { clearDiscoveryCache, 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)
@@ -49,6 +51,18 @@ export class GuardAlreadyInitializedError extends Error {
         this.name = 'GuardAlreadyInitializedError';
     }
 }
+export class GuardConfigError extends Error {
+    constructor(path) {
+        super(`Guard configuration is invalid or unsupported: ${path}`);
+        this.name = 'GuardConfigError';
+    }
+}
+export class GuardStateBusyError extends Error {
+    constructor(path) {
+        super(`Guard state is being updated by another process: ${path}`);
+        this.name = 'GuardStateBusyError';
+    }
+}
 function isGuardConfig(value) {
     return guardConfigSchema.safeParse(value).success;
 }
@@ -61,9 +75,37 @@ function readJson(filePath) {
     }
 }
 function atomicWriteFile(path, content) {
-    const temporaryPath = `${path}.tmp-${process.pid}`;
-    writeFileSync(temporaryPath, content, 'utf8');
-    renameSync(temporaryPath, path);
+    const lockPath = `${path}.lock`;
+    let lockAcquired = false;
+    try {
+        try {
+            writeFileSync(lockPath, `${process.pid}\n`, { encoding: 'utf8', flag: 'wx' });
+            lockAcquired = true;
+        }
+        catch (error) {
+            if (error.code === 'EEXIST') {
+                try {
+                    if (Date.now() - statSync(lockPath).mtimeMs > 60_000) {
+                        unlinkSync(lockPath);
+                        writeFileSync(lockPath, `${process.pid}\n`, { encoding: 'utf8', flag: 'wx' });
+                        lockAcquired = true;
+                    }
+                }
+                catch {
+                    // Another writer may have replaced or removed the lock.
+                }
+            }
+            if (!lockAcquired)
+                throw new GuardStateBusyError(path);
+        }
+        const temporaryPath = `${path}.tmp-${process.pid}-${randomUUID()}`;
+        writeFileSync(temporaryPath, content, 'utf8');
+        renameSync(temporaryPath, path);
+    }
+    finally {
+        if (lockAcquired)
+            unlinkSync(lockPath);
+    }
 }
 function writeGuardArtifact(root, relativePath, value) {
     mkdirSync(resolve(root, GUARD_DIR), { recursive: true });
@@ -107,14 +149,17 @@ export function getGuardProposalFreshness(model, proposals) {
     return proposals.projectFingerprint === fingerprintProjectModel(model) ? 'current' : 'stale';
 }
 export function loadGuardConfig(root) {
-    const value = readJson(resolve(root, GUARD_RULES_FILE));
-    if (!isGuardConfig(value))
+    const rulesPath = resolve(root, GUARD_RULES_FILE);
+    if (!existsSync(rulesPath))
         return undefined;
+    const value = readJson(rulesPath);
+    if (!isGuardConfig(value))
+        throw new GuardConfigError(GUARD_RULES_FILE);
     const contractsPath = resolve(root, GUARD_CONTRACTS_FILE);
     if (existsSync(contractsPath)) {
         const contractFile = readJson(contractsPath);
         if (!isGuardContractsFile(contractFile))
-            return undefined;
+            throw new GuardConfigError(GUARD_CONTRACTS_FILE);
         return { ...value, contracts: contractFile.contracts };
     }
     return {
@@ -136,9 +181,6 @@ export function loadGuardAgentConfig(root) {
 export function writeGuardAgentConfig(root, agentConfig = defaultGuardAgentConfig) {
     writeGuardArtifact(root, GUARD_AGENT_FILE, agentConfig);
 }
-export function loadGuardArtifact(root, relativePath) {
-    return readJson(resolve(root, relativePath));
-}
 export function loadBaseline(root) {
     const value = readJson(resolve(root, GUARD_BASELINE_FILE));
     if (!Array.isArray(value))
@@ -201,6 +243,31 @@ export function recordGuardProposalDecision(root, decisions) {
         decisions: [...(proposals.decisions ?? []), ...nextDecisions],
     });
 }
+export function getPendingGuardProposals(proposals) {
+    if (!proposals)
+        return [];
+    const decisions = new Map();
+    for (const decision of proposals.decisions ?? []) {
+        const current = decisions.get(`${decision.type}:${decision.id}`);
+        if (!current || decision.decidedAt >= current.decidedAt) {
+            decisions.set(`${decision.type}:${decision.id}`, decision);
+        }
+    }
+    const matchesCurrentProposal = (decision) => decision !== undefined &&
+        (proposals.proposalId === undefined || decision.proposalId === proposals.proposalId) &&
+        (proposals.contentFingerprint === undefined ||
+            decision.proposalFingerprint === proposals.contentFingerprint) &&
+        (proposals.revision === undefined || decision.revision === proposals.revision);
+    return [
+        ...proposals.rules
+            .filter((rule) => rule.status === 'proposed' && !matchesCurrentProposal(decisions.get(`rule:${rule.id}`)))
+            .map((rule) => ({ id: rule.id, type: 'rule' })),
+        ...proposals.contracts
+            .filter((contract) => contract.status === 'proposed' &&
+            !matchesCurrentProposal(decisions.get(`contract:${contract.id}`)))
+            .map((contract) => ({ id: contract.id, type: 'contract' })),
+    ];
+}
 export function buildGuardProposals(model, guardConfig) {
     const capabilities = Object.keys(model.capabilities);
     const questions = [];
@@ -346,14 +413,19 @@ export function buildConventionsMemory(model) {
 }
 export function buildGeneratedGuardConfig(model) {
     const isPersistenceImport = (importPath) => /(?:^|\/)(?:database|db)(?:\/|$)/i.test(importPath) ||
-        /^(?:@prisma\codapult-guardent|prisma|drizzle-orm|drizzle-kit|typeorm|sequelize|mongoose|knex)(?:\/|$)/i.test(importPath);
+        /^(?:@prisma\/client|prisma|drizzle-orm|drizzle-kit|typeorm|sequelize|mongoose|knex)(?:\/|$)/i.test(importPath);
+    const moduleReferences = (module) => [
+        ...module.imports,
+        ...module.exports,
+        ...module.dynamicImports,
+    ];
     const persistenceImports = [
-        ...new Set(model.modules.flatMap((module) => module.imports).filter(isPersistenceImport)),
+        ...new Set(model.modules.flatMap((module) => moduleReferences(module)).filter(isPersistenceImport)),
     ].sort();
     const clientPersistenceFiles = model.insights.boundaries
         .find((boundary) => boundary.kind === 'client')
         ?.files.filter((file) => model.modules.some((module) => module.path === file &&
-        module.imports.some((importPath) => persistenceImports.includes(importPath)))) ?? [];
+        moduleReferences(module).some((importPath) => persistenceImports.includes(importPath)))) ?? [];
     const proposedRules = clientPersistenceFiles.length > 0
         ? [
             {
@@ -423,6 +495,32 @@ export function writeProjectSnapshot(root, model) {
     atomicWriteFile(resolve(root, GUARD_HISTORY_DIR, `${revision}.json`), `${JSON.stringify(model, null, 2)}\n`);
     return revision;
 }
+function isProjectPath(root, value) {
+    const normalized = value.replace(/\\/g, '/');
+    if (!normalized || normalized.startsWith('/') || normalized.split('/').includes('..')) {
+        return false;
+    }
+    try {
+        const projectRoot = `${realpathSync(root)}${sep}`;
+        const targetPath = resolve(root, normalized);
+        let target;
+        try {
+            target = realpathSync(targetPath);
+        }
+        catch {
+            target = realpathSync(dirname(targetPath));
+        }
+        return target === projectRoot.slice(0, -1) || target.startsWith(projectRoot);
+    }
+    catch {
+        return false;
+    }
+}
+export function loadGuardArtifact(root, relativePath) {
+    if (!isProjectPath(root, relativePath))
+        return undefined;
+    return readJson(resolve(root, relativePath));
+}
 export function validateGuardContracts(root, contracts = []) {
     const issues = [];
     for (const contract of contracts) {
@@ -444,8 +542,18 @@ export function validateGuardContracts(root, contracts = []) {
                 message: 'Required-call contracts need at least one mustCall pattern.',
             });
         }
+        if (contract.kind === 'package-boundary' &&
+            ((contract.fromPackages?.length ?? 0) === 0 ||
+                (contract.mustNotImportPackages?.length ?? 0) === 0)) {
+            issues.push({
+                contractId: contract.id,
+                field: 'definition',
+                value: contract.kind,
+                message: 'Package-boundary contracts need fromPackages and mustNotImportPackages patterns.',
+            });
+        }
         for (const scope of contract.scope ?? []) {
-            if (!existsSync(resolve(root, scope))) {
+            if (!isProjectPath(root, scope) || !existsSync(resolve(root, scope))) {
                 issues.push({
                     contractId: contract.id,
                     field: 'scope',
@@ -455,7 +563,7 @@ export function validateGuardContracts(root, contracts = []) {
             }
         }
         for (const entrypoint of contract.entrypoints ?? []) {
-            if (!existsSync(resolve(root, entrypoint))) {
+            if (!isProjectPath(root, entrypoint) || !existsSync(resolve(root, entrypoint))) {
                 issues.push({
                     contractId: contract.id,
                     field: 'scope',
@@ -465,7 +573,7 @@ export function validateGuardContracts(root, contracts = []) {
             }
         }
         for (const excluded of contract.exclude ?? []) {
-            if (!existsSync(resolve(root, excluded))) {
+            if (!isProjectPath(root, excluded) || !existsSync(resolve(root, excluded))) {
                 issues.push({
                     contractId: contract.id,
                     field: 'scope',
@@ -475,7 +583,7 @@ export function validateGuardContracts(root, contracts = []) {
             }
         }
         for (const reference of contract.references ?? []) {
-            if (!existsSync(resolve(root, reference))) {
+            if (!isProjectPath(root, reference) || !existsSync(resolve(root, reference))) {
                 issues.push({
                     contractId: contract.id,
                     field: 'reference',
@@ -540,6 +648,32 @@ function importLine(sourceFile, importPath) {
     });
     return dynamicImport?.getStartLineNumber() ?? 1;
 }
+function moduleImportReferences(module) {
+    const sources = [...new Set([...module.imports, ...module.exports, ...module.dynamicImports])];
+    return sources.map((source) => ({ source, resolved: module.resolvedImportMap?.[source] }));
+}
+function packageSelectorMatches(value, selector) {
+    if (!value)
+        return false;
+    return selector.endsWith('*') ? value.startsWith(selector.slice(0, -1)) : value === selector;
+}
+function packageForFile(model, file) {
+    const packageInfo = model.project.workspacePackages
+        .filter((workspace) => workspace.path === '.' ||
+        file === `${workspace.path}/package.json` ||
+        file.startsWith(`${workspace.path}/`))
+        .sort((left, right) => right.path.length - left.path.length)[0] ?? null;
+    return packageInfo === null ? undefined : (packageInfo.name ?? packageInfo.path);
+}
+function packageForImport(model, reference) {
+    const resolvedPackage = reference.resolved
+        ? packageForFile(model, reference.resolved)
+        : undefined;
+    if (resolvedPackage)
+        return resolvedPackage;
+    return model.project.workspacePackages.find((workspace) => workspace.name === reference.source ||
+        (workspace.name !== undefined && reference.source.startsWith(`${workspace.name}/`)))?.name;
+}
 function scanFile(root, file, rules, module, astProject) {
     if (!module)
         return [];
@@ -554,26 +688,25 @@ function scanFile(root, file, rules, module, astProject) {
         }
     }
     const findings = [];
-    const importPaths = [
-        ...new Set([...module.imports, ...module.exports, ...module.dynamicImports]),
-    ];
-    for (const importPath of importPaths) {
-        const line = sourceFile ? importLine(sourceFile, importPath) : 1;
+    for (const reference of moduleImportReferences(module)) {
+        const line = sourceFile ? importLine(sourceFile, reference.source) : 1;
         for (const rule of rules) {
             if (rule.status === 'proposed' || !ruleAppliesToFile(rule, file))
                 continue;
             if (rule.kind === 'client-forbidden-import' && !isClient)
                 continue;
-            if (!rule.patterns.some((pattern) => patternMatches(importPath, pattern)))
+            if (!rule.patterns.some((pattern) => patternMatches(reference.source, pattern) ||
+                (reference.resolved !== undefined && patternMatches(reference.resolved, pattern))))
                 continue;
             findings.push({
                 ruleId: rule.id,
                 severity: rule.severity,
                 file,
                 line,
-                importPath,
+                importPath: reference.source,
+                ...(reference.resolved ? { resolvedPath: reference.resolved } : {}),
                 message: rule.description,
-                fingerprint: `${rule.id}|${file}|${importPath}`,
+                fingerprint: `${rule.id}|${file}|${reference.source}|${reference.resolved ?? ''}`,
             });
         }
     }
@@ -588,22 +721,25 @@ function scanContracts(root, contracts, changed) {
         const severity = contract.severity ?? 'error';
         for (const module of model.modules.filter((item) => (!changed || changed.has(item.path)) && contractAppliesToFile(contract, item.path))) {
             if (contract.kind === 'import-boundary') {
-                for (const importPath of module.imports) {
-                    if (contract.mustNotImport?.some((pattern) => patternMatches(importPath, pattern))) {
+                for (const reference of moduleImportReferences(module)) {
+                    if (contract.mustNotImport?.some((pattern) => patternMatches(reference.source, pattern) ||
+                        (reference.resolved !== undefined && patternMatches(reference.resolved, pattern)))) {
                         findings.push({
                             ruleId: `contract:${contract.id}`,
                             severity,
                             file: module.path,
                             line: 1,
-                            importPath,
+                            importPath: reference.source,
+                            ...(reference.resolved ? { resolvedPath: reference.resolved } : {}),
                             message: contract.statement,
-                            fingerprint: `contract-import|${contract.id}|${module.path}|${importPath}`,
+                            fingerprint: `contract-import|${contract.id}|${module.path}|${reference.source}|${reference.resolved ?? ''}`,
                         });
                     }
                 }
                 if (contract.mustImport !== undefined &&
                     contract.mustImport.length > 0 &&
-                    !module.imports.some((importPath) => contract.mustImport?.some((pattern) => patternMatches(importPath, pattern)))) {
+                    !moduleImportReferences(module).some((reference) => contract.mustImport?.some((pattern) => patternMatches(reference.source, pattern) ||
+                        (reference.resolved !== undefined && patternMatches(reference.resolved, pattern))))) {
                     findings.push({
                         ruleId: `contract:${contract.id}`,
                         severity,
@@ -629,6 +765,28 @@ function scanContracts(root, contracts, changed) {
                     fingerprint: `contract-required-call|${contract.id}|${module.path}`,
                 });
             }
+            if (contract.kind === 'package-boundary') {
+                const sourcePackage = packageForFile(model, module.path);
+                if (!contract.fromPackages?.some((selector) => packageSelectorMatches(sourcePackage, selector))) {
+                    continue;
+                }
+                for (const reference of moduleImportReferences(module)) {
+                    const targetPackage = packageForImport(model, reference);
+                    if (!contract.mustNotImportPackages?.some((selector) => packageSelectorMatches(targetPackage, selector))) {
+                        continue;
+                    }
+                    findings.push({
+                        ruleId: `contract:${contract.id}`,
+                        severity,
+                        file: module.path,
+                        line: 1,
+                        importPath: reference.source,
+                        ...(reference.resolved ? { resolvedPath: reference.resolved } : {}),
+                        message: contract.statement,
+                        fingerprint: `contract-package|${contract.id}|${module.path}|${reference.source}|${targetPackage ?? ''}`,
+                    });
+                }
+            }
         }
     }
     return findings;
@@ -656,6 +814,30 @@ function changedFiles(root) {
         return undefined;
     }
 }
+function changedImpactScope(model, changed) {
+    if (!changed)
+        return undefined;
+    const graph = buildModuleTargetGraph(model.modules);
+    const reverse = new Map();
+    for (const [from, targets] of graph) {
+        for (const target of targets)
+            reverse.set(target, [...(reverse.get(target) ?? []), from]);
+    }
+    const scope = new Set(changed);
+    const queue = [...changed];
+    while (queue.length > 0) {
+        const current = queue.shift();
+        if (!current)
+            continue;
+        for (const dependent of reverse.get(current) ?? []) {
+            if (!scope.has(dependent)) {
+                scope.add(dependent);
+                queue.push(dependent);
+            }
+        }
+    }
+    return scope;
+}
 function architectureInsightFindings(root, changed) {
     const model = discoverProject(root);
     const findings = model.insights.cycles
@@ -676,7 +858,9 @@ function architectureInsightFindings(root, changed) {
     for (const module of model.modules) {
         if (!clientFiles.has(module.path))
             continue;
-        for (const importPath of module.imports.filter((value) => serverOnlyImports.test(value))) {
+        for (const importPath of [
+            ...new Set([...module.imports, ...module.exports, ...module.dynamicImports]),
+        ].filter((value) => serverOnlyImports.test(value))) {
             if (changed && !changed.has(module.path))
                 continue;
             findings.push({
@@ -715,13 +899,35 @@ function isSafeReviewFile(file) {
         /\.(?:pem|key|p12|pfx)$/i.test(file));
 }
 function isSafeReviewPath(root, file) {
+    return isProjectPath(root, file);
+}
+function parseGitChanges(root, args) {
     try {
-        const projectRoot = `${realpathSync(root)}${sep}`;
-        const target = realpathSync(resolve(root, file));
-        return target === projectRoot.slice(0, -1) || target.startsWith(projectRoot);
+        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 false;
+        return [];
     }
 }
 /** @internal Redacts common credential shapes before a diff enters an AI review packet. */
@@ -739,6 +945,9 @@ export function redactSensitiveText(value) {
     };
     replace(/-----BEGIN [A-Z ]+-----[\s\S]*?-----END [A-Z ]+-----/g, '[REDACTED PRIVATE KEY]');
     replace(/\b(?:sk_(?:live|test)_|pk_(?:live|test)_|AKIA|gh[pousr]_|github_pat_)[A-Za-z0-9_-]+/g, '[REDACTED TOKEN]');
+    replace(/\beyJ[A-Za-z0-9_-]{20,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b/g, '[REDACTED JWT]');
+    replace(/\bhttps?:\/\/[^\s/@:]+:[^\s/@]+@/gi, '[REDACTED URL CREDENTIALS]@');
+    replace(/\b(?:AIza[0-9A-Za-z_-]{20,}|xox[baprs]-[0-9A-Za-z-]{10,})\b/g, '[REDACTED TOKEN]');
     replace(/((?:api[_-]?key|secret|token|password|authorization|database[_-]?url)\s*[:=]\s*["']?)[^\s"'`,}]+/gi, '$1[REDACTED]');
     return { value: redactedValue, redacted, redactionCount };
 }
@@ -753,6 +962,7 @@ function reviewDiff(root, maxChars, base) {
                 truncated: false,
                 redacted: false,
                 changedFiles: [],
+                changes: [],
                 error: `Unsafe Git base ref rejected: ${base}`,
             };
         }
@@ -835,6 +1045,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 +1058,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}`,
@@ -851,9 +1066,10 @@ function reviewDiff(root, maxChars, base) {
     }
 }
 export function scanGuard(root, guardConfig, options = {}) {
-    const changed = options.changedOnly ? (options.changedFiles ?? changedFiles(root)) : undefined;
-    const files = listSourceFiles(root).filter((file) => !changed || changed.has(file));
     const model = discoverProject(root);
+    const changed = options.changedOnly ? (options.changedFiles ?? changedFiles(root)) : undefined;
+    const scope = changedImpactScope(model, changed);
+    const files = listSourceFiles(root).filter((file) => !scope || scope.has(file));
     const modules = new Map(model.modules.map((module) => [module.path, module]));
     const astProject = (() => {
         try {
@@ -865,8 +1081,8 @@ export function scanGuard(root, guardConfig, options = {}) {
     })();
     const allFindings = [
         ...files.flatMap((file) => scanFile(root, file, guardConfig.rules, modules.get(file), astProject)),
-        ...scanContracts(root, guardConfig.contracts ?? [], changed),
-        ...(options.includeArchitectureInsights ? architectureInsightFindings(root, changed) : []),
+        ...scanContracts(root, guardConfig.contracts ?? [], scope),
+        ...(options.includeArchitectureInsights ? architectureInsightFindings(root, scope) : []),
     ];
     const baseline = options.baseline ?? new Set();
     const findings = allFindings.filter((finding) => !baseline.has(finding.fingerprint));
@@ -886,11 +1102,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 +1117,7 @@ export function buildGuardReviewPacket(root, guardConfig, baseline = new Set(),
         contracts: guardConfig.contracts ?? [],
         ...(requirement ? { requirement } : {}),
         deterministicFindings: report.findings,
+        impact,
         reviewInstructions: [
             ...(requirement
                 ? [
@@ -933,4 +1152,4 @@ export function initializeGuard(root, options = {}) {
     writeBaseline(root, initialReport.findings, projectModel);
     return { config: guardConfig, report: { ...initialReport, findings: [] } };
 }
-export { discoverProject, discoverProjectWithMetrics, findGuardRoot };
+export { clearDiscoveryCache, discoverProject, discoverProjectWithMetrics, findGuardRoot };

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/core/policy/schemas.d.ts

@@ -30,6 +30,7 @@ export declare const guardContractSchema: z.ZodObject<{
     kind: z.ZodOptional<z.ZodEnum<{
         guidance: "guidance";
         "import-boundary": "import-boundary";
+        "package-boundary": "package-boundary";
         "required-call": "required-call";
     }>>;
     severity: z.ZodOptional<z.ZodEnum<{
@@ -45,6 +46,8 @@ export declare const guardContractSchema: z.ZodObject<{
     mustImport: z.ZodOptional<z.ZodArray<z.ZodString>>;
     mustNotImport: z.ZodOptional<z.ZodArray<z.ZodString>>;
     mustCall: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    fromPackages: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    mustNotImportPackages: z.ZodOptional<z.ZodArray<z.ZodString>>;
     status: z.ZodOptional<z.ZodEnum<{
         active: "active";
         proposed: "proposed";
@@ -89,6 +92,7 @@ export declare const guardConfigSchema: z.ZodObject<{
         kind: z.ZodOptional<z.ZodEnum<{
             guidance: "guidance";
             "import-boundary": "import-boundary";
+            "package-boundary": "package-boundary";
             "required-call": "required-call";
         }>>;
         severity: z.ZodOptional<z.ZodEnum<{
@@ -104,6 +108,8 @@ export declare const guardConfigSchema: z.ZodObject<{
         mustImport: z.ZodOptional<z.ZodArray<z.ZodString>>;
         mustNotImport: z.ZodOptional<z.ZodArray<z.ZodString>>;
         mustCall: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        fromPackages: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        mustNotImportPackages: z.ZodOptional<z.ZodArray<z.ZodString>>;
         status: z.ZodOptional<z.ZodEnum<{
             active: "active";
             proposed: "proposed";
@@ -124,6 +130,7 @@ export declare const guardContractsFileSchema: z.ZodObject<{
         kind: z.ZodOptional<z.ZodEnum<{
             guidance: "guidance";
             "import-boundary": "import-boundary";
+            "package-boundary": "package-boundary";
             "required-call": "required-call";
         }>>;
         severity: z.ZodOptional<z.ZodEnum<{
@@ -139,6 +146,8 @@ export declare const guardContractsFileSchema: z.ZodObject<{
         mustImport: z.ZodOptional<z.ZodArray<z.ZodString>>;
         mustNotImport: z.ZodOptional<z.ZodArray<z.ZodString>>;
         mustCall: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        fromPackages: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        mustNotImportPackages: z.ZodOptional<z.ZodArray<z.ZodString>>;
         status: z.ZodOptional<z.ZodEnum<{
             active: "active";
             proposed: "proposed";
@@ -204,6 +213,7 @@ export declare const guardProposalSchema: z.ZodObject<{
         kind: z.ZodOptional<z.ZodEnum<{
             guidance: "guidance";
             "import-boundary": "import-boundary";
+            "package-boundary": "package-boundary";
             "required-call": "required-call";
         }>>;
         severity: z.ZodOptional<z.ZodEnum<{
@@ -219,6 +229,8 @@ export declare const guardProposalSchema: z.ZodObject<{
         mustImport: z.ZodOptional<z.ZodArray<z.ZodString>>;
         mustNotImport: z.ZodOptional<z.ZodArray<z.ZodString>>;
         mustCall: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        fromPackages: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        mustNotImportPackages: z.ZodOptional<z.ZodArray<z.ZodString>>;
         status: z.ZodOptional<z.ZodEnum<{
             active: "active";
             proposed: "proposed";