@kici-dev/engine 0.4.0 → 0.6.0

package/dist/trigger/content-requirements.js

@@ -0,0 +1,125 @@
+import "../rolldown-runtime-ClRpJifh.js";
+import { resolveContentFormat } from "./types.js";
+import { evaluateTextMatch } from "./text-match.js";
+import { matchJsonPath, matchJsonPathNot } from "./jsonpath-matcher.js";
+import { JSONPath } from "jsonpath-plus";
+import { parse } from "yaml";
+//#region src/trigger/content-requirements.ts
+/**
+* Declarative static content-filter matcher.
+*
+* A git-event trigger may carry a `requires` list ({@link LockContentRequirement}):
+* pure DATA describing a query over the bytes of one source file at the event's
+* ref. The orchestrator interprets that data here — it never executes author
+* code — which is what keeps content filtering inside the orchestrator under the
+* execution-purity model.
+*
+* This module imports `yaml`, so it is a Node-safe subpath export
+* (`@kici-dev/engine/trigger/content-requirements`) and is deliberately kept out
+* of the browser-facing engine barrel (`src/index.ts`).
+*/
+/** Hard byte cap enforced before any parse: an oversize file is indeterminate. */
+const MAX_CONTENT_BYTES = 1048576;
+/**
+* Anchor/alias expansion cap for YAML parsing. The `yaml` library's default of
+* 100 does not reject a small billion-laughs bomb; 50 rejects it while staying
+* generous for legitimately-anchored configs (merge keys, shared defaults). The
+* 1 MiB byte cap above bounds total node count as the complementary limit.
+*/
+const YAML_MAX_ALIAS_COUNT = 50;
+/**
+* Parse `bytes` for the given concrete format. `text` returns the raw string;
+* `json` uses `JSON.parse`; `yaml` uses a hardened `yaml.parse` with an explicit
+* anchor/alias cap. Throws on a malformed document (the caller treats a throw as
+* indeterminate).
+*/
+function parseForFormat(bytes, format) {
+	switch (format) {
+		case "json": return JSON.parse(bytes);
+		case "yaml": return parse(bytes, { maxAliasCount: YAML_MAX_ALIAS_COUNT });
+		case "text": return bytes;
+	}
+}
+/** True when the JSONPath resolves to ≥1 node in the parsed document. */
+function pathExists(doc, path) {
+	return JSONPath({
+		path,
+		json: doc,
+		wrap: true
+	}).length > 0;
+}
+/** JSONPath queries need an object root; wrap a non-object parsed doc so lookups stay safe. */
+function asJsonRoot(doc) {
+	return typeof doc === "object" && doc !== null ? doc : {};
+}
+/**
+* Evaluate one content requirement against the resolved file map.
+* Returns a per-entry {@link ContentRequirementResult}. `pass:false` with no
+* `indeterminate` is a definite negative; `indeterminate` means the file could
+* not be evaluated (oversize, parse failure, unsafe regex) and is fail-visible.
+*/
+function evaluateOne(req, entry) {
+	const present = entry?.present === true;
+	if (req.absent) return { pass: !present };
+	if (!present) return { pass: false };
+	const bytes = entry?.bytes ?? "";
+	if (Buffer.byteLength(bytes, "utf8") > MAX_CONTENT_BYTES) return {
+		pass: false,
+		indeterminate: `${req.file}: exceeds 1 MiB size cap`
+	};
+	const textResult = evaluateTextMatch(bytes, {
+		...req.contains !== void 0 && { contains: req.contains },
+		...req.notContains !== void 0 && { notContains: req.notContains },
+		...req.matches !== void 0 && { matches: req.matches },
+		...req.notMatches !== void 0 && { notMatches: req.notMatches },
+		...req.ignoreCase !== void 0 && { ignoreCase: req.ignoreCase }
+	});
+	if (textResult.indeterminate) return {
+		pass: false,
+		indeterminate: `${req.file}: ${textResult.indeterminate}`
+	};
+	if (!textResult.pass) return { pass: false };
+	if (req.exists && req.exists.length > 0 || req.match && Object.keys(req.match).length > 0 || req.not && Object.keys(req.not).length > 0) {
+		const format = resolveContentFormat(req.file, req.format);
+		let parsed;
+		try {
+			parsed = parseForFormat(bytes, format);
+		} catch (err) {
+			const reason = err instanceof Error ? err.message : String(err);
+			return {
+				pass: false,
+				indeterminate: `${req.file}: failed to parse as ${format}: ${reason}`
+			};
+		}
+		const root = asJsonRoot(parsed);
+		if (req.exists) {
+			for (const path of req.exists) if (!pathExists(parsed, path)) return { pass: false };
+		}
+		if (req.match && !matchJsonPath(root, req.match)) return { pass: false };
+		if (req.not && !matchJsonPathNot(root, req.not)) return { pass: false };
+	}
+	return { pass: true };
+}
+/**
+* Evaluate an AND-ed list of content requirements against a resolved file map.
+*
+* Every entry must pass for the overall result to pass; an empty list passes.
+* The first indeterminate entry short-circuits and is surfaced (fail-visible):
+* an unevaluable file NEVER passes silently.
+*
+* @param reqs  The lock `requires` list (each entry AND-ed).
+* @param files Resolved file contents keyed by repo-relative path. A missing key
+*              or `{ present: false }` means the file does not exist at the ref.
+*/
+function evaluateContentRequirements(reqs, files) {
+	for (const req of reqs) {
+		const result = evaluateOne(req, files.get(req.file));
+		if (result.indeterminate) return result;
+		if (!result.pass) return { pass: false };
+	}
+	return { pass: true };
+}
+//#endregion
+export { evaluateContentRequirements, parseForFormat };
+
+//# sourceMappingURL=content-requirements.js.map

