al-sem 0.0.1

package/src/policy/policy-engine.ts

@@ -0,0 +1,339 @@
+import { compareStrings } from "../engine/uncertainty-util.ts";
+import type { CapabilityFact } from "../model/capability.ts";
+import { type Routine, type Scope, roleOf } from "../model/entities.ts";
+import type { Diagnostic, EvidenceStep, Finding } from "../model/finding.ts";
+import type { SemanticModel } from "../model/model.ts";
+import { fingerprintOf } from "../projection/finding-fingerprint.ts";
+import type {
+	CoveragePolicy,
+	PolicyDoc,
+	PolicyRunResult,
+	Rule,
+	RuleRunSummary,
+	UnknownPolicy,
+} from "./policy-types.ts";
+import { evaluateApplicability, evaluateResult } from "./predicate-evaluator.ts";
+import { type FieldEvalContext, buildFieldIndexes } from "./predicate-fields.ts";
+
+function pickCoverage(rule: Rule, doc: PolicyDoc): CoveragePolicy {
+	return rule.requireCoverage ?? doc.defaults?.requireCoverage ?? "any";
+}
+
+function pickUnknown(rule: Rule, doc: PolicyDoc): UnknownPolicy {
+	return rule.onUnknown ?? doc.defaults?.onUnknown ?? "fail-closed";
+}
+
+function passesCoverageGate(coverageStatus: string | undefined, gate: CoveragePolicy): boolean {
+	if (gate === "any") return true;
+	if (gate === "partial") return coverageStatus !== "unknown";
+	// gate === "complete"
+	return coverageStatus === "complete";
+}
+
+function selectFacts(
+	rule: Rule,
+	summary:
+		| {
+				capabilityFactsDirect?: readonly CapabilityFact[];
+				capabilityFactsInherited?: readonly CapabilityFact[];
+		  }
+		| undefined,
+): readonly CapabilityFact[] {
+	if (summary === undefined) return [];
+	const direct = summary.capabilityFactsDirect ?? [];
+	const inherited = summary.capabilityFactsInherited ?? [];
+	switch (rule.facts ?? "any") {
+		case "direct":
+			return direct;
+		case "inherited":
+			return inherited;
+		case "any":
+			return [...direct, ...inherited];
+	}
+}
+
+function factSortKey(f: CapabilityFact): string {
+	return [
+		f.op,
+		f.resourceKind,
+		f.resourceId ?? "",
+		f.witnessOperationId ?? "",
+		f.confidence,
+		f.provenance,
+		f.via,
+		f.witnessCallsiteId ?? "",
+	].join("|");
+}
+
+export function runPolicyEngine(
+	model: SemanticModel,
+	policy: PolicyDoc,
+	opts?: { scope?: Scope },
+): Omit<PolicyRunResult, "policySource" | "policyVersion"> {
+	const findings: Finding[] = [];
+	const ruleSummaries: RuleRunSummary[] = [];
+	const diagnostics: Diagnostic[] = [];
+
+	const scope = opts?.scope ?? "all";
+	const sortedRules = [...policy.rules].sort((a, b) => compareStrings(a.id, b.id));
+	const allRoutines = [...model.routines].sort((a, b) => compareStrings(a.id, b.id));
+	// scope=primary restricts to the workspace's own routines (a dependency match is not
+	// author-actionable); filtering the loop keeps ruleSummaries counts consistent with findings.
+	const sortedRoutines =
+		scope === "all" ? allRoutines : allRoutines.filter((r) => roleOf(r) !== "dependency");
+	const indexes = buildFieldIndexes(model);
+
+	// Sorted-fact lists are identical across rules that share a `facts` mode (all bundled
+	// defaults use "any"), so computing `[...direct, ...inherited].sort()` per (rule × routine)
+	// re-did the same allocation+sort up to 8× per routine — the dominant cost on a large merged
+	// model. Memoize by (routineId, factsMode); output-identical.
+	const factsCache = new Map<string, readonly CapabilityFact[]>();
+	const sortedFactsFor = (rule: Rule, routine: Routine): readonly CapabilityFact[] => {
+		const mode = rule.facts ?? "any";
+		const key = `${routine.id}|${mode}`;
+		const cached = factsCache.get(key);
+		if (cached !== undefined) return cached;
+		const computed = [...selectFacts(rule, routine.summary)].sort((a, b) =>
+			compareStrings(factSortKey(a), factSortKey(b)),
+		);
+		factsCache.set(key, computed);
+		return computed;
+	};
+
+	for (const rule of sortedRules) {
+		const summary: RuleRunSummary = {
+			ruleId: rule.id,
+			routinesEvaluated: 0,
+			routinesMatched: 0,
+			routinesSkippedCoverage: 0,
+			routinesSkippedUnknown: 0,
+			routinesPassed: 0,
+			findingsEmitted: 0,
+		};
+		const coverageGate = pickCoverage(rule, policy);
+		const unknownPolicy = pickUnknown(rule, policy);
+		const ruleFindings: Finding[] = [];
+
+		try {
+			for (const routine of sortedRoutines) {
+				summary.routinesEvaluated++;
+
+				// Applicability: skip routines this rule structurally cannot apply to.
+				// `false` ⇒ no fact can satisfy `when` ⇒ no coverage finding, no fact loop.
+				if (evaluateApplicability(rule.when, { routine, model, indexes }) === "false") {
+					continue;
+				}
+
+				// Structural except: if `except` is definitely true regardless of facts,
+				// the routine is exempt — skip before coverage (no coverage finding).
+				// Safe to skip: applicability "true" means a routine-scoped branch already
+				// forces except true via Kleene OR-absorption — no concrete fact can lower it
+				// to a non-exempt result, so this routine is structurally exempt.
+				if (
+					rule.except !== undefined &&
+					evaluateApplicability(rule.except, { routine, model, indexes }) === "true"
+				) {
+					continue;
+				}
+
+				const coverageStatus = routine.summary?.coverage?.inheritedStatus as string | undefined;
+				if (!passesCoverageGate(coverageStatus, coverageGate)) {
+					summary.routinesSkippedCoverage++;
+					if (unknownPolicy === "fail-closed") {
+						ruleFindings.push(
+							emitCoverageFinding(rule, routine, model, coverageStatus ?? "unknown", coverageGate),
+						);
+					}
+					continue;
+				}
+
+				const facts = sortedFactsFor(rule, routine);
+				if (facts.length === 0) {
+					// Applicable + covered + no selected facts ⇒ rule does not fire (E2).
+					summary.routinesPassed++;
+					continue;
+				}
+
+				const matchedFacts: CapabilityFact[] = [];
+				let sawUnknown = false;
+
+				for (const fact of facts) {
+					const ctx: FieldEvalContext = { routine, fact, model, indexes };
+					const whenResult = evaluateResult(rule.when, ctx);
+					if (whenResult === "false") continue;
+					if (whenResult === "unknown") {
+						sawUnknown = true;
+						continue;
+					}
+					// when === "true" — evaluate except per-fact if present.
+					if (rule.except !== undefined && evaluateResult(rule.except, ctx) === "true") {
+						continue; // except=true → carve-out; except=false/unknown → violation.
+					}
+					matchedFacts.push(fact);
+				}
+
+				if (matchedFacts.length > 0) {
+					summary.routinesMatched++;
+					ruleFindings.push(emitMatchFinding(rule, routine, model, matchedFacts));
+				} else if (sawUnknown) {
+					summary.routinesSkippedUnknown++;
+					if (unknownPolicy === "fail-closed") {
+						ruleFindings.push(emitUnknownFinding(rule, routine, model));
+					}
+				} else {
+					summary.routinesPassed++;
+				}
+			}
+		} catch (err) {
+			diagnostics.push({
+				severity: "warning",
+				stage: "detect",
+				message: `policy rule '${rule.id}' threw: ${err instanceof Error ? err.message : String(err)}`,
+			});
+			summary.errors = [err instanceof Error ? err.message : String(err)];
+			ruleSummaries.push(summary);
+			continue;
+		}
+
+		summary.findingsEmitted = ruleFindings.length;
+		findings.push(...ruleFindings);
+		ruleSummaries.push(summary);
+	}
+
+	findings.sort((a, b) => compareStrings(a.id, b.id));
+	return { ruleSummaries, findings, diagnostics };
+}
+
+function buildPrimaryLocation(routine: Routine) {
+	return { ...routine.sourceAnchor, enclosingRoutineId: routine.id };
+}
+
+function emitMatchFinding(
+	rule: Rule,
+	routine: Routine,
+	model: SemanticModel,
+	matched: readonly CapabilityFact[],
+): Finding {
+	const rootCauseKey = `policy-${rule.id}/${routine.id}`;
+	const primaryLocation = buildPrimaryLocation(routine);
+	const evidence: EvidenceStep[] = [
+		{
+			routineId: routine.id,
+			sourceAnchor: primaryLocation,
+			note: rule.message ?? rule.title ?? `Policy rule ${rule.id} violation`,
+		},
+		...matched.map((fact) => ({
+			routineId: routine.id,
+			sourceAnchor: primaryLocation,
+			note: `matched on capability.op=${fact.op}, resourceKind=${fact.resourceKind}${fact.resourceId !== undefined ? `, resourceId=${fact.resourceId}` : ""}`,
+			operationId: fact.witnessOperationId,
+			callsiteId: fact.witnessCallsiteId,
+		})),
+	];
+	const finding: Finding = {
+		id: rootCauseKey,
+		rootCauseKey,
+		detector: `policy-${rule.id}`,
+		title: rule.title ?? rule.id,
+		rootCause:
+			rule.message ??
+			rule.description ??
+			`Policy ${rule.id} matched ${matched.length} fact(s) on routine ${routine.id}.`,
+		severity: rule.severity,
+		confidence: { level: "likely", evidence: [] },
+		primaryLocation,
+		evidencePath: evidence,
+		affectedObjects: [routine.objectId],
+		affectedTables: [],
+		fixOptions: [],
+		provenance: [{ source: "tree-sitter" }],
+	};
+	finding.fingerprint = fingerprintOf(finding, model);
+	return finding;
+}
+
+function emitCoverageFinding(
+	rule: Rule,
+	routine: Routine,
+	model: SemanticModel,
+	status: string,
+	effectiveGate: CoveragePolicy,
+): Finding {
+	const rootCauseKey = `policy-${rule.id}/${routine.id}`;
+	const primaryLocation = buildPrimaryLocation(routine);
+	const finding: Finding = {
+		id: rootCauseKey,
+		rootCauseKey,
+		detector: `policy-${rule.id}`,
+		title: rule.title ?? rule.id,
+		rootCause: `Coverage gate (requireCoverage=${effectiveGate}) failed: routine coverage is ${status}.`,
+		severity: rule.severity,
+		confidence: { level: "possible", evidence: [] },
+		primaryLocation,
+		evidencePath: [
+			{
+				routineId: routine.id,
+				sourceAnchor: primaryLocation,
+				note: `coverage=${status}`,
+			},
+		],
+		affectedObjects: [routine.objectId],
+		affectedTables: [],
+		fixOptions: [],
+		provenance: [{ source: "tree-sitter" }],
+	};
+	finding.fingerprint = fingerprintOf(finding, model);
+	return finding;
+}
+
+function emitUnknownFinding(rule: Rule, routine: Routine, model: SemanticModel): Finding {
+	const rootCauseKey = `policy-${rule.id}/${routine.id}`;
+	const primaryLocation = buildPrimaryLocation(routine);
+	const finding: Finding = {
+		id: rootCauseKey,
+		rootCauseKey,
+		detector: `policy-${rule.id}`,
+		title: rule.title ?? rule.id,
+		rootCause: "Predicate could not be resolved on any fact; onUnknown=fail-closed.",
+		severity: rule.severity,
+		confidence: { level: "possible", evidence: [] },
+		primaryLocation,
+		evidencePath: [
+			{
+				routineId: routine.id,
+				sourceAnchor: primaryLocation,
+				note: "policy unknown — fail-closed",
+			},
+		],
+		affectedObjects: [routine.objectId],
+		affectedTables: [],
+		fixOptions: [],
+		provenance: [{ source: "tree-sitter" }],
+	};
+	finding.fingerprint = fingerprintOf(finding, model);
+	return finding;
+}
+
+/**
+ * Public wrapper that adds policySource + policyVersion to the engine result.
+ * Use this from the CLI and integration layer; use runPolicyEngine directly
+ * in unit tests that don't need the source/version envelope.
+ */
+export function runPolicy(
+	model: SemanticModel,
+	policy: PolicyDoc | undefined,
+	source: string,
+	opts?: { scope?: Scope },
+): PolicyRunResult {
+	if (policy === undefined) {
+		return {
+			policySource: source,
+			policyVersion: 0,
+			ruleSummaries: [],
+			findings: [],
+			diagnostics: [],
+		};
+	}
+	const r = runPolicyEngine(model, policy, opts);
+	return { policySource: source, policyVersion: policy.version, ...r };
+}

