trykeyline 0.1.1 → 0.1.2

package/plugins/keyline/skills/keyline/scripts/check/files.mjs

@@ -1,44 +1,88 @@
 /**
- * Which files the detector reads. The same skips as scan.mjs, so the two never
- * disagree about what counts as the project's interface.
+ * Which files Keyline reads. One walker for the detector (check.mjs) and the
+ * inventory (scan.mjs), so the two skip the same folders and match ignores the
+ * same way; each passes only the extensions and filters its job needs.
  */
 import { readdirSync, statSync } from "node:fs";
-import { extname, join, relative, sep } from "node:path";
+import { basename, extname, join, relative, sep } from "node:path";
 
+/** Dependencies, build output, served assets and reports. Dot-folders are skipped wholesale, bar `.storybook`. */
 export const SKIP_DIRS = new Set([
-  "node_modules", ".git", ".next", ".nuxt", ".output", ".svelte-kit", ".turbo",
-  ".vercel", ".cache", "dist", "build", "out", "coverage", "vendor",
-  "storybook-static", ".claude", ".agents", "public", "static",
+  "node_modules", "dist", "build", "out", "coverage", "vendor", "storybook-static", "public", "static",
+  "keyline-report", "smoke-report",
 ]);
 export const STYLE = new Set([".css", ".scss", ".sass", ".less", ".pcss"]);
 export const MARKUP = new Set([".tsx", ".jsx", ".ts", ".js", ".mjs", ".vue", ".svelte", ".astro", ".html", ".mdx"]);
-const SKIP_FILES = /\.(min|d|test|spec|stories|config)\.[a-z]+$|^(eslint|postcss|tailwind|next|vite|vitest|jest|playwright)\.config\./;
+/** Minified, declaration, test and story files: generated, or not the interface. */
+export const GENERATED = /\.(min|test|spec|stories)\.|\.d\.[a-z]+$/;
+/** Tool configs. Not the interface, though a Tailwind config holds theme values. */
+export const CONFIG = /\.config\.[a-z]+$|^(eslint|postcss|tailwind|next|vite|vitest|jest|playwright)\.config\./;
 
