@kici-dev/engine 0.4.0 → 0.5.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 = 1024 * 1024;
+/**
+* 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.
  */
@@ -34,6 +35,94 @@ export interface WorkflowDecision {
  * Create a new trace entry.
  */
 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';
+};
+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;
+/**
+ * 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;
 /**
  * Create a workflow decision record.
  */

package/dist/trigger/decision-trace.js

@@ -1,6 +1,11 @@
 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.
+*/
+/**
 * Create a new trace entry.
 */
 function createTraceEntry(check, pattern, value, passed, reason) {
@@ -13,6 +18,96 @@ function createTraceEntry(check, pattern, value, passed, 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"
+};
+/**
+* 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);
+}
+/**
+* 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
+	};
+}
+/** Max characters of the message recorded in a trace, so an essay-length body stays bounded. */
+const TRACE_TEXT_MAX = 200;
+/**
+* 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 > TRACE_TEXT_MAX ? `${args.text.slice(0, TRACE_TEXT_MAX)}…` : args.text;
+	return createTraceEntry(TraceCheck.CommitMessage, describeTextMatch(args.match), verdictFor(args.passed, args.indeterminate === true), args.passed, args.reason ?? `message: ${JSON.stringify(shown)}`);
+}
+/**
 * Create a workflow decision record.
 */
 function createWorkflowDecision(workflowName, matched, checks, matchedTrigger, summary) {
@@ -25,6 +120,6 @@ function createWorkflowDecision(workflowName, matched, checks, matchedTrigger, s
 	};
 }
 //#endregion
-export { createTraceEntry, createWorkflowDecision };
+export { TraceCheck, TraceVerdict, appendChecks, createCommitMessageTraceEntry, createContentRequirementsTraceEntry, createGlobalFilterTraceEntry, createTraceEntry, createWorkflowDecision };
 
 //# 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;

package/dist/trigger/matcher.js

@@ -1,6 +1,7 @@
 import "../rolldown-runtime-ClRpJifh.js";
-import { createTraceEntry, createWorkflowDecision } from "./decision-trace.js";
-import { getCompiledRegex, getGlobMatcher } from "./compiled-matchers.js";
+import { evaluateTextMatch } from "./text-match.js";
+import { TraceCheck, createCommitMessageTraceEntry, createTraceEntry, createWorkflowDecision } from "./decision-trace.js";
+import { getCompiledRegex, getGlobMatcher, getRepoGlobMatcher } from "./compiled-matchers.js";
 import { matchJsonPath, matchJsonPathNot } from "./jsonpath-matcher.js";
 //#region src/trigger/matcher.ts
 /**
@@ -35,7 +36,21 @@ function splitBranchPatterns(patterns) {
 */
 function matchBranchPattern(pattern, branch) {
 	if (pattern.type === "glob") return getGlobMatcher(pattern.pattern)(branch);
-	else return getCompiledRegex(pattern.pattern, pattern.flags).test(branch);
+	else return getCompiledRegex(pattern.pattern, pattern.flags, "branch/tag/repo pattern").test(branch);
+}
+/**
+* Match a repo pattern against a repository identifier.
+*
+* Same shape as {@link matchBranchPattern}, but glob patterns compile through
+* {@link getRepoGlobMatcher} so a dot-prefixed identifier (`.hidden/repo`) is
+* matched by `**`. Repo identifiers are org/name pairs, not paths, so there is
+* no dotfile convention to respect — and `repos: ['**']` means every repo.
+*
+* Regex patterns are unaffected: `dot` is a glob option with no regex analogue.
+*/
+function matchRepoPattern(pattern, repo) {
+	if (pattern.type === "glob") return getRepoGlobMatcher(pattern.pattern)(repo);
+	return getCompiledRegex(pattern.pattern, pattern.flags, "branch/tag/repo pattern").test(repo);
 }
 /**
 * Match any of the branch patterns.
@@ -73,10 +88,10 @@ function matchRepoPatterns(repos, sourceRepo) {
 	if (repos.length === 0) return true;
 	const { include, exclude } = splitBranchPatterns(repos);
 	if (exclude.length > 0) {
-		if (exclude.some((p) => matchBranchPattern(p, sourceRepo))) return false;
+		if (exclude.some((p) => matchRepoPattern(p, sourceRepo))) return false;
 	}
 	if (include.length === 0) return true;
-	return include.some((p) => matchBranchPattern(p, sourceRepo));
+	return include.some((p) => matchRepoPattern(p, sourceRepo));
 }
 /**
 * Evaluate repo pattern filter for a trigger against an event.
@@ -86,17 +101,48 @@ function matchRepoPatterns(repos, sourceRepo) {
 function evaluateRepoFilter(trigger, event, traces) {
 	if (trigger.repos?.length) {
 		if (!event.sourceRepo) {
-			traces.push(createTraceEntry("repo", "required", "(missing)", false));
+			traces.push(createTraceEntry(TraceCheck.RepoFilter, "required", "(missing)", false));
 			return false;
 		}
 		const { include, exclude } = splitBranchPatterns(trigger.repos);
 		const repoMatch = matchRepoPatterns(trigger.repos, event.sourceRepo);
-		traces.push(createTraceEntry("repo", `include:[${include.map((p) => p.pattern).join(",")}] exclude:[${exclude.map((p) => p.pattern).join(",")}]`, event.sourceRepo, repoMatch));
+		traces.push(createTraceEntry(TraceCheck.RepoFilter, `include:[${include.map((p) => p.pattern).join(",")}] exclude:[${exclude.map((p) => p.pattern).join(",")}]`, event.sourceRepo, repoMatch));
 		if (!repoMatch) return false;
 	}
 	return true;
 }
 /**
+* Evaluate a trigger's `commitMessage` filter. Returns true when the trigger
+* declares none (the fast path).
+*
+* An event with no message is INDETERMINATE, not a clean exclusion: the filter
+* is fail-visible, mirroring the Tier-1 `requires` gate, so a workflow whose
+* declared gate was never evaluated does not run.
+*/
+function evaluateCommitMessageFilter(trigger, event, traces) {
+	const match = trigger.commitMessage;
+	if (!match) return true;
+	if (event.commitMessage === void 0) {
+		traces.push(createCommitMessageTraceEntry({
+			match,
+			text: void 0,
+			passed: false,
+			indeterminate: true,
+			reason: "no commit message in payload (provider carries none for this event)"
+		}));
+		return false;
+	}
+	const result = evaluateTextMatch(event.commitMessage, match);
+	traces.push(createCommitMessageTraceEntry({
+		match,
+		text: event.commitMessage,
+		passed: result.pass,
+		indeterminate: result.indeterminate !== void 0,
+		...result.indeterminate !== void 0 && { reason: result.indeterminate }
+	}));
+	return result.pass;
+}
+/**
 * Match a PR trigger against a simulated event.
 */
 function matchPrTrigger(trigger, event, traces) {
@@ -132,6 +178,7 @@ function matchPrTrigger(trigger, event, traces) {
 		traces.push(createTraceEntry("paths", `include: [${include.join(", ")}] exclude: [${exclude.join(", ")}]`, event.changedFilesStatus === "unavailable" ? "[unavailable — matched conservatively]" : `[${changedFiles.join(", ")}]`, matches));
 		if (!matches) return false;
 	}
+	if (!evaluateCommitMessageFilter(trigger, event, traces)) return false;
 	if (!evaluateRepoFilter(trigger, event, traces)) return false;
 	return true;
 }
@@ -156,6 +203,7 @@ function matchPushTrigger(trigger, event, traces) {
 		traces.push(createTraceEntry("paths", `include: [${include.join(", ")}] exclude: [${exclude.join(", ")}]`, event.changedFilesStatus === "unavailable" ? "[unavailable — matched conservatively]" : `[${changedFiles.join(", ")}]`, matches));
 		if (!matches) return false;
 	}
+	if (!evaluateCommitMessageFilter(trigger, event, traces)) return false;
 	if (!evaluateRepoFilter(trigger, event, traces)) return false;
 	return true;
 }
