@codapult/guard 0.6.2 → 0.8.0

package/dist/core/analysis/doctor.js

@@ -11,6 +11,33 @@ const requiredArtifacts = [
     GUARD_CONTRACTS_FILE,
     GUARD_PROPOSALS_FILE,
 ];
+function downgradedBoundaryItems(root) {
+    let guardConfig;
+    try {
+        guardConfig = loadGuardConfig(root);
+    }
+    catch {
+        return [];
+    }
+    if (!guardConfig)
+        return [];
+    const items = guardConfig.rules
+        .filter((rule) => rule.kind === 'client-forbidden-import' && rule.severity === 'warning')
+        .map((rule) => ({
+        path: GUARD_RULES_FILE,
+        status: 'warning',
+        message: `Boundary rule '${rule.id}' is warning-only and will not block changes.`,
+    }));
+    items.push(...(guardConfig.contracts ?? [])
+        .filter((contract) => (contract.kind === 'import-boundary' || contract.kind === 'package-boundary') &&
+        contract.severity === 'warning')
+        .map((contract) => ({
+        path: GUARD_CONTRACTS_FILE,
+        status: 'warning',
+        message: `Boundary contract '${contract.id}' is warning-only and will not block changes.`,
+    })));
+    return items;
+}
 function parseJson(root, path) {
     try {
         return JSON.parse(readFileSync(resolve(root, path), 'utf8'));
@@ -64,6 +91,7 @@ export function diagnoseGuard(root) {
         }
         return { path, status: 'ok', message: 'Artifact is present and readable.' };
     });
+    items.push(...downgradedBoundaryItems(root));
     if (initialized && existsSync(resolve(root, GUARD_BASELINE_META_FILE))) {
         const metadata = parseJson(root, GUARD_BASELINE_META_FILE);
         items.push({
@@ -79,10 +107,11 @@ export function diagnoseGuard(root) {
     }
     const missing = items.filter((item) => item.status === 'missing');
     const invalid = items.filter((item) => item.status === 'invalid');
+    const warnings = items.filter((item) => item.status === 'warning');
     return {
         status: invalid.length > 0 || (initialized && missing.length > 0)
             ? 'fail'
-            : missing.length > 0
+            : missing.length > 0 || warnings.length > 0
                 ? 'warning'
                 : 'ok',
         initialized,
@@ -93,6 +122,10 @@ export function diagnoseGuard(root) {
             }
             : missing.length > 0
                 ? { recommendation: 'Run `codapult-guard analyze` or reinitialize Guard intentionally.' }
-                : {}),
+                : warnings.length > 0
+                    ? {
+                        recommendation: 'Review downgraded boundary policy before relying on Guard as a hard gate.',
+                    }
+                    : {}),
     };
 }

package/dist/core/audit/governance.d.ts

@@ -0,0 +1,37 @@
+export interface GuardGovernanceAudit {
+    version: 1;
+    generatedAt: string;
+    configured: boolean;
+    policy?: {
+        revision?: number | undefined;
+        fingerprint: string;
+    } | undefined;
+    proposals: {
+        currentId?: string | undefined;
+        currentAuthor?: string | undefined;
+        decisions: number;
+        authors: string[];
+        missingAuthors: number;
+    };
+    approvals: {
+        total: number;
+        approved: number;
+        rejected: number;
+        actors: string[];
+        missingActors: number;
+        actorAuthorOverlap: string[];
+        commitAuthors: string[];
+        actorCommitAuthorOverlap: string[];
+        missingCommits: number;
+        sources: Record<string, number>;
+    };
+    reachability: {
+        approvedWithPolicyFingerprint: number;
+        approvedLinkedToRun: number;
+        approvedWithoutRun: number;
+        runsWithPolicy: number;
+        runsWithoutPolicy: number;
+    };
+    warnings: string[];
+}
+export declare function auditGuardGovernance(root: string): GuardGovernanceAudit;

package/dist/core/audit/governance.js

