@shrkcrft/inspector 0.1.0-alpha.2

package/dist/policy-engine.d.ts

@@ -0,0 +1,101 @@
+import type { ISharkcraftInspection } from './sharkcraft-inspector.js';
+export declare const POLICY_REPORT_SCHEMA = "sharkcraft.policy-report/v1";
+export declare enum PolicySeverity {
+    Info = "info",
+    Warning = "warning",
+    Error = "error",
+    Critical = "critical"
+}
+export declare enum PolicyCheckType {
+    Path = "path",
+    Import = "import",
+    Ownership = "ownership",
+    Command = "command",
+    Template = "template",
+    Plan = "plan",
+    Bundle = "bundle",
+    Session = "session"
+}
+export interface IPolicyCheck {
+    id: string;
+    title: string;
+    severity: PolicySeverity;
+    checkType: PolicyCheckType;
+    message: string;
+    suggestedFix?: string;
+    relatedRules?: readonly string[];
+    relatedPathConventions?: readonly string[];
+    context?: Record<string, unknown>;
+}
+/**
+ * Shape packs export from `policyCheckFiles`. Each declaration runs the
+ * given predicate against the current inspection + (optional) plan/bundle
+ * targets and contributes zero or more checks to the report.
+ *
+ * Predicates are pure functions of inspection state — no shell, no network.
+ */
+export interface IPackPolicyCheck {
+    id: string;
+    title: string;
+    severity?: PolicySeverity;
+    checkType?: PolicyCheckType;
+    /**
+     * Return one of:
+     *  - boolean `true`  → passing (no check emitted)
+     *  - boolean `false` → failing (emit a default check)
+     *  - object          → custom message / suggestedFix / context
+     */
+    evaluate: (input: {
+        projectRoot: string;
+        planTargets: readonly string[];
+        bundleAffectedFiles: readonly string[];
+    }) => boolean | {
+        message: string;
+        suggestedFix?: string;
+        context?: Record<string, unknown>;
+    };
+}
+export interface IPolicyCheckRegistration {
+    id: string;
+    title: string;
+    severity: PolicySeverity;
+    checkType: PolicyCheckType;
+    source: 'local' | 'pack';
+    sourceFile: string;
+    packName?: string;
+    signatureStatus?: string;
+}
+export interface IPolicyReport {
+    schema: typeof POLICY_REPORT_SCHEMA;
+    generatedAt: string;
+    projectRoot: string;
+    checks: readonly IPolicyCheck[];
+    registrations: readonly IPolicyCheckRegistration[];
+    summary: {
+        info: number;
+        warning: number;
+        error: number;
+        critical: number;
+        passed: boolean;
+    };
+}
+export interface IPolicyEvaluateInput {
+    /** Optional explicit plan file to evaluate. */
+    planFile?: string;
+    /** Optional bundle id. */
+    bundleId?: string;
+    /** Optional session id. */
+    sessionId?: string;
+    /** Optional configured ownership files. */
+    ownershipFiles?: readonly string[];
+    /** Skip pack-contributed policy checks. Default false. */
+    skipPackPolicies?: boolean;
+    /** Require packs that contribute policy checks to be signed-and-verified. */
+    requireSignedPolicyPacks?: boolean;
+    /** Override the local policy files list. Default: ['sharkcraft/policies.ts']. */
+    localPolicyFiles?: readonly string[];
+    /** When provided, only evaluate this single registered policy id. */
+    onlyId?: string;
+}
+export declare function evaluatePolicy(inspection: ISharkcraftInspection, input?: IPolicyEvaluateInput): Promise<IPolicyReport>;
+//# sourceMappingURL=policy-engine.d.ts.map

package/dist/policy-engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy-engine.d.ts","sourceRoot":"","sources":["../src/policy-engine.ts"],"names":[],"mappings":"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"}

package/dist/policy-engine.js

