@codapult/guard 0.1.0 → 0.3.0

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

@@ -11,6 +11,7 @@ export interface ModuleRecord {
     exports: string[];
     calls: string[];
     resolvedImports: string[];
+    resolvedImportMap?: Record<string, string>;
     dynamicImports: string[];
     declarations: {
         classes: number;
@@ -44,6 +45,8 @@ export interface ProjectModel {
             private: boolean;
             scripts: Record<string, string>;
             dependencies: string[];
+            exports?: string[];
+            projectReferences?: string[];
         }[];
     };
     files: ProjectFileRecord[];
@@ -122,13 +125,27 @@ export interface DiscoveryMetrics {
     changedFiles: number;
     reusedModules: number;
 }
-export declare function findGuardRoot(from?: string): string;
-export declare function discoverProject(root: string, options?: {
-    persistCache?: boolean;
-}): ProjectModel;
-export declare function discoverProjectWithMetrics(root: string, options?: {
+export interface DiscoveryOptions {
     persistCache?: boolean;
-}): {
+    /** Maximum number of files included in one model. */
+    maxFiles?: number;
+    /** Maximum size of one included file in bytes. */
+    maxFileBytes?: number;
+}
+export declare class DiscoveryLimitError extends Error {
+    constructor(message: string);
+}
+export declare function clearDiscoveryCache(root: string): void;
+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?: DiscoveryOptions): ProjectModel;
+export declare function discoverProjectWithMetrics(root: string, options?: DiscoveryOptions): {
     model: ProjectModel;
     metrics: DiscoveryMetrics;
 };

package/dist/core/discovery/discovery.js

@@ -1,9 +1,17 @@
 import { execFileSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
-import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, statSync, writeFileSync, } from 'node:fs';
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, renameSync, statSync, writeFileSync, } from 'node:fs';
 import { basename, dirname, extname, join, normalize, relative, resolve } from 'node:path';
 import { Project, SyntaxKind } from 'ts-morph';
 import { config } from '../config.js';
+export class DiscoveryLimitError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'DiscoveryLimitError';
+    }
+}
+const DEFAULT_MAX_FILES = 100_000;
+const DEFAULT_MAX_FILE_BYTES = 25 * 1024 * 1024;
 const IGNORED_DIRECTORIES = new Set([
     '.git',
     '.next',
@@ -40,12 +48,16 @@ const CONFIG_NAMES = new Set([
 ]);
 const discoveryCache = new Map();
 const discoveryReuse = new Map();
+const discoveryCacheHits = new Map();
 // Bump when the persisted model shape changes; old cache entries must never
 // bypass discovery and return an incomplete ProjectModel.
 const DISCOVERY_CACHE_VERSION = 3;
 function discoveryCachePath(root) {
     return resolve(root, `.${config.appName}/guard/cache.json`);
 }
+export function clearDiscoveryCache(root) {
+    rmSync(discoveryCachePath(root), { force: true });
+}
 function contentHash(root, path) {
     return createHash('sha256')
         .update(readFileSync(resolve(root, path)))
@@ -121,20 +133,45 @@ function workspacePackages(root, files) {
                 ...asStringRecord(manifest.devDependencies),
                 ...asStringRecord(manifest.peerDependencies),
             }).sort(),
+            ...(manifest.exports !== undefined
+                ? {
+                    exports: Array.isArray(manifest.exports)
+                        ? manifest.exports.filter((item) => typeof item === 'string')
+                        : manifest.exports !== null && typeof manifest.exports === 'object'
+                            ? Object.keys(manifest.exports)
+                            : [],
+                }
+                : {}),
+            ...(Array.isArray(readJsonObject(resolve(root, dirname(path), 'tsconfig.json')).references)
+                ? {
+                    projectReferences: readJsonObject(resolve(root, dirname(path), 'tsconfig.json'))
+                        .references
+                        .filter((reference) => reference !== null &&
+                        typeof reference === 'object' &&
+                        typeof reference.path === 'string')
+                        .map((reference) => reference.path)
+                        .sort(),
+                }
+                : {}),
         };
     })
         .sort((left, right) => left.path.localeCompare(right.path));
 }
