al-sem 0.0.1

package/src/policy/policy-schema.json

@@ -0,0 +1,379 @@
+{
+	"$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": {
+				"root.kinds": {
+					"oneOf": [
+						{
+							"type": "string"
+						},
+						{
+							"type": "array",
+							"items": {
+								"type": "string"
+							}
+						}
+					]
+				},
+				"routine.name": {
+					"oneOf": [
+						{
+							"type": "string"
+						},
+						{
+							"type": "array",
+							"items": {
+								"type": "string"
+							}
+						}
+					]
+				},
+				"routine.kind": {
+					"type": "string",
+					"enum": ["procedure", "trigger", "event-publisher", "event-subscriber"]
+				},
+				"routine.accessModifier": {
+					"oneOf": [
+						{
+							"type": "string"
+						},
+						{
+							"type": "array",
+							"items": {
+								"type": "string"
+							}
+						}
+					]
+				},
+				"object.name": {
+					"oneOf": [
+						{
+							"type": "string"
+						},
+						{
+							"type": "array",
+							"items": {
+								"type": "string"
+							}
+						}
+					]
+				},
+				"object.kind": {
+					"oneOf": [
+						{
+							"type": "string"
+						},
+						{
+							"type": "array",
+							"items": {
+								"type": "string"
+							}
+						}
+					]
+				},
+				"object.appGuid": {
+					"type": "string"
+				},
+				"capability.op": {
+					"oneOf": [
+						{
+							"type": "string",
+							"enum": [
+								"read",
+								"insert",
+								"modify",
+								"delete",
+								"execute",
+								"publish",
+								"subscribe",
+								"send",
+								"log",
+								"store-read",
+								"store-write",
+								"store-delete",
+								"commit",
+								"open",
+								"write-blob",
+								"start",
+								"ui-confirm",
+								"ui-message",
+								"ui-error"
+							]
+						},
+						{
+							"type": "array",
+							"items": {
+								"type": "string",
+								"enum": [
+									"read",
+									"insert",
+									"modify",
+									"delete",
+									"execute",
+									"publish",
+									"subscribe",
+									"send",
+									"log",
+									"store-read",
+									"store-write",
+									"store-delete",
+									"commit",
+									"open",
+									"write-blob",
+									"start",
+									"ui-confirm",
+									"ui-message",
+									"ui-error"
+								]
+							}
+						}
+					]
+				},
+				"capability.resourceKind": {
+					"oneOf": [
+						{
+							"type": "string",
+							"enum": [
+								"table",
+								"event",
+								"codeunit",
+								"page",
+								"report",
+								"http",
+								"telemetry",
+								"isolated-storage",
+								"file",
+								"transaction",
+								"ui",
+								"background"
+							]
+						},
+						{
+							"type": "array",
+							"items": {
+								"type": "string",
+								"enum": [
+									"table",
+									"event",
+									"codeunit",
+									"page",
+									"report",
+									"http",
+									"telemetry",
+									"isolated-storage",
+									"file",
+									"transaction",
+									"ui",
+									"background"
+								]
+							}
+						}
+					]
+				},
+				"capability.resource.table.name": {
+					"oneOf": [
+						{
+							"type": "string"
+						},
+						{
+							"type": "array",
+							"items": {
+								"type": "string"
+							}
+						}
+					]
+				},
+				"capability.resource.event.name": {
+					"oneOf": [
+						{
+							"type": "string"
+						},
+						{
+							"type": "array",
+							"items": {
+								"type": "string"
+							}
+						}
+					]
+				},
+				"capability.resource.http.method": {
+					"oneOf": [
+						{
+							"type": "string"
+						},
+						{
+							"type": "array",
+							"items": {
+								"type": "string"
+							}
+						}
+					]
+				},
+				"capability.resource.ui.kind": {
+					"oneOf": [
+						{
+							"type": "string"
+						},
+						{
+							"type": "array",
+							"items": {
+								"type": "string"
+							}
+						}
+					]
+				},
+				"capability.confidence": {
+					"oneOf": [
+						{
+							"type": "string",
+							"enum": ["static", "boundedDynamic", "configDynamic", "userDynamic", "unresolved"]
+						},
+						{
+							"type": "array",
+							"items": {
+								"type": "string",
+								"enum": ["static", "boundedDynamic", "configDynamic", "userDynamic", "unresolved"]
+							}
+						}
+					]
+				},
+				"capability.origin": {
+					"oneOf": [
+						{
+							"type": "string",
+							"enum": ["direct", "inherited"]
+						},
+						{
+							"type": "array",
+							"items": {
+								"type": "string",
+								"enum": ["direct", "inherited"]
+							}
+						}
+					]
+				},
+				"capability.via": {
+					"oneOf": [
+						{
+							"type": "string",
+							"enum": [
+								"self",
+								"call",
+								"object-run",
+								"event-dispatch",
+								"implicit-trigger",
+								"dependency"
+							]
+						},
+						{
+							"type": "array",
+							"items": {
+								"type": "string",
+								"enum": [
+									"self",
+									"call",
+									"object-run",
+									"event-dispatch",
+									"implicit-trigger",
+									"dependency"
+								]
+							}
+						}
+					]
+				},
+				"all": {
+					"type": "array",
+					"items": {
+						"$ref": "#/definitions/Predicate"
+					}
+				},
+				"any": {
+					"type": "array",
+					"items": {
+						"$ref": "#/definitions/Predicate"
+					}
+				},
+				"not": {
+					"$ref": "#/definitions/Predicate"
+				}
+			},
+			"additionalProperties": false
+		}
+	}
+}

