@heyramzi/lint 0.0.0-stage → 1.32.4

package/register.js

@@ -0,0 +1,255 @@
+/**
+ * The register gate: does this draft carry the rates of the voice it claims?
+ */
+
+/*
+ * `auditSlop` is a ban list, and a ban list cannot see the failure that produced the September 2026 Shorts batch.
+ */
+
+/*
+ * Every one of those scripts passed the word checks and still read as somebody else, because the fault is not a word.
+ */
+
+/*
+ * It is four rates: how often he contracts, how long his sentences run, how many fragments he leaves, and how often he says "you".
+ */
+
+/*
+ * Written copy and spoken copy sit in different places on all four, and a spoken script written to the written numbers is the stilted result.
+ */
+
+/*
+ * Bands are counted, never typed. `scripts/measure-register.mjs` recounts them from the corpora named in each band's `source`, and the corpora are the ones humanizer `references/voice-measured.md` records.
+ */
+
+const SENTENCE_SPLIT = /[.!?]+["'”’)]*(?:\s+|$)/;
+const CONTRACTION = /\b[\w]+['’](?:s|t|re|ve|ll|d|m)\b/gi;
+const SECOND_PERSON = /\b(?:you|your|yours|you're|you've|you'll|you'd|yourself)\b/gi;
+const FIRST_PERSON = /\b(?:i|me|my|mine|myself|i'm|i've|i'll|i'd)\b/gi;
+const CHAINING = /\b(?:and|so|because|but)\b/gi;
+
+/** Counts only. No judgement, so a caller can report without a band. */
+export function measureRegister(text) {
+  const sentences = text
+    .split(SENTENCE_SPLIT)
+    .map((s) => s.trim())
+    .filter(Boolean);
+  const lengths = sentences.map((s) => s.split(/\s+/).filter(Boolean).length);
+  const words = lengths.reduce((a, b) => a + b, 0);
+  const per1k = (n) => (words === 0 ? 0 : (n / words) * 1000);
+  const count = (re) => (text.match(re) ?? []).length;
+  const share = (fn) =>
+    lengths.length === 0 ? 0 : (lengths.filter(fn).length / lengths.length) * 100;
+
+  return {
+    words,
+    sentences: lengths.length,
+    meanSentence: lengths.length === 0 ? 0 : words / lengths.length,
+    medianSentence: median(lengths),
+    fragmentShare: share((n) => n <= 4),
+    fragments: lengths.filter((n) => n <= 4).length,
+    longShare: share((n) => n >= 20),
+    // Per line too, because a list item ends without a full stop.
+    longestSentence: Math.max(0, ...lines(text).map((s) => s.split(/\s+/).length)),
+    mostCommas: Math.max(0, ...lines(text).map((s) => (s.match(/[,;]/g) ?? []).length)),
+    // The metronome: spread of sentence length, which separates him from a model
+    // where the mean does not. Counts and the rejected run rule are in humanizer
+    // `references/registers.md`, "The sixth rate".
+    lengthVariation: variation(lengths),
+    contractions: per1k(count(CONTRACTION)),
+    secondPerson: per1k(count(SECOND_PERSON)),
+    firstPerson: per1k(count(FIRST_PERSON)),
+    chaining: per1k(count(CHAINING)),
+    // "Every I should be a you." Second person over first, 5.25:1 across the four Shorts cut on 20 Aug 2026 against 1.38:1 in the written corpus,
+
+    // so the rule is short-form only. A raw take fails it at about 1.0 and is meant to: the ratio is what `descript-script-edit` produces, not what the mouth does.
+
+    // 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),
+  };
+}
+
+function lines(text) {
+  return text
+    .split(/\n+/)
+    .flatMap((l) => l.split(SENTENCE_SPLIT))
+    .map((s) => s.trim())
+    .filter(Boolean);
+}
+
+/** Standard deviation over the mean, so a long register and a short one compare. */
+function variation(xs) {
+  if (xs.length < 2) return 0;
+  const mean = xs.reduce((a, b) => a + b, 0) / xs.length;
+  if (mean === 0) return 0;
+  const spread = xs.reduce((a, b) => a + (b - mean) ** 2, 0) / xs.length;
+  return Math.sqrt(spread) / mean;
+}
+
+function median(xs) {
+  if (xs.length === 0) return 0;
+  const s = [...xs].toSorted((a, b) => a - b);
+  const mid = Math.floor(s.length / 2);
+  return s.length % 2 === 0 ? (s[mid - 1] + s[mid]) / 2 : s[mid];
+}
+
+/**
+ * The bands. `min`/`max` are inclusive; a missing bound is not checked.
+ */
+
+/*
+ * Every number is the corpus figure with a tolerance, not a target invented here.
+ */
+
+/*
+ * The `shorts` band is the one that matters for a batch: he leaves no fragments out loud, and 0% is the counted figure on EC49,
+ */
+
+/*
+ * so the band allows a little and not the 35% the rejected batch carried.
+ */
+export const REGISTERS = {
+  spoken: {
+    label: "spoken long-form",
+    source: "9 YouTube transcripts, 44,398 words",
+    bands: {
+      meanSentence: { min: 16, max: 34 },
+      fragmentShare: { max: 12 },
+      lengthVariation: { min: 0.3 },
+      contractions: { min: 26 },
+      secondPerson: { min: 28 },
+      chaining: { min: 45 },
+    },
+  },
+  shorts: {
+    label: "spoken short-form",
+    source: "his 4 Shorts, 680 words, plus EC49",
+    bands: {
+      meanSentence: { min: 13, max: 26 },
+      fragmentShare: { max: 10 },
+      // A floor clears his own lowest single Short, never the 4-file average: 19.5 contractions on one file and 31.4 chaining on another.
+
+      // A floor his own speech fails is a band tightened past him, which is the fault this module exists to prevent. Asserted per file in register.test.mjs.
+      contractions: { min: 18 },
+      secondPerson: { min: 30 },
+      egoRatio: { min: 2, max: 3.5 },
+      // Ceilings from the top band of 134 competitor Shorts (p75: 60 chaining, 3.5 ego). His own max is 53 and 1.6; A20 ran 70 and 6.5.
+      chaining: { min: 30, max: 60 },
+      lengthVariation: { min: 0.3 },
+    },
+  },
+  /**
+   * Two voices in the room.
+   */
+
+  /*
+   * Counted 2026-09-14 over 303,956 words of his own turns on 100 English client calls, restricted per file to uninterrupted stretches of 120 words or more so the transcriber's turn-splitting cannot
+   */
+
+  /*
+   * manufacture fragments.
+   */
+
+  /*
+   * Every floor clears his own lowest call of 41, never the median: meanSentence ran 9.7 to 23.9, fragmentShare 1.8 to 33.3, contractions 29.0 to 66.7, chaining 53.6 to 77.7.
+   */
+
+  /*
+   * `spoken` would reject him here. Its band wants 16 to 34 words a sentence and under 12% fragments; live he is at 13.5 and 19.5%.
+   */
+
+  /*
+   * A podcast, an interview or a sales-call script graded as `spoken` fails on his real speech, which is the fault this module exists to prevent.
+   */
+
+  /*
+   * No egoRatio floor, deliberately.
+   */
+
+  /*
+   * It runs 0.3 to 4.2 across the 41 calls, median 1.1: he says "I" about as often as "you" when a person is in front of him.
+   */
+
+  /*
+   * The "every I is a you" rule is a camera rule. `secondPerson` is a loose floor for the same reason.
+   */
+  dialogue: {
+    label: "spoken dialogue",
+    source: "100 English client calls, his turns, 303,956 words",
+    bands: {
+      meanSentence: { min: 9, max: 24 },
+      fragmentShare: { max: 35 },
+      contractions: { min: 26 },
+      secondPerson: { min: 10 },
+      chaining: { min: 45 },
+      lengthVariation: { min: 0.3 },
+    },
+  },
+  written: {
+    label: "written social",
+    source: "40 LinkedIn and 150 X posts",
+    bands: {
+      meanSentence: { min: 5, max: 15 },
+      contractions: { min: 14 },
+      lengthVariation: { min: 0.3 },
+      // Ramzi, 23 Sep 2026, on a 33-word, 3-comma course line: "too long, too many commas".
+      longestSentence: { max: 25 },
+      mostCommas: { max: 2 },
+    },
+  },
+};
+
+const DIRECTION = {
+  meanSentence: "words per sentence",
+  lengthVariation: "spread of sentence length, SD over mean",
+  fragmentShare: "% of sentences of 4 words or fewer",
+  longShare: "% of sentences of 20 words or more",
+  longestSentence: "words in the longest sentence",
+  mostCommas: "commas and semicolons in the busiest sentence",
+  contractions: "contractions per 1,000 words",
+  secondPerson: "you/your per 1,000 words",
+  firstPerson: "I/me/my per 1,000 words",
+  egoRatio: "second person for every first person",
+  chaining: "and/so/because/but per 1,000 words",
+};
+
+/**
+ * Measure, then score against one band set.
+ *
+ * Findings carry the same shape `auditSlop` returns, so a caller merges the
+ * two lists and a hook fails on either.
+ */
+export function auditRegister(text, register = "spoken") {
+  const spec = REGISTERS[register];
+  if (!spec)
+    throw new Error(
+      `unknown register "${register}", expected ${Object.keys(REGISTERS).join(", ")}`,
+    );
+  const measured = measureRegister(text);
+  const findings = [];
+
+  for (const [key, band] of Object.entries(spec.bands)) {
+    const value = measured[key];
+    // A share is noise on a short text.
+
+    // His own Shorts corpus leaves roughly one fragment every 19 sentences, so a 9-sentence script that leaves one sits at 11% and is not a cadence fault. Two is.
+
+    // Only the count settles it.
+    if (key === "fragmentShare" && measured.fragments <= 1) continue;
+    // A spread over 7 sentences is noise: one long line carries it. His own floor
+    // of 0.34 was counted over the 46 documents that reach 8.
+    if (key === "lengthVariation" && measured.sentences < 8) continue;
+    const low = band.min !== undefined && value < band.min;
+    const high = band.max !== undefined && value > band.max;
+    if (!low && !high) continue;
+    const want = low ? `at least ${band.min}` : `at most ${band.max}`;
+    const shown = Number.isFinite(value) ? value.toFixed(1) : "no first person";
+    findings.push({
+      kind: "register",
+      id: key,
+      detail: `${shown} ${DIRECTION[key]}, ${spec.label} wants ${want}`,
+    });
+  }
+
+  return { register, label: spec.label, source: spec.source, measured, findings };
+}

package/repo-rules/packages.js

@@ -0,0 +1,164 @@
+/** Package manager, @heyramzi dependency and registry credential rules. */
+
+const FOREIGN_LOCK = /(^|\/)(package-lock\.json|npm-shrinkwrap\.json|yarn\.lock|bun\.lockb?)$/;
+const MANIFEST = /(^|\/)package\.json$/;
+const LOCAL_SPEC = /^(link|file|portal):|^\.{1,2}\/|^\//;
+const BUCKETS = [
+  "dependencies",
+  "devDependencies",
+  "peerDependencies",
+  "optionalDependencies",
+  "overrides",
+  "resolutions",
+];
+
+export function pnpmOnly(tree) {
+  return tree.touchedMatching(FOREIGN_LOCK).map((file) => ({
+    file,
+    rule: "pnpm-only",
+    message: `Studio uses pnpm only, and ${file} is another package manager's lockfile. Delete it, run pnpm install so pnpm-lock.yaml is the one lockfile, and write pnpm in scripts and docs.`,
+  }));
+}
+
+function heyramziSpecs(manifest) {
+  const specs = [];
+  for (const bucket of [...BUCKETS.map((key) => manifest[key]), manifest.pnpm?.overrides]) {
+    for (const [name, spec] of Object.entries(bucket ?? {})) {
+      if (name.startsWith("@heyramzi/") && typeof spec === "string") specs.push([name, spec]);
+    }
+  }
+  return specs;
+}
+
+const LINK_MESSAGE = (name, spec) =>
+  `${name} is "${spec}". A @heyramzi/* dependency is always a published semver range like ^0.4.0, never link:, file: or a path. A link breaks every build container with no sibling vibe-kit checkout. If the export isn't published yet, bump the version in vibe-kit/packages/<pkg>/package.json, publish, then move this range. Don't swap the protocol to fix a version mismatch.`;
+
+export function heyramziLinks(tree) {
+  const found = [];
+  for (const file of tree.touchedMatching(MANIFEST)) {
+    const manifest = tree.json(file);
+    if (!manifest) continue;
+    for (const [name, spec] of heyramziSpecs(manifest)) {
+      if (LOCAL_SPEC.test(spec)) {
+        found.push({ file, rule: "heyramzi-link", message: LINK_MESSAGE(name, spec) });
+      }
+    }
+  }
+  for (const file of tree.touchedMatching(/(^|\/)pnpm-workspace\.yaml$/)) {
+    for (const line of tree.text(file).split("\n")) {
+      const match = /^\s*['"]?(@heyramzi\/[^'":\s]+)['"]?\s*:\s*['"]?((link|file|portal):\S*)/.exec(
+        line,
+      );
+      if (match) {
+        found.push({ file, rule: "heyramzi-link", message: LINK_MESSAGE(match[1], match[2]) });
+      }
+    }
+  }
+  return found;
+}
+
+const LOCK_ENTRY = /^ {2}'?(@heyramzi\/[^@']+)@([^'(:]+)'?:\s*$/;
+
+export function heyramziTarballs(tree) {
+  const found = [];
+  for (const file of tree.touchedMatching(/(^|\/)pnpm-lock\.yaml$/)) {
+    const lines = tree.text(file).split("\n");
+    lines.forEach((line, index) => {
+      const entry = LOCK_ENTRY.exec(line);
+      const resolution = lines[index + 1] ?? "";
+      if (!entry || !/^ {4}resolution:/.test(resolution)) return;
+      if (!resolution.includes("integrity:") || resolution.includes("tarball:")) return;
+      found.push({
+        file,
+        rule: "heyramzi-tarball",
+        message: `Line ${index + 2}: ${entry[1]}@${entry[2]} has integrity and no tarball URL. Without it pnpm install --frozen-lockfile builds a canonical URL that GitHub Packages redirects to registry.npmjs.com with the scope stripped, which 404s or installs a public package that shares the bare name. Append ", tarball: <url>" to that resolution, where the URL is versions["${entry[2]}"].dist.tarball from https://npm.pkg.github.com/@heyramzi%2f<name>. Any pnpm install, update or advisory patch strips these, so re-check after every dependency change.`,
+      });
+    });
+  }
+  return found;
+}
+
+const SRC_KEY = /^#src(\/|$)/;
+
+/** Entry points that land in dist. `files` listing dist doesn't count: a package can ship it and export src. */
+function shipsDist(manifest) {
+  return JSON.stringify(manifest.exports ?? {}).includes('"./dist/');
+}
+
+/** A bundler resolves #src into the output, and relative-imports.mjs rewrites it before publish. */
+function resolvesItself(manifest, dir, tree) {
+  return (
+    /\b(vp (build|pack)|tsdown|tsup|vite build|rolldown|esbuild|relative-imports)\b/.test(
+      manifest.scripts?.build ?? "",
+    ) || tree.isTracked(`${dir}scripts/relative-imports.mjs`)
+  );
+}
+
+export function srcImportMaps(tree) {
+  const found = [];
+  for (const file of tree.touchedMatching(MANIFEST)) {
+    const manifest = tree.json(file);
+    const keys = Object.keys(manifest?.imports ?? {}).filter((key) => SRC_KEY.test(key));
+    if (!manifest?.name?.startsWith("@heyramzi/") || keys.length === 0) continue;
+    if (manifest.private || !manifest.publishConfig) continue;
+    const dir = file.slice(0, file.length - "package.json".length);
+    if (resolvesItself(manifest, dir, tree)) continue;
+    const fail = (message) => found.push({ file, rule: "src-import-map", message });
+    if (shipsDist(manifest)) {
+      const map = manifest.imports["#src/*"];
+      if (typeof map?.types !== "string" || typeof map?.default !== "string") {
+        fail(
+          `${manifest.name} ships dist, so imports needs "#src/*": { "types": "./src/*", "default": "./dist/*" }. A string mapping to ./src makes the dist build emit #src specifiers that point at TypeScript the consumer can't run. tsc keeps the source, Node and every bundler land in dist.`,
+        );
+      }
+      continue;
+    }
+    const hasTs = tree.trackedMatching(/\.tsx?$/).some((path) => path.startsWith(`${dir}src/`));
+    if (hasTs && !String(manifest.imports["#src/*.js"]).endsWith("/*.ts")) {
+      fail(
+        `${manifest.name} ships src, so imports needs "#src/*.js": "./src/*.ts" and every #src import ends in .js. Apps compile the source: a bare path fails TypeScript, and a .js mapped to ./src/*.js fails Vite, which never swaps the extension. Or ship dist with a { types, default } mapping.`,
+      );
+    }
+  }
+  return found;
+}
+
+export function npmrcCredentials(tree) {
+  const found = [];
+  for (const file of tree.touchedMatching(/(^|\/)\.npmrc$/)) {
+    tree
+      .text(file)
+      .split("\n")
+      .forEach((line, index) => {
+        if (/^\s*[#;]/.test(line) || !line.includes("_authToken")) return;
+        found.push({
+          file,
+          rule: "npmrc-token",
+          message: `Line ${index + 1} sets an _authToken in a committed .npmrc. pnpm 11 ignores registry credentials in a project .npmrc, so the line does nothing and risks leaking. Keep the registry line and a WHY comment only. The token lives in the user-level ~/.npmrc, and CI gets it from the runner.`,
+        });
+      });
+  }
+  return found;
+}
+
+const LEGACY_TOKEN = ["GITHUB", "PRIVATE", "PACKAGES", "TOKEN"].join("_");
+const INSTALL_FILES =
+  /(^|\/)(\.npmrc|\.env[^/]*|Dockerfile[^/]*|(docker-)?compose[^/]*\.ya?ml|wrangler\.jsonc?|[^/]+\.sh|\.github\/workflows\/[^/]+\.ya?ml)$/;
+
+export function legacyTokenName(tree) {
+  const found = [];
+  for (const file of tree.touchedMatching(INSTALL_FILES)) {
+    tree
+      .text(file)
+      .split("\n")
+      .forEach((line, index) => {
+        if (!line.includes(LEGACY_TOKEN)) return;
+        found.push({
+          file,
+          rule: "legacy-token-name",
+          message: `Line ${index + 1} names ${LEGACY_TOKEN}, a dead variable that 403s against the package registry. The package-install token is GH_PRIVATE_PACKAGES_TOKEN everywhere: .npmrc, workflow env, the shell. Leave secrets.GITHUB_TOKEN alone, it's the Actions built-in that release-please, GoReleaser and gh need.`,
+        });
+      });
+  }
+  return found;
+}

package/repo-rules/paths.js

@@ -0,0 +1,101 @@
+/** Compose image tags and fossil file names. */
+
+import { yamlCode } from "#lint/repo-rules/tree.js";
+
+const COMPOSE = /(^|\/)(docker-)?compose([.-][\w.-]*)?\.ya?ml$/;
+
+function tagOf(image) {
+  if (image.includes("@sha256:")) return "digest";
+  const name = image.slice(image.lastIndexOf("/") + 1);
+  const colon = name.indexOf(":");
+  return colon === -1 ? null : name.slice(colon + 1);
+}
+
+function services(lines) {
+  const found = [];
+  let inServices = false;
+  let serviceIndent = null;
+  let current = null;
+  lines.forEach((raw, index) => {
+    const line = yamlCode(raw);
+    if (!line.trim()) return;
+    const indent = line.length - line.trimStart().length;
+    if (indent === 0) {
+      inServices = /^services\s*:/.test(line);
+      serviceIndent = null;
+      current = null;
+      return;
+    }
+    if (!inServices) return;
+    serviceIndent ??= indent;
+    if (indent === serviceIndent) {
+      current = { name: line.trim().replace(/:.*$/, ""), build: false, image: null, line: 0 };
+      found.push(current);
+    } else if (current && indent > serviceIndent) {
+      const trimmed = line.trim();
+      if (/^build\s*:/.test(trimmed)) current.build = true;
+      const image = /^image\s*:\s*(.+)$/.exec(trimmed);
+      if (image) {
+        current.image = image[1].trim().replace(/^["']|["']$/g, "");
+        current.line = index + 1;
+      }
+    }
+  });
+  return found;
+}
+
+export function composeImages(tree) {
+  const found = [];
+  for (const file of tree.touchedMatching(COMPOSE)) {
+    for (const service of services(tree.text(file).split("\n"))) {
+      if (!service.image) continue;
+      const tag = tagOf(service.image);
+      const floating =
+        tag?.includes("latest") ||
+        (tag === null && !service.build && !service.image.includes("${"));
+      if (!floating) continue;
+      found.push({
+        file,
+        rule: "compose-image-tag",
+        message: `Line ${service.line}: ${service.name} uses image ${service.image}, which floats. Pin an exact version tag (traefik v3.7.14, postgres 18.6-trixie), and pin Postgres to the distro base it already runs. A stale local latest masked a real gap once and can't be rolled back.`,
+      });
+    }
+  }
+  return found;
+}
+
+const FOSSIL_STEM = /(-old|-v2|-final| copy( \d+)?)$/;
+const GRAB_BAG = new Set(["misc", "temp"]);
+const GENERATED =
+  /(^|\/)(node_modules|\.upstream|vendor|dist|build|\.svelte-kit|\.agents|\.claude|\.codex|\.gemini|\.opencode)\/|^\.github\/skills\//;
+
+/** The stem of a file name: `report-old.test.ts` is `report-old`, `v2.final.md` is `v2.final`. */
+function stemOf(name) {
+  const dot = name.indexOf(".", 1);
+  return dot === -1 ? name : name.slice(0, dot);
+}
+
+export function fossilNames(tree) {
+  const found = [];
+  for (const file of tree.added) {
+    if (GENERATED.test(file)) continue;
+    const parts = file.split("/");
+    const grabBag = parts.slice(0, -1).find((part) => GRAB_BAG.has(part));
+    if (grabBag) {
+      found.push({
+        file,
+        rule: "fossil-name",
+        message: `${grabBag}/ is a folder named for having no category. Put the file in the folder of what it does.`,
+      });
+    }
+    const stem = stemOf(parts.at(-1));
+    if (FOSSIL_STEM.test(stem)) {
+      found.push({
+        file,
+        rule: "fossil-name",
+        message: `${parts.at(-1)} reads as a copy of a file already in use (-old, -v2, -final, copy). Edit the real file and let git keep the history, or name this one for what it does differently.`,
+      });
+    }
+  }
+  return found;
+}