@heyramzi/lint 0.0.0-stage → 1.32.2

package/file-tokens.js

@@ -0,0 +1,122 @@
+/**
+ * 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`.
+ */
+
+export const MAX_TOKENS = 5000;
+export const BYTES_PER_TOKEN = 4;
+
+/** Generated, vendored or projected trees: nobody hand-writes these, so nobody splits them. */
+export const DEFAULT_IGNORED = [
+  "node_modules",
+  "dist",
+  "build",
+  "out",
+  "coverage",
+  "vendor",
+  ".upstream",
+  "generated",
+  "_generated",
+  "__generated__",
+  "__snapshots__",
+  "paraglide",
+  ".svelte-kit",
+  ".wrangler",
+  ".vercel",
+  ".next",
+  ".agents",
+  ".claude",
+  ".codex",
+  ".gemini",
+  ".opencode",
+  "raw",
+  // Boards are one document per subject by the playground skill's rule, and `playground check` gates them.
+  "playground",
+];
+
+/** Projections that live under a tracked folder agents also write in. */
+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 LOCKFILES = new Set([
+  "pnpm-lock.yaml",
+  "package-lock.json",
+  "npm-shrinkwrap.json",
+  "yarn.lock",
+  "bun.lock",
+  "bun.lockb",
+  "deno.lock",
+  "Cargo.lock",
+  "Gemfile.lock",
+  "poetry.lock",
+  "uv.lock",
+  "Pipfile.lock",
+  "composer.lock",
+  "Podfile.lock",
+  "Package.resolved",
+  "flake.lock",
+  "go.sum",
+]);
+
+/** 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$/];
+
+/** 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;
+
+export function tokens(bytes) {
+  return Math.ceil(bytes / BYTES_PER_TOKEN);
+}
+
+/** True when the path itself says a machine wrote the file. */
+export function ignoredPath(file) {
+  const parts = file.split("/");
+  const name = parts.at(-1);
+  if (LOCKFILES.has(name) || DATA_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;
+  return parts.slice(0, -1).some((part) => DEFAULT_IGNORED.includes(part.toLowerCase().replace(/^\W+\s*/u, "")));
+}
+
+/** True when the content says a machine wrote it: a NUL byte (binary, as git decides) or a codegen header. */
+export function generatedContent(head) {
+  if (head.includes(0)) return true;
+  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) {
+  return Object.entries(sizes)
+    .map(([file, bytes]) => ({ file, bytes, tokens: tokens(bytes) }))
+    .filter((entry) => entry.tokens > max)
+    .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) {
+  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`,
+  );
+  return `file-tokens: ${failures.length} staged file(s) over ${max.toLocaleString("en-US")} tokens (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.
+
+How to split:
+  1. List what the file does. Read its exports and top-level blocks and group them by job: types, pure helpers, I/O (fetch, db, fs), state, UI sections, CLI commands, constants and data.
+  2. Give each job its own file, named for that job. foo.ts becomes a foo/ folder with foo/types.ts, foo/parse.ts, foo/client.ts. Aim for each new file under half the cap.
+  3. Move code, don't rewrite it. Cut each group into its new file and import what it needs from its siblings.
+  4. Fix every importer. Search the repo for the old path and point each import at the new file. Don't leave a re-export file at the old path.
+  5. By file type:
+     - Svelte component: move each visual section into a child component and the state and logic into a .svelte.ts module beside it.
+     - Test file: one test file per module under test, next to that module.
+     - Markdown (SKILL.md, a reference, docs): keep the overview and move each detailed topic into its own references/<topic>.md, linked from the overview in one line.
+     - Data or fixtures inside code: move them to a .json file and import it.
+     - Swift: one type per file, extensions in their own Type+Feature.swift.
+  6. Run the repo's typecheck and tests, then stage the new files and the deletions (git add -A <folder>) and commit again.
+
+Only a file no person or agent writes by hand (codegen, a lockfile, vendored code) is exempt. Mark real codegen with an @generated header or a linguist-generated line in .gitattributes. Never mark a file you wrote.`;
+}

package/gate-files.js

@@ -0,0 +1,14 @@
+import { existsSync, lstatSync } from "node:fs";
+import path from "node:path";
+
+/** The files a gate judges: no symlinks, and only the pushed ones when the hook sets PUSH_FILES. */
+export function gateFiles(root, files) {
+  const pushed =
+    process.env.PUSH_FILES === undefined ? null : new Set(process.env.PUSH_FILES.split("\n"));
+  return files.filter((file) => {
+    if (pushed && !pushed.has(file)) return false;
+    // A symlink points at a file the gate already reads at its real path.
+    const full = path.join(root, file);
+    return existsSync(full) && !lstatSync(full).isSymbolicLink();
+  });
+}

package/index.js

@@ -0,0 +1,116 @@
+// Code quality rules (from @upsys/config)
+import noRelativeImports from "#lint/rules/no-relative-imports.js";
+import noRelativeTypeImports from "#lint/rules/no-relative-type-imports.js";
+import noDeepPhosphorImports from "#lint/rules/no-deep-phosphor-imports.js";
+import noClass from "#lint/rules/no-class.js";
+import noDefaultExport from "#lint/rules/no-default-export.js";
+import noOverkillFallback from "#lint/rules/no-overkill-fallback.js";
+import noRedundantPropFallback from "#lint/rules/no-redundant-prop-fallback.js";
+import maxObjectMethods from "#lint/rules/max-object-methods.js";
+import maxFunctionLines from "#lint/rules/max-function-lines.js";
+import noSnakeCaseProps from "#lint/rules/no-snake-case-props.js";
+import noHardcodedModels from "#lint/rules/no-hardcoded-models.js";
+import noLegacyCompat from "#lint/rules/no-legacy-compat.js";
+
+// Convex rules (the checks @convex-dev/eslint-plugin never ran here, plus the house rules)
+import convexIndexName from "#lint/rules/convex-index-name.js";
+import convexInternalOnly from "#lint/rules/convex-internal-only.js";
+import convexNoDateNowInQuery from "#lint/rules/convex-no-date-now-in-query.js";
+import convexNoDeprecatedCrons from "#lint/rules/convex-no-deprecated-crons.js";
+import convexNoFilter from "#lint/rules/convex-no-filter.js";
+import convexNoGetMetadata from "#lint/rules/convex-no-get-metadata.js";
+import convexNoVAny from "#lint/rules/convex-no-v-any.js";
+import convexReactClientModuleScope from "#lint/rules/convex-react-client-module-scope.js";
+import convexRequireArgs from "#lint/rules/convex-require-args.js";
+import convexRequireReturns from "#lint/rules/convex-require-returns.js";
+import convexRuntimeImports from "#lint/rules/convex-runtime-imports.js";
+
+// Type-evidence rules (ported from dmmulroy/anti-slop)
+import noChainedTypeAssertions from "#lint/rules/no-chained-type-assertions.js";
+import noConditionalEmptyObjectSpread from "#lint/rules/no-conditional-empty-object-spread.js";
+import noKnownValueWidening from "#lint/rules/no-known-value-widening.js";
+import requireSafetyCommentForTypeAssertion from "#lint/rules/require-safety-comment-for-type-assertion.js";
+
+// Stop-slop rules (from eslint-plugin-stop-slop)
+import noAiWords from "#lint/rules/no-ai-words.js";
+import noEmDash from "#lint/rules/no-em-dash.js";
+import noEmoji from "#lint/rules/no-emoji.js";
+import noInlineSvg from "#lint/rules/no-inline-svg.js";
+import noInlinePath from "#lint/rules/no-inline-path.js";
+import noRawTryCatch from "#lint/rules/no-raw-try-catch.js";
+import svelteSectionOrder from "#lint/rules/svelte-section-order.js";
+
+// Svelte and SvelteKit house rules
+import noAppStores from "#lint/rules/no-app-stores.js";
+import noRuneOutsideSvelteFile from "#lint/rules/no-rune-outside-svelte-file.js";
+import noRuneShadowingBinding from "#lint/rules/no-rune-shadowing-binding.js";
+import noSkippedOrFocusedTests from "#lint/rules/no-skipped-or-focused-tests.js";
+import noSvelte4Syntax from "#lint/rules/no-svelte4-syntax.js";
+import noVitestImportInVitePlus from "#lint/rules/no-vitest-import-in-vite-plus.js";
+import propsInterface from "#lint/rules/props-interface.js";
+import redirectExternalNeedsOption from "#lint/rules/redirect-external-needs-option.js";
+
+import { markdownProcessor } from "#lint/processors/markdown.js";
+
+export default {
+  meta: {
+    name: "@heyramzi/lint",
+    version: "2.0.0",
+  },
+  rules: {
+    // Code quality
+    "no-relative-imports": noRelativeImports,
+    "no-relative-type-imports": noRelativeTypeImports,
+    "no-deep-phosphor-imports": noDeepPhosphorImports,
+    "no-class": noClass,
+    "no-default-export": noDefaultExport,
+    "no-overkill-fallback": noOverkillFallback,
+    "no-redundant-prop-fallback": noRedundantPropFallback,
+    "max-object-methods": maxObjectMethods,
+    "max-function-lines": maxFunctionLines,
+    "no-snake-case-props": noSnakeCaseProps,
+    "no-hardcoded-models": noHardcodedModels,
+    "no-legacy-compat": noLegacyCompat,
+
+    // Convex
+    "convex-index-name": convexIndexName,
+    "convex-internal-only": convexInternalOnly,
+    "convex-no-date-now-in-query": convexNoDateNowInQuery,
+    "convex-no-deprecated-crons": convexNoDeprecatedCrons,
+    "convex-no-filter": convexNoFilter,
+    "convex-no-get-metadata": convexNoGetMetadata,
+    "convex-no-v-any": convexNoVAny,
+    "convex-react-client-module-scope": convexReactClientModuleScope,
+    "convex-require-args": convexRequireArgs,
+    "convex-require-returns": convexRequireReturns,
+    "convex-runtime-imports": convexRuntimeImports,
+
+    // Type evidence
+    "no-chained-type-assertions": noChainedTypeAssertions,
+    "no-conditional-empty-object-spread": noConditionalEmptyObjectSpread,
+    "no-known-value-widening": noKnownValueWidening,
+    "require-safety-comment-for-type-assertion": requireSafetyCommentForTypeAssertion,
+
+    // Stop slop
+    "no-ai-words": noAiWords,
+    "no-em-dash": noEmDash,
+    "no-emoji": noEmoji,
+    "no-inline-svg": noInlineSvg,
+    "no-inline-path": noInlinePath,
+    "no-raw-try-catch": noRawTryCatch,
+    "svelte-section-order": svelteSectionOrder,
+
+    // Svelte and SvelteKit
+    "no-app-stores": noAppStores,
+    "no-rune-outside-svelte-file": noRuneOutsideSvelteFile,
+    "no-rune-shadowing-binding": noRuneShadowingBinding,
+    "no-skipped-or-focused-tests": noSkippedOrFocusedTests,
+    "no-svelte4-syntax": noSvelte4Syntax,
+    "no-vitest-import-in-vite-plus": noVitestImportInVitePlus,
+    "props-interface": propsInterface,
+    "redirect-external-needs-option": redirectExternalNeedsOption,
+  },
+  processors: {
+    markdown: markdownProcessor,
+  },
+};

package/inline-path.js

@@ -0,0 +1,90 @@
+/**
+ * The inline path gate: SVG paths must not be embedded inline in components.
+ * SVGs must be separate files (.svg) and imported.
+ *
+ * Pure here, git and process in `bin/heyramzi-inline-path.js`.
+ */
+
+export const DEFAULT_EXTENSIONS = ["svelte", "vue", "jsx", "tsx", "html", "astro"];
+
+/** Generated or vendored trees: nobody can refactor code they do not write. */
+export const DEFAULT_IGNORED = [
+  "node_modules",
+  "dist",
+  "build",
+  "builds",
+  "out",
+  "coverage",
+  "vendor",
+  ".upstream",
+  "generated",
+  "_generated",
+  "paraglide",
+  ".svelte-kit",
+  ".wrangler",
+  ".vercel",
+  ".agents",
+  ".claude",
+  ".next",
+  "static",
+  // Boards draw their diagrams inline by the playground skill's rule, and `playground check` gates them.
+  "playground",
+];
+
+/**
+ * Scans a file's content for inline <path> tags that have static path data (d="...").
+ * Returns an array of matches: { line, snippet }.
+ */
+export function findInlinePaths(source) {
+  const matches = [];
+
+  // Match <path ... > tags across potential line breaks
+  const pathTagRegex = /<path\b([^>]*?)(\/?>)/gis;
+  let match;
+
+  while ((match = pathTagRegex.exec(source)) !== null) {
+    // Only a static path data attribute d="..." or d='...' counts
+    if (!/\bd\s*=\s*["'][^"']*["']/is.test(match[1])) continue;
+
+    matches.push({
+      line: source.slice(0, match.index).split("\n").length,
+      snippet: match[0].slice(0, 80).replace(/\s+/g, " "),
+    });
+  }
+
+  return matches;
+}
+
+/** Total count of inline static paths in source. */
+export function countInlinePaths(source) {
+  return findInlinePaths(source).length;
+}
+
+/** A hard rule: every file with an inline static path fails. */
+export function check(counts) {
+  const failures = [];
+  for (const [file, count] of Object.entries(counts)) {
+    if (count > 0) failures.push({ file, count });
+  }
+  return failures.toSorted((a, b) => b.count - a.count);
+}
+
+/** Filter tracked files for the gate. */
+export function selectFiles(
+  tracked,
+  { targets = [], extensions = DEFAULT_EXTENSIONS, ignored = DEFAULT_IGNORED } = {},
+) {
+  const wanted = new Set(extensions.map((ext) => ext.replace(/^\./, "")));
+  return tracked.filter((file) => {
+    // Explicitly exclude standalone .svg files
+    if (file.endsWith(".svg")) return false;
+    const ext = file.slice(file.lastIndexOf(".") + 1);
+    if (!wanted.has(ext)) return false;
+    if (file.endsWith(".min.js")) 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/jev-code.js

@@ -0,0 +1,194 @@
+/**
+ * Coding guidelines as tiny Jev questions, judged on the edited code alone after each edit.
+ * Only rules a reader can settle from the snippet, no repo context. Bench: scripts/jev-code-bench.mjs.
+ */
+import { NO_KEY, judge, q } from "#lint/jev.js";
+
+// =========================
+// CONSTANTS
+// =========================
+const TS = ["ts", "tsx", "js", "jsx", "mjs", "cjs", "svelte", "vue"];
+const CODE = [...TS, "swift", "py", "sh"];
+const PLAIN = "Ordinary code that does its job directly, or code this question does not apply to.";
+
+/** `langs` scopes a rule by extension; `fix` is what the agent reads; `advisory` never blocks, since acting on it needs the callers. */
+export const RULES = {
+  cast: {
+    langs: TS,
+    fix: "Fix the type at its source instead of asserting it.",
+    shape: q(
+      "Does `code` use a type assertion (`as any`, `as unknown as X`, `as SomeType` on data from outside, a `!` non-null assertion, `@ts-ignore`) to make the compiler accept a value instead of narrowing or typing it properly?",
+      "An assertion or suppression silences the type checker where a real type, a guard or a parse would do.",
+      `${PLAIN} \`as const\`, a narrowing \`if\`, or a schema parse are not assertions.`,
+    ),
+  },
+  compat: {
+    langs: CODE,
+    fix: "Delete the shim and move every caller to the new name.",
+    shape: q(
+      "Does `code` keep an old name or shape alive for backward compatibility: a deprecated alias or re-export, a wrapper that forwards to the new function, or reading one field under two names (`x.newName ?? x.old_name`)?",
+      "A second name, alias, fallback field or forwarding wrapper exists only so old callers keep working.",
+      PLAIN,
+    ),
+  },
+  swallowed: {
+    langs: CODE,
+    fix: "Let the error propagate, or handle it with a real recovery.",
+    shape: q(
+      "Does `code` catch an error and then drop it: an empty catch, a catch that only logs and carries on, or a fallback value that hides a failure the caller needed to know about?",
+      "A failure is caught and silenced, so the program continues as if it had worked.",
+      `${PLAIN} A catch that rethrows, returns a typed error, retries, or recovers with a documented reason passes.`,
+    ),
+  },
+  impossible: {
+    langs: CODE,
+    fix: "Remove the check: the code above already guarantees it.",
+    shape: q(
+      "Does `code` guard against a case that `code` itself already rules out: a null check on a value it just created, a type check on a literal, a try around code that cannot throw, a default for a parameter that is always passed?",
+      "A branch, check or fallback handles a situation the surrounding lines make impossible.",
+      `${PLAIN} A check on input from outside (a request, a file, a user, an API) is never impossible.`,
+    ),
+  },
+  wrapper: {
+    langs: CODE,
+    advisory: true,
+    fix: "If its callers can call the real target directly, inline it there.",
+    shape: q(
+      "Does `code` define a function, class or object that only forwards to one other call with the same arguments, adding no logic, name clarity or type?",
+      "A middle man: its whole body is a single pass-through call.",
+      PLAIN,
+    ),
+  },
+  speculative: {
+    langs: CODE,
+    advisory: true,
+    fix: "If no caller passes it, delete the option or hook.",
+    shape: q(
+      "Does `code` add configurability nobody in `code` uses: an options parameter, flag, strategy, plugin hook or generic type parameter with a single value or no reader?",
+      "A parameter, option, hook or abstraction exists for a future need, not for anything the code shown does.",
+      PLAIN,
+    ),
+  },
+  naming: {
+    langs: CODE,
+    fix: "Rename it for what it holds or does.",
+    shape: q(
+      "Does `code` introduce a name that says nothing about what it holds or does: `data`, `result`, `tmp`, `info`, `item2`, `handleStuff`, `utils`, `manager`, `helper`, `doIt`, a single letter outside a short loop?",
+      "A newly declared name is generic or meaningless, and a reader has to read the body to learn what it is.",
+      `${PLAIN} Conventional short names (\`i\` in a loop, \`e\` for an event, \`err\` in a catch) pass.`,
+    ),
+  },
+  nesting: {
+    langs: CODE,
+    fix: "Return early with guard clauses and flatten the nesting.",
+    shape: q(
+      "Does `code` nest conditionals three or more levels deep where early returns or one combined guard would make it flat?",
+      "An if inside an if inside an if (or nested if-let) that guard clauses could flatten.",
+      PLAIN,
+    ),
+  },
+  narration: {
+    langs: CODE,
+    fix: "Delete the comment, or replace it with the one trap the code can't show.",
+    shape: q(
+      "Does `code` contain a comment that repeats what the next line plainly does, or narrates history ('changed from X', 'added for the new flow', 'now uses Y') instead of a reason the code cannot show?",
+      "A comment that restates the code or reads as a changelog.",
+      `${PLAIN} A comment naming a trap, a constraint, a number's source, a non-obvious why, or a dated fact about an outside service passes. No comment passes.`,
+    ),
+  },
+  leftover: {
+    langs: CODE,
+    fix: "Delete the debug output or commented-out code.",
+    shape: q(
+      "Does `code` leave debugging or dead material behind: commented-out code, a stray `console.log`/`print` of an intermediate value, or a `TODO` placeholder where the work should be?",
+      "Debug output, dead commented code or a placeholder stub.",
+      `${PLAIN} Logging that a CLI or server deliberately emits to its user or log passes.`,
+    ),
+  },
+  workaround: {
+    langs: CODE,
+    fix: "Fix the cause the comment names, then delete the comment.",
+    shape: q(
+      "Does `code` contain a comment that admits the code is a stopgap: a workaround kept until something else changes, an old name kept until a rename, or a known-wrong shortcut ('quick fix', 'until X ships', 'keep the old route name')?",
+      "A comment that explains a hack instead of the code fixing it.",
+      `${PLAIN} A comment naming a fact outside the code (a browser bug, an API that answers 404 since a date, a platform limit) passes.`,
+    ),
+  },
+  fallback: {
+    langs: CODE,
+    fix: "Require the value and fail loudly when it's missing, or read it from its one source.",
+    shape: q(
+      "Does `code` fall back when a value it needs is missing: a default for required config or input (`?? \"\"`, `|| 'default'`), trying a second or third source for the same value (`a ?? b ?? c`), or carrying on with a placeholder instead of failing?",
+      "A fallback that hides a missing value the program needed.",
+      `${PLAIN} A default for a truly optional value (a page size, a label shown blank) or a documented retry passes.`,
+    ),
+  },
+  duplicate: {
+    langs: CODE,
+    fix: "Extract the shared shape once and call it from both places.",
+    shape: q(
+      "Does `code` repeat the same block of logic two or more times with only a value or name changed, where one function or loop would serve?",
+      "Copy-pasted logic appears twice or more inside `code`.",
+      PLAIN,
+    ),
+  },
+  effectSync: {
+    langs: ["svelte", "ts", "js"],
+    fix: "Use `$derived` for state computed from other state; keep `$effect` for side effects.",
+    shape: q(
+      "Does `code` use a Svelte `$effect` (or `$:` statement) to assign one piece of state from other state, where `$derived` would compute it?",
+      "An effect whose body only sets state from other reactive values.",
+      `${PLAIN} An effect that talks to the outside world (DOM, network, storage, timers) passes.`,
+    ),
+  },
+  restates: {
+    langs: CODE,
+    tests: true,
+    fix: "Delete it: assert behaviour through the E2E path, not the implementation's own constants or mocks.",
+    shape: q(
+      "Is `code` a test that checks the implementation instead of a result: its assertion is only that a mock, spy or `vi.fn()` was called, or its expected value is recomputed with the same formula or constant the code under test uses?",
+      "`toHaveBeenCalled` on a mock with no check of what came out, or an expected value built from the implementation's own constant or arithmetic.",
+      "A test that feeds real input and checks an observable output or side effect.",
+    ),
+  },
+};
+
+// =========================
+// FUNCTIONS
+// =========================
+const TEST = /(\.|_|\/)(test|spec)s?\.|__tests__\/|\/tests?\//;
+
+/** The rules that apply to a file, by extension and whether it is a test. */
+export function rulesFor(file) {
+  const ext = file.split(".").pop()?.toLowerCase() ?? "";
+  const isTest = TEST.test(file);
+  return Object.fromEntries(
+    Object.entries(RULES).filter(([, r]) => r.langs.includes(ext) && Boolean(r.tests) === isTest),
+  );
+}
+
+/** Code longer than MAX_LINES is split so each chunk stays one easy judgement. */
+const MAX_LINES = 60;
+
+export function chunks(code) {
+  const lines = code.split("\n");
+  const out = [];
+  for (let i = 0; i < lines.length; i += MAX_LINES)
+    out.push(lines.slice(i, i + MAX_LINES).join("\n"));
+  return out.filter((c) => c.replace(/\s/g, "").length >= 20);
+}
+
+/** Every chunk of `code` against the rules for `file`, split into `findings` and `review`. */
+export async function auditCode(code, file, { key = process.env.KILO_API_KEY } = {}) {
+  if (!key) throw new Error(`jev-code ${NO_KEY}`);
+  const rules = rulesFor(file);
+  const items = chunks(code).map((c) => ({ code: `// ${file.split("/").pop()}\n${c}` }));
+  if (!items.length || !Object.keys(rules).length) return { findings: [], review: [] };
+  const shapes = Object.fromEntries(Object.entries(rules).map(([id, r]) => [id, r.shape]));
+  const { findings, review } = await judge(items, shapes, "code", key);
+  const advisory = (h) => RULES[h.id].advisory;
+  return {
+    findings: findings.filter((h) => !advisory(h)),
+    review: [...review, ...findings.filter(advisory)],
+  };
+}