@@ -0,0 +1,166 @@
+import { execFileSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { createGuardPolicySnapshot, loadBaseline, loadGuardAgentConfig, loadGuardConfig, loadGuardProposals, loadGuardWaivers, withGuardStateLock, GUARD_DIR, } from '../guard.js';
+import { GUARD_RUN_RETENTION, listGuardRuns } from '../history/runs.js';
+function commitAuthor(root, commit, cache) {
+    if (!commit || !/^[0-9a-f]{7,64}$/i.test(commit))
+        return undefined;
+    if (cache.has(commit))
+        return cache.get(commit);
+    try {
+        const value = execFileSync('git', ['show', '-s', '--format=%ae', commit], {
+            cwd: root,
+            stdio: 'pipe',
+            timeout: 5_000,
+            maxBuffer: 64 * 1024,
+        })
+            .toString()
+            .trim();
+        const author = value || undefined;
+        cache.set(commit, author);
+        return author;
+    }
+    catch {
+        cache.set(commit, undefined);
+        return undefined;
+    }
+}
+function currentProposalAuthor(proposals, decision) {
+    if (decision.proposalAuthor)
+        return decision.proposalAuthor;
+    if (decision.proposalId && decision.proposalId === proposals?.proposalId) {
+        return proposals.generatedBy;
+    }
+    return undefined;
+}
+function auditGuardGovernanceUnlocked(root) {
+    const config = loadGuardConfig(root);
+    const proposals = loadGuardProposals(root);
+    const decisions = proposals?.decisions ?? [];
+    const approved = decisions.filter((decision) => decision.decision === 'approved');
+    const authors = [
+        ...new Set(decisions
+            .map((decision) => currentProposalAuthor(proposals, decision))
+            .filter((author) => Boolean(author))),
+    ].sort();
+    const actors = [
+        ...new Set(approved
+            .map((decision) => decision.actor?.trim())
+            .filter((actor) => Boolean(actor))),
+    ].sort();
+    const commitAuthorCache = new Map();
+    const enrichedApprovals = approved.map((decision) => ({
+        decision,
+        author: currentProposalAuthor(proposals, decision),
+        commitAuthor: commitAuthor(root, decision.commit, commitAuthorCache),
+    }));
+    const commitAuthors = [
+        ...new Set(enrichedApprovals
+            .map((item) => item.commitAuthor)
+            .filter((author) => Boolean(author))),
+    ].sort();
+    const actorAuthorOverlap = [
+        ...new Set(enrichedApprovals
+            .filter((item) => item.decision.actor && item.author && item.decision.actor === item.author)
+            .map((item) => item.decision.actor)
+            .filter((actor) => Boolean(actor))),
+    ].sort();
+    const actorCommitAuthorOverlap = [
+        ...new Set(enrichedApprovals
+            .filter((item) => item.decision.actor && item.commitAuthor === item.decision.actor)
+            .map((item) => item.decision.actor)
+            .filter((actor) => Boolean(actor))),
+    ].sort();
+    const runs = listGuardRuns(root, GUARD_RUN_RETENTION);
+    const runDecisionBindings = new Map();
+    for (const run of runs) {
+        const fingerprint = run.policy?.fingerprint;
+        if (!fingerprint)
+            continue;
+        for (const decisionId of run.policy?.decisionIds ?? []) {
+            const fingerprints = runDecisionBindings.get(decisionId) ?? new Set();
+            fingerprints.add(fingerprint);
+            runDecisionBindings.set(decisionId, fingerprints);
+        }
+    }
+    const approvedWithPolicyFingerprint = approved.filter((decision) => decision.policyFingerprint !== undefined).length;
+    const approvedLinkedToRun = approved.filter((decision) => decision.policyFingerprint !== undefined &&
+        runDecisionBindings
+            .get(decision.decisionId ??
+            `${decision.proposalId ?? 'unknown'}:${decision.type}:${decision.id}`)
+            ?.has(decision.policyFingerprint)).length;
+    const warnings = [];
+    if (approved.some((decision) => !decision.actor)) {
+        warnings.push('Some approved decisions do not declare an approval actor.');
+    }
+    if (approved.some((decision) => !currentProposalAuthor(proposals, decision))) {
+        warnings.push('Some approved decisions do not retain a proposal author.');
+    }
+    if (actorAuthorOverlap.length > 0) {
+        warnings.push('At least one declared approval actor also authored an approved proposal.');
+    }
+    if (approved.some((decision) => !decision.policyFingerprint)) {
+        warnings.push('Some approved decisions are not bound to a resulting policy fingerprint.');
+    }
+    if (approved.some((decision) => decision.policyFingerprint === undefined ||
+        !runDecisionBindings
+            .get(decision.decisionId ??
+            `${decision.proposalId ?? 'unknown'}:${decision.type}:${decision.id}`)
+            ?.has(decision.policyFingerprint))) {
+        warnings.push('Some approved decisions have no retained verification run linked by decision ID.');
+    }
+    return {
+        version: 1,
+        generatedAt: new Date().toISOString(),
+        configured: config !== undefined,
+        ...(config
+            ? {
+                policy: (() => {
+                    const snapshot = createGuardPolicySnapshot(config, loadBaseline(root), loadGuardWaivers(root), 'working-tree', undefined, loadGuardAgentConfig(root));
+                    return {
+                        ...(snapshot.revision !== undefined ? { revision: snapshot.revision } : {}),
+                        fingerprint: snapshot.fingerprint,
+                    };
+                })(),
+            }
+            : {}),
+        proposals: {
+            ...(proposals?.proposalId ? { currentId: proposals.proposalId } : {}),
+            ...(proposals?.generatedBy ? { currentAuthor: proposals.generatedBy } : {}),
+            decisions: decisions.length,
+            authors,
+            missingAuthors: decisions.filter((decision) => !currentProposalAuthor(proposals, decision))
+                .length,
+        },
+        approvals: {
+            total: decisions.length,
+            approved: approved.length,
+            rejected: decisions.filter((decision) => decision.decision === 'rejected').length,
+            actors,
+            missingActors: approved.filter((decision) => !decision.actor).length,
+            actorAuthorOverlap,
+            commitAuthors,
+            actorCommitAuthorOverlap,
+            missingCommits: approved.filter((decision) => !decision.commit).length,
+            sources: decisions.reduce((counts, decision) => {
+                const source = decision.source ?? 'unknown';
+                counts[source] = (counts[source] ?? 0) + 1;
+                return counts;
+            }, {}),
+        },
+        reachability: {
+            approvedWithPolicyFingerprint,
+            approvedLinkedToRun,
+            approvedWithoutRun: approvedWithPolicyFingerprint - approvedLinkedToRun,
+            runsWithPolicy: runs.filter((run) => run.policy !== undefined).length,
+            runsWithoutPolicy: runs.filter((run) => run.policy === undefined).length,
+        },
+        warnings,
+    };
+}
+export function auditGuardGovernance(root) {
+    if (!existsSync(resolve(root, GUARD_DIR)))
+        return auditGuardGovernanceUnlocked(root);
+    return withGuardStateLock(root, () => auditGuardGovernanceUnlocked(root));
+}

package/dist/core/errors.d.ts

@@ -1,4 +1,4 @@
-export type GuardErrorCode = 'GUARD_NOT_CONFIGURED' | 'GUARD_CONFIG_INVALID' | 'GUARD_STATE_BUSY' | 'GUARD_STATE_STALE' | 'GUARD_INVALID_INPUT';
+export type GuardErrorCode = 'GUARD_NOT_CONFIGURED' | 'GUARD_CONFIG_INVALID' | 'GUARD_STATE_BUSY' | 'GUARD_STATE_STALE' | 'GUARD_POLICY_BASE_INVALID' | 'GUARD_POLICY_CHANGED' | 'GUARD_INVALID_INPUT';
 export interface GuardErrorPayload {
     status: 'error';
     outcome: 'not-configured' | 'error';

package/dist/core/guard.d.ts

@@ -1,8 +1,8 @@
 import { type ProjectModel } from './discovery/discovery.js';
 import { clearDiscoveryCache, discoverProject, discoverProjectWithMetrics, findGuardRoot } from './discovery/discovery.js';
 import { type GuardImpactAnalysis } from './analysis/impact.js';
-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';
+import type { GuardAdapterName, GuardApprovalMode, GuardContractKind, GuardBudgetMetric, GuardRuleKind, GuardRuleStatus, GuardSeverity, GuardToolMode, GuardWaiver, GuardWaiverPolicy } from './model/types.js';
+export type { GuardAdapterName, GuardApprovalMode, GuardContractKind, GuardBudgetMetric, GuardRuleKind, GuardRuleStatus, GuardSeverity, GuardToolMode, GuardWaiver, GuardWaiverPolicy, GuardWaiverDecision, } from './model/types.js';
 export type GuardOutcomeStatus = 'pass' | 'fail' | 'warning' | 'needs-review' | 'not-configured';
 export interface GuardOutcomeInput {
     configured?: boolean | undefined;
@@ -85,6 +85,7 @@ export interface GuardConfig {
     contracts?: GuardContract[] | undefined;
     budgets?: GuardBudget[] | undefined;
     approval?: GuardApprovalPolicy | undefined;
+    waiverPolicy?: GuardWaiverPolicy | undefined;
 }
 export interface GuardApprovalPolicy {
     mode: GuardApprovalMode;
@@ -105,6 +106,7 @@ export interface GuardProposalFile {
     decisions?: GuardProposalDecision[] | undefined;
 }
 export interface GuardProposalDecision {
+    decisionId?: string | undefined;
     id: string;
     type: 'rule' | 'contract';
     decision: 'approved' | 'rejected';
@@ -113,8 +115,11 @@ export interface GuardProposalDecision {
     proposalFingerprint?: string | undefined;
     revision?: number | undefined;
     source?: 'cli' | 'mcp' | 'external' | undefined;
+    proposalAuthor?: string | undefined;
     actor?: string | undefined;
     commit?: string | undefined;
+    policyFingerprint?: string | undefined;
+    policyRevision?: number | undefined;
 }
 export type GuardProposalFreshness = 'current' | 'stale' | 'unknown';
 export interface GuardAgentConfig {
@@ -157,12 +162,17 @@ export interface GuardReport {
     findings: GuardFinding[];
     suppressed: number;
     scannedFiles: number;
+    waived: number;
+    waiverWarnings: GuardWaiver[];
+    expiredWaivers: GuardWaiver[];
 }
 interface ScanGuardOptions {
     changedOnly?: boolean | undefined;
     changedFiles?: Set<string> | undefined;
     baseline?: Set<string> | undefined;
     includeArchitectureInsights?: boolean | undefined;
+    waivers?: GuardWaiver[] | undefined;
+    now?: string | undefined;
 }
 export interface GuardReviewPacket {
     version: 1;
@@ -178,6 +188,9 @@ export interface GuardReviewPacket {
     contracts: GuardContract[];
     requirement?: string | undefined;
     deterministicFindings: GuardFinding[];
+    waived: number;
+    waiverWarnings: GuardWaiver[];
+    expiredWaivers: GuardWaiver[];
     impact: GuardImpactAnalysis;
     reviewInstructions: string[];
 }
@@ -185,6 +198,7 @@ export declare const GUARD_DIR: string;
 export declare const GUARD_RULES_FILE: string;
 export declare const GUARD_BASELINE_FILE: string;
 export declare const GUARD_BASELINE_META_FILE: string;
+export declare const GUARD_WAIVERS_FILE: string;
 export declare const GUARD_PROJECT_FILE: string;
 export declare const GUARD_HISTORY_DIR: string;
 export declare const GUARD_ARCHITECTURE_FILE: string;
@@ -212,6 +226,9 @@ export declare class GuardStateStaleError extends Error {
 export declare class GuardBaselineReasonError extends Error {
     constructor();
 }
+export declare class GuardWaiverError extends Error {
+    constructor(message: string);
+}
 export declare function withGuardStateLock<T>(root: string, callback: () => T, options?: GuardStateLockOptions): T;
 export declare function isGuardContractsFile(value: unknown): value is {
     version: 1;
@@ -220,6 +237,30 @@ export declare function isGuardContractsFile(value: unknown): value is {
 export declare function isGuardProposalFile(value: unknown): value is GuardProposalFile;
 export declare function fingerprintProjectModel(model: ProjectModel): string;
 export declare function fingerprintGuardConfig(guardConfig: GuardConfig): string;
+export interface GuardPolicySnapshot {
+    config: GuardConfig;
+    agentConfig: GuardAgentConfig;
+    baseline: Set<string>;
+    waivers: GuardWaiver[];
+    revision?: number | undefined;
+    fingerprint: string;
+    source: 'working-tree' | 'git-ref';
+    ref?: string | undefined;
+}
+/**
+ * Fingerprints the effective policy used by a verification run.
+ *
+ * The rules revision alone is not sufficient: baseline and waiver changes also
+ * affect the verdict. Keeping them in this fingerprint makes a run auditable
+ * without pretending that a numeric revision covers every policy artifact.
+ */
+export declare function fingerprintGuardPolicy(guardConfig: GuardConfig, baseline?: Set<string>, waivers?: GuardWaiver[], agentConfig?: GuardAgentConfig): string;
+export declare function createGuardPolicySnapshot(guardConfig: GuardConfig, baseline: Set<string>, waivers: GuardWaiver[], source?: GuardPolicySnapshot['source'], ref?: string, agentConfig?: GuardAgentConfig): GuardPolicySnapshot;
+/**
+ * Loads policy artifacts from a trusted Git ref instead of the checked-out
+ * working tree. This is intended for CI verification of untrusted branches.
+ */
+export declare function loadGuardPolicyAtRevision(root: string, revision: string): GuardPolicySnapshot | undefined;
 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;
@@ -227,6 +268,18 @@ 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 interface GuardWaiverUpdateOptions {
+    action: 'add' | 'renew' | 'remove';
+    waiver?: GuardWaiver | undefined;
+    waiverId: string;
+    reason: string;
+    expiresAt?: string | undefined;
+    actor?: string | undefined;
+    maxLifetimeDays?: number | undefined;
+}
+export declare function loadGuardWaivers(root: string): GuardWaiver[];
+export declare function writeGuardWaivers(root: string): void;
+export declare function updateGuardWaivers(root: string, options: GuardWaiverUpdateOptions): GuardWaiver[];
 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;