package/dist/trigger/decision-trace.d.ts

@@ -2,6 +2,7 @@
  * Decision trace recording for debugging trigger matching.
  * Records every check performed during trigger evaluation.
  */
+import type { LockTextMatch } from './types.js';
 /**
  * Individual trace entry for a single check.
  */
@@ -30,10 +31,177 @@ export interface WorkflowDecision {
     /** Summary reason */
     summary: string;
 }
+/**
+ * Max characters of any free-text field a trace entry carries, so an
+ * essay-length input stays bounded.
+ *
+ * The entry count is capped separately, downstream, but a count bound alone
+ * bounds nothing: a single `paths` entry names every changed file in the push
+ * and a single `bodyMatch` entry quotes a comment body an outsider authored, so
+ * fifty entries can still be megabytes. The forwarded trace rides one WebSocket
+ * frame to the Platform, and a frame past the server's payload ceiling closes
+ * the connection — stalling every delivery for that organization until it
+ * reconnects. Bounding at the point each field is minted is what makes the
+ * downstream size guards a backstop rather than the only limit.
+ */
+export declare const TRACE_TEXT_MAX = 200;
+/** Clamp one free-text trace field, marking a clamped value with an ellipsis. */
+export declare function truncateTraceText(text: string): string;
 /**
  * Create a new trace entry.
+ *
+ * Every free-text field is clamped here rather than at each call site: the
+ * fields are fed from event content of unbounded size, and one unclamped call
+ * site is enough to reintroduce an unbounded frame.
  */
 export declare function createTraceEntry(check: string, pattern: string, value: string, passed: boolean, reason?: string): TraceEntry;