package/src/policy/policy-loader.ts

@@ -0,0 +1,257 @@
+import { readFileSync } from "node:fs";
+import { parseDocument } from "yaml";
+import type {
+	CoveragePolicy,
+	FactOriginFilter,
+	PolicyDoc,
+	PolicySeverity,
+	Rule,
+	UnknownPolicy,
+} from "./policy-types.ts";
+import { compilePredicate } from "./predicate-compiler.ts";
+import { PREDICATE_FIELDS } from "./predicate-fields.ts";
+
+export type LoadResult =
+	| { ok: true; policy: PolicyDoc; warnings: readonly string[] }
+	| { ok: false; errors: readonly string[]; warnings: readonly string[] };
+
+const RULE_ID_RE = /^[a-z][a-z0-9-]{2,80}$/;
+const ALLOWED_SEVERITIES: readonly PolicySeverity[] = ["critical", "high", "medium", "low", "info"];
+const ALLOWED_UNKNOWN: readonly UnknownPolicy[] = ["fail-open", "fail-closed"];
+const ALLOWED_COVERAGE: readonly CoveragePolicy[] = ["complete", "partial", "any"];
+const ALLOWED_FACTS: readonly FactOriginFilter[] = ["direct", "inherited", "any"];
+const ALLOWED_TOP_FIELDS = new Set(["version", "description", "defaults", "rules"]);
+const ALLOWED_RULE_FIELDS = new Set([
+	"id",
+	"title",
+	"description",
+	"message",
+	"severity",
+	"when",
+	"except",
+	"requireCoverage",
+	"onUnknown",
+	"facts",
+]);
+
+export function loadPolicyFromString(yaml: string): LoadResult {
+	const errors: string[] = [];
+	const warnings: string[] = [];
+
+	const doc = parseDocument(yaml, { uniqueKeys: true, customTags: [] });
+	if (doc.errors.length > 0) {
+		for (const e of doc.errors) errors.push(`yaml: ${e.message}`);
+		return { ok: false, errors, warnings };
+	}
+	for (const w of doc.warnings) warnings.push(`yaml: ${w.message}`);
+
+	// maxAliasCount: 0 disallows all alias nodes (anti-billion-laughs)
+	const obj = doc.toJS({ maxAliasCount: 0 });
+	if (obj === null || typeof obj !== "object" || Array.isArray(obj)) {
+		return { ok: false, errors: ["policy root must be a map"], warnings };
+	}
+	const top = obj as Record<string, unknown>;
+
+	for (const k of Object.keys(top)) {
+		if (!ALLOWED_TOP_FIELDS.has(k)) errors.push(`unknown top-level field '${k}'`);
+	}
+	if (top.version !== 1) errors.push(`policy version must be 1 (got ${String(top.version)})`);
+
+	const defaults: { onUnknown?: UnknownPolicy; requireCoverage?: CoveragePolicy } = {};
+	if (top.defaults !== undefined) {
+		if (typeof top.defaults !== "object" || top.defaults === null || Array.isArray(top.defaults)) {
+			errors.push("defaults must be a map");
+		} else {
+			const d = top.defaults as Record<string, unknown>;
+			if (d.onUnknown !== undefined) {
+				if (ALLOWED_UNKNOWN.includes(d.onUnknown as UnknownPolicy)) {
+					defaults.onUnknown = d.onUnknown as UnknownPolicy;
+				} else {
+					errors.push(`defaults.onUnknown: must be one of ${ALLOWED_UNKNOWN.join(", ")}`);
+				}
+			}
+			if (d.requireCoverage !== undefined) {
+				if (ALLOWED_COVERAGE.includes(d.requireCoverage as CoveragePolicy)) {
+					defaults.requireCoverage = d.requireCoverage as CoveragePolicy;
+				} else {
+					errors.push(`defaults.requireCoverage: must be one of ${ALLOWED_COVERAGE.join(", ")}`);
+				}
+			}
+		}
+	}
+
+	if (!Array.isArray(top.rules)) {
+		return { ok: false, errors: [...errors, "rules must be an array"], warnings };
+	}
+
+	const rules: Rule[] = [];
+	const seenIds = new Set<string>();
+
+	for (let i = 0; i < top.rules.length; i++) {
+		const raw = top.rules[i];
+		if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+			errors.push(`rules[${i}]: must be a map`);
+			continue;
+		}
+		const r = raw as Record<string, unknown>;
+		const path = `rules[${i}]`;
+
+		for (const k of Object.keys(r)) {
+			if (!ALLOWED_RULE_FIELDS.has(k)) errors.push(`${path}.${k}: unknown rule field`);
+		}
+
+		const id = typeof r.id === "string" ? r.id : "";
+		if (!RULE_ID_RE.test(id)) {
+			errors.push(`${path}.id: must match ${RULE_ID_RE.source} (got '${id}')`);
+			continue;
+		}
+		if (seenIds.has(id)) {
+			errors.push(`${path}: duplicate rule id '${id}'`);
+			continue;
+		}
+		seenIds.add(id);
+
+		if (
+			typeof r.severity !== "string" ||
+			!ALLOWED_SEVERITIES.includes(r.severity as PolicySeverity)
+		) {
+			errors.push(`${path}.severity: must be one of ${ALLOWED_SEVERITIES.join(", ")}`);
+			continue;
+		}
+
+		if (r.when === undefined) {
+			errors.push(`${path}.when: required`);
+			continue;
+		}
+		const whenC = compilePredicate(r.when, `${path}.when`);
+		if (!whenC.ok) {
+			errors.push(whenC.error);
+			continue;
+		}
+
+		let except: Rule["except"] | undefined;
+		if (r.except !== undefined) {
+			const exceptC = compilePredicate(r.except, `${path}.except`);
+			if (!exceptC.ok) {
+				errors.push(exceptC.error);
+				continue;
+			}
+			except = exceptC.value;
+		}
+
+		const requireCoverage = r.requireCoverage as CoveragePolicy | undefined;
+		if (requireCoverage !== undefined && !ALLOWED_COVERAGE.includes(requireCoverage)) {
+			errors.push(`${path}.requireCoverage: invalid value`);
+			continue;
+		}
+
+		const onUnknown = r.onUnknown as UnknownPolicy | undefined;
+		if (onUnknown !== undefined && !ALLOWED_UNKNOWN.includes(onUnknown)) {
+			errors.push(`${path}.onUnknown: invalid value`);
+			continue;
+		}
+
+		const facts = r.facts as FactOriginFilter | undefined;
+		if (facts !== undefined && !ALLOWED_FACTS.includes(facts)) {
+			errors.push(`${path}.facts: invalid value`);
+			continue;
+		}
+
+		rules.push({
+			id,
+			title: typeof r.title === "string" ? r.title : undefined,
+			description: typeof r.description === "string" ? r.description : undefined,
+			message: typeof r.message === "string" ? r.message : undefined,
+			severity: r.severity as PolicySeverity,
+			when: whenC.value,
+			except,
+			requireCoverage,
+			onUnknown,
+			facts,
+		});
+	}
+
+	if (errors.length > 0) return { ok: false, errors, warnings };
+
+	const policy: PolicyDoc = {
+		version: 1,
+		description: typeof top.description === "string" ? top.description : undefined,
+		defaults: Object.keys(defaults).length > 0 ? defaults : undefined,
+		rules,
+	};
+	return { ok: true, policy, warnings };
+}
+
+export function loadPolicyFromFile(path: string): LoadResult {
+	let yaml: string;
+	try {
+		yaml = readFileSync(path, "utf8");
+	} catch (err) {
+		return {
+			ok: false,
+			errors: [`failed to read ${path}: ${(err as Error).message}`],
+			warnings: [],
+		};
+	}
+	return loadPolicyFromString(yaml);
+}
+
+/**
+ * Generate the JSON Schema for the policy file format. Derived from the
+ * predicate-fields registry (single source of truth). The checked-in
+ * `src/policy/policy-schema.json` artifact is regenerated from this
+ * function; CI guard test (T12) catches drift.
+ */
+export function generatePolicySchema(): unknown {
+	const predicateProps: Record<string, unknown> = {};
+	for (const f of PREDICATE_FIELDS) predicateProps[f.name] = f.jsonSchemaFragment;
+	return {
+		$schema: "http://json-schema.org/draft-07/schema#",
+		title: "al-sem policy",
+		type: "object",
+		required: ["version", "rules"],
+		properties: {
+			version: { const: 1 },
+			description: { type: "string" },
+			defaults: {
+				type: "object",
+				properties: {
+					onUnknown: { type: "string", enum: ["fail-open", "fail-closed"] },
+					requireCoverage: { type: "string", enum: ["complete", "partial", "any"] },
+				},
+				additionalProperties: false,
+			},
+			rules: { type: "array", items: { $ref: "#/definitions/Rule" } },
+		},
+		additionalProperties: false,
+		definitions: {
+			Rule: {
+				type: "object",
+				required: ["id", "severity", "when"],
+				properties: {
+					id: { type: "string", pattern: "^[a-z][a-z0-9-]{2,80}$" },
+					title: { type: "string" },
+					description: { type: "string" },
+					message: { type: "string" },
+					severity: { type: "string", enum: ["critical", "high", "medium", "low", "info"] },
+					when: { $ref: "#/definitions/Predicate" },
+					except: { $ref: "#/definitions/Predicate" },
+					requireCoverage: { type: "string", enum: ["complete", "partial", "any"] },
+					onUnknown: { type: "string", enum: ["fail-open", "fail-closed"] },
+					facts: { type: "string", enum: ["direct", "inherited", "any"] },
+				},
+				additionalProperties: false,
+			},
+			Predicate: {
+				type: "object",
+				properties: {
+					...predicateProps,
+					all: { type: "array", items: { $ref: "#/definitions/Predicate" } },
+					any: { type: "array", items: { $ref: "#/definitions/Predicate" } },
+					not: { $ref: "#/definitions/Predicate" },
+				},
+				additionalProperties: false,
+			},
+		},
+	};
+}