@heyramzi/lint 1.33.0 → 1.34.0

package/README.md

@@ -143,7 +143,7 @@ Test and fixture files need no entry: `no-emoji` skips them already.
 
 ### Comment Length Gate
 
-The conduct core caps a comment at 30 words. `heyramzi-comment-length` enforces it over a
+`ai-doc/rules/comments.md` caps a comment at 30 words. `heyramzi-comment-length` enforces it over a
 whole repo: block comments, HTML comments and runs of consecutive line comments (`//`, `#`, `--`).
 
 ```bash
@@ -195,8 +195,12 @@ Installed into every Studio repo's active pre-push hook by `bash ai-doc/scripts/
 
 ### File Token Gate
 
-No staged file may run past 5,000 tokens, counted as bytes / 4. `heyramzi-file-tokens` reads the
-staged blobs, not the working copy, so it judges exactly what the commit records.
+No staged file may run past its cap, counted as bytes / 4: 5,000 tokens for code, 8,000 for
+Markdown, because a reference reads top to bottom and splitting it at 5,000 scattered one topic over
+linked files. `heyramzi-file-tokens` reads the staged blobs, not the working copy, so it judges
+exactly what the commit records. `heyramzi-file-tokens --file <path>…` runs the same check on working
+copies; the `file-tokens-warn.sh` hook calls it after every write, so a file is split when it
+crosses the cap, not at someone else's commit.
 
 It skips pages, stylesheets and logs (`.html`, `.css`, `.log`), and what no person or agent
 writes by hand: lockfiles, `CHANGELOG.md`, `*.generated.*`, minified bundles, source maps, snapshots, SVGs, binaries, generated and vendored trees (`dist`,

package/bin/heyramzi-file-tokens.js

@@ -1,42 +1,72 @@
 #!/usr/bin/env node
 /**
- * The file-token gate over staged files. Usage: this package's README, "File Token Gate".
+ * The file-token gate. Usage: this package's README, "File Token Gate".
  *
- *   heyramzi-file-tokens  # non-zero when a staged file runs over 5,000 tokens
+ *   heyramzi-file-tokens               # staged files
+ *   heyramzi-file-tokens --file <p>…   # working copies, for the write-time hook
  */
 
 import { execFileSync } from "node:child_process";
-import { exit } from "node:process";
+import { readFileSync, statSync } from "node:fs";
+import { dirname, relative, resolve } from "node:path";
+import { argv, exit } from "node:process";
 
-import {
-  MAX_TOKENS,
-  check,
-  generatedContent,
-  ignoredPath,
-  report,
-} from "#lint/file-tokens.js";
+import { check, generatedContent, ignoredPath, report } from "#lint/file-tokens.js";
 
-const repoRoot = execFileSync("git", ["rev-parse", "--show-toplevel"], { encoding: "utf8" }).trim();
+const fileMode = argv[2] === "--file";
+// A hook passes a path from any repo, so the file's own folder names the repo, not the cwd.
+const repoRoot = gitRoot(fileMode && argv[3] ? dirname(resolve(argv[3])) : ".");
+if (!repoRoot) exit(0);
 const git = (args, input) =>
   execFileSync("git", args, { cwd: repoRoot, input, maxBuffer: 256 * 1024 * 1024 });
 
-const failures = check(stagedSizes(staged().filter((file) => !ignoredPath(file))));
+const failures = fileMode
+  ? check(workingSizes(argv.slice(3)))
+  : check(stagedSizes(staged().filter((file) => !ignoredPath(file))));
 const real = failures.filter(({ file }) => !generated(file));
 
 if (real.length === 0) {
-  console.log(`file-tokens: every staged file is under ${MAX_TOKENS.toLocaleString("en-US")} tokens`);
+  console.log(`file-tokens: every ${fileMode ? "" : "staged "}file is under its cap`);
 } else {
   console.error(report(real));
   exit(1);
 }
 
+function gitRoot(cwd) {
+  try {
+    return execFileSync("git", ["rev-parse", "--show-toplevel"], {
+      cwd,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+  } catch {
+    return "";
+  }
+}
+
+/** Working-copy sizes of the given paths, repo-relative, skipping what the gate never caps. */
+function workingSizes(paths) {
+  return Object.fromEntries(
+    paths
+      .map((path) => relative(repoRoot, resolve(path)))
+      .filter((file) => !file.startsWith("..") && !ignoredPath(file))
+      .flatMap((file) => {
+        try {
+          return [[file, statSync(resolve(repoRoot, file)).size]];
+        } catch {
+          return [];
+        }
+      }),
+  );
+}
+
 /** Added, copied, modified and renamed files. A pure move (R100) changes nothing, so it passes. */
 function staged() {
   const fields = git(["diff", "--cached", "--name-status", "-M", "-z", "--diff-filter=ACMR"])
     .toString("utf8")
     .split("\0");
   const files = [];
-  for (let index = 0; index < fields.length - 1; ) {
+  for (let index = 0; index < fields.length - 1;) {
     const status = fields[index];
     const paired = status.startsWith("R") || status.startsWith("C");
     const target = fields[index + (paired ? 2 : 1)];
@@ -49,18 +79,32 @@ function staged() {
 /** Byte size of each file's staged blob, which is what gets committed, not the working copy. */
 function stagedSizes(files) {
   if (files.length === 0) return {};
-  const lines = git(["cat-file", "--batch-check=%(objectsize)"], files.map((file) => `:${file}`).join("\n"))
+  const lines = git(
+    ["cat-file", "--batch-check=%(objectsize)"],
+    files.map((file) => `:${file}`).join("\n"),
+  )
     .toString("utf8")
     .trim()
     .split("\n");
   return Object.fromEntries(
-    files.flatMap((file, index) => (/^\d+$/.test(lines[index]) ? [[file, Number(lines[index])]] : [])),
+    files.flatMap((file, index) =>
+      /^\d+$/.test(lines[index]) ? [[file, Number(lines[index])]] : [],
+    ),
   );
 }
 
 /** Content markers or `.gitattributes` say a machine wrote this file. Checked only for files over the cap. */
 function generated(file) {
-  const attribute = git(["check-attr", "--cached", "linguist-generated", "--", file]).toString("utf8");
+  const attribute = git([
+    "check-attr",
+    ...(fileMode ? [] : ["--cached"]),
+    "linguist-generated",
+    "--",
+    file,
+  ]).toString("utf8");
   if (/: (set|true)\s*$/.test(attribute)) return true;
-  return generatedContent(git(["cat-file", "blob", `:${file}`]).subarray(0, 8000));
+  const head = fileMode
+    ? readFileSync(resolve(repoRoot, file))
+    : git(["cat-file", "blob", `:${file}`]);
+  return generatedContent(head.subarray(0, 8000));
 }

package/comment-length.js

@@ -1,6 +1,6 @@
 /**
  * The 30-word comment cap: a comment that outgrows its explanation stops being
- * read. The rule is `ai-doc/references/agents-core.md`.
+ * read. The rule is `ai-doc/rules/comments.md`.
  *
  * Pure here, git and process in `bin/heyramzi-comment-length.js`.
  */
@@ -239,7 +239,11 @@ function simpleSpans(src, syntax) {
       i = j;
     } else if (syntax.raw && c === "#" && rawStringEnd(src, i) !== null) {
       i = rawStringEnd(src, i);
-    } else if (syntax.url && src.startsWith("url(", i) && !/^url\(\s*["']/.test(src.slice(i, i + 12))) {
+    } else if (
+      syntax.url &&
+      src.startsWith("url(", i) &&
+      !/^url\(\s*["']/.test(src.slice(i, i + 12))
+    ) {
       const close = src.indexOf(")", i);
       i = close === -1 ? src.length : close + 1;
     } else if (syntax.quotes.includes(c)) {

package/file-tokens.js

@@ -1,9 +1,11 @@
 /**
- * The file-token gate: no staged file an agent writes may run past 5,000 tokens.
- * Pure here, git and process in `bin/heyramzi-file-tokens.js`.
+ * The file-token gate: no staged file an agent writes may run past its cap, 5,000 tokens for code
+ * and 8,000 for Markdown. Pure here, git and process in `bin/heyramzi-file-tokens.js`.
  */
 
 export const MAX_TOKENS = 5000;
+/** A reference reads top to bottom; split at 5,000 it scattered one topic over linked files (Ramzi, 22 Oct 2026). */
+export const MARKDOWN_MAX_TOKENS = 8000;
 export const BYTES_PER_TOKEN = 4;
 
 /** Generated, vendored or projected trees: nobody hand-writes these, so nobody splits them. */
@@ -105,21 +107,26 @@ export function generatedContent(head) {
   return GENERATED_HEADER.test(head.subarray(0, 2048).toString("utf8"));
 }
 
-/** Files over the cap, biggest first. `sizes` maps path to staged bytes. */
-export function check(sizes, max = MAX_TOKENS) {
+/** The cap a file is held to. */
+export function capFor(file) {
+  return /\.mdx?$/i.test(file) ? MARKDOWN_MAX_TOKENS : MAX_TOKENS;
+}
+
+/** Files over their cap, biggest first. `sizes` maps path to bytes. */
+export function check(sizes) {
   return Object.entries(sizes)
-    .map(([file, bytes]) => ({ file, bytes, tokens: tokens(bytes) }))
-    .filter((entry) => entry.tokens > max)
+    .map(([file, bytes]) => ({ file, bytes, tokens: tokens(bytes), cap: capFor(file) }))
+    .filter((entry) => entry.tokens > entry.cap)
     .sort((left, right) => right.tokens - left.tokens);
 }
 
 /** The refusal. It tells the agent how to split, because "too big" alone gets a file squashed, not split. */
-export function report(failures, max = MAX_TOKENS) {
+export function report(failures) {
   const rows = failures.map(
-    ({ file, bytes, tokens: count }) =>
-      `  ${file}  ${count.toLocaleString("en-US")} tokens (${bytes.toLocaleString("en-US")} bytes), ${Math.round((count / max) * 100)}% of the cap`,
+    ({ file, bytes, tokens: count, cap }) =>
+      `  ${file}  ${count.toLocaleString("en-US")} tokens (${bytes.toLocaleString("en-US")} bytes), ${Math.round((count / cap) * 100)}% of its ${cap.toLocaleString("en-US")} cap`,
   );
-  return `file-tokens: ${failures.length} staged file(s) over ${max.toLocaleString("en-US")} tokens (tokens = bytes / ${BYTES_PER_TOKEN}):
+  return `file-tokens: ${failures.length} file(s) over their cap: ${MAX_TOKENS.toLocaleString("en-US")} tokens for code, ${MARKDOWN_MAX_TOKENS.toLocaleString("en-US")} for Markdown (tokens = bytes / ${BYTES_PER_TOKEN}):
 ${rows.join("\n")}
 
 Split each file before you commit. Don't get under the cap by deleting comments, squashing lines or shortening names: that keeps one file doing too many jobs.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heyramzi/lint",
-  "version": "1.33.0",
+  "version": "1.34.0",
   "description": "Shared oxlint rules, base config and gates for Studio projects",
   "license": "MIT",
   "repository": {