@codapult/guard 0.3.0 → 0.4.0

package/dist/core/discovery/discovery.js

@@ -10,6 +10,12 @@ export class DiscoveryLimitError extends Error {
         this.name = 'DiscoveryLimitError';
     }
 }
+export class DiscoveryStaleError extends Error {
+    constructor() {
+        super('Project changed while Guard was discovering it.');
+        this.name = 'DiscoveryStaleError';
+    }
+}
 const DEFAULT_MAX_FILES = 100_000;
 const DEFAULT_MAX_FILE_BYTES = 25 * 1024 * 1024;
 const IGNORED_DIRECTORIES = new Set([
@@ -366,6 +372,17 @@ function runGit(root, args) {
         return stdout?.toString().trim() || undefined;
     }
 }
+function discoverySignature(root, packageJson, allFiles) {
+    return JSON.stringify([
+        JSON.stringify(packageJson),
+        allFiles.map((path) => {
+            const stat = statSync(resolve(root, path));
+            return [path, stat.size, stat.mtimeMs, contentHash(root, path)];
+        }),
+        runGit(root, ['rev-parse', 'HEAD']),
+        runGit(root, ['status', '--porcelain']),
+    ]);
+}
 function gitModel(root) {
     const branch = runGit(root, ['branch', '--show-current']);
     const status = runGit(root, ['status', '--porcelain'])?.split('\n').filter(Boolean) ?? [];
@@ -383,7 +400,7 @@ function gitModel(root) {
     });
     return {
         repository: runGit(root, ['rev-parse', '--is-inside-work-tree']) === 'true',
-        branch: branch || undefined,
+        ...(branch ? { branch } : {}),
         dirty: status.length > 0,
         changedFiles: [...changed].sort(),
         status,
@@ -762,7 +779,7 @@ function createAstProject(root) {
         return new Project({ skipAddingFilesFromTsConfig: true });
     }
 }
-export function discoverProject(root, options = {}) {
+function discoverProjectOnce(root, options = {}, attempt = 0) {
     const packageJson = readJsonObject(resolve(root, 'package.json'));
     const dependencies = asStringRecord(packageJson.dependencies);
     const devDependencies = asStringRecord(packageJson.devDependencies);
@@ -787,17 +804,7 @@ export function discoverProject(root, options = {}) {
                 'Ignore the file or raise maxFileBytes deliberately.');
         }
     }
-    const signature = JSON.stringify([
-        JSON.stringify(packageJson),
-        allFiles.map((path) => {
-            const stat = statSync(resolve(root, path));
-            // 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 signature = discoverySignature(root, packageJson, allFiles);
     const cacheKey = resolve(root);
     discoveryCacheHits.set(cacheKey, false);
     const cached = discoveryCache.get(cacheKey);
@@ -890,11 +897,12 @@ export function discoverProject(root, options = {}) {
         }
         return { path, methods: [...methods].sort() };
     });
+    const detectedPackageManager = packageManager(root);
     const model = {
         version: 1,
         project: {
-            name: typeof packageJson.name === 'string' ? packageJson.name : undefined,
-            packageManager: packageManager(root),
+            ...(typeof packageJson.name === 'string' ? { name: packageJson.name } : {}),
+            ...(detectedPackageManager ? { packageManager: detectedPackageManager } : {}),
             frameworks: inferFrameworks(dependencies, devDependencies),
             scripts,
             dependencies,
@@ -922,6 +930,15 @@ export function discoverProject(root, options = {}) {
         },
         insights: buildInsights(root, files, modules, sourceFiles, dependencies, astProject),
     };
+    const finalFiles = listFiles(root, root, maxFiles);
+    const finalSignature = finalFiles.length <= maxFiles
+        ? discoverySignature(root, readJsonObject(resolve(root, 'package.json')), finalFiles)
+        : undefined;
+    if (finalSignature !== signature) {
+        if (attempt < 2)
+            return discoverProjectOnce(root, options, attempt + 1);
+        throw new DiscoveryStaleError();
+    }
     discoveryCache.set(cacheKey, { signature, model });
     discoveryReuse.set(cacheKey, reusedModules);
     if (options.persistCache ?? existsSync(resolve(root, `.${config.appName}/guard`))) {
@@ -938,6 +955,9 @@ export function discoverProject(root, options = {}) {
     }
     return model;
 }
+export function discoverProject(root, options = {}) {
+    return discoverProjectOnce(root, options);
+}
 export function discoverProjectWithMetrics(root, options = {}) {
     const startedAt = Date.now();
     const model = discoverProject(root, options);

package/dist/core/errors.d.ts

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

package/dist/core/guard.d.ts

@@ -1,35 +1,59 @@
 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';
+import type { GuardAdapterName, GuardApprovalMode, GuardContractKind, GuardBudgetMetric, GuardRuleKind, GuardRuleStatus, GuardSeverity, GuardToolMode } from './model/types.js';
+export type { GuardAdapterName, GuardApprovalMode, GuardContractKind, GuardBudgetMetric, GuardRuleKind, GuardRuleStatus, GuardSeverity, GuardToolMode, } from './model/types.js';
 export type GuardOutcomeStatus = 'pass' | 'fail' | 'warning' | 'needs-review' | 'not-configured';
-export declare function classifyGuardOutcome(input: {
-    configured?: boolean;
-    errors?: number;
-    warnings?: number;
-    needsReview?: boolean;
-}): GuardOutcomeStatus;
-export type GuardRuleKind = 'forbidden-import' | 'client-forbidden-import';
-export type GuardRuleStatus = 'active' | 'proposed';
-export type GuardContractKind = 'guidance' | 'import-boundary' | 'required-call' | 'package-boundary';
+export interface GuardOutcomeInput {
+    configured?: boolean | undefined;
+    errors?: number | undefined;
+    warnings?: number | undefined;
+    needsReview?: boolean | undefined;
+}
+interface GuardStateLockOptions {
+    waitMs?: number | undefined;
+    noWait?: boolean | undefined;
+}
+interface GuardBaselineUpdateOptions {
+    add?: string[] | undefined;
+    remove?: string[] | undefined;
+    reason?: string | undefined;
+}
+interface GuardConfigWriteOptions extends GuardStateLockOptions {
+    expectedRevision?: number | undefined;
+}
+interface GuardPendingProposal {
+    id: string;
+    type: 'rule' | 'contract';
+}
+export interface GuardSensitiveText {
+    value: string;
+    redacted: boolean;
+    redactionCount: number;
+}
+export interface GuardInitializationResult {
+    config: GuardConfig;
+    report: GuardReport;
+}
+export declare function classifyGuardOutcome(input: GuardOutcomeInput): GuardOutcomeStatus;
 export interface GuardContract {
     id: string;
     statement: string;
-    kind?: GuardContractKind;
-    severity?: GuardSeverity;
-    scope?: string[];
-    entrypoints?: string[];
-    exclude?: string[];
-    guidance?: string[];
-    references?: string[];
-    mustImport?: string[];
-    mustNotImport?: string[];
-    mustCall?: string[];
-    fromPackages?: string[];
-    mustNotImportPackages?: string[];
-    status?: GuardRuleStatus;
-    confidence?: 'high' | 'medium' | 'low';
-    evidence?: string[];
+    kind?: GuardContractKind | undefined;
+    severity?: GuardSeverity | undefined;
+    scope?: string[] | undefined;
+    entrypoints?: string[] | undefined;
+    exclude?: string[] | undefined;
+    guidance?: string[] | undefined;
+    references?: string[] | undefined;
+    mustImport?: string[] | undefined;
+    mustNotImport?: string[] | undefined;
+    mustCall?: string[] | undefined;
+    fromPackages?: string[] | undefined;
+    mustNotImportPackages?: string[] | undefined;
+    status?: GuardRuleStatus | undefined;
+    confidence?: 'high' | 'medium' | 'low' | undefined;
+    evidence?: string[] | undefined;
 }
 export interface GuardRule {
     id: string;
@@ -37,36 +61,60 @@ export interface GuardRule {
     severity: GuardSeverity;
     kind: GuardRuleKind;
     patterns: string[];
-    files?: string[];
-    status?: GuardRuleStatus;
-    confidence?: 'high' | 'medium' | 'low';
-    evidence?: string[];
+    files?: string[] | undefined;
+    status?: GuardRuleStatus | undefined;
+    confidence?: 'high' | 'medium' | 'low' | undefined;
+    evidence?: string[] | undefined;
+}
+export interface GuardBudget {
+    id: string;
+    description: string;
+    metric: GuardBudgetMetric;
+    scope: string[];
+    limit: number;
+    severity: GuardSeverity;
+    reason: string;
+    status?: GuardRuleStatus | undefined;
+    evidence?: string[] | undefined;
 }
 export interface GuardConfig {
     version: 1;
+    revision?: number | undefined;
+    contentFingerprint?: string | undefined;
     rules: GuardRule[];
-    contracts?: GuardContract[];
+    contracts?: GuardContract[] | undefined;
+    budgets?: GuardBudget[] | undefined;
+    approval?: GuardApprovalPolicy | undefined;
+}
+export interface GuardApprovalPolicy {
+    mode: GuardApprovalMode;
+    allowMcpApproval: boolean;
+    requireDistinctActor: boolean;
 }
 export interface GuardProposalFile {
     version: 1;
     generatedAt: string;
-    proposalId?: string;
-    projectFingerprint?: string;
-    revision?: number;
-    contentFingerprint?: string;
+    generatedBy?: string | undefined;
+    proposalId?: string | undefined;
+    projectFingerprint?: string | undefined;
+    revision?: number | undefined;
+    contentFingerprint?: string | undefined;
     rules: GuardRule[];
     contracts: GuardContract[];
     questions: string[];
-    decisions?: GuardProposalDecision[];
+    decisions?: GuardProposalDecision[] | undefined;
 }
 export interface GuardProposalDecision {
     id: string;
     type: 'rule' | 'contract';
     decision: 'approved' | 'rejected';
     decidedAt: string;
-    proposalId?: string;
-    proposalFingerprint?: string;
-    revision?: number;
+    proposalId?: string | undefined;
+    proposalFingerprint?: string | undefined;
+    revision?: number | undefined;
+    source?: 'cli' | 'mcp' | 'external' | undefined;
+    actor?: string | undefined;
+    commit?: string | undefined;
 }
 export type GuardProposalFreshness = 'current' | 'stale' | 'unknown';
 export interface GuardAgentConfig {
@@ -83,26 +131,24 @@ export interface GuardAgentConfig {
         checks: ('lint' | 'typecheck' | 'test' | 'build')[];
     };
 }
-export type GuardToolMode = 'auto' | 'on' | 'off';
-export type GuardAdapterName = 'dependency-graph' | 'security' | 'dependency-hygiene';
 export interface GuardFinding {
     ruleId: string;
     severity: GuardSeverity;
     file: string;
     line: number;
     importPath: string;
-    resolvedPath?: string;
+    resolvedPath?: string | undefined;
     message: string;
     fingerprint: string;
 }
 export interface GuardFileChange {
     path: string;
     status: 'added' | 'modified' | 'deleted' | 'renamed';
-    previousPath?: string;
+    previousPath?: string | undefined;
 }
 export interface GuardContractIssue {
     contractId: string;
-    field: 'scope' | 'reference' | 'definition';
+    field: 'scope' | 'reference' | 'definition' | 'files';
     value: string;
     message: string;
 }
@@ -113,24 +159,24 @@ export interface GuardReport {
     scannedFiles: number;
 }
 interface ScanGuardOptions {
-    changedOnly?: boolean;
-    changedFiles?: Set<string>;
-    baseline?: Set<string>;
-    includeArchitectureInsights?: boolean;
+    changedOnly?: boolean | undefined;
+    changedFiles?: Set<string> | undefined;
+    baseline?: Set<string> | undefined;
+    includeArchitectureInsights?: boolean | undefined;
 }
 export interface GuardReviewPacket {
     version: 1;
     outcome: GuardOutcomeStatus;
-    diffBase?: string;
+    diffBase?: string | undefined;
     changedFiles: string[];
     changes: GuardFileChange[];
     diff: string;
     truncated: boolean;
     redacted: boolean;
-    diffError?: string;
+    diffError?: string | undefined;
     project: ProjectModel;
     contracts: GuardContract[];
-    requirement?: string;
+    requirement?: string | undefined;
     deterministicFindings: GuardFinding[];
     impact: GuardImpactAnalysis;
     reviewInstructions: string[];
@@ -146,6 +192,9 @@ export declare const GUARD_CONVENTIONS_FILE: string;
 export declare const GUARD_AGENT_FILE: string;
 export declare const GUARD_CONTRACTS_FILE: string;
 export declare const GUARD_PROPOSALS_FILE: string;
+export declare const GUARD_STATE_DIR: string;
+export declare const GUARD_STATE_GENERATIONS_DIR: string;
+export declare const GUARD_STATE_CURRENT_FILE: string;
 export declare const defaultGuardConfig: GuardConfig;
 export declare const defaultGuardAgentConfig: GuardAgentConfig;
 export declare class GuardAlreadyInitializedError extends Error {
@@ -157,12 +206,20 @@ export declare class GuardConfigError extends Error {
 export declare class GuardStateBusyError extends Error {
     constructor(path: string);
 }
+export declare class GuardStateStaleError extends Error {
+    constructor();
+}
+export declare class GuardBaselineReasonError extends Error {
+    constructor();
+}
+export declare function withGuardStateLock<T>(root: string, callback: () => T, options?: GuardStateLockOptions): T;
 export declare function isGuardContractsFile(value: unknown): value is {
     version: 1;
     contracts: GuardContract[];
 };
 export declare function isGuardProposalFile(value: unknown): value is GuardProposalFile;
 export declare function fingerprintProjectModel(model: ProjectModel): string;
+export declare function fingerprintGuardConfig(guardConfig: GuardConfig): string;
 export declare function getGuardProposalFreshness(model: ProjectModel, proposals: GuardProposalFile | undefined): GuardProposalFreshness;
 export declare function loadGuardConfig(root: string): GuardConfig | undefined;
 export declare function loadGuardProposals(root: string): GuardProposalFile | undefined;
@@ -170,18 +227,13 @@ export declare function isGuardAgentConfig(value: unknown): value is GuardAgentC
 export declare function loadGuardAgentConfig(root: string): GuardAgentConfig;
 export declare function writeGuardAgentConfig(root: string, agentConfig?: GuardAgentConfig): void;
 export declare function loadBaseline(root: string): Set<string>;
-export declare function updateBaseline(root: string, options?: {
-    add?: string[];
-    remove?: string[];
-    reason?: string;
-}): Set<string>;
-export declare function writeGuardConfig(root: string, guardConfig: GuardConfig): void;
+export declare function updateBaseline(root: string, options?: GuardBaselineUpdateOptions): Set<string>;
+export declare function writeGuardConfig(root: string, guardConfig: GuardConfig, options?: GuardConfigWriteOptions): 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 recordGuardProposalDecision(root: string, decisions: Pick<GuardProposalDecision, 'id' | 'type' | 'decision'>[], options?: Pick<GuardProposalDecision, 'source'>): void;
+export declare function applyGuardProposalDecision(root: string, guardConfig: GuardConfig, decisions: Pick<GuardProposalDecision, 'id' | 'type' | 'decision'>[], options: Pick<GuardProposalDecision, 'source'>): void;
+export declare function validateGuardProposalApproval(policy: GuardApprovalPolicy | undefined, proposals: GuardProposalFile | undefined): string | undefined;
+export declare function getPendingGuardProposals(proposals: GuardProposalFile | undefined): GuardPendingProposal[];
 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>;
@@ -190,21 +242,21 @@ export declare function writeGuardMemory(root: string, model: ProjectModel): voi
 export declare function writeBaseline(root: string, findings: GuardFinding[], model?: ProjectModel): void;
 export declare function loadProjectModel(root: string): ProjectModel | undefined;
 export declare function writeProjectModel(root: string, model: ProjectModel): void;
+/**
+ * Persist all derived project facts as one generation. Legacy root-level files remain as
+ * compatibility mirrors, while readers that understand generations always see a coherent set.
+ */
+export declare function writeProjectState(root: string, model: ProjectModel, options?: GuardStateLockOptions): string;
 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[];
+export declare function validateGuardBudgets(root: string, budgets?: GuardBudget[]): GuardContractIssue[];
+export declare function validateGuardPolicy(root: string, guardConfig: GuardConfig): GuardContractIssue[];
 /** @internal Redacts common credential shapes before a diff enters an AI review packet. */
-export declare function redactSensitiveText(value: string): {
-    value: string;
-    redacted: boolean;
-    redactionCount: number;
-};
+export declare function redactSensitiveText(value: string): GuardSensitiveText;
 export declare function scanGuard(root: string, guardConfig: GuardConfig, options?: ScanGuardOptions): GuardReport;
 export declare function buildGuardReviewPacket(root: string, guardConfig: GuardConfig, baseline?: Set<string>, maxDiffChars?: number, changedOnly?: boolean, requirement?: string, base?: string): GuardReviewPacket;
-export declare function initializeGuard(root: string, options?: {
-    force?: boolean;
-}): {
-    config: GuardConfig;
-    report: GuardReport;
-};
+export declare function initializeGuard(root: string, options?: GuardConfigWriteOptions & {
+    force?: boolean | undefined;
+}): GuardInitializationResult;
 export { clearDiscoveryCache, discoverProject, discoverProjectWithMetrics, findGuardRoot };