@sabaiway/agent-workflow-kit 5.4.0 → 5.6.0

package/tools/source-size-report.mjs

@@ -0,0 +1,254 @@
+// source-size-report.mjs — the words a verdict is delivered in. Every refusal this practice prints
+// must name the file, the actual value, the allowed value AND a step the reader can perform against
+// THIS build — never a bare "too big" and never a command that does not exist yet.
+//
+// Two render contracts, honestly separated (D-3a):
+//   • TIGHTEN — the tree shrank below what is recorded. Shrinking is progress, so the regenerator is
+//     printed EXACTLY as it should be pasted; no reason is needed and none is asked for.
+//   • GROWTH — the regeneration would RAISE a recorded value. The checker cannot invent the human's
+//     reason, so the command is printed as a TEMPLATE carrying the placeholder, and the requirement
+//     is stated rather than implied.
+// The exception both share: on a project path that does not survive double-quoting, NO command is
+// rendered (a rendered one could run somewhere else) — the parameters, the reason requirement and
+// the manual lane are stated instead.
+//
+// The standing echo (D-17 U4) rides the same two renders: a PASS states the practice in one line, so
+// the enforced path itself keeps the caps in front of the reader, and every refusal CLOSES with the
+// canonical WHY sentence — a cap whose reason has to be looked up is a cap that reads as arbitrary.
+//
+// Dependency-free, Node >= 22. No writes, no side effects on import.
+
+import { SOURCE_SIZE_WHY, configPathFor, escapeForLine, isLineUnsafe, jsonForLine } from './source-size-refusal.mjs';
+import { INITIAL_ADOPTION_REASON, SOURCE_SIZE_DEFAULTS, SOURCE_SIZE_SCHEMA, practiceFacts } from './source-size-config.mjs';
+import { SOURCE_SIZE_TOOL_PATH, dqUnsafePath } from './source-size-gate-cmd.mjs';
+import { hasGrowth, hasLoweredRecord, isRaise } from './source-size-judge.mjs';
+
+// The project directory is project-controlled too, so the path every refusal names enters its line
+// escaped like any other such value. configPathFor itself stays literal — it also builds the real
+// filesystem path the writer opens.
+const namedConfig = (cwd) => escapeForLine(configPathFor(cwd));
+
+export const GROWTH_REASON_PLACEHOLDER = '<why this size is accepted>';
+
+// The authoring template (D-5): GENERIC, and INERT by construction — its roots/extensions carry
+// placeholders the validator refuses, so it can never be pasted into an empty-green scope.
+export const authoringTemplate = () => JSON.stringify({
+  _README: 'Source-size practice: declared scope + thresholds + the recorded ratchet. Authored keys: schema, defaults, roots, exclude, extensions. Machine keys: baseline, aggregate — each recorded entry carries a reason, and a recorded size is debt, not permission. Strict JSON — unknown keys refused.',
+  schema: SOURCE_SIZE_SCHEMA,
+  defaults: { ...SOURCE_SIZE_DEFAULTS },
+  roots: ['<a directory this practice covers>'],
+  exclude: [],
+  extensions: ['<.an-extension-this-practice-covers>'],
+}, null, 2);
+
+// A rendered command carries the RESOLVED tool path and an explicit quoted --cwd, so it means the
+// same thing from any directory. It is WITHHELD on either of two grounds, and the render says WHICH
+// one fired: a reader told their path "does not survive double-quoting" when it quotes perfectly
+// goes off to fix the wrong thing. The grounds are made DISJOINT by testing line-safety FIRST — a
+// newline satisfies both, and a path that cannot be printed at all is not a quoting question. The
+// recovery lane is identical either way; only the diagnosis differs.
+const WITHHELD_SHELL = 'source-size: no paste-ready command is printed — this project\'s path does not survive double-quoting, so a rendered command could run somewhere other than the project it names.';
+const WITHHELD_LINE = 'source-size: no paste-ready command is printed — this project\'s path carries a character that cannot appear in a rendered line, and escaping it would change the path the shell receives.';
+// The withheld fallback is the reader's ONLY remaining instruction, so it has to be the instruction
+// for what they were actually doing. Sending an adoption to the regenerator would leave them with a
+// record and no gate — half an adoption, handed over as the way out — so the lane is per MODE.
+const WITHHELD_LANE = 'Run the regenerator yourself with the working directory set to this project (source-size-check.mjs --write-baseline, plus --reason "<text>" for any raise), or record each size by hand below.';
+const WITHHELD_ADOPT_LANE = `Run source-size-check.mjs --adopt --reason "${INITIAL_ADOPTION_REASON}" yourself, with the working directory set to this project — it mints the record and declares the gate in one step.`;
+
+// → { command, withheld }: exactly one of the two is non-null. ONE renderer for every mode this tool
+// prints, so a withhold can never apply to some of its own commands and not others.
+const rendered = (cwd, mode, reason) => {
+  const paths = [SOURCE_SIZE_TOOL_PATH, cwd];
+  if (paths.some(isLineUnsafe)) return { command: null, withheld: WITHHELD_LINE };
+  if (paths.some(dqUnsafePath)) return { command: null, withheld: WITHHELD_SHELL };
+  return { command: `node "${SOURCE_SIZE_TOOL_PATH}" ${mode} --cwd "${cwd}"${reason === undefined ? '' : ` --reason "${reason}"`}`, withheld: null };
+};
+const regenerator = (cwd, reason) => rendered(cwd, '--write-baseline', reason);
+
+const SPLIT_QUALITY_FOCUS = 'source-size: REVIEW FOCUS — a recorded size went DOWN or disappeared: check that this is real decomposition and not the same coupling spread across more files (paste this line into the review dispatch focus).';
+
+// Every refusal THIS module renders closes with the canonical WHY. The two thrown classes do not
+// carry it — the exit-1 scope refusals (an unverifiable in-scope source file, a non-UTF-8 path, an
+// unmerged index, an empty declared scope) and the exit-2 config, usage and enumeration errors: both
+// are about a tree the practice could not judge at all, where a sentence about module size explains
+// nothing.
+const WHY_LINE = `source-size: WHY — ${SOURCE_SIZE_WHY}`;
+const refusal = (lines) => [...lines, WHY_LINE];
+
+// The standing summary (D-17 U4) — one line, from the CONFIG alone. There is no headroom to report:
+// the ratchet refuses actual > recorded and actual < recorded alike, so a recorded aggregate is EXACT
+// by construction, and saying that is the honest form of "how much room is left". Reached only on a
+// MINTED config (a check refuses every other state before it renders anything).
+const practiceLine = (config) => {
+  const facts = practiceFacts(config);
+  return `source-size: practice — caps ${facts.maxLines} lines · ${facts.maxLineBytes} bytes per line over ${facts.roots} declared root(s) · ${facts.recordedFiles} file(s) carry a recorded size (debt, not permission) · aggregate ${facts.aggregateLines} line(s), EXACT: growth takes a reasoned bump, never free headroom.`;
+};
+
+export const absentRefusalLines = (cwd) => refusal([
+  `source-size: REFUSED — ${namedConfig(cwd)} is absent, so the scope of this practice is undeclared.`,
+  'Scope is DECLARED, never guessed: the kit ships no default root list and no default file-type list, because a fixed one would silently exempt every unlisted language. Authoring this file is the ONE manual step of the practice.',
+  'Create it with this content, replacing every placeholder value:',
+  authoringTemplate(),
+]);
+
+// Both not-yet-MINTED states route to the same lane — the regenerator writes the machine half — so
+// they differ only in what they say happened: AUTHORED is the state a human creates, INCOMPLETE is a
+// machine half no regenerator produces, which means the file was hand-edited into it.
+export const unmintedRefusalLines = (cwd, { state, missing }) => {
+  const { command, withheld } = regenerator(cwd, INITIAL_ADOPTION_REASON);
+  return refusal([
+    state === 'incomplete'
+      ? `source-size: REFUSED — ${namedConfig(cwd)} is INCOMPLETE: it carries a machine half no regenerator produces (missing ${missing.map((key) => `"${key}"`).join(', ')}), so the ratchet holds only part of this tree.`
+      : `source-size: REFUSED — ${namedConfig(cwd)} is AUTHORED but not yet MINTED (it records no size yet), so there is nothing for the ratchet to hold.`,
+    'Mint it — the regenerator records what this tree already carries; recording a value for the first time is a raise, so it takes a reason:',
+    command === null ? `${withheld} Run source-size-check.mjs --write-baseline --reason "${INITIAL_ADOPTION_REASON}" with the working directory set to this project.` : `  ${command}`,
+  ]);
+};
+
+// Every finding names a path or a root the PROJECT chose, and each one crosses the line-safety
+// boundary ONCE — in lineSafeFinding, before any branch sees it. Nine branches each remembering to
+// escape would be nine chances to forget, and the tenth branch nobody has written yet would start
+// out forgetting; here a branch cannot render an unsafe value even if it tries. The PASTEABLE
+// suggestion goes through the boundary's JSON consumer instead — same set, different serialization,
+// because those are bytes a human copies back into the config.
+const lineSafeFinding = (finding) => ({
+  ...finding,
+  ...(finding.rel === undefined ? {} : { rel: escapeForLine(finding.rel) }),
+  ...(finding.root === undefined ? {} : { root: escapeForLine(finding.root) }),
+});
+
+const FINDING_LINE = Object.freeze({
+  'over-default': (f) => `${f.rel}: ${f.dimension} ${f.actual} exceeds the declared default ${f.allowed}`,
+  grew: (f) => `${f.rel}: ${f.dimension} ${f.actual} exceeds its recorded baseline ${f.recorded} — recorded debt is not permission to grow`,
+  stale: (f) => `${f.rel}: ${f.dimension} ${f.actual} is under the recorded ${f.recorded} — the baseline is STALE, tighten it`,
+  'record-obsolete': (f) => `${f.rel}: ${f.dimension} ${f.actual} no longer exceeds the declared default ${f.allowed} — the record must go`,
+  'entry-gone': (f) => `${f.rel}: recorded in "baseline" but no longer in scope — split, renamed or deleted; the record must go`,
+  'aggregate-grew': (f) => `${f.root}: aggregate lines ${f.actual} exceeds the recorded budget ${f.recorded} — splitting a file buys no aggregate headroom`,
+  'aggregate-stale': (f) => `${f.root}: aggregate lines ${f.actual} is under the recorded budget ${f.recorded} — the budget is STALE, tighten it`,
+  'aggregate-unrecorded': (f) => `${f.root}: declared root carries NO recorded aggregate budget (${f.actual} lines measured) — the record must mirror the declared roots exactly`,
+  'aggregate-root-gone': (f) => `${f.root}: recorded in "aggregate" but no longer a declared root — the record must mirror the declared roots exactly`,
+});
+
+// The suggested entry is the WHOLE projected record, not the dimensions that happen to have changed:
+// an entry printed from the findings alone would drop a recorded dimension that stayed put, and
+// pasting it would fail the very next check. The projection already carries exactly the dimensions
+// that violate the declared defaults and nothing else.
+const suggestedEntryLines = (verdict) => {
+  const rels = [...new Set(verdict.findings.filter((f) => f.kind === 'over-default' || f.kind === 'grew').map((f) => f.rel))];
+  return rels.map((rel) => {
+    const parts = Object.entries(verdict.projected.get(rel)).map(([dimension, value]) => `"${dimension}": ${value}`);
+    return `  ${jsonForLine(rel)}: { ${[...parts, `"reason": "${GROWTH_REASON_PLACEHOLDER}"`].join(', ')} }`;
+  });
+};
+
+const servableStep = (cwd, verdict) => {
+  const growth = hasGrowth(verdict.findings);
+  const entries = suggestedEntryLines(verdict);
+  const { command, withheld } = regenerator(cwd, growth ? GROWTH_REASON_PLACEHOLDER : undefined);
+  const byHand = entries.length === 0 ? [] : ['Or record each size by hand under "baseline" — the validator accepts exactly these bytes:', ...entries];
+  if (command === null) return [withheld, WITHHELD_LANE, ...entries];
+  return [
+    growth
+      ? 'This regeneration RAISES a recorded value, so the reason is REQUIRED — it is recorded in the entry it raises, and it is what the commit message and the CHANGELOG restate:'
+      : 'Nothing here grows — regenerate the record (no reason needed; shrinking is progress):',
+    `  ${command}`,
+    ...byHand,
+  ];
+};
+
+export const checkReportLines = ({ cwd, config, verdict }) => {
+  const lines = verdict.scope.emptyRoots.map(
+    (rel) => `source-size: NOTE — the declared root "${escapeForLine(rel)}" matches no tracked file with a declared extension`);
+  if (verdict.findings.length === 0) {
+    lines.push(`source-size: PASS — ${verdict.scope.files.length} in-scope file(s) within the declared caps`, practiceLine(config));
+    return lines;
+  }
+  lines.push(`source-size: FAIL — ${verdict.findings.length} finding(s) against ${namedConfig(cwd)}:`);
+  for (const finding of verdict.findings) lines.push(`  ${FINDING_LINE[finding.kind](lineSafeFinding(finding))}`);
+  lines.push(...servableStep(cwd, verdict));
+  if (hasLoweredRecord(verdict.findings)) lines.push(SPLIT_QUALITY_FOCUS);
+  return refusal(lines);
+};
+
+// The delta is the DURABLE RECORD on a deployment whose docs/ai is git-hidden: it is what the commit
+// message carries and what the release CHANGELOG restates. It is printed WHOLE — a refusal that
+// showed only the raises would drop the tightens and removals riding the same regeneration from the
+// record it promises, so the raises are MARKED instead of filtered.
+export const deltaLines = (deltas) => deltas.map(
+  ({ target, dimension, from, to }) =>
+    `  ${escapeForLine(target)}: ${dimension} ${from ?? 'none'} → ${to ?? 'none'}${isRaise({ from, to }) ? ' (raise)' : ''}`);
+
+export const reasonRequiredLines = (cwd, deltas) => {
+  const { command, withheld } = regenerator(cwd, GROWTH_REASON_PLACEHOLDER);
+  const raises = deltas.filter(isRaise).length;
+  return refusal([
+    `source-size: REFUSED — this regeneration RAISES ${raises} recorded value(s), and a raise takes a reason (it lands verbatim in the entry it raises, in the commit message and in the CHANGELOG). The whole old→new it would write:`,
+    ...deltaLines(deltas),
+    command === null ? `${withheld} ${WITHHELD_LANE}` : `  ${command}`,
+  ]);
+};
+
+// ── --adopt (D-16) ────────────────────────────────────────────────────────────────────────────────
+// The verb touches TWO files, so it reports the two halves separately, ALWAYS. A failure in the
+// second must never read as a failure of the first: a reader told only "adopt failed" would re-run a
+// mint that already succeeded, or hand-write a record that is already on disk. Every line below
+// therefore names what WAS done before what was not.
+
+// ABSENT config. This says the one thing the check refusal need not: authoring the scope is the
+// EXPECTED first step of adoption, not a failure — the template and the WHY are the same ones the
+// check prints, because a second wording of the same refusal would be a second practice.
+export const adoptAbsentRefusalLines = (cwd) => {
+  const { command, withheld } = rendered(cwd, '--adopt', INITIAL_ADOPTION_REASON);
+  return refusal([
+    `source-size: --adopt REFUSED — ${namedConfig(cwd)} is absent, so this practice has no declared scope yet.`,
+    'Authoring that file is the ONE manual step of the practice, and reaching it here is EXPECTED, not a failure: the kit ships no default root list and no default file-type list, because a fixed one would silently exempt every unlisted language.',
+    'Create it with this content, replacing every placeholder value:',
+    authoringTemplate(),
+    'Then re-run this same verb — it mints the record and declares the gate in one step:',
+    command === null ? `${withheld} ${WITHHELD_ADOPT_LANE}` : `  ${command}`,
+  ]);
+};
+
+// Byte-identity cannot tell a recognition from a regeneration that rewrote the same bytes, and the
+// two differ exactly when the tree has moved — so the run SAYS which one it did.
+export const recordRecognizedLines = (cwd) => [
+  `source-size: the record in ${namedConfig(cwd)} already holds for this tree — recognized, not regenerated (adoption never rewrites a minted record).`,
+];
+
+// The record the tree outgrew. The checker's own refusal has already printed the numbers and the
+// reasoned lane; this line adds the ONE thing that refusal cannot know — that a gate was on its way
+// in and did not land, so nothing was half-armed.
+export const recordNoLongerHoldsLines = (rel) => [
+  `source-size: --adopt STOPPED before declaring — the ${escapeForLine(rel)} gate was NOT declared, because the recorded sizes above no longer hold and the gate would refuse on every run.`,
+  'Settle the record with its own reason first (the command above), then re-run --adopt: the settled record is recognized and only the gate is declared.',
+];
+
+export const gateAlreadyDeclaredLines = (rel) => [
+  `source-size: the ${escapeForLine(rel)} gate is already declared — nothing to declare; --adopt converged.`,
+];
+
+export const gateDeclaredLines = (rel, id) => [
+  `source-size: gate "${escapeForLine(id)}" declared in ${escapeForLine(rel)} — the practice now runs with the matrix.`,
+];
+
+// The PARTIAL outcome, and the reason it is not simply an error: the record IS minted and the tree
+// IS judgeable — only the declaration step was refused, and a re-run converges from here without
+// re-doing the mint.
+export const gateRefusedLines = (rel, message) => refusal([
+  `source-size: --adopt INCOMPLETE — the record was minted, the gate was NOT declared in ${escapeForLine(rel)}.`,
+  `  ${escapeForLine(message)}`,
+  'Fix what the line above names and re-run the same verb: the minted record is recognized, so the re-run only declares the gate.',
+]);
+
+// `changed` is decided by comparing the serialized bytes with the file's own — never by the delta
+// count alone: completing a half-written machine record changes the file while raising nothing, and
+// reporting that as "unchanged" would hide a write that happened.
+export const writtenLines = ({ cwd, deltas, reason, changed }) => {
+  if (!changed) return [`source-size: baseline unchanged — ${namedConfig(cwd)} already records this tree`];
+  if (deltas.length === 0) return [`source-size: baseline rewritten — no recorded value changed; ${namedConfig(cwd)} was completed or re-serialized`];
+  return [
+    `source-size: baseline regenerated — ${deltas.length} change(s) in ${namedConfig(cwd)}:`,
+    ...deltaLines(deltas),
+    ...(reason === undefined ? [] : [`reason: ${reason}`]),
+  ];
+};

