trykeyline 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,67 @@
+/**
+ * What the detector takes from DESIGN.md: the preset (which turns some rules on
+ * or off), the motion ladder and the z-index ladder. Everything else in the
+ * file is for the agent; the detector only needs what changes a verdict.
+ */
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+const PRESETS = ["editorial", "product", "expressive", "glass"];
+
+function section(md, heading) {
+  const m = md.match(new RegExp(`^##\\s+${heading}\\b[^\\n]*\\n([\\s\\S]*?)(?=^##\\s|(?![\\s\\S]))`, "mi"));
+  return m ? m[1] : "";
+}
+
+export function readDesign(root) {
+  const name = existsSync(root) ? readdirSync(root).find((f) => f.toLowerCase() === "design.md") : null;
+  if (!name) return { found: false, preset: null, durations: null, roles: new Map(), zLadder: null };
+  const md = readFileSync(join(root, name), "utf8");
+  const headingLine = (h) => {
+    const i = md.search(new RegExp(`^##\\s+${h}\\b`, "mi"));
+    return i < 0 ? 1 : md.slice(0, i).split("\n").length;
+  };
+
+  const profile = section(md, "Profile");
+  const presetRow = profile.split("\n").find((l) => /^\|\s*Preset\s*\|/i.test(l)) ?? "";
+  const preset = PRESETS.find((p) => new RegExp(`\`${p}\`|\\b${p}\\b`).test(presetRow.split("|").slice(2).join("|"))) ?? null;
+
+  // Durations: every ms / s value in the Motion section's table rows. Rows on a
+  // canonical duration.* role (before any "Named exemptions" line) are also kept by
+  // role, so the detector can check they grow with the size of the change.
+  const motion = section(md, "Motion");
+  const durations = new Set();
+  const roles = new Map();
+  let inExemptions = false;
+  for (const line of motion.split("\n")) {
+    if (!line.startsWith("|")) {
+      if (/exemption/i.test(line)) inExemptions = true;
+      continue;
+    }
+    for (const m of line.matchAll(/(?<![\w.])(\d+(?:\.\d+)?)(ms|s)\b/g)) {
+      const ms = m[2] === "s" ? Math.round(parseFloat(m[1]) * 1000) : Math.round(parseFloat(m[1]));
+      durations.add(ms);
+      const role = line.split("|")[1]?.match(/duration\.(\w+)/)?.[1];
+      if (!inExemptions && role && !roles.has(role)) roles.set(role, ms);
+    }
+  }
+
+  // z-index: rows whose role is z.*, or a project role whose name is a z utility
+  // or mentions one — their values are the ladder.
+  const layout = section(md, "Layout");
+  const zLadder = new Set();
+  for (const row of layout.split("\n").filter((l) => /^\|\s*`?z\./.test(l) || (l.startsWith("|") && /`-?z-\[?-?\d|`z\./.test(l)))) {
+    const cells = row.split("|").slice(1, -1).map((c) => c.trim());
+    for (const c of cells.slice(1)) for (const m of c.matchAll(/(?<![\w.#-])(-?\d+)(?![\w.%])/g)) zLadder.add(Number(m[1]));
+  }
+
+  return {
+    found: true,
+    file: name,
+    lines: { motion: headingLine("Motion"), layout: headingLine("Layout") },
+    preset,
+    durations: durations.size ? durations : null,
+    roles,
+    zLadder: zLadder.size ? zLadder : null,
+  };
+}

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

@@ -0,0 +1,44 @@
+/**
+ * Which files the detector reads. The same skips as scan.mjs, so the two never
+ * disagree about what counts as the project's interface.
+ */
+import { readdirSync, statSync } from "node:fs";
+import { extname, join, relative, sep } from "node:path";
+
+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",
+]);
+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\./;
+
+/** Every style and markup file under `paths`, relative to `root`, minus ignores. */
+export function collect(root, paths, 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;
+    try {
+      st = statSync(abs);
+    } 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;
+    }
+    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);
+  return out;
+}

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

@@ -0,0 +1,149 @@
+/**
+ * What the detector needs from markup and script files, found without a parser:
+ * class lists (attributes, class helpers, string constants), inline styles,
+ * <style> blocks, CSS-in-JS templates, and the text of buttons and links.
+ *
+ * Regexes rather than an AST so it reads any framework's files the same way
+ * and never fails on syntax it doesn't know. The cost is precision: a class
+ * built by concatenation is invisible, and a string that only looks like a
+ * class list can be read as one. Rules are written to tolerate both.
+ */
+import { blankComments, lineIndex, parseCss, parseInlineStyle } from "./css.mjs";
+
+const CLASS_ATTR = /\b(?:class|className|class:list)\s*=\s*(?:"([^"]*)"|'([^']*)'|\{\s*"([^"]*)"\s*\}|\{\s*'([^']*)'\s*\}|\{\s*`([^`]*)`\s*\})/g;
+const CLASS_CALL = /\b(?:cn|clsx|cx|classNames|classnames|twMerge|twJoin|cva|tv)\s*\(/g;
+const EXPR_STRING = /(?:[=:(,\[?]|\breturn|&&|\|\|)\s*(["'`])((?:(?!\1)[^\\\n]|\\.)*)\1/g;
+const CLASSY = /^[\w\s:\-\[\]\/.#%(),!&>*@=+'"~]*$/;
+const TAILWINDISH = /(?:^|\s)!?(?:[\w-]+:)*-?(?:p[xytrbl]?|m[xytrbl]?|text|bg|border|rounded|flex|grid|gap|w|h|min-w|min-h|max-w|max-h|font|leading|tracking|shadow|z|opacity|transition|duration|ease|animate|backdrop|ring|outline|uppercase|italic|hidden|block|inline|absolute|relative|fixed|sticky|top|left|right|bottom|inset|items|justify|self|space|overflow|cursor|select|pointer|translate|scale|rotate|blur|from|to|via|fill|stroke)(?:-[\w.\[\]#%/():,-]+)?(?=\s|$)/;
+
+/** Split a class token into its variants and its utility, respecting [arbitrary:values]. */
+export function splitClass(token) {
+  let t = token.replace(/^!/, "").replace(/!$/, "");
+  let depth = 0;
+  let cut = -1;
+  for (let i = 0; i < t.length; i++) {
+    if (t[i] === "[" || t[i] === "(") depth++;
+    else if (t[i] === "]" || t[i] === ")") depth--;
+    else if (t[i] === ":" && depth === 0) cut = i;
+  }
+  return { variants: cut < 0 ? [] : t.slice(0, cut).split(":"), base: cut < 0 ? t : t.slice(cut + 1), raw: token };
+}
+
+function balanced(text, open, openCh, closeCh) {
+  let depth = 0;
+  let quote = null;
+  for (let i = open; i < text.length; i++) {
+    const c = text[i];
+    if (quote) {
+      if (c === "\\") i++;
+      else if (c === quote) quote = null;
+      continue;
+    }
+    if (c === '"' || c === "'" || c === "`") quote = c;
+    else if (c === openCh) depth++;
+    else if (c === closeCh && --depth === 0) return i;
+  }
+  return -1;
+}
+
+/** Static parts of a template literal body; ${…} becomes spaces of equal length. */
+const staticParts = (s) => s.replace(/\$\{[^}]*\}/g, (m) => " ".repeat(m.length));
+
+export function readMarkup(source, ext) {
+  // Blank JS comments only in script-like files; in HTML `//` is just text.
+  const isHtmlLike = ext === ".html" || ext === ".vue" || ext === ".svelte" || ext === ".astro";
+  let text = blankComments(source);
+  if (!isHtmlLike) text = text.replace(/(^|[^:"'`\\])\/\/[^\n]*/g, (m, pre) => pre + " ".repeat(m.length - pre.length));
+  text = text.replace(/<!--[\s\S]*?-->/g, (m) => m.replace(/[^\n]/g, " "));
+  const at = lineIndex(text);
+
+  const classLists = []; // { value, offset, line, tokens: [{...splitClass, line}] }
+  const seen = new Set();
+  const addList = (value, offset, origin) => {
+    if (seen.has(offset)) return;
+    seen.add(offset);
+    const tokens = [];
+    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) : "" });
+  };
+
+  /** The opening tag a class attribute sits in, for rules that need its element or attributes. */
+  const tagAround = (offset, length) => {
+    let lt = offset;
+    while (lt > 0 && !(text[lt] === "<" && /[A-Za-z]/.test(text[lt + 1] ?? ""))) lt--;
+    const rest = text.slice(offset + length, offset + length + 600);
+    const gt = rest.search(/(?<![=-])>/);
+    return text.slice(lt, offset + length + (gt < 0 ? 0 : gt + 1));
+  };
+
+  for (const m of text.matchAll(CLASS_ATTR)) {
+    const idx = m.slice(1).findIndex((g) => g !== undefined);
+    const value = m[idx + 1];
+    const offset = m.index + m[0].indexOf(value, m[0].indexOf("="));
+    addList(idx === 4 ? staticParts(value) : value, offset, "attribute");
+  }
+  for (const m of text.matchAll(CLASS_CALL)) {
+    const open = m.index + m[0].length - 1;
+    const close = balanced(text, open, "(", ")");
+    if (close < 0) continue;
+    const args = text.slice(open + 1, close);
+    for (const s of args.matchAll(/(["'`])((?:(?!\1)[^\\]|\\.)*)\1/g)) {
+      addList(s[1] === "`" ? staticParts(s[2]) : s[2], open + 1 + s.index + 1, "helper");
+    }
+  }
+  if (!isHtmlLike || 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;
+      if (/^[a-z]+(-[a-z]+)*$/.test(value) && !/\s/.test(value) && !/^(uppercase|italic|transition-all|h-screen|min-h-screen|outline-none)$/.test(value)) continue;
+      addList(m[1] === "`" ? staticParts(value) : value, m.index + m[0].lastIndexOf(m[1] + value) + 1, "string");
+    }
+  }
+
+  // Styles: <style> blocks, style="…" attributes, style={{…}} objects, CSS-in-JS templates.
+  const css = [];
+  for (const m of text.matchAll(/<style\b[^>]*>([\s\S]*?)<\/style>/gi)) {
+    const body = source.slice(m.index + m[0].indexOf(">") + 1, m.index + m[0].lastIndexOf("</"));
+    css.push(parseCss(body, at(m.index + m[0].indexOf(">") + 1)));
+  }
+  const inline = [];
+  for (const m of text.matchAll(/\bstyle\s*=\s*(?:"([^"]*)"|'([^']*)')/g)) {
+    const body = m[1] ?? m[2];
+    if (body.includes(":")) inline.push(...parseInlineStyle(body, at(m.index)));
+  }
+  for (const m of text.matchAll(/\bstyle\s*=\s*\{\{/g)) {
+    const open = m.index + m[0].length - 1;
+    const close = balanced(text, open, "{", "}");
+    if (close < 0) continue;
+    const body = text.slice(open + 1, close);
+    for (const p of body.matchAll(/([A-Za-z]+)\s*:\s*("[^"]*"|'[^']*'|`[^`]*`|-?[\d.]+)/g)) {
+      const prop = p[1].replace(/[A-Z]/g, (c) => "-" + c.toLowerCase());
+      const value = p[2].replace(/^["'`]|["'`]$/g, "");
+      inline.push({ prop, value, line: at(open + 1 + p.index), selector: "[style]", atRules: [], block: null, inline: true });
+    }
+  }
+  for (const m of text.matchAll(/\b(?:styled(?:\.\w+|\([^)]*\))|css|createGlobalStyle|keyframes|injectGlobal)\s*`([^`]*)`/g)) {
+    const bodyOffset = m.index + m[0].indexOf("`") + 1;
+    css.push(parseCss(`x{${staticParts(m[1])}}`, at(bodyOffset)));
+  }
+
+  // Visible text of buttons and links, for the copy rules.
+  const labels = [];
+  for (const m of text.matchAll(/<(button|Button|a|Link)\b[^>]*>\s*([^<>{}]+?)\s*<\/\1>/g)) {
+    labels.push({ element: m[1], text: m[2].replace(/\s+/g, " ").trim(), line: at(m.index + m[0].indexOf(m[2])) });
+  }
+
+  // Navigation blocks: how many links each writes out, and whether it groups them.
+  // Links rendered from an array (`items.map`) are invisible here, so the count is a floor.
+  const navs = [];
+  for (const m of text.matchAll(/<nav\b[^>]*>([\s\S]*?)<\/nav>/g)) {
+    const body = m[1];
+    const links = (body.match(/<(?:a|Link|NavLink)\b/g) ?? []).length;
+    const grouped = /<details\b|<h[2-6]\b|role\s*=\s*["']group|<section\b|<fieldset\b/.test(body) || (body.match(/<ul\b/g) ?? []).length > 1;
+    navs.push({ line: at(m.index), links, grouped });
+  }
+
+  return { text, classLists, css, inline, labels, navs };
+}