@bamboocss/node 1.29.0 → 1.30.0

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 (3) hide show
  1. package/dist/index.cjs +129 -34
  2. package/dist/index.mjs +129 -34
  3. package/package.json +13 -13
package/dist/index.cjs CHANGED
@@ -1810,7 +1810,7 @@ var BambooContext = class extends _bamboocss_generator.Generator {
1810
1810
  poll
1811
1811
  }).on("change", (0, perfect_debounce.debounce)(async (file) => {
1812
1812
  _bamboocss_logger.logger.info("ctx:change", "config changed, rebuilding...");
1813
- await cb(file);
1813
+ await reportRebuildFailure(() => cb(file));
1814
1814
  }));
1815
1815
  };
1816
1816
  watchFiles = (cb, opts) => {
@@ -1824,10 +1824,30 @@ var BambooContext = class extends _bamboocss_generator.Generator {
1824
1824
  cwd
1825
1825
  }).on("all", (0, perfect_debounce.debounce)(async (event, file) => {
1826
1826
  _bamboocss_logger.logger.info(`file:${event}`, file);
1827
- await cb(event, file);
1827
+ await reportRebuildFailure(() => cb(event, file));
1828
1828
  }));
1829
1829
  };
1830
1830
  };
1831
+ /**
1832
+ * Report a failed rebuild as a failed rebuild.
1833
+ *
1834
+ * Chokidar is an `EventEmitter`, so it discards whatever a listener returns, and the debounce
1835
+ * wrapper attaches no rejection handler — a throw from inside a rebuild became a dangling
1836
+ * promise. `node-runtime.ts` then catches it as `Unhandled rejection`, which labels a config
1837
+ * error as an internal crash, leaves the exit code at 0, and is suppressed entirely at
1838
+ * `logLevel: 'silent'`. The initial build is caught by the CLI and prints properly; only
1839
+ * rebuilds of the identical source were silent, which is the worse half of the asymmetry.
1840
+ *
1841
+ * Caught rather than rethrown: a watcher's job is to survive a bad intermediate state and
1842
+ * rebuild when the next edit fixes it. What it must not do is claim success.
1843
+ */
1844
+ async function reportRebuildFailure(run) {
1845
+ try {
1846
+ await run();
1847
+ } catch (error) {
1848
+ _bamboocss_logger.logger.error("ctx:rebuild", error instanceof Error ? error.message : String(error));
1849
+ }
1850
+ }
1831
1851
  //#endregion
1832
1852
  //#region src/tsconfig-utils.ts
1833
1853
  /**
@@ -2186,6 +2206,24 @@ function* snapshotTexts(snapshot) {
2186
2206
  //#endregion
2187
2207
  //#region src/token-accounting.ts
2188
2208
  /**
2209
+ * The one decline `strict` fails the build on.
2210
+ *
2211
+ * `strict` asserts that every token path resolves, and this is the reason that says otherwise:
2212
+ * a token binding used in a way the build cannot follow — a path built at runtime, a binding
2213
+ * assigned away, a namespace enumerated. It is about the author's *token usage*, and it has a
2214
+ * fix at the call site.
2215
+ *
2216
+ * Nothing else may throw, because nothing else is necessarily about tokens at all. The other
2217
+ * reasons were written under a premise this would break: declining was free, so every branch
2218
+ * that could not prove a shape declined, and the accepted set was kept deliberately small.
2219
+ * `import(`./pages/${name}`)` declines as `dynamic-import` because the specifier is not a
2220
+ * literal and *could* be the artifact; `import lexer = require('./tokenizer')` declines because
2221
+ * the statement contains the substring `token`. Both are routine code with nothing to do with
2222
+ * design tokens, and failing a build over them would be indefensible. They keep every
2223
+ * declaration, which is what they always did, and say so.
2224
+ */
2225
+ const failsStrict = (entry) => entry.reason === "unresolved-reference";
2226
+ /**
2189
2227
  * One file's contribution, split out so the build can account and scan in a single walk.
2190
2228
  *
2191
2229
  * `pruneTokensForBuild` needs the keep set, the reachability answer and this accounting from
@@ -2193,7 +2231,7 @@ function* snapshotTexts(snapshot) {
2193
2231
  */