@@ -0,0 +1,321 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { existsSync, readFileSync } from 'node:fs';
+import * as nodePath from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { evaluateBoundaries, loadTsconfigPaths, scanImports } from '@shrkcrft/boundaries';
+import { impactFor, loadOwnershipRules } from "./ownership.js";
+export const POLICY_REPORT_SCHEMA = 'sharkcraft.policy-report/v1';
+export var PolicySeverity;
+(function (PolicySeverity) {
+    PolicySeverity["Info"] = "info";
+    PolicySeverity["Warning"] = "warning";
+    PolicySeverity["Error"] = "error";
+    PolicySeverity["Critical"] = "critical";
+})(PolicySeverity || (PolicySeverity = {}));
+export var PolicyCheckType;
+(function (PolicyCheckType) {
+    PolicyCheckType["Path"] = "path";
+    PolicyCheckType["Import"] = "import";
+    PolicyCheckType["Ownership"] = "ownership";
+    PolicyCheckType["Command"] = "command";
+    PolicyCheckType["Template"] = "template";
+    PolicyCheckType["Plan"] = "plan";
+    PolicyCheckType["Bundle"] = "bundle";
+    PolicyCheckType["Session"] = "session";
+})(PolicyCheckType || (PolicyCheckType = {}));
+function nowIso() {
+    return new Date().toISOString();
+}
+export async function evaluatePolicy(inspection, input = {}) {
+    const cwd = inspection.projectRoot;
+    const checks = [];
+    const registrations = [];
+    // 1) Boundary violations.
+    if (inspection.boundaryRegistry.size() > 0) {
+        try {
+            const scan = scanImports({ projectRoot: cwd });
+            const tsconfigPaths = loadTsconfigPaths(cwd);
+            const evalResult = evaluateBoundaries(scan, inspection.boundaryRegistry.list(), {
+                ...(tsconfigPaths.aliases.size > 0 ? { tsconfigPaths } : {}),
+            });
+            for (const v of evalResult.violations.slice(0, 200)) {
+                checks.push({
+                    id: `boundary:${v.ruleId}:${v.file}:${v.line}`,
+                    title: `Boundary violation: ${v.ruleId}`,
+                    severity: v.severity === 'error' ? PolicySeverity.Error : PolicySeverity.Warning,
+                    checkType: PolicyCheckType.Import,
+                    message: `${v.file}:${v.line} imports ${v.importSpecifier} — ${v.message}`,
+                    relatedRules: [v.ruleId],
+                });
+            }
+        }
+        catch (e) {
+            checks.push({
+                id: 'boundary:scan-failed',
+                title: 'Boundary scan failed',
+                severity: PolicySeverity.Warning,
+                checkType: PolicyCheckType.Import,
+                message: e.message,
+            });
+        }
+    }
+    // 2) Forbidden actions (from action hints) — surface as informational checks
+    //    so the agent sees them in the policy report.
+    const allForbidden = new Set();
+    for (const e of inspection.knowledgeEntries) {
+        const hints = e.actionHints;
+        for (const a of hints?.forbiddenActions ?? [])
+            allForbidden.add(a);
+    }
+    for (const f of allForbidden) {
+        checks.push({
+            id: `forbidden:${hash(f)}`,
+            title: 'Forbidden action documented',
+            severity: PolicySeverity.Info,
+            checkType: PolicyCheckType.Command,
+            message: f,
+        });
+    }
+    // 3) Ownership-required reviews for an explicit plan (best-effort).
+    if (input.planFile) {
+        const planTargets = extractPlanTargets(cwd, input.planFile);
+        const { rules } = await loadOwnershipRules(cwd, input.ownershipFiles);
+        if (rules.length > 0 && planTargets.length > 0) {
+            const impact = impactFor(planTargets, rules);
+            if (impact.requiredReviewFiles.length > 0) {
+                checks.push({
+                    id: 'ownership:required-review',
+                    title: 'Ownership requires review',
+                    severity: PolicySeverity.Warning,
+                    checkType: PolicyCheckType.Ownership,
+                    message: `Plan touches ${impact.requiredReviewFiles.length} file(s) with requiredReview owners.`,
+                    context: { files: impact.requiredReviewFiles, owners: impact.owners },
+                });
+            }
+        }
+    }
+    // 4) Unsigned plan check.
+    if (input.planFile) {
+        try {
+            const planPath = nodePath.isAbsolute(input.planFile)
+                ? input.planFile
+                : nodePath.join(cwd, input.planFile);
+            if (existsSync(planPath)) {
+                const parsed = JSON.parse(readFileSync(planPath, 'utf8'));
+                if (!parsed.signature) {
+                    checks.push({
+                        id: 'plan:unsigned',
+                        title: 'Plan is unsigned',
+                        severity: PolicySeverity.Warning,
+                        checkType: PolicyCheckType.Plan,
+                        message: `${input.planFile} has no signature.`,
+                        suggestedFix: 'Sign with `shrk plan sign <plan.json>` or generate with --sign.',
+                    });
+                }
+            }
+        }
+        catch {
+            /* ignore */
+        }
+    }
+    // 5) Pack signature gate (if any pack is unverified).
+    for (const pack of inspection.packs.validPacks ?? []) {
+        const status = pack.signatureStatus;
+        if (status && status !== 'verified' && status !== 'not-checked') {
+            checks.push({
+                id: `pack:unverified:${pack.packageName}`,
+                title: 'Pack signature not verified',
+                severity: PolicySeverity.Warning,
+                checkType: PolicyCheckType.Bundle,
+                message: `Pack ${pack.packageName} signature status: ${status}`,
+            });
+        }
+    }
+    // 6) Pack-contributed + local policy checks.
+    const planTargets = input.planFile
+        ? extractPlanTargets(cwd, input.planFile)
+        : [];
+    let bundleAffectedFiles = [];
+    if (input.bundleId) {
+        try {
+            const { readFeatureBundle } = await import("./feature-bundle.js");
+            const b = readFeatureBundle(cwd, input.bundleId);
+            if (b)
+                bundleAffectedFiles = b.affectedFiles;
+        }
+        catch {
+            /* ignore */
+        }
+    }
+    const runDecl = (d, reg) => {
+        registrations.push(reg);
+        if (input.onlyId && reg.id !== input.onlyId)
+            return;
+        let result;
+        try {
+            result = d.evaluate({ projectRoot: cwd, planTargets, bundleAffectedFiles });
+        }
+        catch (e) {
+            checks.push({
+                id: `${reg.id}:error`,
+                title: d.title,
+                severity: PolicySeverity.Warning,
+                checkType: d.checkType ?? PolicyCheckType.Path,
+                message: `Policy check threw: ${e.message}`,
+            });
+            return;
+        }
+        if (result === true)
+            return;
+        const detail = typeof result === 'object' ? result : { message: 'Policy check failed' };
+        checks.push({
+            id: reg.id,
+            title: d.title,
+            severity: d.severity ?? PolicySeverity.Warning,
+            checkType: d.checkType ?? PolicyCheckType.Path,
+            message: detail.message,
+            ...(detail.suggestedFix ? { suggestedFix: detail.suggestedFix } : {}),
+            ...(detail.context ? { context: detail.context } : {}),
+        });
+    };
+    // 6a) Local policy file(s).
+    const localFiles = input.localPolicyFiles ?? ['sharkcraft/policies.ts'];
+    for (const rel of localFiles) {
+        const full = nodePath.isAbsolute(rel) ? rel : nodePath.join(cwd, rel);
+        if (!existsSync(full))
+            continue;
+        try {
+            const mod = (await import(__rewriteRelativeImportExtension(pathToFileURL(full).href)));
+            const decls = mod.default ?? mod.policyChecks ?? [];
+            for (const d of decls) {
+                runDecl(d, {
+                    id: `local:${d.id}`,
+                    title: d.title,
+                    severity: d.severity ?? PolicySeverity.Warning,
+                    checkType: d.checkType ?? PolicyCheckType.Path,
+                    source: 'local',
+                    sourceFile: full,
+                });
+            }
+        }
+        catch (e) {
+            checks.push({
+                id: `local:policy:load-failed:${nodePath.basename(full)}`,
+                title: 'Local policy check load failed',
+                severity: PolicySeverity.Warning,
+                checkType: PolicyCheckType.Bundle,
+                message: `${full}: ${e.message}`,
+            });
+        }
+    }
+    // 6b) Pack-contributed policy files (skippable for safety).
+    if (!input.skipPackPolicies) {
+        for (const pack of inspection.packs.validPacks ?? []) {
+            const c = pack.manifest?.contributions;
+            const files = c?.policyCheckFiles ?? [];
+            if (files.length === 0)
+                continue;
+            const sigStatus = pack.signatureStatus;
+            const verified = sigStatus === 'verified';
+            if (input.requireSignedPolicyPacks && !verified) {
+                checks.push({
+                    id: `pack:policy:unsigned:${pack.packageName}`,
+                    title: 'Pack policy file requires signature',
+                    severity: PolicySeverity.Warning,
+                    checkType: PolicyCheckType.Bundle,
+                    message: `Pack ${pack.packageName} contributes policy checks but signature status is ${sigStatus ?? 'unknown'}; skipping per --require-signed-policy-packs.`,
+                });
+                continue;
+            }
+            if (!verified) {
+                // Always emit a soft warning when an unsigned pack contributes policy
+                // checks so the operator notices the trust boundary.
+                checks.push({
+                    id: `pack:policy:warn-unsigned:${pack.packageName}`,
+                    title: 'Unsigned pack contributes policy checks',
+                    severity: PolicySeverity.Info,
+                    checkType: PolicyCheckType.Bundle,
+                    message: `Pack ${pack.packageName} contributes policy checks but signature status is ${sigStatus ?? 'unknown'}.`,
+                });
+            }
+            for (const rel of files) {
+                const full = nodePath.resolve(pack.packageRoot, rel);
+                if (!existsSync(full))
+                    continue;
+                try {
+                    const mod = (await import(__rewriteRelativeImportExtension(pathToFileURL(full).href)));
+                    const decls = mod.default ?? mod.policyChecks ?? [];
+                    for (const d of decls) {
+                        runDecl(d, {
+                            id: `pack:${pack.packageName}:${d.id}`,
+                            title: d.title,
+                            severity: d.severity ?? PolicySeverity.Warning,
+                            checkType: d.checkType ?? PolicyCheckType.Path,
+                            source: 'pack',
+                            sourceFile: full,
+                            packName: pack.packageName,
+                            ...(sigStatus ? { signatureStatus: sigStatus } : {}),
+                        });
+                    }
+                }
+                catch (e) {
+                    checks.push({
+                        id: `pack:${pack.packageName}:policy:load-failed`,
+                        title: 'Pack policy check load failed',
+                        severity: PolicySeverity.Warning,
+                        checkType: PolicyCheckType.Bundle,
+                        message: `${pack.packageName} (${rel}): ${e.message}`,
+                    });
+                }
+            }
+        }
+    }
+    const summary = { info: 0, warning: 0, error: 0, critical: 0, passed: true };
+    for (const c of checks) {
+        if (c.severity === PolicySeverity.Info)
+            summary.info += 1;
+        else if (c.severity === PolicySeverity.Warning)
+            summary.warning += 1;
+        else if (c.severity === PolicySeverity.Error)
+            summary.error += 1;
+        else if (c.severity === PolicySeverity.Critical)
+            summary.critical += 1;
+    }
+    summary.passed = summary.error === 0 && summary.critical === 0;
+    return {
+        schema: POLICY_REPORT_SCHEMA,
+        generatedAt: nowIso(),
+        projectRoot: cwd,
+        checks,
+        registrations,
+        summary,
+    };
+}
+function extractPlanTargets(cwd, planFile) {
+    try {
+        const planPath = nodePath.isAbsolute(planFile) ? planFile : nodePath.join(cwd, planFile);
+        if (!existsSync(planPath))
+            return [];
+        const parsed = JSON.parse(readFileSync(planPath, 'utf8'));
+        const changes = parsed.changes ?? parsed.plan?.changes ?? [];
+        return changes
+            .map((c) => c.relativePath ?? c.path ?? c.targetPath ?? '')
+            .filter((s) => Boolean(s));
+    }
+    catch {
+        return [];
+    }
+}
+function hash(s) {
+    let h = 0;
+    for (let i = 0; i < s.length; i += 1)
+        h = (h * 31 + s.charCodeAt(i)) | 0;
+    return Math.abs(h).toString(36);
+}

