src/rule-docs.ts

Functions

Imports

It imports src/jobs-schema.ts, src/ops-types/views.ts, src/scope.ts, src/tools/surface.ts. Imported by src/maintenance.ts, src/tools/docs-lifecycle.ts, src/tools/docs-write.ts, src/truth-report.ts.

Source

1// The rule documents: the ones sessions follow as rules rather than read as records
2// (job_c13dc0d4f22f). Two checks hold them:
3//
4//   - the cap. A namespace's core.md stays under 8KB, any other rule document under 20KB.
5//   - stale tool names. A rule document names no tool or action the Worker does not
6//     serve. A session that follows a rule naming a removed tool fails at the call.
7//
8// Dated records (archive/, research/, reports/, audits/, jobs/) are not rule documents:
9// they say what was true when written, and an old tool name there is history.
10//
11// Three places run the checks. capsid_write_doc refuses a write that makes a rule document
12// worse (ruleDocWriteRefusal: over the cap and larger than before, or a stale name the
13// stored body did not have), so an over-cap document can still be cut in steps.
14// capsid_lint_namespace mode report lists every violation in the namespace, and the daily
15// maintenance pass files one finding per violating document. test/rule-docs.test.ts
16// plants both kinds.
17
18import { rewriteProse, OLD_TOOLS } from "../scripts/tool-names-lib";
19import { TOOL_GRANTS } from "./scope";
20import { COMPOSITES } from "./tools/surface";
21import { JOB_ACTIONS } from "./jobs-schema";
22import type { OpsMaintenanceItem } from "./ops-types/views";
23
24export const CORE_CAP_BYTES = 8 * 1024;
25export const RULE_DOC_CAP_BYTES = 20 * 1024;
26
27const CONVENTIONS = /^conventions(-[a-z0-9]+)*\.md$/;
28const DECISIONS = /^decisions\.md$/;
29// One document directly inside rulings/, no deeper (src/portfolio-docs.ts reads it the same way).
30const RULING = /^rulings\/[a-z0-9][a-z0-9._-]*\.md$/;
31
32/** The byte cap of a rule document, or null when the path is not one. */
33export function ruleDocCap(namespace: string, path: string): number | null {
34  if (path === "core.md") return CORE_CAP_BYTES;
35  if (DECISIONS.test(path)) return RULE_DOC_CAP_BYTES;
36  if (namespace !== "capsid") return null;
37  if (CONVENTIONS.test(path) || RULING.test(path)) return RULE_DOC_CAP_BYTES;
38  return null;
39}
40
41const byteLength = (text: string): number => new TextEncoder().encode(text).length;
42
43// The served surface, as tool -> its actions (null: the tool takes none this check knows).
44// Composite actions come from src/tools/surface.ts; capsid_work_jobs's from its schema.
45const SERVED: ReadonlyMap<string, ReadonlySet<string> | null> = (() => {
46  const out = new Map<string, ReadonlySet<string> | null>();
47  for (const tool of Object.keys(TOOL_GRANTS)) out.set(tool, null);
48  for (const spec of COMPOSITES) out.set(spec.name, new Set(Object.keys(spec.actions)));
49  out.set("capsid_work_jobs", new Set(JOB_ACTIONS));
50  return out;
51})();
52
53// Every action some served tool takes. An old tool name that is still an action somewhere
54// (create_branch, delete_branch) is not stale when it stands alone.
55const SERVED_ACTIONS: ReadonlySet<string> = new Set([...SERVED.values()].flatMap((a) => (a ? [...a] : [])));
56
57// Old names with an underscore are not words, so outside backticks they still name the old
58// tool. rewriteProse reads only backtick spans and calls; this reads the rest. open_pr is
59// excluded for the reason rewriteProse gives (it is also a gate class). A name followed by
60// "(" is a call, which rewriteProse already reads.
61const BARE_OLD = OLD_TOOLS.filter((name) => name.includes("_") && name !== "open_pr" && !SERVED_ACTIONS.has(name));
62const BARE_OLD_RE = new RegExp(`(?<![\\w./-])(${BARE_OLD.join("|")})(?![\\w(-])`, "g");
63
64// An old tool name as a whole word, to say which names a line rewriteProse rewrote held.
65// Inside capsid_work_jobs, "jobs" follows an underscore and is not a match.
66const OLD_WORD = new RegExp(`(?<![\\w-])(${OLD_TOOLS.slice().sort((a, b) => b.length - a.length).join("|")})(?![\\w-])`, "g");
67
68// A capsid_* name where the text says it is a tool: a call, a dotted action, an action
69// after it, the word tool after it, or "call" before it. A capsid_* field, column or
70// cookie (capsid_sha, capsid_portal_csrf) is not a tool and is not read. A Capsid Admin
71// name is a tool wherever it appears.
72const CAPSID_NAME = /(?<![\w-])(capsid_[a-z][a-z_]*[a-z])(?![\w-])`?(?:(\()|\.([a-z_]+)\b|\s+\(?actions?\s+[`"]([a-z_]+)[`"]|\s+(?:\(?actions?|tools?)\b)?/g;
73const CALL_BEFORE = /\b(call|calls|calling|called|tool|tools|use|ask)\s+`?$/i;
74
75/** One stale reference: the line it is on and the name it uses. */
76export interface StaleName {
77  line: number;
78  text: string;
79}
80
81function multiset(names: string[]): Map<string, number> {
82  const out = new Map<string, number>();
83  for (const n of names) out.set(n, (out.get(n) ?? 0) + 1);
84  return out;
85}
86
87/** Every tool or action reference in `text` that the Worker does not serve. Fenced code is
88 *  not read: a SQL or JS example there is not a tool reference. */
89export function staleToolNames(text: string): StaleName[] {
90  const found: StaleName[] = [];
91  // "write(s)" and "item(es)" are plurals, not calls.
92  const prose = rewriteProse(text.replace(/\((?:s|es)\)/g, ""));
93  // Old names in backtick spans and calls, the migration's own reading of prose. Each
94  // rewritten line reports the old names it lost, so an edit elsewhere on the line is not
95  // a new stale name.
96  for (const c of prose.changes) {
97    const lost = multiset([...c.before.matchAll(OLD_WORD)].map((m) => m[1]));
98    for (const m of c.after.matchAll(OLD_WORD)) lost.set(m[1], (lost.get(m[1]) ?? 0) - 1);
99    for (const [name, n] of lost) for (let k = 0; k < n; k++) found.push({ line: c.line, text: name });
100  }
101  for (const u of prose.unmapped) found.push({ line: u.line, text: [...u.text.matchAll(OLD_WORD)][0]?.[1] ?? u.text.trim() });
102  let fenced = false;
103  text.split("\n").forEach((raw, i) => {
104    if (/^\s*(```|~~~)/.test(raw)) {
105      fenced = !fenced;
106      return;
107    }
108    if (fenced) return;
109    const line = i + 1;
110    const outside = raw.replace(/`[^`]*`/g, "``");
111    for (const m of outside.matchAll(BARE_OLD_RE)) found.push({ line, text: m[1] });
112    // capsid_* names: the tool must be served, and an action given must be one of its own.
113    for (const m of raw.matchAll(CAPSID_NAME)) {
114      const [whole, tool, called, dotted, named] = m;
115      const said = whole.slice(tool.length).replace(/^`/, "").length > 0 || called !== undefined || CALL_BEFORE.test(raw.slice(0, m.index)) || tool.startsWith("capsid_admin_");
116      if (!SERVED.has(tool)) {
117        if (said) found.push({ line, text: tool });
118        continue;
119      }
120      const action = dotted ?? named;
121      const actions = SERVED.get(tool);
122      if (action !== undefined && actions && !actions.has(action)) found.push({ line, text: `${tool} action ${action}` });
123    }
124  });
125  return found.sort((a, b) => a.line - b.line);
126}
127
128/** The stale names as one clause: the count and the first five. */
129export function staleSummary(stale: readonly StaleName[]): string {
130  return `${stale.length} tool(s) or action(s) the Worker does not serve: ${stale.slice(0, 5).map((s) => `line ${s.line} "${s.text}"`).join("; ")}`;
131}
132
133/** What is wrong with one rule document, or null when it is not one or nothing is. */
134export interface RuleDocProblem {
135  namespace: string;
136  path: string;
137  bytes: number;
138  cap: number;
139  oversize: boolean;
140  stale: StaleName[];
141}
142
143export function ruleDocProblem(namespace: string, path: string, body: string): RuleDocProblem | null {
144  const cap = ruleDocCap(namespace, path);
145  if (cap === null) return null;
146  const bytes = byteLength(body);
147  const stale = staleToolNames(body);
148  if (bytes <= cap && stale.length === 0) return null;
149  return { namespace, path, bytes, cap, oversize: bytes > cap, stale };
150}
151
152/** One line per problem, for a refusal, a report or a finding. */
153function describeRuleDocProblem(p: RuleDocProblem): string {
154  const parts: string[] = [];
155  if (p.oversize) parts.push(`${p.bytes} bytes, over its ${p.cap}-byte cap`);
156  if (p.stale.length > 0) parts.push(`names ${staleSummary(p.stale)}`);
157  return `${p.namespace}/${p.path}: ${parts.join("; ")}`;
158}
159
160/** Refuse a write that makes a rule document worse: over its cap and larger than the
161 *  stored body, or naming a stale tool the stored body did not. A write that cuts an
162 *  over-cap document, or leaves an existing stale name alone, passes, so a violating
163 *  document can be fixed in steps. Null when the write may go ahead. */
164export function ruleDocWriteRefusal(namespace: string, path: string, before: string | null, after: string): string | null {
165  const problem = ruleDocProblem(namespace, path, after);
166  if (!problem) return null;
167  const reasons: string[] = [];
168  if (problem.oversize && (before === null || byteLength(after) > byteLength(before))) {
169    const next = path === "core.md" ? "Rewrite it shorter: current facts only." : DECISIONS.test(path) ? "Fold rulings into the rules they changed, or move settled ones to archive/." : "Cut it, or split it by subject.";
170    reasons.push(`it would be ${problem.bytes} bytes, over the ${problem.cap}-byte cap for this rule document${before === null ? "" : ` and larger than the ${byteLength(before)} bytes stored`}. ${next}`);
171  }
172  const had = multiset(before === null ? [] : staleToolNames(before).map((s) => s.text));
173  const added: StaleName[] = [];
174  for (const s of problem.stale) {
175    const left = had.get(s.text) ?? 0;
176    if (left > 0) had.set(s.text, left - 1);
177    else added.push(s);
178  }
179  if (added.length > 0) {
180    reasons.push(
181      `it would name ${staleSummary(added)}. ` +
182        `Use the served names (capsid_find_docs, capsid_work_jobs action post, and so on; tools/list has them all).`
183    );
184  }
185  if (reasons.length === 0) return null;
186  return `${namespace}/${path} is a rule document (src/rule-docs.ts). Nothing was written: ${reasons.join(" Also, ")}`;
187}
188
189/** The daily maintenance pass's rule (src/maintenance.ts): one item per rule document
190 *  over its cap or naming a stale tool, in every namespace, and how many were read.
191 *  ruleDocCap alone decides which documents those are: every path is listed, and only the
192 *  rule documents' bodies are read. A failed read is one rule-docs-not-checked item. */
193export async function gatherRuleDocItems(db: D1Database): Promise<{ items: OpsMaintenanceItem[]; read: number }> {
194  try {
195    const paths = await db.prepare("SELECT namespace, path FROM documents ORDER BY namespace, path").all<{ namespace: string; path: string }>();
196    const rule = (paths.results ?? []).filter((r) => ruleDocCap(r.namespace, r.path) !== null);
197    const items: OpsMaintenanceItem[] = [];
198    // One statement per document, in one batch: never one placeholder per row in a single
199    // query (conventions 8.2).
200    const bodies = rule.length === 0 ? [] : await db.batch(rule.map((r) => db.prepare("SELECT body FROM documents WHERE namespace = ?1 AND path = ?2").bind(r.namespace, r.path)));
201    rule.forEach((r, i) => {
202      const body = ((bodies[i]?.results ?? [])[0] as { body: string | null } | undefined)?.body ?? "";
203      const problem = ruleDocProblem(r.namespace, r.path, body);
204      if (problem) items.push({ rule: "rule-doc", namespace: r.namespace, job: null, line: `${describeRuleDocProblem(problem)}. Cut it or fix the names.` });
205    });
206    return { items, read: rule.length };
207  } catch (err) {
208    const message = err instanceof Error ? err.message : String(err);
209    return { items: [{ rule: "rule-docs-not-checked", namespace: "capsid", job: null, line: `The rule documents could not be read: ${message}` }], read: 0 };
210  }
211}