synthesisui 0.6.0 → 0.7.0

package/README.md

@@ -99,8 +99,28 @@ worse than none.
 With no system installed it still finds every hand-written value and counts
 the distinct ones. Runs offline, needs no account, writes nothing.
 
-`--strict` exits 1 when drift is found, for CI. `--all` lists everything
-instead of the loudest files.
+### What your system says
+
+```
+── What your system says about what you use ──────────────────────
+
+  ds-badge  ·  3 places
+      Badges whisper status in periwinkle; danger appears only for money at risk.
+
+  ds-button  ·  3 places
+      One indigo action per view; gold is reserved for moments of ceremony, never buttons.
+      Buttons speak quietly - sentence case, no exclamation.
+```
+
+The usage laws your team wrote, for the components this project actually uses,
+ordered by how much you use them. They are prose, so nothing verifies them -
+the value is putting them in front of whoever is touching the component. No
+other tool is positioned to do it, because no other tool knows these laws
+exist.
+
+`--strict` exits 1 when drift is found, for CI. `--all` lists every finding
+instead of the loudest files. `--laws` shows every law instead of the busiest
+components.
 
 ## What `add` materializes
 

package/dist/commands/doctor.js

@@ -1,6 +1,6 @@
 import { readdir, readFile } from "node:fs/promises";
 import { join, relative, resolve } from "node:path";
-import { bindingsFromDocument, findOverrides, } from "../doctor/overrides.js";
+import { bindingsFromDocument, countComponents, findOverrides, } from "../doctor/overrides.js";
 import { diagnose, scanSource, } from "../doctor/scan.js";
 import { buildTable, EMPTY_TABLE } from "../doctor/tokens.js";
 import { body, section, snippet } from "../output.js";
@@ -132,7 +132,7 @@ function meter(pct, width = 24) {
     const filled = Math.round((pct / 100) * width);
     return `${"█".repeat(filled)}${"░".repeat(width - filled)}`;
 }
