@heyramzi/lint 1.32.5 → 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
@@ -160,8 +160,10 @@ backticks is a quote and passes. The list is `MARKERS` in `comment-length.js`.
 
 Every tracked `.ts .tsx .js .jsx .mjs .cjs .svelte .swift .py .sh .bash .zsh .css .sql` file is
 read (the hack markers above apply to the first seven only), minus generated and vendored
-trees (`dist`, `build`, `.svelte-kit`, `paraglide`, `vendor`, …) and symlinks. Narrow or widen
-it with an optional `commentLength` key in the repo's root `package.json`:
+trees (`dist`, `build`, `.svelte-kit`, `paraglide`, `vendor`, …) and symlinks. Run from a folder
+below the repo root, such as a product in a monorepo, it reads only that folder's files. Narrow or
+widen it with an optional `commentLength` key in the nearest `package.json` at or above where it
+runs (its `targets` are relative to that file):
 
 ```json
 {
@@ -193,11 +195,15 @@ 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 what no person or agent writes by hand: lockfiles, `CHANGELOG.md`, `*.generated.*`,
-minified bundles, source maps, snapshots, SVGs, binaries, generated and vendored trees (`dist`,
+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`,
 `_generated`, `vendor`, the `.claude/` projections, …), files whose first 2 KB carry a codegen
 header (`@generated`, `Do not edit`, `Generated by`), and paths `.gitattributes` marks
 `linguist-generated`. A pure rename passes. There's no config and no allowlist: a hand-written

package/bin/heyramzi-comment-length.js

