simt-dev 0.2.1 → 0.2.2

package/src/measure/context.mjs

@@ -0,0 +1,371 @@
+// What a reader loads at session start, in bytes, counted rather than estimated.
+//
+// Review 0002 S38 measured this by hand - 90,042 B per turn across seven roots,
+// 64,738 B of it a paragraph an earlier root had already loaded - and a number that
+// costs a session to produce is a number nobody re-measures. This module is that
+// measurement as code.
+//
+// What it will not do:
+//
+//   1. Estimate. Tokens are bytes divided by four and are labelled approximate: a
+//      tokenizer is a dependency this package does not have (ADR-012), and an
+//      exact-looking wrong number is worse than a labelled approximation.
+//   2. Charge hand-written bytes to the tool. `generatedBytes` is what the
+//      projection wrote; `readerBytes` is what the reader reads past the marker. A
+//      repository with a 40 KB hand-written prefix has a context problem this tool
+//      does not have, and billing it to the budget would put the number on the
+//      wrong head.
+//   3. Keep a second opinion about any harness. Paths, read limits and pointer
+//      behaviour all come from the surface table, which the writer already has to
+//      agree with; a loader list living here would drift from it.
+//   4. Write anything. `compare` is read-only for the same reason - a measurement
+//      that can change what it measures is not a measurement.
+
+import { readFile, readdir } from 'node:fs/promises';
+import { basename, join } from 'node:path';
+
+import { resolveSurfaces } from '../projection/surfaces.mjs';
+import { parse } from '../projection/markers.mjs';
+import { budgetFinding, DEFAULT_BUDGET_BYTES, readManifest } from '../projection/manifest.mjs';
+import { extractFrontmatter } from '../projection/targets.mjs';
+import { readLimitFindings } from '../projection/project.mjs';
+import { TOOLS } from '../mcp/tools.mjs';
+
+/**
+ * The ceiling review 0002 S38 set for one repository's always-on generated bytes.
+ *
+ * Read as 30,000 rather than 30 * 1024: it is a ceiling, and the conservative reading
+ * of "at most 30 KB" is the one that trips first. Plan 0003 R08 makes the budget a
+ * manifest field, and the manifest's default is the same number - so a repo that
+ * declares nothing is measured against the line the review drew, and a repo that
+ * declares something is measured against its own (ADR-072).
+ */
+export const ALWAYS_ON_BUDGET_BYTES = DEFAULT_BUDGET_BYTES;
+
+/** Bytes per token for the approximation. Labelled approximate wherever it is printed. */
+export const BYTES_PER_TOKEN = 4;
+
+/** Tokens for a byte count. Rounded, and never presented as exact. */
+export function tokens(bytes) {
+  return Math.round(bytes / BYTES_PER_TOKEN);
+}
+
+/**
+ * Bytes of `tools/list` the MCP surface answers with - the same for every repository,
+ * so it is reported beside the roots and never inside a root's total. Counting it per
+ * root would make each repository look over budget for a workspace-level cost.
+ */
+export function mcpTools() {
+  const list = TOOLS.map((t) => ({ name: t.name, description: t.description ?? '' }));
+  return { tools: TOOLS.length, bytes: Buffer.byteLength(JSON.stringify({ tools: list })) };
+}
+
+/**
+ * Paragraphs, as the redundancy figure in review 0002 counted them: blank-line
+ * separated blocks, byte-exact after trimming. A different definition would produce a
+ * different number that could not be compared with the one this replaces.
+ */
+export function paragraphs(text) {
+  return text
+    .split(/\n[ \t]*\n/)
+    .map((block) => block.trim())
+    .filter((block) => block.length > 0);
+}
+
+/** UTF-8 byte length. `text.length` counts UTF-16 units, which undercounts every
+ *  non-ASCII character - and a rule file with an em dash in it is ordinary. */
+function bytes(text) {
+  return Buffer.byteLength(text);
+}
+
+async function readText(path) {
+  try {
+    return await readFile(path, 'utf8');
+  } catch {
+    // ENOENT is the expected answer for a surface a repo selected but has not written
+    // yet, and a permission error is not a byte count either. Both mean "nothing to
+    // measure here", which the caller states as zero rather than as a failure.
+    return null;
+  }
+}
+
+/**
+ * Files under a directory a surface declares, in a stable order.
+ *
+ * Recursive because Claude Code documents recursive discovery for `.claude/rules/`: a
+ * nested rule file loads for that reader, and a meter that did not walk into it would
+ * report a cost the reader does not pay - or hide one it does. The depth cap is not a
+ * guess about nesting; it is the bound that keeps a stray `node_modules` inside a
+ * tool-owned directory from turning a byte count into an unbounded walk.
+ */
+async function filesUnder(root, dir, suffix, depth = 0) {
+  let entries;
+  try {
+    entries = await readdir(join(root, dir), { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const names = entries.map((e) => e.name).sort();
+  const out = [];
+  for (const name of names) {
+    if (name.startsWith('.')) continue;
+    const entry = entries.find((e) => e.name === name);
+    const path = `${dir}/${name}`;
+    if (entry.isDirectory()) {
+      if (depth >= 6) continue;
+      out.push(...(await filesUnder(root, `${path}`, suffix, depth + 1)));
+    } else if (entry.isFile() && (!suffix || name.endsWith(suffix))) {
+      out.push(path);
+    }
+  }
+  return out;
+}
+
+/** Frontmatter keys, as an object. One block, no nesting - which is all a SKILL.md has. */
+function frontmatter(text) {
+  const block = extractFrontmatter(text);
+  const out = {};
+  if (!block) return out;
+  for (const line of block.split('\n').slice(1)) {
+    if (line === '---') break;
+    const at = line.indexOf(':');
+    if (at < 1) continue;
+    out[line.slice(0, at).trim()] = line
+      .slice(at + 1)
+      .trim()
+      .replace(/^["']|["']$/g, '');
+  }
+  return out;
+}
+
+/** Every document a selected surface puts in front of a reader, with what it costs.
+ *
+ *  `channel`   which kind of channel the bytes arrive through
+ *  `file`      the path, relative to the repository root, for the reader to check
+ *  `text`      the bytes a reader loads - the generated span for a region, the whole
+ *              file for a rule file, only the frontmatter for a skill
+ *  `readerBytes` what the reader reads, which for the primary file includes the
+ *              hand-written bytes around the region */
+async function documentsFor(root, surface) {
+  const out = [];
+
+  if (surface.primary) {
+    const text = await readText(join(root, surface.primary));
+    if (text !== null) {
+      const state = parse(text);
+      // A malformed region is reported as a finding with no byte count: the span
+      // between two markers that do not pair is not a region, and attributing the
+      // whole file to the projection would overstate what the tool wrote.
+      // `parse` hands back `before` and `after` as lines re-joined with `\n`, which is
+      // one byte shorter than the text they were cut from: the newline that joined
+      // them to the region belongs to neither. So `text - before - after` bills the
+      // projection for the blank line a person left above its own marker - in the one
+      // command whose entire claim is that it counts exactly. The span is the two
+      // markers and what is between them, and the byte count is that span's.
+      const open = state.before.length === 0 ? 0 : state.before.length + 1;
+      const close = state.after.length === 0 ? text.length : text.length - state.after.length - 1;
+      const span = state.status === 'ok' ? text.slice(open, close) : '';
+      const generated = bytes(span);
+      out.push({
+        channel: 'region',
+        file: surface.primary,
+        text: span,
+        generatedBytes: generated,
+        readerBytes: bytes(text),
+      });
+    }
+  }
+
+  if (surface.rule) {
+    const dir = surface.rule.slice(0, surface.rule.lastIndexOf('/'));
+    const suffix = surface.rule.slice(surface.rule.lastIndexOf('.') + 1);
+    for (const file of await filesUnder(root, dir, `.${suffix}`)) {
+      const text = await readText(join(root, file));
+      if (text === null) continue;
+      out.push({ channel: 'rules', file, text, generatedBytes: bytes(text), readerBytes: bytes(text) });
+    }
+  }
+
+  if (surface.skills) {
+    // `skills` is the directory this tool writes; the documented paths are the
+    // alternatives a reader also accepts. A skill present in two of them loads once,
+    // so the first path in the table keeps the bytes - the same rule a pointer
+    // follows, and for the same reason: one reader, one copy of the text.
+    const dirs = [...new Set([surface.skills, ...(surface.documentedSkillsPaths ?? [])])];
+    const seen = new Set();
+    for (const dir of dirs) {
+      for (const file of await filesUnder(root, dir, '.md')) {
+        if (!basename(file).startsWith('SKILL')) continue;
+        const text = await readText(join(root, file));
+        if (text === null) continue;
+        const meta = frontmatter(text);
+        const name = meta.name ?? basename(file);
+        const description = meta.description ?? '';
+        if (seen.has(name)) continue;
+        seen.add(name);
+        // Name and description only: that is what the Agent Skills spec has a reader
+        // load before it decides to open the body, so that is what costs a turn.
+        const head = description ? `${name}\n${description}` : name;
+        out.push({
+          channel: 'skills',
+          file,
+          text: head,
+          generatedBytes: bytes(head),
+          readerBytes: bytes(head),
+        });
+      }
+    }
+  }
+
+  return out;
+}
+
+/** One repository: what its readers load, and what of it this tool wrote. */
+export async function measureRoot(root) {
+  const { manifest, exists, error } = await readManifest(root);
+  const resolved = resolveSurfaces(manifest, {});
+  const documents = [];
+  for (const surface of resolved.surfaces) {
+    documents.push(...(await documentsFor(root, surface)));
+  }
+
+  const generatedBytes = documents.reduce((sum, d) => sum + d.generatedBytes, 0);
+  const readerBytes = documents.reduce((sum, d) => sum + d.readerBytes, 0);
+  const budgetBytes =
+    manifest?.budget?.bytes !== undefined && Number.isFinite(manifest.budget.bytes)
+      ? manifest.budget.bytes
+      : ALWAYS_ON_BUDGET_BYTES;
+
+  const byChannel = new Map();
+  for (const doc of documents) {
+    const row = byChannel.get(doc.channel) ?? { channel: doc.channel, files: 0, generatedBytes: 0, readerBytes: 0 };
+    row.files += 1;
+    row.generatedBytes += doc.generatedBytes;
+    row.readerBytes += doc.readerBytes;
+    byChannel.set(doc.channel, row);
+  }
+
+  const findings = [];
+  const readLimits = [];
+  if (manifest?.error) findings.push(`manifest: ${manifest.error}`);
+  const regionDoc = documents.find((d) => d.channel === 'region');
+  if (regionDoc) {
+    const text = await readText(join(root, regionDoc.file));
+    const state = parse(text ?? '');
+    if (state.status === 'malformed') findings.push(`${regionDoc.file}: generated region is malformed`);
+    // The gate's own finding, for the same reason `check` uses it: one answer to
+    // "does this reader reach the end of the region", so a meter that disagreed with
+    // the gate would be a second bug to find.
+    for (const finding of readLimitFindings(text ?? '', regionDoc.file)) {
+      findings.push(finding.detail);
+      readLimits.push({
+        file: finding.file,
+        reader: finding.reader,
+        limit: finding.limitBytes,
+        endByte: finding.endByte,
+        overBy: finding.overBy,
+      });
+    }
+  }
+
+  const name = root.split('/').filter(Boolean).pop() ?? root;
+  return {
+    name,
+    path: root,
+    adoption: !exists ? 'unmanaged' : error ? 'broken' : 'adopted',
+    surfaces: resolved.ids,
+    surfaceProblems: resolved.problems,
+    generatedBytes,
+    readerBytes,
+    // `readerBytes` is what a reader pays for this repository's file; `tokens` is an
+    // approximation of it and is reported as such wherever it is printed.
+    tokens: tokens(readerBytes),
+    generatedTokens: tokens(generatedBytes),
+    // The repository's own number, not the constant. The constant is the default a repo
+    // gets if it never declares one, which is the same line the review drew — but a repo
+    // that measures its rules differently has said so, and a measurement that overrode
+    // that would be reporting a violation of a line the repository never agreed to
+    // (ADR-072).
+    budget: {
+      bytes: budgetBytes,
+      declared: manifest?.budget?.bytes !== undefined,
+      over: generatedBytes > budgetBytes,
+      overBy: Math.max(0, generatedBytes - budgetBytes),
+      // The finding the gate would raise, produced by the same function, so the report
+      // and the gate cannot word the same fact two ways. It is carried rather than
+      // raised: R08 calls the cut non-blocking, and this command never fails on a
+      // measurement (ADR-064).
+      finding: budgetFinding(generatedBytes, manifest?.budget, manifest?.mode),
+    },
+    channels: [...byChannel.values()],
+    readLimits,
+    findings,
+    documents,
+  };
+}
+
+/**
+ * Fill in the redundancy numbers for a set of roots, in the order given.
+ *
+ * Three questions, one walk: bytes that repeat a paragraph an earlier ROOT loaded
+ * (`duplicateBytes` - the figure review 0002 quoted), bytes that repeat a paragraph
+ * an earlier DOCUMENT in the same root loaded (`repeatBytes` - what a per-rule file
+ * repeating the region costs), and the bytes neither does (`uniqueBytes`).
+ *
+ * Order decides ownership, so it is the caller's: `discover` returns repositories
+ * sorted by path, and the first root to carry a paragraph keeps it. Two runs over the
+ * same workspace therefore produce the same two numbers, which is the only reason the
+ * first of them is worth keeping.
+ */
+export function annotate(rows) {
+  const seenAcrossRoots = new Set();
+  for (const row of rows) {
+    const seenInRoot = new Set();
+    let uniqueBytes = 0;
+    let duplicateBytes = 0;
+    let repeatBytes = 0;
+    for (const doc of row.documents) {
+      for (const block of paragraphs(doc.text)) {
+        const size = bytes(block);
+        if (seenInRoot.has(block)) {
+          repeatBytes += size;
+          continue;
+        }
+        seenInRoot.add(block);
+        if (seenAcrossRoots.has(block)) {
+          duplicateBytes += size;
+          continue;
+        }
+        seenAcrossRoots.add(block);
+        uniqueBytes += size;
+      }
+    }
+    row.redundancy = {
+      blockBytes: uniqueBytes + duplicateBytes + repeatBytes,
+      uniqueBytes,
+      duplicateBytes,
+      repeatBytes,
+    };
+  }
+  return rows;
+}
+
+/** The workspace totals. `generatedBytes` is the denominator the review used, so the
+ *  percentage beside it means what the 72% meant. */
+export function totals(rows) {
+  const sum = (pick) => rows.reduce((n, r) => n + pick(r), 0);
+  const generatedBytes = sum((r) => r.generatedBytes);
+  const duplicateBytes = sum((r) => r.redundancy?.duplicateBytes ?? 0);
+  const repeatBytes = sum((r) => r.redundancy?.repeatBytes ?? 0);
+  return {
+    roots: rows.length,
+    generatedBytes,
+    readerBytes: sum((r) => r.readerBytes),
+    tokens: sum((r) => r.generatedTokens),
+    blockBytes: sum((r) => r.redundancy?.blockBytes ?? 0),
+    uniqueBytes: sum((r) => r.redundancy?.uniqueBytes ?? 0),
+    duplicateBytes,
+    repeatBytes,
+    overBudget: rows.filter((r) => r.budget.over).map((r) => r.name),
+  };
+}