@@ -174,6 +222,7 @@ function matchTagTrigger(trigger, event, traces) {
 		traces.push(createTraceEntry("tag pattern", trigger.patterns.map((p) => p.pattern).join("|"), event.targetBranch, matches));
 		if (!matches) return false;
 	}
+	if (!evaluateCommitMessageFilter(trigger, event, traces)) return false;
 	if (!evaluateRepoFilter(trigger, event, traces)) return false;
 	return true;
 }
@@ -213,7 +262,7 @@ function matchCommentTrigger(trigger, event, traces) {
 			traces.push(createTraceEntry("bodyMatch (glob)", trigger.bodyMatch.pattern, body, matches));
 			if (!matches) return false;
 		} else {
-			const matches = getCompiledRegex(trigger.bodyMatch.pattern, trigger.bodyMatch.flags).test(body);
+			const matches = getCompiledRegex(trigger.bodyMatch.pattern, trigger.bodyMatch.flags, "comment bodyMatch").test(body);
 			traces.push(createTraceEntry("bodyMatch (regex)", trigger.bodyMatch.pattern, body, matches));
 			if (!matches) return false;
 		}

package/dist/trigger/text-match.d.ts

@@ -0,0 +1,27 @@
+import type { LockTextMatch, TextMatch } from './types.js';
+/** A definite verdict, or fail-visible indeterminate. Mirrors `ContentRequirementResult`. */
+export interface TextMatchResult {
+    readonly pass: boolean;
+    /** Set (with `pass: false`) when the match could not be evaluated. */
+    readonly indeterminate?: string;
+}
+/**
+ * Compile a `/pattern/flags` (or bare-pattern) string, rejecting a ReDoS-prone
+ * pattern. Returns `null` when the pattern is syntactically invalid or fails the
+ * `safe-regex` star-height heuristic — callers treat `null` as indeterminate.
+ *
+ * Always compiles a FRESH RegExp. A `g`-flagged instance carries `lastIndex`
+ * across `.test()` calls, so a cached one would return alternating verdicts for
+ * the same input.
+ */
+export declare function compileSafeRegex(source: string): RegExp | null;
+/** True when the matcher carries at least one populated query key. */
+export declare function textMatchHasQuery(m: TextMatch | LockTextMatch): boolean;
+/** Render the populated keys for a decision-trace `pattern` field. */
+export declare function describeTextMatch(m: LockTextMatch): string;
+/**
+ * Evaluate a text match. Every entry in every list is a conjunct, and every
+ * populated key ANDs with the others; an empty matcher passes.
+ */
+export declare function evaluateTextMatch(text: string, m: LockTextMatch): TextMatchResult;
+//# sourceMappingURL=text-match.d.ts.map