package/src/policy/policy-types.ts

@@ -0,0 +1,81 @@
+import type { Diagnostic, Finding } from "../model/finding.ts";
+
+export type PolicySeverity = "critical" | "high" | "medium" | "low" | "info";
+export type PolicyVerdict = "pass" | "fail" | "unknown" | "not-applicable";
+export type Tristate = "true" | "false" | "unknown";
+export type CoveragePolicy = "complete" | "partial" | "any";
+export type UnknownPolicy = "fail-open" | "fail-closed";
+export type FactOriginFilter = "direct" | "inherited" | "any";
+
+export type PredicateOperator = "==" | "in" | "glob" | "glob-in";
+
+export type Predicate =
+	| { kind: "field"; field: string; operator: PredicateOperator; value: unknown }
+	| { kind: "all"; children: readonly Predicate[] }
+	| { kind: "any"; children: readonly Predicate[] }
+	| { kind: "not"; child: Predicate };
+
+export interface Rule {
+	id: string;
+	title?: string;
+	description?: string;
+	message?: string;
+	severity: PolicySeverity;
+	when: Predicate;
+	except?: Predicate;
+	requireCoverage?: CoveragePolicy;
+	onUnknown?: UnknownPolicy;
+	facts?: FactOriginFilter;
+}
+
+export interface PolicyDoc {
+	version: 1;
+	description?: string;
+	defaults?: {
+		onUnknown?: UnknownPolicy;
+		requireCoverage?: CoveragePolicy;
+	};
+	rules: readonly Rule[];
+}
+
+export interface PredicateTrace {
+	node: "field" | "all" | "any" | "not";
+	result: Tristate;
+	field?: string;
+	expected?: unknown;
+	actual?: unknown;
+	unknownReason?:
+		| "field-not-applicable"
+		| "resource-id-unresolved"
+		| "no-root-classification"
+		| "coverage-below-bar"
+		| "evaluator-error";
+	children?: readonly PredicateTrace[];
+}
+
+/** Per-rule run counters. NOTE: routines a rule is structurally not applicable to
+ *  (applicability "false") or structurally exempt from (except "true") are counted in
+ *  `routinesEvaluated` but in NONE of the sub-buckets — so
+ *  `routinesEvaluated >= matched + skippedCoverage + skippedUnknown + passed`, not `==`. */
+export interface RuleRunSummary {
+	ruleId: string;
+	routinesEvaluated: number;
+	routinesMatched: number;
+	routinesSkippedCoverage: number;
+	routinesSkippedUnknown: number;
+	routinesPassed: number;
+	findingsEmitted: number;
+	/** Traces captured for sample findings or via policy explain --routine. */
+	traces?: readonly { routineId: string; trace: PredicateTrace }[];
+	/** Per-rule errors (compilation or evaluation). */
+	errors?: readonly string[];
+}
+
+export interface PolicyRunResult {
+	/** "default" | "auto:<absolute-path>" | "explicit:<absolute-path>" | "inline" | "disabled" */
+	policySource: string;
+	policyVersion: number;
+	ruleSummaries: readonly RuleRunSummary[];
+	findings: readonly Finding[];
+	diagnostics: readonly Diagnostic[];
+}

package/src/policy/predicate-compiler.ts

