@avi2dg/checks 0.65.3 → 0.66.0

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 Every release of `@avi2dg/checks`, newest first, written by the release from its conventional commits.
 
+## 0.66.0
+
+Released 2026-11-05.
+
+### Features
+
+- **docs:** cap READMEs at 6,000 characters and table cells at 300 [#46](https://github.com/avi2d/checks/pull/46)
+
 ## 0.65.3
 
 Released 2026-11-04.

package/docs/gates/checks-docs.md

@@ -16,6 +16,7 @@ It fails when such a line copies a version `package.json` or `.bun-version` pins
 It fails when a living doc or an agent file names a path, link or command that does not resolve, and the range added or broke it.
 It fails when an agent file holds more than 3,000 characters or a `## Maintaining this file` section, whatever the range touches, as [Agent files](#agent-files) says.
 It fails when an entry in an agent file names no tracked path, link or `bun run` command, whatever the range touches.
+It fails when a range edits a README that is over 6,000 characters or holds a table cell over 300, as [README ceilings](#readme-ceilings) says.
 It fails when a living doc or an agent file names a code span the range removed from every file outside the docs, on any line.
 [Paths, links and commands](#paths-links-and-commands) says how each reference resolves.
 The package ships one template per kind under `dist/templates/`, and a repository starts a new doc file by copying one:
@@ -188,6 +189,23 @@ An entry is any list item a reader sees as CommonMark renders the file, the item
 A list item inside an HTML comment, an HTML block or an indented code block is not an entry.
 A fresh file passes the ceiling, and its entries pass once each names the file that holds its detail.
 
+## README ceilings
+
+The root `README.md` and every `README.md` beside a `package.json` take two ceilings, since npm shows a package's README as its front page:
+
+- The file holds at most 6,000 characters, counted as the agent file ceiling counts them.
+  The failure names the file's size and its largest section, and says to move that section to a page under `docs/`.
+- A table cell holds at most 300 characters.
+  A table follows the GitHub table rules, with a header row above a delimiter row with the same cell count.
+  Every line after the delimiter counts until a blank line.
+  Tables indented by four spaces or a tab, and tables inside blockquotes, are left unchecked.
+  Lines in fenced or indented code never count as table rows.
+  An escaped `\|` never ends a cell.
+
+No line in a complete same-named generated block counts toward either ceiling, from its `<!-- generated <name>: ... -->` line to its `<!-- end generated <name> -->` line, so a generated index sizes itself.
+A README fails only in a range that edits it.
+A README the range leaves alone is listed as advisory, so the first change that edits an oversize README shrinks it.
+
 ## What it reads
 
 It reads each Markdown file at the head commit, and uses its path or front matter to choose its kind.
@@ -198,6 +216,7 @@ It compares each code span a living doc or an agent file names with the text git
 It reads the repository's own name and its direct dependencies from the root `package.json` at the head commit.
 It reads the versions the root `package.json` and `.bun-version` pin at the head commit.
 It reads each agent file at the head commit for the ceiling, its sections and its entries, whatever the range touches.
+It reads the root `README.md` and each `README.md` beside a tracked `package.json` at the head commit for the README ceilings.
 A name that an installed direct dependency still holds counts as present.
 From the working tree it reads the ignore files git reads, `node_modules/.bin`, and the directory of each direct dependency under `node_modules`.
 
@@ -215,8 +234,8 @@ With one it is that commit against its parent, or against the empty tree for a r
 
 | Code | When |
 | --- | --- |
-| 0 | every doc file the range touches holds to its template, every line it adds to a living doc or an agent file holds to the prose rules and copies no pinned version, it adds or breaks no reference that does not resolve, every agent file holds to the ceiling and holds no `## Maintaining this file`, every entry in an agent file names a tracked path, a link or a command, and no code span a living doc or an agent file names vanished from every file outside the docs |
-| 1 | a doc file the range touches does not hold to its template, a line the range adds to a living doc or an agent file breaks a prose rule or copies a pinned version, the range adds or breaks a reference that does not resolve, an agent file is over the ceiling or holds `## Maintaining this file`, an entry in an agent file names no tracked path, link or command, or the range removes a name a living doc or an agent file still carries |
+| 0 | every doc file the range touches holds to its template, every line it adds to a living doc or an agent file holds to the prose rules and copies no pinned version, it adds or breaks no reference that does not resolve, every agent file holds to the ceiling and holds no `## Maintaining this file`, every entry in an agent file names a tracked path, a link or a command, every README the range edits holds to the README ceilings, and no code span a living doc or an agent file names vanished from every file outside the docs |
+| 1 | a doc file the range touches does not hold to its template, a line the range adds to a living doc or an agent file breaks a prose rule or copies a pinned version, the range adds or breaks a reference that does not resolve, an agent file is over the ceiling or holds `## Maintaining this file`, an entry in an agent file names no tracked path, link or command, a README the range edits is over a README ceiling, or the range removes a name a living doc or an agent file still carries |
 | 2 | a `package.json` does not decode, a ref does not resolve, or `grep` cannot read an installed direct dependency |
 
 ## Sample output
@@ -232,6 +251,8 @@ docs: 7 violation(s):
   docs/parts.md:9: names `gates.lint`, which the range removed from every file outside the docs. Say what holds now, or drop the line
 docs: advisory, 1 doc file(s) the range leaves alone do not hold to their templates yet:
   docs/adr/0001-quality-gates.md: 5 violation(s)
+docs: advisory, 1 README ceiling finding(s) in README(s) the range leaves alone:
+  packages/run/README.md: is 6412 characters, over the 6,000-character ceiling for a README. Its largest section is `## Configure a run` at 2310 characters. Move that section to a page under docs/ and link it from the README in one line
 docs: advisory, 1 sentence(s) over the trial length caps:
   README.md:16: carries a 27-word descriptive sentence, over the 25-word cap (procedural means an ordered list item, capped at 20 words)
 docs: advisory, 1 path(s), link(s) or command(s) the living docs or agent files name were broken before the range:
@@ -243,6 +264,7 @@ docs: advisory, 1 path(s), link(s) or command(s) the living docs or agent files
 `checks-lint` runs it over each pull request's range in every repository, as [checks-lint](checks-lint.md) says.
 A repository adopts the templates as its files change, and the prose rules as its lines change, because an untouched file or line never fails those checks.
 It reshapes its agent files when it adopts the gate, because [Agent files](#agent-files) judges each one whatever the range touches.
+It shrinks an oversize README in the first change that edits it, because [README ceilings](#readme-ceilings) judges only a README the range edits.
 A name the range removes fails wherever a doc still carries it, because the removal is what turned the line stale.
 
 ## Related topics

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avi2dg/checks",
-  "version": "0.65.3",
+  "version": "0.66.0",
   "description": "Deterministic checks shared across a set of TypeScript repositories",
   "author": {
     "name": "avi2d",

package/src/docs/doc-agents.ts

@@ -1,8 +1,18 @@
 import { Parser, type NodeType } from "commonmark";
 import { commandNames, type Snapshot } from "./doc-references.ts";
+import { handWritten } from "./doc-versions.ts";
 import { AGENT_NAMES, scanMarkdown, type MarkdownLine } from "./prose-matchers.ts";
 
 export const AGENT_CEILING = 3000;
+export const README_CEILING = 6000;
+export const CELL_CEILING = 300;
+
+const README = "README.md";
+const MANIFEST = "package.json";
+const SECOND_LEVEL = /^\s{0,3}##(?:\s+|$)(.*?)(?:\s+#+)?\s*$/;
+const SETEXT_SECOND = /^\s{0,3}-+\s*$/;
+const CELL_SEPARATOR = /(?<!\\)\|/;
+const ROW_EDGES = /^\||(?<!\\)\|$/g;
 
 const INLINE_LINK =
   /(?<![!\\])\[(?:[^[\]\\]|\\.|\[[^\]]*\])*\]\(\s*(?:<[^<>\n]+>|[^\s()<>]+(?:\([^\s()]*\)[^\s()<>]*)*)(?:\s+(?:"[^"]*"|'[^']*'))?\s*\)/g;
@@ -25,6 +35,167 @@ export function ceilingFinding(text: string): AgentFinding | undefined {
   };
 }
 
+export function isCeiledReadme(repositoryPath: string, files: ReadonlySet<string>): boolean {
+  if (repositoryPath === README) return true;
+  return repositoryPath.endsWith(`/${README}`) && files.has(`${repositoryPath.slice(0, -README.length)}${MANIFEST}`);
+}
+
+type Part = { readonly title: string; readonly lines: readonly MarkdownLine[] };
+
+function endingLengths(text: string): readonly number[] {
+  const pieces = text.split("\n");
+  return pieces.map((piece, index) => (index < pieces.length - 1 ? (piece.endsWith("\r") ? 2 : 1) : 0));
+}
+
+function sizeOf(lines: readonly MarkdownLine[], endings: readonly number[]): number {
+  return lines.reduce((sum, { line, raw }) => sum + raw.length + (endings[line - 1] ?? 0), 0);
+}
+
+function sectionTitle(line: MarkdownLine, next: MarkdownLine | undefined): string | undefined {
+  if (line.kind !== "heading") return undefined;
+  const atx = SECOND_LEVEL.exec(line.raw);
+  if (atx !== null) return atx[1] ?? "";
+  return next !== undefined && SETEXT_SECOND.test(next.raw) ? line.raw.trim() : undefined;
+}
+
+function partsOf(lines: readonly MarkdownLine[]): readonly Part[] {
+  const starts = lines.flatMap((line, index) => {
+    const title = sectionTitle(line, lines[index + 1]);
+    return title === undefined ? [] : [{ index, title: `\`## ${title}\`` }];
+  });
+  const bounds = [{ index: 0, title: "the text before the first section" }, ...starts];
+  return bounds.map(({ index, title }, at) => ({ title, lines: lines.slice(index, bounds[at + 1]?.index ?? lines.length) }));
+}
+
+function largestPart(lines: readonly MarkdownLine[], endings: readonly number[]): { readonly title: string; readonly size: number } {
+  return partsOf(lines)
+    .map(({ title, lines: held }) => ({ title, size: sizeOf(held, endings) }))
+    .reduce((largest, part) => (part.size > largest.size ? part : largest));
+}
+
+function cellsOf(raw: string): readonly string[] {
+  return raw.trim().replaceAll(ROW_EDGES, "").split(CELL_SEPARATOR).map((cell) => cell.trim());
+}
+
+const DELIMITER_CELL = /^\s*:?-+:?\s*$/;
+
+function isDelimiterRow(raw: string): boolean {
+  if (/^\s*>/.test(raw)) return false;
+  if (/^(?: {4}|\t)/.test(raw)) return false;
+  const trimmed = raw.trim();
+  if (!trimmed.includes("|") || !trimmed.includes("-")) return false;
+  const inner = trimmed.replace(/^\|/, "").replace(/\|$/, "");
+  return inner.split("|").every((cell) => DELIMITER_CELL.test(cell));
+}
+
+function codeLinesIn(scanned: readonly MarkdownLine[]): ReadonlySet<number> {
+  const read = scanned.map(({ kind, raw }) => (kind === "front-matter" ? "" : raw)).join("\n");
+  const walker = new Parser().parse(read).walker();
+  const excluded = new Set<number>();
+  for (let step = walker.next(); step !== null; step = walker.next()) {
+    if (step.entering && step.node.type === "code_block") {
+      const start = step.node.sourcepos[0][0];
+      const end = step.node.sourcepos[1][0];
+      for (let line = start; line <= end; line += 1) excluded.add(line);
+    }
+  }
+  return excluded;
+}
+
+function isTableCandidate(line: MarkdownLine, code: ReadonlySet<number>): boolean {
+  if (line.kind !== "prose" && line.kind !== "table") return false;
+  if (code.has(line.line)) return false;
+  if (/^\s*>/.test(line.raw)) return false;
+  if (/^(?: {4}|\t)/.test(line.raw)) return false;
+  return true;
+}
+
+type TableRow = { readonly line: number; readonly raw: string; readonly width: number };
+
+function isBodyLine(line: MarkdownLine, code: ReadonlySet<number>): boolean {
+  if (line.raw.trim() === "") return false;
+  if (code.has(line.line)) return false;
+  if (/^\s*>/.test(line.raw)) return false;
+  if (/^(?: {4}|\t)/.test(line.raw)) return false;
+  return true;
+}
+
+type HeaderMatch = { readonly header: MarkdownLine; readonly delimiterLine: number; readonly width: number };
+
+function matchHeader(lines: readonly MarkdownLine[], at: number, code: ReadonlySet<number>): HeaderMatch | undefined {
+  const delimiter = lines[at];
+  if (delimiter === undefined || !isTableCandidate(delimiter, code)) return undefined;
+  if (!isDelimiterRow(delimiter.raw) || !CELL_SEPARATOR.test(delimiter.raw)) return undefined;
+  const header = lines[at - 1];
+  if (header === undefined || header.line + 1 !== delimiter.line) return undefined;
+  if (!isTableCandidate(header, code) || !CELL_SEPARATOR.test(header.raw)) return undefined;
+  const width = cellsOf(header.raw).length;
+  if (width !== cellsOf(delimiter.raw).length) return undefined;
+  return { header, delimiterLine: delimiter.line, width };
+}
+
+function collectBody(
+  lines: readonly MarkdownLine[],
+  from: number,
+  delimiterLine: number,
+  width: number,
+  code: ReadonlySet<number>,
+): { readonly rows: readonly TableRow[]; readonly last: number } {
+  const rows: TableRow[] = [];
+  let expected = delimiterLine + 1;
+  let last = from - 1;
+  for (let next = from; next < lines.length; next += 1) {
+    const body = lines[next];
+    if (body === undefined || body.line !== expected) break;
+    if (!isBodyLine(body, code)) break;
+    rows.push({ line: body.line, raw: body.raw, width });
+    expected += 1;
+    last = next;
+  }
+  return { rows, last };
+}
+
+function tableRows(lines: readonly MarkdownLine[], code: ReadonlySet<number>): readonly TableRow[] {
+  const rows: TableRow[] = [];
+  for (let at = 0; at < lines.length; at += 1) {
+    const matched = matchHeader(lines, at, code);
+    if (matched === undefined) continue;
+    rows.push({ line: matched.header.line, raw: matched.header.raw, width: matched.width });
+    const body = collectBody(lines, at + 1, matched.delimiterLine, matched.width, code);
+    rows.push(...body.rows);
+    at = body.last;
+  }
+  return rows;
+}
+
+export function readmeFindings(text: string): readonly AgentFinding[] {
+  const scanned = scanMarkdown(text);
+  const endings = endingLengths(text);
+  const lines = handWritten(scanned);
+  const size = sizeOf(lines, endings);
+  const largest = largestPart(lines, endings);
+  const ceiling: readonly AgentFinding[] =
+    size <= README_CEILING
+      ? []
+      : [
+          {
+            line: undefined,
+            message: `is ${size} characters, over the 6,000-character ceiling for a README. Its largest section is ${largest.title} at ${largest.size} characters. Move that section to a page under docs/ and link it from the README in one line`,
+          },
+        ];
+  const rows = tableRows(lines, codeLinesIn(scanned));
+  const cells = rows.flatMap(({ line, raw, width }) =>
+      cellsOf(raw)
+        .slice(0, width)
+        .filter((cell) => cell.length > CELL_CEILING)
+        .map((cell) => ({
+          line,
+          message: `holds a ${cell.length}-character table cell, over the 300-character ceiling for a README table cell. Move the detail to a page under docs/ and keep the cell to what a reader scans`,
+        })),
+    );
+  return [...ceiling, ...cells];
+}
+
 function blockStarts(lines: readonly MarkdownLine[], type: NodeType): ReadonlySet<number> {
   const read = lines.map(({ kind, raw }) => (kind === "front-matter" ? "" : raw)).join("\n");
   const walker = new Parser().parse(read).walker();

package/src/docs/doc-versions.ts

@@ -64,7 +64,7 @@ function patternOf({ name, version }: Pin): RegExp {
 const GENERATED_OPEN = /^\s*<!-- generated ([\w-]+):/;
 const GENERATED_CLOSE = /^\s*<!-- end generated ([\w-]+) -->/;
 
-function handWritten(lines: readonly MarkdownLine[]): readonly MarkdownLine[] {
+export function handWritten(lines: readonly MarkdownLine[]): readonly MarkdownLine[] {
   const exempt = new Set<number>();
   let at = 0;
   while (at < lines.length) {

package/src/docs/docs.ts

@@ -1,6 +1,6 @@
 #!/usr/bin/env bun
 import { Console, Effect } from "effect";
-import { ceilingFinding, entryFindings, isAgentFile, maintainingFinding } from "./doc-agents.ts";
+import { ceilingFinding, entryFindings, isAgentFile, isCeiledReadme, maintainingFinding, readmeFindings } from "./doc-agents.ts";
 import { rootsOf, snapshotOf, unresolvedIn, type Judging, type Unresolved } from "./doc-references.ts";
 import { ADR_DIRECTORY, judge, placementOf, placementProblem, recordsOf, speaksToConsumers, type Placement, type Records } from "./doc-rules.ts";
 import { vanishedNames } from "./doc-names.ts";
@@ -22,8 +22,10 @@ type Judged = {
   readonly edited: { readonly docs: number; readonly lines: number };
   readonly named: number;
   readonly agents: number;
+  readonly readmes: number;
   readonly findings: readonly Finding[];
   readonly advisory: ReadonlyMap<string, number>;
+  readonly readmeAdvisory: readonly Finding[];
   readonly sentenceAdvisory: readonly Finding[];
   readonly brokenBefore: readonly Finding[];
 };
@@ -127,6 +129,8 @@ const runDocs = Effect.fn("runDocs")(function* (root: string, base: string, head
     [ceilingFinding(text(path)), maintainingFinding(text(path))].flatMap((finding) => (finding === undefined ? [] : [{ path, ...finding }])),
   );
   const entries = agents.flatMap(({ path }) => entryFindings(path, text(path), tracked).map((finding) => ({ path, ...finding })));
+  const readmes = proseDocs.filter(({ path }) => isCeiledReadme(path, tracked.files));
+  const oversize = readmes.flatMap(({ path }) => readmeFindings(text(path)).map((finding) => ({ path, ...finding })));
   const advisory = new Map<string, number>();
   for (const { path } of templated.filter((finding) => !touched.has(finding.path))) advisory.set(path, (advisory.get(path) ?? 0) + 1);
   return {
@@ -134,6 +138,7 @@ const runDocs = Effect.fn("runDocs")(function* (root: string, base: string, head
     edited: { docs: edited.length, lines: edited.reduce((sum, { path }) => sum + (changed.get(path)?.size ?? 0), 0) },
     named: referenced.size,
     agents: agents.length,
+    readmes: readmes.filter(({ path }) => touched.has(path)).length,
     findings: [
       ...templated.filter((finding) => touched.has(finding.path)),
       ...prose,
@@ -142,8 +147,10 @@ const runDocs = Effect.fn("runDocs")(function* (root: string, base: string, head
       ...vanished,
       ...shapes,
       ...entries,
+      ...oversize.filter((finding) => touched.has(finding.path)),
     ].toSorted(inPathOrder),
     advisory,
+    readmeAdvisory: oversize.filter((finding) => !touched.has(finding.path)).toSorted(inPathOrder),
     sentenceAdvisory,
     brokenBefore: references.brokenBefore.toSorted(inPathOrder),
   } satisfies Judged;
@@ -153,7 +160,7 @@ function describe({ path, line, message }: Finding): string {
   return `  ${path}${line === undefined ? "" : `:${line}`}: ${message}`;
 }
 
-export function report({ held, edited, named, agents, findings, advisory, sentenceAdvisory, brokenBefore }: Judged): string {
+export function report({ held, edited, named, agents, readmes, findings, advisory, readmeAdvisory, sentenceAdvisory, brokenBefore }: Judged): string {
   const verdict =
     findings.length === 0
       ? [
@@ -162,6 +169,7 @@ export function report({ held, edited, named, agents, findings, advisory, senten
           `${NAME}: no line the range adds or edits copies a version package.json or .bun-version pins`,
           `${NAME}: the range breaks no path, link or command the ${named} living doc(s) or agent file(s) name`,
           `${NAME}: the ${agents} agent file(s) hold to the ceiling, and every entry names a tracked path, a link or a command`,
+          `${NAME}: the ${readmes} README(s) the range edits hold to the 6,000-character ceiling and the 300-character table cell ceiling`,
         ]
       : [`${NAME}: ${findings.length} violation(s):`, ...findings.map(describe)];
   const unconformed =
@@ -171,6 +179,10 @@ export function report({ held, edited, named, agents, findings, advisory, senten
           `${NAME}: advisory, ${advisory.size} doc file(s) the range leaves alone do not hold to their templates yet:`,
           ...[...advisory].map(([path, count]) => `  ${path}: ${count} violation(s)`),
         ];
+  const oversize =
+    readmeAdvisory.length === 0
+      ? []
+      : [`${NAME}: advisory, ${readmeAdvisory.length} README ceiling finding(s) in README(s) the range leaves alone:`, ...readmeAdvisory.map(describe)];
   const sentences =
     sentenceAdvisory.length === 0
       ? []
@@ -185,7 +197,7 @@ export function report({ held, edited, named, agents, findings, advisory, senten
           `${NAME}: advisory, ${brokenBefore.length} path(s), link(s) or command(s) the living docs or agent files name were broken before the range:`,
           ...brokenBefore.map(describe),
         ];
-  return [...verdict, ...unconformed, ...sentences, ...broken].join("\n");
+  return [...verdict, ...unconformed, ...oversize, ...sentences, ...broken].join("\n");
 }
 
 const docs = Effect.gen(function* () {