npm - synthesisui - Versions diffs - 0.16.6 → 0.16.7 - Mend

synthesisui 0.16.6 → 0.16.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (5) hide show

package/dist/claude-md.js CHANGED Viewed

@@ -106,6 +106,51 @@ component found in a repo-wide audit next week is an archaeology exercise.
 If it reports a value with no token, do NOT invent one. Say which value and what
 you would call it, and let a person decide.`;
+/**
+ * THE INTERFACE LANGUAGE, READ FROM THE PROJECT RATHER THAN ASKED FOR.
+ *
+ * Prompted in Portuguese, an agent wrote a dashboard whose menu was English
+ * (the labels the person dictated), whose content was Portuguese, and whose
+ * root element still said `lang="en"` inherited from the landing page
+ * (my-test4, 27/07). Nothing in the contract had ever mentioned language, so
+ * it was not disobedience - nobody had read that attribute out loud to it.
+ *
+ * The cruelty is that careful accessibility makes it worse: a screen reader
+ * pronounces `aria-label="Sessões por canal"` with English phonemes. The most
+ * conscientious lines in the file are the ones that break hardest.
+ *
+ * This does NOT belong to the design system. One system serves many apps, and
+ * one of them will be Spanish - a locale baked into the tokens would break the
+ * first customer with two markets. The PROJECT owns its language, it already
+ * declares it in the layout, and this only reads it back.
+ */
+const HTML_LANG = /<html[^>]*\slang=(?:"([a-z-]+)"|'([a-z-]+)'|\{)/i;
+const LAYOUTS = [
+    "app/layout.tsx",
+    "app/layout.jsx",
+    "src/app/layout.tsx",
+    "src/app/layout.jsx",
+    "pages/_document.tsx",
+    "src/pages/_document.tsx",
+    "index.html",
+    "public/index.html",
+];
+async function readInterfaceLanguage(projectRoot) {
+    for (const rel of LAYOUTS) {
+        const src = await readFile(join(projectRoot, rel), "utf8").catch(() => "");
+        if (!src)
+            continue;
+        const m = HTML_LANG.exec(src);
+        if (!m)
+            continue;
+        const lang = m[1] ?? m[2];
+        // `lang={locale}` - the project is internationalised, and the useful
+        // instruction is the opposite one: literal copy in JSX is the mistake,
+        // whatever language it is in.
+        return lang ? { lang } : { i18n: true };
+    }
+    return null;
+}
 async function renderRegion(projectRoot, installed) {
     if (installed.length === 0) {
         return `${START}\n${END}`;
@@ -149,9 +194,24 @@ Only write something new when nothing in the manifest covers the purpose - and w
 say which entry you considered and why it did not fit. To review a
 component, create an isolated sample page (e.g. \`app/synthesisui-samples/<component>/\`) - do not
 apply it to real production pages unless asked.${SELF_CHECK}`;
+    const locale = await readInterfaceLanguage(projectRoot);
+    const language = locale === null
+        ? ""
+        : "i18n" in locale
+            ? `
+**This project is internationalised** - its \`<html lang>\` is set from a variable. User-facing
+copy belongs in the message catalogue, never written literally into JSX.`
+            : `
+**This project's interface language is \`${locale.lang}\`**, from the \`lang\` attribute on its root
+element. Write every user-facing string in that language - labels, empty states, \`aria-label\`,
+\`alt\`. A screen reader pronounces \`aria-label\` using \`lang\`, so a mixed-language interface is
+worse than an untranslated one. If the attribute is wrong, change it rather than writing against
+it.`;
     const body = `## Design Systems (via SynthesisUI)
-This project uses design system(s) tracked by the \`synthesisui\` CLI. ${rule}
+This project uses design system(s) tracked by the \`synthesisui\` CLI. ${rule}${language}
 ${sections.join("\n")}

package/dist/commands/doctor.js CHANGED Viewed

@@ -2,7 +2,7 @@ import { readdir, readFile } from "node:fs/promises";
 import { join, relative, resolve } from "node:path";
 import { findFrozenBindings } from "../doctor/frozen.js";
 import { bindingsFromDocument, countComponents, findOverrides, } from "../doctor/overrides.js";
-import { diagnose, scanSource, } from "../doctor/scan.js";
+import { diagnose, scanSource, siblingTokens, } from "../doctor/scan.js";
 import { findSelfConflicts, forbiddenProps, isReset, propMatchesLabel, } from "../doctor/self-conflict.js";
 import { buildTable, EMPTY_TABLE, nearestToken, } from "../doctor/tokens.js";
 import { body, section, snippet } from "../output.js";
@@ -459,7 +459,45 @@ export async function doctor(opts) {
     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`));