@@ -23,7 +23,12 @@ import {
 import { gateFiles } from "#lint/gate-files.js";
 
 const repoRoot = execFileSync("git", ["rev-parse", "--show-toplevel"], { encoding: "utf8" }).trim();
-const config = readConfig(repoRoot);
+// Run from a product inside a monorepo, the gate reads that product's files and config, not
+// its siblings': four add-ons in to-sheets failed each other's releases (21 Oct 2026).
+const scope = execFileSync("git", ["rev-parse", "--show-prefix"], { encoding: "utf8" })
+  .trim()
+  .replace(/\/$/, "");
+const config = readConfig(repoRoot, scope);
 const max = config.max ?? MAX_WORDS;
 
 const args = process.argv.slice(2);
@@ -42,17 +47,30 @@ const files = gateFiles(repoRoot, selectFiles(candidates, { ...config, ignored }
 
 gate(files);
 
-function readConfig(root) {
-  const manifest = path.join(root, "package.json");
-  if (!existsSync(manifest)) return {};
-  return JSON.parse(readFileSync(manifest, "utf8")).commentLength ?? {};
+/** The nearest `commentLength` from the scope up to the repo root; its targets are scope-relative. */
+function readConfig(root, dir) {
+  for (let rel = dir; ; rel = path.dirname(rel)) {
+    const at = rel === "." ? "" : rel;
+    const manifest = path.join(root, at, "package.json");
+    const found = existsSync(manifest)
+      ? JSON.parse(readFileSync(manifest, "utf8")).commentLength
+      : undefined;
+    if (found) {
+      const targets = found.targets?.map((t) => (at ? `${at}/${t}` : t));
+      return targets ? { ...found, targets } : found;
+    }
+    if (!at) return {};
+  }
 }
 
 function tracked(root) {
   const patterns = (config.extensions ?? DEFAULT_EXTENSIONS).map(
     (ext) => `*.${ext.replace(/^\./, "")}`,
   );
-  return execFileSync("git", ["ls-files", ...patterns], { cwd: root, encoding: "utf8" })
+  return execFileSync("git", ["ls-files", "--full-name", "--", ...patterns], {
+    cwd: path.join(root, scope),
+    encoding: "utf8",
+  })
     .trim()
     .split("\n")
     .filter(Boolean);

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/bin/heyramzi-slop.js

@@ -185,7 +185,7 @@ const paths = args.filter((a) => !a.startsWith("--"));
 
 if (paths.length === 0) {
   process.stderr.write(
-    "usage: heyramzi-slop <file|dir|-> [more...] [--fix] [--json] [--jev [--shape-block=0.6-1]] [--quiet] [--register=spoken|shorts|written] [--only=kind|id,...]\n",
+    "usage: heyramzi-slop <file|dir|-> [more...] [--fix] [--json] [--jev [--shape-block=0.6-1]] [--quiet] [--register=spoken|shorts|written|forum] [--only=kind|id,...]\n",
   );
   process.exit(2);
 }
@@ -195,7 +195,7 @@ const registerFlag = args.find((a) => a.startsWith("--register"));
 
 // That is the worst thing a gate can do: silence a caller reads as a pass.
 if (registerFlag && !registerFlag.includes("=")) {
-  process.stderr.write("--register takes a value: --register=spoken|shorts|written\n");
+  process.stderr.write("--register takes a value: --register=spoken|shorts|written|forum\n");
   process.exit(2);
 }
 const register = registerFlag ? registerFlag.split("=")[1] : undefined;

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. */
@@ -38,7 +40,11 @@ export const DEFAULT_IGNORED = [
 const IGNORED_PREFIXES = [".github/skills/"];
 
 /** Data, transcripts and tool-managed files: nobody splits a dataset, a call recording or an Xcode project by hand. */
-const DATA_EXTENSIONS = /\.(json|jsonl|ndjson|csv|tsv|txt|srt|vtt|pdf|xcstrings|strings|pbxproj|excalidraw|tldr|geojson)$/i;
+const DATA_EXTENSIONS =
+  /\.(json|jsonl|ndjson|csv|tsv|txt|srt|vtt|pdf|xcstrings|strings|pbxproj|excalidraw|tldr|geojson)$/i;
+
+/** Pages, stylesheets and logs: a page or deck CSS is one document, a log is tool output. A token cap means nothing there (Ramzi, 21 Oct 2026). */
+const UNCAPPED_EXTENSIONS = /\.(html|css|log)$/i;
 
 const LOCKFILES = new Set([
   "pnpm-lock.yaml",
@@ -61,7 +67,15 @@ const LOCKFILES = new Set([
 ]);
 
 /** Release tooling writes these, and a minified bundle, source map or snapshot is machine output. */
-const GENERATED_NAMES = [/^CHANGELOG\.md$/, /\.generated\.\w+$/,/\.min\.(js|css)$/, /\.map$/, /\.snap$/, /\.tsbuildinfo$/, /\.svg$/];
+const GENERATED_NAMES = [
+  /^CHANGELOG\.md$/,
+  /\.generated\.\w+$/,
+  /\.min\.(js|css)$/,
+  /\.map$/,
+  /\.snap$/,
+  /\.tsbuildinfo$/,
+  /\.svg$/,
+];
 
 /** A header any codegen tool writes. Read from the first 2 KB only. */
 const GENERATED_HEADER = /@generated|auto-?generated|do not edit|generated by /i;
@@ -74,13 +88,16 @@ export function tokens(bytes) {
 export function ignoredPath(file) {
   const parts = file.split("/");
   const name = parts.at(-1);
-  if (LOCKFILES.has(name) || DATA_EXTENSIONS.test(name)) return true;
+  if (LOCKFILES.has(name) || DATA_EXTENSIONS.test(name) || UNCAPPED_EXTENSIONS.test(name))
+    return true;
   if (GENERATED_NAMES.some((pattern) => pattern.test(name))) return true;
   if (IGNORED_PREFIXES.some((prefix) => file.startsWith(prefix))) return true;
   // Match the name as written (`.claude`) and with a symbol prefix stripped; stripping alone dropped every dot-folder.
   return parts.slice(0, -1).some((part) => {
     const lower = part.toLowerCase();
-    return DEFAULT_IGNORED.includes(lower) || DEFAULT_IGNORED.includes(lower.replace(/^\W+\s*/u, ""));
+    return (
+      DEFAULT_IGNORED.includes(lower) || DEFAULT_IGNORED.includes(lower.replace(/^\W+\s*/u, ""))
+    );
   });
 }
 
@@ -90,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.32.5",
+  "version": "1.34.0",
   "description": "Shared oxlint rules, base config and gates for Studio projects",
   "license": "MIT",
   "repository": {
@@ -74,7 +74,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@heyramzi/social": "^1.0.0"
+    "@heyramzi/social": "^1.1.0"
   },
   "scripts": {
     "voice:refresh": "node scripts/harvest-voice.mjs --write",

package/register.d.ts

@@ -1,4 +1,4 @@
-export type RegisterName = "spoken" | "shorts" | "written";
+export type RegisterName = "spoken" | "shorts" | "written" | "forum";
 
 export type RegisterMeasurement = {
   words: number;
@@ -20,6 +20,14 @@ export type RegisterMeasurement = {
   chaining: number;
   /** Second person for every first person. `Infinity` when there is no first person. */
   egoRatio: number;
+  /** Paragraphs, split on blank lines. */
+  paragraphs: number;
+  /** Sentences in the longest paragraph. A forum reply holds 1 to 3. */
+  paragraphSentences: number;
+  /** Words in the longest paragraph. */
+  paragraphWords: number;
+  /** Every word when the text has no paragraph break, else 0. */
+  unbrokenWords: number;
 };
 
 export type RegisterAudit = {

package/register.js

@@ -40,6 +40,10 @@ export function measureRegister(text) {
   const count = (re) => (text.match(re) ?? []).length;
   const share = (fn) =>
     lengths.length === 0 ? 0 : (lengths.filter(fn).length / lengths.length) * 100;
+  const paragraphs = text
+    .split(/\n\s*\n/)
+    .map((p) => p.trim())
+    .filter(Boolean);
 
   return {
     words,
@@ -66,6 +70,11 @@ export function measureRegister(text) {
 
     // Guarded, because a script with no "I" at all is not a failure.
     egoRatio: count(FIRST_PERSON) === 0 ? Infinity : count(SECOND_PERSON) / count(FIRST_PERSON),
+    paragraphs: paragraphs.length,
+    paragraphSentences: Math.max(0, ...paragraphs.map((p) => lines(p).length)),
+    paragraphWords: Math.max(0, ...paragraphs.map((p) => p.split(/\s+/).length)),
+    // The wall of text: every word in one paragraph, counted only when there's no break at all.
+    unbrokenWords: paragraphs.length === 1 ? words : 0,
   };
 }
 
@@ -199,6 +208,18 @@ export const REGISTERS = {
   },
 };
 
+// A Reddit or community reply: the written bands, broken into short paragraphs. Ramzi, 21 Oct 2026: our replies shipped as one block of text.
+REGISTERS.forum = {
+  label: "forum reply",
+  source: "the written bands, plus his position replies at 1 to 3 sentences a paragraph",
+  bands: {
+    ...REGISTERS.written.bands,
+    paragraphSentences: { max: 3 },
+    paragraphWords: { max: 60 },
+    unbrokenWords: { max: 40 },
+  },
+};
+
 const DIRECTION = {
   meanSentence: "words per sentence",
   lengthVariation: "spread of sentence length, SD over mean",
@@ -211,6 +232,9 @@ const DIRECTION = {
   firstPerson: "I/me/my per 1,000 words",
   egoRatio: "second person for every first person",
   chaining: "and/so/because/but per 1,000 words",
+  paragraphSentences: "sentences in the longest paragraph",
+  paragraphWords: "words in the longest paragraph",
+  unbrokenWords: "words with no paragraph break",
 };
 
 /**

package/rules/no-hardcoded-models.js

@@ -1,6 +1,6 @@
 /**
  * Ban hardcoded AI model identifiers in source code.
- * Model versions should come from @heyramzi/ai tier system (MODEL_IDS / MODEL_CATALOG).
+ * Model versions should come from the @heyramzi/utils/ai tier system (MODEL_IDS / MODEL_CATALOG).
  */
 
 import { isTestFile } from "#lint/rules/test-file.js";
@@ -14,9 +14,9 @@ const MODEL_PATTERNS = [
 
 const COMBINED = new RegExp(MODEL_PATTERNS.map((r) => r.source).join("|"));
 
-// WHY: files inside @heyramzi/ai define the canonical model catalog, so they must use literal IDs.
+// WHY: the model catalog in @heyramzi/utils/ai (and the old @heyramzi/ai) names the literal IDs.
 function isModelCatalogFile(filename) {
-  return /packages\/ai\//.test(filename);
+  return /packages\/(?:ai|utils\/src\/ai)\//.test(filename);
 }
 
 // WHY: a `ladder.ts` is where an app lists its model ids, so naming them there is the job.
@@ -29,11 +29,11 @@ export default {
     type: "suggestion",
     docs: {
       description:
-        "Disallow hardcoded AI model identifiers. Use @heyramzi/ai MODEL_IDS or MODEL_CATALOG instead.",
+        "Disallow hardcoded AI model identifiers. Use MODEL_IDS or MODEL_CATALOG from @heyramzi/utils/ai instead.",
     },
     messages: {
       noHardcodedModel:
-        'Hardcoded model "{{ model }}". Import MODEL_IDS or MODEL_CATALOG from @heyramzi/ai instead.',
+        'Hardcoded model "{{ model }}". Import MODEL_IDS or MODEL_CATALOG from @heyramzi/utils/ai instead.',
     },
     schema: [],
   },