package/dist/policy-override-audit.d.ts

@@ -0,0 +1,18 @@
+import type { ISharkcraftInspection } from './sharkcraft-inspector.js';
+import type { PolicySeverity } from './policy-engine.js';
+export declare const POLICY_OVERRIDE_AUDIT_SCHEMA = "sharkcraft.policy-override-audit/v1";
+export interface IPolicyOverrideAuditEntry {
+    schema: typeof POLICY_OVERRIDE_AUDIT_SCHEMA;
+    timestamp: string;
+    policyId: string;
+    originalSeverity?: PolicySeverity;
+    effectiveSeverity?: PolicySeverity;
+    disabled: boolean;
+    reason?: string;
+    sourceConfig: string;
+    command: string;
+}
+export declare function policyOverrideAuditPath(projectRoot: string): string;
+export declare function readPolicyOverrideAudit(inspection: ISharkcraftInspection): readonly IPolicyOverrideAuditEntry[];
+export declare function appendPolicyOverrideAudit(inspection: ISharkcraftInspection, entries: readonly Omit<IPolicyOverrideAuditEntry, 'schema' | 'timestamp'>[]): string;
+//# sourceMappingURL=policy-override-audit.d.ts.map

package/dist/policy-override-audit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy-override-audit.d.ts","sourceRoot":"","sources":["../src/policy-override-audit.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AACvE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAEzD,eAAO,MAAM,4BAA4B,wCAAwC,CAAC;AAElF,MAAM,WAAW,yBAAyB;IACxC,MAAM,EAAE,OAAO,4BAA4B,CAAC;IAC5C,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,gBAAgB,CAAC,EAAE,cAAc,CAAC;IAClC,iBAAiB,CAAC,EAAE,cAAc,CAAC;IACnC,QAAQ,EAAE,OAAO,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;CACjB;AAID,wBAAgB,uBAAuB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAEnE;AAED,wBAAgB,uBAAuB,CACrC,UAAU,EAAE,qBAAqB,GAChC,SAAS,yBAAyB,EAAE,CAkBtC;AAED,wBAAgB,yBAAyB,CACvC,UAAU,EAAE,qBAAqB,EACjC,OAAO,EAAE,SAAS,IAAI,CAAC,yBAAyB,EAAE,QAAQ,GAAG,WAAW,CAAC,EAAE,GAC1E,MAAM,CAgBR"}