package/dist/trigger/text-match.js

@@ -0,0 +1,86 @@
+import "../rolldown-runtime-ClRpJifh.js";
+import safeRegex from "safe-regex";
+//#region src/trigger/text-match.ts
+/**
+* The single definition of what `contains` / `notContains` / `matches` /
+* `notMatches` mean.
+*
+* Two sites consume it: the Tier-0 `commitMessage` trigger filter (in
+* `matcher.ts`) and the Tier-1 `requires` content filter (in
+* `content-requirements.ts`). Sharing one function is what keeps them from
+* drifting into two dialects of the same vocabulary.
+*
+* Pure string logic — it imports only `safe-regex` and no Node built-in, so it
+* belongs in the browser-safe barrel rather than a subpath export.
+*/
+/**
+* Compile a `/pattern/flags` (or bare-pattern) string, rejecting a ReDoS-prone
+* pattern. Returns `null` when the pattern is syntactically invalid or fails the
+* `safe-regex` star-height heuristic — callers treat `null` as indeterminate.
+*
+* Always compiles a FRESH RegExp. A `g`-flagged instance carries `lastIndex`
+* across `.test()` calls, so a cached one would return alternating verdicts for
+* the same input.
+*/
+function compileSafeRegex(source) {
+	const wrapped = /^\/(.+)\/([gimsuy]*)$/.exec(source);
+	const pattern = wrapped ? wrapped[1] : source;
+	const flags = wrapped ? wrapped[2] : "";
+	let re;
+	try {
+		re = new RegExp(pattern, flags);
+	} catch {
+		return null;
+	}
+	return safeRegex(re) ? re : null;
+}
+/** True when the matcher carries at least one populated query key. */
+function textMatchHasQuery(m) {
+	const populated = (v) => Array.isArray(v) ? v.length > 0 : v !== void 0 && v !== null;
+	return populated(m.contains) || populated(m.notContains) || populated(m.matches) || populated(m.notMatches);
+}
+/** Render the populated keys for a decision-trace `pattern` field. */
+function describeTextMatch(m) {
+	const parts = [];
+	if (m.contains?.length) parts.push(`contains: [${m.contains.join(", ")}]`);
+	if (m.notContains?.length) parts.push(`notContains: [${m.notContains.join(", ")}]`);
+	if (m.matches?.length) parts.push(`matches: [${m.matches.join(", ")}]`);
+	if (m.notMatches?.length) parts.push(`notMatches: [${m.notMatches.join(", ")}]`);
+	if (m.ignoreCase) parts.push("ignoreCase");
+	return parts.length > 0 ? parts.join("; ") : "(no query)";
+}
+/** Evaluate every regex in `sources`; `expectMatch` selects matches vs notMatches. */
+function evaluateRegexes(text, sources, expectMatch) {
+	for (const source of sources) {
+		const re = compileSafeRegex(source);
+		if (!re) return {
+			pass: false,
+			indeterminate: `unsafe or invalid regex: ${source}`
+		};
+		if (re.test(text) !== expectMatch) return { pass: false };
+	}
+	return { pass: true };
+}
+/**
+* Evaluate a text match. Every entry in every list is a conjunct, and every
+* populated key ANDs with the others; an empty matcher passes.
+*/
+function evaluateTextMatch(text, m) {
+	const fold = (s) => m.ignoreCase === true ? s.toLowerCase() : s;
+	const haystack = fold(text);
+	for (const needle of m.contains ?? []) if (!haystack.includes(fold(needle))) return { pass: false };
+	for (const needle of m.notContains ?? []) if (haystack.includes(fold(needle))) return { pass: false };
+	if (m.matches?.length) {
+		const result = evaluateRegexes(text, m.matches, true);
+		if (!result.pass) return result;
+	}
+	if (m.notMatches?.length) {
+		const result = evaluateRegexes(text, m.notMatches, false);
+		if (!result.pass) return result;
+	}
+	return { pass: true };
+}
+//#endregion
+export { compileSafeRegex, describeTextMatch, evaluateTextMatch, textMatchHasQuery };
+
+//# sourceMappingURL=text-match.js.map