synthesisui 0.16.46 → 0.16.47

package/dist/commands/import.js

@@ -3,6 +3,7 @@ import { basename, join, relative } from "node:path";
 import { readToken, resolveRegistry } from "../config.js";
 import { isNearDuplicate } from "../doctor/color-distance.js";
 import { emptyTally, scanComponentsInto, tallyToInventory, } from "../doctor/components-scan.js";
+import { crosswalk } from "../doctor/crosswalk.js";
 import { diagnose, scanSource } from "../doctor/scan.js";
 import { parseSchemeBlocks } from "../doctor/scheme-blocks.js";
 import { buildTable } from "../doctor/tokens.js";
@@ -440,6 +441,43 @@ function printComponents(c) {
     if (mine.length > 12) {
         console.log(body(paint.faint(`(${mine.length - 12} more of yours)`)));
     }
+    printCrosswalk(mine);
+}
+/**
+ * The crosswalk, printed and nothing else.
+ *
+ * Three buckets, each line carrying the evidence that put it there - a name
+ * the catalogue knows, or a measured overlap with something they already wrote.
+ * Nothing is mapped, adopted or sent: the thresholds below are a first guess
+ * and the only way to tune them is to read this against a real codebase, which
+ * is exactly how the colour work found its own.
+ */
+function printCrosswalk(mine) {
+    if (mine.length === 0)
+        return;
+    const rows = crosswalk(mine);
+    const of = (b) => rows.filter((r) => r.bucket === b);
+    const exists = of("exists");
+    const nearly = of("nearly");
+    const exclusive = of("exclusive");
+    console.log("");
+    console.log(section("Which of these already exist"));
+    const show = (title, list, limit) => {
+        if (list.length === 0)
+            return;
+        console.log(body(paint.strong(title)));
+        for (const r of list.slice(0, limit)) {
+            console.log(body(`  ${r.component.name.padEnd(18)} ${paint.faint(`${r.component.files} files`)}  ${paint.dim(r.because)}`));
+        }
+        if (list.length > limit) {
+            console.log(body(paint.faint(`  (${list.length - limit} more)`)));
+        }
+        console.log("");
+    };
+    show(`Already in the catalogue (${exists.length})`, exists, 6);
+    show(`The same decision, twice (${nearly.length})`, nearly, 6);
+    show(`Only yours (${exclusive.length})`, exclusive, 8);
+    console.log(body(paint.dim("Nothing was mapped. This is a reading - the adopting is a decision you make.")));
 }
 function printAgentContract() {
     console.log("");

package/dist/doctor/crosswalk.js

@@ -0,0 +1,307 @@
+/**
+ * THE CROSSWALK - does this component already exist, here or in the catalogue?
+ *
+ * Phase one counted what a project composes. This asks the question that
+ * follows and is the whole reason to ask it: which of those are things the
+ * design system already has, which are the same thing twice, and which are
+ * genuinely theirs.
+ *
+ * Three signals, strongest first, and only the third needs a person:
+ *
+ *   1. THE CANONICAL NAME. `Pill`, `Chip` and `Tag` are a badge. Cheap, and it
+ *      settles most of the list. The table below is curated knowledge, the same
+ *      kind as the hue lanes the colour report argues with.
+ *   2. THE SHAPE OF THE AXES. Two components carrying a closed set on the same
+ *      kind of axis, with values that overlap, are the same kind of thing -
+ *      and overlap is measurable rather than felt.
+ *   3. JUDGEMENT, when the first two disagree. Reported, never applied.
+ *
+ * It runs in BOTH directions on purpose. Comparing only against our catalogue
+ * would have missed the finding that mattered most on a real dashboard (dono,
+ * 30/07): `Loader` (59 uses), `SimpleLoading` (21) and `ShimmerLoader` (158)
+ * are three loading components in one app. Redundancy is redundancy whoever
+ * owns it.
+ */
+/** Their word → the canonical thing it is. */
+const SYNONYM = {
+    button: "button",
+    btn: "button",
+    iconbutton: "button",
+    toolbarbutton: "button",
+    badge: "badge",
+    pill: "badge",
+    chip: "badge",
+    tag: "badge",
+    label: "badge",
+    card: "card",
+    panel: "card",
+    tile: "card",
+    input: "input",
+    textfield: "input",
+    textinput: "input",
+    field: "input",
+    modal: "modal",
+    dialog: "modal",
+    modalbox: "modal",
+    drawer: "drawer",
+    sheet: "drawer",
+    spinner: "spinner",
+    loader: "spinner",
+    loading: "spinner",
+    simpleloading: "spinner",
+    shimmerloader: "skeleton",
+    skeleton: "skeleton",
+    shimmer: "skeleton",
+    tooltip: "tooltip",
+    popover: "popover",
+    avatar: "avatar",
+    alert: "alert",
+    banner: "alert",
+    toast: "toast",
+    snackbar: "toast",
+    tabs: "tabs",
+    table: "table",
+    datatable: "table",
+    select: "select",
+    dropdown: "select",
+    checkbox: "checkbox",
+    radio: "radio",
+    toggle: "switch",
+    switch: "switch",
+    link: "link",
+    anchor: "link",
+    text: "text",
+    typography: "text",
+    heading: "heading",
+    title: "heading",
+    divider: "divider",
+    separator: "divider",
+    breadcrumb: "breadcrumb",
+    progress: "progress",
+    slider: "slider",
+};
+/** What the toolkit ships, with the axes each one carries. Curated because the
+ *  CLI has no catalogue to read offline; kept short and canonical. */
+const CATALOGUE = {
+    button: ["intent", "size"],
+    badge: ["intent"],
+    card: ["intent"],
+    input: ["size"],
+    modal: [],
+    drawer: ["side"],
+    spinner: ["size"],
+    skeleton: [],
+    tooltip: ["side"],
+    popover: ["side"],
+    avatar: ["size"],
+    alert: ["intent"],
+    toast: ["intent"],
+    tabs: [],
+    table: ["density"],
+    select: ["size"],
+    checkbox: [],
+    radio: [],
+    switch: ["size"],
+    link: ["intent"],
+    text: ["size"],
+    heading: ["size"],
+    divider: [],
+    breadcrumb: [],
+    progress: [],
+    slider: [],
+};
+/** Values that mean the same decision under different spellings. */
+const VALUE_SYNONYM = {
+    warn: "warning",
+    destructive: "danger",
+    error: "danger",
+    negative: "danger",
+    positive: "success",
+    ok: "success",
+    info: "info",
+    informational: "info",
+    primary: "primary",
+    main: "primary",
+    secondary: "accent",
+    accent: "accent",
+    neutral: "neutral",
+    default: "neutral",
+    xs: "xs",
+    xsm: "xs",
+    small: "sm",
+    sm: "sm",
+    medium: "md",
+    md: "md",
+    large: "lg",
+    lg: "lg",
+};
+/** Axis names that ask the same question. */
+const AXIS_SYNONYM = {
+    variant: "intent",
+    intent: "intent",
+    tone: "intent",
+    color: "intent",
+    colour: "intent",
+    kind: "intent",
+    type: "intent",
+    status: "intent",
+    severity: "intent",
+    size: "size",
+    scale: "size",
+    density: "density",
+    dense: "density",
+    compact: "density",
+    side: "side",
+    placement: "side",
+    position: "side",
+};
+export function canonicalName(name) {
+    const head = name
+        .split(".")[0]
+        .toLowerCase()
+        .replace(/[^a-z]/g, "");
+    if (SYNONYM[head])
+        return SYNONYM[head];
+    // A compound like `WidgetCard` or `ArrowDownIcon` is only canonical when the
+    // WHOLE word is - a widget card is not a card, it is their own thing.
+    return null;
+}
+export function canonicalAxes(props) {
+    const out = new Set();
+    for (const p of Object.keys(props)) {
+        const axis = AXIS_SYNONYM[p.toLowerCase()];
+        if (axis)
+            out.add(axis);
+    }
+    return out;
+}
+function canonicalValues(values) {
+    return new Set(values
+        .map((v) => v.trim().toLowerCase())
+        .map((v) => VALUE_SYNONYM[v] ?? v)
+        // A raw colour or a css length is a value passed through, not a named
+        // option somebody designed - it says nothing about what this component IS.
+        .filter((v) => v && !/^(#|var\(|rgb|\d)/.test(v)));
+}
+/** How much two components' axis VALUES overlap, 0-1 (Jaccard). */
+export function axisOverlap(a, b) {
+    const va = new Set();
+    const vb = new Set();
+    for (const [p, values] of Object.entries(a)) {
+        if (AXIS_SYNONYM[p.toLowerCase()]) {
+            for (const v of canonicalValues(values))
+                va.add(v);
+        }
+    }
+    for (const [p, values] of Object.entries(b)) {
+        if (AXIS_SYNONYM[p.toLowerCase()]) {
+            for (const v of canonicalValues(values))
+                vb.add(v);
+        }
+    }
+    if (va.size === 0 || vb.size === 0)
+        return 0;
+    let shared = 0;
+    for (const v of va)
+        if (vb.has(v))
+            shared += 1;
+    return shared / new Set([...va, ...vb]).size;
+}
+/** Below this, two components share a value or two by accident. */
+export const TWIN_OVERLAP = 0.5;
+/**
+ * And a ratio needs a denominator worth trusting.
+ *
+ * The first real run called an `InformationIcon` the same decision as a
+ * spinner, at 100% (dono, 30/07) - both carried exactly one readable option,
+ * `sm`, so one shared value out of one union was a perfect score. Same lesson
+ * the colour work learned twice: a ratio over a tiny set says nothing.
+ */
+export const TWIN_MIN_SHARED = 2;
+function sharedCount(a, b) {
+    const va = new Set();
+    const vb = new Set();
+    for (const [p, values] of Object.entries(a)) {
+        if (AXIS_SYNONYM[p.toLowerCase()]) {
+            for (const v of canonicalValues(values))
+                va.add(v);
+        }
+    }
+    for (const [p, values] of Object.entries(b)) {
+        if (AXIS_SYNONYM[p.toLowerCase()]) {
+            for (const v of canonicalValues(values))
+                vb.add(v);
+        }
+    }
+    let n = 0;
+    for (const v of va)
+        if (vb.has(v))
+            n += 1;
+    return n;
+}
+export function crosswalk(components) {
+    const mine = components.filter((c) => !c.from);
+    // Two of THEIR components reading as the same catalogue entry is the
+    // strongest redundancy signal there is, and it needs no threshold: it is not
+    // "these look alike", it is "you wrote this twice". The first run filed both
+    // of a project's spinners as `exists` and said nothing about them being two.
+    const claims = new Map();
+    for (const c of mine) {
+        const k = canonicalName(c.name);
+        if (!k)
+            continue;
+        claims.set(k, [...(claims.get(k) ?? []), c.name]);
+    }
+    return mine
+        .map((component) => {
+        const canonical = canonicalName(component.name);
+        const twins = mine
+            .filter((o) => o.name !== component.name)
+            .map((o) => ({
+            name: o.name,
+            overlap: axisOverlap(component.props, o.props),
+        }))
+            .filter((t) => t.overlap >= TWIN_OVERLAP &&
+            sharedCount(component.props, mine.find((m) => m.name === t.name)?.props ?? {}) >= TWIN_MIN_SHARED)
+            .sort((a, b) => b.overlap - a.overlap);
+        if (canonical && CATALOGUE[canonical]) {
+            const alsoClaiming = (claims.get(canonical) ?? []).filter((n) => n !== component.name);
+            if (alsoClaiming.length > 0) {
+                return {
+                    component,
+                    canonical,
+                    twins,
+                    bucket: "nearly",
+                    because: `you have ${alsoClaiming.length + 1} components that all read as ds-${canonical} (${[component.name, ...alsoClaiming].join(", ")})`,
+                };
+            }
+            const axes = [...canonicalAxes(component.props)];
+            return {
+                component,
+                canonical,
+                twins,
+                bucket: "exists",
+                because: axes.length
+                    ? `reads as ds-${canonical}; its ${axes.join(" and ")} ${axes.length === 1 ? "maps" : "map"} onto ours`
+                    : `reads as ds-${canonical}`,
+            };
+        }
+        if (twins.length > 0) {
+            return {
+                component,
+                canonical,
+                twins,
+                bucket: "nearly",
+                because: `shares ${Math.round(twins[0].overlap * 100)}% of its options with ${twins[0].name} - one decision, two components`,
+            };
+        }
+        return {
+            component,
+            canonical,
+            twins,
+            bucket: "exclusive",
+            because: "nothing in the catalogue does this - it is yours",
+        };
+    })
+        .sort((a, b) => b.component.files - a.component.files);
+}

package/package.json

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