package/dist/policy-override-audit.js

@@ -0,0 +1,54 @@
+/**
+ * Policy override audit trail.
+ *
+ * Append-only log of policy override events. Lives at
+ * `.sharkcraft/policy-override-audit.log` (one JSON entry per line).
+ *
+ * Only written when the caller explicitly opts in
+ * (`--record-override-audit`). Read-only by default.
+ */
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs';
+import * as nodePath from 'node:path';
+export const POLICY_OVERRIDE_AUDIT_SCHEMA = 'sharkcraft.policy-override-audit/v1';
+const LOG_PATH = ['.sharkcraft', 'policy-override-audit.log'];
+export function policyOverrideAuditPath(projectRoot) {
+    return nodePath.join(projectRoot, ...LOG_PATH);
+}
+export function readPolicyOverrideAudit(inspection) {
+    const file = policyOverrideAuditPath(inspection.projectRoot);
+    if (!existsSync(file))
+        return [];
+    try {
+        const lines = readFileSync(file, 'utf8').split('\n').filter(Boolean);
+        const out = [];
+        for (const line of lines) {
+            try {
+                const obj = JSON.parse(line);
+                if (obj && typeof obj.policyId === 'string')
+                    out.push(obj);
+            }
+            catch {
+                continue;
+            }
+        }
+        return out;
+    }
+    catch {
+        return [];
+    }
+}
+export function appendPolicyOverrideAudit(inspection, entries) {
+    const file = policyOverrideAuditPath(inspection.projectRoot);
+    mkdirSync(nodePath.dirname(file), { recursive: true });
+    const now = new Date().toISOString();
+    const body = entries
+        .map((e) => JSON.stringify({
+        schema: POLICY_OVERRIDE_AUDIT_SCHEMA,
+        timestamp: now,
+        ...e,
+    }) + '\n')
+        .join('');
+    if (body.length > 0)
+        appendFileSync(file, body, 'utf8');
+    return file;
+}

