adsa-cli 0.1.1 → 0.1.4

package/lib/score.mjs

@@ -10,6 +10,8 @@ const here = dirname(fileURLToPath(import.meta.url));
 export const RUBRIC = JSON.parse(readFileSync(join(here, "..", "rubric", "rubric.json"), "utf8"));
 
 const pct = (n) => `${Math.round(n * 100)}%`;
+/** Evidence lines end up on a landing page and in a pull request. They read as English. */
+const plural = (n, one, many = `${one}s`) => `${n} ${n === 1 ? one : many}`;
 
 /** What "accessibility documentation" means in the vocabulary of each platform. */
 const A11Y_LABEL = {
@@ -22,10 +24,13 @@ const A11Y_LABEL = {
 const SCORERS = {
     "agent-instructions"(f) {
         const files = f.agentFiles.filter((a) => a.lines > 3);
-        const main = files.find((a) => a.mentionsPackage) || files[0];
+        // A file in the package's own directory is about the package. Requiring the
+        // name in the text is the right question for a monorepo root, and the wrong one
+        // for the AGENTS.md a single-package repository keeps beside its components.
+        const main = files.find((a) => a.mentionsPackage) || files.find((a) => a.scope !== "repo") || files[0];
         if (!main) return { score: 1, evidence: ["No AGENTS.md, CLAUDE.md or equivalent in the repository."] };
-        const ev = [`${main.file}, ${main.lines} lines.`];
-        if (!main.mentionsPackage) {
+        const ev = [`${main.label || main.file}, ${main.lines} lines.`];
+        if (!main.mentionsPackage && main.scope === "repo") {
             ev.push(`It never mentions ${f.name}, so an agent gets no design-system rules from it.`);
             return { score: 1, evidence: ev };
         }
@@ -46,15 +51,22 @@ const SCORERS = {
     "machine-surface"(f) {
         const m = f.machine;
         const ev = [];
+        const served = m.servedMcp || [];
+        const siblings = m.siblingClis || [];
+        const commands = m.commands || [];
         if (m.mcpInPackage) ev.push(`An MCP server ships inside the package (bin: ${m.binNames.join(", ")}).`);
+        if (served.length) ev.push(`This repository serves an MCP server: ${served.slice(0, 3).join(", ")}.`);
         if (m.declaredServers.length) ev.push(`${m.mcpConfigs.join(", ")} registers ${m.declaredServers.join(", ")}.`);
         if (m.cliShipped && !m.mcpInPackage) ev.push(`A CLI ships with the package (bin: ${m.binNames.join(", ")}).`);
+        if (siblings.length) ev.push(`A CLI ships from ${siblings.map((c) => `${c.name} (${c.bin.join(", ")})`).slice(0, 2).join(", ")}.`);
         if (m.llmsTxt.length) ev.push(`${m.llmsTxt.join(", ")} present.`);
         if (m.skills.length) ev.push(`${m.skills.length} agent skill${m.skills.length === 1 ? "" : "s"} published.`);
+        if (commands.length) ev.push(`${commands.length} agent command${commands.length === 1 ? "" : "s"} published.`);
         if (m.storybookMcp) ev.push("@storybook/addon-mcp is installed, which answers from a running Storybook in this repo only.");
         if (!ev.length) ev.push("No MCP server, no docs CLI, no llms.txt, no published skills: an agent has to read files.");
-        const score = m.mcpInPackage || m.declaredServers.length ? 5 : m.cliShipped || m.llmsTxt.length || m.skills.length || m.storybookMcp ? 3 : 1;
-        return { score, evidence: ev };
+        const mcp = m.mcpInPackage || m.declaredServers.length || served.length;
+        const queryable = m.cliShipped || siblings.length || m.llmsTxt.length || m.skills.length || commands.length || m.storybookMcp;
+        return { score: mcp ? 5 : queryable ? 3 : 1, evidence: ev };
     },
 
     "docs-coverage"(f) {
@@ -74,7 +86,7 @@ const SCORERS = {
         const ev = [`${f.guides.length} guides, ${s.blocks} code blocks, ${s.guidesWithPropTable} with a prop table.`];
         if (s.guidesGenerated) ev.push(`${s.guidesGenerated} guides carry a generated marker.`);
         else ev.push("No guide is marked as generated, so every table is hand-maintained.");
-        if (s.unknownCount) ev.push(`${s.unknownCount} imports in the guides name symbols this repo does not export, e.g. ${s.unknownImports.slice(0, 3).map((u) => `${u.name} in ${u.guide}`).join("; ")}.`);
+        if (s.unknownCount) ev.push(`${plural(s.unknownCount, "import")} in the guides ${s.unknownCount === 1 ? "names a symbol" : "name symbols"} this repo does not export, e.g. ${s.unknownImports.slice(0, 3).map((u) => `${u.name} in ${u.guide}`).join("; ")}.`);
         else ev.push("Every symbol imported in the guides exists in the source.");
         ev.push(s.compiledInCi ? "CI checks the guides against the code." : "Nothing compares the guides to the code.");
         let score = s.compiledInCi && s.guidesGenerated ? 5 : s.guidesGenerated || s.guidesWithPropTable ? 3 : 1;
@@ -123,7 +135,7 @@ const SCORERS = {
 
     verification(f) {
         const v = f.verification;
-        const ev = [`${v.testFiles} test files, ${v.storyFiles} stories.`];
+        const ev = [`${plural(v.testFiles, "test file")}, ${plural(v.storyFiles, "story", "stories")}.`];
         const bits = [v.testScript && "test", v.typecheckScript && "typecheck", v.lintScript && "lint"].filter(Boolean);
         ev.push(bits.length ? `Scripts: ${bits.join(", ")}.` : "No test, typecheck or lint script.");
         if (v.workflows.length) ev.push(`CI: ${v.workflows.join(", ")}.`);

package/lib/target.mjs

@@ -0,0 +1,82 @@
+/**
+ * Which directory to audit. A design system usually lives in a monorepo, and the
+ * package the reader means is rarely the directory they typed: they hand over the
+ * repository and expect the tool to find the components.
+ *
+ * Getting this wrong is the worst thing this tool can do. Every dimension is then
+ * measured from inside the wrong folder, and "no agent instructions in the
+ * repository" means "none in a subfolder of a repository that has them".
+ */
+import { join, basename } from "node:path";
+import { isDir, readJson, rel } from "./fsx.mjs";
+import { countGuides, workspaceDirs } from "./config.mjs";
+import { countComponents } from "./scan.mjs";
+
+/**
+ * @param {string} root the directory the reader named
+ * @param {{workspace?:string, noWorkspace?:boolean}} options `--workspace` / `--no-workspace`
+ * @returns {{ dir:string, note:string|null, candidates:Array<object>, error?:string }}
+ */
+export function resolveTarget(root, options = {}) {
+    if (options.noWorkspace) return { dir: root, note: null, candidates: [] };
+
+    if (options.workspace) {
+        const all = profile(workspaceDirs(root), true);
+        const wanted = all.find((c) => c.name === options.workspace || basename(c.dir) === options.workspace || rel(root, c.dir) === options.workspace);
+        if (!wanted) {
+            const known = all.map((c) => c.name).join(", ") || "none";
+            return { dir: root, note: null, candidates: all, error: `No workspace matches "${options.workspace}". This repository has: ${known}.` };
+        }
+        return { dir: wanted.dir, note: `workspace: audited ${wanted.name} (--workspace)`, candidates: all };
+    }
+
+    // A root that publishes the components itself is the package, whatever else the
+    // repository keeps beside it: its own export map is what a consumer installs.
+    const pkg = readJson(join(root, "package.json"));
+    const rootExports = Object.keys(pkg?.exports || {}).filter((k) => k.startsWith("./")).length;
+    if (rootExports >= 5 || isDir(join(root, "guidelines"))) return { dir: root, note: null, candidates: [] };
+
+    const workspaces = workspaceDirs(root);
+    if (!workspaces.length) return { dir: root, note: null, candidates: [] };
+
+    // Published packages first. Only when none of them exports a component does a
+    // private workspace count: a repository that keeps its components in its own docs
+    // app — a registry, a showcase — still keeps them somewhere, and reporting a
+    // repository full of components as having none is the worse answer.
+    const published = profile(workspaces, false);
+    const all = published.some((c) => c.components > 0) ? published : profile(workspaces, true);
+    const withComponents = all.filter((c) => c.components > 0);
+    if (!withComponents.length) return { dir: root, note: null, candidates: all };
+
+    const best = withComponents[0];
+    const runnerUp = withComponents[1];
+    const note = `workspace: audited ${best.name}, ${best.components} components${runnerUp ? ` (next: ${runnerUp.name}, ${runnerUp.components})` : ""}`;
+    return { dir: best.dir, note, candidates: withComponents };
+}
+
+/**
+ * Rank the packages by what actually distinguishes a design system: the number of
+ * components a consumer can import from it. Ranking by the presence of a `docs/`
+ * folder — what this did before — hands the audit to whichever package happens to
+ * keep markdown next to it, and a codemod package with thirty migration notes beat
+ * the component library every time.
+ *
+ * `explicit` is a name the reader typed, so nothing is filtered out: a private
+ * workspace is still a package somebody can ask to audit.
+ */
+/** `"private": "true"` is in the wild, and reads as published to a strict check. */
+const isPrivate = (pkg) => pkg.private === true || pkg.private === "true";
+
+function profile(dirs, explicit) {
+    const out = [];
+    for (const dir of dirs) {
+        const pkg = readJson(join(dir, "package.json"));
+        if (!pkg || (isPrivate(pkg) && !explicit)) continue;
+        const components = countComponents(dir);
+        const guides = countGuides(dir);
+        const exports_ = Object.keys(pkg.exports || {}).filter((k) => k.startsWith("./")).length;
+        if (!explicit && !components && !guides && !exports_) continue;
+        out.push({ dir, name: pkg.name || basename(dir), components, guides, exports: exports_ });
+    }
+    return out.sort((a, b) => b.components - a.components || b.guides - a.guides || b.exports - a.exports);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "adsa-cli",
-    "version": "0.1.1",
+    "version": "0.1.4",
     "description": "Score a design system on how well coding agents can use it, then fix what is missing.",
     "type": "module",
     "bin": {

package/rubric/reference.json

@@ -0,0 +1,293 @@
+{
+    "note": "Public design systems audited with this rubric, at the commit named. Reproduce with `npx adsa-cli audit <clone>`.",
+    "rubric": "1.0",
+    "measured": "2026-09-10",
+    "systems": [
+        {
+            "name": "Astryx",
+            "org": "Meta",
+            "repo": "facebook/astryx",
+            "commit": "5447429bac",
+            "package": "@astryxdesign/core",
+            "version": "0.5.4",
+            "packageDir": "packages/core",
+            "total": 33,
+            "max": 45,
+            "dimensions": {
+                "agent-instructions": 3,
+                "machine-surface": 5,
+                "docs-coverage": 3,
+                "docs-freshness": 3,
+                "tokens": 3,
+                "patterns": 5,
+                "a11y": 3,
+                "verification": 5,
+                "gap-handling": 3
+            }
+        },
+        {
+            "name": "Chakra UI",
+            "org": "",
+            "repo": "chakra-ui/chakra-ui",
+            "commit": "67abe9fb80",
+            "package": "@chakra-ui/react",
+            "version": "3.37.0",
+            "packageDir": "packages/react",
+            "total": 29,
+            "max": 45,
+            "dimensions": {
+                "agent-instructions": 3,
+                "machine-surface": 5,
+                "docs-coverage": 3,
+                "docs-freshness": 3,
+                "tokens": 5,
+                "patterns": 5,
+                "a11y": 1,
+                "verification": 3,
+                "gap-handling": 1
+            }
+        },
+        {
+            "name": "React Spectrum",
+            "org": "Adobe",
+            "repo": "adobe/react-spectrum",
+            "commit": "4693fcc844",
+            "package": "@react-spectrum/s2",
+            "version": "1.7.1",
+            "packageDir": "packages/@react-spectrum/s2",
+            "total": 25,
+            "max": 45,
+            "dimensions": {
+                "agent-instructions": 3,
+                "machine-surface": 5,
+                "docs-coverage": 3,
+                "docs-freshness": 3,
+                "tokens": 3,
+                "patterns": 3,
+                "a11y": 1,
+                "verification": 3,
+                "gap-handling": 1
+            }
+        },
+        {
+            "name": "shadcn/ui",
+            "org": "",
+            "repo": "shadcn-ui/ui",
+            "commit": "3ba91b1cc8",
+            "package": "v4",
+            "version": "0.1.0",
+            "packageDir": "apps/v4",
+            "total": 25,
+            "max": 45,
+            "dimensions": {
+                "agent-instructions": 1,
+                "machine-surface": 5,
+                "docs-coverage": 3,
+                "docs-freshness": 3,
+                "tokens": 3,
+                "patterns": 5,
+                "a11y": 1,
+                "verification": 3,
+                "gap-handling": 1
+            }
+        },
+        {
+            "name": "HeroUI",
+            "org": "",
+            "repo": "heroui-inc/heroui",
+            "commit": "98553cefdc",
+            "package": "@heroui/react",
+            "version": "3.2.4",
+            "packageDir": "packages/react",
+            "total": 23,
+            "max": 45,
+            "dimensions": {
+                "agent-instructions": 3,
+                "machine-surface": 3,
+                "docs-coverage": 1,
+                "docs-freshness": 1,
+                "tokens": 3,
+                "patterns": 5,
+                "a11y": 3,
+                "verification": 3,
+                "gap-handling": 1
+            }
+        },
+        {
+            "name": "Polaris",
+            "org": "Shopify",
+            "repo": "Shopify/polaris",
+            "commit": "3f7954ae42",
+            "package": "@shopify/polaris",
+            "version": "13.10.1",
+            "packageDir": "polaris-react",
+            "total": 23,
+            "max": 45,
+            "dimensions": {
+                "agent-instructions": 1,
+                "machine-surface": 3,
+                "docs-coverage": 1,
+                "docs-freshness": 3,
+                "tokens": 5,
+                "patterns": 5,
+                "a11y": 1,
+                "verification": 3,
+                "gap-handling": 1
+            }
+        },
+        {
+            "name": "BoardUI",
+            "org": "",
+            "repo": "BoardUI/boardui",
+            "commit": "3e76e28261",
+            "package": "boardui@0.5.5",
+            "packageDir": ".",
+            "via": "npx boardui add + skill, in the starter repo",
+            "total": 21,
+            "max": 45,
+            "dimensions": {
+                "agent-instructions": 3,
+                "machine-surface": 3,
+                "docs-coverage": 1,
+                "docs-freshness": 1,
+                "tokens": 3,
+                "patterns": 5,
+                "a11y": 1,
+                "verification": 3,
+                "gap-handling": 1
+            }
+        },
+        {
+            "name": "Mantine",
+            "org": "",
+            "repo": "mantinedev/mantine",
+            "commit": "61049ecd95",
+            "package": "@mantine/core",
+            "version": "9.6.1",
+            "packageDir": "packages/@mantine/core",
+            "total": 21,
+            "max": 45,
+            "dimensions": {
+                "agent-instructions": 3,
+                "machine-surface": 3,
+                "docs-coverage": 3,
+                "docs-freshness": 1,
+                "tokens": 3,
+                "patterns": 3,
+                "a11y": 1,
+                "verification": 3,
+                "gap-handling": 1
+            }
+        },
+        {
+            "name": "Base UI",
+            "org": "MUI",
+            "repo": "mui/base-ui",
+            "commit": "9f4551b4cb",
+            "package": "@base-ui/react",
+            "version": "1.8.0",
+            "packageDir": "packages/react",
+            "total": 19,
+            "max": 45,
+            "dimensions": {
+                "agent-instructions": 1,
+                "machine-surface": 3,
+                "docs-coverage": 1,
+                "docs-freshness": 3,
+                "tokens": 1,
+                "patterns": 5,
+                "a11y": 1,
+                "verification": 3,
+                "gap-handling": 1
+            }
+        },
+        {
+            "name": "Carbon",
+            "org": "IBM",
+            "repo": "carbon-design-system/carbon",
+            "commit": "12277c649e",
+            "package": "@carbon/react",
+            "version": "1.116.0",
+            "packageDir": "packages/react",
+            "total": 19,
+            "max": 45,
+            "dimensions": {
+                "agent-instructions": 3,
+                "machine-surface": 3,
+                "docs-coverage": 1,
+                "docs-freshness": 1,
+                "tokens": 3,
+                "patterns": 3,
+                "a11y": 1,
+                "verification": 3,
+                "gap-handling": 1
+            }
+        },
+        {
+            "name": "Primer",
+            "org": "GitHub",
+            "repo": "primer/react",
+            "commit": "4dc92ecc50",
+            "package": "@primer/react",
+            "version": "38.38.0",
+            "packageDir": "packages/react",
+            "total": 17,
+            "max": 45,
+            "dimensions": {
+                "agent-instructions": 3,
+                "machine-surface": 5,
+                "docs-coverage": 1,
+                "docs-freshness": 1,
+                "tokens": 1,
+                "patterns": 1,
+                "a11y": 1,
+                "verification": 3,
+                "gap-handling": 1
+            }
+        },
+        {
+            "name": "Radix Primitives",
+            "org": "WorkOS",
+            "repo": "radix-ui/primitives",
+            "commit": "f7ecd5ab16",
+            "package": "radix-ui",
+            "version": "1.6.7",
+            "packageDir": "packages/react/radix-ui",
+            "total": 13,
+            "max": 45,
+            "dimensions": {
+                "agent-instructions": 3,
+                "machine-surface": 1,
+                "docs-coverage": 1,
+                "docs-freshness": 1,
+                "tokens": 1,
+                "patterns": 1,
+                "a11y": 1,
+                "verification": 3,
+                "gap-handling": 1
+            }
+        },
+        {
+            "name": "Untitled UI React",
+            "org": "",
+            "repo": "untitleduico/react",
+            "commit": "c981a73bcd",
+            "package": "@untitledui/react",
+            "version": "0.0.0",
+            "packageDir": ".",
+            "total": 13,
+            "max": 45,
+            "dimensions": {
+                "agent-instructions": 3,
+                "machine-surface": 1,
+                "docs-coverage": 1,
+                "docs-freshness": 1,
+                "tokens": 1,
+                "patterns": 1,
+                "a11y": 1,
+                "verification": 3,
+                "gap-handling": 1
+            }
+        }
+    ]
+}

package/skills/ds-audit/SKILL.md

@@ -49,6 +49,23 @@ npx adsa-cli audit <path>            # score, report, .adsa/score.json
 npx adsa-cli audit <path> --json     # the same, machine-readable
 ```
 
+**Show the tool's own output.** It prints a coloured bar per dimension, the band the
+score falls in, and where that score sits against the public design systems in the reference set. Paste
+that block as it came out. Do not rebuild it as a markdown table: your table drops the
+bars, the band and the standing, and it is one retyping away from being wrong about a
+number the reader could otherwise have checked.
+
+The run opens `report.html` and prints its `file://` link. Do not ask whether to open
+it, and do not offer to fix everything before the reader has read anything — the
+report is the deliverable, and what to fix first is a decision it exists to inform.
+
+**Check the scan line before you believe the score.** `scanned:` says which directories
+were read and which package was picked out of a monorepo. If the guides say `none
+found` and you can see a documentation site in the repository, the audit is measuring
+the wrong folder: fix it with `--workspace <name>` or a `guides` entry in
+`adsa.config.json`, and re-run before reporting anything. A wrong scope reads as an
+undocumented system, and that is the one mistake that makes the whole audit worthless.
+
 Read `.adsa/report.md` and the evidence under every dimension. The score is a
 starting point, not the finding.
 
@@ -80,8 +97,21 @@ so every invention is a gap the system never declared.
 
 ## Phase 4 — Compare
 
-Say where the system stands against systems that have done this work, by trait, not
-by vibe. The ones worth checking, and what each is known for:
+The reference set is measured, not remembered: `rubric/reference.json` in the tool
+holds every public design system measured with this rubric, at a named commit, and
+the terminal already told the reader where their score sits in it. Quote that, and
+reproduce any figure you are unsure of with `npx adsa-cli audit <clone>`.
+
+Two things to say out loud, because a reader will otherwise assume the opposite:
+
+- **45 is nobody's score.** The best-documented public system measured reaches 33.
+  A number in the twenties is the middle of the field, not a failing grade.
+- **This is not a ranking of design systems.** It measures what a coding agent can
+  find in the repository. A system whose documentation lives on an excellent website
+  scores low here and may be the better design system for people.
+
+Then say where the system stands by trait, not by vibe. The ones worth checking, and
+what each is known for:
 
 | System | What to look at |
 | :-- | :-- |
@@ -111,6 +141,9 @@ Then say what to do first, in one sentence, and stop. Do not pad.
 
 ## Phase 6 — Fix
 
+Only after the reader has seen the findings, and one fix at a time unless they ask
+for more. `fix --all` is theirs to run, not yours to propose as the first move.
+
 ```bash
 npx adsa-cli fix --list        # what is automatic and what is a brief
 npx adsa-cli fix agents-md     # writes files
@@ -126,6 +159,8 @@ After the fixes: `npx adsa-cli audit` again. The delta is the deliverable.
 ## Rules
 
 - Never invent a finding. Every claim names a file, a line or a command output.
+- Never retype the tool's output. Paste it.
+- A score without its band and its standing is a number nobody can act on.
 - Report a dimension you could not assess as not assessed. Do not guess a number.
 - Quote the repository, not your memory of similar repositories.
 - The score belongs to a version. Say which one you audited.