simt-dev 0.2.1 → 0.3.0

package/src/kernel/inferability.mjs

@@ -0,0 +1,188 @@
+// The inferability filter: a rule line the repository already proves does not ship
+// (plan 0003 R09).
+//
+// The costliest byte in a projection is the one the reader already knows. A Go repository
+// with one runner does not need to be told to use it; a repository whose manifest declares
+// a format gate does not need to be told how it indents. The evidence is committed — the
+// marker files, the declared gates, the command card — so the same repository filters the
+// same way on every machine (plan 0003 P4, R13).
+//
+// Nothing is dropped by guesswork. A rule author marks the line with
+// `<!-- simt-inferable-when: <expression> -->`, naming the evidence that makes it
+// redundant, and the line leaves only when the repository proves every term. A line nobody
+// marked is a line nobody claimed was inferable, and stays.
+//
+// The unit dropped is the blank-line-delimited block, so a wrapped bullet is marked once
+// and leaves whole rather than leaving half a sentence behind. The marker is stripped from
+// the region either way: `simt-` vocabulary is for the rule's author, not its reader.
+
+import { gateNames } from '../hooks/gates.mjs';
+import { KNOWN_TAGS } from '../resolve/fingerprint.mjs';
+
+import { CARD_VERBS } from './card.mjs';
+
+/**
+ * The marker a rule line carries. Named here rather than at its use, because the defect
+ * message has to spell the thing the author must type.
+ */
+export const INFERABLE_MARKER = 'simt-inferable-when';
+
+const MARKER = /<!--\s*simt-inferable-when:\s*([^>]*?)\s*-->/g;
+
+/**
+ * Marks the trailing position of a marker on a line, so the text a reader keeps is the
+ * line without the comment and not the line with a hole in it.
+ */
+const MARKER_AT = /\s*<!--\s*simt-inferable-when:\s*[^>]*?-->/g;
+
+/** A non-global probe, because a global regex carries `lastIndex` between calls. */
+const HAS_MARKER = /<!--\s*simt-inferable-when:/;
+
+/**
+ * Split a body into the units a marker drops. Blank lines separate blocks, except inside a
+ * fenced code block, where a blank line is part of the sample and splitting there would
+ * cut a fence in half.
+ */
+function blocks(text) {
+  const out = [];
+  let current = [];
+  let fenced = false;
+  for (const line of String(text ?? '').split('\n')) {
+    if (/^\s*(```|~~~)/.test(line)) {
+      if (current.length > 0 || fenced) current.push(line);
+      fenced = !fenced;
+      continue;
+    }
+    if (!fenced && line.trim() === '') {
+      if (current.length > 0) out.push(current.join('\n'));
+      current = [];
+      continue;
+    }
+    current.push(line);
+  }
+  if (current.length > 0) out.push(current.join('\n'));
+  return out;
+}
+
+/** Every marker in one block, as `{line, expr}`. More than one is a defect. */
+function markers(block) {
+  const found = [];
+  for (const line of block.split('\n')) {
+    for (const match of line.matchAll(MARKER)) found.push({ line, expr: match[1] });
+  }
+  return found;
+}
+
+/**
+ * An expression is a conjunction of terms: `term + term`, and nothing else. There is no
+ * negation, because every reason a line is redundant is a positive proof the repository
+ * offers, and a grammar for a case nobody has is a grammar nobody can be taught.
+ */
+export function parseInferable(expression) {
+  return String(expression ?? '')
+    .split('+')
+    .map((term) => term.trim())
+    .filter((term) => term !== '');
+}
+
+/**
+ * Whether a term is evidence this tool can check: a fact or stack tag the repository
+ * proves by its files, a verb its command card names, or a gate it declares. Anything else
+ * is a typo the author has to see, not a term that happens to be unproven — a marker
+ * naming evidence the tool never gathered would drop the line on a claim nothing verified.
+ */
+function knownTerm(term) {
+  if (term.startsWith('card:')) return CARD_VERBS.includes(term.slice('card:'.length));
+  if (term.startsWith('gate:')) return gateNames().includes(term.slice('gate:'.length));
+  return KNOWN_TAGS.has(term);
+}
+
+/**
+ * The defect in a body's markers, or null. Reported through the same field as a
+ * frontmatter defect, so `check` and `rules list` need no second path to a broken rule.
+ */
+export function inferableDefect(body) {
+  for (const block of blocks(body)) {
+    const found = markers(block);
+    if (found.length === 0) continue;
+    if (found.length > 1) {
+      return `carries more than one ${INFERABLE_MARKER} marker; a block is dropped whole, so one marker is one claim`;
+    }
+    const terms = parseInferable(found[0].expr);
+    if (terms.length === 0) {
+      return `${INFERABLE_MARKER} names no evidence, so nothing can decide whether the line is redundant`;
+    }
+    for (const term of terms) {
+      if (!knownTerm(term)) {
+        return `${INFERABLE_MARKER} names "${term}", which is not evidence this repository can prove; use a marker-file fact, card:${CARD_VERBS.join('|card:')} or gate:<name>`;
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * The evidence a projection may treat as already known. Built from committed bytes only —
+ * never PATH or `node_modules` — because a proof read off the machine would make the
+ * region differ between a laptop and CI for no reason a diff could explain.
+ */
+export function inferableProofs({ facts = [], stack = [], card = null, manifest = null } = {}) {
+  const proofs = new Set([...facts, ...stack]);
+  for (const line of card?.lines ?? []) {
+    if (line.verb) proofs.add(`card:${line.verb}`);
+  }
+  const gates = manifest?.gates ?? {};
+  for (const name of [...(gates.preCommit ?? []), ...(gates.prePush ?? [])]) {
+    proofs.add(`gate:${name}`);
+  }
+  return proofs;
+}
+
+/** The line a reader would have read, collapsed and clipped for a one-line note. */
+function excerpt(text) {
+  const one = text.replace(/\s+/g, ' ').trim();
+  return one.length > 80 ? `${one.slice(0, 79)}…` : one;
+}
+
+/** The block without its markers, and without the line a marker stood on alone. */
+function stripMarkers(block) {
+  const kept = [];
+  for (const line of block.split('\n')) {
+    const stripped = line.replace(MARKER_AT, '').replace(/\s+$/, '');
+    if (stripped === '' && HAS_MARKER.test(line)) continue;
+    kept.push(stripped);
+  }
+  return kept.join('\n');
+}
+
+/**
+ * Drop every marked block whose expression the repository proves, and strip the markers
+ * from the rest.
+ *
+ * `changed` is false when the body carries no marker, and then `body` is the input by
+ * identity: a projection of a rule nobody marked must not move a byte, or every
+ * repository in the estate would diff on a change none of them made.
+ *
+ * @returns {{body: string, removed: {text: string, expr: string}[], changed: boolean}}
+ */
+export function filterInferable(body, proofs) {
+  const parts = blocks(body);
+  if (!parts.some((block) => markers(block).length > 0)) {
+    return { body, removed: [], changed: false };
+  }
+  const kept = [];
+  const removed = [];
+  for (const block of parts) {
+    const found = markers(block);
+    if (found.length > 0) {
+      const terms = parseInferable(found[0].expr);
+      if (terms.length > 0 && terms.every((term) => proofs.has(term))) {
+        removed.push({ text: excerpt(stripMarkers(block)), expr: found[0].expr.trim() });
+        continue;
+      }
+    }
+    const clean = stripMarkers(block).replace(/\s+$/, '');
+    if (clean.trim() !== '') kept.push(clean);
+  }
+  return { body: kept.join('\n\n'), removed, changed: true };
+}

package/src/mcp/resources.mjs

@@ -0,0 +1,157 @@
+// Rules and decisions as MCP resources.
+//
+// The tools answer questions and the answers are arguments to the next call. These two
+// answer a different request: "what is the rule you would apply, in full". A client that
+// reads them can hold the text rather than reconstructing it from a tool's summary, and
+// a reader outside this estate gets the same bytes an adopting repository's agent reads -
+// redacted, because a decision record cites its own rulings and not this repository's
+// layout (ADR-055, ADR-061).
+//
+// Both revisions agree on the shape here. They disagree about what a missing resource
+// returns, and that difference is handled in the server, not here: this module answers
+// with a resource or with nothing at all, and never with an empty `contents` array,
+// which the newest revision forbids because it is indistinguishable from an empty rule.
+
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import { DECISIONS_DIR, loadDecisions, redactEstate, redactInternalPaths } from '../decisions/index.mjs';
+import { CLI } from '../name.mjs';
+import { loadMdcRules } from '../projection/mdc.mjs';
+import { loadRules } from '../projection/rules.mjs';
+
+const RULES_SCHEME = 'simt://rules/';
+const DECISIONS_SCHEME = 'simt://decisions/';
+
+/**
+ * RFC 6570 templates, so a client can discover the shape without a hard-coded string.
+ *
+ * `id` and `adr` are the handles a reader already has: a gate names a rule id and a
+ * finding names an ADR, so the template's variable names match what those print.
+ */
+export const RESOURCE_TEMPLATES = [
+  {
+    uriTemplate: `${RULES_SCHEME}{id}`,
+    name: 'rules',
+    title: 'Projected rules',
+    description: 'One rule as this tool projects it: its frontmatter, its body and its decision citations.',
+    mimeType: 'text/markdown',
+  },
+  {
+    uriTemplate: `${DECISIONS_SCHEME}{adr}`,
+    name: 'decisions',
+    title: 'Decision records',
+    description: 'One decision record, including the rulings and the reasons they were given.',
+    mimeType: 'text/markdown',
+  },
+];
+
+/**
+ * Split a resource URI into its collection and its handle.
+ *
+ * String handling rather than `new URL`, because a custom scheme is parsed by the WHATWG
+ * URL machinery according to rules written for http, and the one thing this has to get
+ * right is which character separates `simt://rules` from the id. A handle that carries a
+ * slash or a dot segment is refused rather than resolved: a resource URI is not a file
+ * path, and the specification requires a server to reject one that tries to be.
+ */
+function parseResourceUri(uri) {
+  if (typeof uri !== 'string') return null;
+  const [collection, ...rest] = uri.split('://');
+  if (collection !== 'simt') return null;
+  const [name, ...handle] = rest.join('://').split('/');
+  const id = handle.join('/');
+  if (!id || id === '.' || id === '..' || id.includes('..')) return null;
+  if (name === 'rules' && id.includes('/')) return null;
+  if (name !== 'rules' && name !== 'decisions') return null;
+  return { collection: name, id };
+}
+
+function resource(collection, id, title, bytes) {
+  return {
+    uri: `simt://${collection}/${id}`,
+    name: id,
+    title,
+    description: `${title}, as this tool projects it`,
+    mimeType: 'text/markdown',
+    size: bytes,
+  };
+}
+
+/**
+ * Every rule and every decision record, one entry each.
+ *
+ * The list is built from what is on disk rather than from a hand-kept index, so it cannot
+ * describe a rule that was renamed or a record that was never written. Order is sorted:
+ * the newest revision forbids a set that varies per connection or as a side effect of
+ * another request, and a list built from a directory read is the only shape that satisfies
+ * that without a cache to invalidate.
+ */
+export async function listResources() {
+  const [rules, mdc, { decisions }] = await Promise.all([loadRules(null), loadMdcRules(), loadDecisions({ all: true })]);
+  // `size` is the bytes on disk rather than the bytes served: `read` redacts a decision
+  // before sending it, so the served length is not knowable without reading the file, and
+  // a size that disagrees with the payload is worse than a size that rounds.
+  return [
+    ...[...rules, ...mdc]
+      .filter((rule) => rule.id !== null)
+      .map((rule) => resource('rules', rule.id, rule.title ?? rule.id, rule.bytes)),
+    ...decisions.map((decision) => resource('decisions', decision.id, decision.title ?? decision.id, decision.bytes)),
+  ].sort((a, b) => a.uri.localeCompare(b.uri));
+}
+
+/**
+ * One resource, or null when there is no such id.
+ *
+ * `null` is not a failure the caller swallows: the specification makes a missing resource
+ * a protocol error with a code that CHANGED between revisions, so the server decides the
+ * code and this module only declines to invent content.
+ */
+export async function readResource(uri) {
+  const parsed = parseResourceUri(uri);
+  if (parsed === null) return null;
+
+  if (parsed.collection === 'rules') {
+    const [rules, mdc] = await Promise.all([loadRules(null), loadMdcRules()]);
+    const rule = [...rules, ...mdc].find((candidate) => candidate.id === parsed.id);
+    if (rule === undefined) return null;
+    const text = `${frontmatterOf(rule)}\n${rule.body ?? ''}`.trim();
+    return {
+      uri,
+      mimeType: 'text/markdown',
+      text,
+      // The body a tool returns is redacted for the same reason: a reader outside this
+      // estate is told what the rule says and not which directory here it is filed in.
+      bytes: Buffer.byteLength(text),
+    };
+  }
+
+  // `loadDecisions` reads the index, not the records: it reports status, currency and
+  // byte count, and keeps no body. Reading the file the index named is one read of a
+  // record the reader has already asked for by id.
+  const { decisions } = await loadDecisions({ all: true });
+  const decision = decisions.find((candidate) => candidate.id === parsed.id);
+  if (decision === undefined) return null;
+  const raw = await readFile(join(DECISIONS_DIR, decision.file), 'utf8');
+  const text = redactInternalPaths(redactEstate(raw)).trim();
+  return { uri, mimeType: 'text/markdown', text, bytes: Buffer.byteLength(text) };
+}
+
+function frontmatterOf(rule) {
+  const keys = ['id', 'title', 'applies', 'priority'];
+  const present = keys.filter((key) => rule[key] !== undefined && rule[key] !== null);
+  if (present.length === 0) return '';
+  return ['---', ...present.map((key) => `${key}: ${formatValue(rule[key])}`), '---'].join('\n');
+}
+
+function formatValue(value) {
+  return Array.isArray(value) ? `[${value.join(', ')}]` : String(value);
+}
+
+/**
+ * The remedy a client gets when it asks for something that is not here.
+ *
+ * A command, not a path, for the reason every remedy in this package is a command: the
+ * reader runs this tool, not this checkout.
+ */
+const MISSING_REMEDY = `run: ${CLI} rules list, or ${CLI} graph lint to see what this copy can read`;

package/src/mcp/schema.mjs

@@ -0,0 +1,139 @@
+// A JSON Schema checker, for the subset these schemas use.
+//
+// Written here rather than taken from npm because a tool that validates a payload has
+// to keep working on a machine where nothing was installed (ADR-012), and because the
+// schemas it checks are in this file: a dependency would be a second place for the same
+// rules to live, and the one thing a validator must not be is quietly out of date.
+//
+// The subset is deliberately small and deliberately loud. A keyword this file does not
+// understand is reported as an error rather than skipped, because a keyword silently
+// ignored turns a schema into decoration - the check passes, the payload does not match,
+// and nobody can say which of the two was wrong. `assertValid` is the only entry point
+// the tests use, and it names the failing path.
+//
+// Supported: type (including union arrays), properties, required, items, enum,
+// additionalProperties (boolean or a schema), anyOf.
+
+/**
+ * Check a value against a schema.
+ *
+ * @param {unknown} value
+ * @param {object} schema
+ * @param {string} [path] JSON pointer-ish location, for the message
+ * @returns {string|null} the first failure, or null when it validates
+ */
+export function check(value, schema, path = '$') {
+  if (schema === true || schema === undefined) return null;
+  if (schema === false) return `${path}: no value is allowed here`;
+  if (typeof schema !== 'object' || schema === null) return `${path}: schema must be an object`;
+
+  for (const keyword of Object.keys(schema)) {
+    if (!SUPPORTED.has(keyword)) {
+      // Loud on purpose: see the header. A keyword nobody implements is a promise the
+      // schema does not keep, and this is the only place that can notice.
+      throw new Error(`schema at ${path} uses "${keyword}", which this checker does not implement`);
+    }
+  }
+
+  if (schema.type !== undefined && !typeMatches(value, schema.type)) {
+    return `${path}: expected ${describe(schema.type)}, got ${describeValue(value)}`;
+  }
+  if (Array.isArray(schema.enum) && !schema.enum.some((allowed) => same(allowed, value))) {
+    return `${path}: ${JSON.stringify(value)} is not one of ${JSON.stringify(schema.enum)}`;
+  }
+  if (Array.isArray(schema.anyOf)) {
+    const matched = schema.anyOf.some((option) => check(value, option, path) === null);
+    if (!matched) return `${path}: matched none of the ${schema.anyOf.length} allowed shapes`;
+  }
+
+  if (schema.type === 'object' || schema.properties !== undefined || schema.required !== undefined) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) return null;
+    for (const key of schema.required ?? []) {
+      if (!(key in value)) return `${path}: missing required property "${key}"`;
+    }
+    for (const [key, sub] of Object.entries(schema.properties ?? {})) {
+      if (!(key in value)) continue;
+      const failure = check(value[key], sub, `${path}.${key}`);
+      if (failure !== null) return failure;
+    }
+    if (schema.additionalProperties !== undefined) {
+      const known = new Set(Object.keys(schema.properties ?? {}));
+      for (const [key, sub] of Object.entries(value)) {
+        if (known.has(key)) continue;
+        if (schema.additionalProperties === false) return `${path}: unexpected property "${key}"`;
+        if (schema.additionalProperties !== true) {
+          const failure = check(sub, schema.additionalProperties, `${path}.${key}`);
+          if (failure !== null) return failure;
+        }
+      }
+    }
+  }
+
+  if (schema.items !== undefined && Array.isArray(value)) {
+    for (const [index, item] of value.entries()) {
+      const failure = check(item, schema.items, `${path}[${index}]`);
+      if (failure !== null) return failure;
+    }
+  }
+  return null;
+}
+
+/** Throws with the first failure, named. The shape a test wants. */
+export function assertValid(value, schema, what = 'value') {
+  const failure = check(value, schema);
+  if (failure !== null) throw new Error(`${what} does not match its schema: ${failure}`);
+  return true;
+}
+
+const SUPPORTED = new Set([
+  'type',
+  'properties',
+  'required',
+  'items',
+  'enum',
+  'additionalProperties',
+  'anyOf',
+  'description',
+  '$schema',
+]);
+
+function typeMatches(value, type) {
+  const types = Array.isArray(type) ? type : [type];
+  return types.some((t) => singleTypeMatches(value, t));
+}
+
+function singleTypeMatches(value, type) {
+  switch (type) {
+    case 'object':
+      return value !== null && typeof value === 'object' && !Array.isArray(value);
+    case 'array':
+      return Array.isArray(value);
+    case 'string':
+      return typeof value === 'string';
+    case 'number':
+      return typeof value === 'number' && Number.isFinite(value);
+    case 'integer':
+      return Number.isInteger(value);
+    case 'boolean':
+      return typeof value === 'boolean';
+    case 'null':
+      return value === null;
+    default:
+      return false;
+  }
+}
+
+function describe(type) {
+  return Array.isArray(type) ? type.join('|') : type;
+}
+
+/** What a value IS, for the failure message. Distinct from `describe(type)`. */
+function describeValue(value) {
+  if (value === null) return 'null';
+  if (Array.isArray(value)) return 'array';
+  return typeof value;
+}
+
+function same(a, b) {
+  return JSON.stringify(a) === JSON.stringify(b);
+}