package/dist/policy-overrides.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Policy severity overrides.
+ *
+ * Local config can override the severity (or enable/disable) of
+ * pack-contributed or local policy checks. Overrides are visible in
+ * the report and always have a reason field.
+ *
+ * Source: `sharkcraft.config.ts` `policyOverrides` array.
+ */
+import type { ISharkcraftInspection } from './sharkcraft-inspector.js';
+import { type IPolicyReport, PolicySeverity } from './policy-engine.js';
+export declare const POLICY_OVERRIDES_SCHEMA = "sharkcraft.policy-overrides/v1";
+export interface IPolicyOverride {
+    policyId: string;
+    severity?: PolicySeverity;
+    enabled?: boolean;
+    reason?: string;
+}
+export interface IPolicyOverridesReport {
+    schema: typeof POLICY_OVERRIDES_SCHEMA;
+    overrides: readonly IPolicyOverride[];
+    applied: readonly {
+        policyId: string;
+        appliedSeverity?: PolicySeverity;
+        originalSeverity?: PolicySeverity;
+        disabled?: boolean;
+        reason?: string;
+    }[];
+}
+export declare function listPolicyOverrides(inspection: ISharkcraftInspection): readonly IPolicyOverride[];
+export declare function applyPolicyOverrides(report: IPolicyReport, overrides: readonly IPolicyOverride[]): {
+    report: IPolicyReport;
+    explain: IPolicyOverridesReport;
+};
+//# sourceMappingURL=policy-overrides.d.ts.map

