@heyramzi/lint 0.0.0-stage → 1.32.2

package/svelte-markup.js

@@ -0,0 +1,107 @@
+/**
+ * The Svelte markup gate: the template checks oxlint can't make.
+ */
+
+/*
+ * oxlint only visits a .svelte file that has a `<script>`, and a markup-only component (a `<slot />` wrapper) has none. Pure here, git and process in `bin/heyramzi-svelte-markup.js`.
+ */
+import {
+  isRegularElement,
+  MATHML_ELEMENTS,
+  scanTemplate,
+  SVG_ELEMENTS,
+  VOID_ELEMENTS,
+} from "#lint/svelte-template.js";
+
+/** Generated or vendored trees: nobody can fix code they don't write. */
+export const DEFAULT_IGNORED = [
+  "node_modules",
+  "dist",
+  "build",
+  "out",
+  "coverage",
+  "vendor",
+  ".upstream",
+  "generated",
+  "_generated",
+  ".svelte-kit",
+  ".wrangler",
+  ".agents",
+  ".claude",
+  ".opencode",
+  ".gemini",
+  "playground",
+];
+
+/** Every violation in one .svelte source: `{ line, rule, message }`. */
+export function findMarkupViolations(source) {
+  const { tags } = scanTemplate(source);
+  const customElement = tags.some(
+    (tag) => tag.name === "svelte:options" && tag.attrs.some((a) => a.name === "customElement"),
+  );
+  const found = [];
+  const add = (line, rule, message) => found.push({ line, rule, message });
+
+  for (const tag of tags) {
+    if (tag.closing) continue;
+
+    if (tag.name === "slot" && !customElement) {
+      add(
+        tag.line,
+        "svelte4-slot",
+        "`<slot>` is Svelte 4. Take `children` or a named snippet prop and render it with `{@render children?.()}`.",
+      );
+    }
+    if (tag.name === "svelte:component") {
+      add(
+        tag.line,
+        "svelte4-component",
+        "`<svelte:component>` is Svelte 4. Put the component in a variable and render `<Component />`.",
+      );
+    }
+    for (const attr of tag.attrs) {
+      if (attr.name.startsWith("on:")) {
+        const event = attr.name.slice(3).split("|")[0];
+        add(
+          attr.line,
+          "svelte4-event",
+          `\`${attr.name.split("|")[0]}\` is Svelte 4. Use the \`on${event}\` attribute, and a callback prop on a component.`,
+        );
+      }
+      if (attr.name.startsWith("class:") && /\[[^\]]+\]/.test(attr.name)) {
+        add(
+          attr.line,
+          "class-arbitrary-value",
+          `\`${attr.name}\` never applies: \`class:\` can't carry a Tailwind arbitrary value. Use \`style:property={...}\` (for example \`style:min-height={compact ? '300px' : '460px'}\`).`,
+        );
+      }
+    }
+    if (
+      tag.selfClosing &&
+      tag.name !== "slot" &&
+      isRegularElement(tag.name) &&
+      !VOID_ELEMENTS.has(tag.name) &&
+      !SVG_ELEMENTS.has(tag.name) &&
+      !MATHML_ELEMENTS.has(tag.name)
+    ) {
+      add(
+        tag.line,
+        "self-closing",
+        `\`<${tag.name} />\` is ambiguous HTML. Write \`<${tag.name}></${tag.name}>\`.`,
+      );
+    }
+  }
+  return found.toSorted((a, b) => a.line - b.line);
+}
+
+/** Filter tracked files down to the .svelte files the gate reads. */
+export function selectFiles(tracked, { ignored = DEFAULT_IGNORED, targets = [] } = {}) {
+  return tracked.filter((file) => {
+    if (!file.endsWith(".svelte")) 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/svelte-template.js

@@ -0,0 +1,258 @@
+/**
+ * A small reader for a Svelte template, for the rules that oxlint can't reach.
+ */
+
+/*
+ * oxlint gives a rule only a .svelte file's script. This scans the markup from disk: tags with attributes, `{...}` expressions and block headers, each with its line.
+ */
+
+/*
+ * It isn't a parser. It knows quotes, comments, `<script>`, `<style>` and balanced braces, which is all the rules need to never read prose or a string as markup.
+ */
+
+import { readFileSync } from "node:fs";
+
+export const VOID_ELEMENTS = new Set([
+  "area",
+  "base",
+  "br",
+  "col",
+  "command",
+  "embed",
+  "hr",
+  "img",
+  "input",
+  "keygen",
+  "link",
+  "meta",
+  "param",
+  "source",
+  "track",
+  "wbr",
+]);
+
+// Copied from svelte/src/utils.js, which warns on a self-closing tag by name.
+export const SVG_ELEMENTS = new Set(
+  "altGlyph altGlyphDef altGlyphItem animate animateColor animateMotion animateTransform circle clipPath color-profile cursor defs desc discard ellipse feBlend feColorMatrix feComponentTransfer feComposite feConvolveMatrix feDiffuseLighting feDisplacementMap feDistantLight feDropShadow feFlood feFuncA feFuncB feFuncG feFuncR feGaussianBlur feImage feMerge feMergeNode feMorphology feOffset fePointLight feSpecularLighting feSpotLight feTile feTurbulence filter font font-face font-face-format font-face-name font-face-src font-face-uri foreignObject g glyph glyphRef hatch hatchpath hkern image line linearGradient marker mask mesh meshgradient meshpatch meshrow metadata missing-glyph mpath path pattern polygon polyline radialGradient rect set solidcolor stop svg switch symbol text textPath tref tspan unknown use view vkern".split(
+    " ",
+  ),
+);
+
+export const MATHML_ELEMENTS = new Set(
+  "annotation annotation-xml maction math merror mfrac mi mmultiscripts mn mo mover mpadded mphantom mprescripts mroot mrow ms mspace msqrt mstyle msub msubsup msup mtable mtd mtext mtr munder munderover semantics".split(
+    " ",
+  ),
+);
+
+const RAW_TEXT = new Set(["script", "style"]);
+
+/** The index just past the `}` that closes the `{` at `start`, honouring strings and comments. */
+function skipBraces(source, start) {
+  let depth = 0;
+  for (let i = start; i < source.length; i++) {
+    const c = source[i];
+    if (c === "'" || c === '"') {
+      i = skipString(source, i, c);
+    } else if (c === "`") {
+      i = skipTemplate(source, i);
+    } else if (c === "/" && source[i + 1] === "*") {
+      const end = source.indexOf("*/", i + 2);
+      if (end === -1) return source.length;
+      i = end + 1;
+    } else if (c === "/" && source[i + 1] === "/" && source[i - 1] !== ":") {
+      const end = source.indexOf("\n", i);
+      if (end === -1) return source.length;
+      i = end;
+    } else if (c === "{") {
+      depth++;
+    } else if (c === "}") {
+      depth--;
+      if (depth === 0) return i + 1;
+    }
+  }
+  return source.length;
+}
+
+function skipString(source, start, quote) {
+  for (let i = start + 1; i < source.length; i++) {
+    if (source[i] === "\\") i++;
+    else if (source[i] === quote || source[i] === "\n") return i;
+  }
+  return source.length;
+}
+
+function skipTemplate(source, start) {
+  for (let i = start + 1; i < source.length; i++) {
+    if (source[i] === "\\") i++;
+    else if (source[i] === "`") return i;
+    else if (source[i] === "$" && source[i + 1] === "{") i = skipBraces(source, i + 1) - 1;
+  }
+  return source.length;
+}
+
+/**
+ * Scan a whole .svelte source.
+ * @returns {{ tags: Tag[], expressions: Expression[], blocks: Block[] }}
+ */
+export function scanTemplate(source) {
+  const tags = [];
+  const expressions = [];
+  const blocks = [];
+  const lineStarts = [0];
+  for (let i = 0; i < source.length; i++) if (source[i] === "\n") lineStarts.push(i + 1);
+  const lineAt = (index) => {
+    let lo = 0;
+    let hi = lineStarts.length - 1;
+    while (lo < hi) {
+      const mid = (lo + hi + 1) >> 1;
+      if (lineStarts[mid] <= index) lo = mid;
+      else hi = mid - 1;
+    }
+    return lo + 1;
+  };
+
+  /** Read `{...}` at `start`; records it and returns the index after it. */
+  function readBraces(start, into) {
+    const end = skipBraces(source, start);
+    const code = source.slice(start + 1, end - 1);
+    const kind = code[0];
+    const record = { code, line: lineAt(start) };
+    if (kind === "#" || kind === ":" || kind === "/" || kind === "@") blocks.push(record);
+    else if (into) into.push(record);
+    else expressions.push(record);
+    return end;
+  }
+
+  function readTag(start, closing) {
+    let i = start + (closing ? 2 : 1);
+    const nameStart = i;
+    while (i < source.length && /[\w:.-]/.test(source[i])) i++;
+    const tag = {
+      name: source.slice(nameStart, i),
+      closing,
+      selfClosing: false,
+      line: lineAt(start),
+      attrs: [],
+      end: i,
+    };
+    while (i < source.length) {
+      while (i < source.length && /\s/.test(source[i])) i++;
+      const c = source[i];
+      if (c === undefined) break;
+      if (c === ">") {
+        i++;
+        break;
+      }
+      if (c === "/" && source[i + 1] === ">") {
+        tag.selfClosing = true;
+        i += 2;
+        break;
+      }
+      if (c === "/") {
+        i++;
+        continue;
+      }
+      if (c === "{") {
+        const attrExprs = [];
+        const end = readBraces(i, attrExprs);
+        tag.attrs.push({ name: source.slice(i, end), value: null, line: lineAt(i) });
+        expressions.push(...attrExprs);
+        i = end;
+        continue;
+      }
+      const attrStart = i;
+      while (
+        i < source.length &&
+        !/[\s=>]/.test(source[i]) &&
+        !(source[i] === "/" && source[i + 1] === ">")
+      ) {
+        if (source[i] === "{") i = skipBraces(source, i);
+        else i++;
+      }
+      const attr = { name: source.slice(attrStart, i), value: null, line: lineAt(attrStart) };
+      let j = i;
+      while (j < source.length && /\s/.test(source[j])) j++;
+      if (source[j] === "=") {
+        j++;
+        while (j < source.length && /\s/.test(source[j])) j++;
+        const q = source[j];
+        const valueStart = j;
+        if (q === '"' || q === "'") {
+          j++;
+          while (j < source.length && source[j] !== q) {
+            if (source[j] === "{") j = readBraces(j, null);
+            else j++;
+          }
+          attr.value = source.slice(valueStart + 1, j);
+          j++;
+        } else {
+          while (j < source.length && !/[\s>]/.test(source[j])) {
+            if (source[j] === "{") j = readBraces(j, null);
+            else if (source[j] === "/" && source[j + 1] === ">") break;
+            else j++;
+          }
+          attr.value = source.slice(valueStart, j);
+        }
+        i = j;
+      }
+      tag.attrs.push(attr);
+    }
+    tag.end = i;
+    return tag;
+  }
+
+  let i = 0;
+  while (i < source.length) {
+    const c = source[i];
+    if (c === "<" && source.startsWith("<!--", i)) {
+      const end = source.indexOf("-->", i + 4);
+      i = end === -1 ? source.length : end + 3;
+    } else if (c === "<" && /[A-Za-z]/.test(source[i + 1] ?? "")) {
+      const tag = readTag(i, false);
+      tags.push(tag);
+      i = tag.end;
+      if (RAW_TEXT.has(tag.name) && !tag.selfClosing) {
+        const close = new RegExp(`</${tag.name}\\s*>`, "i");
+        const rest = source.slice(i);
+        const found = close.exec(rest);
+        i = found ? i + found.index + found[0].length : source.length;
+      }
+    } else if (c === "<" && source[i + 1] === "/" && /[A-Za-z]/.test(source[i + 2] ?? "")) {
+      const tag = readTag(i, true);
+      tags.push(tag);
+      i = tag.end;
+    } else if (c === "{") {
+      i = readBraces(i, null);
+    } else {
+      i++;
+    }
+  }
+  return { tags, expressions, blocks };
+}
+
+/** True for `<div>`, false for `<Card>`, `<a.b>` and `<svelte:head>`. */
+export function isRegularElement(name) {
+  return /^[a-z][^\s.:]*$/.test(name);
+}
+
+/** @typedef {{ name: string, closing: boolean, selfClosing: boolean, line: number, attrs: { name: string, value: string | null, line: number }[], end: number }} Tag */
+
+/** @typedef {{ code: string, line: number }} Expression */
+
+/** @typedef {{ code: string, line: number }} Block */
+
+let cached = null;
+
+/** The scan of a .svelte file on disk, or null when it can't be read. One file is kept, since every rule asks for the same one in turn. */
+export function readTemplate(filename) {
+  let source;
+  try {
+    source = readFileSync(filename, "utf8");
+  } catch {
+    return null;
+  }
+  if (cached?.filename !== filename || cached.source !== source) {
+    cached = { filename, source, scan: scanTemplate(source) };
+  }
+  return { source, ...cached.scan };
+}

package/ui-rules.js

@@ -0,0 +1,324 @@
+/**
+ * The UI-rules gate: CSS, markup and config checks the impeccable detector misses.
+ * Pure here, git and process in `bin/heyramzi-ui-rules.js`.
+ */
+
+export const STYLE_EXTENSIONS = [".svelte", ".css", ".html", ".ts", ".tsx"];
+
+/** Generated, vendored or projected trees, plus the playground boards and fixture-style test dirs. */
+export const DEFAULT_IGNORED = [
+  "node_modules",
+  "dist",
+  "build",
+  "out",
+  "coverage",
+  "vendor",
+  ".upstream",
+  "generated",
+  "_generated",
+  "paraglide",
+  ".svelte-kit",
+  ".wrangler",
+  ".vercel",
+  ".next",
+  ".agents",
+  ".claude",
+  ".codex",
+  ".gemini",
+  ".opencode",
+  "playground",
+  ".obsidian",
+  ".reference",
+  "builds",
+];
+
+const T_FAMILIES =
+  "avatar|check|clear|digit|dropdown|enter|error|exit|fade|fly|follow|glare|hold|input|learn|lift|like|mask|modal|morph|page|pop|press|reel|resize|return|scrollbar|shake|shimmer|stagger|success|swap|text|think|tilt|acc|tabs|toast|tooltip|number|badge|panel|toggle|banner|matrix|stream|reason|skeleton|accordion";
+
+const TOKEN_NAMES = "stagger|micro|quick|fast|medium|slow|very-slow";
+
+const MESSAGES = {
+  "transition-all":
+    "Name the properties: `transition: opacity var(--duration-fast), transform var(--duration-fast)`, or Tailwind `transition-[opacity,transform]`. `all` animates layout properties you never meant to.",
+  "scale-zero":
+    "Start from `scale(0.9)` to `scale(0.97)` plus `opacity: 0`. Nothing in the real world appears from nothing.",
+  "ease-in":
+    "Use `var(--ease-smooth-out)` (or `ease-out`). `ease-in` starts slow, delaying the exact moment the user is watching. `ease-in-out` is fine for on-screen movement.",
+  "duration-literal":
+    "Write `duration-[var(--duration-fast)]` and `delay-[var(--duration-micro)]`, never a literal. Tokens: stagger, micro, quick, fast, medium, slow, very-slow.",
+  "duration-bare":
+    "Write `duration-[var(--duration-fast)]`, never `duration-fast`. Tailwind's `duration-*` resolves against `--transition-duration-*`, so a bare token class generates nothing and sits at 0s.",
+  "acc-panel-padding":
+    "Put the padding on `.t-acc-panel-inner`. A padded `0fr` grid track never fully closes.",
+  "swift-t-class":
+    "`t-*` classes are CSS. In Swift, take the pattern and tokens from `transitions-dev` and write the native call (see `ios-design`, Transitions branch).",
+  "viewport-zoom":
+    "Never disable zoom, it's an accessibility failure. Remove `user-scalable=no` and `maximum-scale=1`; set input font size to 16px instead, since that caused the zoom.",
+  "body-user-select":
+    "Never `user-select: none` on body or html: users copy addresses and order numbers. Put it on controls only (`button`, `[role=\"button\"]`, `.tab`, `.chip`).",
+  "outline-neutral":
+    "Image outlines are pure black or white at 10%: `outline outline-1 -outline-offset-1 outline-black/10 dark:outline-white/10`. Never `outline-slate-*`, `-zinc-*` or `-neutral-*`.",
+  "raw-hover":
+    "Wrap raw CSS `:hover` in `@media (hover: hover) and (pointer: fine) { }`, or it sticks after a tap on touch. Tailwind's `hover:` is already gated.",
+  "local-shadcn":
+    "Never vendor shadcn. Import from `@heyramzi/ui/shadcn/<name>`; a fix or new component lands in the `@heyramzi/ui` source and arrives as a version bump. Delete the local copy and `components.json`.",
+  "ui-source":
+    "app.css needs `@source \"../node_modules/@heyramzi/ui/src\";` (path relative to app.css), or Tailwind generates none of the kit's classes.",
+  "cloudflare-relative":
+    "Set `paths: { relative: false }` in svelte.config. adapter-cloudflare with relative paths took upsys-consulting.com down with intermittent 404s.",
+  "static-shadow":
+    "Delete the static file. On Cloudflare a file in `static/` beats a route of the same path, so a robots or sitemap route never has a static twin.",
+};
+
+/** Blank out comments, keeping every newline so line numbers hold. */
+export function stripComments(source, file) {
+  const blank = (match) => match.replace(/[^\n]/g, " ");
+  let out = source.replace(/\/\*[\s\S]*?\*\//g, blank);
+  if (file.endsWith(".svelte") || file.endsWith(".html")) out = out.replace(/<!--[\s\S]*?-->/g, blank);
+  if (/\.(svelte|tsx?)$/.test(file)) out = out.replace(/(^|[\s;{(,])\/\/[^\n]*/g, (m, lead) => lead + blank(m.slice(lead.length)));
+  return out;
+}
+
+function lineOf(source, index) {
+  let line = 1;
+  for (let i = 0; i < index; i++) if (source.charCodeAt(i) === 10) line++;
+  return line;
+}
+
+function scan(source, pattern, rule) {
+  const hits = [];
+  for (const match of source.matchAll(pattern)) {
+    hits.push({ rule, line: lineOf(source, match.index), snippet: match[0].trim().slice(0, 80) });
+  }
+  return hits;
+}
+
+/** A `t-*` class from `@heyramzi/ui/animations` or `design`, inside a Swift string. */
+const SWIFT_T_CLASS = new RegExp(
+  `"[^"\\n]*(?<![\\w/.-])t-(?:${T_FAMILIES})(?![\\w])[^"\\n]*"`,
+  "g",
+);
+
+const LINE_RULES = [
+  ["transition-all", /(?<![\w-])transition(?:-property)?\s*:\s*[^;}"'`]*\ball\b|(?<![\w-])transition-(?:all|\[all\])(?![\w-])/g],
+  ["scale-zero", /(?<![\w-])scale\(\s*0(?:\.0+)?\s*(?:,\s*0(?:\.0+)?\s*)?\)|(?<![\w-])scale-0(?![\w.-])/g],
+  ["ease-in", /(?<![\w-])ease-in(?![\w-])/g],
+  ["duration-literal", /(?<![\w-])(?:duration|delay)-\[\s*[\d.]+m?s\s*\]/g],
+  ["duration-bare", new RegExp(`(?<![\\w-])(?:duration|delay)-(?:${TOKEN_NAMES})(?![\\w-])`, "g")],
+  ["viewport-zoom", /user-scalable\s*=\s*(?:no|0)|maximum-scale\s*=\s*1(?:\.0+)?(?![\d.])/g],
+  ["outline-neutral", /(?<![\w-])outline-(?:slate|zinc|neutral)-\d/g],
+];
+
+/** Every `<style>` body in a .svelte or .html file, or the whole .css, with its first line number. */
+function styleBlocks(source, file) {
+  if (file.endsWith(".css")) return [{ css: source, offset: 0 }];
+  const blocks = [];
+  for (const match of source.matchAll(/<style\b[^>]*>([\s\S]*?)<\/style>/g)) {
+    const start = match.index + match[0].indexOf(">") + 1;
+    blocks.push({ css: match[1], offset: lineOf(source, start) - 1 });
+  }
+  return blocks;
+}
+
+/** Rules as `{ selector, body, ancestors, line }`, walking the brace stack. */
+export function parseRules(css) {
+  const rules = [];
+  const stack = [];
+  let start = 0;
+  for (let i = 0; i < css.length; i++) {
+    const char = css[i];
+    if (char === "{") {
+      const prelude = css.slice(start, i).trim();
+      stack.push({ prelude, from: i + 1, line: lineOf(css, start + (css.slice(start).length - css.slice(start).trimStart().length)) });
+      start = i + 1;
+    } else if (char === "}") {
+      const open = stack.pop();
+      if (open) {
+        const body = css.slice(open.from, i);
+        rules.push({ selector: open.prelude, body, ancestors: stack.map((s) => s.prelude), line: open.line });
+      }
+      start = i + 1;
+    } else if (char === ";") {
+      start = i + 1;
+    }
+  }
+  return rules;
+}
+
+const hoverGated = (ancestors) =>
+  ancestors.some((p) => /^@media\b[^{]*hover\s*:\s*hover/i.test(p) || /^@(custom-variant|variant|utility|theme)\b/.test(p));
+
+function cssRules(source, file) {
+  const hits = [];
+  for (const { css, offset } of styleBlocks(source, file)) {
+    for (const rule of parseRules(css)) {
+      if (rule.selector.startsWith("@")) continue;
+      const line = rule.line + offset;
+      if (/:hover\b/.test(rule.selector) && !hoverGated(rule.ancestors)) {
+        hits.push({ rule: "raw-hover", line, snippet: rule.selector.slice(0, 80) });
+      }
+      const selectors = rule.selector.split(",").map((s) => s.trim());
+      const own = selectors.some((s) => /(^|[\s>+~])\.t-acc-panel$/.test(s) || /(^|[\s>+~])\.t-acc-panel(?=[:.\[])/.test(s));
+      if (own && /(?<![\w-])padding(?:-[a-z]+)*\s*:/.test(rule.body) && !selectors.some((s) => /t-acc-panel-/.test(s))) {
+        hits.push({ rule: "acc-panel-padding", line, snippet: `${rule.selector} { padding }` });
+      }
+      const root = selectors.some((s) => /^(?:body|html)$/.test(s));
+      if (root && /(?<![\w-])(?:-webkit-)?user-select\s*:\s*none|@apply[^;]*\bselect-none\b/.test(rule.body)) {
+        hits.push({ rule: "body-user-select", line, snippet: `${rule.selector} { user-select: none }` });
+      }
+    }
+  }
+  return hits;
+}
+
+function markupRules(source) {
+  const hits = [];
+  for (const match of source.matchAll(/<body\b[^>]*\bclass\s*=\s*["'{`][^"'`>]*\bselect-none\b/g)) {
+    hits.push({ rule: "body-user-select", line: lineOf(source, match.index), snippet: "<body class=\"select-none\">" });
+  }
+  for (const match of source.matchAll(/class\s*=\s*["'`{][^"'`>]*(?<![\w-])t-acc-panel(?![\w-])[^"'`>]*/g)) {
+    if (/(?:^|[\s:"'`{])-?p[xytblrse]?-[\w[\]./]+/.test(match[0].replace(/^class\s*=\s*["'`{]/, " "))) {
+      hits.push({ rule: "acc-panel-padding", line: lineOf(source, match.index), snippet: match[0].slice(0, 80) });
+    }
+  }
+  return hits;
+}
+
+/** The per-file rules. Returns `{ rule, line, snippet }` hits, each rule's message in `describe`. */
+export function checkFile(file, source) {
+  if (file.endsWith(".swift")) {
+    return scan(source, SWIFT_T_CLASS, "swift-t-class");
+  }
+  if (!STYLE_EXTENSIONS.some((ext) => file.endsWith(ext))) return [];
+  const clean = stripComments(source, file);
+  const plainTs = file.endsWith(".ts") || file.endsWith(".tsx");
+  const hits = LINE_RULES.filter(([rule]) => !(plainTs && rule === "ease-in")).flatMap(([rule, pattern]) => scan(clean, pattern, rule));
+  if (!plainTs) hits.push(...cssRules(clean, file));
+  if (!file.endsWith(".css")) hits.push(...markupRules(clean));
+  return hits.sort((a, b) => a.line - b.line);
+}
+
+export function describe(rule) {
+  return MESSAGES[rule];
+}
+
+/** Nearest package.json up from `file`, as a parsed object, using `read(path)` that returns text or null. */
+export function nearestManifest(file, read) {
+  const parts = file.split("/");
+  for (let depth = parts.length - 1; depth >= 0; depth--) {
+    const candidate = [...parts.slice(0, depth), "package.json"].join("/");
+    const text = read(candidate);
+    if (text) {
+      try {
+        return JSON.parse(text);
+      } catch {
+        return null;
+      }
+    }
+  }
+  return null;
+}
+
+export function dependsOnKit(manifest) {
+  if (!manifest) return false;
+  return ["dependencies", "devDependencies", "peerDependencies"].some((key) => {
+    const range = manifest[key]?.["@heyramzi/ui"];
+    return range && !range.startsWith("workspace:");
+  });
+}
+
+/**
+ * Whole-project checks on the judged files. `read(path)` gives text or null, `tracked` is every file in the repo.
+ * `files` are the judged ones: only a violation they touch is reported.
+ */
+export function checkProject(files, tracked, read) {
+  const hits = [];
+  const add = (file, rule, line, snippet) => hits.push({ file, rule, line, snippet });
+  const trackedSet = new Set(tracked);
+
+  for (const file of files) {
+    const name = file.split("/").at(-1);
+    const isKitApp = () => dependsOnKit(nearestManifest(file, read));
+
+    if (/(^|\/)src\/lib\/components\/ui\/[^/]+\.svelte$/.test(file) && isKitApp()) {
+      add(file, "local-shadcn", 1, file);
+    }
+    if (name === "components.json" && isKitApp() && /shadcn-svelte/.test(read(file) ?? "")) {
+      add(file, "local-shadcn", 1, "components.json (shadcn-svelte)");
+    }
+    if (/(^|\/)src\/app\.css$/.test(file) && isKitApp()) {
+      const css = stripComments(read(file) ?? "", file);
+      if (!/@source\s+["'][^"']*(?:@heyramzi\/ui\/src|packages\/ui\/src|\/ui\/src)/.test(css)) {
+        add(file, "ui-source", 1, "no @source for @heyramzi/ui/src");
+      }
+    }
+    if (/^(?:svelte|kit)\.config\.(js|ts|mjs)$/.test(name)) {
+      const config = stripComments(read(file) ?? "", file);
+      if (/adapter-cloudflare/.test(config) && !/relative\s*:\s*false/.test(config)) {
+        add(file, "cloudflare-relative", 1, "adapter-cloudflare without paths.relative: false");
+      }
+    }
+  }
+
+  const prefixes = new Set();
+  for (const file of [...files, ...tracked.filter((f) => /\/\+(server|page)\.(ts|js|svelte)$/.test(f) && files.includes(f))]) {
+    const staticAt = file.match(/^(.*?)(?:^|\/)static\/(.+)$/) ?? file.match(/^()static\/(.+)$/);
+    if (staticAt) prefixes.add(staticAt[1] === undefined ? "" : staticAt[1].replace(/\/$/, ""));
+    const routeAt = file.match(/^(.*?)\/?src\/routes\//);
+    if (routeAt) prefixes.add(routeAt[1].replace(/\/$/, ""));
+  }
+  const judged = new Set(files);
+  for (const prefix of prefixes) {
+    const base = prefix ? `${prefix}/` : "";
+    for (const file of tracked) {
+      if (!file.startsWith(`${base}src/routes/`)) continue;
+      const route = file.slice(`${base}src/routes/`.length);
+      const match = route.match(/^(.*?)\/?\+(?:server\.(?:ts|js)|page\.svelte)$/);
+      if (!match) continue;
+      const url = match[1].split("/").filter((seg) => !/^\(.*\)$/.test(seg)).join("/");
+      if (!url || /[[\]]/.test(url)) continue;
+      const twin = `${base}static/${url}`;
+      if (trackedSet.has(twin) && (judged.has(twin) || judged.has(file))) {
+        add(twin, "static-shadow", 1, `static/${url} shadows ${file}`);
+      }
+    }
+  }
+  return hits;
+}
+
+/** Skip generated and vendored trees. */
+export function ignoredPath(file, extra = []) {
+  const parts = file.split("/");
+  return [...DEFAULT_IGNORED, ...extra].some((entry) => parts.includes(entry));
+}
+
+export function report(hits) {
+  const byRule = new Map();
+  for (const hit of hits) {
+    if (!byRule.has(hit.rule)) byRule.set(hit.rule, []);
+    byRule.get(hit.rule).push(hit);
+  }
+  const blocks = [...byRule].map(
+    ([rule, list]) =>
+      `[${rule}] ${MESSAGES[rule]}\n${list.map((hit) => `  ${hit.file}:${hit.line}  ${hit.snippet}`).join("\n")}`,
+  );
+  return `ui-rules: ${hits.length} violation(s)\n\n${blocks.join("\n\n")}`;
+}
+
+/** Names the repo makes a bare `duration-NAME` class for: the kit's design import, or its own `--transition-duration-NAME`. */
+export function durationNames(tracked, read) {
+  const names = new Set();
+  for (const file of tracked.filter((f) => f.endsWith(".css") && !ignoredPath(f))) {
+    const css = read(file) ?? "";
+    if (/@import\s+["']@heyramzi\/ui\/design["']/.test(css)) {
+      for (const name of TOKEN_NAMES.split("|").filter((n) => n !== "stagger")) names.add(name);
+    }
+    for (const match of css.matchAll(/--transition-duration-([\w-]+)\s*:/g)) names.add(match[1]);
+  }
+  return names;
+}
+
+/** Drops `duration-bare` hits the repo resolves. */
+export function resolvedDurations(hits, names) {
+  return hits.filter((hit) => !(hit.rule === "duration-bare" && names.has(hit.snippet.replace(/^(?:duration|delay)-/, ""))));
+}