-function listFiles(root, directory = root) {
+function listFiles(root, directory = root, maxFiles = DEFAULT_MAX_FILES) {
     const result = [];
     for (const entry of readdirSync(directory, { withFileTypes: true })) {
         if (entry.isDirectory() && IGNORED_DIRECTORIES.has(entry.name))
             continue;
         const path = resolve(directory, entry.name);
         if (entry.isDirectory())
-            result.push(...listFiles(root, path));
-        else if (entry.isFile() && !ignoredFile(path))
+            result.push(...listFiles(root, path, maxFiles - result.length));
+        else if (entry.isFile() && !ignoredFile(path)) {
             result.push(relative(root, path));
+            if (result.length > maxFiles) {
+                throw new DiscoveryLimitError(`Project contains more than ${maxFiles} files; discovery limit was reached. ` +
+                    'Use an ignore file or raise maxFiles deliberately.');
+            }
+        }
     }
     return result.sort();
 }
@@ -169,7 +206,54 @@ function resolveInternalImport(from, importPath, modules) {
     ];
     return candidates.find((candidate) => modules.has(candidate));
 }
-function parseModule(project, root, path, projectFiles) {
+function pathAliases(root) {
+    return listFiles(root)
+        .filter((path) => basename(path) === 'tsconfig.json' || basename(path) === 'jsconfig.json')
+        .flatMap((path) => {
+        const tsconfigJson = readJsonObject(resolve(root, path));
+        const compilerOptions = tsconfigJson.compilerOptions !== null && typeof tsconfigJson.compilerOptions === 'object'
+            ? tsconfigJson.compilerOptions
+            : {};
+        const paths = compilerOptions.paths;
+        if (paths === null || typeof paths !== 'object')
+            return [];
+        const baseUrl = typeof compilerOptions.baseUrl === 'string' ? compilerOptions.baseUrl : '.';
+        return Object.entries(paths).flatMap(([pattern, value]) => {
+            if (!Array.isArray(value))
+                return [];
+            const targets = value.filter((item) => typeof item === 'string');
+            return targets.length > 0
+                ? [{ pattern, baseDirectory: resolve(root, dirname(path), baseUrl), targets }]
+                : [];
+        });
+    });
+}
+function resolveAliasedImport(root, importPath, aliases, modules) {
+    for (const alias of aliases) {
+        const wildcard = alias.pattern.indexOf('*');
+        const prefix = wildcard >= 0 ? alias.pattern.slice(0, wildcard) : alias.pattern;
+        const suffix = wildcard >= 0 ? alias.pattern.slice(wildcard + 1) : '';
+        if (!importPath.startsWith(prefix) || (suffix && !importPath.endsWith(suffix)))
+            continue;
+        const replacement = importPath.slice(prefix.length, importPath.length - suffix.length);
+        for (const target of alias.targets) {
+            const targetPath = target.replace('*', replacement);
+            const absoluteBase = resolve(alias.baseDirectory, targetPath);
+            const relativeBase = relative(root, absoluteBase);
+            const normalizedBase = relativeBase.replace(/^\.\//, '').replaceAll('\\', '/');
+            const candidates = [
+                normalizedBase,
+                ...[...SOURCE_EXTENSIONS].map((extension) => `${normalizedBase}${extension}`),
+                ...[...SOURCE_EXTENSIONS].map((extension) => `${normalizedBase}/index${extension}`),
+            ];
+            const projectCandidate = candidates.find((candidate) => modules.has(candidate));
+            if (projectCandidate)
+                return projectCandidate;
+        }
+    }
+    return undefined;
+}
+function parseModule(project, root, path, projectFiles, aliases) {
     if (!SOURCE_EXTENSIONS.has(extname(path)))
         return undefined;
     let sourceFile;
@@ -187,6 +271,7 @@ function parseModule(project, root, path, projectFiles) {
     const dynamicImports = [];
     const declarations = { classes: 0, functions: 0, interfaces: 0, types: 0, variables: 0 };
     const resolvedImports = new Set();
+    const resolvedImportMap = {};
     for (const declaration of sourceFile.getImportDeclarations()) {
         const importPath = declaration.getModuleSpecifierValue();
         imports.push(importPath);
@@ -200,9 +285,12 @@ function parseModule(project, root, path, projectFiles) {
             importedSymbols.push(namedImport.getAliasNode()?.getText() ?? namedImport.getName());
         }
         const resolved = declaration.getModuleSpecifierSourceFile();
-        const resolvedPath = resolved && sourceFilePath(root, resolved, projectFiles);
-        if (resolvedPath)
+        const resolvedPath = (resolved && sourceFilePath(root, resolved, projectFiles)) ??
+            resolveAliasedImport(root, importPath, aliases, projectFiles);
+        if (resolvedPath) {
             resolvedImports.add(resolvedPath);
+            resolvedImportMap[importPath] = resolvedPath;
+        }
     }
     for (const declaration of sourceFile.getExportDeclarations()) {
         const moduleSpecifier = declaration.getModuleSpecifierValue();
@@ -210,9 +298,12 @@ function parseModule(project, root, path, projectFiles) {
             continue;
         exports.push(moduleSpecifier);
         const resolved = declaration.getModuleSpecifierSourceFile();
-        const resolvedPath = resolved && sourceFilePath(root, resolved, projectFiles);
-        if (resolvedPath)
+        const resolvedPath = (resolved && sourceFilePath(root, resolved, projectFiles)) ??
+            resolveAliasedImport(root, moduleSpecifier, aliases, projectFiles);
+        if (resolvedPath) {
             resolvedImports.add(resolvedPath);
+            resolvedImportMap[moduleSpecifier] = resolvedPath;
+        }
     }
     declarations.classes = sourceFile.getClasses().length;
     declarations.functions = sourceFile.getFunctions().length;
@@ -234,9 +325,12 @@ function parseModule(project, root, path, projectFiles) {
         if (!importPath)
             continue;
         dynamicImports.push(importPath);
-        const resolvedPath = resolveInternalImport(path, importPath, projectFiles);
-        if (resolvedPath)
+        const resolvedPath = resolveInternalImport(path, importPath, projectFiles) ??
+            resolveAliasedImport(root, importPath, aliases, projectFiles);
+        if (resolvedPath) {
             resolvedImports.add(resolvedPath);
+            resolvedImportMap[importPath] = resolvedPath;
+        }
     }
     const directives = sourceFile
         .getStatements()
@@ -257,6 +351,7 @@ function parseModule(project, root, path, projectFiles) {
         exports: [...new Set(exports)].sort(),
         calls: [...new Set(calls)].sort(),
         resolvedImports: [...resolvedImports].sort(),
+        resolvedImportMap,
         dynamicImports: [...new Set(dynamicImports)].sort(),
         declarations,
         directives,
@@ -337,16 +432,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);
@@ -638,9 +740,23 @@ function buildInsights(root, files, modules, sourceFiles, dependencies, astProje
 function createAstProject(root) {
     const tsConfigPath = resolve(root, 'tsconfig.json');
     try {
-        return existsSync(tsConfigPath)
+        const project = existsSync(tsConfigPath)
             ? new Project({ tsConfigFilePath: tsConfigPath })
             : new Project({ skipAddingFilesFromTsConfig: true });
+        // Monorepos commonly keep compiler options and path aliases per package.
+        // Load those projects as well; files still remain bounded by listFiles().
+        for (const configPath of listFiles(root).filter((path) => basename(path) === 'tsconfig.json')) {
+            const absolutePath = resolve(root, configPath);
+            if (absolutePath === tsConfigPath)
+                continue;
+            try {
+                project.addSourceFilesFromTsConfig(absolutePath);
+            }
+            catch {
+                // A package config can be partial or reference an unavailable project.
+            }
+        }
+        return project;
     }
     catch {
         return new Project({ skipAddingFilesFromTsConfig: true });
@@ -651,19 +767,42 @@ export function discoverProject(root, options = {}) {
     const dependencies = asStringRecord(packageJson.dependencies);
     const devDependencies = asStringRecord(packageJson.devDependencies);
     const scripts = asStringRecord(packageJson.scripts);
-    const allFiles = listFiles(root);
+    const maxFiles = options.maxFiles ?? DEFAULT_MAX_FILES;
+    const maxFileBytes = options.maxFileBytes ?? DEFAULT_MAX_FILE_BYTES;
+    if (!Number.isInteger(maxFiles) || maxFiles < 1) {
+        throw new DiscoveryLimitError('Discovery maxFiles must be a positive integer.');
+    }
+    if (!Number.isInteger(maxFileBytes) || maxFileBytes < 1) {
+        throw new DiscoveryLimitError('Discovery maxFileBytes must be a positive integer.');
+    }
+    const allFiles = listFiles(root, root, maxFiles);
+    if (allFiles.length > maxFiles) {
+        throw new DiscoveryLimitError(`Project contains ${allFiles.length} files; discovery limit is ${maxFiles}. ` +
+            'Use an ignore file or raise maxFiles deliberately.');
+    }
+    for (const path of allFiles) {
+        const bytes = statSync(resolve(root, path)).size;
+        if (bytes > maxFileBytes) {
+            throw new DiscoveryLimitError(`File ${path} is ${bytes} bytes; discovery limit is ${maxFileBytes}. ` +
+                'Ignore the file or raise maxFileBytes deliberately.');
+        }
+    }
     const signature = JSON.stringify([
         JSON.stringify(packageJson),
         allFiles.map((path) => {
             const stat = statSync(resolve(root, path));
-            return [path, stat.size, stat.mtimeMs];
+            // Size/mtime alone can miss an in-place edit that preserves both values.
+            // The model is a correctness boundary, so include content in the cache key.
+            return [path, stat.size, stat.mtimeMs, contentHash(root, path)];
         }),
         runGit(root, ['rev-parse', 'HEAD']),
         runGit(root, ['status', '--porcelain']),
     ]);
     const cacheKey = resolve(root);
+    discoveryCacheHits.set(cacheKey, false);
     const cached = discoveryCache.get(cacheKey);
     if (cached?.signature === signature) {
+        discoveryCacheHits.set(cacheKey, true);
         discoveryReuse.set(cacheKey, cached.model.modules.length);
         return cached.model;
     }
@@ -676,6 +815,7 @@ export function discoverProject(root, options = {}) {
             persisted.model.version === 1) {
             previousModel = persisted.model;
             if (persisted.signature === signature) {
+                discoveryCacheHits.set(cacheKey, true);
                 discoveryCache.set(cacheKey, { signature, model: previousModel });
                 discoveryReuse.set(cacheKey, previousModel.modules.length);
                 return previousModel;
@@ -692,6 +832,7 @@ export function discoverProject(root, options = {}) {
     }));
     const projectFiles = new Set(files.map((file) => file.path));
     const astProject = createAstProject(root);
+    const aliases = pathAliases(root);
     const previousModules = new Map(previousModel?.modules.map((module) => [module.path, module]));
     const currentShape = files
         .filter((file) => file.kind === 'source' || file.kind === 'test')
@@ -716,7 +857,7 @@ export function discoverProject(root, options = {}) {
             reusedModules += 1;
             return previous;
         }
-        return parseModule(astProject, root, file.path, projectFiles);
+        return parseModule(astProject, root, file.path, projectFiles, aliases);
     })
         .filter((module) => module !== undefined);
     const sourceFiles = files.filter((file) => file.kind === 'source').map((file) => file.path);
@@ -799,7 +940,6 @@ export function discoverProject(root, options = {}) {
 }
 export function discoverProjectWithMetrics(root, options = {}) {
     const startedAt = Date.now();
-    const cacheHit = discoveryCache.has(resolve(root));
     const model = discoverProject(root, options);
     return {
         model,
@@ -808,7 +948,7 @@ export function discoverProjectWithMetrics(root, options = {}) {
             files: model.files.length,
             modules: model.modules.length,
             cacheAvailable: existsSync(discoveryCachePath(root)),
-            cacheHit,
+            cacheHit: discoveryCacheHits.get(resolve(root)) ?? false,
             changedFiles: model.git.changedFiles.length,
             reusedModules: discoveryReuse.get(resolve(root)) ?? 0,
         },

package/dist/core/errors.d.ts

@@ -0,0 +1,11 @@
+export type GuardErrorCode = 'GUARD_NOT_CONFIGURED' | 'GUARD_CONFIG_INVALID' | 'GUARD_STATE_BUSY' | 'GUARD_INVALID_INPUT';
+export interface GuardErrorPayload {
+    status: 'error';
+    outcome: 'not-configured' | 'error';
+    configured: boolean;
+    errorCode: GuardErrorCode;
+    message: string;
+    recoverable: boolean;
+    hint?: string;
+}
+export declare function guardErrorPayload(errorCode: GuardErrorCode, message: string, options: Pick<GuardErrorPayload, 'configured' | 'recoverable' | 'outcome'> & Partial<Pick<GuardErrorPayload, 'hint'>>): GuardErrorPayload;

package/dist/core/errors.js

@@ -0,0 +1,11 @@
+export function guardErrorPayload(errorCode, message, options) {
+    return {
+        status: 'error',
+        outcome: options.outcome,
+        configured: options.configured,
+        errorCode,
+        message,
+        recoverable: options.recoverable,
+        ...(options.hint ? { hint: options.hint } : {}),
+    };
+}

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 ProjectModel } from './discovery/discovery.js';
+import { clearDiscoveryCache, 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: {
@@ -10,7 +11,7 @@ export declare function classifyGuardOutcome(input: {
 }): GuardOutcomeStatus;
 export type GuardRuleKind = 'forbidden-import' | 'client-forbidden-import';
 export type GuardRuleStatus = 'active' | 'proposed';
-export type GuardContractKind = 'guidance' | 'import-boundary' | 'required-call';
+export type GuardContractKind = 'guidance' | 'import-boundary' | 'required-call' | 'package-boundary';
 export interface GuardContract {
     id: string;
     statement: string;
@@ -24,6 +25,8 @@ export interface GuardContract {
     mustImport?: string[];
     mustNotImport?: string[];
     mustCall?: string[];
+    fromPackages?: string[];
+    mustNotImportPackages?: string[];
     status?: GuardRuleStatus;
     confidence?: 'high' | 'medium' | 'low';
     evidence?: string[];
@@ -88,9 +91,15 @@ export interface GuardFinding {
     file: string;
     line: number;
     importPath: string;
+    resolvedPath?: string;
     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 +123,7 @@ export interface GuardReviewPacket {
     outcome: GuardOutcomeStatus;
     diffBase?: string;
     changedFiles: string[];
+    changes: GuardFileChange[];
     diff: string;
     truncated: boolean;
     redacted: boolean;
@@ -122,6 +132,7 @@ export interface GuardReviewPacket {
     contracts: GuardContract[];
     requirement?: string;
     deterministicFindings: GuardFinding[];
+    impact: GuardImpactAnalysis;
     reviewInstructions: string[];
 }
 export declare const GUARD_DIR: string;
@@ -140,6 +151,12 @@ export declare const defaultGuardAgentConfig: GuardAgentConfig;
 export declare class GuardAlreadyInitializedError extends Error {
     constructor();
 }
+export declare class GuardConfigError extends Error {
+    constructor(path: string);
+}
+export declare class GuardStateBusyError extends Error {
+    constructor(path: string);
+}
 export declare function isGuardContractsFile(value: unknown): value is {
     version: 1;
     contracts: GuardContract[];
@@ -152,7 +169,6 @@ export declare function loadGuardProposals(root: string): GuardProposalFile | un
 export declare function isGuardAgentConfig(value: unknown): value is GuardAgentConfig;
 export declare function loadGuardAgentConfig(root: string): GuardAgentConfig;
 export declare function writeGuardAgentConfig(root: string, agentConfig?: GuardAgentConfig): void;
-export declare function loadGuardArtifact(root: string, relativePath: string): unknown;
 export declare function loadBaseline(root: string): Set<string>;
 export declare function updateBaseline(root: string, options?: {
     add?: string[];
@@ -162,6 +178,10 @@ export declare function updateBaseline(root: string, options?: {
 export declare function writeGuardConfig(root: string, guardConfig: GuardConfig): void;
 export declare function writeGuardProposals(root: string, proposals: GuardProposalFile): void;
 export declare function recordGuardProposalDecision(root: string, decisions: Pick<GuardProposalDecision, 'id' | 'type' | 'decision'>[]): void;
+export declare function getPendingGuardProposals(proposals: GuardProposalFile | undefined): {
+    id: string;
+    type: 'rule' | 'contract';
+}[];
 export declare function buildGuardProposals(model: ProjectModel, guardConfig: GuardConfig): GuardProposalFile;
 export declare function buildArchitectureMemory(model: ProjectModel): Record<string, unknown>;
 export declare function buildConventionsMemory(model: ProjectModel): Record<string, unknown>;
@@ -171,6 +191,7 @@ export declare function writeBaseline(root: string, findings: GuardFinding[], mo
 export declare function loadProjectModel(root: string): ProjectModel | undefined;
 export declare function writeProjectModel(root: string, model: ProjectModel): void;
 export declare function writeProjectSnapshot(root: string, model: ProjectModel): string;
+export declare function loadGuardArtifact(root: string, relativePath: string): unknown;
 export declare function validateGuardContracts(root: string, contracts?: GuardContract[]): GuardContractIssue[];
 /** @internal Redacts common credential shapes before a diff enters an AI review packet. */
 export declare function redactSensitiveText(value: string): {
@@ -186,4 +207,4 @@ export declare function initializeGuard(root: string, options?: {
     config: GuardConfig;
     report: GuardReport;
 };
-export { discoverProject, discoverProjectWithMetrics, findGuardRoot };
+export { clearDiscoveryCache, discoverProject, discoverProjectWithMetrics, findGuardRoot };