2194
2232
  function accountSnapshot(ctx, snapshot, accounting) {
2195
2233
  const { filePath, onDisk, parsed, sourceFile } = snapshot;
2196
- const { paths, declined } = accounting;
2234
+ const { paths, prefixes, declined } = accounting;
2197
2235
  if (onDisk == null || parsed == null || parsed !== onDisk) {
2198
2236
  if (!((onDisk?.includes("token") ?? false) || (parsed?.includes("token") ?? false))) return;
2199
2237
  declined.push({
@@ -2212,7 +2250,7 @@ function accountSnapshot(ctx, snapshot, accounting) {
2212
2250
  });
2213
2251
  return;
2214
2252
  }
2215
- accountFile(ctx, sourceFile, filePath, paths, declined);
2253
+ accountFile(ctx, sourceFile, filePath, paths, prefixes, declined);
2216
2254
  }
2217
2255
  /**
2218
2256
  * How many syntax errors the parse produced.
@@ -2234,7 +2272,7 @@ const isTokensEntrypoint = (ctx, specifier) => {
2234
2272
  return mods.some((mod) => resolved.includes(mod) || resolved === mod);
2235
2273
  };
2236
2274
  const lineOf = (node) => node.getSourceFile().getLineAndColumnAtPos(node.getStart()).line;
2237
- function accountFile(ctx, sourceFile, filePath, paths, declined) {
2275
+ function accountFile(ctx, sourceFile, filePath, paths, prefixes, declined) {
2238
2276
  const decline = (node, reason) => declined.push({
2239
2277
  filePath,
2240
2278
  line: lineOf(node),
@@ -2268,7 +2306,7 @@ function accountFile(ctx, sourceFile, filePath, paths, declined) {
2268
2306
  for (const named of clause.getNamedImports()) {
2269
2307
  if (named.isTypeOnly()) continue;
2270
2308
  if (nameOf(named.getNameNode()) !== "token") {
2271
- decline(named, "unsupported-import");
2309
+ if (usedAsValue(sourceFile, (named.getAliasNode() ?? named.getNameNode()).getText(), named)) decline(named, "unsupported-import");
2272
2310
  continue;
2273
2311
  }
2274
2312
  bindings.add((named.getAliasNode() ?? named.getNameNode()).getText());
@@ -2296,12 +2334,17 @@ function accountFile(ctx, sourceFile, filePath, paths, declined) {
2296
2334
  continue;
2297
2335
  }
2298
2336
  if (ts_morph.Node.isPropertyAssignment(parent) && parent.getNameNode() === identifier) continue;
2299
- const path = accountedPath(identifier);
2300
- if (path === void 0) {
2337
+ const resolved = accountedPath(identifier);
2338
+ if (resolved === void 0) {
2301
2339
  decline(identifier, "unresolved-reference");
2302
2340
  continue;
2303
2341
  }
2304
- paths.add(path);
2342
+ if (resolved.kind === "binding") continue;
2343
+ if (resolved.kind === "prefix") {
2344
+ prefixes.add(resolved.value);
2345
+ continue;
2346
+ }
2347
+ paths.add(resolved.value);
2305
2348
  }
2306
2349
  }
2307
2350
  /**
@@ -2326,57 +2369,106 @@ function usesTokenMember(sourceFile, namespace) {
2326
2369
  */
2327
2370
  const nameOf = (node) => ts_morph.Node.isIdentifier(node) ? String(node.compilerNode.escapedText) : node.getText();
2328
2371
  /**
2329
- * The token path one occurrence asks for, or `undefined` if it is not a call this can read.
2372
+ * What one occurrence asks for, or `undefined` if it is not a call this can read.
2330
2373
  *
2331
- * Accepts the callee position and nothing else — `token('x')`, `token.var('x')`,
2332
- * `token.value('x')`, and the namespaced spellings. An identifier anywhere else is a value
2374
+ * Accepts the callee position and nothing else — `token('x')`, `token.value('x')`, and the
2375
+ * namespaced spellings of each. An identifier anywhere else is a value
2333
2376
  * escaping somewhere this pass cannot follow: assigned (`const t = token`), passed
2334
2377
  * (`useMemo(() => token)`), spread, or enumerated.
2335
2378
  */
2336
2379
  function accountedPath(identifier) {
2337
2380
  const parent = identifier.getParent();
2338
2381
  if (!parent) return void 0;
2339
- if (ts_morph.Node.isImportSpecifier(parent) || ts_morph.Node.isNamespaceImport(parent) || ts_morph.Node.isImportClause(parent)) return "";
2382
+ if (ts_morph.Node.isImportSpecifier(parent) || ts_morph.Node.isNamespaceImport(parent) || ts_morph.Node.isImportClause(parent) || ts_morph.Node.isExportSpecifier(parent)) return { kind: "binding" };
2340
2383
  if (ts_morph.Node.isCallExpression(parent) && parent.getExpression() === identifier) return literalPath(parent);
2341
2384
  if (!ts_morph.Node.isPropertyAccessExpression(parent) || parent.getExpression() !== identifier) return void 0;
2342
2385
  const property = parent.getNameNode().getText();
2343
2386
  const grandParent = parent.getParent();
2344
- if (property === "var" || property === "value") return ts_morph.Node.isCallExpression(grandParent) && grandParent.getExpression() === parent ? literalPath(grandParent) : void 0;
2387
+ if (property === "value") return ts_morph.Node.isCallExpression(grandParent) && grandParent.getExpression() === parent ? literalPath(grandParent) : void 0;
2345
2388
  if (property !== "token") return void 0;
2346
2389
  if (ts_morph.Node.isCallExpression(grandParent) && grandParent.getExpression() === parent) return literalPath(grandParent);
2347
2390
  if (ts_morph.Node.isPropertyAccessExpression(grandParent) && grandParent.getExpression() === parent) {
2348
- const method = grandParent.getNameNode().getText();
2349
- if (method !== "var" && method !== "value") return void 0;
2391
+ if (grandParent.getNameNode().getText() !== "value") return void 0;
2350
2392
  const call = grandParent.getParent();
2351
2393
  return ts_morph.Node.isCallExpression(call) && call.getExpression() === grandParent ? literalPath(call) : void 0;
2352
2394
  }
2353
2395
  }
2354
2396
  /**
2355
- * The path a call asks for, when the first argument is a literal.
2397
+ * The path a call asks for, or the prefix it is bounded by.
2356
2398
  *
2357
2399
  * Read through `getLiteralValue()`, never off the source text. The text carries escapes —
2358
2400
  * `token('colors.red.300')` — and a path recorded raw looks up nothing, which
2359
2401
  * would accept a reference and keep no declaration for it. That is the exact failure this
2360
2402
  * module exists to make unrepresentable.
2403
+ *
2404
+ * A template literal with substitutions is not a path, but it is not unbounded either: its
2405
+ * head is a prefix everything it can produce begins with. Declining one cost every token
2406
+ * declaration in the project; bounding it costs the category. The head is the *whole* answer —
2407
+ * `` `colors.${a}.${b}` `` bounds no more tightly than `` `colors.${x}` `` does — and an empty
2408
+ * head bounds nothing at all, so that still declines.
2361
2409
  */
2362
2410
  function literalPath(call) {
2363
2411
  if (!ts_morph.Node.isCallExpression(call)) return void 0;
2364
- const argument = call.getArguments()[0];
2412
+ const argument = unwrapAssertions(call.getArguments()[0]);
2365
2413
  if (!argument) return void 0;
2366
- if (ts_morph.Node.isStringLiteral(argument)) return argument.getLiteralValue();
2367
- if (ts_morph.Node.isNoSubstitutionTemplateLiteral(argument)) return argument.getLiteralValue();
2414
+ if (ts_morph.Node.isStringLiteral(argument)) return {
2415
+ kind: "path",
2416
+ value: argument.getLiteralValue()
2417
+ };
2418
+ if (ts_morph.Node.isNoSubstitutionTemplateLiteral(argument)) return {
2419
+ kind: "path",
2420
+ value: argument.getLiteralValue()
2421
+ };
2422
+ if (ts_morph.Node.isTemplateExpression(argument)) {
2423
+ const head = argument.getHead().getLiteralText();
2424
+ return head ? {
2425
+ kind: "prefix",
2426
+ value: head
2427
+ } : void 0;
2428
+ }
2429
+ }
2430
+ /**
2431
+ * Whether a binding is read anywhere outside a type position.
2432
+ *
2433
+ * `import { Token, token }` brings in a type beside the value, and a type cannot produce a
2434
+ * `var()` — but a binding that is *called* can, whatever it is named, because a barrel
2435
+ * matching the specifier test could re-export `token` under it.
2436
+ */
2437
+ function usedAsValue(sourceFile, name, declaration) {
2438
+ return sourceFile.getDescendantsOfKind(ts_morph.SyntaxKind.Identifier).some((identifier) => {
2439
+ if (nameOf(identifier) !== name) return false;
2440
+ if (identifier.getFirstAncestor((ancestor) => ancestor === declaration)) return false;
2441
+ return !identifier.getFirstAncestor((ancestor) => ts_morph.Node.isTypeNode(ancestor));
2442
+ });
2443
+ }
2444
+ /**
2445
+ * Strip the wrappers that carry no runtime meaning.
2446
+ *
2447
+ * `` token(`animations.${name}` as Token) `` is the shape a *typed* caller writes, and has to
2448
+ * be: the generated `Token` type is a union of template literals, so a `string`-typed
2449
+ * substitution does not typecheck without the assertion. Reading only the outermost node
2450
+ * declined exactly the call this bounding exists for — the one in this repository's own
2451
+ * documentation site.
2452
+ *
2453
+ * Each of these evaluates to its inner expression, so unwrapping changes nothing about what
2454
+ * the call receives.
2455
+ */
2456
+ function unwrapAssertions(node) {
2457
+ let current = node;
2458
+ while (current && (ts_morph.Node.isAsExpression(current) || ts_morph.Node.isSatisfiesExpression(current) || ts_morph.Node.isNonNullExpression(current) || ts_morph.Node.isParenthesizedExpression(current) || ts_morph.Node.isTypeAssertion(current))) current = current.getExpression();
2459
+ return current;
2368
2460
  }
2369
2461
  //#endregion
2370
2462
  //#region src/token-references.ts
2371
2463
  /**
2372
- * `token.var('colors.red.300')` and `token('spacing.4')`, including the whitespace a
2464
+ * `token('spacing.4')` and `token.value('colors.red.300')`, including the whitespace a
2373
2465
  * formatter may leave behind. The parser reports both, resolving constants and template
2374
- * literals through them — `token.var()` included, since it is recorded as its own kind
2466
+ * literals through them — `token.value()` included, since it is recorded as its own kind
2375
2467
  * rather than dropped for having a property access as its callee. Scanning the text still
2376
2468
  * earns its place twice over: it covers a path built somewhere the extractor cannot
2377
2469
  * follow, and it covers the callers below that supply no `results` at all.
2378
2470
  */
2379
- const TOKEN_CALL = /\btoken(?:\s*\.\s*(?:var|value))?\s*\(\s*['"`]([^'"`]+)['"`]/g;
2471
+ const TOKEN_CALL = /\btoken(?:\s*\.\s*value)?\s*\(\s*['"`]([^'"`]+)['"`]/g;
2380
2472
  /**
2381
2473
  * A token reached from javascript at all — a call of any shape, or an import of the artifact.
2382
2474
  *
@@ -2384,7 +2476,7 @@ const TOKEN_CALL = /\btoken(?:\s*\.\s*(?:var|value))?\s*\(\s*['"`]([^'"`]+)['"`]
2384
2476
  * also wherever that one gives up. See `collectTokenReferences` for why the redundancy holds.
2385
2477
  * No `g` flag, so `test` carries no state between files.
2386
2478
  */
2387
- const REACHABLE_FROM_JS = /\btoken(\s*\.\s*(?:var|value))?\s*\(|\b(?:from|import|require)\s*\(?\s*['"][^'"]*\/tokens(\/[^'"]*|\.[cm]?[jt]sx?)?['"]/;
2479
+ const REACHABLE_FROM_JS = /\btoken(\s*\.\s*value)?\s*\(|\b(?:from|import|require)\s*\(?\s*['"][^'"]*\/tokens(\/[^'"]*|\.[cm]?[jt]sx?)?['"]/;
2388
2480
  /**
2389
2481
  * The text of every file `include` covers — as written on disk, and, when they differ, as the
2390
2482
  * parser understands it.
@@ -2431,6 +2523,7 @@ function pruneTokensForBuild(ctx, sheet, results) {
2431
2523
  const vars = /* @__PURE__ */ new Set();
2432
2524
  const accounting = {
2433
2525
  paths: /* @__PURE__ */ new Set(),
2526
+ prefixes: /* @__PURE__ */ new Set(),
2434
2527
  declined: []
2435
2528
  };
2436
2529
  let reachable = false;
@@ -2449,7 +2542,16 @@ function pruneTokensForBuild(ctx, sheet, results) {
2449
2542
  return;
2450
2543
  }
2451
2544
  for (const name of tokenVarsFor(ctx, accounting.paths)) vars.add(name);
2452
- if (accounting.declined.length) _bamboocss_logger.logger.warn("tokens:strict", formatDeclined(ctx, accounting.declined));
2545
+ if (accounting.prefixes.size && !accounting.declined.length) {
2546
+ const prefixes = Array.from(accounting.prefixes);
2547
+ const matched = [];
2548
+ for (const token of ctx.tokens.allTokens) if (prefixes.some((prefix) => token.name.startsWith(prefix))) matched.push(token.name);
2549
+ for (const name of tokenVarsFor(ctx, matched)) vars.add(name);
2550
+ }
2551
+ const failing = accounting.declined.filter(failsStrict);
2552
+ const reported = accounting.declined.filter((entry) => !failsStrict(entry));
2553
+ if (failing.length) throw new _bamboocss_shared.BambooError("TOKEN_REFERENCE_UNRESOLVED", `${failing.length} token reference(s) could not be resolved.\n\n${formatDeclined(ctx, failing)}\n\n\`pruneUnusedTokens: 'strict'\` asserts that every token path resolves at build time, so this is an error rather than a silent fallback. Spell the path as a string literal at the call, give a template a static prefix so it can be bounded, move the token into \`staticCss\`, or set \`pruneUnusedTokens: true\` to stop asserting.`);
2554
+ if (reported.length) _bamboocss_logger.logger.warn("tokens:strict", `${reported.length} reference(s) could not be accounted for, so every token declaration is kept.\n\n${formatDeclined(ctx, reported)}\n\nThese are shapes the build cannot follow rather than paths you can respell — a component stored post-transform, a file it could not parse, a barrel it cannot classify, a dynamic \`import()\`. Narrow \`include\`, or accept the keeps.`);
2453
2555
  ctx.pruneTokens(sheet, vars, accounting.declined.length > 0 && reachable);
2454
2556
  }
2455
2557
  /** The custom properties a set of token paths resolves to. */
@@ -2463,13 +2565,7 @@ function tokenVarsFor(ctx, paths) {
2463
2565
  }
2464
2566
  return vars;
2465
2567
  }
2466
- /**
2467
- * Why `strict` could not prune, grouped by file.
2468
- *
2469
- * Printed rather than thrown. A decline is not an error — the build falls back to keeping
2470
- * every declaration, which is what would have happened anyway — it is the answer to "why is my
2471
- * token layer still this size", which otherwise has no answer at all.
2472
- */
2568
+ /** Where to look, grouped by file. The surrounding text differs by whether this throws. */
2473
2569
  function formatDeclined(ctx, declined) {
2474
2570
  const byFile = /* @__PURE__ */ new Map();
2475
2571
  for (const entry of declined) {
@@ -2477,10 +2573,9 @@ function formatDeclined(ctx, declined) {
2477
2573
  list.push(entry);
2478
2574
  byFile.set(entry.filePath, list);
2479
2575
  }
2480
- const detail = Array.from(byFile.entries()).map(([filePath, entries]) => {
2576
+ return Array.from(byFile.entries()).map(([filePath, entries]) => {
2481
2577
  return [` ${filePath.startsWith(ctx.config.cwd) ? filePath.slice(ctx.config.cwd.length + 1) : filePath}`, ...entries.map((entry) => ` ${entry.line}: ${entry.reason}`)].join("\n");
2482
2578
  }).join("\n");
2483
- return `${declined.length} token reference(s) could not be resolved, so every token declaration is kept.\n\n${detail}\n\nSpell the path as a string literal at the call, move it into \`staticCss\`, or set \`pruneUnusedTokens: true\` to stop asking.`;
2484
2579
  }
2485
2580
  /**
2486
2581
  * Collect keyframe names that reading the generated css cannot reveal.
package/dist/index.mjs CHANGED
@@ -1795,7 +1795,7 @@ var BambooContext = class extends Generator {
1795
1795
  poll
1796
1796
  }).on("change", debounce(async (file) => {
1797
1797
  logger.info("ctx:change", "config changed, rebuilding...");
1798
- await cb(file);
1798
+ await reportRebuildFailure(() => cb(file));
1799
1799
  }));
1800
1800
  };
1801
1801
  watchFiles = (cb, opts) => {
@@ -1809,10 +1809,30 @@ var BambooContext = class extends Generator {
1809
1809
  cwd
1810
1810
  }).on("all", debounce(async (event, file) => {
1811
1811
  logger.info(`file:${event}`, file);
1812
- await cb(event, file);
1812
+ await reportRebuildFailure(() => cb(event, file));
1813
1813
  }));
1814
1814
  };
1815
1815
  };
1816
+ /**
1817
+ * Report a failed rebuild as a failed rebuild.
1818
+ *
1819
+ * Chokidar is an `EventEmitter`, so it discards whatever a listener returns, and the debounce
1820
+ * wrapper attaches no rejection handler — a throw from inside a rebuild became a dangling
1821
+ * promise. `node-runtime.ts` then catches it as `Unhandled rejection`, which labels a config
1822
+ * error as an internal crash, leaves the exit code at 0, and is suppressed entirely at
1823
+ * `logLevel: 'silent'`. The initial build is caught by the CLI and prints properly; only
1824
+ * rebuilds of the identical source were silent, which is the worse half of the asymmetry.
1825
+ *
1826
+ * Caught rather than rethrown: a watcher's job is to survive a bad intermediate state and
1827
+ * rebuild when the next edit fixes it. What it must not do is claim success.
1828
+ */
1829
+ async function reportRebuildFailure(run) {
1830
+ try {
1831
+ await run();
1832
+ } catch (error) {
1833
+ logger.error("ctx:rebuild", error instanceof Error ? error.message : String(error));
1834
+ }
1835
+ }
1816
1836
  //#endregion
1817
1837
  //#region src/tsconfig-utils.ts
1818
1838
  /**
@@ -2171,6 +2191,24 @@ function* snapshotTexts(snapshot) {
2171
2191
  //#endregion
2172
2192
  //#region src/token-accounting.ts
2173
2193
  /**
2194
+ * The one decline `strict` fails the build on.
2195
+ *
2196
+ * `strict` asserts that every token path resolves, and this is the reason that says otherwise:
2197
+ * a token binding used in a way the build cannot follow — a path built at runtime, a binding
2198
+ * assigned away, a namespace enumerated. It is about the author's *token usage*, and it has a
2199
+ * fix at the call site.
2200
+ *
2201
+ * Nothing else may throw, because nothing else is necessarily about tokens at all. The other
2202
+ * reasons were written under a premise this would break: declining was free, so every branch
2203
+ * that could not prove a shape declined, and the accepted set was kept deliberately small.
2204
+ * `import(`./pages/${name}`)` declines as `dynamic-import` because the specifier is not a
2205
+ * literal and *could* be the artifact; `import lexer = require('./tokenizer')` declines because
2206
+ * the statement contains the substring `token`. Both are routine code with nothing to do with
2207
+ * design tokens, and failing a build over them would be indefensible. They keep every
2208
+ * declaration, which is what they always did, and say so.
2209
+ */
2210
+ const failsStrict = (entry) => entry.reason === "unresolved-reference";
2211
+ /**
2174
2212
  * One file's contribution, split out so the build can account and scan in a single walk.
2175
2213
  *
2176
2214
  * `pruneTokensForBuild` needs the keep set, the reachability answer and this accounting from
@@ -2178,7 +2216,7 @@ function* snapshotTexts(snapshot) {
2178
2216
  */
2179
2217
  function accountSnapshot(ctx, snapshot, accounting) {
2180
2218
  const { filePath, onDisk, parsed, sourceFile } = snapshot;
2181
- const { paths, declined } = accounting;
2219
+ const { paths, prefixes, declined } = accounting;
2182
2220
  if (onDisk == null || parsed == null || parsed !== onDisk) {
2183
2221
  if (!((onDisk?.includes("token") ?? false) || (parsed?.includes("token") ?? false))) return;
2184
2222
  declined.push({
@@ -2197,7 +2235,7 @@ function accountSnapshot(ctx, snapshot, accounting) {
2197
2235
  });
2198
2236
  return;
2199
2237
  }
2200
- accountFile(ctx, sourceFile, filePath, paths, declined);
2238
+ accountFile(ctx, sourceFile, filePath, paths, prefixes, declined);
2201
2239
  }
2202
2240
  /**
2203
2241
  * How many syntax errors the parse produced.
@@ -2219,7 +2257,7 @@ const isTokensEntrypoint = (ctx, specifier) => {
2219
2257
  return mods.some((mod) => resolved.includes(mod) || resolved === mod);
2220
2258
  };
2221
2259
  const lineOf = (node) => node.getSourceFile().getLineAndColumnAtPos(node.getStart()).line;
2222
- function accountFile(ctx, sourceFile, filePath, paths, declined) {
2260
+ function accountFile(ctx, sourceFile, filePath, paths, prefixes, declined) {
2223
2261
  const decline = (node, reason) => declined.push({
2224
2262
  filePath,
2225
2263
  line: lineOf(node),
@@ -2253,7 +2291,7 @@ function accountFile(ctx, sourceFile, filePath, paths, declined) {
2253
2291
  for (const named of clause.getNamedImports()) {
2254
2292
  if (named.isTypeOnly()) continue;
2255
2293
  if (nameOf(named.getNameNode()) !== "token") {
2256
- decline(named, "unsupported-import");
2294
+ if (usedAsValue(sourceFile, (named.getAliasNode() ?? named.getNameNode()).getText(), named)) decline(named, "unsupported-import");
2257
2295
  continue;
2258
2296
  }
2259
2297
  bindings.add((named.getAliasNode() ?? named.getNameNode()).getText());
@@ -2281,12 +2319,17 @@ function accountFile(ctx, sourceFile, filePath, paths, declined) {
2281
2319
  continue;
2282
2320
  }
2283
2321
  if (Node.isPropertyAssignment(parent) && parent.getNameNode() === identifier) continue;
2284
- const path = accountedPath(identifier);
2285
- if (path === void 0) {
2322
+ const resolved = accountedPath(identifier);
2323
+ if (resolved === void 0) {
2286
2324
  decline(identifier, "unresolved-reference");
2287
2325
  continue;
2288
2326
  }
2289
- paths.add(path);
2327
+ if (resolved.kind === "binding") continue;
2328
+ if (resolved.kind === "prefix") {
2329
+ prefixes.add(resolved.value);
2330
+ continue;
2331
+ }
2332
+ paths.add(resolved.value);
2290
2333
  }
2291
2334
  }
2292
2335
  /**
@@ -2311,57 +2354,106 @@ function usesTokenMember(sourceFile, namespace) {
2311
2354
  */
2312
2355
  const nameOf = (node) => Node.isIdentifier(node) ? String(node.compilerNode.escapedText) : node.getText();
2313
2356
  /**
2314
- * The token path one occurrence asks for, or `undefined` if it is not a call this can read.
2357
+ * What one occurrence asks for, or `undefined` if it is not a call this can read.
2315
2358
  *
2316
- * Accepts the callee position and nothing else — `token('x')`, `token.var('x')`,
2317
- * `token.value('x')`, and the namespaced spellings. An identifier anywhere else is a value
2359
+ * Accepts the callee position and nothing else — `token('x')`, `token.value('x')`, and the
2360
+ * namespaced spellings of each. An identifier anywhere else is a value
2318
2361
  * escaping somewhere this pass cannot follow: assigned (`const t = token`), passed
2319
2362
  * (`useMemo(() => token)`), spread, or enumerated.
2320
2363
  */
2321
2364
  function accountedPath(identifier) {
2322
2365
  const parent = identifier.getParent();
2323
2366
  if (!parent) return void 0;
2324
- if (Node.isImportSpecifier(parent) || Node.isNamespaceImport(parent) || Node.isImportClause(parent)) return "";
2367
+ if (Node.isImportSpecifier(parent) || Node.isNamespaceImport(parent) || Node.isImportClause(parent) || Node.isExportSpecifier(parent)) return { kind: "binding" };
2325
2368
  if (Node.isCallExpression(parent) && parent.getExpression() === identifier) return literalPath(parent);
2326
2369
  if (!Node.isPropertyAccessExpression(parent) || parent.getExpression() !== identifier) return void 0;
2327
2370
  const property = parent.getNameNode().getText();
2328
2371
  const grandParent = parent.getParent();
2329
- if (property === "var" || property === "value") return Node.isCallExpression(grandParent) && grandParent.getExpression() === parent ? literalPath(grandParent) : void 0;
2372
+ if (property === "value") return Node.isCallExpression(grandParent) && grandParent.getExpression() === parent ? literalPath(grandParent) : void 0;
2330
2373
  if (property !== "token") return void 0;
2331
2374
  if (Node.isCallExpression(grandParent) && grandParent.getExpression() === parent) return literalPath(grandParent);
2332
2375
  if (Node.isPropertyAccessExpression(grandParent) && grandParent.getExpression() === parent) {
2333
- const method = grandParent.getNameNode().getText();
2334
- if (method !== "var" && method !== "value") return void 0;
2376
+ if (grandParent.getNameNode().getText() !== "value") return void 0;
2335
2377
  const call = grandParent.getParent();
2336
2378
  return Node.isCallExpression(call) && call.getExpression() === grandParent ? literalPath(call) : void 0;
2337
2379
  }
2338
2380
  }
2339
2381
  /**
2340
- * The path a call asks for, when the first argument is a literal.
2382
+ * The path a call asks for, or the prefix it is bounded by.
2341
2383
  *
2342
2384
  * Read through `getLiteralValue()`, never off the source text. The text carries escapes —
2343
2385
  * `token('colors.red.300')` — and a path recorded raw looks up nothing, which
2344
2386
  * would accept a reference and keep no declaration for it. That is the exact failure this
2345
2387
  * module exists to make unrepresentable.
2388
+ *
2389
+ * A template literal with substitutions is not a path, but it is not unbounded either: its
2390
+ * head is a prefix everything it can produce begins with. Declining one cost every token
2391
+ * declaration in the project; bounding it costs the category. The head is the *whole* answer —
2392
+ * `` `colors.${a}.${b}` `` bounds no more tightly than `` `colors.${x}` `` does — and an empty
2393
+ * head bounds nothing at all, so that still declines.
2346
2394
  */
2347
2395
  function literalPath(call) {
2348
2396
  if (!Node.isCallExpression(call)) return void 0;
2349
- const argument = call.getArguments()[0];
2397
+ const argument = unwrapAssertions(call.getArguments()[0]);
2350
2398
  if (!argument) return void 0;
2351
- if (Node.isStringLiteral(argument)) return argument.getLiteralValue();
2352
- if (Node.isNoSubstitutionTemplateLiteral(argument)) return argument.getLiteralValue();
2399
+ if (Node.isStringLiteral(argument)) return {
2400
+ kind: "path",
2401
+ value: argument.getLiteralValue()
2402
+ };
2403
+ if (Node.isNoSubstitutionTemplateLiteral(argument)) return {
2404
+ kind: "path",
2405
+ value: argument.getLiteralValue()
2406
+ };
2407
+ if (Node.isTemplateExpression(argument)) {
2408
+ const head = argument.getHead().getLiteralText();
2409
+ return head ? {
2410
+ kind: "prefix",
2411
+ value: head
2412
+ } : void 0;
2413
+ }
2414
+ }
2415
+ /**
2416
+ * Whether a binding is read anywhere outside a type position.
2417
+ *
2418
+ * `import { Token, token }` brings in a type beside the value, and a type cannot produce a
2419
+ * `var()` — but a binding that is *called* can, whatever it is named, because a barrel
2420
+ * matching the specifier test could re-export `token` under it.
2421
+ */
2422
+ function usedAsValue(sourceFile, name, declaration) {
2423
+ return sourceFile.getDescendantsOfKind(SyntaxKind.Identifier).some((identifier) => {
2424
+ if (nameOf(identifier) !== name) return false;
2425
+ if (identifier.getFirstAncestor((ancestor) => ancestor === declaration)) return false;
2426
+ return !identifier.getFirstAncestor((ancestor) => Node.isTypeNode(ancestor));
2427
+ });
2428
+ }
2429
+ /**
2430
+ * Strip the wrappers that carry no runtime meaning.
2431
+ *
2432
+ * `` token(`animations.${name}` as Token) `` is the shape a *typed* caller writes, and has to
2433
+ * be: the generated `Token` type is a union of template literals, so a `string`-typed
2434
+ * substitution does not typecheck without the assertion. Reading only the outermost node
2435
+ * declined exactly the call this bounding exists for — the one in this repository's own
2436
+ * documentation site.
2437
+ *
2438
+ * Each of these evaluates to its inner expression, so unwrapping changes nothing about what
2439
+ * the call receives.
2440
+ */
2441
+ function unwrapAssertions(node) {
2442
+ let current = node;
2443
+ while (current && (Node.isAsExpression(current) || Node.isSatisfiesExpression(current) || Node.isNonNullExpression(current) || Node.isParenthesizedExpression(current) || Node.isTypeAssertion(current))) current = current.getExpression();
2444
+ return current;
2353
2445
  }
2354
2446
  //#endregion
2355
2447
  //#region src/token-references.ts
2356
2448
  /**
2357
- * `token.var('colors.red.300')` and `token('spacing.4')`, including the whitespace a
2449
+ * `token('spacing.4')` and `token.value('colors.red.300')`, including the whitespace a
2358
2450
  * formatter may leave behind. The parser reports both, resolving constants and template
2359
- * literals through them — `token.var()` included, since it is recorded as its own kind
2451
+ * literals through them — `token.value()` included, since it is recorded as its own kind
2360
2452
  * rather than dropped for having a property access as its callee. Scanning the text still
2361
2453
  * earns its place twice over: it covers a path built somewhere the extractor cannot
2362
2454
  * follow, and it covers the callers below that supply no `results` at all.
2363
2455
  */
2364
- const TOKEN_CALL = /\btoken(?:\s*\.\s*(?:var|value))?\s*\(\s*['"`]([^'"`]+)['"`]/g;
2456
+ const TOKEN_CALL = /\btoken(?:\s*\.\s*value)?\s*\(\s*['"`]([^'"`]+)['"`]/g;
2365
2457
  /**
2366
2458
  * A token reached from javascript at all — a call of any shape, or an import of the artifact.
2367
2459
  *
@@ -2369,7 +2461,7 @@ const TOKEN_CALL = /\btoken(?:\s*\.\s*(?:var|value))?\s*\(\s*['"`]([^'"`]+)['"`]
2369
2461
  * also wherever that one gives up. See `collectTokenReferences` for why the redundancy holds.
2370
2462
  * No `g` flag, so `test` carries no state between files.
2371
2463
  */
2372
- const REACHABLE_FROM_JS = /\btoken(\s*\.\s*(?:var|value))?\s*\(|\b(?:from|import|require)\s*\(?\s*['"][^'"]*\/tokens(\/[^'"]*|\.[cm]?[jt]sx?)?['"]/;
2464
+ const REACHABLE_FROM_JS = /\btoken(\s*\.\s*value)?\s*\(|\b(?:from|import|require)\s*\(?\s*['"][^'"]*\/tokens(\/[^'"]*|\.[cm]?[jt]sx?)?['"]/;
2373
2465
  /**
2374
2466
  * The text of every file `include` covers — as written on disk, and, when they differ, as the
2375
2467
  * parser understands it.
@@ -2416,6 +2508,7 @@ function pruneTokensForBuild(ctx, sheet, results) {
2416
2508
  const vars = /* @__PURE__ */ new Set();
2417
2509
  const accounting = {
2418
2510
  paths: /* @__PURE__ */ new Set(),
2511
+ prefixes: /* @__PURE__ */ new Set(),
2419
2512
  declined: []
2420
2513
  };
2421
2514
  let reachable = false;
@@ -2434,7 +2527,16 @@ function pruneTokensForBuild(ctx, sheet, results) {
2434
2527
  return;
2435
2528
  }
2436
2529
  for (const name of tokenVarsFor(ctx, accounting.paths)) vars.add(name);
2437
- if (accounting.declined.length) logger.warn("tokens:strict", formatDeclined(ctx, accounting.declined));
2530
+ if (accounting.prefixes.size && !accounting.declined.length) {
2531
+ const prefixes = Array.from(accounting.prefixes);
2532
+ const matched = [];
2533
+ for (const token of ctx.tokens.allTokens) if (prefixes.some((prefix) => token.name.startsWith(prefix))) matched.push(token.name);
2534
+ for (const name of tokenVarsFor(ctx, matched)) vars.add(name);
2535
+ }
2536
+ const failing = accounting.declined.filter(failsStrict);
2537
+ const reported = accounting.declined.filter((entry) => !failsStrict(entry));
2538
+ if (failing.length) throw new BambooError("TOKEN_REFERENCE_UNRESOLVED", `${failing.length} token reference(s) could not be resolved.\n\n${formatDeclined(ctx, failing)}\n\n\`pruneUnusedTokens: 'strict'\` asserts that every token path resolves at build time, so this is an error rather than a silent fallback. Spell the path as a string literal at the call, give a template a static prefix so it can be bounded, move the token into \`staticCss\`, or set \`pruneUnusedTokens: true\` to stop asserting.`);
2539
+ if (reported.length) logger.warn("tokens:strict", `${reported.length} reference(s) could not be accounted for, so every token declaration is kept.\n\n${formatDeclined(ctx, reported)}\n\nThese are shapes the build cannot follow rather than paths you can respell — a component stored post-transform, a file it could not parse, a barrel it cannot classify, a dynamic \`import()\`. Narrow \`include\`, or accept the keeps.`);
2438
2540
  ctx.pruneTokens(sheet, vars, accounting.declined.length > 0 && reachable);
2439
2541
  }
2440
2542
  /** The custom properties a set of token paths resolves to. */
@@ -2448,13 +2550,7 @@ function tokenVarsFor(ctx, paths) {
2448
2550
  }
2449
2551
  return vars;
2450
2552
  }
2451
- /**
2452
- * Why `strict` could not prune, grouped by file.
2453
- *
2454
- * Printed rather than thrown. A decline is not an error — the build falls back to keeping
2455
- * every declaration, which is what would have happened anyway — it is the answer to "why is my
2456
- * token layer still this size", which otherwise has no answer at all.
2457
- */
2553
+ /** Where to look, grouped by file. The surrounding text differs by whether this throws. */
2458
2554
  function formatDeclined(ctx, declined) {
2459
2555
  const byFile = /* @__PURE__ */ new Map();
2460
2556
  for (const entry of declined) {
@@ -2462,10 +2558,9 @@ function formatDeclined(ctx, declined) {
2462
2558
  list.push(entry);
2463
2559
  byFile.set(entry.filePath, list);
2464
2560
  }
2465
- const detail = Array.from(byFile.entries()).map(([filePath, entries]) => {
2561
+ return Array.from(byFile.entries()).map(([filePath, entries]) => {
2466
2562
  return [` ${filePath.startsWith(ctx.config.cwd) ? filePath.slice(ctx.config.cwd.length + 1) : filePath}`, ...entries.map((entry) => ` ${entry.line}: ${entry.reason}`)].join("\n");
2467
2563
  }).join("\n");
2468
- return `${declined.length} token reference(s) could not be resolved, so every token declaration is kept.\n\n${detail}\n\nSpell the path as a string literal at the call, move it into \`staticCss\`, or set \`pruneUnusedTokens: true\` to stop asking.`;
2469
2564
  }
2470
2565
  /**
2471
2566
  * Collect keyframe names that reading the generated css cannot reveal.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@bamboocss/node",
3
- "version": "1.29.0",
3
+ "version": "1.30.0",
4
4
  "description": "The core css bamboo library",
5
5
  "homepage": "https://bamboocss.com",
6
6
  "license": "MIT",
@@ -52,18 +52,18 @@
52
52
  "postcss": "8.5.26",
53
53
  "ts-morph": "28.0.0",
54
54
  "ts-pattern": "5.9.0",
55
- "@bamboocss/config": "1.29.0",
56
- "@bamboocss/core": "1.29.0",
57
- "@bamboocss/generator": "1.29.0",
58
- "@bamboocss/logger": "1.29.0",
59
- "@bamboocss/parser": "1.29.0",
60
- "@bamboocss/plugin-lightningcss": "1.29.0",
61
- "@bamboocss/plugin-svelte": "1.29.0",
62
- "@bamboocss/plugin-vue": "1.29.0",
63
- "@bamboocss/reporter": "1.29.0",
64
- "@bamboocss/shared": "1.29.0",
65
- "@bamboocss/token-dictionary": "1.29.0",
66
- "@bamboocss/types": "1.29.0"
55
+ "@bamboocss/config": "1.30.0",
56
+ "@bamboocss/core": "1.30.0",
57
+ "@bamboocss/generator": "1.30.0",
58
+ "@bamboocss/logger": "1.30.0",
59
+ "@bamboocss/parser": "1.30.0",
60
+ "@bamboocss/plugin-lightningcss": "1.30.0",
61
+ "@bamboocss/plugin-svelte": "1.30.0",
62
+ "@bamboocss/plugin-vue": "1.30.0",
63
+ "@bamboocss/reporter": "1.30.0",
64
+ "@bamboocss/shared": "1.30.0",
65
+ "@bamboocss/token-dictionary": "1.30.0",
66
+ "@bamboocss/types": "1.30.0"
67
67
  },
68
68
  "devDependencies": {
69
69
  "@types/fs-extra": "11.0.4",