@codapult/guard 0.2.0 → 0.4.0

package/dist/core/guard.d.ts

@@ -1,33 +1,59 @@
-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';
+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';
+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[];
-    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;
@@ -35,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 {
@@ -81,25 +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 | 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;
 }
@@ -110,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[];
@@ -143,33 +192,48 @@ 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 {
     constructor();
 }
+export declare class GuardConfigError extends Error {
+    constructor(path: string);
+}
+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;
 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[];
-    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 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>;
@@ -178,20 +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 { discoverProject, discoverProjectWithMetrics, findGuardRoot };
+export declare function initializeGuard(root: string, options?: GuardConfigWriteOptions & {
+    force?: boolean | undefined;
+}): GuardInitializationResult;
+export { clearDiscoveryCache, discoverProject, discoverProjectWithMetrics, findGuardRoot };