synthesisui 0.16.71 → 0.16.72

package/dist/commands/import.js

@@ -2,6 +2,7 @@ import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
 import { basename, dirname, join, relative } from "node:path";
 import { readCredentials, readToken, resolveRegistry, sameRegistry, } from "../config.js";
 import { findBrokenRefs } from "../doctor/broken-refs.js";
+import { describeClassStyle, detectClassStyle, } from "../doctor/class-style.js";
 import { isNearDuplicate, isNeutral, lightness, } from "../doctor/color-distance.js";
 import { emptyTally, internalSpecifiers, scanComponentsInto, tallyToInventory, } from "../doctor/components-scan.js";
 import { crosswalk, observedRules } from "../doctor/crosswalk.js";
@@ -407,12 +408,14 @@ export async function takeCensus(root) {
     }
     const brokenRefs = findBrokenRefs(sources, declaredNames);
     const conventions = detectConventions(sources);
+    const classStyle = detectClassStyle(sources);
     return {
         census: 1,
         project: { name, stack: await detectStack(root) },
         declared: Object.fromEntries(table.byName),
         ...(brokenRefs.length > 0 ? { brokenRefs } : {}),
         ...(conventions.length > 0 ? { conventions } : {}),
+        classStyle,
         ...(Object.keys(looks).length > 0 ? { looks } : {}),
         ...(schemes.alt.size > 0
             ? { declaredAlt: Object.fromEntries(schemes.alt) }
@@ -496,6 +499,10 @@ function sayConventions(c) {
         if (remainder)
             console.log(body(paint.faint(`  ${remainder}`)));
     }
+    if (c.classStyle) {
+        console.log("");
+        console.log(body(describeClassStyle(c.classStyle)));
+    }
     console.log("");
     console.log(body(paint.faint("Nothing here is a rule we brought - it is what your own files already do, and the system now knows it. None of the rest has to move today: this is a complement, not a correction.")));
 }

package/dist/doctor/class-style.js

@@ -0,0 +1,127 @@
+/**
+ * HOW THIS PROJECT NAMES A CLASS - and whether it names one at all.
+ *
+ * A compiled `.ds-metric-card` attaches to their markup, and a project whose own
+ * convention is `.metric-card__title` should not get a new name in its house for
+ * no reason it chose (dono, 01/08). So the convention has to be read, not
+ * assumed.
+ *
+ * Reading a real project first changed what this had to answer. Measured on a
+ * 670-stylesheet monorepo: 536 files are `*.module.scss` and 134 are not, and the
+ * class names inside them are `root`, `wrapper`, `editorText` - LOCAL names that
+ * a bundler hashes into `RootWrapper_root__x7f2a`.
+ *
+ * Which means there is no global convention there to follow, and our global
+ * class cannot collide with anything of theirs. The honest answer for that
+ * project is "nothing to change", and saying so is worth more than a concession
+ * nobody needed - inventing a problem is its own kind of dishonesty.
+ *
+ * Three worlds, and only the third asks anything of us:
+ *
+ *   modules   classes are local and hashed - ours are safe, and separate
+ *   utility   no component classes at all - ours are the only global ones
+ *   global    they DO name global classes, and we follow their shape
+ */
+const MODULE_FILE = /\.module\.(css|scss|sass|less)$/i;
+const STYLESHEET = /\.(css|scss|sass|less)$/i;
+/** A class selector at the start of a rule: `.metric-card__title {`. */
+const CLASS_DECL = /^\s*\.([a-zA-Z][a-zA-Z0-9_-]*)\s*[,{:]/gm;
+/** A Tailwind-shaped utility in markup - enough to know they exist. */
+const UTILITY = /\b(?:bg|text|border|p|px|py|m|mx|my|gap|flex|grid|rounded|shadow)-[a-z0-9[\]./-]+/g;
+/**
+ * Below this many global class declarations, a "convention" is a handful of
+ * one-off selectors rather than a house style - and adopting one from noise
+ * would rename everything we compile on the strength of three sightings.
+ */
+const MIN_GLOBAL_DECLS = 20;
+/**
+ * Prefixes worth honouring have to be shared by most of what they declare.
+ * A project with `app-header` and `admin-nav` has two words, not a prefix.
+ */
+const PREFIX_SHARE = 0.6;
+export function detectClassStyle(files) {
+    let moduleFiles = 0;
+    let globalFiles = 0;
+    let utilities = 0;
+    const globalDecls = [];
+    for (const { file, source } of files) {
+        if (MODULE_FILE.test(file)) {
+            moduleFiles += 1;
+            continue;
+        }
+        if (STYLESHEET.test(file)) {
+            globalFiles += 1;
+            // Only a non-module stylesheet can hold a class anybody else must match.
+            for (const m of source.matchAll(CLASS_DECL))
+                globalDecls.push(m[1]);
+            continue;
+        }
+        utilities += source.match(UTILITY)?.length ?? 0;
+    }
+    // Their own global classes come first - but only if they have a SHAPE.
+    //
+    // Counting them was not enough. A real repo returned `global` on the strength
+    // of a syntax-highlighting theme: `hll`, `field-name`, `document` cleared the
+    // threshold with no convention between them, and we would have renamed every
+    // class we compile to match vendor CSS (dono, 01/08). Many global classes with
+    // nothing in common is not a house style, it is a stylesheet.
+    if (globalDecls.length >= MIN_GLOBAL_DECLS) {
+        const shape = shapeOf(globalDecls);
+        if (shape) {
+            return {
+                kind: "global",
+                ...shape,
+                agreed: globalDecls.length,
+                samples: [...new Set(globalDecls)].slice(0, 3),
+            };
+        }
+    }
+    if (moduleFiles > globalFiles && moduleFiles > 0) {
+        return { kind: "modules", moduleFiles, globalFiles };
+    }
+    return { kind: "utility", utilities };
+}
+/**
+ * The shape their global classes share.
+ *
+ * BEM's `__` is unmistakable when present, so it is checked first and only
+ * accepted on a real share - two `__` selectors in a thousand is somebody's
+ * exception, not the house style.
+ */
+function shapeOf(decls) {
+    // BEM's `__` is unmistakable when it is the house style, and meaningless as
+    // somebody's two exceptions.
+    const bem = decls.filter((c) => c.includes("__")).length;
+    const isBem = bem / decls.length > 0.2;
+    // A prefix is the first delimited segment, when most of them share it. A
+    // project with `app-header` and `admin-nav` has two words, not a prefix.
+    const heads = new Map();
+    for (const c of decls) {
+        const head = c.split(/[-_]/)[0];
+        if (!head || head === c)
+            continue;
+        heads.set(head, (heads.get(head) ?? 0) + 1);
+    }
+    const top = [...heads.entries()].sort((a, b) => b[1] - a[1])[0];
+    const hasPrefix = top != null && top[1] / decls.length >= PREFIX_SHARE;
+    // Neither established: there is nothing here for us to follow, and adopting
+    // "unprefixed, hyphenated" from a grab-bag would rename everything we compile
+    // for no reason anybody chose.
+    if (!isBem && !hasPrefix)
+        return null;
+    return {
+        prefix: hasPrefix ? `${top[0]}-` : "",
+        partSeparator: isBem ? "__" : "-",
+    };
+}
+/** One line for the report, in their vocabulary and without asking for anything. */
+export function describeClassStyle(style) {
+    if (style.kind === "modules") {
+        return `your components style themselves through CSS Modules (${style.moduleFiles} module stylesheets) - those class names are local and hashed, so ours stay global and cannot collide with yours`;
+    }
+    if (style.kind === "utility") {
+        return "your components style themselves with utilities, so there are no component class names of yours for ours to match";
+    }
+    const named = style.prefix ? `prefixed \`${style.prefix}\`` : "unprefixed";
+    return `your global classes are ${named} and join parts with \`${style.partSeparator}\` (e.g. ${style.samples.join(", ")}) - what we compile will be spelled the same way`;
+}

package/package.json

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