-function verdict(d, hasSystem) {
+function verdict(d, hasSystem, overruled) {
     // Nothing found and nothing installed: a utility package, a config folder,
     // the wrong directory. Selling a design system here would be noise.
     if (!hasSystem && d.findings.length === 0) {
@@ -152,12 +152,26 @@ function verdict(d, hasSystem) {
             body("Browse systems at https://www.synthesisui.com/gallery"),
         ];
     }
-    if (d.findings.length === 0) {
+    if (d.findings.length === 0 && overruled === 0) {
         return [
             body("No drift. Every design value in this project comes from the"),
             body("system. That is a rarer sentence than it sounds."),
         ];
     }
+    // A report that accuses a component of being overruled and then closes with
+    // "no drift" is a report nobody believes twice.
+    if (d.findings.length === 0) {
+        return [
+            body("No loose values - everything is a token."),
+            body(overruled === 1
+                ? "But one place takes a component the system defines and"
+                : `But ${overruled} places take a component the system defines and`),
+            body(overruled === 1
+                ? "overrules it locally. Either the recipe should change, or"
+                : "overrule it locally. Either the recipe should change, or"),
+            body("that override should not be there."),
+        ];
+    }
     const lines = [
         body(`${d.named} of ${d.findings.length} already have a name in your system.`),
         body("Those are the cheap ones: swap the literal for the token."),
@@ -173,6 +187,8 @@ export async function doctor(opts) {
     const hasSystem = table.byName.size > 0;
     const reports = [];
     const overrides = [];
+    const used = new Map();
+    const known = new Set(recipes.keys());
     for await (const file of walk(root)) {
         const src = await readFile(file, "utf8").catch(() => "");
         if (!src)
@@ -182,6 +198,9 @@ export async function doctor(opts) {
         if (recipes.size > 0) {
             for (const o of findOverrides(src, recipes))
                 overrides.push({ ...o, file: rel });
+            for (const [name, n] of countComponents(src, known)) {
+                used.set(name, (used.get(name) ?? 0) + n);
+            }
         }
     }
     if (reports.length === 0) {
@@ -193,7 +212,10 @@ export async function doctor(opts) {
     console.log(body(hasSystem
         ? `${table.name ?? table.slug} v${table.version ?? "?"} - ${table.byName.size} tokens, ${d.scanned} files read`
         : `No system installed - ${d.scanned} files read`));
-    if (hasSystem) {
+    // 0 of 0 is not a perfect score, it is an empty measurement - printing a
+    // full bar there would be the report's first lie.
+    const measurable = d.tokenUses + d.findings.length > 0;
+    if (hasSystem && measurable) {
         console.log("");
         console.log(body(`Token coverage  ${meter(d.coverage)}  ${String(d.coverage).padStart(3)}%`));
         console.log(body(`                ${d.tokenUses} from the system, ${d.findings.length} by hand`));
@@ -271,8 +293,34 @@ export async function doctor(opts) {
             console.log(body(`+${byFile.size - shown.length} more files. Run with --all.`));
         }
     }
+    // The system's own words, for the components this project actually uses.
+    // Prose, so nothing verifies it - the value is putting it in front of
+    // whoever is touching the component, which no other tool is positioned to
+    // do because no other tool knows these laws exist.
+    const inUse = [...used.entries()]
+        .filter(([name]) => (recipes.get(name)?.usage.length ?? 0) > 0)
+        .sort((a, b) => b[1] - a[1]);
+    if (inUse.length > 0) {
+        console.log(section("What your system says about what you use"));
+        const shownComps = opts.laws || opts.all ? inUse : inUse.slice(0, 4);
+        for (const [name, count] of shownComps) {
+            const laws = recipes.get(name)?.usage ?? [];
+            const shown = opts.laws || opts.all ? laws : laws.slice(0, 2);
+            console.log(body(`ds-${name}  ·  ${count} place${count === 1 ? "" : "s"}`));
+            for (const law of shown)
+                console.log(`      ${law}`);
+            if (laws.length > shown.length) {
+                console.log(`      +${laws.length - shown.length} more`);
+            }
+            console.log("");
+        }
+        if (inUse.length > shownComps.length) {
+            console.log(body(`+${inUse.length - shownComps.length} more components carry laws. Run with --laws.`));
+            console.log("");
+        }
+    }
     console.log(section("What this means"));
-    for (const line of verdict(d, hasSystem))
+    for (const line of verdict(d, hasSystem, overrides.length))
         console.log(line);
     console.log("");
     if (opts.strict && (d.findings.length > 0 || overrides.length > 0))

package/dist/doctor/overrides.js

@@ -46,7 +46,24 @@ export function bindingsOf(recipe) {
     collect(r.variants, false);
     collect(r.states, false);
     collect(r.parts, false);
-    return { props, baseValues };
+    const usage = Array.isArray(r.usage)
+        ? r.usage.filter((x) => typeof x === "string")
+        : [];
+    return { props, baseValues, usage };
+}
+/**
+ * How many places each known component is used. An inventory nobody has today:
+ * a design system's own report can say "ds-button, 14 places" because it knows
+ * which names are components rather than guessing at class strings.
+ */
+export function countComponents(source, known) {
+    const out = new Map();
+    for (const m of source.matchAll(DS_IN_CLASS)) {
+        if (!known.has(m[1]))
+            continue;
+        out.set(m[1], (out.get(m[1]) ?? 0) + 1);
+    }
+    return out;
 }
 /**
  * Tailwind utilities that plainly set a CSS property. Deliberately short:

package/dist/index.js

@@ -27,7 +27,8 @@ Usage - deterministic, FREE:
   synthesisui use <slug> "<intent>"        print a ready-to-paste agent prompt to build/modify on-system
   synthesisui clean [--force]              strip create-next-app boilerplate (dry run without --force)
   synthesisui doctor [--strict] [--all]    audit this repo for DRIFT: every design value written by
-                                           hand, and the token your system already has for it
+                                           hand, the token your system already has for it, and the
+                                           laws your system carries for what you use
 
 Usage - AI, USES CREDITS (login required):
   synthesisui generate "<desc>"            AI-create a NEW component your DS doesn't have (token-only recipe)
@@ -53,6 +54,7 @@ Options:
   --force            clean: apply the changes (without it, dry run)
   --strict           doctor: exit 1 when drift is found (for CI)
   --all              doctor: list every finding, not just the loudest files
+  --laws             doctor: show every usage law, not just the busiest components
   --out <path>       output path for the generated template (default: <pagesDir>/<file>)
   -h, --help         this help
 
@@ -122,6 +124,7 @@ async function main() {
                 dir,
                 strict: flags.strict === true,
                 all: flags.all === true,
+                laws: flags.laws === true,
             });
             break;
         case "list":

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "synthesisui",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Bring SynthesisUI design systems into any project - tokens, typed components, whole pages and an agent-ready CLAUDE.md manifest.",
   "type": "module",
   "bin": {