package/dist/policy-overrides.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy-overrides.d.ts","sourceRoot":"","sources":["../src/policy-overrides.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AACvE,OAAO,EAEL,KAAK,aAAa,EAClB,cAAc,EACf,MAAM,oBAAoB,CAAC;AAE5B,eAAO,MAAM,uBAAuB,mCAAmC,CAAC;AAExE,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,OAAO,uBAAuB,CAAC;IACvC,SAAS,EAAE,SAAS,eAAe,EAAE,CAAC;IACtC,OAAO,EAAE,SAAS;QAChB,QAAQ,EAAE,MAAM,CAAC;QACjB,eAAe,CAAC,EAAE,cAAc,CAAC;QACjC,gBAAgB,CAAC,EAAE,cAAc,CAAC;QAClC,QAAQ,CAAC,EAAE,OAAO,CAAC;QACnB,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,EAAE,CAAC;CACL;AAiBD,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,qBAAqB,GAAG,SAAS,eAAe,EAAE,CAEjG;AAED,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,aAAa,EACrB,SAAS,EAAE,SAAS,eAAe,EAAE,GACpC;IAAE,MAAM,EAAE,aAAa,CAAC;IAAC,OAAO,EAAE,sBAAsB,CAAA;CAAE,CA8D5D"}

package/dist/policy-overrides.js

@@ -0,0 +1,84 @@
+import { PolicySeverity, } from "./policy-engine.js";
+export const POLICY_OVERRIDES_SCHEMA = 'sharkcraft.policy-overrides/v1';
+function readOverridesFromConfig(inspection) {
+    const cfg = inspection.config;
+    if (!cfg || !Array.isArray(cfg.policyOverrides))
+        return [];
+    const out = [];
+    for (const o of cfg.policyOverrides) {
+        if (typeof o.policyId !== 'string' || o.policyId.length === 0)
+            continue;
+        const override = { policyId: o.policyId };
+        if (o.severity)
+            override.severity = o.severity;
+        if (typeof o.enabled === 'boolean')
+            override.enabled = o.enabled;
+        if (typeof o.reason === 'string')
+            override.reason = o.reason;
+        out.push(override);
+    }
+    return out;
+}
+export function listPolicyOverrides(inspection) {
+    return readOverridesFromConfig(inspection);
+}
+export function applyPolicyOverrides(report, overrides) {
+    const byId = new Map();
+    for (const o of overrides)
+        byId.set(o.policyId, o);
+    const applied = [];
+    const checks = [];
+    for (const c of report.checks) {
+        const o = byId.get(c.id);
+        if (!o) {
+            checks.push(c);
+            continue;
+        }
+        if (o.enabled === false) {
+            applied.push({
+                policyId: c.id,
+                originalSeverity: c.severity,
+                disabled: true,
+                ...(o.reason ? { reason: o.reason } : {}),
+            });
+            continue;
+        }
+        if (o.severity && o.severity !== c.severity) {
+            checks.push({ ...c, severity: o.severity });
+            applied.push({
+                policyId: c.id,
+                appliedSeverity: o.severity,
+                originalSeverity: c.severity,
+                ...(o.reason ? { reason: o.reason } : {}),
+            });
+        }
+        else {
+            checks.push(c);
+        }
+    }
+    // Recompute summary.
+    let info = 0, warning = 0, error = 0, critical = 0;
+    for (const c of checks) {
+        if (c.severity === PolicySeverity.Info)
+            info++;
+        else if (c.severity === PolicySeverity.Warning)
+            warning++;
+        else if (c.severity === PolicySeverity.Error)
+            error++;
+        else if (c.severity === PolicySeverity.Critical)
+            critical++;
+    }
+    const passed = error === 0 && critical === 0;
+    return {
+        report: {
+            ...report,
+            checks,
+            summary: { info, warning, error, critical, passed },
+        },
+        explain: {
+            schema: POLICY_OVERRIDES_SCHEMA,
+            overrides,
+            applied,
+        },
+    };
+}