+/**
+ * Stable `check` labels for the gates an organization-wide global workflow
+ * passes on its way to dispatch.
+ *
+ * The other trigger checks are minted with free-text labels because each one
+ * names the trigger field it read. These are named constants instead: they are
+ * recorded in one package and read back in another — by code, and by whoever is
+ * asking "why did nothing run?" — so a typo on either side would silently
+ * produce a trace nobody can search for.
+ */
+export declare const TraceCheck: {
+    /** `repos` glob/regex filter, deciding whether a workflow applies to the event's repo. */
+    readonly RepoFilter: 'repo';
+    /** Tier-1 declarative `requires` content filter, interpreted by the orchestrator. */
+    readonly ContentRequirements: 'requires';
+    /** Tier-2 `filter` predicate, run by an agent in the global eval round. */
+    readonly GlobalFilter: 'filter';
+    /** Tier-0 declarative `commitMessage` filter, read from the normalized event. */
+    readonly CommitMessage: 'commitMessage';
+    /** Materialization of a matched workflow's jobs, on the way to dispatch. */
+    readonly Dispatch: 'dispatch';
+};
+export type TraceCheck = (typeof TraceCheck)[keyof typeof TraceCheck];
+/**
+ * Verdict vocabulary shared by both gates.
+ *
+ * `Indeterminate` is deliberately distinct from `Excluded`: a gate that could
+ * not be evaluated did not decide anything, and reporting it as an exclusion
+ * would tell a workflow author their filter said no when nothing ever ran it.
+ */
+export declare const TraceVerdict: {
+    readonly Matched: 'matched';
+    readonly Excluded: 'excluded';
+    readonly Indeterminate: 'indeterminate';
+};
+export type TraceVerdict = (typeof TraceVerdict)[keyof typeof TraceVerdict];
+/**
+ * Record the Tier-1 `requires` content filter's verdict for one workflow.
+ *
+ * `files` is the set of repo-relative paths the requirement list reads, so the
+ * entry names what was inspected as well as what it concluded.
+ */
+export declare function createContentRequirementsTraceEntry(args: {
+    files: readonly string[];
+    passed: boolean;
+    /** Set when the requirement list could not be evaluated (unreadable file, bad parse). */
+    indeterminate?: boolean;
+    reason?: string;
+}): TraceEntry;
+/**
+ * Record the Tier-2 `filter` predicate's verdict for one workflow.
+ *
+ * Without this entry a `filter` exclusion is invisible: the predicate runs on an
+ * agent, returns `false`, and the workflow simply never appears — leaving its
+ * author nothing to inspect. The entry is the answer to "why did nothing run?".
+ */
+export declare function createGlobalFilterTraceEntry(args: {
+    /** The round's verdict for this candidate: `true` means the filter admitted it. */
+    run: boolean;
+    /** True when the round could not decide (a failed round, a budget breach). */
+    indeterminate?: boolean;
+    reason?: string;
+}): TraceEntry;
+/**
+ * Record that a matched workflow could not be materialized into jobs.
+ *
+ * A workflow whose triggers matched and whose build then threw is absent from
+ * every other record: no run row is created and no job is queued. Omitting it
+ * from the trace as well leaves its author unable to tell it apart from a
+ * workflow that was never registered — the exact indistinguishability the trace
+ * exists to remove.
+ */
+export declare function createDispatchFailureTraceEntry(reason: string): TraceEntry;
+/**
+ * Return a copy of `decision` with `entries` appended to its checks.
+ *
+ * A decision is treated as a value, never mutated in place: the same object is
+ * read by the caller that recorded it, and a gate appending to it would
+ * retroactively rewrite what an earlier reader saw.
+ *
+ * A failing appended entry demotes `matched` and replaces `summary`, because a
+ * workflow whose triggers matched but whose content filter excluded it did NOT
+ * match overall — reporting it as matched is precisely the invisible outcome
+ * these entries exist to explain.
+ */
+export declare function appendChecks(decision: WorkflowDecision, entries: readonly TraceEntry[]): WorkflowDecision;
+/**
+ * Record the Tier-0 `commitMessage` filter's verdict for one trigger.
+ *
+ * `text: undefined` means the event carried no message — an INDETERMINATE
+ * verdict, deliberately distinct from an exclusion: reporting it as "excluded"
+ * would tell an author their filter said no when nothing ever read it.
+ */
+export declare function createCommitMessageTraceEntry(args: {
+    match: LockTextMatch;
+    text: string | undefined;
+    passed: boolean;
+    indeterminate?: boolean;
+    reason?: string;
+}): TraceEntry;
+/**
+ * What a withheld trace field is replaced with when the reader does not hold
+ * `event_log:read_payload`.
+ *
+ * Lives here rather than beside the Platform's redactor because three packages
+ * read it: the Platform writes it, the dashboard renders it, and the E2E suite
+ * asserts the permission boundary against it. A literal repeated at each site
+ * would drift into a marker one of them no longer recognizes.
+ */
+export declare const REDACTED_TRACE_FIELD = "[redacted \u2014 requires event_log:read_payload]";
+/**
+ * Workflow name the truncation marker carries.
+ *
+ * A reserved sentinel rather than a real workflow: it is written by one package
+ * and read back by two others, so a literal repeated at each site would drift
+ * into a marker nobody recognizes.
+ */
+export declare const TRACE_TRUNCATION_WORKFLOW_NAME = "(trace truncated)";
+/**
+ * Build the marker that stands in for the decisions a size budget dropped.
+ *
+ * The trace is truncated rather than discarded: a reader who is told nothing
+ * cannot tell "matching never ran" from "the trace was too large to keep", and
+ * those two have opposite answers to "why did my workflow not fire".
+ */
+export declare function createTraceTruncationMarker(omitted: number): Record<string, unknown>;
+/**
+ * UTF-8 byte length of `text`.
+ *
+ * Byte length, never `String.length`: the latter counts UTF-16 code units, so a
+ * CJK-heavy comment body measures at roughly a third of the bytes it actually
+ * costs on the wire and in the stored row.
+ */
+export declare function utf8ByteLength(text: string): number;
+/**
+ * Drop trailing decisions until the serialized array fits `maxBytes`, appending
+ * a marker naming how many were dropped.
+ *
+ * Shared by the orchestrator, which bounds what it puts on the wire, and the
+ * Platform, which bounds what it stores. Two independent budgets over one
+ * shape: keeping one implementation is what stops them from disagreeing about
+ * what a truncated trace looks like.
+ */
+export declare function truncateDecisionsToByteBudget<T>(decisions: readonly T[], maxBytes: number): {
+    decisions: Array<T | Record<string, unknown>>;
+    omitted: number;
+};
 /**
  * Create a workflow decision record.
  */

