@cat-factory/kernel 0.159.1 → 0.161.0

package/dist/shared/host-markdown.logic.js

@@ -0,0 +1,202 @@
+// ---------------------------------------------------------------------------
+// The TEXT BOUNDARY for anything this platform writes onto a VCS/tracker host.
+//
+// A pull-request description — or an issue comment — is NOT an inert string sink. The host
+// parses it: `#123` becomes an issue link, `@name` notifies a real person, a closing keyword
+// in front of an issue reference CLOSES that issue when the PR merges, a newline ends a
+// markdown table row, and an unbalanced code fence swallows everything after it — including
+// the machine-readable JSON block external tooling ingests.
+//
+// Almost everything we splice into such a body is written by an agent or a human (a task
+// title, a tester summary, a merge rationale, a provisioner's stderr, a requirements
+// reviewer's question), so all of those are live hazards rather than theoretical ones: "This
+// closes #42" is idiomatic prose for a merge rationale to emit, and it must not close issue
+// 42; "@alice should decide the rounding rule" is idiomatic for a reviewer finding, and it
+// must not page whoever owns that handle.
+//
+// This module is the single place that turns untrusted text into something safe to send to a
+// host. It lives in kernel because it has TWO consumers on opposite sides of the architecture
+// — the PR verification report (orchestration) and the tracker-issue writebacks
+// (integrations) — and a second copy of these escapes is exactly how one of them would drift
+// into notifying real accounts. It is deliberately separate from the composers (which decide
+// WHAT to say) and from the marker splice in `domain/pr-report.ts` (which decides WHERE it
+// goes).
+//
+// Adding a field to any host-bound body means picking one of {@link inline}, {@link cell} or
+// {@link prose} for it — never a bare template hole.
+// ---------------------------------------------------------------------------
+/** Free-text prose (a tester summary, a merge rationale) is capped at this many characters. */
+export const MAX_PROSE_CHARS = 4_000;
+/** A single markdown table cell is capped at this many characters. */
+export const MAX_CELL_CHARS = 300;
+/** Any rendered list/table in the report is capped at this many rows. */
+export const MAX_LIST_ITEMS = 50;
+/**
+ * Hard ceiling for the whole rendered section. GitHub rejects a PR body over 65,536
+ * characters with a 422, and the body also has to hold the agent's own description, so the
+ * managed region keeps well clear of the limit. With the per-field caps above this is
+ * unreachable for realistic runs; it exists so that pathological data degrades visibly
+ * instead of making every publish fail silently forever.
+ */
+export const MAX_SECTION_CHARS = 50_000;
+/** Marks where a value was cut, so a reader never mistakes a truncation for the whole story. */
+const TRUNCATION_NOTE = '… (truncated)';
+/**
+ * The host's closing keywords. A PR body carrying one of these in front of an issue reference
+ * closes that issue on merge — a side effect the engine must never trigger on the agent's
+ * behalf. Same list on GitHub and GitLab.
+ */
+const CLOSING_KEYWORDS = 'close[sd]?|closing|fix|fixe[sd]|fixing|resolve[sd]?|resolving|implement(?:s|ed)?|implementing';
+/** An issue/MR URL on either host, in the form a closing keyword can reference. */
+const ISSUE_URL = String.raw `https?://\S+?/(?:issues|-/issues|merge_requests|pull)/\d+`;
+/**
+ * Every auto-linking trigger, in ONE alternation.
+ *
+ * Deliberately a single pass rather than chained `.replace()` calls: each escape EMITS a `#`,
+ * so a later rule would re-escape the output of an earlier one (`@` → `@` → `@`).
+ * One regex means the replacement text is never rescanned.
+ */
+const AUTO_LINK_TRIGGERS = new RegExp([
+    // A closing keyword in front of an issue/MR URL. The URL form survives the character
+    // escapes below (nothing in it is a trigger), so the KEYWORD is what gets defused.
+    String.raw `(?<keyword>\b(?:${CLOSING_KEYWORDS}))(?=\s*:?\s+${ISSUE_URL})`,
+    // `@name` / `@org/team` — a mention notifies a real account.
+    String.raw `(?<at>@(?=[A-Za-z0-9]))`,
+    // `#123` and `owner/repo#123` — an issue/PR cross-reference.
+    String.raw `(?<hash>#(?=\d))`,
+    // `!123` — GitLab's merge-request reference.
+    String.raw `(?<bang>!(?=\d))`,
+].join('|'), 'gi');
+/**
+ * Neutralise the host's auto-linking triggers in ONE line of untrusted text, leaving inline
+ * code spans alone (the host does not auto-link inside them, so escaping there would only
+ * show the reader a literal `&#35;`).
+ *
+ * The escapes are numeric HTML entities, which render as the original character but are
+ * invisible to the reference parser — so the reader sees exactly what the agent wrote while
+ * the mention/close side effects are defused.
+ */
+function inertLine(line) {
+    return mapOutsideCodeSpans(line, (text) => text.replace(AUTO_LINK_TRIGGERS, (match, ...args) => {
+        const groups = args[args.length - 1];
+        // Entity-escaping the FIRST character is enough to break the parser's match while
+        // rendering identically — which matters most for the keyword, whose remaining letters
+        // are ordinary prose the reader should still see.
+        return `&#${match.charCodeAt(0)};${groups.keyword ? match.slice(1) : ''}`;
+    }));
+}
+/**
+ * Apply `fn` to the parts of `line` that are NOT inline code spans. Code spans are matched by
+ * a backtick run and its matching closer, which is CommonMark's rule and — more to the point
+ * — the rule the host renderer applies when deciding where to auto-link.
+ */
+function mapOutsideCodeSpans(line, fn) {
+    const out = [];
+    let index = 0;
+    const span = /(`+)[\s\S]*?\1/g;
+    let match;
+    while ((match = span.exec(line)) !== null) {
+        out.push(fn(line.slice(index, match.index)), match[0]);
+        index = match.index + match[0].length;
+    }
+    return out.join('') + fn(line.slice(index));
+}
+/** A line that opens or closes a fenced code block, with the fence it uses. */
+function fenceAt(line) {
+    const match = /^ {0,3}(`{3,}|~{3,})(.*)$/.exec(line);
+    if (!match)
+        return null;
+    const fence = match[1];
+    // A ``` fence's info string may not contain a backtick (CommonMark), which is what stops an
+    // inline span from being read as a fence.
+    if (fence.startsWith('`') && match[2].includes('`'))
+        return null;
+    return { char: fence[0], length: fence.length, info: match[2].trim().length > 0 };
+}
+/**
+ * Walk `lines`, tracking fenced-code state, and hand each line to `visit` together with
+ * whether it sits INSIDE a fenced block. Returns the fence still open at the end, if any.
+ *
+ * One shared walker so the two things that care about fences — leaving code untouched, and
+ * closing what the text left open — can never disagree about where a block starts and ends.
+ */
+function walkFences(lines, visit) {
+    let open = null;
+    for (const line of lines) {
+        const fence = fenceAt(line);
+        // The fence line itself belongs to the code block, so it is never rewritten.
+        visit(line, open !== null || fence !== null);
+        if (!fence)
+            continue;
+        if (!open)
+            open = { char: fence.char, length: fence.length };
+        else if (fence.char === open.char && fence.length >= open.length && !fence.info)
+            open = null;
+    }
+    return open;
+}
+/**
+ * Close any code fence the text leaves open.
+ *
+ * An unbalanced fence in agent prose — an interrupted transcript, a truncated tool dump — would
+ * otherwise swallow every section rendered after it, including the fenced JSON block that is
+ * the report's machine-readable contract. Balancing preserves the agent's own formatting
+ * (unlike escaping the fences) while guaranteeing the enclosing document stays well-formed.
+ */
+export function balanceFences(text) {
+    const open = walkFences(text.split('\n'), () => { });
+    return open ? `${text}\n${open.char.repeat(open.length)}` : text;
+}
+/** Cut `value` to `max` characters, marking the cut. Prefers a line boundary when one is near. */
+function truncate(value, max) {
+    if (value.length <= max)
+        return value;
+    const head = value.slice(0, max);
+    const lastNewline = head.lastIndexOf('\n');
+    const body = lastNewline > max * 0.6 ? head.slice(0, lastNewline) : head;
+    return `${body.trimEnd()}\n\n${TRUNCATION_NOTE}`;
+}
+/**
+ * Render untrusted multi-line prose as a safe markdown block: auto-link triggers defused,
+ * length capped, and any code fence the value leaves open closed again.
+ *
+ * `max` lets a caller with a tighter budget than a PR body (a tracker comment renders many of
+ * these into one payload, and Jira rejects an oversized comment outright) cut to ITS limit —
+ * the cut happens BEFORE the escapes, so an entity can never be sliced in half.
+ */
+export function prose(value, max = MAX_PROSE_CHARS) {
+    const capped = truncate(value.replace(/\r\n?/g, '\n'), max);
+    const rewritten = [];
+    const open = walkFences(capped.split('\n'), (line, insideFence) => {
+        rewritten.push(insideFence ? line : inertLine(line));
+    });
+    const text = rewritten.join('\n');
+    return open ? `${text}\n${open.char.repeat(open.length)}` : text;
+}
+/**
+ * Render untrusted text as ONE markdown table cell: newlines folded to `<br>` (a raw newline
+ * ends the row and spills the rest of the value into the document as loose prose), pipes
+ * escaped so a value cannot open a new column, auto-link triggers defused, and the whole thing
+ * capped so a stack trace cannot dominate the table.
+ */
+export function cell(value) {
+    const flattened = truncate(value.replace(/\r\n?/g, '\n'), MAX_CELL_CHARS)
+        .replaceAll('|', '\\|')
+        .replace(/\n+/g, '<br>');
+    return inertLine(flattened);
+}
+/**
+ * Render untrusted text INLINE (a title, a label — not a table cell, so pipes are harmless).
+ * Newlines are folded to spaces because the surrounding line has its own meaning. `max` caps
+ * to a caller's own budget, before the escapes, exactly as in {@link prose}.
+ */
+export function inline(value, max = MAX_CELL_CHARS) {
+    return inertLine(truncate(value.replace(/\s+/g, ' '), max));
+}
+/** Cap a list at {@link MAX_LIST_ITEMS}, returning the kept rows plus how many were dropped. */
+export function capList(items) {
+    if (items.length <= MAX_LIST_ITEMS)
+        return { items: [...items], dropped: 0 };
+    return { items: items.slice(0, MAX_LIST_ITEMS), dropped: items.length - MAX_LIST_ITEMS };
+}
+//# sourceMappingURL=host-markdown.logic.js.map

package/dist/shared/host-markdown.logic.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-markdown.logic.js","sourceRoot":"","sources":["../../src/shared/host-markdown.logic.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/kernel",
-  "version": "0.159.1",
+  "version": "0.161.0",
   "description": "Shared vocabulary, pure logic, and port interfaces for the Agent Architecture Board.",
   "repository": {
     "type": "git",
@@ -26,7 +26,7 @@
   "dependencies": {
     "ai": "^7.0.35",
     "yaml": "^2.9.0",
-    "@cat-factory/contracts": "0.165.0"
+    "@cat-factory/contracts": "0.167.0"
   },
   "devDependencies": {
     "@vitest/coverage-v8": "^4.1.10",