@heyramzi/lint 0.0.0-stage → 1.32.2

package/rules/redirect-external-needs-option.js

@@ -0,0 +1,45 @@
+/**
+ * A SvelteKit `redirect()` to a literal absolute URL needs `{ external: true }`.
+ */
+
+/*
+ * Kit 3 throws `redirect_external_not_allowed` and the visitor gets a 500. A dynamic location can't be judged statically, so only `"https://..."` and `//host` literals are flagged.
+ */
+
+function literalLocation(node) {
+  if (node.type === "Literal" && typeof node.value === "string") return node.value;
+  if (node.type === "TemplateLiteral") return node.quasis[0]?.value.cooked ?? "";
+  return null;
+}
+
+export default {
+  meta: {
+    type: "problem",
+    docs: { description: "Require { external: true } on a redirect() to an absolute URL." },
+    messages: {
+      needsExternal:
+        "`redirect()` to the absolute URL `{{ url }}` throws `redirect_external_not_allowed` in SvelteKit 3 and the visitor gets a 500. Pass `{ external: true }` as the third argument, or an array of the allowed origins.",
+    },
+    schema: [],
+  },
+  create(context) {
+    const local = new Set();
+    return {
+      ImportDeclaration(node) {
+        if (node.source.value !== "@sveltejs/kit") return;
+        for (const specifier of node.specifiers) {
+          if (specifier.type === "ImportSpecifier" && specifier.imported.name === "redirect") {
+            local.add(specifier.local.name);
+          }
+        }
+      },
+      CallExpression(node) {
+        if (node.callee.type !== "Identifier" || !local.has(node.callee.name)) return;
+        if (node.arguments.length !== 2) return;
+        const location = literalLocation(node.arguments[1]);
+        if (location === null || !/^(?:https?:)?\/\/(?:[^/]|$)/i.test(location)) return;
+        context.report({ node, messageId: "needsExternal", data: { url: location.slice(0, 60) } });
+      },
+    };
+  },
+};

package/rules/require-safety-comment-for-type-assertion.js

@@ -0,0 +1,110 @@
+/**
+ * Require a `SAFETY:` comment on every non-const type assertion.
+ */
+
+/*
+ * An assertion tells the compiler to trust a claim it cannot check. The comment is where the invariant that makes the claim true gets written down.
+ */
+
+/*
+ * `as const` is exempt: it narrows rather than claims.
+ */
+
+/*
+ * The comment must sit inside the containing statement, or immediately above it.
+ */
+
+/*
+ * Ported from dmmulroy/anti-slop (MIT).
+ */
+
+const SAFETY_PATTERN = /\bSAFETY\s*:/u;
+
+/** Statement kinds a SAFETY comment may be attached above. */
+const COMMENT_OWNERS = new Set([
+  "ExpressionStatement",
+  "PropertyDefinition",
+  "ReturnStatement",
+  "ThrowStatement",
+  "VariableDeclaration",
+]);
+
+function isConstAssertion(node) {
+  const annotation = node.typeAnnotation;
+  return (
+    annotation?.type === "TSTypeReference" &&
+    annotation.typeName?.type === "Identifier" &&
+    annotation.typeName.name === "const"
+  );
+}
+
+/**
+ * One diagnostic per chain: an inner assertion shares its position with the
+ * outer one, so reporting both prints the same line twice.
+ */
+function isInnerAssertionOfChain(node) {
+  let current = node;
+  let parent = node.parent;
+  while (parent?.type === "ParenthesizedExpression" && parent.expression === current) {
+    current = parent;
+    parent = parent.parent;
+  }
+  return (
+    (parent?.type === "TSAsExpression" || parent?.type === "TSTypeAssertion") &&
+    parent.expression === current
+  );
+}
+
+function ownerStart(node) {
+  let current = node;
+  while (current.parent && current.parent.type !== "Program") {
+    if (COMMENT_OWNERS.has(current.type)) break;
+    current = current.parent;
+  }
+  return current.start;
+}
+
+export default {
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Require a nearby SAFETY comment for every type assertion except const assertions.",
+    },
+    messages: {
+      missingSafetyComment:
+        "This type assertion has no `SAFETY:` justification. State the checked invariant immediately before the assertion or its containing statement.",
+    },
+    schema: [],
+  },
+  create(context) {
+    const sourceCode = context.sourceCode ?? context.getSourceCode();
+    let safetyComments = null;
+
+    const hasSafetyComment = (node) => {
+      safetyComments ??= sourceCode
+        .getAllComments()
+        .filter((comment) => SAFETY_PATTERN.test(comment.value));
+
+      if (safetyComments.length === 0) return false;
+
+      const start = ownerStart(node);
+      return safetyComments.some(
+        (comment) =>
+          comment.end <= node.start &&
+          // Inside the statement, or directly above it with only whitespace between.
+          (comment.start >= start || sourceCode.text.slice(comment.end, start).trim() === ""),
+      );
+    };
+
+    const check = (node) => {
+      if (isConstAssertion(node) || isInnerAssertionOfChain(node) || hasSafetyComment(node)) return;
+      context.report({ node, messageId: "missingSafetyComment" });
+    };
+
+    return {
+      TSAsExpression: check,
+      TSTypeAssertion: check,
+    };
+  },
+};

