synthesisui 0.16.80 → 0.16.81

package/dist/doctor/component-gate.js

@@ -0,0 +1,235 @@
+/**
+ * IS THIS A COMPONENT OF A DESIGN SYSTEM?
+ *
+ * Nothing asked. The definition reader matched `export const X` / `export function X`
+ * for any capitalised name, and pointed at a whole monorepo it found **704
+ * components in a repo that has 37** (dono, 01/08). The other 667 were:
+ *
+ *     ds-activation-page          a route
+ *     ds-auth-layout              a Next layout
+ *     ds-cache-providers          a provider
+ *     ds-approvals-monitoring-template
+ *
+ * A page is not a component of a design system, and it has no visual identity to
+ * draw - which is why the vitrine came back unreadable. The renderer was not the
+ * problem; 95% of what entered had nothing to render.
+ *
+ * WHAT THIS IS NOT. It is not a quality bar and it never asks whether something is
+ * good. Every test here is about CATEGORY: a route, a provider, a config object.
+ * And nothing disappears - every rejection carries a reason, and the import prints
+ * them grouped, because "649 seen, not imported, and here is why" is information and
+ * a silent drop is a lie.
+ *
+ * FEWER AND BETTER. 37 components that all draw is a transformative result; 704
+ * where 30 draw is a broken product. This is the pipeline choosing legibility over
+ * coverage.
+ */
+import { localOnlyNames } from "./components-scan.js";
+/**
+ * Next's own reserved file names. Exact, not heuristic: the framework defines these,
+ * so a file called `page.tsx` IS a route in every Next codebase there is.
+ */
+const RESERVED_FILE = /(^|[/\\])(page|layout|template|default|error|global-error|not-found|loading|route|middleware|instrumentation|sitemap|robots|opengraph-image|icon|apple-icon|manifest)\.[jt]sx?$/;
+/** Nuxt, SvelteKit and Remix equivalents, for the same exact reason. */
+const RESERVED_FILE_OTHER = /(^|[/\\])(\+page|\+layout|\+server|_app|_document|_layout)\.[a-z]+$/;
+/**
+ * A name that means WHOLE SCREEN in every codebase.
+ *
+ * Suffix-decisive, and deliberately short. `Page`, `Screen`, `Route` and `Template`
+ * name a destination; `Layout` names the frame around one. A component library does
+ * not export those, and the 704-component run was mostly these four words.
+ *
+ * `View` is NOT here on purpose: `TreeView` and `ListView` are components in a
+ * hundred libraries. It only counts when the file itself is a route.
+ */
+const SCREEN_SUFFIX = /(Page|Screen|Route|Template|Layout)$/;
+/** Something that carries context down the tree rather than drawing. */
+const PROVIDER_SUFFIX = /(Provider|Providers|Context|Boundary|Guard|Wrapper)$/;
+/** Any JSX at all in the file. A capitalised export with none is a constant, a
+ *  config object or a helper - `export const ROUTES = {…}` is not a component. */
+const HAS_JSX = /<[A-Za-z][^>]*>|<>/;
+/**
+ * Any sign that this file decides how something LOOKS.
+ *
+ * The generic catch, and the one that gets the providers whose names give nothing
+ * away. A file with no class, no style, no styled-anything and no variant helper is
+ * plumbing: it may render, but every pixel it produces was decided somewhere else.
+ */
+const HAS_STYLING = /className|class=|style=|styled[.(]|css`|cva\(|\btv\(|makeStyles|sx=|tw`/;
+/** `createContext` + a `.Provider` in the return is a provider whatever it is
+ *  called - `RootWrapper` and `CommonProviders` both read this way. */
+const IS_CONTEXT = /createContext\s*[<(]/;
+/** A lowercase JSX tag: an html element this file renders ITSELF. */
+const OWN_ELEMENT = /<(?:[a-z][a-z0-9]*)(\s|>|\/)/;
+/** Every capitalised JSX tag the file opens, dots included. */
+const RENDERED_TAG = /<([A-Z][A-Za-z0-9_]*(?:\.[A-Za-z0-9_]+)*)/g;
+/** `import … from "some-package"` - not relative, not an alias of theirs. */
+const THIRD_PARTY_IMPORT = /import\s+(?:type\s+)?([\s\S]*?)\s+from\s+["'](?![./]|@\/)([^"']+)["']/g;
+/**
+ * A file whose every pixel belongs to somebody else's component.
+ *
+ * `apps/web-dashboard/src/components/ui/_legacy/_chakra-ui/accordion.tsx` forwards
+ * to `<Accordion.ItemTrigger>` and renders no element of its own; 205 files like it
+ * arrived as components of the system (dono, 01/08). The first version rejected them
+ * for "deciding nothing about how anything looks", which reached the right outcome
+ * with a false reason - `gap="4"` and `rotate={…}` ARE styling decisions, just not
+ * through a class.
+ *
+ * The truthful category is the one this pipeline already has a word for: EXTERNAL.
+ * A component that renders only a third party's components, with no element of its
+ * own, is an ADAPTER for that library. Its markup and its pixels are that library's,
+ * and a design system that claimed them would be claiming what it cannot re-theme.
+ *
+ * The test needs no list of style props, which is why it holds across Chakra, Panda,
+ * MUI and whatever comes next: no html element of its own AND it imports components
+ * from a package.
+ */
+function adapterFor(source, internal) {
+    // It renders an html element of its own: whatever else it does, some pixel here is
+    // this file's decision.
+    if (OWN_ELEMENT.test(source))
+        return null;
+    /**
+     * THE POLYMORPHIC ESCAPE, and it is not a detail.
+     *
+     * `function Text({ as: Component = "p" })` renders `<Component>` and no lowercase
+     * tag, so the first version of this test rejected the real `Text` and `Pill` of a
+     * real library as adapters (spec, 01/08). `Component` is a prop rename - a name the
+     * file BINDS - and a tag a file binds itself is not somebody else's component.
+     *
+     * The reachability reader already answers exactly this question, so it answers it
+     * here rather than being approximated a second time.
+     */
+    const own = localOnlyNames(source);
+    const fromPackage = new Map();
+    THIRD_PARTY_IMPORT.lastIndex = 0;
+    for (const m of source.matchAll(THIRD_PARTY_IMPORT)) {
+        const spec = m[2];
+        if (internal.some((pre) => spec === pre || spec.startsWith(`${pre}/`))) {
+            continue;
+        }
+        for (const raw of m[1].replace(/[{}]/g, ",").split(",")) {
+            const local = (raw
+                .trim()
+                .split(/\s+as\s+/)
+                .pop() ?? "").trim();
+            if (/^[A-Z]/.test(local))
+                fromPackage.set(local, spec);
+        }
+    }
+    if (fromPackage.size === 0)
+        return null;
+    RENDERED_TAG.lastIndex = 0;
+    let theirs = null;
+    let seen = 0;
+    for (const m of source.matchAll(RENDERED_TAG)) {
+        const root = m[1].split(".")[0];
+        if (own.has(root))
+            return null;
+        const spec = fromPackage.get(root);
+        // A tag from neither - their own component, imported relatively - means this file
+        // composes the system rather than adapting a library.
+        if (!spec)
+            return null;
+        theirs ??= spec;
+        seen += 1;
+    }
+    return seen > 0 ? theirs : null;
+}
+export function gateComponent(input) {
+    const { name, file, source } = input;
+    if (RESERVED_FILE.test(file) || RESERVED_FILE_OTHER.test(file)) {
+        return {
+            ok: false,
+            why: "route",
+            because: `\`${file}\` is a file name the framework reserves - it is a route, not a component somebody can import`,
+        };
+    }
+    if (SCREEN_SUFFIX.test(name)) {
+        return {
+            ok: false,
+            why: "screen",
+            because: `\`${name}\` names a whole screen or the frame around one. A design system is made of the pieces a screen is built FROM`,
+        };
+    }
+    if (PROVIDER_SUFFIX.test(name) || IS_CONTEXT.test(source)) {
+        return {
+            ok: false,
+            why: "provider",
+            because: `\`${name}\` carries context or wraps a tree rather than drawing anything of its own`,
+        };
+    }
+    const adapter = adapterFor(source, input.internal ?? []);
+    if (adapter) {
+        return {
+            ok: false,
+            why: "adapter",
+            because: `\`${name}\` renders \`${adapter}\`'s components and no element of its own - its markup and every pixel are that library's, so there is nothing here for this system to re-theme`,
+        };
+    }
+    if (!HAS_JSX.test(source)) {
+        return {
+            ok: false,
+            why: "config",
+            because: `\`${name}\` is a capitalised export in a file with no markup - a constant, a config object or a helper`,
+        };
+    }
+    if (!HAS_STYLING.test(source)) {
+        return {
+            ok: false,
+            why: "no-styling",
+            because: `\`${name}\` renders but decides nothing about how anything looks - every pixel it produces was decided somewhere else`,
+        };
+    }
+    return { ok: true };
+}
+/**
+ * The rejections, grouped and counted, in the order that reads best out loud.
+ *
+ * NO SILENT CAPS. A run that quietly imports 40 of 704 reads as "your project has 40
+ * components", which is the one thing a census must never imply. Every name is
+ * carried; the printer shows the first few per group and says how many more.
+ */
+export const SKIP_LABEL = {
+    route: "routes and framework files",
+    screen: "whole screens, and the frames around them",
+    provider: "providers, contexts and wrappers",
+    adapter: "adapters for another library's components",
+    config: "constants, config and helpers",
+    "no-jsx": "capitalised exports with no markup",
+    "no-styling": "components that decide nothing about how anything looks",
+};
+export function groupSkips(skips) {
+    const order = [
+        "screen",
+        "route",
+        "provider",
+        "adapter",
+        "no-styling",
+        "config",
+        "no-jsx",
+    ];
+    const by = new Map();
+    for (const s of skips) {
+        by.set(s.why, [...(by.get(s.why) ?? []), s.name]);
+    }
+    return order
+        .filter((why) => (by.get(why) ?? []).length > 0)
+        .map((why) => ({
+        why,
+        label: SKIP_LABEL[why],
+        names: (by.get(why) ?? []).sort(),
+    }));
+}
+/**
+ * One line saying what the gate did, in the terms the decision was actually made on.
+ *
+ * The sentence a person needs in order to trust a number that just dropped by an
+ * order of magnitude - and to notice if it dropped too far.
+ */
+export function describeGate(kept, skipped) {
+    if (skipped === 0) {
+        return `${kept} component${kept === 1 ? "" : "s"} - every capitalised export here is one.`;
+    }
+    return `${kept} component${kept === 1 ? "" : "s"}, and ${skipped} export${skipped === 1 ? "" : "s"} left out. A page is not a component of a design system: it has no visual identity to draw, and importing one puts a name in your vitrine that nobody can compose with. Everything left out is listed below with the reason, so you can disagree with any of it.`;
+}

package/dist/doctor/transcribe.js

@@ -91,6 +91,20 @@ const SPACING_PROPERTY = {
     mx: "marginInline",
     my: "marginBlock",
     gap: "gap",
+    /**
+     * SIZE, which the first version had no entry for at all.
+     *
+     * A real `cva` puts the whole size axis in `h-8 px-3`, `h-12 px-6`, `h-16 px-10` -
+     * six options, and only the padding came through, so every size read as the same
+     * height (probe, 01/08). A control's height IS its size.
+     */
+    h: "height",
+    w: "width",
+    size: "size",
+    "min-h": "minHeight",
+    "min-w": "minWidth",
+    "max-h": "maxHeight",
+    "max-w": "maxWidth",
 };
 /** Tailwind's radius scale. */
 const RADIUS = {
@@ -221,6 +235,35 @@ export function readUtility(utility, declared) {
     const keyword = TYPE_KEYWORD[core];
     if (keyword)
         return keyword;
+    /**
+     * AN ARBITRARY VALUE POINTING AT ONE OF THEIR OWN TOKENS.
+     *
+     * `rounded-[var(--radius-md)]`, `gap-[var(--spacing-sm)]`,
+     * `[font-size:var(--text-body-s)]`. This library writes half its scale that way, and
+     * none of it was read - the base of a real Button came back with two declarations out
+     * of fifteen (probe, 01/08).
+     *
+     * It is the STRONGEST kind of value in the file, not the weakest: an arbitrary value
+     * naming a custom property is somebody pointing at their own declared token by hand.
+     * The bracket is a Tailwind escape hatch; the `var()` inside it is a token ref.
+     */
+    const arbitraryProp = /^\[([a-z-]+):(.+)\]$/.exec(core);
+    if (arbitraryProp) {
+        const property = arbitraryProp[1].replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+        const value = resolveArbitrary(arbitraryProp[2], declared);
+        if (value)
+            return { property, value: value.value, token: value.token };
+    }
+    const bracket = core.indexOf("-[");
+    if (bracket !== -1 && core.endsWith("]")) {
+        const head = core.slice(0, bracket);
+        const inner = core.slice(bracket + 2, -1);
+        const property = COLOR_PROPERTY[head] ?? SPACING_PROPERTY[head] ?? BRACKET_PROPERTY[head];
+        const value = resolveArbitrary(inner, declared);
+        if (property && value) {
+            return { property, value: value.value, token: value.token };
+        }
+    }
     const dash = core.indexOf("-");
     if (dash === -1)
         return null;
@@ -299,6 +342,14 @@ export function readUtility(utility, declared) {
         }
         return null;
     }
+    /**
+     * `opacity-50`, which a real `cva` uses for its whole disabled look:
+     * `disabled:opacity-50 disabled:grayscale-[0.5]`. Tailwind's own scale is the
+     * percentage, so the value is the number over one hundred.
+     */
+    if (prefix === "opacity" && /^\d{1,3}$/.test(rest)) {
+        return { property: "opacity", value: String(Number(rest) / 100) };
+    }
     const spaceProp = SPACING_PROPERTY[prefix];
     if (spaceProp && SPACING[rest]) {
         return { property: spaceProp, value: SPACING[rest] };
@@ -324,6 +375,71 @@ export function readUtility(utility, declared) {
  * before it is the family, hyphens intact, because `royal-blue-500` is one
  * family called `royal-blue`.
  */
+/**
+ * Utility heads whose arbitrary value is not a colour or a length in the tables above.
+ * `rounded-[…]` is a radius, `shadow-[…]` an elevation, `text-[…]` ambiguous by design
+ * (a colour or a size) and resolved by what the value looks like.
+ */
+const BRACKET_PROPERTY = {
+    rounded: "borderRadius",
+    shadow: "boxShadow",
+    border: "borderWidth",
+    leading: "lineHeight",
+    tracking: "letterSpacing",
+    font: "fontFamily",
+    opacity: "opacity",
+    z: "zIndex",
+    grid: "gridTemplateColumns",
+    aspect: "aspectRatio",
+};
+/**
+ * What is inside the brackets, resolved.
+ *
+ * `var(--radius-md)` where they declared `--radius-md` is a REF - the value travels as
+ * the token they named it. A `var()` they never declared, or a plain literal, travels
+ * as the literal they typed, which keeps v1 a mirror and leaves normalising to a v2
+ * they approve.
+ */
+function resolveArbitrary(inner, declared) {
+    const raw = inner.replace(/_/g, " ").trim();
+    if (!raw)
+        return null;
+    const v = /^var\(\s*(--[a-zA-Z0-9_-]+)\s*(?:,[^)]*)?\)$/.exec(raw);
+    if (!v) {
+        // A literal in brackets is still a real value somebody typed.
+        return /[<>{}@;]/.test(raw) ? null : { value: raw };
+    }
+    const name = v[1];
+    if (!declared.has(name))
+        return { value: raw };
+    return { value: tokenRefFor(name), token: name };
+}
+/**
+ * A declared custom property, as a token ref in the document's own namespace.
+ *
+ * `--color-ocean-500` → `{color.ocean.500}`, `--radius-md` → `{radius.md}`,
+ * `--text-body-s` → `{typography.scale.body-s.fontSize}`. Their name is the path,
+ * which is the whole "your names travel unchanged" promise applied one level deeper.
+ */
+function tokenRefFor(name) {
+    const bare = name.replace(/^--/, "");
+    if (bare.startsWith("color-"))
+        return refFor(bare.slice("color-".length));
+    if (bare.startsWith("radius-"))
+        return `{radius.${bare.slice(7)}}`;
+    if (bare.startsWith("spacing-"))
+        return `{spacing.${bare.slice(8)}}`;
+    if (bare.startsWith("shadow-"))
+        return `{shadow.${bare.slice(7)}}`;
+    if (bare.startsWith("text-")) {
+        return `{typography.scale.${bare.slice(5)}.fontSize}`;
+    }
+    if (bare.startsWith("font-"))
+        return `{typography.families.${bare.slice(5)}}`;
+    // A namespace we do not model. The literal `var()` is still correct CSS against
+    // their own stylesheet, and inventing a ref would point at nothing.
+    return `var(${name})`;
+}
 function refFor(name) {
     const m = /^(.*)-(\d{2,4})$/.exec(name);
     if (!m)