@homebound/truss 2.29.9 → 2.29.11

package/build/plugin/index.d.ts

@@ -1,3 +1,5 @@
+import { PluginContext } from 'rollup';
+
 /** The shape of the Css.json mapping file consumed by the Vite plugin. */
 interface TrussMapping {
     increment: number;
@@ -91,15 +93,18 @@ interface TrussPluginOptions {
     mapping: string;
     /** Paths to pre-compiled truss.css files from libraries to merge into the app's CSS. */
     libraries?: string[];
+    /** Unsupported patterns fail builds by default; dev transforms warn and keep serving the page. */
+    unsupportedPattern?: "error" | "warn";
 }
+type DiagnosticContext = Pick<PluginContext, "warn">;
 interface TrussVitePlugin {
     name: string;
     enforce?: "pre" | "post";
     configResolved?: (config: any) => void;
     buildStart?: () => void;
     resolveId?: (source: string, importer: string | undefined) => string | null;
-    load?: (id: string) => string | null;
-    transform?: (code: string, id: string) => {
+    load?: (this: DiagnosticContext, id: string) => string | null;
+    transform?: (this: DiagnosticContext, code: string, id: string) => {
         code: string;
         map: any;
     } | null;

package/build/plugin/index.js

@@ -330,11 +330,44 @@ function resetConditionContext(context) {
   Object.assign(context, emptyConditionContext());
 }
 
+// src/plugin/unknown-abbreviation.ts
+var UnknownAbbreviationError = class extends UnsupportedPatternError {
+  constructor(abbreviation, candidates) {
+    const suggestion = closestAbbreviation(abbreviation, candidates);
+    super(`Unknown abbreviation "${abbreviation}"${suggestion ? `. Did you mean "${suggestion}"?` : ""}`);
+  }
+};
+function closestAbbreviation(abbreviation, candidates) {
+  let closest;
+  let bestDistance = 3;
+  for (const candidate of candidates) {
+    if (Math.abs(candidate.length - abbreviation.length) >= bestDistance) continue;
+    let previous = Array.from({ length: candidate.length + 1 }, (_, index) => index);
+    for (let i = 1; i <= abbreviation.length; i++) {
+      const current = [i];
+      for (let j = 1; j <= candidate.length; j++) {
+        current[j] = Math.min(
+          current[j - 1] + 1,
+          previous[j] + 1,
+          previous[j - 1] + (abbreviation[i - 1] === candidate[j - 1] ? 0 : 1)
+        );
+      }
+      previous = current;
+    }
+    const distance = previous[candidate.length];
+    if (distance < bestDistance) {
+      closest = candidate;
+      bestDistance = distance;
+    }
+  }
+  return closest;
+}
+
 // src/plugin/resolve-entry.ts
 function requireEntry(mapping, abbr) {
   const entry = mapping.abbreviations[abbr];
   if (!entry) {
-    throw new UnsupportedPatternError(`Unknown abbreviation "${abbr}"`);
+    throw new UnknownAbbreviationError(abbr, Object.keys(mapping.abbreviations));
   }
   return entry;
 }
@@ -2553,16 +2586,18 @@ function parseTrussCss(cssText) {
   }
   return { rules, properties, arbitraryCssBlocks };
 }
-function serializeTrussCss(css) {
+function serializeTrussCss(css, annotate = true) {
   const lines = [];
   for (const rule of css.rules) {
-    lines.push(`/* @truss p:${rule.priority} c:${rule.className} */`, rule.cssText);
+    if (annotate) lines.push(`/* @truss p:${rule.priority} c:${rule.className} */`);
+    lines.push(rule.cssText);
   }
   for (const prop of css.properties) {
-    lines.push(`/* @truss @property */`, prop.cssText);
+    if (annotate) lines.push(`/* @truss @property */`);
+    lines.push(prop.cssText);
   }
   for (const block of css.arbitraryCssBlocks) {
-    lines.push(annotateArbitraryCssBlock(block.cssText));
+    lines.push(annotate ? annotateArbitraryCssBlock(block.cssText) : block.cssText.trim());
   }
   return lines.join("\n");
 }
@@ -2733,12 +2768,28 @@ function getTopLevelVariableDeclaration(node) {
   return null;
 }
 
+// src/plugin/diagnostic.ts
+var Diagnostic = class extends Error {
+  id;
+  loc;
+  constructor(message, filename, node) {
+    const start = node.loc?.start;
+    const location = start ? `${filename}:${start.line}:${start.column + 1}` : filename;
+    super(`${location}: ${message}`);
+    this.id = filename;
+    this.loc = start ? { file: filename, line: start.line, column: start.column } : void 0;
+  }
+};
+
 // src/plugin/transform-css.ts
-function transformCssTs(code, filename, mapping) {
+function transformCssTs(code, filename, mapping, options = {}) {
   const ast = parseModule(code, filename);
   const cssBindingName = findCssImportBinding(ast);
   const cssExport = findNamedCssExportObject(ast);
   if (!cssExport) {
+    options.onDiagnostic?.(
+      new Diagnostic("expected `export const css = { ... }` with an object literal", filename, ast.program)
+    );
     return `/* [truss] ${filename}: expected \`export const css = { ... }\` with an object literal */
 `;
   }
@@ -2746,16 +2797,16 @@ function transformCssTs(code, filename, mapping) {
   const stringBindings = collectStaticStringBindings(ast);
   for (const prop of cssExport.properties) {
     if (t12.isSpreadElement(prop)) {
-      rules.push(`/* [truss] unsupported: spread elements in css.ts export */`);
+      rules.push(unsupported("spread elements in css.ts export", prop));
       continue;
     }
     if (!t12.isObjectProperty(prop)) {
-      rules.push(`/* [truss] unsupported: non-property in css.ts export */`);
+      rules.push(unsupported("non-property in css.ts export", prop));
       continue;
     }
     const selector = objectPropertyStringKey(prop, stringBindings);
     if (selector === null) {
-      rules.push(`/* [truss] unsupported: non-string-literal key in css.ts export */`);
+      rules.push(unsupported("non-string-literal key in css.ts export", prop));
       continue;
     }
     const valueNode = prop.value;
@@ -2765,21 +2816,25 @@ function transformCssTs(code, filename, mapping) {
       continue;
     }
     if (!t12.isExpression(valueNode)) {
-      rules.push(`/* [truss] unsupported: "${selector}" value is not an expression */`);
+      rules.push(unsupported(`"${selector}" value is not an expression`, valueNode));
       continue;
     }
     if (!cssBindingName) {
-      rules.push(`/* [truss] unsupported: "${selector}" \u2014 Css.*.$  chain requires a Css import */`);
+      rules.push(unsupported(`"${selector}" \u2014 Css.*.$  chain requires a Css import`, valueNode));
       continue;
     }
-    const cssResult = resolveCssExpression(valueNode, cssBindingName, mapping, filename);
+    const cssResult = resolveCssExpression(valueNode, cssBindingName, mapping);
     if ("error" in cssResult) {
-      rules.push(`/* [truss] unsupported: "${selector}" \u2014 ${cssResult.error} */`);
+      rules.push(unsupported(`"${selector}" \u2014 ${cssResult.error}`, valueNode));
       continue;
     }
     rules.push(formatCssRule(selector, cssResult.declarations));
   }
   return rules.join("\n\n") + "\n";
+  function unsupported(message, node) {
+    options.onDiagnostic?.(new Diagnostic(message, filename, node));
+    return `/* [truss] unsupported: ${message} */`;
+  }
 }
 function findNamedCssExportObject(ast) {
   for (const node of ast.program.body) {
@@ -2809,7 +2864,7 @@ function extractStaticStringValue(node, cssBindingName) {
   }
   return null;
 }
-function resolveCssExpression(node, cssBindingName, mapping, filename) {
+function resolveCssExpression(node, cssBindingName, mapping) {
   const chain = extractDollarChain(node, cssBindingName);
   if (!chain) {
     return { error: "value must be a Css.*.$ expression" };
@@ -3375,10 +3430,18 @@ function transformTruss(code, filename, mapping, options = {}) {
         return;
       }
       const resolveCssChainReference2 = buildCssChainReferenceResolver(path, cssBindingName);
-      const resolvedChain = resolveFullChain({ mapping, cssBindingName, resolveCssChainReference: resolveCssChainReference2 }, chain);
+      const resolvedChain = resolveFullChain(
+        {
+          mapping,
+          cssBindingName,
+          resolveCssChainReference: resolveCssChainReference2
+        },
+        chain
+      );
       sites.push({ path, resolvedChain });
       const line = path.node.loc?.start.line ?? null;
       for (const err of resolvedChain.errors) {
+        options.onDiagnostic?.(new Diagnostic(err, filename, path.node));
         errorMessages.push({ message: err, line });
       }
     },
@@ -3628,9 +3691,9 @@ function createTrussTransformSession(options) {
     arbitraryCssRegistry.clear();
     libraryCache = null;
   }
-  function updateArbitraryCssRegistry(sourcePath, sourceCode) {
+  function updateArbitraryCssRegistry(sourcePath, sourceCode, diagnostics = {}) {
     sourcePath = resolve2(sourcePath).replace(/\\/g, "/");
-    const css = transformCssTs(sourceCode, sourcePath, ensureMapping()).trim();
+    const css = transformCssTs(sourceCode, sourcePath, ensureMapping(), diagnostics).trim();
     if (css.length > 0) {
       const prev = arbitraryCssRegistry.get(sourcePath);
       arbitraryCssRegistry.set(sourcePath, css);
@@ -3656,13 +3719,13 @@ function createTrussTransformSession(options) {
     }
     return result;
   }
-  function collectCss() {
+  function collectCss(annotate = true) {
     const mapping2 = ensureMapping();
     const appCss = generateCssData(cssRegistry);
     const allArbitrary = Array.from(arbitraryCssRegistry.entries()).sort((a, b) => compareClassNames(a[0], b[0])).map((entry) => entry[1]).join("\n\n");
     if (allArbitrary.length > 0) appCss.arbitraryCssBlocks.push({ cssText: allArbitrary });
     const libs = loadLibraries();
-    const body = serializeTrussCss(libs.length === 0 ? appCss : mergeTrussCssData([...libs, appCss]));
+    const body = serializeTrussCss(libs.length === 0 ? appCss : mergeTrussCssData([...libs, appCss]), annotate);
     if (body.length === 0) return "";
     return `${rootSpacingPreludeCss(mapping2.increment)}
 ${body}`;
@@ -3695,6 +3758,11 @@ import * as t16 from "@babel/types";
 import { readFileSync as readFileSync3, writeFileSync, mkdirSync } from "fs";
 import { resolve as resolve3, join } from "path";
 function trussEsbuildPlugin(opts) {
+  const diagnostics = {
+    onDiagnostic(error) {
+      throw error;
+    }
+  };
   const session = createTrussTransformSession({
     mappingPath() {
       return resolve3(process.cwd(), opts.mapping);
@@ -3710,11 +3778,11 @@ function trussEsbuildPlugin(opts) {
       build.onLoad({ filter: /\.[cm]?[jt]sx?$/ }, (args) => {
         const code = readFileSync3(args.path, "utf8");
         if (args.path.endsWith(".css.ts")) {
-          session.updateArbitraryCssRegistry(args.path, code);
+          session.updateArbitraryCssRegistry(args.path, code, diagnostics);
           return { contents: code, loader: loaderForPath(args.path) };
         }
         if (!code.includes("Css") && !code.includes("css=")) return void 0;
-        const result = session.transformCode(code, args.path);
+        const result = session.transformCode(code, args.path, diagnostics);
         if (!result) return void 0;
         return { contents: result.code, loader: loaderForPath(args.path) };
       });
@@ -3753,6 +3821,8 @@ function trussPlugin(opts) {
   let debug = false;
   let isTest = false;
   let isBuild = false;
+  let annotate = true;
+  let devSocket;
   const libraryPaths = opts.libraries ?? [];
   let emittedCssFileName = null;
   let cssVersion = 0;
@@ -3760,6 +3830,11 @@ function trussPlugin(opts) {
   function mappingPath() {
     return resolve4(projectRoot || process.cwd(), opts.mapping);
   }
+  function diagnostics(context) {
+    return {
+      onDiagnostic: (error) => reportDiagnostic(context, error)
+    };
+  }
   const session = createTrussTransformSession({
     mappingPath,
     projectRoot: () => projectRoot || process.cwd(),
@@ -3776,6 +3851,7 @@ function trussPlugin(opts) {
       debug = config.command === "serve" || config.mode === "development" || config.mode === "test";
       isTest = config.mode === "test";
       isBuild = config.command === "build";
+      annotate = !isBuild || Boolean(config.build?.lib);
     },
     buildStart() {
       session.ensureMapping();
@@ -3786,9 +3862,10 @@ function trussPlugin(opts) {
     // -- Dev mode HMR --
     configureServer(server) {
       if (isTest) return;
+      devSocket = server.ws;
       server.middlewares.use((req, res, next) => {
         if (req.url !== VIRTUAL_CSS_ENDPOINT) return next();
-        const css = session.collectCss();
+        const css = session.collectCss(annotate);
         res.setHeader("Content-Type", "text/css");
         res.setHeader("Cache-Control", "no-store");
         res.end(css);
@@ -3878,7 +3955,7 @@ __injectTrussCSS(${JSON.stringify(payload)});
       }
       if (id.startsWith(VIRTUAL_TEST_CSS_PREFIX)) {
         const sourcePath2 = canonicalSourcePath(id.slice(VIRTUAL_TEST_CSS_PREFIX.length));
-        session.updateArbitraryCssRegistry(sourcePath2, readFileSync4(sourcePath2, "utf8"));
+        session.updateArbitraryCssRegistry(sourcePath2, readFileSync4(sourcePath2, "utf8"), diagnostics(this));
         const payload = {
           arbitraryRules: splitArbitraryCss(session.getArbitraryCss(sourcePath2)),
           source: sourcePath2
@@ -3893,7 +3970,7 @@ __injectTrussCSS(${JSON.stringify(payload)});
       if (!id.startsWith(VIRTUAL_CSS_PREFIX)) return null;
       const sourcePath = id.slice(VIRTUAL_CSS_PREFIX.length) + ".ts";
       const sourceCode = readFileSync4(sourcePath, "utf8");
-      session.updateArbitraryCssRegistry(sourcePath, sourceCode);
+      session.updateArbitraryCssRegistry(sourcePath, sourceCode, diagnostics(this));
       return `/* [truss] ${sourcePath} \u2014 included via truss.css */`;
     },
     transform(code, id) {
@@ -3907,7 +3984,7 @@ __injectTrussCSS(${JSON.stringify(payload)});
 import "${VIRTUAL_TEST_CSS_ID}";` : rewrittenImports.code;
       const importsOnlyResult = rewrittenImports.changed || shouldBootstrapTestCss ? { code: transformedCode, map: null } : null;
       if (fileId.endsWith(".css.ts")) {
-        session.updateArbitraryCssRegistry(fileId, code);
+        session.updateArbitraryCssRegistry(fileId, code, diagnostics(this));
         if (isTest) {
           const css = session.getArbitraryCss(fileId);
           return { code: appendTestCssInjection(transformedCode, fileId, css), map: null };
@@ -3916,13 +3993,13 @@ import "${VIRTUAL_TEST_CSS_ID}";` : rewrittenImports.code;
       }
       const hasCssDsl = rewrittenImports.code.includes("Css") || rewrittenImports.code.includes("css=");
       if (!hasCssDsl) return importsOnlyResult;
-      const result = session.transformCode(transformedCode, fileId, { debug, injectCss: isTest });
+      const result = session.transformCode(transformedCode, fileId, { debug, injectCss: isTest, ...diagnostics(this) });
       return result ? { code: result.code, map: result.map } : importsOnlyResult;
     },
     // -- Production CSS emission --
     generateBundle(_options, _bundle) {
       if (!isBuild) return;
-      const css = session.collectCss();
+      const css = session.collectCss(annotate);
       if (!css) return;
       const hash = createHash("sha256").update(css).digest("hex").slice(0, 8);
       const fileName = `assets/truss-${hash}.css`;
@@ -3947,6 +4024,16 @@ import "${VIRTUAL_TEST_CSS_ID}";` : rewrittenImports.code;
       }
     }
   };
+  function reportDiagnostic(context, error) {
+    if ((opts.unsupportedPattern ?? (isBuild ? "error" : "warn")) === "error") {
+      throw error;
+    }
+    context.warn(error);
+    devSocket?.send({
+      type: "error",
+      err: { message: error.message, stack: "", id: error.id, loc: error.loc, plugin: "truss" }
+    });
+  }
 }
 function resolveImportPath(source, importer, projectRoot) {
   if (isAbsolute(source)) {