package/rules/svelte-section-order.js

@@ -0,0 +1,115 @@
+/**
+ * Enforce section comment ordering in Svelte <script> blocks.
+ */
+
+/*
+ * Valid order: IMPORTS → TYPES → PROPS → STATE → DERIVED → EFFECTS → FUNCTIONS Each section comment must use exactly 25 '=' signs. Skips files in components/ui/ (shadcn-svelte primitives).
+ */
+
+const VALID_SECTIONS = ["IMPORTS", "TYPES", "PROPS", "STATE", "DERIVED", "EFFECTS", "FUNCTIONS"];
+
+const SECTION_COMMENT_RE = /\/\/ (=+)\n\/\/ ([A-Z]+)\n\/\/ (=+)/g;
+
+const EXPECTED_EQUALS = 25;
+
+export default {
+  meta: {
+    type: "suggestion",
+    docs: {
+      description: "Enforce section comment ordering and format in Svelte script blocks.",
+    },
+    messages: {
+      wrongOrder:
+        '"{{ current }}" section must come after "{{ previous }}", not before. Expected order: IMPORTS → TYPES → PROPS → STATE → DERIVED → EFFECTS → FUNCTIONS.',
+      wrongEquals:
+        '"{{ section }}" section header uses {{ count }} equals signs, expected exactly {{ expected }}.',
+      unknownSection: '"{{ section }}" is not a recognized section. Valid sections: {{ valid }}.',
+    },
+    schema: [],
+  },
+  create(context) {
+    const filename = context.filename;
+
+    if (!filename.endsWith(".svelte")) return {};
+    if (/[\\/]components[\\/]ui[\\/]/.test(filename)) return {};
+
+    return {
+      Program() {
+        const source = context.sourceCode?.text ?? "";
+        if (!source) return;
+
+        const found = [];
+        let match;
+
+        SECTION_COMMENT_RE.lastIndex = 0;
+        while ((match = SECTION_COMMENT_RE.exec(source)) !== null) {
+          const [, equalsTop, name, equalsBottom] = match;
+          found.push({
+            name,
+            equalsTop: equalsTop.length,
+            equalsBottom: equalsBottom.length,
+            index: match.index,
+          });
+        }
+
+        if (found.length === 0) return;
+
+        let lastValidIndex = -1;
+
+        for (const section of found) {
+          const sectionIndex = VALID_SECTIONS.indexOf(section.name);
+
+          if (sectionIndex === -1) {
+            context.report({
+              loc: { line: 1, column: 0 },
+              messageId: "unknownSection",
+              data: {
+                section: section.name,
+                valid: VALID_SECTIONS.join(", "),
+              },
+            });
+            continue;
+          }
+
+          if (section.equalsTop !== EXPECTED_EQUALS) {
+            context.report({
+              loc: { line: 1, column: 0 },
+              messageId: "wrongEquals",
+              data: {
+                section: section.name,
+                count: String(section.equalsTop),
+                expected: String(EXPECTED_EQUALS),
+              },
+            });
+          }
+
+          if (section.equalsBottom !== EXPECTED_EQUALS) {
+            context.report({
+              loc: { line: 1, column: 0 },
+              messageId: "wrongEquals",
+              data: {
+                section: section.name,
+                count: String(section.equalsBottom),
+                expected: String(EXPECTED_EQUALS),
+              },
+            });
+          }
+
+          if (sectionIndex <= lastValidIndex) {
+            const previousName = VALID_SECTIONS[lastValidIndex];
+            context.report({
+              loc: { line: 1, column: 0 },
+              messageId: "wrongOrder",
+              data: {
+                current: section.name,
+                previous: previousName,
+              },
+            });
+          }
+
+          lastValidIndex = Math.max(lastValidIndex, sectionIndex);
+        }
+      },
+    };
+  },
+};

package/rules/test-file.js

@@ -0,0 +1,8 @@
+/**
+ * A test or fixture file: `*.test.*`, `*.spec.*`, `__fixtures__/` or `fixtures/`. Its strings are inputs under test, so rules about product copy and model ids leave it alone.
+ */
+const TEST_FILE = /\.(?:test|spec)\.|(?:^|[\\/])(?:__fixtures__|fixtures)[\\/]/;
+
+export function isTestFile(filename) {
+  return TEST_FILE.test(filename ?? "");
+}

package/scripts/count-hits.mjs

@@ -0,0 +1,213 @@
+#!/usr/bin/env node
+// Counts lint hits per rule per repo with this working copy of @heyramzi/lint, not the published one.
+// Usage: node packages/lint/scripts/count-hits.mjs [repo ...] [--warn] [--rule <name>] [--files] [--json]
+
+// Base ignorePatterns apply to every count; repos not carrying them are listed after (`ignoreGaps` in --json).
+
+import { spawnSync } from "node:child_process";
+import {
+  existsSync,
+  lstatSync,
+  readdirSync,
+  readFileSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const packageDir = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const baseConfig = join(packageDir, "config", "oxlintrc.json");
+const vibeKit = resolve(packageDir, "..", "..");
+const studio = resolve(vibeKit, "..");
+const vp = join(vibeKit, "node_modules", ".bin", "vp");
+
+const args = process.argv.slice(2);
+const flags = {
+  warn: args.includes("--warn"),
+  files: args.includes("--files"),
+  json: args.includes("--json"),
+  rule: args.includes("--rule") ? args[args.indexOf("--rule") + 1] : null,
+};
+const repoArgs = args.filter((arg, i) => !arg.startsWith("--") && args[i - 1] !== "--rule");
+
+// A Studio repo is a git checkout with a package.json, the same set the counts in the report came from.
+function studioRepos() {
+  return readdirSync(studio, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name)
+    .filter(
+      (name) =>
+        existsSync(join(studio, name, ".git")) && existsSync(join(studio, name, "package.json")),
+    )
+    .toSorted();
+}
+
+const pointsAtThisPackage = (entry) => /@heyramzi\/lint|packages\/lint/.test(entry);
+
+// oxlint configs are JSONC. Strings go through untouched so a `//` inside a URL or glob survives.
+function parseJsonc(text) {
+  const stripped = text.replace(
+    /("(?:\\.|[^"\\])*")|\/\/[^\n]*|\/\*[\s\S]*?\*\//g,
+    (match, string) => string ?? "",
+  );
+  return JSON.parse(stripped.replace(/,(\s*[}\]])/g, "$1"));
+}
+
+// The paths the repo's own `vp lint` script names, so upsys counts `app website packages` and not its vendored bundles.
+function lintTargets(repoDir) {
+  const scripts = parseJsonc(readFileSync(join(repoDir, "package.json"), "utf8")).scripts ?? {};
+  for (const script of Object.values(scripts)) {
+    const match = /\bvp lint ([^&|;]*)/.exec(script);
+    if (!match) continue;
+    const words = match[1].trim().split(/\s+/);
+    const targets = words.filter(
+      (word, i) => !word.startsWith("-") && words[i - 1] !== "-c" && words[i - 1] !== "--config",
+    );
+    const present = targets.filter((target) => existsSync(join(repoDir, target)));
+    if (present.length > 0) return present;
+  }
+  return ["."];
+}
+
+// oxlint walks into a symlinked folder, and upsys links all of vibe-kit under heyramzi-website/lib, so those get ignored.
+function symlinkedDirs(repoDir) {
+  const listed = spawnSync("git", ["ls-files", "--cached", "--others", "--exclude-standard"], {
+    cwd: repoDir,
+    encoding: "utf8",
+    maxBuffer: 1024 * 1024 * 1024,
+  }).stdout;
+  return (listed ?? "")
+    .split("\n")
+    .filter(Boolean)
+    .filter((file) => {
+      const full = join(repoDir, file);
+      return (
+        lstatSync(full, { throwIfNoEntry: false })?.isSymbolicLink() &&
+        statSync(full, { throwIfNoEntry: false })?.isDirectory()
+      );
+    })
+    .map((dir) => `${dir}/**`);
+}
+
+// An extended config's ignorePatterns resolve against its own folder and match nothing in a repo, so the repo carries them. This lists the base ones it lacks.
+const bare = (pattern) => pattern.replace(/^\*\*\//, "");
+function missingIgnores(repoDir) {
+  const ownPath = join(repoDir, ".oxlintrc.json");
+  const own = existsSync(ownPath) ? parseJsonc(readFileSync(ownPath, "utf8")) : {};
+  const carried = new Set((own.ignorePatterns ?? []).map(bare));
+  const base = parseJsonc(readFileSync(baseConfig, "utf8"));
+  return (base.ignorePatterns ?? []).filter((pattern) => !carried.has(bare(pattern)));
+}
+
+// The temp config sits in the repo root because oxlint resolves ignorePatterns and relative plugins against the config's own folder.
+function tempConfig(repoDir) {
+  const ownPath = join(repoDir, ".oxlintrc.json");
+  const own = existsSync(ownPath) ? parseJsonc(readFileSync(ownPath, "utf8")) : {};
+  const base = parseJsonc(readFileSync(baseConfig, "utf8"));
+  const extendsList = (own.extends ?? []).filter((entry) => !pointsAtThisPackage(entry));
+  const plugins = (own.jsPlugins ?? []).filter((entry) => !pointsAtThisPackage(entry));
+  return {
+    ...own,
+    extends: [baseConfig, ...extendsList],
+    jsPlugins: [packageDir, ...plugins],
+    ignorePatterns: [
+      ...new Set([
+        ...(base.ignorePatterns ?? []),
+        ...(own.ignorePatterns ?? []),
+        ...symlinkedDirs(repoDir),
+      ]),
+    ],
+  };
+}
+
+function lintRepo(name) {
+  const repoDir = join(studio, name);
+  const configPath = join(repoDir, `.oxlintrc.count-hits-${process.pid}.json`);
+  writeFileSync(configPath, JSON.stringify(tempConfig(repoDir), null, 2));
+  try {
+    const run = spawnSync(vp, ["lint", "-c", configPath, "-f", "json", ...lintTargets(repoDir)], {
+      cwd: repoDir,
+      encoding: "utf8",
+      maxBuffer: 1024 * 1024 * 1024,
+    });
+    const start = run.stdout.indexOf("{");
+    if (start === -1)
+      return { error: (run.stderr || run.stdout).trim().split("\n").slice(0, 5).join("\n") };
+    return { diagnostics: JSON.parse(run.stdout.slice(start)).diagnostics };
+  } finally {
+    rmSync(configPath, { force: true });
+  }
+}
+
+// oxlint writes a rule code as `plugin(rule)`; the config writes it as `plugin/rule`, so the report uses the config's spelling.
+const ruleName = (code) =>
+  (code ?? "unknown").replace(/^(.*)\((.*)\)$/, "$1/$2").replace(/^eslint-plugin-/, "");
+
+const repos = repoArgs.length > 0 ? repoArgs : studioRepos();
+const counts = new Map();
+const hits = [];
+const failures = [];
+const ignoreGaps = {};
+
+for (const repo of repos) {
+  if (!existsSync(join(studio, repo, "package.json"))) {
+    failures.push({ repo, error: `no package.json under ${join(studio, repo)}` });
+    continue;
+  }
+  if (!flags.json) process.stderr.write(`linting ${repo}\n`);
+  const gaps = missingIgnores(join(studio, repo));
+  if (gaps.length > 0) ignoreGaps[repo] = gaps;
+  const result = lintRepo(repo);
+  if (result.error) {
+    failures.push({ repo, error: result.error });
+    continue;
+  }
+  for (const diagnostic of result.diagnostics) {
+    if (diagnostic.severity !== "error" && !flags.warn) continue;
+    const rule = ruleName(diagnostic.code);
+    if (flags.rule && !rule.endsWith(flags.rule)) continue;
+    const perRepo = counts.get(rule) ?? new Map();
+    perRepo.set(repo, (perRepo.get(repo) ?? 0) + 1);
+    counts.set(rule, perRepo);
+    const line = diagnostic.labels?.[0]?.span?.line ?? 0;
+    hits.push({ repo, rule, file: diagnostic.filename, line, message: diagnostic.message });
+  }
+}
+
+const total = (perRepo) => [...perRepo.values()].reduce((sum, n) => sum + n, 0);
+const ranked = [...counts.entries()].toSorted((a, b) => total(b[1]) - total(a[1]));
+
+if (flags.json) {
+  const rules = Object.fromEntries(
+    ranked.map(([rule, perRepo]) => [rule, Object.fromEntries(perRepo)]),
+  );
+  const report = { repos, rules, failures, ignoreGaps };
+  if (flags.files) report.hits = hits;
+  console.log(JSON.stringify(report, null, 2));
+} else {
+  for (const [rule, perRepo] of ranked) {
+    const byRepo = [...perRepo.entries()].toSorted((a, b) => b[1] - a[1]);
+    console.log(`${String(total(perRepo)).padStart(6)}  ${rule}`);
+    for (const [repo, n] of byRepo) console.log(`${String(n).padStart(14)}  ${repo}`);
+  }
+  if (flags.files) {
+    for (const hit of hits)
+      console.log(`${hit.repo}/${hit.file}:${hit.line}  ${hit.rule}  ${hit.message}`);
+  }
+  const grand = ranked.reduce((sum, [, perRepo]) => sum + total(perRepo), 0);
+  console.log(
+    `\n${grand} ${flags.warn ? "hits" : "errors"} across ${repos.length - failures.length} repos`,
+  );
+  for (const { repo, error } of failures) console.log(`FAILED ${repo}: ${error}`);
+  const gapped = Object.entries(ignoreGaps);
+  if (gapped.length > 0) {
+    console.log(
+      `\nCounts above apply the base ignores. ${gapped.length} repos don't carry them in their own .oxlintrc.json, so their real lint run reads files the counts skip:`,
+    );
+    for (const [repo, gaps] of gapped) console.log(`  ${repo}: ${gaps.join(" ")}`);
+  }
+}
+
+process.exitCode = failures.length > 0 ? 2 : 0;

package/scripts/harvest-voice.mjs

@@ -0,0 +1,161 @@
+#!/usr/bin/env node
+/**
+ * Folds Ramzi's dictated messages into the voice profile. `--write` also rewrites the generated
+ * block in registers.md. Raw text stays in `~/.claude-ramzi/voice-corpus/`; only counts reach the repo.
+ */
+
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { appendFileSync, openSync, readSync, closeSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { measureRegister } from "#lint/register.js";
+
+const START = "<!-- voice:generated:start -->";
+const END = "<!-- voice:generated:end -->";
+/** A longer message is pasted material, not speech. */
+const MAX_WORDS = 400;
+const MIN_WORDS = 8;
+const FILLERS = ["basically", "actually", "literally", "you know", "kind of", "sort of", "i mean"];
+
+/** The words he typed in one transcript entry, or null when the entry is not his speech. */
+export function humanText(entry) {
+  if (entry?.type !== "user" || entry.isSidechain || entry.origin?.kind !== "human") return null;
+  const c = entry.message?.content;
+  const raw =
+    typeof c === "string" ? c : (c ?? []).map((b) => (b.type === "text" ? b.text : "")).join(" ");
+  const text = raw
+    .replace(/<system-reminder>[\s\S]*?<\/system-reminder>/g, "")
+    .replace(/<\/?pasted_content[^>]*>/g, "")
+    .replace(/https?:\/\/\S+/g, "")
+    .trim();
+  if (!text || /^<(?:local-)?command/.test(text)) return null;
+  const tokens = text.split(/\s+/);
+  if (tokens.length < MIN_WORDS || tokens.length > MAX_WORDS) return null;
+  return pasted(text, tokens) ? null : text;
+}
+
+/** A log, a stack trace, SVG path data, a shell session or an image placeholder, none of which he said. */
+function pasted(text, tokens) {
+  const lone = tokens.filter((t) => t.length === 1 && !/^[Iia]$/.test(t)).length;
+  const junk =
+    /\/Users\/|node_modules|[│├└┌─]|\bat \S+:\d+:\d+|\bimage\s+image\b|\[Image|\b[b-hj-zB-HJ-Z]\s+[b-hj-zB-HJ-Z]\s+[b-hj-zB-HJ-Z]\b/;
+  const code = tokens.filter((t) => /[/\\{}()<>=;_|$]|\d[a-z]+\d/i.test(t)).length;
+  return junk.test(text) || lone / tokens.length > 0.1 || code / tokens.length > 0.15;
+}
+
+/** Complete lines appended to a file since `from`, and the offset to resume at. */
+function newLines(file, from) {
+  const size = statSync(file).size;
+  if (size <= from) return { lines: [], next: from };
+  const fd = openSync(file, "r");
+  const buf = Buffer.alloc(size - from);
+  readSync(fd, buf, 0, buf.length, from);
+  closeSync(fd);
+  const chunk = buf.toString("utf8");
+  const end = chunk.lastIndexOf("\n") + 1;
+  return {
+    lines: chunk.slice(0, end).split("\n"),
+    next: from + Buffer.byteLength(chunk.slice(0, end)),
+  };
+}
+
+export function harvest({ projects, dir }) {
+  mkdirSync(dir, { recursive: true });
+  const stateFile = join(dir, "offsets.json");
+  const corpusFile = join(dir, "dictation.jsonl");
+  const state = existsSync(stateFile) ? JSON.parse(readFileSync(stateFile, "utf8")) : {};
+  let added = 0;
+  for (const project of readdirSync(projects)) {
+    if (project.includes("observer")) continue;
+    const base = join(projects, project);
+    if (!statSync(base).isDirectory()) continue;
+    for (const name of readdirSync(base).filter((f) => f.endsWith(".jsonl"))) {
+      const file = join(base, name);
+      const { lines, next } = newLines(file, state[file] ?? 0);
+      state[file] = next;
+      for (const line of lines) {
+        if (!line.includes('"kind":"human"')) continue;
+        try {
+          const entry = JSON.parse(line);
+          const text = humanText(entry);
+          if (text) {
+            appendFileSync(corpusFile, `${JSON.stringify({ t: entry.timestamp, text })}\n`);
+            added++;
+          }
+        } catch {
+          // A line cut mid-write is picked up on the next run.
+        }
+      }
+    }
+  }
+  writeFileSync(stateFile, JSON.stringify(state));
+  const rows = existsSync(corpusFile)
+    ? readFileSync(corpusFile, "utf8")
+        .split("\n")
+        .filter(Boolean)
+        .map((l) => JSON.parse(l))
+    : [];
+  return { added, rows };
+}
+
+/** Counts per 1,000 words, and the first words he opens a message with. */
+export function profile(rows) {
+  const body = rows.map((r) => r.text).join("\n\n");
+  const m = measureRegister(body);
+  const lower = body.toLowerCase();
+  const per1k = (n) => (n / m.words) * 1000;
+  const fillers = Object.fromEntries(
+    FILLERS.map((f) => [f, per1k((lower.match(new RegExp(`\\b${f}\\b`, "g")) ?? []).length)]),
+  );
+  const openers = new Map();
+  for (const r of rows) {
+    const first = r.text.toLowerCase().match(/^[a-z']+/)?.[0];
+    if (first) openers.set(first, (openers.get(first) ?? 0) + 1);
+  }
+  const top = [...openers].toSorted((a, b) => b[1] - a[1]).slice(0, 12);
+  return { messages: rows.length, m, fillers, top };
+}
+
+export function block({ messages, m, fillers, top }, day) {
+  const f = (n) => n.toFixed(1);
+  return [
+    START,
+    "<!-- Generated by `node packages/lint/scripts/harvest-voice.mjs --write`. Do not edit by hand. -->",
+    "",
+    `**His dictation to Claude, ${day}.** ${messages} messages, ${m.words} words, read off the session transcripts (\`origin.kind = human\`, 8 to 400 words each, links stripped, so pasted material is out). Speech-to-text, so the punctuation is the software's and the word choice is his.`,
+    "",
+    `Mean sentence ${f(m.meanSentence)} words, median ${f(m.medianSentence)}, ${f(m.fragmentShare)}% fragments, ${f(m.longShare)}% long. Contractions ${f(m.contractions)} per 1,000 words, "you" ${f(m.secondPerson)}, "I" ${f(m.firstPerson)}.`,
+    "",
+    `Fillers per 1,000 words: ${Object.entries(fillers)
+      .map(([k, v]) => `${k} ${f(v)}`)
+      .join(", ")}.`,
+    "",
+    `Opens a message with: ${top.map(([w, n]) => `${w} (${n})`).join(", ")}.`,
+    END,
+  ].join("\n");
+}
+
+function main() {
+  const dir = process.env.VOICE_CORPUS_DIR ?? join(homedir(), ".claude-ramzi", "voice-corpus");
+  const projects = process.env.VOICE_PROJECTS_DIR ?? join(homedir(), ".claude-ramzi", "projects");
+  const { added, rows } = harvest({ projects, dir });
+  const out = block(profile(rows), new Date().toISOString().slice(0, 10));
+  console.log(`${added} new messages, ${rows.length} in the corpus\n\n${out}`);
+  if (!process.argv.includes("--write")) return;
+  const target = fileURLToPath(
+    new URL(
+      "../../../ai-doc/skills/content/writing/humanizer/references/registers.md",
+      import.meta.url,
+    ),
+  );
+  const doc = readFileSync(target, "utf8");
+  const re = new RegExp(`${START}[\\s\\S]*?${END}`);
+  if (!re.test(doc)) throw new Error(`registers.md has no ${START} markers`);
+  writeFileSync(
+    target,
+    doc.replace(re, () => out),
+  );
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) main();