@designtools/adherence 0.0.0-stage → 0.1.1

package/dist/chunk-7FM4ZQLW.js

@@ -0,0 +1,1030 @@
+// src/config.ts
+import { existsSync, readFileSync } from "fs";
+import { dirname, relative, resolve } from "path";
+var CONFIG_FILE = "designtools.json";
+var UsageError = class extends Error {
+};
+var DEFAULT_INCLUDE = ["app/**/*.{tsx,jsx,ts,js}", "src/**/*.{tsx,jsx,ts,js}"];
+var DEFAULT_EXCLUDE = [
+  "app/design/**",
+  "src/app/design/**",
+  // the (design) route group, where the skills put the docs and every other design page
+  "app/(design)/**",
+  "src/app/(design)/**",
+  "**/node_modules/**",
+  "**/*.d.ts",
+  "**/*.{test,spec}.*",
+  "**/__tests__/**",
+  "**/{test,tests,e2e}/**",
+  "**/*.{fixtures,examples,stories}.*",
+  "**/{fixtures,examples}/**"
+];
+function loadConfig(flags) {
+  const root = resolve(flags.root ?? ".");
+  const path = resolve(root, CONFIG_FILE);
+  let file = {};
+  if (existsSync(path)) {
+    try {
+      file = JSON.parse(readFileSync(path, "utf8"));
+    } catch (e) {
+      throw new UsageError(`${CONFIG_FILE} is not valid JSON: ${e.message}`);
+    }
+  }
+  let manifest;
+  if (flags.manifest) {
+    manifest = toRelative(root, resolve(flags.manifest));
+  } else {
+    const out = file.manifest?.out ?? (file.manifest?.system ? `${trim(file.manifest.system)}/manifest` : void 0);
+    if (!out) {
+      throw new UsageError(
+        `no manifest. Pass --manifest <components.json>, or add { "manifest": { "system": "src/ds" } } to ${CONFIG_FILE}.`
+      );
+    }
+    manifest = `${trim(out)}/components.json`;
+  }
+  if (!existsSync(resolve(root, manifest))) {
+    throw new UsageError(`${manifest} does not exist. Run designtools-manifest build first.`);
+  }
+  const tokensPath = `${dirname(manifest)}/tokens.json`;
+  const include = flags.include?.length ? flags.include : file.adherence?.include ?? DEFAULT_INCLUDE;
+  const exclude = [...DEFAULT_EXCLUDE, ...file.adherence?.exclude ?? [], ...flags.exclude ?? []];
+  for (const [name, list] of [["include", include], ["exclude", exclude]]) {
+    if (!Array.isArray(list) || list.some((g) => typeof g !== "string")) {
+      throw new UsageError(`adherence.${name} in ${CONFIG_FILE} must be a list of globs`);
+    }
+  }
+  return {
+    root,
+    manifest,
+    tokens: existsSync(resolve(root, tokensPath)) ? tokensPath : void 0,
+    tsconfig: file.manifest?.tsconfig,
+    include,
+    exclude
+  };
+}
+function trim(p) {
+  return p.replace(/\/+$/, "");
+}
+function toRelative(root, abs) {
+  const rel = relative(root, abs);
+  if (rel.startsWith("..") || resolve(root, rel) !== abs) return abs.split("\\").join("/");
+  return rel.split("\\").join("/");
+}
+
+// src/sort.ts
+function cmp(a, b) {
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+
+// src/markdown.ts
+var LIMIT = 6e4;
+var PER_FILE = 25;
+function formatMarkdown(report) {
+  const s = report.summary;
+  const lines = [];
+  lines.push("## Design system adherence", "");
+  lines.push(
+    s.share === null ? "No system components or replaceable raw elements found." : `**${percent(s.share)}** from the system: ${s.systemUses} system component ${plural(s.systemUses, "use")} against ${s.rawElements} raw ${plural(s.rawElements, "element")} a component replaces.`
+  );
+  lines.push(
+    "",
+    `${s.offSystemValues} off-system ${plural(s.offSystemValues, "value")} (${s.offSystem.palette} palette, ${s.offSystem.arbitrary} arbitrary, ${s.offSystem["status-text"] ?? 0} status text) \xB7 ${s.overrides} ${plural(s.overrides, "override")} \xB7 ${s.files} ${plural(s.files, "file")} scanned, ${s.filesWithFindings} with findings.`
+  );
+  lines.push("", "Warnings only: nothing here blocks a merge.");
+  if (!s.replaceable.length) {
+    lines.push("", "No component declares `@replaces`, so no raw elements were counted. Tag components with the elements they stand in for, such as `@replaces button`.");
+  }
+  if (report.routes.length) {
+    lines.push("", "### Routes", "", "| Route | From the system | Off-system values | Overrides |", "| --- | --- | --- | --- |");
+    for (const r of report.routes) {
+      lines.push(`| \`${r.route}\` | ${shareCell(r.counts)} | ${r.counts.offSystemValues} | ${r.counts.overrides} |`);
+    }
+  }
+  const findings = report.files.filter((f) => f.raw.length || f.offSystem.length || f.overrides.length);
+  const tail = [];
+  const used = report.components.filter((c) => c.uses > 0);
+  if (used.length) {
+    tail.push("", "### Components", "", "| Component | Uses | Files |", "| --- | --- | --- |");
+    for (const c of [...used].sort((a, b) => b.uses - a.uses || cmp(a.name, b.name))) {
+      tail.push(`| \`${c.name}\` | ${c.uses} | ${c.files} |`);
+    }
+  }
+  if (s.componentsUnused.length) {
+    tail.push("", `Not used in the product: ${s.componentsUnused.map((n) => `\`${n}\``).join(", ")}.`);
+  }
+  if (report.skipped.length) {
+    tail.push("", "### Skipped", "");
+    for (const f of report.skipped) tail.push(`- \`${f.file}\`: ${f.reason}`);
+  }
+  tail.push("", `<sub>${report.generator} \xB7 ${report.manifest}</sub>`, "");
+  if (findings.length) {
+    lines.push("", "### Findings by file", "");
+    let size = lines.join("\n").length + tail.join("\n").length;
+    for (let i = 0; i < findings.length; i++) {
+      const block = fileBlock(findings[i]);
+      if (size + block.length > LIMIT) {
+        lines.push(`${findings.length - i} more ${plural(findings.length - i, "file")} with findings are in the JSON report (\`--json <file>\`).`, "");
+        break;
+      }
+      lines.push(block);
+      size += block.length + 1;
+    }
+  }
+  return [...lines, ...tail].join("\n").replace(/\n{3,}/g, "\n\n");
+}
+function fileBlock(f) {
+  const parts = [
+    f.raw.length && `${f.raw.length} raw`,
+    f.offSystem.length && `${f.offSystem.length} off-system`,
+    f.overrides.length && `${f.overrides.length} ${plural(f.overrides.length, "override")}`
+  ].filter(Boolean);
+  const items = [
+    ...f.raw.map((r) => [
+      r.line,
+      r.column,
+      `\`<${r.element}>\`${r.selector !== r.element ? ` (\`${r.selector}\`)` : ""}: use ${r.replacedBy.map((c) => `\`${c}\``).join(" or ")}`
+    ]),
+    ...f.offSystem.map((v) => [
+      v.line,
+      v.column,
+      `\`${v.class}\`: ${OFF_SYSTEM_ADVICE[v.kind]}`
+    ]),
+    ...f.overrides.map((o) => [
+      o.line,
+      o.column,
+      `\`<${o.component} className>\` overrides ${[...new Set(o.classes.map((c) => c.kind))].join(", ")} with ${o.classes.map((c) => `\`${c.class}\``).join(" ")}; use a variant`
+    ])
+  ].sort((a, b) => a[0] - b[0] || a[1] - b[1] || cmp(a[2], b[2]));
+  const shown = items.slice(0, PER_FILE).map(([line, , text]) => `- L${line} ${text}`);
+  if (items.length > PER_FILE) shown.push(`- and ${items.length - PER_FILE} more`);
+  const title = `\`${f.file}\`${f.route ? ` (\`${f.route}\`)` : ""}: ${parts.join(", ")}`;
+  return ["<details>", `<summary>${title}</summary>`, "", ...shown, "", "</details>", ""].join("\n");
+}
+function percent(share) {
+  let p = Math.round(share * 100);
+  if (p === 100 && share < 1) p = 99;
+  if (p === 0 && share > 0) p = 1;
+  return `${p}%`;
+}
+function shareCell(c) {
+  if (c.share === null) return "\u2013";
+  return `${percent(c.share)} (${c.systemUses} of ${c.systemUses + c.rawElements})`;
+}
+function plural(n, word) {
+  return n === 1 ? word : `${word}s`;
+}
+var OFF_SYSTEM_ADVICE = {
+  palette: "a palette step; use a semantic colour",
+  arbitrary: "an arbitrary value; use a token",
+  "status-text": "a status fill as text, unchecked on the page; use its `-subdued-foreground`, or neutral text with an icon for a warning"
+};
+
+// src/discipline.ts
+import { existsSync as existsSync2 } from "fs";
+import { createRequire } from "module";
+import { dirname as dirname2, join, relative as relative2, sep } from "path";
+import { fileURLToPath } from "url";
+var TAILWIND_FAMILIES = [
+  "red",
+  "orange",
+  "amber",
+  "yellow",
+  "lime",
+  "green",
+  "emerald",
+  "teal",
+  "cyan",
+  "sky",
+  "blue",
+  "indigo",
+  "violet",
+  "purple",
+  "fuchsia",
+  "pink",
+  "rose",
+  "slate",
+  "gray",
+  "zinc",
+  "neutral",
+  "stone",
+  "mauve",
+  "olive",
+  "mist",
+  "taupe"
+];
+var COLOUR_UTILITIES = [
+  "bg",
+  "text",
+  "border",
+  "border-x",
+  "border-y",
+  "border-t",
+  "border-r",
+  "border-b",
+  "border-l",
+  "border-s",
+  "border-e",
+  "outline",
+  "ring",
+  "ring-offset",
+  "inset-ring",
+  "shadow",
+  "inset-shadow",
+  "drop-shadow",
+  "text-shadow",
+  "divide",
+  "fill",
+  "stroke",
+  "from",
+  "via",
+  "to",
+  "decoration",
+  "accent",
+  "caret",
+  "placeholder"
+];
+var esc = (s) => s.replace(/[.*+?^${}()|[\]\\/]/g, "\\$&");
+var wrap = (utility) => `^((?:\\S*:)?!?-?${utility}!?)$`;
+var LAYOUT = `(?:z|w|min-w|max-w|grid-cols|grid-rows|columns|aspect)-\\[`;
+function restrictionsFor(families) {
+  const fams = [...new Set(families)].sort((a, b) => b.length - a.length || cmp(a, b)).map(esc).join("|");
+  const utils = [...COLOUR_UTILITIES].sort((a, b) => b.length - a.length).map(esc).join("|");
+  const step = `(?:${fams})-\\d+`;
+  const palette = `(?:${utils})-(?:${step}|\\(--color-${step}\\)|\\[var\\(--color-${step}\\)\\])(?:\\/\\S+)?`;
+  return [
+    { pattern: wrap(palette), message: "[designtools:palette] $1" },
+    // a bracketed value that is not a token reference, or an arbitrary property. Layout is left
+    // alone: container widths, grid templates, aspect ratios and z-index are not tokens
+    // (mxa-tokens, "Deliberately not tokenised"), so `max-w-[40rem]` is art direction, not drift.
+    // a status colour's fill used as text: it is measured against its own label, not the page, and
+    // fails there (red text on a dark page, 2.4:1 for every brand tested). Its subdued label is the
+    // text tone that reads on every background; warning text is neutral text with an icon.
+    { pattern: wrap(`text-(?:success|warning|destructive)(?:\\/\\S+)?`), message: "[designtools:status-text] $1" },
+    { pattern: wrap(`(?:(?!${LAYOUT})[a-z][\\w-]*-\\[(?!var\\(--)[^\\]]+\\](?:\\/\\S+)?|\\[[a-z-]+:[^\\]]+\\])`), message: "[designtools:arbitrary] $1" }
+  ];
+}
+function familiesFromTokens(tokens) {
+  const out = /* @__PURE__ */ new Set();
+  for (const t of tokens) {
+    const m = /^--color-([a-z][a-z0-9-]*?)-(\d+)$/.exec(t.name);
+    if (m) out.add(m[1]);
+  }
+  return [...out].sort();
+}
+async function checkDiscipline(root, files, families) {
+  const values = /* @__PURE__ */ new Map();
+  const failed = [];
+  if (!files.length) return { values, failed };
+  const [{ ESLint }, parser, plugin] = await Promise.all([
+    import("eslint"),
+    import("@typescript-eslint/parser"),
+    import("eslint-plugin-better-tailwindcss")
+  ]);
+  const eslint = new ESLint({
+    cwd: root,
+    overrideConfigFile: true,
+    // the project's own eslint-disable comments name rules that are not loaded here
+    allowInlineConfig: false,
+    overrideConfig: [
+      {
+        files: ["**/*.{tsx,jsx,ts,js,mjs,cjs}"],
+        languageOptions: {
+          parser: parser.default ?? parser,
+          parserOptions: { ecmaFeatures: { jsx: true } }
+        },
+        linterOptions: { reportUnusedDisableDirectives: "off" },
+        plugins: { "better-tailwindcss": plugin.default ?? plugin },
+        settings: { "better-tailwindcss": { cwd: tailwindCwd(root) } },
+        rules: { "better-tailwindcss/no-restricted-classes": ["warn", { restrict: restrictionsFor([...TAILWIND_FAMILIES, ...families]) }] }
+      }
+    ]
+  });
+  const results = await eslint.lintFiles(files.map((f) => join(root, f)));
+  for (const result of results) {
+    const file = relative2(root, result.filePath).split(sep).join("/");
+    const found = [];
+    for (const m of result.messages) {
+      if (m.fatal) {
+        failed.push({ file, reason: m.message });
+        continue;
+      }
+      const hit = /\[designtools:(palette|arbitrary|status-text)\] (\S+)/.exec(m.message);
+      if (hit) found.push({ class: hit[2], kind: hit[1], line: m.line, column: m.column });
+    }
+    if (found.length) values.set(file, found.sort((a, b) => a.line - b.line || a.column - b.column || cmp(a.class, b.class)));
+  }
+  return { values, failed };
+}
+function tailwindCwd(root) {
+  try {
+    createRequire(join(root, "package.json")).resolve("tailwindcss/package.json");
+    return root;
+  } catch {
+    let dir = dirname2(fileURLToPath(import.meta.url));
+    while (!existsSync2(join(dir, "package.json")) && dirname2(dir) !== dir) dir = dirname2(dir);
+    return dir;
+  }
+}
+
+// src/files.ts
+import { existsSync as existsSync3, readdirSync, statSync } from "fs";
+import { join as join2, posix } from "path";
+import picomatch from "picomatch";
+var SKIP_DIRS = /* @__PURE__ */ new Set(["node_modules"]);
+function listProductFiles(root, includeGlobs, excludeGlobs) {
+  const include = includeGlobs.map(nextSegments);
+  const exclude = excludeGlobs.map(nextSegments);
+  const isIncluded = picomatch(include, { dot: false });
+  const isExcluded = exclude.length ? picomatch(exclude, { dot: true }) : () => false;
+  const bases = new Set(include.map((g) => picomatch.scan(g).base.replace(/\\/g, "").replace(/^\.\//, "")));
+  const found = /* @__PURE__ */ new Set();
+  const walk = (rel) => {
+    const abs = rel ? join2(root, rel) : root;
+    let entries;
+    try {
+      entries = readdirSync(abs, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const path = rel ? posix.join(rel, entry.name) : entry.name;
+      if (entry.isDirectory()) {
+        if (SKIP_DIRS.has(entry.name) || entry.name.startsWith(".")) continue;
+        if (isExcluded(`${path}/`) || isExcluded(`${path}/x`)) continue;
+        walk(path);
+      } else if (entry.isFile() && isIncluded(path) && !isExcluded(path)) {
+        found.add(path);
+      }
+    }
+  };
+  for (const base of [...bases].sort()) {
+    if (!base) {
+      walk("");
+      continue;
+    }
+    const abs = join2(root, base);
+    if (!existsSync3(abs)) continue;
+    if (statSync(abs).isFile()) {
+      if (isIncluded(base) && !isExcluded(base)) found.add(base);
+    } else {
+      walk(base);
+    }
+  }
+  return [...found].sort();
+}
+function nextSegments(glob) {
+  return glob.replace(/(^|\/)\(([^()/|]+)\)(?=\/|$)/g, "$1\\($2\\)").replace(/(^|\/)(\[\[?(?:\.\.\.)?[\w-]+\]?\])(?=\/|$)/g, (_, lead, seg) => lead + seg.replace(/[[\]]/g, "\\$&"));
+}
+
+// src/overrides.ts
+var KEYWORD_COLOURS = ["black", "white", "transparent", "current", "currentColor", "inherit"];
+var SPACING = /^(?:p|px|py|pt|pr|pb|pl|ps|pe|m|mx|my|mt|mr|mb|ml|ms|me|gap|gap-x|gap-y|space-x|space-y)-./;
+var RADIUS = /^rounded(?:$|-)/;
+var BRACKET_COLOUR = /^\[(?:#|rgba?\(|hsla?\(|oklch\(|oklab\(|lab\(|lch\(|hwb\(|color\(|color-mix\(|var\(--color-)|^\(--color-/;
+function colourContext(tokens, families) {
+  const colours = new Set(KEYWORD_COLOURS);
+  for (const t of tokens) {
+    const m = /^--color-(.+)$/.exec(t.name);
+    if (m) colours.add(m[1]);
+  }
+  return { colours, families: [.../* @__PURE__ */ new Set([...TAILWIND_FAMILIES, ...families])] };
+}
+function findOverrides(uses, ctx) {
+  const out = [];
+  for (const use of uses) {
+    const value = use.props.className ?? use.props.class;
+    if (typeof value !== "string" || value.startsWith("(")) continue;
+    const classes = value.split(/\s+/).filter(Boolean).flatMap((c) => {
+      const kind = overrideKind(c, ctx);
+      return kind ? [{ class: c, kind }] : [];
+    });
+    if (classes.length) out.push({ component: use.component, classes, line: use.line, column: use.column });
+  }
+  return out;
+}
+function overrideKind(cls, ctx) {
+  const utility = stripVariants(cls).replace(/^!/, "").replace(/!$/, "").replace(/^-/, "");
+  if (RADIUS.test(utility)) return "radius";
+  if (SPACING.test(utility) && !/-auto$/.test(utility)) return "spacing";
+  for (const prefix of [...COLOUR_UTILITIES].sort((a, b) => b.length - a.length)) {
+    if (!utility.startsWith(`${prefix}-`)) continue;
+    const value = utility.slice(prefix.length + 1).replace(/\/[^/]+$/, "");
+    if (isColour(value, ctx)) return "colour";
+    break;
+  }
+  return void 0;
+}
+function isColour(value, ctx) {
+  if (ctx.colours.has(value)) return true;
+  if (BRACKET_COLOUR.test(value)) return true;
+  const m = /^(.+)-(\d+)$/.exec(value);
+  return !!m && ctx.families.includes(m[1]);
+}
+function stripVariants(cls) {
+  let depth = 0;
+  let last = -1;
+  for (let i = 0; i < cls.length; i++) {
+    const c = cls[i];
+    if (c === "[" || c === "(") depth++;
+    else if (c === "]" || c === ")") depth--;
+    else if (c === ":" && depth === 0) last = i;
+  }
+  return cls.slice(last + 1);
+}
+
+// src/resolve.ts
+import { existsSync as existsSync4, readFileSync as readFileSync2, statSync as statSync2 } from "fs";
+import { dirname as dirname3, posix as posix2, resolve as resolve2 } from "path";
+var EXTENSIONS = [".tsx", ".ts", ".jsx", ".js", ".mjs"];
+function createResolver(root, tsconfig) {
+  const paths = readPaths(root, tsconfig);
+  const cache = /* @__PURE__ */ new Map();
+  return (moduleName, fromFile) => {
+    const relativeImport = moduleName.startsWith(".");
+    const key = relativeImport ? `${posix2.dirname(fromFile)}\0${moduleName}` : moduleName;
+    if (cache.has(key)) return cache.get(key);
+    let candidates = [];
+    if (relativeImport) {
+      candidates = [resolve2(root, posix2.dirname(fromFile), moduleName)];
+    } else if (moduleName.startsWith("/")) {
+      candidates = [moduleName];
+    } else if (paths) {
+      candidates = aliasTargets(paths, moduleName);
+    }
+    let found;
+    for (const candidate of candidates) {
+      const file = probe(candidate);
+      if (file) {
+        found = toRelative(root, file);
+        break;
+      }
+    }
+    cache.set(key, found);
+    return found;
+  };
+}
+function aliasTargets(paths, moduleName) {
+  const matches = paths.entries.filter(
+    (e) => e.wildcard ? moduleName.startsWith(e.prefix) && moduleName.endsWith(e.suffix) && moduleName.length >= e.prefix.length + e.suffix.length : moduleName === e.prefix
+  ).sort((a, b) => b.prefix.length - a.prefix.length);
+  const out = [];
+  for (const entry of matches) {
+    const star = entry.wildcard ? moduleName.slice(entry.prefix.length, moduleName.length - entry.suffix.length) : "";
+    for (const target of entry.targets) out.push(resolve2(paths.base, target.replace("*", star)));
+  }
+  return out;
+}
+function probe(path) {
+  if (isFile(path)) return path;
+  for (const ext of EXTENSIONS) if (isFile(path + ext)) return path + ext;
+  for (const ext of EXTENSIONS) if (isFile(`${path}/index${ext}`)) return `${path}/index${ext}`;
+  return void 0;
+}
+function isFile(path) {
+  try {
+    return statSync2(path).isFile();
+  } catch {
+    return false;
+  }
+}
+function readPaths(root, tsconfig) {
+  const start = resolve2(root, tsconfig ?? "tsconfig.json");
+  const seen = /* @__PURE__ */ new Set();
+  let file = start;
+  while (file && existsSync4(file) && !seen.has(file)) {
+    seen.add(file);
+    let json;
+    try {
+      json = JSON.parse(stripJsonComments(readFileSync2(file, "utf8")));
+    } catch {
+      return void 0;
+    }
+    const options = json.compilerOptions ?? {};
+    if (options.paths) {
+      const base = resolve2(dirname3(file), options.baseUrl ?? ".");
+      return {
+        base,
+        entries: Object.entries(options.paths).map(([pattern, targets]) => {
+          const star = pattern.indexOf("*");
+          return {
+            prefix: star === -1 ? pattern : pattern.slice(0, star),
+            suffix: star === -1 ? "" : pattern.slice(star + 1),
+            wildcard: star !== -1,
+            targets
+          };
+        })
+      };
+    }
+    const ext = Array.isArray(json.extends) ? json.extends[0] : json.extends;
+    file = ext && ext.startsWith(".") ? resolve2(dirname3(file), ext.endsWith(".json") ? ext : `${ext}.json`) : void 0;
+  }
+  return void 0;
+}
+function stripJsonComments(text) {
+  let out = "";
+  let i = 0;
+  while (i < text.length) {
+    const c = text[i];
+    if (c === '"') {
+      let j = i + 1;
+      while (j < text.length && text[j] !== '"') j += text[j] === "\\" ? 2 : 1;
+      out += text.slice(i, j + 1);
+      i = j + 1;
+    } else if (c === "/" && text[i + 1] === "/") {
+      while (i < text.length && text[i] !== "\n") i++;
+    } else if (c === "/" && text[i + 1] === "*") {
+      const end = text.indexOf("*/", i + 2);
+      i = end === -1 ? text.length : end + 2;
+    } else {
+      out += c;
+      i++;
+    }
+  }
+  return out.replace(/,(\s*[}\]])/g, "$1");
+}
+
+// src/routes.ts
+import { posix as posix3 } from "path";
+var PAGE = /^page\.(tsx|jsx|ts|js|mdx)$/;
+var APP_DIRS = ["app", "src/app"];
+function mapRoutes(files) {
+  const pages = /* @__PURE__ */ new Map();
+  for (const file of files) {
+    const appDir = APP_DIRS.find((d) => file.startsWith(`${d}/`));
+    if (!appDir || !PAGE.test(posix3.basename(file))) continue;
+    pages.set(file, routeOf(posix3.dirname(file).slice(appDir.length)));
+  }
+  const pageIn = /* @__PURE__ */ new Map();
+  const leadsToPage = /* @__PURE__ */ new Set();
+  for (const page of pages.keys()) {
+    let dir = posix3.dirname(page);
+    pageIn.set(dir, page);
+    while (dir !== "." && !leadsToPage.has(dir)) {
+      leadsToPage.add(dir);
+      dir = posix3.dirname(dir);
+    }
+  }
+  const owner = /* @__PURE__ */ new Map();
+  for (const file of files) {
+    if (!APP_DIRS.some((d) => file.startsWith(`${d}/`))) continue;
+    let dir = posix3.dirname(file);
+    while (dir !== ".") {
+      const page = pageIn.get(dir);
+      if (page) {
+        owner.set(file, page);
+        break;
+      }
+      if (leadsToPage.has(dir)) break;
+      dir = posix3.dirname(dir);
+    }
+  }
+  return { pages, owner };
+}
+function routeOf(dir) {
+  const segments = dir.split("/").filter((s) => s && !/^\(.*\)$/.test(s) && !s.startsWith("@")).map((s) => s.replace(/^(?:\(\.{1,3}\))+/, ""));
+  return `/${segments.join("/")}`;
+}
+
+// src/scanner.ts
+import { createRequire as createRequire2 } from "module";
+import { posix as posix4, relative as relative3, sep as sep2 } from "path";
+var require2 = createRequire2(import.meta.url);
+async function scanJsx(root, files) {
+  const wanted = new Set(files);
+  if (!files.length) return { report: {}, instances: [], failed: [] };
+  const dirs = /* @__PURE__ */ new Set();
+  for (const f of files) {
+    let d = posix4.dirname(f);
+    while (d !== "." && !dirs.has(d)) {
+      dirs.add(d);
+      d = posix4.dirname(d);
+    }
+  }
+  const rel = (abs) => relative3(root, abs).split(sep2).join("/");
+  const scanner = require2("react-scanner");
+  let raw = {};
+  const failed = [];
+  const log = console.log;
+  const error = console.error;
+  console.log = () => {
+  };
+  console.error = (...args) => {
+    const m = /^Failed to parse: (.*)$/.exec(String(args[0]));
+    if (m) failed.push(rel(m[1]));
+  };
+  try {
+    await scanner.run(
+      {
+        crawlFrom: root,
+        rootDir: root,
+        globs: ["**/*.@(tsx|jsx|ts|js|mjs)"],
+        exclude: (_name, dirPath) => {
+          const d = rel(dirPath.replace(/[\\/]+$/, ""));
+          return d !== "" && !dirs.has(d);
+        },
+        includeSubComponents: true,
+        getPropValue: ({ node, propName, defaultGetPropValue }) => (
+          // a bare attribute, <Checkbox checked>, is true; react-scanner calls it null
+          node === null ? true : propName === "className" || propName === "class" ? classValue(node, defaultGetPropValue) : safe(defaultGetPropValue, node)
+        ),
+        processors: [
+          ({ report: report2 }) => {
+            raw = report2;
+          }
+        ]
+      },
+      root,
+      "programmatic"
+    );
+  } catch (e) {
+    if (!/No files found to scan/.test(e.message)) throw e;
+  } finally {
+    console.log = log;
+    console.error = error;
+  }
+  const report = narrow(raw, (abs) => {
+    const f = rel(abs);
+    return wanted.has(f) ? f : void 0;
+  });
+  return { report, instances: flatten(report), failed: failed.filter((f) => wanted.has(f)).sort() };
+}
+function narrow(report, keep) {
+  const out = {};
+  for (const name of Object.keys(report).sort()) {
+    const entry = report[name];
+    const instances = (entry.instances ?? []).flatMap((i) => {
+      const file = keep(i.location.file);
+      return file ? [{ ...i, location: { ...i.location, file } }] : [];
+    });
+    const components = entry.components ? narrow(entry.components, keep) : void 0;
+    const next = {};
+    if (instances.length) next.instances = instances;
+    if (components && Object.keys(components).length) next.components = components;
+    if (next.instances || next.components) out[name] = next;
+  }
+  return out;
+}
+function flatten(report, prefix = "") {
+  const out = [];
+  for (const [key, entry] of Object.entries(report)) {
+    const name = prefix + key;
+    for (const i of entry.instances ?? []) {
+      out.push({
+        name,
+        file: i.location.file,
+        line: i.location.start.line,
+        column: i.location.start.column + 1,
+        importInfo: i.importInfo,
+        props: i.props,
+        spread: i.propsSpread
+      });
+    }
+    if (entry.components) out.push(...flatten(entry.components, `${name}.`));
+  }
+  return out.sort((a, b) => cmp(a.file, b.file) || a.line - b.line || a.column - b.column || cmp(a.name, b.name));
+}
+function safe(get, node) {
+  try {
+    return get(node);
+  } catch {
+    return node ? `(${node.type})` : null;
+  }
+}
+function classValue(node, get) {
+  if (!node || node.type === "Literal") return safe(get, node);
+  const strings = [];
+  collectStrings(node, strings);
+  const text = strings.join(" ").split(/\s+/).filter(Boolean).join(" ");
+  return text || safe(get, node);
+}
+function collectStrings(node, out) {
+  if (!node || typeof node !== "object") return;
+  const n = node;
+  switch (n.type) {
+    case "Literal":
+      if (typeof n.value === "string") out.push(n.value);
+      return;
+    case "TemplateLiteral":
+      for (const q of n.quasis) out.push(q.value.cooked ?? "");
+      for (const e of n.expressions) collectStrings(e, out);
+      return;
+    case "Property":
+      if (n.key.type === "Literal") collectStrings(n.key, out);
+      else if (n.key.type === "Identifier" && !n.computed) out.push(n.key.name);
+      return;
+    case "ConditionalExpression":
+      collectStrings(n.consequent, out);
+      collectStrings(n.alternate, out);
+      return;
+    case "BinaryExpression":
+      if (n.operator === "+") {
+        collectStrings(n.left, out);
+        collectStrings(n.right, out);
+      }
+      return;
+    case "MemberExpression":
+    case "Identifier":
+    case "ThisExpression":
+      return;
+    default:
+      for (const [key, value] of Object.entries(n)) {
+        if (key === "loc" || key === "range" || key === "parent" || key === "callee") continue;
+        if (Array.isArray(value)) for (const v of value) collectStrings(v, out);
+        else if (value && typeof value === "object") collectStrings(value, out);
+      }
+  }
+}
+
+// src/types.ts
+var ADHERENCE_SCHEMA = "designtools.adherence/1";
+
+// src/usage.ts
+function parseSelector(text) {
+  const m = /^([a-z][a-z0-9-]*)((?:\[[^\]]+\])*)$/.exec(text.trim());
+  if (!m) return void 0;
+  const attrs = [...m[2].matchAll(/\[([^\]=]+)(?:=["']?([^"'\]]*)["']?)?\]/g)].map((a) => ({
+    name: a[1].trim(),
+    ...a[2] !== void 0 && { value: a[2] }
+  }));
+  return { text: text.trim(), tag: m[1], attrs };
+}
+function classify(instances, manifest, resolve4) {
+  const system = manifest.system.replace(/\/+$/, "");
+  const bySource = /* @__PURE__ */ new Map();
+  const byExport = /* @__PURE__ */ new Map();
+  for (const c of [...manifest.components].sort((a, b) => cmp(a.source, b.source) || cmp(a.name, b.name))) {
+    if (!bySource.has(c.source)) bySource.set(c.source, /* @__PURE__ */ new Map());
+    bySource.get(c.source).set(c.export, c);
+    if (!byExport.has(c.export)) byExport.set(c.export, c);
+  }
+  const replaceable = /* @__PURE__ */ new Map();
+  for (const c of manifest.components) {
+    for (const r of c.replaces ?? []) {
+      const selector = parseSelector(r);
+      if (!selector) continue;
+      const entry = replaceable.get(selector.text) ?? { selector, components: [] };
+      if (!entry.components.includes(c.name)) entry.components.push(c.name);
+      entry.components.sort();
+      replaceable.set(selector.text, entry);
+    }
+  }
+  const selectors = [...replaceable.values()].sort(
+    (a, b) => b.selector.attrs.length - a.selector.attrs.length || cmp(a.selector.text, b.selector.text)
+  );
+  const uses = /* @__PURE__ */ new Map();
+  const raw = /* @__PURE__ */ new Map();
+  const push = (map, file, item) => {
+    if (!map.has(file)) map.set(file, []);
+    map.get(file).push(item);
+  };
+  for (const i of instances) {
+    const [first, ...rest] = i.name.split(".");
+    if (!i.importInfo) {
+      if (rest.length || !/^[a-z]/.test(first)) continue;
+      const matched = selectors.filter((s) => s.selector.tag === first && s.selector.attrs.every((a) => attrMatches(i.props, a)));
+      if (!matched.length) continue;
+      const best = matched[0];
+      const replacedBy = [...new Set(matched.flatMap((s) => s.components))];
+      push(raw, i.file, { element: first, selector: best.selector.text, replacedBy, line: i.line, column: i.column });
+      continue;
+    }
+    const file = resolve4(i.importInfo.moduleName, i.file);
+    if (!file) continue;
+    const inSource = bySource.get(file);
+    if (!inSource && !(file === system || file.startsWith(`${system}/`))) continue;
+    const namespace = i.importInfo.importType === "ImportNamespaceSpecifier";
+    const exportName = namespace ? rest[0] : i.importInfo.importType === "ImportDefaultSpecifier" ? i.importInfo.local : i.importInfo.imported ?? first;
+    if (!exportName) continue;
+    let entry = inSource?.get(exportName) ?? (inSource ? void 0 : byExport.get(exportName));
+    if (!entry && i.importInfo.importType === "ImportDefaultSpecifier" && inSource?.size === 1) entry = [...inSource.values()][0];
+    if (!entry) continue;
+    push(uses, i.file, {
+      component: entry.name,
+      ...i.name !== entry.name && { as: i.name },
+      line: i.line,
+      column: i.column,
+      props: sortProps(i.props),
+      spread: i.spread,
+      entry
+    });
+  }
+  return { uses, raw, replaceable };
+}
+function attrMatches(props, attr) {
+  if (!(attr.name in props)) return false;
+  if (attr.value === void 0) return true;
+  return String(props[attr.name]) === attr.value;
+}
+function sortProps(props) {
+  const out = {};
+  for (const key of Object.keys(props).sort()) {
+    const v = props[key];
+    out[key] = v === null || typeof v === "string" || typeof v === "number" || typeof v === "boolean" ? v : String(v);
+  }
+  return out;
+}
+
+// src/report.ts
+import { readFileSync as readFileSync3 } from "fs";
+import { dirname as dirname4, join as join3, resolve as resolve3 } from "path";
+import { fileURLToPath as fileURLToPath2 } from "url";
+var GENERATOR_NAME = "@designtools/adherence";
+var VERSION = (() => {
+  try {
+    const here = dirname4(fileURLToPath2(import.meta.url));
+    return JSON.parse(readFileSync3(join3(here, "../package.json"), "utf8")).version;
+  } catch {
+    return "0.0.0";
+  }
+})();
+var GENERATOR = `${GENERATOR_NAME}@${VERSION}`;
+async function buildReport(config) {
+  const t0 = performance.now();
+  const manifest = readJson(config.root, config.manifest);
+  if (!manifest || !Array.isArray(manifest.components) || typeof manifest.system !== "string") {
+    throw new UsageError(`${config.manifest} is not a components.json written by designtools-manifest`);
+  }
+  const tokens = config.tokens ? readJson(config.root, config.tokens)?.tokens ?? [] : [];
+  const system = manifest.system.replace(/\/+$/, "");
+  const exclude = [...config.exclude, `${system}/**`];
+  const files = listProductFiles(config.root, config.include, exclude);
+  const t1 = performance.now();
+  const scan = await scanJsx(config.root, files);
+  const classified = classify(scan.instances, manifest, createResolver(config.root, config.tsconfig));
+  const families = familiesFromTokens(tokens);
+  const colours = colourContext(tokens, families);
+  const t2 = performance.now();
+  const discipline = await checkDiscipline(config.root, files, families);
+  const t3 = performance.now();
+  const routes = mapRoutes(files);
+  const fileEntries = [];
+  for (const file of files) {
+    const uses = (classified.uses.get(file) ?? []).map(({ entry: _entry, ...use }) => use);
+    const raw = classified.raw.get(file) ?? [];
+    const offSystem = discipline.values.get(file) ?? [];
+    const overrides = findOverrides(uses, colours);
+    if (!uses.length && !raw.length && !offSystem.length) continue;
+    const owner = routes.owner.get(file);
+    fileEntries.push({
+      file,
+      ...owner && { route: routes.pages.get(owner) },
+      counts: counts(uses.length, raw.length, offSystem.length, overrides.length),
+      uses,
+      raw,
+      offSystem,
+      overrides
+    });
+  }
+  const byFile = new Map(fileEntries.map((f) => [f.file, f]));
+  const routeEntries = [...routes.pages.entries()].map(([page, route]) => {
+    const owned = files.filter((f) => routes.owner.get(f) === page);
+    return { route, page, files: owned, counts: sum(owned.map((f) => byFile.get(f)?.counts)) };
+  }).sort((a, b) => cmp(a.route, b.route) || cmp(a.page, b.page));
+  const components = componentUsage(manifest.components, classified.uses);
+  const elements = [...classified.replaceable.values()].map(({ selector, components: components2 }) => {
+    const hits = fileEntries.flatMap((f) => f.raw.filter((r) => r.selector === selector.text).map(() => f.file));
+    return { selector: selector.text, uses: hits.length, files: new Set(hits).size, replacedBy: components2 };
+  }).sort((a, b) => cmp(a.selector, b.selector));
+  const skipped = /* @__PURE__ */ new Map();
+  for (const file of scan.failed) skipped.set(file, { file, reason: "react-scanner could not parse it" });
+  for (const f of discipline.failed) if (!skipped.has(f.file)) skipped.set(f.file, { file: f.file, reason: f.reason });
+  const total = sum(fileEntries.map((f) => f.counts));
+  const all = fileEntries.flatMap((f) => f.offSystem);
+  const overrideClasses = fileEntries.flatMap((f) => f.overrides.flatMap((o) => o.classes));
+  const report = {
+    generator: GENERATOR,
+    schema: ADHERENCE_SCHEMA,
+    manifest: config.manifest,
+    system,
+    include: config.include,
+    exclude,
+    summary: {
+      ...total,
+      files: files.length,
+      filesWithFindings: fileEntries.filter((f) => f.raw.length || f.offSystem.length || f.overrides.length).length,
+      offSystem: {
+        palette: all.filter((v) => v.kind === "palette").length,
+        arbitrary: all.filter((v) => v.kind === "arbitrary").length,
+        "status-text": all.filter((v) => v.kind === "status-text").length
+      },
+      overrideKinds: {
+        colour: overrideClasses.filter((c) => c.kind === "colour").length,
+        spacing: overrideClasses.filter((c) => c.kind === "spacing").length,
+        radius: overrideClasses.filter((c) => c.kind === "radius").length
+      },
+      componentsUsed: components.filter((c) => c.uses > 0).length,
+      componentsUnused: components.filter((c) => c.uses === 0).map((c) => c.name),
+      replaceable: elements.map((e) => e.selector)
+    },
+    routes: routeEntries,
+    files: fileEntries,
+    components,
+    elements,
+    skipped: [...skipped.values()].sort((a, b) => cmp(a.file, b.file))
+  };
+  const t4 = performance.now();
+  return {
+    report,
+    timings: { files: t1 - t0, components: t2 - t1, discipline: t3 - t2, total: t4 - t0 }
+  };
+}
+function counts(systemUses, rawElements, offSystemValues, overrides) {
+  const denominator = systemUses + rawElements;
+  return {
+    systemUses,
+    rawElements,
+    share: denominator ? Math.round(systemUses / denominator * 1e4) / 1e4 : null,
+    offSystemValues,
+    overrides
+  };
+}
+function sum(list) {
+  let u = 0, r = 0, o = 0, v = 0;
+  for (const c of list) {
+    if (!c) continue;
+    u += c.systemUses;
+    r += c.rawElements;
+    v += c.offSystemValues;
+    o += c.overrides;
+  }
+  return counts(u, r, v, o);
+}
+function componentUsage(manifest, uses) {
+  const sorted = [...manifest].sort((a, b) => cmp(a.name, b.name) || cmp(a.source, b.source));
+  return sorted.map((c) => {
+    let count = 0;
+    const files = /* @__PURE__ */ new Set();
+    const props = {};
+    const axes = c.variants?.axes ?? [];
+    const variants = {};
+    for (const a of axes) variants[a.name] = {};
+    for (const [file, list] of uses) {
+      for (const use of list) {
+        if (use.entry !== c) continue;
+        count++;
+        files.add(file);
+        for (const p of Object.keys(use.props)) props[p] = (props[p] ?? 0) + 1;
+        for (const a of axes) {
+          const has = a.name in use.props;
+          const v = use.props[a.name];
+          const key = !has ? a.default ?? "(unset)" : v === null ? "true" : typeof v === "string" && !v.startsWith("(") ? v : typeof v === "boolean" || typeof v === "number" ? String(v) : "(dynamic)";
+          variants[a.name][key] = (variants[a.name][key] ?? 0) + 1;
+        }
+      }
+    }
+    return {
+      name: c.name,
+      source: c.source,
+      uses: count,
+      files: files.size,
+      props: sortKeys(props),
+      ...axes.length && { variants: Object.fromEntries(axes.map((a) => [a.name, sortKeys(variants[a.name])])) }
+    };
+  });
+}
+function sortKeys(o) {
+  return Object.fromEntries(Object.keys(o).sort().map((k) => [k, o[k]]));
+}
+function readJson(root, path) {
+  try {
+    return JSON.parse(readFileSync3(resolve3(root, path), "utf8"));
+  } catch {
+    return void 0;
+  }
+}
+function serialise(report) {
+  return `${JSON.stringify(report, null, 2)}
+`;
+}
+
+export {
+  CONFIG_FILE,
+  UsageError,
+  DEFAULT_INCLUDE,
+  DEFAULT_EXCLUDE,
+  loadConfig,
+  formatMarkdown,
+  TAILWIND_FAMILIES,
+  COLOUR_UTILITIES,
+  restrictionsFor,
+  familiesFromTokens,
+  checkDiscipline,
+  listProductFiles,
+  colourContext,
+  findOverrides,
+  overrideKind,
+  createResolver,
+  mapRoutes,
+  routeOf,
+  scanJsx,
+  flatten,
+  ADHERENCE_SCHEMA,
+  parseSelector,
+  classify,
+  GENERATOR_NAME,
+  VERSION,
+  GENERATOR,
+  buildReport,
+  counts,
+  serialise
+};