+        console.log(body(`                ${d.tokenUses} from the system, ${d.findings.length} by hand${d.phantomUses > 0 ? `, ${d.phantomUses} naming nothing` : ""}`));
+    }
+    /**
+     * Its own section, above drift, because it is a worse problem wearing a
+     * better disguise.
+     *
+     * Drift is a literal where a token belongs: the screen looks right and the
+     * system lost. A name the system does not declare resolves to NOTHING - no
+     * error, no console warning, the property simply does not apply - and it
+     * reads in review as the most obedient line in the file.
+     */
+    const phantoms = new Map();
+    for (const f of d.files) {
+        for (const p of f.phantoms ?? []) {
+            const at = phantoms.get(p.name) ?? { files: new Set(), line: p.line };
+            at.files.add(f.file);
+            phantoms.set(p.name, at);
+        }
+    }
+    /**
+     * `console.log`, not `say`. Everything else earns its place behind
+     * `--verbose` because the reader can already see it on screen; this is the
+     * one finding whose entire nature is that NOTHING is on screen. Hiding the
+     * invisible failure behind a flag is the same bug as not reporting it.
+     */
+    if (phantoms.size > 0) {
+        console.log(section("Names your system does not have"));
+        console.log(body(`${plural(phantoms.size, "name")} written as tokens that your system never declares.`));
+        console.log(body("An undeclared custom property applies nothing at all."));
+        console.log("");
+        for (const [name, at] of [...phantoms].sort()) {
+            const where = [...at.files][0];
+            console.log(body(`${name}   ${where}:${at.line}${at.files.size > 1 ? ` +${at.files.size - 1} more` : ""}`));
+            const kin = siblingTokens(name, table);
+            if (kin.length > 0)
+                console.log(snippet([`your system has ${kin.join(", ")}`]));
+        }
+        console.log("");
+        console.log(body("Add the name to the system, or use one it has. Do not leave it."));
     }
     if (d.findings.length > 0) {
         say(section("Drift"));

package/dist/doctor/scan.js CHANGED Viewed

@@ -49,16 +49,111 @@ const FONT = /font-family\s*:\s*([^;}\n]+)/g;
  * seen it declared - which is exactly what the token table knows.
  */
 const ANY_VAR_USE = /var\(\s*(--[a-z0-9_-]+)/gi;
+/**
+ * `var(--ds-xp, 60%)` - a name with a fallback ALWAYS renders, so it is never
+ * a phantom. This is not a mistake pattern either: it is how a runtime knob is
+ * written, and our own generated components ship two of them, set inline by
+ * whoever uses the component. Flagging those would have accused the platform's
+ * own output on the first real run.
+ */
+const VAR_WITH_FALLBACK = /var\(\s*(--[a-z0-9_-]+)\s*,/gi;
 const ANY_VAR_FALLBACK = /var\(\s*(--[a-z0-9_-]+)\s*,([^()]*)\)/gi;
 const isKnownToken = (name, table) => name.startsWith("--ds-") || table.byName.has(name);
+/**
+ * A NAME THAT RESOLVES TO NOTHING IS NOT COVERAGE.
+ *
+ * The prefix rule above is generous on purpose, and it had a hole underneath
+ * it: `var(--ds-color-series-99)` counted as a token use because it started
+ * with `--ds-`, whether or not the system declares it. Injected two invented
+ * names into a real project and the report said 100%, 20 from the system
+ * (my-test4, 27/07).
+ *
+ * That is the exact failure the whole product exists to prevent. An undeclared
+ * custom property is not a fallback to some default - it renders as NOTHING,
+ * with no error and no console warning. The managed block tells the agent not
+ * to invent tokens; until now the measurement could not tell whether it had
+ * obeyed.
+ *
+ * Only OUR prefix can be judged this way. `--acme-*` belongs to the project and
+ * we never see its full vocabulary, so an unknown one there means we did not
+ * read the file that declares it, not that it does not exist.
+ */
+const canJudgeDsNames = (table) => {
+    for (const name of table.declared)
+        if (name.startsWith("--ds-"))
+            return true;
+    // No `--ds-` in the table at all: an adopted system, a project with none, or
+    // a lock we failed to parse. Calling every reference a phantom there would
+    // turn one unreadable file into a report that condemns the whole repo.
+    return false;
+};
+/**
+ * Names we decline to judge, because being wrong here is worse than being
+ * quiet. Each of these was a real line in a real project, not a hypothetical.
+ */
+const unjudgeable = (name, line) => {
+    // Cheap and exact: the same line, re-read for `var(<name>,`.
+    for (const m of line.matchAll(VAR_WITH_FALLBACK))
+        if (m[1].toLowerCase() === name)
+            return true;
+    return (
+    // `var(--ds-color-series-${i})` and `var(--ds-${kind}-500)` both capture
+    // up to the interpolation and stop. The name is assembled at runtime; the
+    // static text is not a claim about any one token.
+    name.endsWith("-") ||
+        // A comment that documents the pattern - `var(--ds-color-series-*)` - is
+        // prose, and accusing a comment of drift is the tool losing the reader.
+        line.startsWith("//") ||
+        line.startsWith("*") ||
+        line.startsWith("/*"));
+};
 function countTokenUses(line, table) {
     let n = 0;
+    const judge = canJudgeDsNames(table);
     for (const m of line.matchAll(ANY_VAR_USE)) {
-        if (isKnownToken(m[1].toLowerCase(), table))
+        const name = m[1].toLowerCase();
+        if (judge && name.startsWith("--ds-") && !table.declared.has(name)) {
+            if (!unjudgeable(name, line))
+                continue;
+        }
+        if (isKnownToken(name, table))
             n++;
     }
     return n;
 }
+/** The undeclared `--ds-` names on a line, for the report. Same rules as the
+ *  counter above, so a name is never both uncounted and unmentioned. */
+function findPhantoms(line, table) {
+    if (!canJudgeDsNames(table))
+        return [];
+    const out = [];
+    for (const m of line.matchAll(ANY_VAR_USE)) {
+        const name = m[1].toLowerCase();
+        if (!name.startsWith("--ds-"))
+            continue;
+        if (table.declared.has(name) || unjudgeable(name, line))
+            continue;
+        out.push(name);
+    }
+    return out;
+}
+/**
+ * What the author probably meant, by the longest prefix the system does hold.
+ *
+ * `--ds-color-series-99` against a system with series 1 to 5 should not answer
+ * "no idea" - the family is right there, and naming its members is the same
+ * move the drift report already makes for values.
+ */
+export function siblingTokens(name, table) {
+    const parts = name.split("-").filter(Boolean);
+    for (let take = parts.length - 1; take >= 3; take--) {
+        const prefix = `--${parts.slice(0, take).join("-")}-`;
+        const kin = [...table.declared].filter((k) => k.startsWith(prefix) && k !== name);
+        if (kin.length > 0)
+            return kin.sort().slice(0, 5);
+    }
+    return [];
+}
 /**
  * `var(--ds-color-semantic-primary, #5266eb)` - the literal is the TOKEN'S OWN
  * fallback, written for safety, and reporting it as drift told an author to
@@ -89,6 +184,7 @@ const DECLARES_TOKEN = /^\s*(--[a-z0-9_-]+)\s*:/i;
 const IDIOM = new Set(["0", "0px", "1px", "9999px", "100%", "50%"]);
 export function scanSource(file, source, table) {
     const findings = [];
+    const phantoms = [];
     let tokenUses = 0;
     // Reason by reason. Rolling two into "A or B" was the one place the report
     // still lumped things it had told apart everywhere else.
@@ -112,6 +208,8 @@ export function scanSource(file, source, table) {
         const line = raw.trim();
         const at = i + 1;
         tokenUses += countTokenUses(line, table);
+        for (const name of findPhantoms(line, table))
+            phantoms.push({ name, line: at });
         // Depth at the START of this line, carried before the early return so a
         // blank line inside an <svg> cannot close the region by accident. The
         // per-match depth is recomputed below, because an icon is often written on
@@ -192,6 +290,7 @@ export function scanSource(file, source, table) {
         file,
         findings,
         tokenUses,
+        ...(phantoms.length > 0 ? { phantoms } : null),
         ...(aside.size > 0
             ? {
                 setAside: [...aside].map(([reason, count]) => ({ reason, count })),
@@ -210,7 +309,11 @@ export function diagnose(files) {
     for (const f of flat)
         counts[f.kind] += 1;
     const tokenUses = files.reduce((n, f) => n + f.tokenUses, 0);
-    const total = tokenUses + flat.length;
+    // A name that resolves to nothing did not come from the system, so it cannot
+    // sit outside the fraction. Reporting 100% directly above "2 names your
+    // system never declares" is the report contradicting itself in six lines.
+    const phantomUses = files.reduce((n, f) => n + (f.phantoms?.length ?? 0), 0);
+    const total = tokenUses + flat.length + phantomUses;
     const byLiteral = new Map();
     for (const f of flat) {
         const key = `${f.kind}:${f.literal.toLowerCase()}`;
@@ -239,11 +342,14 @@ export function diagnose(files) {
         .filter((r) => r.count > 1)
         .sort((a, b) => b.count - a.count);
     return {
-        files: files.filter((f) => f.findings.length > 0),
+        // A file with a phantom name and no drift has nothing to say by the old
+        // measure and the worst thing to say by the new one. Both keep it.
+        files: files.filter((f) => f.findings.length > 0 || (f.phantoms?.length ?? 0) > 0),
         findings: flat,
         counts,
         named: flat.filter((f) => f.token).length,
         tokenUses,
+        phantomUses,
         coverage: total === 0 ? 100 : Math.round((tokenUses / total) * 100),
         scanned: files.length,
         repeats,

package/dist/doctor/tokens.js CHANGED Viewed

@@ -18,6 +18,7 @@ export const EMPTY_TABLE = {
     version: null,
     byName: new Map(),
     byValue: new Map(),
+    declared: new Set(),
 };
 const hex2 = (n) => Math.max(0, Math.min(255, Math.round(n)))
     .toString(16)
@@ -166,6 +167,25 @@ export function parseTokens(css) {
     }
     return out;
 }
+/**
+ * EVERY name the stylesheet declares, aliases included.
+ *
+ * "What value does this hold" and "does this name exist" are different
+ * questions, and the table only answered the first. `parseTokens` drops
+ * aliases on purpose - you cannot match a hardcoded colour against
+ * `var(--ds-color-blue-500)` - so fifteen perfectly real tokens, the whole
+ * `--ds-color-series-*` family among them, were absent from `byName` while
+ * being declared two lines apart in the same file.
+ *
+ * Harmless while nothing asked about existence. The moment the phantom check
+ * did, it called them invented (caught before shipping, 27/07).
+ */
+export function parseDeclaredNames(css) {
+    const out = new Set();
+    for (const m of css.matchAll(/(--[a-z0-9_-]+)\s*:\s*[^;}]+[;}]/gi))
+        out.add(m[1].toLowerCase());
+    return out;
+}
 /**
  * Custom properties the project declares AT THE ROOT, whatever it calls them.
  *
@@ -276,6 +296,7 @@ export function buildTable(input) {
         version: input.lock?.version ?? null,
         byName,
         byValue,
+        declared: parseDeclaredNames(input.css),
     };
 }
 /**

package/package.json CHANGED Viewed

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