package/dist/trigger/decision-trace.js

@@ -1,15 +1,218 @@
 import "../rolldown-runtime-ClRpJifh.js";
+import { describeTextMatch } from "./text-match.js";
 //#region src/trigger/decision-trace.ts
 /**
+* Decision trace recording for debugging trigger matching.
+* Records every check performed during trigger evaluation.
+*/
+/**
+* Max characters of any free-text field a trace entry carries, so an
+* essay-length input stays bounded.
+*
+* The entry count is capped separately, downstream, but a count bound alone
+* bounds nothing: a single `paths` entry names every changed file in the push
+* and a single `bodyMatch` entry quotes a comment body an outsider authored, so
+* fifty entries can still be megabytes. The forwarded trace rides one WebSocket
+* frame to the Platform, and a frame past the server's payload ceiling closes
+* the connection — stalling every delivery for that organization until it
+* reconnects. Bounding at the point each field is minted is what makes the
+* downstream size guards a backstop rather than the only limit.
+*/
+const TRACE_TEXT_MAX = 200;
+/** Clamp one free-text trace field, marking a clamped value with an ellipsis. */
+function truncateTraceText(text) {
+	return text.length > 200 ? `${text.slice(0, 200)}…` : text;
+}
+/**
 * Create a new trace entry.
+*
+* Every free-text field is clamped here rather than at each call site: the
+* fields are fed from event content of unbounded size, and one unclamped call
+* site is enough to reintroduce an unbounded frame.
 */
 function createTraceEntry(check, pattern, value, passed, reason) {
 	return {
 		check,
-		pattern,
-		value,
+		pattern: truncateTraceText(pattern),
+		value: truncateTraceText(value),
 		passed,
-		reason
+		reason: reason === void 0 ? void 0 : truncateTraceText(reason)
+	};
+}
+/**
+* Stable `check` labels for the gates an organization-wide global workflow
+* passes on its way to dispatch.
+*
+* The other trigger checks are minted with free-text labels because each one
+* names the trigger field it read. These are named constants instead: they are
+* recorded in one package and read back in another — by code, and by whoever is
+* asking "why did nothing run?" — so a typo on either side would silently
+* produce a trace nobody can search for.
+*/
+const TraceCheck = {
+	/** `repos` glob/regex filter, deciding whether a workflow applies to the event's repo. */
+	RepoFilter: "repo",
+	/** Tier-1 declarative `requires` content filter, interpreted by the orchestrator. */
+	ContentRequirements: "requires",
+	/** Tier-2 `filter` predicate, run by an agent in the global eval round. */
+	GlobalFilter: "filter",
+	/** Tier-0 declarative `commitMessage` filter, read from the normalized event. */
+	CommitMessage: "commitMessage",
+	/** Materialization of a matched workflow's jobs, on the way to dispatch. */
+	Dispatch: "dispatch"
+};
+/**
+* Verdict vocabulary shared by both gates.
+*
+* `Indeterminate` is deliberately distinct from `Excluded`: a gate that could
+* not be evaluated did not decide anything, and reporting it as an exclusion
+* would tell a workflow author their filter said no when nothing ever ran it.
+*/
+const TraceVerdict = {
+	Matched: "matched",
+	Excluded: "excluded",
+	Indeterminate: "indeterminate"
+};
+/** Pick the verdict for a gate from its pass flag and whether it could decide. */
+function verdictFor(passed, indeterminate) {
+	if (indeterminate) return TraceVerdict.Indeterminate;
+	return passed ? TraceVerdict.Matched : TraceVerdict.Excluded;
+}
+/**
+* Record the Tier-1 `requires` content filter's verdict for one workflow.
+*
+* `files` is the set of repo-relative paths the requirement list reads, so the
+* entry names what was inspected as well as what it concluded.
+*/
+function createContentRequirementsTraceEntry(args) {
+	return createTraceEntry(TraceCheck.ContentRequirements, args.files.length > 0 ? args.files.join(", ") : "(no files)", verdictFor(args.passed, args.indeterminate === true), args.passed, args.reason);
+}
+/**
+* Record the Tier-2 `filter` predicate's verdict for one workflow.
+*
+* Without this entry a `filter` exclusion is invisible: the predicate runs on an
+* agent, returns `false`, and the workflow simply never appears — leaving its
+* author nothing to inspect. The entry is the answer to "why did nothing run?".
+*/
+function createGlobalFilterTraceEntry(args) {
+	return createTraceEntry(TraceCheck.GlobalFilter, "filter(context) === true", verdictFor(args.run, args.indeterminate === true), args.run, args.reason);
+}
+/**
+* Record that a matched workflow could not be materialized into jobs.
+*
+* A workflow whose triggers matched and whose build then threw is absent from
+* every other record: no run row is created and no job is queued. Omitting it
+* from the trace as well leaves its author unable to tell it apart from a
+* workflow that was never registered — the exact indistinguishability the trace
+* exists to remove.
+*/
+function createDispatchFailureTraceEntry(reason) {
+	return createTraceEntry(TraceCheck.Dispatch, "jobs materialize", TraceVerdict.Excluded, false, reason);
+}
+/**
+* Return a copy of `decision` with `entries` appended to its checks.
+*
+* A decision is treated as a value, never mutated in place: the same object is
+* read by the caller that recorded it, and a gate appending to it would
+* retroactively rewrite what an earlier reader saw.
+*
+* A failing appended entry demotes `matched` and replaces `summary`, because a
+* workflow whose triggers matched but whose content filter excluded it did NOT
+* match overall — reporting it as matched is precisely the invisible outcome
+* these entries exist to explain.
+*/
+function appendChecks(decision, entries) {
+	const failed = entries.find((entry) => !entry.passed);
+	return {
+		...decision,
+		matched: decision.matched && failed === void 0,
+		checks: [...decision.checks, ...entries],
+		summary: failed ? failed.reason ?? `Excluded by the ${failed.check} check` : decision.summary
+	};
+}
+/**
+* Record the Tier-0 `commitMessage` filter's verdict for one trigger.
+*
+* `text: undefined` means the event carried no message — an INDETERMINATE
+* verdict, deliberately distinct from an exclusion: reporting it as "excluded"
+* would tell an author their filter said no when nothing ever read it.
+*/
+function createCommitMessageTraceEntry(args) {
+	const shown = args.text === void 0 ? "(absent)" : args.text.length > 200 ? `${args.text.slice(0, 200)}…` : args.text;
+	return createTraceEntry(TraceCheck.CommitMessage, describeTextMatch(args.match), verdictFor(args.passed, args.indeterminate === true), args.passed, args.reason ?? `message: ${JSON.stringify(shown)}`);
+}
+/**
+* What a withheld trace field is replaced with when the reader does not hold
+* `event_log:read_payload`.
+*
+* Lives here rather than beside the Platform's redactor because three packages
+* read it: the Platform writes it, the dashboard renders it, and the E2E suite
+* asserts the permission boundary against it. A literal repeated at each site
+* would drift into a marker one of them no longer recognizes.
+*/
+const REDACTED_TRACE_FIELD = "[redacted — requires event_log:read_payload]";
+/**
+* Workflow name the truncation marker carries.
+*
+* A reserved sentinel rather than a real workflow: it is written by one package
+* and read back by two others, so a literal repeated at each site would drift
+* into a marker nobody recognizes.
+*/
+const TRACE_TRUNCATION_WORKFLOW_NAME = "(trace truncated)";
+/**
+* Build the marker that stands in for the decisions a size budget dropped.
+*
+* The trace is truncated rather than discarded: a reader who is told nothing
+* cannot tell "matching never ran" from "the trace was too large to keep", and
+* those two have opposite answers to "why did my workflow not fire".
+*/
+function createTraceTruncationMarker(omitted) {
+	return {
+		workflowName: TRACE_TRUNCATION_WORKFLOW_NAME,
+		matched: false,
+		traceTruncated: true,
+		decisionsOmitted: omitted,
+		checks: [],
+		checksCount: 0,
+		summary: (omitted === 1 ? "1 further workflow decision was dropped: " : `${omitted} further workflow decisions were dropped: `) + "the trace exceeded the size budget for this delivery."
+	};
+}
+/**
+* UTF-8 byte length of `text`.
+*
+* Byte length, never `String.length`: the latter counts UTF-16 code units, so a
+* CJK-heavy comment body measures at roughly a third of the bytes it actually
+* costs on the wire and in the stored row.
+*/
+function utf8ByteLength(text) {
+	return new TextEncoder().encode(text).length;
+}
+/**
+* Drop trailing decisions until the serialized array fits `maxBytes`, appending
+* a marker naming how many were dropped.
+*
+* Shared by the orchestrator, which bounds what it puts on the wire, and the
+* Platform, which bounds what it stores. Two independent budgets over one
+* shape: keeping one implementation is what stops them from disagreeing about
+* what a truncated trace looks like.
+*/
+function truncateDecisionsToByteBudget(decisions, maxBytes) {
+	if (utf8ByteLength(JSON.stringify(decisions)) <= maxBytes) return {
+		decisions: [...decisions],
+		omitted: 0
+	};
+	let used = 3 + utf8ByteLength(JSON.stringify(createTraceTruncationMarker(decisions.length)));
+	const kept = [];
+	for (const decision of decisions) {
+		const cost = utf8ByteLength(JSON.stringify(decision)) + 1;
+		if (used + cost > maxBytes) break;
+		used += cost;
+		kept.push(decision);
+	}
+	const omitted = decisions.length - kept.length;
+	return {
+		decisions: [...kept, createTraceTruncationMarker(omitted)],
+		omitted
 	};
 }
 /**
@@ -25,6 +228,6 @@ function createWorkflowDecision(workflowName, matched, checks, matchedTrigger, s
 	};
 }
 //#endregion
-export { createTraceEntry, createWorkflowDecision };
+export { REDACTED_TRACE_FIELD, TRACE_TEXT_MAX, TRACE_TRUNCATION_WORKFLOW_NAME, TraceCheck, TraceVerdict, appendChecks, createCommitMessageTraceEntry, createContentRequirementsTraceEntry, createDispatchFailureTraceEntry, createGlobalFilterTraceEntry, createTraceEntry, createTraceTruncationMarker, createWorkflowDecision, truncateDecisionsToByteBudget, truncateTraceText, utf8ByteLength };
 
 //# sourceMappingURL=decision-trace.js.map

package/dist/trigger/jsonpath-matcher.js

@@ -1,4 +1,5 @@
 import "../rolldown-runtime-ClRpJifh.js";
+import { assertSafeRegex } from "../safe-regex.js";
 import { JSONPath } from "jsonpath-plus";
 //#region src/trigger/jsonpath-matcher.ts
 /**
@@ -81,7 +82,10 @@ function matchValue(results, expected) {
 function valueEquals(result, expected) {
 	if (typeof expected === "string" && typeof result === "string") {
 		const regexMatch = /^\/(.+)\/([gimsuy]*)$/.exec(expected);
-		if (regexMatch) return new RegExp(regexMatch[1], regexMatch[2]).test(result);
+		if (regexMatch) {
+			assertSafeRegex(regexMatch[1], regexMatch[2], "jsonpath match");
+			return new RegExp(regexMatch[1], regexMatch[2]).test(result);
+		}
 		return result === expected;
 	}
 	return result === expected;