@codapult/guard 0.6.2 → 0.8.0

package/dist/core/guard.js

@@ -9,7 +9,7 @@ import { clearDiscoveryCache, discoverProject, discoverProjectWithMetrics, findG
 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';
+import { guardAgentConfigSchema, guardConfigSchema, guardContractsFileSchema, guardProposalSchema, guardWaiversFileSchema, } from './policy/schemas.js';
 export function classifyGuardOutcome(input) {
     if (input.configured === false)
         return 'not-configured';
@@ -23,6 +23,7 @@ export const GUARD_DIR = `.${config.appName}/guard`;
 export const GUARD_RULES_FILE = `${GUARD_DIR}/rules.json`;
 export const GUARD_BASELINE_FILE = `${GUARD_DIR}/baseline.json`;
 export const GUARD_BASELINE_META_FILE = `${GUARD_DIR}/baseline-meta.json`;
+export const GUARD_WAIVERS_FILE = `${GUARD_DIR}/waivers.json`;
 export const GUARD_PROJECT_FILE = `${GUARD_DIR}/project.json`;
 export const GUARD_HISTORY_DIR = `${GUARD_DIR}/history`;
 export const GUARD_ARCHITECTURE_FILE = `${GUARD_DIR}/architecture.json`;
@@ -44,6 +45,7 @@ export const defaultGuardConfig = {
         allowMcpApproval: true,
         requireDistinctActor: false,
     },
+    waiverPolicy: { warningDays: 14 },
 };
 export const defaultGuardAgentConfig = {
     version: 1,
@@ -86,6 +88,12 @@ export class GuardBaselineReasonError extends Error {
         this.name = 'GuardBaselineReasonError';
     }
 }
+export class GuardWaiverError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'GuardWaiverError';
+    }
+}
 const activeStateLocks = new Map();
 function processIsAlive(pid) {
     try {
@@ -263,7 +271,9 @@ function atomicWriteFile(path, content) {
 }
 function writeGuardArtifactUnlocked(root, relativePath, value) {
     mkdirSync(resolve(root, GUARD_DIR), { recursive: true });
-    atomicWriteFile(resolve(root, relativePath), `${JSON.stringify(value, null, 2)}\n`);
+    const path = resolve(root, relativePath);
+    mkdirSync(dirname(path), { recursive: true });
+    atomicWriteFile(path, `${JSON.stringify(value, null, 2)}\n`);
 }
 function writeGuardArtifact(root, relativePath, value) {
     withGuardStateLock(root, () => writeGuardArtifactUnlocked(root, relativePath, value));
@@ -300,16 +310,136 @@ export function isGuardProposalFile(value) {
 export function fingerprintProjectModel(model) {
     return createHash('sha256').update(JSON.stringify(model)).digest('hex');
 }
+function stableSerialize(value) {
+    if (Array.isArray(value)) {
+        return `[${value.map((item) => stableSerialize(item)).join(',')}]`;
+    }
+    if (value !== null && typeof value === 'object') {
+        const record = value;
+        return `{${Object.keys(record)
+            .sort()
+            .map((key) => `${JSON.stringify(key)}:${stableSerialize(record[key])}`)
+            .join(',')}}`;
+    }
+    return JSON.stringify(value) ?? 'null';
+}
 export function fingerprintGuardConfig(guardConfig) {
     return createHash('sha256')
-        .update(JSON.stringify({
-        rules: guardConfig.rules,
-        contracts: guardConfig.contracts ?? [],
-        budgets: guardConfig.budgets ?? [],
+        .update(stableSerialize({
+        rules: [...guardConfig.rules].sort((left, right) => left.id.localeCompare(right.id)),
+        contracts: [...(guardConfig.contracts ?? [])].sort((left, right) => left.id.localeCompare(right.id)),
+        budgets: [...(guardConfig.budgets ?? [])].sort((left, right) => left.id.localeCompare(right.id)),
         approval: guardConfig.approval ?? defaultGuardConfig.approval,
     }))
         .digest('hex');
 }
+/**
+ * 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 function fingerprintGuardPolicy(guardConfig, baseline = new Set(), waivers = [], agentConfig = defaultGuardAgentConfig) {
+    return createHash('sha256')
+        .update(stableSerialize({
+        config: fingerprintGuardConfig(guardConfig),
+        agentConfig,
+        baseline: [...baseline].sort(),
+        waivers: [...waivers].sort((left, right) => left.id.localeCompare(right.id)),
+    }))
+        .digest('hex');
+}
+export function createGuardPolicySnapshot(guardConfig, baseline, waivers, source = 'working-tree', ref, agentConfig = defaultGuardAgentConfig) {
+    return {
+        config: guardConfig,
+        agentConfig,
+        baseline,
+        waivers,
+        ...(typeof guardConfig.revision === 'number' ? { revision: guardConfig.revision } : {}),
+        fingerprint: fingerprintGuardPolicy(guardConfig, baseline, waivers, agentConfig),
+        source,
+        ...(ref ? { ref } : {}),
+    };
+}
+function readGitFileAtRevision(root, revision, relativePath) {
+    try {
+        return execFileSync('git', ['show', `${revision}:${relativePath}`], {
+            cwd: root,
+            stdio: 'pipe',
+            maxBuffer: 4_000_000,
+        }).toString();
+    }
+    catch {
+        return undefined;
+    }
+}
+function parseGitJsonAtRevision(root, revision, relativePath) {
+    const text = readGitFileAtRevision(root, revision, relativePath);
+    if (text === undefined)
+        return undefined;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new GuardConfigError(`${relativePath} at ${revision}`);
+    }
+}
+/**
+ * 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 function loadGuardPolicyAtRevision(root, revision) {
+    if (!/^[\w./@-]+$/.test(revision) || revision.startsWith('-')) {
+        throw new GuardConfigError(`unsafe policy ref: ${revision}`);
+    }
+    const rulesValue = parseGitJsonAtRevision(root, revision, GUARD_RULES_FILE);
+    if (rulesValue === undefined || !isGuardConfig(rulesValue)) {
+        if (rulesValue === undefined)
+            return undefined;
+        throw new GuardConfigError(`${GUARD_RULES_FILE} at ${revision}`);
+    }
+    const contractsValue = parseGitJsonAtRevision(root, revision, GUARD_CONTRACTS_FILE);
+    if (contractsValue !== undefined && !isGuardContractsFile(contractsValue)) {
+        throw new GuardConfigError(`${GUARD_CONTRACTS_FILE} at ${revision}`);
+    }
+    const guardConfig = {
+        ...rulesValue,
+        contracts: contractsValue ? contractsValue.contracts : (rulesValue.contracts ?? []),
+        budgets: rulesValue.budgets ?? [],
+        approval: rulesValue.approval ?? defaultGuardConfig.approval,
+    };
+    const agentValue = parseGitJsonAtRevision(root, revision, GUARD_AGENT_FILE);
+    const agentConfig = agentValue === undefined
+        ? defaultGuardAgentConfig
+        : // eslint-disable-next-line @typescript-eslint/no-use-before-define
+            isGuardAgentConfig(agentValue)
+                ? agentValue
+                : (() => {
+                    throw new GuardConfigError(`${GUARD_AGENT_FILE} at ${revision}`);
+                })();
+    const baselineValue = parseGitJsonAtRevision(root, revision, GUARD_BASELINE_FILE);
+    const baselineEntries = [];
+    if (baselineValue !== undefined) {
+        if (!Array.isArray(baselineValue)) {
+            throw new GuardConfigError(`${GUARD_BASELINE_FILE} at ${revision}`);
+        }
+        for (const item of baselineValue) {
+            if (typeof item !== 'string') {
+                throw new GuardConfigError(`${GUARD_BASELINE_FILE} at ${revision}`);
+            }
+            baselineEntries.push(item);
+        }
+    }
+    const waiversValue = parseGitJsonAtRevision(root, revision, GUARD_WAIVERS_FILE);
+    const parsedWaivers = guardWaiversFileSchema.safeParse(waiversValue ?? { version: 1, waivers: [], decisions: [] });
+    if (!parsedWaivers.success)
+        throw new GuardConfigError(`${GUARD_WAIVERS_FILE} at ${revision}`);
+    // The validator is declared with the waiver file model below the policy readers.
+    // eslint-disable-next-line @typescript-eslint/no-use-before-define
+    validateGuardWaiversFile(parsedWaivers.data);
+    return createGuardPolicySnapshot(guardConfig, new Set(baselineEntries), parsedWaivers.data.waivers, 'git-ref', revision, agentConfig);
+}
 export function getGuardProposalFreshness(model, proposals) {
     if (!proposals?.projectFingerprint)
         return 'unknown';
@@ -429,6 +559,119 @@ export function loadBaseline(root) {
         throw new GuardConfigError(GUARD_BASELINE_FILE);
     return new Set(value.filter((item) => typeof item === 'string'));
 }
+function validateGuardWaiversFile(value) {
+    const ids = new Set();
+    const fingerprints = new Set();
+    for (const waiver of value.waivers) {
+        if (ids.has(waiver.id))
+            throw new GuardConfigError(GUARD_WAIVERS_FILE);
+        if (fingerprints.has(waiver.fingerprint))
+            throw new GuardConfigError(GUARD_WAIVERS_FILE);
+        if (Date.parse(waiver.expiresAt) <= Date.parse(waiver.createdAt)) {
+            throw new GuardConfigError(GUARD_WAIVERS_FILE);
+        }
+        ids.add(waiver.id);
+        fingerprints.add(waiver.fingerprint);
+    }
+}
+function assertWaiverLifetime(expiresAt, maxLifetimeDays) {
+    if (maxLifetimeDays === undefined)
+        return;
+    const lifetime = Date.parse(expiresAt) - Date.now();
+    if (lifetime > maxLifetimeDays * 24 * 60 * 60 * 1000) {
+        throw new GuardWaiverError(`A waiver may not exceed the configured maximum lifetime of ${maxLifetimeDays} day(s).`);
+    }
+}
+function readGuardWaiversUnlocked(root) {
+    const path = resolve(root, GUARD_WAIVERS_FILE);
+    if (!existsSync(path))
+        return { version: 1, waivers: [], decisions: [] };
+    const parsed = guardWaiversFileSchema.safeParse(readJson(path));
+    if (!parsed.success)
+        throw new GuardConfigError(GUARD_WAIVERS_FILE);
+    validateGuardWaiversFile(parsed.data);
+    return parsed.data;
+}
+export function loadGuardWaivers(root) {
+    if (!existsSync(resolve(root, GUARD_DIR)))
+        return readGuardWaiversUnlocked(root).waivers;
+    return withGuardStateLock(root, () => readGuardWaiversUnlocked(root).waivers);
+}
+export function writeGuardWaivers(root) {
+    withGuardStateLock(root, () => {
+        const file = { version: 1, waivers: [], decisions: [] };
+        atomicWriteFile(resolve(root, GUARD_WAIVERS_FILE), `${JSON.stringify(file, null, 2)}\n`);
+    });
+}
+export function updateGuardWaivers(root, options) {
+    if (!options.reason.trim())
+        throw new GuardWaiverError('A reason is required for waiver changes.');
+    return withGuardStateLock(root, () => {
+        const current = readGuardWaiversUnlocked(root);
+        const index = current.waivers.findIndex((waiver) => waiver.id === options.waiverId);
+        if (options.action === 'add') {
+            if (!options.waiver)
+                throw new GuardWaiverError('A waiver is required when adding one.');
+            if (index >= 0 ||
+                current.waivers.some((waiver) => waiver.fingerprint === options.waiver?.fingerprint)) {
+                throw new GuardWaiverError('A waiver already exists for this id or fingerprint.');
+            }
+            if (Date.parse(options.waiver.expiresAt) <= Date.now()) {
+                throw new GuardWaiverError('A waiver must expire in the future.');
+            }
+            if (Date.parse(options.waiver.expiresAt) <= Date.parse(options.waiver.createdAt)) {
+                throw new GuardWaiverError('A waiver must expire after it is created.');
+            }
+            assertWaiverLifetime(options.waiver.expiresAt, options.maxLifetimeDays);
+            const candidate = guardWaiversFileSchema.safeParse({
+                version: 1,
+                waivers: [...current.waivers, options.waiver],
+                decisions: current.decisions,
+            });
+            if (!candidate.success)
+                throw new GuardWaiverError('The waiver data is invalid.');
+            try {
+                validateGuardWaiversFile(candidate.data);
+            }
+            catch {
+                throw new GuardWaiverError('The waiver data is invalid.');
+            }
+            current.waivers.push(options.waiver);
+        }
+        else {
+            if (index < 0)
+                throw new GuardWaiverError(`Waiver not found: ${options.waiverId}`);
+            if (options.action === 'remove')
+                current.waivers.splice(index, 1);
+            else {
+                if (!options.expiresAt || Date.parse(options.expiresAt) <= Date.now()) {
+                    throw new GuardWaiverError('A renewed waiver must expire in the future.');
+                }
+                assertWaiverLifetime(options.expiresAt, options.maxLifetimeDays);
+                current.waivers[index] = { ...current.waivers[index], expiresAt: options.expiresAt };
+            }
+        }
+        const decision = {
+            at: new Date().toISOString(),
+            action: options.action,
+            waiverId: options.waiverId,
+            reason: options.reason.trim(),
+            ...(options.actor?.trim() ? { actor: options.actor.trim() } : {}),
+        };
+        current.decisions = [...current.decisions, decision].slice(-500);
+        const validated = guardWaiversFileSchema.safeParse(current);
+        if (!validated.success)
+            throw new GuardWaiverError('The waiver data is invalid.');
+        try {
+            validateGuardWaiversFile(validated.data);
+        }
+        catch {
+            throw new GuardWaiverError('The waiver data is invalid.');
+        }
+        atomicWriteFile(resolve(root, GUARD_WAIVERS_FILE), `${JSON.stringify(current, null, 2)}\n`);
+        return current.waivers;
+    });
+}
 export function updateBaseline(root, options = {}) {
     if ((options.add?.length ?? 0) > 0 || (options.remove?.length ?? 0) > 0) {
         if (!options.reason?.trim())
@@ -486,15 +729,24 @@ function buildGuardProposalWithDecisionsUnlocked(root, decisions, options) {
             return undefined;
         }
     })();
+    const currentRevision = readGuardConfigFilesUnlocked(root)?.revision ?? 0;
+    const policyFingerprint = options.resultingPolicy
+        ? fingerprintGuardPolicy(options.resultingPolicy, loadBaseline(root), readGuardWaiversUnlocked(root).waivers, loadGuardAgentConfig(root))
+        : undefined;
     const nextDecisions = decisions.map((decision) => ({
         ...decision,
+        decisionId: randomUUID(),
         decidedAt,
         source: options.source,
         ...(process.env.GUARD_APPROVER?.trim() ? { actor: process.env.GUARD_APPROVER.trim() } : {}),
         ...(commit ? { commit } : {}),
+        ...(proposals.generatedBy ? { proposalAuthor: proposals.generatedBy } : {}),
         ...(proposals.proposalId ? { proposalId: proposals.proposalId } : {}),
         ...(proposals.contentFingerprint ? { proposalFingerprint: proposals.contentFingerprint } : {}),
         ...(typeof proposals.revision === 'number' ? { revision: proposals.revision } : {}),
+        ...(decision.decision === 'approved' && policyFingerprint
+            ? { policyFingerprint, policyRevision: currentRevision + 1 }
+            : {}),
     }));
     return {
         ...proposals,
@@ -514,7 +766,10 @@ export function recordGuardProposalDecision(root, decisions, options = { source:
 }
 export function applyGuardProposalDecision(root, guardConfig, decisions, options) {
     withGuardStateLock(root, () => {
-        const proposals = buildGuardProposalWithDecisionsUnlocked(root, decisions, options);
+        const proposals = buildGuardProposalWithDecisionsUnlocked(root, decisions, {
+            ...options,
+            resultingPolicy: guardConfig,
+        });
         writeGuardArtifactUnlocked(root, GUARD_POLICY_TRANSACTION_FILE, {
             version: 1,
             createdAt: new Date().toISOString(),
@@ -986,6 +1241,23 @@ export function validateGuardBudgets(root, budgets = []) {
 }
 export function validateGuardPolicy(root, guardConfig) {
     const issues = [];
+    const validateUniqueIds = (items, kind) => {
+        const seen = new Set();
+        for (const item of items) {
+            if (seen.has(item.id)) {
+                issues.push({
+                    contractId: `${kind}:${item.id}`,
+                    field: 'definition',
+                    value: item.id,
+                    message: `${kind} IDs must be unique: ${item.id}`,
+                });
+            }
+            seen.add(item.id);
+        }
+    };
+    validateUniqueIds(guardConfig.rules, 'rule');
+    validateUniqueIds(guardConfig.contracts ?? [], 'contract');
+    validateUniqueIds(guardConfig.budgets ?? [], 'budget');
     for (const rule of guardConfig.rules) {
         for (const file of rule.files ?? []) {
             if (!isProjectPath(root, file)) {
@@ -1538,12 +1810,45 @@ export function scanGuard(root, guardConfig, options = {}) {
         ...(options.includeArchitectureInsights ? architectureInsightFindings(root, scope) : []),
     ];
     const baseline = options.baseline ?? new Set();
-    const findings = allFindings.filter((finding) => !baseline.has(finding.fingerprint));
+    const waivers = options.waivers ?? loadGuardWaivers(root);
+    if (options.waivers) {
+        const parsedWaivers = guardWaiversFileSchema.safeParse({
+            version: 1,
+            waivers,
+            decisions: [],
+        });
+        if (!parsedWaivers.success)
+            throw new GuardWaiverError('The waiver data is invalid.');
+        try {
+            validateGuardWaiversFile(parsedWaivers.data);
+        }
+        catch {
+            throw new GuardWaiverError('The waiver data is invalid.');
+        }
+    }
+    const nowValue = options.now ?? new Date().toISOString();
+    const now = Date.parse(nowValue);
+    if (!Number.isFinite(now))
+        throw new GuardWaiverError(`Invalid Guard time: ${nowValue}`);
+    const activeWaivers = new Map(waivers
+        .filter((waiver) => Date.parse(waiver.expiresAt) > now)
+        .map((waiver) => [waiver.fingerprint, waiver]));
+    const warningDays = guardConfig.waiverPolicy?.warningDays ?? 14;
+    const warningLimit = now + warningDays * 24 * 60 * 60 * 1000;
+    const currentFingerprints = new Set(allFindings.map((finding) => finding.fingerprint));
+    const relevantWaivers = waivers.filter((waiver) => currentFingerprints.has(waiver.fingerprint));
+    const waiverWarnings = relevantWaivers.filter((waiver) => Date.parse(waiver.expiresAt) > now && Date.parse(waiver.expiresAt) <= warningLimit);
+    const expiredWaivers = relevantWaivers.filter((waiver) => Date.parse(waiver.expiresAt) <= now);
+    const baselineFindings = allFindings.filter((finding) => !baseline.has(finding.fingerprint));
+    const findings = baselineFindings.filter((finding) => !activeWaivers.has(finding.fingerprint));
     return {
         configured: true,
         findings,
         suppressed: allFindings.length - findings.length,
         scannedFiles: files.length,
+        waived: baselineFindings.length - findings.length,
+        waiverWarnings,
+        expiredWaivers,
     };
 }
 export function buildGuardReviewPacket(root, guardConfig, baseline = new Set(), maxDiffChars = 120_000, changedOnly = true, requirement, base) {
@@ -1570,6 +1875,9 @@ export function buildGuardReviewPacket(root, guardConfig, baseline = new Set(),
         contracts: guardConfig.contracts ?? [],
         ...(requirement ? { requirement } : {}),
         deterministicFindings: report.findings,
+        waived: report.waived,
+        waiverWarnings: report.waiverWarnings,
+        expiredWaivers: report.expiredWaivers,
         impact,
         reviewInstructions: [
             ...(requirement
@@ -1595,6 +1903,9 @@ export function initializeGuard(root, options = {}) {
         const guardConfig = loadGuardConfig(root) ?? buildGeneratedGuardConfig(projectModel);
         ensureGeneratedStateIgnored(root, projectModel);
         writeGuardConfig(root, guardConfig);
+        if (options.force || !existsSync(resolve(root, GUARD_WAIVERS_FILE))) {
+            writeGuardWaivers(root);
+        }
         if (options.force || !existsSync(resolve(root, GUARD_AGENT_FILE))) {
             writeGuardAgentConfig(root);
         }

package/dist/core/history/runs.d.ts

@@ -5,6 +5,14 @@ export interface GuardRunStage {
     status: 'ok' | 'fail' | 'skipped';
     detail?: string | undefined;
 }
+export interface GuardRunPolicy {
+    revision?: number | undefined;
+    fingerprint: string;
+    source: 'working-tree' | 'git-ref';
+    ref?: string | undefined;
+    changedFromBase?: boolean | undefined;
+    decisionIds?: string[] | undefined;
+}
 export interface GuardRunManifest {
     version: 1;
     runId: string;
@@ -16,6 +24,7 @@ export interface GuardRunManifest {
     gate: string;
     stages: Record<string, GuardRunStage>;
     commit?: string | undefined;
+    policy?: GuardRunPolicy | undefined;
 }
 export interface GuardRunContext {
     runId: string;
@@ -40,4 +49,4 @@ export declare function writeGuardRun(root: string, manifest: GuardRunManifest):
 /** Reads locally persisted run manifests without reaching a remote service. */
 export declare function listGuardRuns(root: string, limit?: number): GuardRunManifest[];
 export declare function summarizeGuardRuns(root: string, limit?: number): GuardRunSummary;
-export declare function finishGuardRun(root: string, context: GuardRunContext, outcome: GuardRunManifest['outcome'], gate: string, command?: string): GuardRunManifest;
+export declare function finishGuardRun(root: string, context: GuardRunContext, outcome: GuardRunManifest['outcome'], gate: string, command?: string, policy?: GuardRunPolicy): GuardRunManifest;

package/dist/core/history/runs.js

@@ -33,7 +33,22 @@ function isGuardRunManifest(value) {
             manifest.outcome === 'not-configured') &&
         typeof manifest.gate === 'string' &&
         manifest.stages !== null &&
-        typeof manifest.stages === 'object');
+        typeof manifest.stages === 'object' &&
+        (manifest.policy === undefined ||
+            (manifest.policy !== null &&
+                typeof manifest.policy === 'object' &&
+                typeof manifest.policy.fingerprint === 'string' &&
+                manifest.policy.fingerprint.length > 0 &&
+                (manifest.policy.source === 'working-tree' || manifest.policy.source === 'git-ref') &&
+                (manifest.policy.revision === undefined ||
+                    (Number.isInteger(manifest.policy.revision) && manifest.policy.revision >= 0)) &&
+                (manifest.policy.ref === undefined || typeof manifest.policy.ref === 'string') &&
+                (manifest.policy.changedFromBase === undefined ||
+                    typeof manifest.policy.changedFromBase === 'boolean') &&
+                (manifest.policy.decisionIds === undefined ||
+                    (Array.isArray(manifest.policy.decisionIds) &&
+                        new Set(manifest.policy.decisionIds).size === manifest.policy.decisionIds.length &&
+                        manifest.policy.decisionIds.every((decisionId) => typeof decisionId === 'string' && decisionId.trim().length > 0))))));
 }
 export function startGuardRun() {
     return {
@@ -122,7 +137,7 @@ export function summarizeGuardRuns(root, limit = 100) {
         ...(total > 0 ? { last: runs[0] } : {}),
     };
 }
-export function finishGuardRun(root, context, outcome, gate, command = 'verify') {
+export function finishGuardRun(root, context, outcome, gate, command = 'verify', policy) {
     let commit;
     try {
         commit = execFileSync('git', ['rev-parse', 'HEAD'], { cwd: root, stdio: 'pipe' })
@@ -143,6 +158,7 @@ export function finishGuardRun(root, context, outcome, gate, command = 'verify')
         gate,
         stages: context.stages,
         ...(commit ? { commit } : {}),
+        ...(policy ? { policy } : {}),
     };
     try {
         writeGuardRun(root, manifest);

package/dist/core/model/types.d.ts

@@ -5,6 +5,28 @@ export type GuardRuleStatus = 'active' | 'proposed';
 export type GuardContractKind = 'guidance' | 'import-boundary' | 'required-call' | 'package-boundary';
 export type GuardBudgetMetric = 'lines' | 'bytes' | 'imports';
 export type GuardToolMode = 'auto' | 'on' | 'off';
+export interface GuardWaiver {
+    id: string;
+    fingerprint: string;
+    ruleId: string;
+    owner: string;
+    reason: string;
+    createdAt: string;
+    expiresAt: string;
+    issue?: string | undefined;
+    approvedBy?: string | undefined;
+}
+export interface GuardWaiverPolicy {
+    warningDays: number;
+    maxDays?: number | undefined;
+}
+export interface GuardWaiverDecision {
+    at: string;
+    action: 'add' | 'renew' | 'remove';
+    waiverId: string;
+    reason: string;
+    actor?: string | undefined;
+}
 export type GuardApprovalMode = 'local' | 'protected';
 export type GuardAdapterName = 'dependency-graph' | 'security' | 'dependency-hygiene' | 'sast' | 'secret-scanning' | 'dependency-audit';
 export type ProjectCheck = 'lint' | 'typecheck' | 'test' | 'build';

package/dist/core/output/sarif.d.ts

@@ -1,11 +1,16 @@
 import type { GuardFinding } from '../guard.js';
+export interface GuardSarifNotice {
+    ruleId: string;
+    level: 'error' | 'warning' | 'note';
+    message: string;
+}
 interface SarifResult {
     ruleId: string;
     level: 'error' | 'warning' | 'note';
     message: {
         text: string;
     };
-    locations: [
+    locations?: [
         {
             physicalLocation: {
                 artifactLocation: {
@@ -31,5 +36,5 @@ export interface SarifLog {
         results: SarifResult[];
     }];
 }
-export declare function guardFindingsToSarif(findings: GuardFinding[]): SarifLog;
+export declare function guardFindingsToSarif(findings: GuardFinding[], notices?: GuardSarifNotice[]): SarifLog;
 export {};

package/dist/core/output/sarif.js

@@ -1,4 +1,25 @@
-export function guardFindingsToSarif(findings) {
+export function guardFindingsToSarif(findings, notices = []) {
+    const findingResults = findings.map((finding) => ({
+        ruleId: finding.ruleId,
+        level: finding.severity === 'info' ? 'note' : finding.severity,
+        message: { text: finding.message },
+        locations: [
+            {
+                physicalLocation: {
+                    artifactLocation: { uri: finding.file },
+                    region: { startLine: finding.line },
+                },
+            },
+        ],
+    }));
+    const results = [
+        ...findingResults,
+        ...notices.map((notice) => ({
+            ruleId: notice.ruleId,
+            level: notice.level,
+            message: { text: notice.message },
+        })),
+    ];
     return {
         version: '2.1.0',
         $schema: 'https://json.schemastore.org/sarif-2.1.0.json',
@@ -10,19 +31,7 @@ export function guardFindingsToSarif(findings) {
                         informationUri: 'https://codapult.dev/docs/developer-tools/guard',
                     },
                 },
-                results: findings.map((finding) => ({
-                    ruleId: finding.ruleId,
-                    level: finding.severity === 'info' ? 'note' : finding.severity,
-                    message: { text: finding.message },
-                    locations: [
-                        {
-                            physicalLocation: {
-                                artifactLocation: { uri: finding.file },
-                                region: { startLine: finding.line },
-                            },
-                        },
-                    ],
-                })),
+                results,
             },
         ],
     };