package/tools/source-size-scope.mjs

@@ -0,0 +1,145 @@
+// source-size-scope.mjs — which files the practice judges (D-6) and how big each one is (D-7). The
+// two rules ride together because they meet in measureFile: the same strict-UTF-8 decoder decides
+// both whether a PATH can be addressed losslessly and whether a file's BYTES can be judged, and both
+// refuse through the same fail-closed lane.
+//
+//   • SCOPE (fail-closed) — git-tracked files under a declared root carrying a declared extension,
+//     minus the excluded path-segment prefixes. Symlinks and submodule gitlinks are skipped BY KIND.
+//     An unmerged index, a non-UTF-8 in-scope FILENAME, an unverifiable in-scope file and an empty
+//     declared scope are REFUSALS (exit 1); a failed enumeration is exit 2. The enumeration is
+//     NUL-delimited and every path test runs on BYTES, so a tracked path carrying a tab or a newline
+//     is judged byte-exactly instead of being mangled by line splitting.
+//   • COUNTING — lines, and the longest line in BYTES. Terminators never count, CR included.
+//
+// Dependency-free, Node >= 22. No side effects on import; the only child process is a read-only git
+// query, so the read-graph purity suite stays true.
+
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { configFail, configPathFor, scopeFail } from './source-size-refusal.mjs';
+
+const LF = 0x0a;
+const CR = 0x0d;
+const TAB = 0x09;
+const SLASH = 0x2f;
+
+const GIT_MAX_BUFFER = 256 * 1024 * 1024;
+const SYMLINK_MODE = '120000';
+const GITLINK_MODE = '160000';
+
+// Raw bytes in, raw bytes out: `ls-files -s -z` emits mode, object and stage, then a TAB, then the
+// path, then a NUL — and the path half is never decoded before it has been matched, so a name
+// carrying a tab or a newline survives intact (splitting on lines would mangle it).
+const parseIndexEntries = (buf) => {
+  const entries = [];
+  let start = 0;
+  while (start < buf.length) {
+    let end = buf.indexOf(0, start);
+    if (end === -1) end = buf.length;
+    const record = buf.subarray(start, end);
+    const tab = record.indexOf(TAB);
+    if (tab !== -1) {
+      const head = record.subarray(0, tab).toString('utf8').split(' ');
+      entries.push({ mode: head[0], stage: Number(head[2]), path: record.subarray(tab + 1) });
+    }
+    start = end + 1;
+  }
+  return entries;
+};
+
+// A path whose bytes are not valid UTF-8 round-trips to something DIFFERENT (the replacement char is
+// lossy) — that is the whole test, and it is exact.
+const decodeStrict = (buf) => {
+  const text = buf.toString('utf8');
+  return Buffer.from(text, 'utf8').equals(buf) ? text : null;
+};
+
+const bufSegmentPrefix = (path, prefix) =>
+  path.length >= prefix.length &&
+  path.subarray(0, prefix.length).equals(prefix) &&
+  (path.length === prefix.length || path[prefix.length] === SLASH);
+
+const bufEndsWith = (path, suffix) =>
+  path.length >= suffix.length && path.subarray(path.length - suffix.length).equals(suffix);
+
+export const enumerateIndex = (cwd, deps = {}) => {
+  const spawn = deps.spawn ?? spawnSync;
+  const result = spawn('git', ['ls-files', '-s', '-z'], { cwd, maxBuffer: GIT_MAX_BUFFER, windowsHide: true });
+  if (result.error || result.status !== 0) {
+    const why = result.error ? result.error.message : `git exited ${result.status}`;
+    throw configFail(`the git index could not be enumerated in ${cwd} (${why}) — the declared scope is unknown, so nothing is judged`);
+  }
+  return parseIndexEntries(result.stdout);
+};
+
+// resolveScope(cwd, config) → { files: [rel…] sorted, perRoot: Map<root, [rel…]>, emptyRoots: [root…] }.
+// Every exclusion is BY RULE (root / extension / exclude prefix) or BY KIND (symlink, gitlink); an
+// in-scope path that cannot be addressed losslessly is a refusal, never a quiet skip.
+export const resolveScope = (cwd, config, deps = {}) => {
+  const entries = enumerateIndex(cwd, deps);
+  const unmerged = entries.filter((e) => e.stage !== 0);
+  if (unmerged.length > 0) {
+    throw scopeFail(`the git index is UNMERGED (${unmerged.length} conflict-stage entr(ies)) — an ambiguous index cannot be judged; resolve the conflict, then re-run`);
+  }
+  const roots = config.roots.map((rel) => ({ rel, buf: Buffer.from(rel, 'utf8') }));
+  const excludes = config.exclude.map((rel) => Buffer.from(rel, 'utf8'));
+  const extensions = config.extensions.map((ext) => Buffer.from(ext, 'utf8'));
+  const perRoot = new Map(config.roots.map((rel) => [rel, []]));
+  const files = [];
+  for (const entry of entries) {
+    const root = roots.find((r) => bufSegmentPrefix(entry.path, r.buf));
+    if (!root) continue;
+    if (!extensions.some((ext) => bufEndsWith(entry.path, ext))) continue;
+    if (excludes.some((ex) => bufSegmentPrefix(entry.path, ex))) continue;
+    if (entry.mode === SYMLINK_MODE || entry.mode === GITLINK_MODE) continue;
+    const rel = decodeStrict(entry.path);
+    if (rel === null) {
+      throw scopeFail(`an in-scope tracked path's NAME is not valid UTF-8 (bytes ${entry.path.toString('hex')}) — it cannot be addressed losslessly, so nothing is judged; rename it, or add its prefix to "exclude" in ${configPathFor(cwd)}`);
+    }
+    files.push(rel);
+    perRoot.get(root.rel).push(rel);
+  }
+  if (files.length === 0) {
+    throw scopeFail(`the declared scope matches ZERO tracked files (roots: ${config.roots.join(', ')}; extensions: ${config.extensions.join(', ')}) — an empty scope is a misdeclaration, never an empty green; either widen "roots" / "extensions" in ${configPathFor(cwd)}, or track a file the declared scope covers`);
+  }
+  files.sort();
+  for (const list of perRoot.values()) list.sort();
+  return { files, perRoot, emptyRoots: [...perRoot].filter(([, list]) => list.length === 0).map(([rel]) => rel) };
+};
+
+// countBytes(buf) → { lines, maxLineBytes }. A terminator never counts (the CR of a CRLF included);
+// a last line with no final newline still counts; an empty file is 0 lines.
+export const countBytes = (buf) => {
+  let lines = 0;
+  let maxLineBytes = 0;
+  let start = 0;
+  const widen = (from, to) => {
+    lines += 1;
+    if (to - from > maxLineBytes) maxLineBytes = to - from;
+  };
+  for (let i = 0; i < buf.length; i += 1) {
+    if (buf[i] !== LF) continue;
+    widen(start, i > start && buf[i - 1] === CR ? i - 1 : i);
+    start = i + 1;
+  }
+  if (start < buf.length) widen(start, buf.length);
+  return { lines, maxLineBytes };
+};
+
+// measureFile(cwd, rel) → { lines, maxLineBytes }. The judged bytes are the WORKTREE bytes of an
+// index-visible path; an in-scope file the checker cannot verify is exit 1 naming the exclude lane,
+// never a silent or green skip.
+export const measureFile = (cwd, rel, deps = {}) => {
+  const read = deps.readFile ?? readFileSync;
+  let buf;
+  try {
+    buf = read(join(cwd, rel));
+  } catch (err) {
+    throw scopeFail(`${rel}: in-scope but unverifiable (${err.message}) — a file the checker cannot read is never a silent skip; fix it, or add its prefix to "exclude" in ${configPathFor(cwd)}`);
+  }
+  if (decodeStrict(buf) === null) {
+    throw scopeFail(`${rel}: in-scope but not valid UTF-8 — its size cannot be judged; add its prefix to "exclude" in ${configPathFor(cwd)}`);
+  }
+  return countBytes(buf);
+};