-/** Every style and markup file under `paths`, relative to `root`, minus ignores. */
-export function collect(root, paths, ignores) {
+const clean = (ig) => ig.replace(/\\/g, "/").replace(/^\.\//, "").replace(/\/+$/, "");
+
+/** A test for paths relative to the root: `src/content` drops `src/content/a.tsx`, never `src/contentful`. */
+export function ignoredBy(ignores = []) {
+  const list = ignores.map(clean).filter(Boolean);
+  return (rel) => list.some((ig) => rel === ig || rel.startsWith(ig + "/"));
+}
+
+/**
+ * Every file under `paths` whose extension is in `accept` and whose name `skip`
+ * doesn't match, up to `maxSize` bytes (bigger is a bundle, not source). Folders
+ * in SKIP_DIRS and dot-folders are passed over unless named in `paths`;
+ * symlinked folders aren't followed.
+ * @returns {{ abs: string, rel: string, ext: string }[]} rel is relative to root, with `/`
+ */
+export function walk(root, { paths = [root], accept, skip = GENERATED, maxSize = 400_000, ignores = [] }) {
   const out = [];
-  const ignored = (rel) => ignores.some((ig) => ig && (rel === ig || rel.startsWith(ig.endsWith("/") ? ig : ig + "/")));
-  const visit = (abs) => {
-    const rel = relative(root, abs).split(sep).join("/");
-    if (rel && ignored(rel)) return;
-    let st;
+  const ignored = ignoredBy(ignores);
+  const rel = (abs) => relative(root, abs).split(sep).join("/");
+  const file = (abs, name, size) => {
+    const ext = extname(name);
+    if (!accept.has(ext) || skip?.test(name)) return;
+    if ((size ?? statSync(abs).size) > maxSize) return;
+    out.push({ abs, rel: rel(abs) || name, ext });
+  };
+  const dir = (abs) => {
+    let entries;
     try {
-      st = statSync(abs);
+      entries = readdirSync(abs, { withFileTypes: true });
     } catch {
       return;
     }
-    if (st.isDirectory()) {
-      const name = abs.split(sep).pop();
-      if (rel && (SKIP_DIRS.has(name) || (name.startsWith(".") && name !== ".storybook"))) return;
-      for (const e of readdirSync(abs)) visit(join(abs, e));
-      return;
+    for (const e of entries) {
+      const child = join(abs, e.name);
+      if (ignored(rel(child))) continue;
+      if (e.isDirectory()) {
+        if (!SKIP_DIRS.has(e.name) && (!e.name.startsWith(".") || e.name === ".storybook")) dir(child);
+      } else {
+        try {
+          file(child, e.name);
+        } catch {}
+      }
     }
-    const ext = extname(abs);
-    if (!(STYLE.has(ext) || MARKUP.has(ext))) return;
-    if (SKIP_FILES.test(abs.split(sep).pop())) return;
-    if (st.size > 400_000) return; // generated bundles, not source
-    out.push({ abs, rel: rel || abs.split(sep).pop(), ext, kind: STYLE.has(ext) ? "style" : "markup" });
   };
-  for (const p of paths) visit(p);
+  for (const p of paths) {
+    const r = rel(p);
+    if (r && ignored(r)) continue;
+    let st;
+    try {
+      st = statSync(p);
+    } catch {
+      continue;
+    }
+    if (st.isDirectory()) dir(p);
+    else file(p, basename(p), st.size);
+  }
   return out;
 }
+
+const DETECTOR_SKIP = new RegExp(`${GENERATED.source}|${CONFIG.source}`);
+
+/** The detector's files: style and markup, minus generated files and tool configs. */
+export function collect(root, paths, ignores) {
+  return walk(root, { paths, ignores, accept: new Set([...STYLE, ...MARKUP]), skip: DETECTOR_SKIP }).map((f) => ({
+    ...f,
+    kind: STYLE.has(f.ext) ? "style" : "markup",
+  }));
+}

package/plugins/keyline/skills/keyline/scripts/check/markup.mjs

@@ -57,7 +57,7 @@ export function readMarkup(source, ext) {
   text = text.replace(/<!--[\s\S]*?-->/g, (m) => m.replace(/[^\n]/g, " "));
   const at = lineIndex(text);
 
-  const classLists = []; // { value, offset, line, tokens: [{...splitClass, line}] }
+  const classLists = []; // { line, tokens: [{...splitClass, line}], tag }
   const seen = new Set();
   const addList = (value, offset, origin) => {
     if (seen.has(offset)) return;
@@ -66,7 +66,7 @@ export function readMarkup(source, ext) {
     const re = /\S+/g;
     let m;
     while ((m = re.exec(value))) tokens.push({ ...splitClass(m[0]), line: at(offset + m.index) });
-    if (tokens.length) classLists.push({ value, offset, line: at(offset), tokens, origin, tag: origin === "attribute" ? tagAround(offset, value.length) : "" });
+    if (tokens.length) classLists.push({ line: at(offset), tokens, tag: origin === "attribute" ? tagAround(offset, value.length) : "" });
   };
 
   /** The opening tag a class attribute sits in, for rules that need its element or attributes. */
@@ -93,7 +93,7 @@ export function readMarkup(source, ext) {
       addList(s[1] === "`" ? staticParts(s[2]) : s[2], open + 1 + s.index + 1, "helper");
     }
   }
-  if (!isHtmlLike || ext !== ".html") {
+  if (ext !== ".html") {
     for (const m of text.matchAll(EXPR_STRING)) {
       const value = m[2];
       if (value.length < 3 || !CLASSY.test(value) || !TAILWINDISH.test(value)) continue;

package/plugins/keyline/skills/keyline/scripts/check/rules.mjs

@@ -226,8 +226,16 @@ const colorRules = [
         // recipe, not a palette colour; the recipe itself is what depth law 4 wants
         // kept in one definition. A tinted shadow (a blue glow) still counts.
         if (/^(box-shadow|text-shadow)$/.test(d.prop) && neutralOnly(d.value)) continue;
+        // Gradient stops and filter lights only exist inside SVG artwork, which colour law 1 exempts.
+        if (/^(stop-color|flood-color|lighting-color)$/.test(d.prop)) continue;
         const c = literalColor(d.value);
-        if (c) out.push({ ...where(d), severity: "warning", message: `\`${c}\` typed into \`${d.prop}\`${d.inline ? " in an inline style" : ""}. Give it a token named for its job (a text tier, a border, a status), so a theme or a contrast fix changes it once.` });
+        if (!c) continue;
+        // fill and stroke paint SVG: artwork (exempt) or an icon (should be currentColor). A regex can't tell which.
+        if (/^(fill|stroke)$/.test(d.prop)) {
+          out.push({ ...where(d), severity: "info", message: `\`${c}\` painted into \`${d.prop}\`. Inside artwork marked \`role="img"\` that's fine (colour law 1); on an icon, use \`currentColor\` so it follows its label.` });
+          continue;
+        }
+        out.push({ ...where(d), severity: "warning", message: `\`${c}\` typed into \`${d.prop}\`${d.inline ? " in an inline style" : ""}. Give it a token named for its job (a text tier, a border, a status), so a theme or a contrast fix changes it once.` });
       }
       for (const c of tw(facts, (b) => TAILWIND_ARBITRARY_COLOR.test(b))) {
         out.push({ ...where(c), severity: "warning", message: `\`${c.base}\` puts a raw colour in a class. Map it to a token named for its job.` });

package/plugins/keyline/skills/keyline/scripts/check.mjs

@@ -92,8 +92,8 @@ export function gather(root, files) {
       const VIEWPORT_VALUE = /<meta\b[^>]*\bviewport\b[^>]*>|["'`][^"'`\n<>]*width\s*=\s*device-width[^"'`\n<>]*["'`]/gi;
       for (const v of m.text.matchAll(VIEWPORT_VALUE)) for (const z of v[0].matchAll(LOCK)) facts.zoomLocks.push({ file: f.rel, line: at(v.index + z.index) });
       for (const z of m.text.matchAll(/\bmaximumScale\s*:\s*1\b|\buserScalable\s*:\s*false\b/g)) facts.zoomLocks.push({ file: f.rel, line: at(z.index) });
-      if (MOTION_IMPORT.test(m.text)) {
-        const imp = m.text.match(MOTION_IMPORT);
+      const imp = m.text.match(MOTION_IMPORT);
+      if (imp) {
         noteAnimation({ file: f.rel, line: at(imp.index) });
         for (const d of m.text.matchAll(/\bduration\s*:\s*(\d*\.?\d+)\b/g)) {
           // A spring's duration is a settling time set by its character, not a tier.

package/plugins/keyline/skills/keyline/scripts/contrast.mjs

@@ -150,4 +150,6 @@ if (ladder) {
 if (rest.length !== 2) die("give a foreground and a background (or --ladder)");
 const r = ratio(rest[0], rest[1]);
 console.log(`${r >= floor ? "✓" : "✗"} ${fmt(r)} (floor ${floor}:1)`);
+// 1:1 means the two colours came out identical — nearly always the arguments, not the design.
+if (r < 1.01) console.error(`contrast: ${rest[0]} and ${rest[1]} come out as the same colour. Check the order: <fg> <bg>, or --over <backdrop> <fg> <bg>, or --ladder <bg> <fg>…`);
 process.exit(r >= floor ? 0 : 2);

package/plugins/keyline/skills/keyline/scripts/scan.mjs

@@ -16,8 +16,9 @@
  * at runtime or a class built by string concatenation. When the summary and the
  * code disagree, the code wins — open the file the summary points at.
  */
-import { readdirSync, readFileSync, statSync, existsSync } from "node:fs";
-import { join, relative, extname, basename } from "node:path";
+import { readFileSync, existsSync } from "node:fs";
+import { join, basename, resolve } from "node:path";
+import { walk, STYLE as CHECKED_STYLE, MARKUP as CHECKED_MARKUP } from "./check/files.mjs";
 
 const argv = process.argv.slice(2);
 const json = argv.includes("--json");
@@ -33,37 +34,14 @@ if (!existsSync(root)) {
   process.exit(1);
 }
 
-const SKIP_DIRS = new Set([
-  "node_modules", ".git", ".next", ".nuxt", ".output", ".svelte-kit", ".turbo",
-  ".vercel", ".cache", "dist", "build", "out", "coverage", "vendor",
-  "storybook-static", ".claude", "public", "static",
-]);
-const STYLE = new Set([".css", ".scss", ".sass", ".less", ".pcss", ".styl"]);
-const MARKUP = new Set([".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".vue", ".svelte", ".astro", ".html", ".mdx"]);
-
-/* ── Walk ─────────────────────────────────────────────────────────────────── */
-
-const files = [];
-(function walk(dir) {
-  let entries;
-  try {
-    entries = readdirSync(dir, { withFileTypes: true });
-  } catch {
-    return;
-  }
-  for (const e of entries) {
-    if (e.name.startsWith(".") && e.isDirectory() && e.name !== ".storybook") continue;
-    const path = join(dir, e.name);
-    if (ignores.some((ig) => ig && relative(root, path).startsWith(ig))) continue;
-    if (e.isDirectory()) {
-      if (!SKIP_DIRS.has(e.name)) walk(path);
-    } else if (STYLE.has(extname(e.name)) || MARKUP.has(extname(e.name))) {
-      if (/\.min\.|\.d\.ts$|\.test\.|\.spec\.|\.stories\./.test(e.name)) continue;
-      if (statSync(path).size > 1_000_000) continue;
-      files.push(path);
-    }
-  }
-})(root);
+/*
+ * The detector's walker and folder skips, read wider: an inventory wants every
+ * hand-written value, so it also reads Stylus and CommonJS, keeps tool configs
+ * (a Tailwind config is where a theme is declared) and allows files up to 1 MB.
+ */
+const STYLE = new Set([...CHECKED_STYLE, ".styl"]);
+const MARKUP = new Set([...CHECKED_MARKUP, ".cjs"]);
+const files = walk(resolve(root), { accept: new Set([...STYLE, ...MARKUP]), maxSize: 1_000_000, ignores });
 
 /* ── Tallies ──────────────────────────────────────────────────────────────── */
 
@@ -74,7 +52,7 @@ function count(bucket, value, file) {
   tallies[bucket] ??= new Map();
   const entry = tallies[bucket].get(v) ?? { n: 0, files: new Set() };
   entry.n++;
-  entry.files.add(relative(root, file));
+  entry.files.add(file);
   tallies[bucket].set(v, entry);
 }
 
@@ -91,7 +69,7 @@ const classWords = new Map();
 const signals = {};
 function signal(name, file) {
   signals[name] ??= new Set();
-  signals[name].add(relative(root, file));
+  signals[name].add(file);
 }
 
 /** Tailwind's scale names, so `text-sm` counts as a size and `text-red-500` doesn't. */
@@ -156,9 +134,9 @@ const SIGNALS = [
   ["numerals: tabular-nums", /tabular-nums|font-variant-numeric/],
 ];
 
-for (const file of files) {
-  const text = readFileSync(file, "utf8");
-  const kind = STYLE.has(extname(file)) ? "style" : "markup";
+for (const { abs, rel: file, ext } of files) {
+  const text = readFileSync(abs, "utf8");
+  const kind = STYLE.has(ext) ? "style" : "markup";
 
   for (const [bucket, re, group, only] of RULES) {
     if (only !== "all" && only !== kind) continue;
@@ -175,7 +153,7 @@ for (const file of files) {
     if (m[1].startsWith("--tw-")) continue;
     const entry = props.get(m[1]) ?? { values: [], files: new Set() };
     if (entry.values.length < 4 && !entry.values.includes(m[2].trim())) entry.values.push(m[2].trim());
-    entry.files.add(relative(root, file));
+    entry.files.add(file);
     props.set(m[1], entry);
   }
   if (kind === "markup") {
@@ -196,14 +174,20 @@ for (const file of files) {
  * but it's the difference between "unused" and "used in 40 files".
  */
 const NAMESPACES = ["color", "font", "text", "radius", "shadow", "ease", "animate", "container", "spacing", "tracking", "leading", "breakpoint", "blur", "inset-shadow", "drop-shadow"];
-function utilityUses(prop) {
+/** Class-word uses by every tail after a hyphen: `hover:text-ink-soft` counts for `ink-soft` and `soft`. */
+const bySuffix = new Map();
+for (const [word, c] of classWords) {
+  for (let i = word.indexOf("-"); i >= 0; i = word.indexOf("-", i + 1)) {
+    const tail = word.slice(i + 1);
+    bySuffix.set(tail, (bySuffix.get(tail) ?? 0) + c);
+  }
+}
+const utilityCount = new Map();
+for (const prop of props.keys()) {
   const ns = NAMESPACES.find((n) => prop.startsWith(`--${n}-`));
-  if (!ns) return 0;
-  const name = prop.slice(ns.length + 3);
-  let n = 0;
-  for (const [word, c] of classWords) if (word.endsWith(`-${name}`) && word !== name) n += c;
-  return n;
+  utilityCount.set(prop, ns ? (bySuffix.get(prop.slice(ns.length + 3)) ?? 0) : 0);
 }
+const utilityUses = (prop) => utilityCount.get(prop) ?? 0;
 const uses = (prop) => (propUses.get(prop) ?? 0) + utilityUses(prop);
 
 /* ── Stack ────────────────────────────────────────────────────────────────── */

package/plugins/keyline/skills/keyline/system/guide.md

@@ -33,7 +33,7 @@ Five places projects have quietly broken a law:
 - **One token doing two jobs.** A grey used for borders and text: a border needs 3:1, text 4.5:1, and one value rarely serves both. Record the coupling as an open issue; don't split it yet.
 - **A job with no token.** Captions at six greys, durations typed inline. Propose a name in the project's style (`design-md.md` says how to detect it) and mark it `proposed`. Where a whole domain has no tokens — no type tokens, no motion tokens — record that as one open issue, not one per role; that domain's refining pass proposes a full set in the project's style, marked `proposed`.
 - **Roles the list doesn't have.** A `keyline`, a `pull-quote`, a `kicker`: record each as a project role under its nearest canonical parent, with what separates it — size, weight, leading, colour or a rule. If nothing does, that's a finding.
-- **Boxes as the default.** Every section, stat and list in a card, cards inside cards, a bento grid of unlike sections, tinted strips behind labels, uppercase eyebrows, several chip shapes, a second hue that calls for attention (a hue family answering what, where or who under `product` is not one), success colour on done steps where completion isn't the news (a sequence the reader passes through, not a board or queue). Count the boxes per main screen and list each that holds more than one object (depth law 2, layout law 3). If the user has a reference interface they've already approved, screenshot each main screen beside it; the gaps are open issues.
+- **Boxes as the default.** Every section, stat and list in a card, cards inside cards, a bento grid of unlike sections, tinted strips behind labels, uppercase eyebrows (outside an `expressive` eyebrow role), several chip shapes, a second hue that calls for attention (a hue family answering what, where or who under `product` is not one), success colour on done steps where completion isn't the news (a sequence the reader passes through, not a board or queue). Count the boxes per main screen and list each that holds more than one object (depth law 2, layout law 3); a panel that layout law 3's table gives a settings or form group is not one. If the user has a reference interface they've already approved, screenshot each main screen beside it; the gaps are open issues.
 - **Values on no ladder.** Twenty-three font sizes, fourteen radii. Cluster them by usage, propose the ladder, list the strays that could snap to a neighbour unseen.
 
 Compute contrast; don't estimate it: