@heyramzi/lint 0.0.0-stage → 1.32.4

package/jev.js

@@ -0,0 +1,341 @@
+/**
+ * The judgement half of the humanizer patterns, asked of TypeSafe Jev per sentence
+ * and per paragraph, through the Kilo gateway. Bench: scripts/jev-bench.mjs. Why these shapes: TECHLOG.md.
+ */
+
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+// =========================
+// CONSTANTS
+// =========================
+/** TypeSafe's /v1/systemone behind Kilo, which bills our Kilo credits and pins the model. */
+const KILO_URL = "https://api.kilo.ai/api/gateway/typesafe/v1/systemone";
+/** One request that hangs must not hang a draft: past this it counts as unreachable. */
+const TIMEOUT_MS = 30_000;
+/** Kilo only takes the pinned name; `jev-latest` answers 400 model_not_found. */
+export const MODEL = "typesafe/jev-1.13";
+export const NO_KEY = "needs KILO_API_KEY (Proton Pass, Dev vault, item Kilo)";
+export const FAIL = 0.75;
+export const REVIEW = 0.6;
+/** Scores drift about 0.05 between identical calls, so each item is asked RUNS times and its worst score counts. */
+const RUNS = 3;
+/** Items per request: 4 sentences x 9 shapes answered in about 1s. */
+const BATCH = 4;
+const CONCURRENCY = 8;
+
+/** One question per root cause, not per pattern: humanizer references/patterns.md maps each pattern to one. */
+export const q = (instructions, yes, no) => ({
+  type: "noul",
+  instructions,
+  criteria: { true: yes, false: no },
+});
+const PLAIN =
+  "A plain, literal sentence: a step the reader takes, a named thing, a number, or a fact that carries its own meaning.";
+
+/** Asked of every sentence, with its paragraph as `context`. */
+export const SHAPES = {
+  inflated: q(
+    "Does `sentence` tell the reader that something matters, impresses or feels a certain way, instead of giving the fact, number or mechanism that would show it, or is it generic enough to move unchanged to another company, product or person?",
+    "Praise, significance, emotion or quality asserted, not shown, or a line with nothing only this subject could say.",
+    `${PLAIN} Or a letter's courtesy to its reader: a thanks, a greeting, an invitation.`,
+  ),
+  aphorism: q(
+    "Is `sentence` a slogan or maxim: a quotable general truth stated in abstract terms instead of a concrete step, number or fact?",
+    "Could be printed on a poster, often a flip or an 'only', and the next sentence has to explain it.",
+    PLAIN,
+  ),
+  law: q(
+    "Does `sentence` describe how a tool, setting or system behaves as a general rule, with the thing as the subject and no person acting, where it could tell the reader what to do and what they will see?",
+    "The subject is an object or an idea, the verb is a state or a spread, and the reader has no step to copy. Often it ends on 'it' or 'them'.",
+    "A person does something, a literal step (where to click, what appears), a measured result of what happened, with its number, or a plain fact or rule about one specific thing said the way a person would ('the back door doesn't lock', 'a cancelled ticket is never refunded').",
+  ),
+  vague: q(
+    "Does `sentence` point at content instead of stating it: it announces, promises, sets up or labels a point that the sentence itself does not give?",
+    "A teaser, signpost or label: the reader learns that there is a reason, a tip, a rule or a next step, but not what it is.",
+    "The sentence gives the content itself, the paragraph gives it right after, or it starts with 'Link:' and names what the reader does when they click.",
+  ),
+  hedge: q(
+    "Does `sentence` pad itself with a hedge, a reassurance, a propping adverb (really, basically, actually), an unnamed source, or a line about the conversation instead of the subject?",
+    "It contains padding of that kind, or talks about the writing instead of the subject.",
+    "No hedge, prop or talk about the conversation. A thanks, a greeting or a question to the reader is not padding.",
+  ),
+  filler: q(
+    "Can one word or phrase in `sentence` be deleted, or swapped for a shorter one, and the sentence still say exactly the same thing?",
+    "At least one word can go or shrink ('in order to', 'each and every', a word the rest already implies) with no loss of meaning.",
+    "Every word carries meaning the sentence would lose. Warmth to the reader in a letter counts as meaning.",
+  ),
+  contrast: q(
+    "Does `sentence` stage a contrast to make its point: 'not X, it's Y' denying a claim nobody made, an either-or where one side is a strawman, a 'from X to Y' span with no real range, or one claim said twice in other words?",
+    "The denied half, the strawman side, the span or the repeat is there for effect. Delete it and the point stands alone.",
+    "A real comparison between two named options, or a single plain claim.",
+  ),
+  stilted: q(
+    "Does `sentence` sound awkward or unnatural, like a clumsy translation or a forced rewrite, so a native English speaker would phrase it differently or need to reread it?",
+    "Awkward phrasing: a person made the subject of find, meet or get where people would say 'there is' or 'X has'; an odd verb; an unexplained code or label; a clumsy word order.",
+    "Natural, clear English a person would say out loud.",
+  ),
+  pitch: q(
+    "Is `sentence` an ad line that promises an effortless result: a dramatic command plus an outcome said to be already true, or a lone word used as a verdict, instead of saying what happens when the reader takes an action?",
+    "Reads like a tagline: 'Do X, and Y is already done', or a one-word fragment as the punchline.",
+    `${PLAIN} Or a literal step with what happens next, in the product's own terms.`,
+  ),
+  personified: q(
+    "Does `sentence` use a figure where a literal word exists: a non-human thing doing what only a person does, or an abstract idea dressed as a physical object?",
+    "A tool that knows, wants, saves or gives; an idea that is a lever, a ceiling, a moat or a muscle.",
+    "The thing does something mechanical and literal, or a person does the acting.",
+  ),
+  thingdoer: q(
+    "Does `sentence` make a tool, automation, checklist, script or system the grammatical subject of what a person sets up or does, where a person as the subject ('we', 'you', or an imperative) would be plainer?",
+    "A noun leads and acts: 'An automation creates it and assigns it', 'A checklist catches this', 'The script only posts what is approved'. It reads like a description of a machine, with nobody behind it. Ramzi, 30 Sep 2026.",
+    "A person is the subject or the sentence is an instruction ('Have an automation create it'), or the thing genuinely is the subject of a literal fact ('The API returns JSON').",
+  ),
+  stagey: q(
+    "Does `sentence` describe an action or a rule as a small scene where a plain verb and object would do: 'waits for someone to say go' for 'needs your approval', 'gets you most of the way' for 'covers most of it', 'does its sweep' for 'runs'?",
+    "A phrase that acts out the idea (waits, says go, gets you there, takes the wheel) when one plain verb says the same thing. Ramzi, 30 Sep 2026: 'Claude Code on a timer requires you' is simpler and means the same.",
+    "The sentence already uses the plain verb and object a person would say out loud.",
+  ),
+};
+
+/** Asked once per paragraph of 3 or more sentences: the shapes no single sentence shows. */
+export const PARAGRAPH_SHAPES = {
+  rhythm: q(
+    "Does `paragraph` repeat one structure instead of varying it: sentences of one length or one opening, items forced into threes, a punchy closer on every beat, a word reused where no new idea arrived, or a transition that asserts a link the facts do not show?",
+    "A reader could predict the shape of the next sentence before reading it.",
+    "Sentence lengths and openings vary with the thought, and each link between sentences is shown by what they say.",
+  ),
+};
+
+// =========================
+// FUNCTIONS
+// =========================
+/** Short unpunctuated lines are glance copy (subjects, headlines); Ramzi, 23 Sep 2026, on a subject Jev never saw. */
+const GLANCE = /^[^\n]{1,60}$/;
+
+/** Prose sentences with their paragraph, plus glance lines of 4+ words as their own item. */
+export function sentences(text) {
+  return text.split(/\n\s*\n|\n(?=\s*[-*]\s)/).flatMap((para) => {
+    const lines = para
+      .split("\n")
+      .map((l) => l.replace(/^\s*(?:#+|[-*])\s*/, "").trim())
+      .filter(Boolean);
+    if (lines.every((l) => GLANCE.test(l)) && lines.some((l) => !/[.!?]["')\]]*$/.test(l))) {
+      return lines
+        .filter((l) => l.split(" ").length >= 4)
+        .map((l) => ({ sentence: l, context: l }));
+    }
+    // An unpunctuated line is a heading: end it, so it isn't glued to the next sentence.
+    const flat = para.replace(/\s+/g, " ").trim();
+    const ended = lines.map((l) => (/[.!?:]["')\]]*$/.test(l) ? l : `${l}.`)).join(" ");
+    // A stop only ends a sentence before a space, so "1.5" stays whole.
+    return (ended.match(/.+?[.!?]+["')\]]*(?=\s|$)/g) ?? [])
+      .map((s) => s.trim())
+      .filter((s) => s.split(" ").length >= 3)
+      .map((sentence) => ({ sentence, context: flat }));
+  });
+}
+
+/** Markup as Jev reads it: a block ends a paragraph, and link text says it's a link. */
+export function proseOf(html) {
+  return html
+    .replace(/<(script|style)[\s\S]*?<\/\1>|<!--[\s\S]*?-->/gi, " ")
+    .replace(/<a\b[^>]*>([\s\S]*?)<\/a>/gi, "\n\nLink: $1\n\n")
+    .replace(/<\/(p|li|h[1-6]|div|td|blockquote)>|<br\s*\/?>/gi, "\n\n")
+    .replace(/<[^>]+>/g, " ")
+    .replace(/&rarr;|&[a-z]+;|&#\d+;/gi, " ")
+    .replace(/[ \t]+/g, " ")
+    .replace(/\n\s*\n\s*/g, "\n\n")
+    .trim();
+}
+
+/** Paragraphs long enough to have a rhythm: 3 sentences or more. */
+export function paragraphs(text) {
+  return text
+    .split(/\n\s*\n/)
+    .map((para) => para.replace(/\s+/g, " ").trim())
+    .filter((para) => (para.match(/[.!?]+["')\]]*(?=\s|$)/g) ?? []).length >= 3)
+    .map((paragraph) => ({ paragraph }));
+}
+
+/** `KILO_API_KEY` from the env, else Proton Pass (Dev vault, item Kilo), else "". */
+export function kiloKey() {
+  if (process.env.KILO_API_KEY) return process.env.KILO_API_KEY;
+  try {
+    return execFileSync(
+      "pass-cli",
+      ["item", "view", "--vault-name", "Dev", "--item-title", "Kilo", "--field", "password"],
+      { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 30_000 },
+    ).trim();
+  } catch {
+    return "";
+  }
+}
+
+/** The model check could not run: network, key, credits, timeout or a bad answer. Callers skip it, not crash. */
+function unavailable(message) {
+  return Object.assign(new Error(message), { name: "JevUnavailable" });
+}
+
+export const isUnavailable = (err) => err instanceof Error && err.name === "JevUnavailable";
+
+/** The URL is overridable so a test can point it at a local server or an unresolvable host. */
+const endpoint = () => process.env.HEYRAMZI_JEV_URL || KILO_URL;
+
+function why(err) {
+  if (err?.name === "TimeoutError") return `timed out after ${TIMEOUT_MS / 1000}s`;
+  return err?.cause?.code ?? err?.cause?.message ?? err?.message ?? String(err);
+}
+
+async function post(body, key, attempt = 0) {
+  let res;
+  try {
+    res = await fetch(endpoint(), {
+      method: "POST",
+      headers: { Authorization: `Bearer ${key}`, "Content-Type": "application/json" },
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(TIMEOUT_MS),
+    });
+  } catch (err) {
+    throw unavailable(`${new URL(endpoint()).host} unreachable (${why(err)})`);
+  }
+  if ((res.status === 429 || res.status >= 500) && attempt < 4) {
+    await new Promise((r) => setTimeout(r, 1000 * 2 ** attempt));
+    return post(body, key, attempt + 1);
+  }
+  if (!res.ok) throw unavailable(`Jev HTTP ${res.status}: ${(await res.text()).slice(0, 200)}`);
+  const { answers } = await res.json().catch(() => ({}));
+  if (!answers) throw unavailable("Jev answered without scores");
+  return answers;
+}
+
+/** One request for every shape of up to BATCH items; item `i` is `i<n>` in state, so `field` becomes `i<n>.field`. */
+async function askBatch(items, key, shapes, field) {
+  const state = Object.fromEntries(items.map((it, n) => [`i${n}`, it]));
+  const questions = {};
+  items.forEach((_, n) => {
+    for (const [id, q] of Object.entries(shapes)) {
+      questions[`i${n}_${id}`] = {
+        ...q,
+        instructions: q.instructions.replaceAll(`\`${field}\``, `\`i${n}.${field}\``),
+      };
+    }
+  });
+  const answers = await post({ model: MODEL, state, questions }, key);
+  return items.map((_, n) =>
+    Object.fromEntries(
+      Object.keys(shapes).map((id) => {
+        const score = answers[`i${n}_${id}`]?.noul;
+        if (typeof score !== "number") throw unavailable(`Jev left out the score for ${id}`);
+        return [id, score];
+      }),
+    ),
+  );
+}
+
+async function pooled(jobs) {
+  const out = [];
+  for (let i = 0; i < jobs.length; i += CONCURRENCY)
+    out.push(...(await Promise.all(jobs.slice(i, i + CONCURRENCY).map((job) => job()))));
+  return out;
+}
+
+// =========================
+// CACHE
+// =========================
+/**
+ * Identical text scored 0.71, then 0.78 (12 Oct 2026). Worst-of-RUNS scores are kept per model, shape
+ * set and normalized text, so a re-run asks nothing.
+ */
+const cacheRoot = () =>
+  process.env.HEYRAMZI_SLOP_CACHE ||
+  join(process.env.XDG_CACHE_HOME || join(homedir(), ".cache"), "heyramzi-slop");
+/** `HEYRAMZI_SLOP_CACHE=off` asks the model every time, which is what a bench of the questions needs. */
+const cacheOff = () => process.env.HEYRAMZI_SLOP_CACHE === "off";
+
+const normalize = (text) => text.normalize("NFC").replace(/\s+/g, " ").trim();
+const digest = (value) => createHash("sha256").update(value).digest("hex");
+
+function cacheFile(item, field, shapesKey) {
+  const name = digest(JSON.stringify([MODEL, field, shapesKey, normalize(item[field])]));
+  return join(cacheRoot(), MODEL.replace(/[^\w.-]/g, "_"), `${name.slice(0, 40)}.json`);
+}
+
+function readScores(item, field, shapesKey, shapes) {
+  if (cacheOff()) return undefined;
+  try {
+    const scores = JSON.parse(readFileSync(cacheFile(item, field, shapesKey), "utf8"));
+    return Object.keys(shapes).every((id) => typeof scores[id] === "number") ? scores : undefined;
+  } catch {
+    // No entry, or a half-written one: ask the model.
+    return undefined;
+  }
+}
+
+function writeScores(item, field, shapesKey, scores) {
+  if (cacheOff()) return;
+  const file = cacheFile(item, field, shapesKey);
+  try {
+    mkdirSync(join(file, ".."), { recursive: true });
+    writeFileSync(`${file}.${process.pid}.tmp`, JSON.stringify(scores));
+    renameSync(`${file}.${process.pid}.tmp`, file);
+  } catch {
+    // An unwritable cache (a sandbox, a full disk) costs a re-ask, never the gate.
+  }
+}
+
+// =========================
+// JUDGE
+// =========================
+/** Every item's worst score per shape over RUNS calls, kept from REVIEW up. Cached items cost no request. */
+async function askAll(items, key, shapes, field) {
+  const shapesKey = digest(JSON.stringify(shapes));
+  const worst = items.map((it) => readScores(it, field, shapesKey, shapes));
+  const pending = items.flatMap((_, i) => (worst[i] ? [] : [i]));
+  const chunks = [];
+  for (let i = 0; i < pending.length; i += BATCH) chunks.push(pending.slice(i, i + BATCH));
+  const runs = await pooled(
+    chunks.flatMap((chunk) =>
+      Array.from({ length: RUNS }, () => async () => ({
+        chunk,
+        scores: await askBatch(
+          chunk.map((i) => items[i]),
+          key,
+          shapes,
+          field,
+        ),
+      })),
+    ),
+  );
+  for (const { chunk, scores } of runs) {
+    scores.forEach((byShape, n) => {
+      const seen = (worst[chunk[n]] ??= {});
+      for (const [id, p] of Object.entries(byShape)) seen[id] = Math.max(seen[id] ?? 0, p);
+    });
+  }
+  for (const i of pending) writeScores(items[i], field, shapesKey, worst[i]);
+  return items.flatMap((it, i) =>
+    Object.entries(worst[i])
+      .filter(([, p]) => p >= REVIEW)
+      .map(([id, p]) => ({ p, kind: "shape", id, detail: `${p.toFixed(2)}  "${it[field]}"` })),
+  );
+}
+
+/** Every item asked every shape: `findings` at `block` and up (FAIL by default), `review` from REVIEW to `block`. */
+export async function judge(items, shapes, field, key, block = FAIL) {
+  const hits = await askAll(items, key, shapes, field);
+  return { findings: hits.filter((h) => h.p >= block), review: hits.filter((h) => h.p < block) };
+}
+
+/**
+ * Shapes Jev reads in a text. A report (`review`) unless `block` names a bar; a hit at or above it
+ * is a `finding`. Throws JevUnavailable when the model can't answer.
+ */
+export async function auditShapes(text, { key = process.env.KILO_API_KEY, block = Infinity } = {}) {
+  if (!key) throw unavailable(`--jev ${NO_KEY}`);
+  const a = await judge(sentences(text), SHAPES, "sentence", key, block);
+  const b = await judge(paragraphs(text), PARAGRAPH_SHAPES, "paragraph", key, block);
+  return { findings: [...a.findings, ...b.findings], review: [...a.review, ...b.review] };
+}

package/package.json

@@ -1,6 +1,83 @@
 {
   "name": "@heyramzi/lint",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.32.4",
+  "description": "Shared oxlint rules, base config and gates for Studio projects",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/heyramzi/vibe-kit.git",
+    "directory": "packages/lint"
+  },
+  "bin": {
+    "heyramzi-commit-msg": "./bin/heyramzi-commit-msg.js",
+    "heyramzi-comment-length": "./bin/heyramzi-comment-length.js",
+    "heyramzi-file-tokens": "./bin/heyramzi-file-tokens.js",
+    "heyramzi-inline-path": "./bin/heyramzi-inline-path.js",
+    "heyramzi-jev-code": "./bin/heyramzi-jev-code.js",
+    "heyramzi-push-diff": "./bin/heyramzi-push-diff.js",
+    "heyramzi-repo-rules": "./bin/heyramzi-repo-rules.js",
+    "heyramzi-slop": "./bin/heyramzi-slop.js",
+    "heyramzi-svelte-markup": "./bin/heyramzi-svelte-markup.js",
+    "heyramzi-ui-rules": "./bin/heyramzi-ui-rules.js"
+  },
+  "files": [
+    "bin",
+    "config",
+    "data",
+    "comment-length.js",
+    "commit-msg.js",
+    "file-tokens.js",
+    "gate-files.js",
+    "inline-path.js",
+    "index.js",
+    "jev.js",
+    "jev-code.js",
+    "package.json",
+    "processors",
+    "push-diff.js",
+    "slop.d.ts",
+    "slop.js",
+    "slop-views.js",
+    "ui-rules.js",
+    "svelte-markup.js",
+    "svelte-template.js",
+    "register.js",
+    "register.d.ts",
+    "repo-rules.js",
+    "repo-rules",
+    "scripts",
+    "rules"
+  ],
+  "type": "module",
+  "main": "index.js",
+  "imports": {
+    "#lint/*": "./*"
+  },
+  "exports": {
+    ".": "./index.js",
+    "./oxlint": "./config/oxlintrc.json",
+    "./slop-words": {
+      "types": "./data/slop-words.d.ts",
+      "default": "./data/slop-words.js"
+    },
+    "./register": {
+      "types": "./register.d.ts",
+      "default": "./register.js"
+    },
+    "./slop": {
+      "types": "./slop.d.ts",
+      "default": "./slop.js"
+    },
+    "./invisibles": "./data/invisibles.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@heyramzi/social": "^1.0.0"
+  },
+  "scripts": {
+    "voice:refresh": "node scripts/harvest-voice.mjs --write",
+    "test": "node --test \"*.test.mjs\""
+  }
+}

package/processors/markdown.js

@@ -0,0 +1,22 @@
+/**
+ * Processor that wraps each markdown line as a JS string literal,
+ * so stop-slop rules (no-ai-words, no-em-dash) can check prose.
+ */
+
+export const markdownProcessor = {
+  meta: {
+    name: "stop-slop/markdown",
+  },
+
+  preprocess(text) {
+    const lines = text.split("\n");
+    const code = lines.map((line, i) => `const _line${i} = ${JSON.stringify(line)};`).join("\n");
+    return [{ text: code, filename: "0.js" }];
+  },
+
+  postprocess(messages) {
+    return messages.flat();
+  },
+
+  supportsAutofix: false,
+};

package/push-diff.js

@@ -0,0 +1,55 @@
+/**
+ * The pushed-diff gate: a push may not change a persisted `StorageKey` string.
+ * Pure here, git and process in `bin/heyramzi-push-diff.js`.
+ */
+import { commentSpans } from "#lint/comment-length.js";
+
+
+/** The registry the add-ons persist under: `enum StorageKey {…}` or `const StorageKey = {…}`. */
+const REGISTRY = /(?:\benum\s+StorageKey\s*\{|\bStorageKey\s*(?::[^=\n]+)?=\s*\{)/;
+
+export const hasStorageKeys = (source) => REGISTRY.test(source);
+
+/** Each `NAME: "value"` (or `NAME = "value"`) of the StorageKey registry. Comments are blanked first, so one holding a quote or a brace can't skew it. */
+export function storageKeysOf(source) {
+  let clean = source;
+  for (const span of commentSpans(source).toReversed()) {
+    clean = clean.slice(0, span.start) + " ".repeat(span.end - span.start) + clean.slice(span.end);
+  }
+  const open = REGISTRY.exec(clean);
+  const keys = new Map();
+  if (!open) return keys;
+  let depth = 1;
+  let end = open.index + open[0].length;
+  while (end < clean.length && depth > 0) {
+    if (clean[end] === "{") depth += 1;
+    else if (clean[end] === "}") depth -= 1;
+    end += 1;
+  }
+  const body = clean.slice(open.index + open[0].length, end);
+  const entry = /(?:^|[\s,{])(["']?)([A-Za-z_$][\w$]*)\1\s*[:=]\s*(["'`])((?:\\.|(?!\3)[^\\\n])*)\3/g;
+  // A template that only splices string literals, `a_${"b"}`, is the same string at runtime.
+  const literal = (value) => value.replace(/\$\{\s*(["'])((?:(?!\1).)*)\1\s*\}/g, "$2");
+  for (const match of body.matchAll(entry)) keys.set(match[2], literal(match[4]));
+  return keys;
+}
+
+/** Keys present before and after whose string changed. Adding or deleting a key isn't a change of value. */
+export function changedStorageValues(before, after) {
+  const was = storageKeysOf(before);
+  const now = storageKeysOf(after);
+  return [...was].flatMap(([name, value]) =>
+    now.has(name) && now.get(name) !== value ? [{ name, was: value, now: now.get(name) }] : [],
+  );
+}
+
+export function report(storage) {
+  const out = [];
+  for (const { file, name, was, now } of storage)
+    out.push(`${file}: StorageKey.${name} was "${was}" and is now "${now}"`);
+  if (storage.length > 0)
+    out.push(
+      "\nThose strings are live in users' Apps Script properties, and changing one orphans their data. Put each back to its old value; the name on the left is free to change.",
+    );
+  return out.join("\n");
+}

package/register.d.ts

@@ -0,0 +1,43 @@
+export type RegisterName = "spoken" | "shorts" | "written";
+
+export type RegisterMeasurement = {
+  words: number;
+  sentences: number;
+  meanSentence: number;
+  medianSentence: number;
+  /** Percent of sentences of 4 words or fewer. He does not fragment out loud. */
+  fragmentShare: number;
+  /** The same as a count. A single fragment never fails the band, however short the text. */
+  fragments: number;
+  /** Percent of sentences of 20 words or more. */
+  longShare: number;
+  /** Sentence-length spread, SD over mean. His floor is 0.34, machine prose sits near 0.1. */
+  lengthVariation: number;
+  contractions: number;
+  secondPerson: number;
+  firstPerson: number;
+  /** `and`, `so`, `because`, `but` per 1,000. He chains, he does not stack. */
+  chaining: number;
+  /** Second person for every first person. `Infinity` when there is no first person. */
+  egoRatio: number;
+};
+
+export type RegisterAudit = {
+  register: RegisterName;
+  label: string;
+  /** The corpus the band was counted from. */
+  source: string;
+  measured: RegisterMeasurement;
+  findings: { kind: "register"; id: string; detail: string }[];
+};
+
+/** Counts only, no judgement. The bands in `REGISTERS` are recounted from this. */
+export declare function measureRegister(text: string): RegisterMeasurement;
+
+export declare const REGISTERS: Record<
+  RegisterName,
+  { label: string; source: string; bands: Record<string, { min?: number; max?: number }> }
+>;
+
+/** Measure, then score against one band set. Findings merge into a prose audit. */
+export declare function auditRegister(text: string, register?: RegisterName): RegisterAudit;