@heyramzi/lint 0.0.0-stage → 1.32.2

package/comment-length.js

@@ -0,0 +1,368 @@
+/**
+ * The 30-word comment cap: a comment that outgrows its explanation stops being
+ * read. The rule is `ai-doc/references/agents-core.md`.
+ *
+ * Pure here, git and process in `bin/heyramzi-comment-length.js`.
+ */
+
+/** Ramzi, 4 Sep 2026: "Maximum should be something like 30 words." */
+export const MAX_WORDS = 30;
+
+export const JS_EXTENSIONS = ["ts", "tsx", "js", "jsx", "mjs", "cjs", "svelte"];
+
+export const DEFAULT_EXTENSIONS = [
+  ...JS_EXTENSIONS,
+  "swift",
+  "py",
+  "sh",
+  "bash",
+  "zsh",
+  "css",
+  "sql",
+];
+
+/**
+ * Comment syntax for the languages the JS scanner can't read. Backslash escapes, quotes that span
+ * lines, and the shell's heredocs and word-start `#` are the traps that make each differ.
+ */
+const SYNTAX = {
+  swift: {
+    lead: "//",
+    block: true,
+    nested: true,
+    quotes: ['"'],
+    triple: ['"""'],
+    raw: true,
+    escapes: true,
+  },
+  py: { lead: "#", quotes: ["'", '"'], triple: ["'''", '"""'], escapes: true },
+  sh: {
+    lead: "#",
+    wordStart: true,
+    quotes: ["'", '"'],
+    multiline: true,
+    heredoc: true,
+    rawSingle: true,
+    escapes: true,
+  },
+  css: { block: true, quotes: ['"', "'"], url: true, escapes: true },
+  sql: { lead: "--", block: true, quotes: ["'", '"'], multiline: true },
+};
+const SYNTAX_ALIAS = { bash: "sh", zsh: "sh" };
+const syntaxOf = (extension) => SYNTAX[SYNTAX_ALIAS[extension] ?? extension];
+
+/** Generated or vendored trees: nobody can shorten a comment they do not write. */
+export const DEFAULT_IGNORED = [
+  "node_modules",
+  "dist",
+  "build",
+  "out",
+  "coverage",
+  "vendor",
+  ".upstream",
+  "generated",
+  "_generated",
+  "paraglide",
+  ".svelte-kit",
+  ".wrangler",
+  ".vercel",
+];
+
+function words(text) {
+  return text.trim().split(/\s+/).filter(Boolean).length;
+}
+
+/**
+ * Every comment in a file, as spans, from a scanner that tracks its state. A
+ * comment opener inside a string is code: one `import.meta.glob` swallowed
+ * 313 words.
+ */
+// Quotes are looked for only in code, so an apostrophe in a comment stays
+// prose, and a markup quote closes at its line end.
+export function commentSpans(src) {
+  const spans = [];
+  let i = 0;
+  while (i < src.length) {
+    const two = src.slice(i, i + 2);
+    // Outside strings a backslash only escapes inside a regex literal, so `/\/*$/` never opens a comment.
+    if (src[i] === "\\") {
+      i += 2;
+      continue;
+    }
+    if (two === "//") {
+      const end = src.indexOf("\n", i);
+      const stop = end === -1 ? src.length : end;
+      spans.push({ kind: "line", start: i, end: stop });
+      i = stop;
+    } else if (two === "/*") {
+      const close = src.indexOf("*/", i + 2);
+      const stop = close === -1 ? src.length : close + 2;
+      spans.push({ kind: "block", start: i, end: stop });
+      i = stop;
+    } else if (src.startsWith("<!--", i)) {
+      const close = src.indexOf("-->", i + 4);
+      const stop = close === -1 ? src.length : close + 3;
+      spans.push({ kind: "html", start: i, end: stop });
+      i = stop;
+    } else if (src[i] === "/" && regexStarts(src, i)) {
+      i = regexEnd(src, i);
+    } else if (src[i] === '"' || src[i] === "'" || src[i] === "`") {
+      const quote = src[i];
+      let j = i + 1;
+      while (j < src.length) {
+        if (src[j] === "\\") {
+          j += 2;
+          continue;
+        }
+        if (src[j] === quote) {
+          j += 1;
+          break;
+        }
+        if (src[j] === "\n" && quote !== "`") {
+          break;
+        }
+        j += 1;
+      }
+      i = j;
+    } else {
+      i += 1;
+    }
+  }
+  return mergeRuns(src, spans);
+}
+
+/**
+ * Consecutive line comments read as one comment: a run that outgrows its point
+ * is what this gate is for. A blank line ends a run.
+ */
+function mergeRuns(src, spans) {
+  const merged = [];
+  for (const span of spans) {
+    const last = merged[merged.length - 1];
+    const gap = last ? src.slice(last.end, span.start) : "";
+    const adjacent = last && !gap.trim() && (gap.match(/\n/g) || []).length === 1;
+    if (adjacent && last.kind === "line" && span.kind === "line") {
+      last.end = span.end;
+      continue;
+    }
+    merged.push({ ...span });
+  }
+  return merged;
+}
+
+/** The comments of a file in `extension`'s language, as spans. */
+export function commentSpansFor(src, extension) {
+  const syntax = syntaxOf(extension);
+  return syntax ? simpleSpans(src, syntax) : commentSpans(src);
+}
+
+function skipString(src, i, syntax) {
+  const quote = src[i];
+  const triple = syntax.triple?.find((t) => src.startsWith(t, i));
+  const escapes = syntax.escapes && !(syntax.rawSingle && quote === "'" && src[i - 1] !== "$");
+  let j = i + (triple ? 3 : 1);
+  while (j < src.length) {
+    if (escapes && src[j] === "\\") {
+      j += 2;
+    } else if (triple ? src.startsWith(triple, j) : src[j] === quote) {
+      return j + (triple ? 3 : 1);
+    } else if (src[j] === "\n" && !triple && !syntax.multiline) {
+      return j;
+    } else {
+      j += 1;
+    }
+  }
+  return j;
+}
+
+/** Swift `#"..."#`, with as many hashes as it opens with. Null when the `#` isn't a raw string. */
+function rawStringEnd(src, i) {
+  let hashes = 0;
+  while (src[i + hashes] === "#") hashes += 1;
+  if (src[i + hashes] !== '"') return null;
+  const close = (src.startsWith('"""', i + hashes) ? '"""' : '"') + "#".repeat(hashes);
+  const end = src.indexOf(close, i + hashes + 1);
+  return end === -1 ? src.length : end + close.length;
+}
+
+const HEREDOC = /^<<(-?)\s*(?:'([^']+)'|"([^"]+)"|\\?([A-Za-z_]\w*))/;
+
+/** Past the bodies of the heredocs opened on the line that just ended at `i`. */
+function skipHeredocs(src, i, pending) {
+  let j = i;
+  for (const { tag, dash } of pending) {
+    while (j < src.length) {
+      const next = src.indexOf("\n", j + 1);
+      const stop = next === -1 ? src.length : next;
+      const line = src.slice(j + 1, stop);
+      j = stop;
+      if ((dash ? line.replace(/^\t+/, "") : line) === tag) break;
+    }
+  }
+  return j;
+}
+
+function simpleSpans(src, syntax) {
+  const spans = [];
+  const pending = [];
+  let i = 0;
+  while (i < src.length) {
+    const c = src[i];
+    if (c === "\n" && pending.length) {
+      i = skipHeredocs(src, i, pending.splice(0));
+    } else if (c === "\\" && syntax.escapes) {
+      i += 2;
+    } else if (
+      syntax.lead &&
+      src.startsWith(syntax.lead, i) &&
+      (!syntax.wordStart || i === 0 || /[\s;&|(]/.test(src[i - 1]))
+    ) {
+      const end = src.indexOf("\n", i);
+      const stop = end === -1 ? src.length : end;
+      spans.push({ kind: "line", lead: syntax.lead, start: i, end: stop });
+      i = stop;
+    } else if (syntax.block && src.startsWith("/*", i)) {
+      let depth = 1;
+      let j = i + 2;
+      while (j < src.length && depth > 0) {
+        if (syntax.nested && src.startsWith("/*", j)) {
+          depth += 1;
+          j += 2;
+        } else if (src.startsWith("*/", j)) {
+          depth -= 1;
+          j += 2;
+        } else {
+          j += 1;
+        }
+      }
+      spans.push({ kind: "block", start: i, end: j });
+      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))) {
+      const close = src.indexOf(")", i);
+      i = close === -1 ? src.length : close + 1;
+    } else if (syntax.quotes.includes(c)) {
+      i = skipString(src, i, syntax);
+    } else {
+      // `<<<` is a here-string, and its 2nd and 3rd `<` must not read as a heredoc opener.
+      const opener =
+        syntax.heredoc && src.startsWith("<<", i) && src[i - 1] !== "<" && src[i + 2] !== "<";
+      const heredoc = opener ? HEREDOC.exec(src.slice(i, i + 80)) : null;
+      if (heredoc)
+        pending.push({ dash: heredoc[1] === "-", tag: heredoc[2] ?? heredoc[3] ?? heredoc[4] });
+      i += heredoc ? heredoc[0].length : 1;
+    }
+  }
+  return mergeRuns(src, spans);
+}
+
+const REGEX_AFTER = new Set("(,=:[!&|?{};+-*%<>~^");
+const REGEX_KEYWORD = /\b(?:return|typeof|case|in|of|delete|void|throw|new|else|do|yield|await)$/;
+
+/** A `/` opens a regex after an operator or keyword, never after a value, so `a / b` stays division. */
+function regexStarts(src, i) {
+  const before = src.slice(0, i).trimEnd();
+  return before === "" || REGEX_AFTER.has(before[before.length - 1]) || REGEX_KEYWORD.test(before);
+}
+
+/** Where a regex literal ends, flags included. A newline first means it was division after all. */
+function regexEnd(src, i) {
+  let j = i + 1;
+  let inClass = false;
+  while (j < src.length) {
+    const c = src[j];
+    if (c === "\\") j += 2;
+    else if (c === "\n") return i + 1;
+    else if (c === "[") {
+      inClass = true;
+      j += 1;
+    } else if (c === "]") {
+      inClass = false;
+      j += 1;
+    } else if (c === "/" && !inClass) break;
+    else j += 1;
+  }
+  j += 1;
+  while (j < src.length && /[a-z]/i.test(src[j])) j += 1;
+  return j;
+}
+
+/** A span's prose, with the comment punctuation taken off. */
+export function spanText(src, span) {
+  const raw = src.slice(span.start, span.end);
+  if (span.kind === "block") return raw.replace(/^\/\*+|\*+\/$/g, "").replace(/^[ \t]*\*/gm, "");
+  if (span.kind === "html") return raw.replace(/^<!--|-->$/g, "");
+  const lead = (span.lead ?? "//").replace(/[^\w\s]/g, "\\$&");
+  return raw.replace(new RegExp(`^[ \\t]*${lead}+\\s?`, "gm"), "");
+}
+
+/** The longest comment in a file, in words. Zero when the file has none. */
+export function maxCommentWords(source, extension = "ts") {
+  let longest = 0;
+  for (const span of commentSpansFor(source, extension)) {
+    longest = Math.max(longest, words(spanText(source, span)));
+  }
+  return longest;
+}
+
+/**
+ * Words that mark a hack left in place, which agents copy along with the hack.
+ * The tags match uppercase only, so "hack" in a sentence stays prose.
+ */
+export const MARKERS = [
+  { label: "a TODO, FIXME or HACK tag", test: /\b(?:TODO|FIXME|HACK)\b/ },
+  { label: '"for now"', test: /\bfor now\b/i },
+  {
+    label: "a temporary fix",
+    test: /\btemporar(?:y|ily)\s+(?:fix|workaround|hack|patch|solution)\b/i,
+  },
+  { label: "backward compatibility", test: /\bbackwards?[\s-]*compat/i },
+  {
+    label: "a legacy name or path",
+    test: /\blegacy\s+(?:alias|synonym|shim|wrapper|fallback|export|import|path|name|field|support|code|compat)\b/i,
+  },
+  { label: "a @deprecated tag", test: /@deprecated\b/ },
+];
+
+/** Every marker in a file's comments, with its line. A backticked span is a quote, never a marker. */
+export function markerHits(source, extension = "ts") {
+  const hits = [];
+  // The markers are a TS, JS and Svelte rule; the other languages only carry the length cap.
+  if (!JS_EXTENSIONS.includes(extension)) return hits;
+  for (const span of commentSpans(source)) {
+    const text = spanText(source, span).replace(/`[^`\n]*`/g, "");
+    const marker = MARKERS.find((m) => m.test.test(text));
+    if (!marker) continue;
+    const line = source.slice(0, span.start).split("\n").length;
+    hits.push({ line, label: marker.label });
+  }
+  return hits;
+}
+
+/** A hard cap: every file whose longest comment runs over `max` words fails. */
+export function check(lengths, max = MAX_WORDS) {
+  const failures = [];
+  for (const [file, count] of Object.entries(lengths)) {
+    if (count > max) failures.push({ file, words: count });
+  }
+  return failures.toSorted((a, b) => b.words - a.words);
+}
+
+/** Which of a repo's tracked files the gate reads. `targets` empty means all. */
+export function selectFiles(
+  tracked,
+  { targets = [], extensions = DEFAULT_EXTENSIONS, ignored = DEFAULT_IGNORED } = {},
+) {
+  const wanted = new Set(extensions.map((ext) => ext.replace(/^\./, "")));
+  return tracked.filter((file) => {
+    const ext = file.slice(file.lastIndexOf(".") + 1);
+    if (!wanted.has(ext)) return false;
+    if (file.endsWith(".min.js") || file.endsWith(".min.css")) return false;
+    if (file.split("/").some((segment) => ignored.includes(segment))) return false;
+    if (targets.length === 0) return true;
+    return targets.some(
+      (target) => file === target || file.startsWith(`${target.replace(/\/$/, "")}/`),
+    );
+  });
+}

package/commit-msg.js

@@ -0,0 +1,57 @@
+/**
+ * The commit-message gate: no em or en dash, Conventional Commits and no "!" or BREAKING CHANGE
+ * where versions come from commit types. Pure here, git in `bin/heyramzi-commit-msg.js`.
+ */
+
+const DASH = new RegExp("[\\u2013\\u2014]");
+const SCISSORS = /^# -{24} >8 -{24}$/m;
+const CONVENTIONAL = /^[a-z][a-z0-9-]*(\([^()\r\n]+\))?!?: \S/;
+const GENERATED = /^(Merge |Revert "|fixup! |squash! |amend! )/;
+const BANG = /^[a-z][a-z0-9-]*(\([^()\r\n]+\))?!:/;
+const BREAKING_FOOTER = /^BREAKING[ -]CHANGE:/m;
+
+/** What git keeps: no comment lines, nothing after the verbose-commit scissors line. */
+export function messageBody(raw) {
+  const cut = SCISSORS.exec(raw);
+  const kept = cut ? raw.slice(0, cut.index) : raw;
+  return kept
+    .split("\n")
+    .filter((line) => !line.startsWith("#"))
+    .join("\n");
+}
+
+/**
+ * Problems with a commit message. `conventional` is true in a repo whose versions
+ * are cut from the commit types: it also refuses "!" and a BREAKING CHANGE footer.
+ */
+export function check(raw, { conventional = false } = {}) {
+  const body = messageBody(raw);
+  const subject = body.split("\n").find((line) => line.trim()) ?? "";
+  const problems = [];
+  if (conventional && !GENERATED.test(subject) && !CONVENTIONAL.test(subject)) {
+    problems.push(
+      `The subject "${subject}" isn't a Conventional Commit. Release-please reads the type to pick the version: type(scope): summary, like fix: or feat(cli): add x. fix and perf are a patch, feat is a minor, and a breaking change is a minor too. Other types (docs, chore, refactor, test) don't release.`,
+    );
+  }
+  if (conventional && !GENERATED.test(subject) && BANG.test(subject)) {
+    problems.push(
+      `The subject "${subject}" has a "!" after the type. Release-please would cut a major from it. Here a breaking change is a minor: drop the "!" and say what broke in the body. A major needs a "Release-As: X.0.0" footer you write by hand.`,
+    );
+  }
+  if (conventional && BREAKING_FOOTER.test(body)) {
+    problems.push(
+      `The message has a BREAKING CHANGE footer. Release-please would cut a major from it. Here a breaking change is a minor: say what broke in plain body text instead. A major needs a "Release-As: X.0.0" footer you write by hand.`,
+    );
+  }
+  const dashed = body.split("\n").filter((line) => DASH.test(line));
+  if (dashed.length > 0) {
+    problems.push(
+      `The message has an em or en dash: "${dashed[0].trim()}". Rewrite the sentence with a comma, a colon, parentheses or a full stop. Use a plain hyphen only inside a word.`,
+    );
+  }
+  return problems;
+}
+
+export function report(problems) {
+  return `commit-msg: the message was refused\n${problems.map((problem) => `  ${problem}`).join("\n")}\n\nEdit the message and commit again.`;
+}

package/config/oxlintrc.json

@@ -0,0 +1,87 @@
+{
+  "$schema": "https://raw.githubusercontent.com/nicolo-ribaudo/oxlint-config-schema/refs/heads/main/oxlintrc.schema.json",
+  "categories": {
+    "correctness": "error",
+    "suspicious": "warn",
+    "pedantic": "off",
+    "perf": "warn",
+    "style": "off"
+  },
+  "plugins": ["typescript", "unicorn", "import", "oxc"],
+  "jsPlugins": [".."],
+  "ignorePatterns": [
+    "**/.agents/**",
+    "**/.claude/**",
+    "**/.opencode/**",
+    "**/_generated/**",
+    "**/vendor/**",
+    "**/.upstream/**",
+    "**/*.generated.*",
+    "**/public/**",
+    "**/node_modules/**",
+    "**/dist/**",
+    "build/**",
+    "**/.svelte-kit/**",
+    "**/.next/**",
+    "**/.output/**",
+    "**/.vercel/**",
+    "**/.wrangler/**",
+    "**/coverage/**",
+    "**/scripts/secrets.mjs",
+    "**/scripts/secrets-auto.mjs",
+    "**/scripts/secrets.d.mts"
+  ],
+  "rules": {
+    "eslint/max-lines-per-function": [
+      "warn",
+      { "max": 150, "skipBlankLines": true, "skipComments": true, "IIFEs": true }
+    ],
+    "unicorn/no-static-only-class": "error",
+    "@heyramzi/lint/no-ai-words": "warn",
+    "@heyramzi/lint/no-em-dash": "error",
+    "@heyramzi/lint/no-emoji": "error",
+    "typescript/no-explicit-any": "error",
+    "typescript/ban-ts-comment": "error",
+    "typescript/no-non-null-assertion": "error",
+    "@heyramzi/lint/no-skipped-or-focused-tests": "error",
+    "@heyramzi/lint/no-hardcoded-models": "error",
+    "@heyramzi/lint/no-redundant-prop-fallback": "error",
+    "@heyramzi/lint/no-app-stores": "error",
+    "@heyramzi/lint/no-rune-outside-svelte-file": "error",
+    "@heyramzi/lint/no-rune-shadowing-binding": "error",
+    "@heyramzi/lint/no-svelte4-syntax": "error",
+    "@heyramzi/lint/no-vitest-import-in-vite-plus": "error",
+    "@heyramzi/lint/props-interface": "error",
+    "@heyramzi/lint/redirect-external-needs-option": "error",
+    "@heyramzi/lint/no-raw-try-catch": "warn",
+    "@heyramzi/lint/svelte-section-order": "warn",
+    "@heyramzi/lint/no-inline-svg": "error",
+    "@heyramzi/lint/no-inline-path": "error",
+    "@heyramzi/lint/no-relative-imports": "error",
+    "@heyramzi/lint/no-relative-type-imports": "off",
+    "@heyramzi/lint/no-legacy-compat": "error",
+    "@heyramzi/lint/convex-react-client-module-scope": "error",
+    "@heyramzi/lint/no-chained-type-assertions": "warn",
+    "@heyramzi/lint/no-conditional-empty-object-spread": "warn",
+    "@heyramzi/lint/no-known-value-widening": "warn",
+    "@heyramzi/lint/require-safety-comment-for-type-assertion": "off"
+  },
+  "overrides": [
+    {
+      "files": ["**/convex/**"],
+      "rules": {
+        "@heyramzi/lint/convex-index-name": "warn",
+        "@heyramzi/lint/convex-internal-only": "error",
+        "@heyramzi/lint/convex-no-date-now-in-query": "warn",
+        "@heyramzi/lint/convex-no-deprecated-crons": "error",
+        "@heyramzi/lint/convex-no-filter": "warn",
+        "@heyramzi/lint/convex-no-get-metadata": "error",
+        "@heyramzi/lint/convex-no-v-any": "warn",
+        "@heyramzi/lint/convex-require-args": "error",
+        "@heyramzi/lint/convex-require-returns": "warn",
+        "@heyramzi/lint/convex-runtime-imports": "error"
+      }
+    }
+  ],
+  "options": {}
+}