@@ -0,0 +1,151 @@
+import type { Predicate, PredicateOperator } from "./policy-types.ts";
+import { type FieldScope, type PredicateFieldDef, getFieldDef } from "./predicate-fields.ts";
+
+export type CompileResult = { ok: true; value: Predicate } | { ok: false; error: string };
+
+export function compilePredicate(raw: unknown, path = ""): CompileResult {
+	if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+		return { ok: false, error: `${path || "<root>"}: expected an object` };
+	}
+	const obj = raw as Record<string, unknown>;
+	const keys = Object.keys(obj);
+
+	// Single-key boolean wrappers
+	if (keys.length === 1) {
+		const k = keys[0] as string;
+		if (k === "all" || k === "any") {
+			const items = obj[k];
+			if (!Array.isArray(items)) return { ok: false, error: `${path}.${k}: expected array` };
+			if (items.length === 0) return { ok: false, error: `${path}.${k}: empty array not allowed` };
+			const children: Predicate[] = [];
+			for (let i = 0; i < items.length; i++) {
+				const child = compilePredicate(items[i], `${path}.${k}[${i}]`);
+				if (!child.ok) return child;
+				children.push(child.value);
+			}
+			if (k === "any") {
+				const scopes = collectScopes(children);
+				if (scopes.size > 1) {
+					return {
+						ok: false,
+						error: `${path}.any: mixed ${[...scopes].join("/")} scope predicates — move routine filters into a parent all, or split into separate rules`,
+					};
+				}
+			}
+			return { ok: true, value: { kind: k, children } };
+		}
+		if (k === "not") {
+			const inner = obj.not;
+			if (
+				inner === null ||
+				typeof inner !== "object" ||
+				Array.isArray(inner) ||
+				Object.keys(inner as object).length === 0
+			) {
+				return { ok: false, error: `${path}.not: empty or missing predicate` };
+			}
+			const child = compilePredicate(inner, `${path}.not`);
+			if (!child.ok) return child;
+			const scopes = collectScopes([child.value]);
+			// Disallow `not` over a routine-only predicate (use `except` for routine carve-outs).
+			if (scopes.size === 1 && scopes.has("routine")) {
+				return {
+					ok: false,
+					error: `${path}.not wraps a routine-scope predicate — use except: for routine-scope carve-outs`,
+				};
+			}
+			return { ok: true, value: { kind: "not", child: child.value } };
+		}
+	}
+
+	// Multi-key map (or single-key field) → compile each key; wrap in implicit all if >1
+	const children: Predicate[] = [];
+	for (const k of keys) {
+		if (k === "all" || k === "any" || k === "not") {
+			const sub = compilePredicate({ [k]: obj[k] }, path);
+			if (!sub.ok) return sub;
+			children.push(sub.value);
+			continue;
+		}
+		// Field predicate
+		const def = getFieldDef(k);
+		if (def === undefined) {
+			return { ok: false, error: `${path}.${k}: unknown predicate field` };
+		}
+		const fieldP = compileFieldPredicate(def, obj[k], `${path}.${k}`);
+		if (!fieldP.ok) return fieldP;
+		children.push(fieldP.value);
+	}
+	if (children.length === 0) {
+		return { ok: false, error: `${path || "<root>"}: empty predicate` };
+	}
+	if (children.length === 1) {
+		const first = children[0];
+		// biome-ignore lint/style/noNonNullAssertion: length === 1 guarantees index 0 exists
+		return { ok: true, value: first! };
+	}
+	return { ok: true, value: { kind: "all", children } };
+}
+
+function compileFieldPredicate(def: PredicateFieldDef, raw: unknown, path: string): CompileResult {
+	const isList = Array.isArray(raw);
+	const list = isList ? (raw as unknown[]) : [raw];
+
+	if (def.valueShape === "enum" || def.valueShape === "enum-list") {
+		if (def.enumValues !== undefined) {
+			for (const v of list) {
+				if (typeof v !== "string" || !def.enumValues.includes(v)) {
+					return {
+						ok: false,
+						error: `${path}: invalid enum value '${String(v)}' (allowed: ${def.enumValues.join(", ")})`,
+					};
+				}
+			}
+		}
+		if (def.valueShape === "enum" && isList && list.length > 1) {
+			return { ok: false, error: `${path}: expected single value, got list` };
+		}
+		const op: PredicateOperator = "in";
+		return { ok: true, value: { kind: "field", field: def.name, operator: op, value: list } };
+	}
+
+	if (def.valueShape === "glob" || def.valueShape === "glob-list") {
+		for (const v of list) {
+			if (typeof v !== "string")
+				return { ok: false, error: `${path}: glob value must be a string` };
+		}
+		const op: PredicateOperator = isList ? "glob-in" : "glob";
+		const value = isList ? list : list[0];
+		// biome-ignore lint/style/noNonNullAssertion: list is [raw] when !isList, so index 0 always exists
+		return { ok: true, value: { kind: "field", field: def.name, operator: op, value: value! } };
+	}
+
+	if (def.valueShape === "string-exact" || def.valueShape === "string-list") {
+		for (const v of list) {
+			if (typeof v !== "string") return { ok: false, error: `${path}: value must be a string` };
+		}
+		const op: PredicateOperator = isList ? "in" : "==";
+		const value = isList ? list : list[0];
+		// biome-ignore lint/style/noNonNullAssertion: list is [raw] when !isList, so index 0 always exists
+		return { ok: true, value: { kind: "field", field: def.name, operator: op, value: value! } };
+	}
+
+	return { ok: false, error: `${path}: unsupported value shape '${def.valueShape}'` };
+}
+
+function collectScopes(preds: readonly Predicate[]): Set<FieldScope> {
+	const out = new Set<FieldScope>();
+	for (const p of preds) collectScopesOne(p, out);
+	return out;
+}
+
+function collectScopesOne(p: Predicate, out: Set<FieldScope>): void {
+	if (p.kind === "field") {
+		const def = getFieldDef(p.field);
+		if (def !== undefined) out.add(def.scope);
+	} else if (p.kind === "not") {
+		collectScopesOne(p.child, out);
+	} else {
+		for (const c of p.children) collectScopesOne(c, out);
+	}
+}