@bamboocss/node 1.31.0 → 1.33.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.
package/README.md CHANGED
@@ -14,7 +14,7 @@ Everything below is exported from `@bamboocss/node`.
14
14
  ### Context
15
15
 
16
16
  - `loadConfigAndCreateContext({ cwd?, config?, configPath? })` – resolve the config file, merge presets and inline
17
- overrides, auto-inject the built-in plugins (`vue`, `svelte`, `lightningcss`), and return a `BambooContext`.
17
+ overrides, auto-inject the built-in plugins (`vue`, `svelte`), and return a `BambooContext`.
18
18
  - `BambooContext` – the resolved config plus everything derived from it: tokens, utilities, conditions, recipes,
19
19
  patterns, the `ts-morph` project, the output engine and the diff engine.
20
20
  - `Builder` – the incremental driver the bundler plugins use. It owns context setup, tracks which files and config
package/dist/index.cjs CHANGED
@@ -25,12 +25,12 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
25
25
  let _bamboocss_reporter = require("@bamboocss/reporter");
26
26
  let _bamboocss_logger = require("@bamboocss/logger");
27
27
  let _bamboocss_config = require("@bamboocss/config");
28
+ let _bamboocss_core = require("@bamboocss/core");
28
29
  let _bamboocss_shared = require("@bamboocss/shared");
29
30
  let fs = require("fs");
30
31
  let path = require("path");
31
32
  let _bamboocss_plugin_svelte = require("@bamboocss/plugin-svelte");
32
33
  let _bamboocss_plugin_vue = require("@bamboocss/plugin-vue");
33
- let _bamboocss_core = require("@bamboocss/core");
34
34
  let _bamboocss_generator = require("@bamboocss/generator");
35
35
  let _bamboocss_parser = require("@bamboocss/parser");
36
36
  let perfect_debounce = require("perfect-debounce");
@@ -56,6 +56,7 @@ let is_glob = require("is-glob");
56
56
  is_glob = __toESM(is_glob);
57
57
  let glob_parent = require("glob-parent");
58
58
  glob_parent = __toESM(glob_parent);
59
+ let matcher = require("matcher");
59
60
  let _bamboocss_config_ts_path = require("@bamboocss/config/ts-path");
60
61
  let ts_morph = require("ts-morph");
61
62
  let node_readline = require("node:readline");
@@ -1610,6 +1611,8 @@ var OutputEngine = class {
1610
1611
  };
1611
1612
  //#endregion
1612
1613
  //#region src/create-context.ts
1614
+ /** A thrown value's message, for a `catch` binding that is typed `unknown`. */
1615
+ const messageOf = (error) => error instanceof Error ? error.message : String(error);
1613
1616
  /**
1614
1617
  * What each loss is, and what the author can do about it.
1615
1618
  *
@@ -1630,6 +1633,26 @@ var BambooContext = class extends _bamboocss_generator.Generator {
1630
1633
  output;
1631
1634
  diff;
1632
1635
  explicitDeps = [];
1636
+ /**
1637
+ * Files whose extraction threw, keyed by path, holding what it threw.
1638
+ *
1639
+ * A parse failure is not an opinion about a build that still works. The file's styles never
1640
+ * reach the encoder, so every rule it would have contributed is absent from the stylesheet
1641
+ * and the classes its components ask for have nothing behind them — the same shape as a
1642
+ * naming disagreement, and the reverse of `reportUnresolvedStyles`, where what the build
1643
+ * *did* see still applies. Logging it and carrying on is how a build printed error-level
1644
+ * lines, dropped rules, and exited 0.
1645
+ *
1646
+ * Retained rather than rethrown from the `catch`, so one pass names every broken file
1647
+ * instead of the first. Keyed by file, so a failure survives the incremental passes that
1648
+ * skip an unchanged file: nothing re-parses it, and its styles stay missing until it does.
1649
+ *
1650
+ * The error rather than its message, so `assertExtracted` can hand the originals on as a
1651
+ * `cause`. The aggregate carries a code of its own — `ERR_BAMBOO_EXTRACT_FAILED` — and the
1652
+ * codes underneath it are what a caller has to read to tell a retired token spelling from a
1653
+ * syntax error.
1654
+ */
1655
+ parseFailures = /* @__PURE__ */ new Map();
1633
1656
  constructor(conf) {
1634
1657
  super(conf);
1635
1658
  const config = conf.config;
@@ -1699,6 +1722,35 @@ var BambooContext = class extends _bamboocss_generator.Generator {
1699
1722
  cwd
1700
1723
  });
1701
1724
  };
1725
+ /**
1726
+ * Fail the build if any file's extraction threw.
1727
+ *
1728
+ * Called at the end of an extraction pass rather than from the `catch`, so the message names
1729
+ * every broken file at once — a config with one retired token spelling in six components is
1730
+ * fixed once, not six builds in a row.
1731
+ *
1732
+ * This is what makes the integrations agree. `cssgen` already exited non-zero on a file it
1733
+ * could not extract, by letting the throw through; every bundler goes through `parseFile`,
1734
+ * which caught it. CI running a build passed what CI running `cssgen` rejected, over the same
1735
+ * source.
1736
+ *
1737
+ * `files` is the set still in scope, which the caller has usually just globbed. Deleting the
1738
+ * offending file, or taking it out of `include`, is a *fix* — and nothing re-parses a file
1739
+ * that is gone, so the entry that outlived it would fail every later build, naming a path
1740
+ * that no longer exists. A context outlives rebuilds (it is replaced only when the config
1741
+ * changes) and both long-lived integrations hold one, so that wedged a dev server until the
1742
+ * process was restarted.
1743
+ */
1744
+ assertExtracted = (files) => {
1745
+ if (!this.parseFailures.size) return;
1746
+ const inScope = new Set(Array.from(files ?? this.getFiles(), (file) => this.runtime.path.abs(this.config.cwd, file)));
1747
+ for (const file of this.parseFailures.keys()) if (!inScope.has(file)) this.parseFailures.delete(file);
1748
+ if (!this.parseFailures.size) return;
1749
+ const detail = Array.from(this.parseFailures.entries()).map(([file, error]) => `${this.relative(file)}\n${messageOf(error).replace(/^(?=.)/gm, " ")}`).join("\n\n");
1750
+ throw new _bamboocss_shared.BambooError("EXTRACT_FAILED", `${this.parseFailures.size} file(s) could not be extracted:\n\n${detail}\n\nNothing emits a rule for a file the build could not read, so every style in these is absent from the stylesheet and the classes their components ask for have nothing behind them.`, { cause: new AggregateError(Array.from(this.parseFailures.values()), `${this.parseFailures.size} file(s) could not be extracted`) });
1751
+ };
1752
+ /** A path as the user typed it, when it is under `cwd`. */
1753
+ relative = (file) => file.startsWith(this.config.cwd) ? file.slice(this.config.cwd.length + 1) : file;
1702
1754
  parseFile = (filePath, styleEncoder) => {
1703
1755
  const file = this.runtime.path.abs(this.config.cwd, filePath);
1704
1756
  _bamboocss_logger.logger.debug("file:extract", file);
@@ -1707,27 +1759,34 @@ var BambooContext = class extends _bamboocss_generator.Generator {
1707
1759
  try {
1708
1760
  const encoder = styleEncoder || this.parserOptions.encoder;
1709
1761
  result = this.project.parseSourceFile(file, encoder);
1762
+ this.parseFailures.delete(file);
1710
1763
  } catch (error) {
1711
1764
  _bamboocss_logger.logger.caughtError("file:extract", `Failed to parse ${file}`, error);
1765
+ this.parseFailures.set(file, error);
1712
1766
  }
1713
1767
  if (result) this.reportUnresolvedStyles(result);
1714
1768
  measure();
1715
1769
  return result;
1716
1770
  };
1771
+ /**
1772
+ * Extract every file in one pass, and fail on the ones that could not be read.
1773
+ *
1774
+ * Routed through `parseFile` rather than parsing directly, so the two entry points cannot
1775
+ * disagree about what a failure means. This one used to let the first throw out, which is
1776
+ * why `cssgen` and a bundler build reported different things about the same source.
1777
+ */
1717
1778
  parseFiles = (styleEncoder) => {
1718
1779
  const encoder = styleEncoder || this.parserOptions.encoder;
1719
1780
  const files = this.getFiles();
1720
1781
  const filesWithCss = [];
1721
1782
  const results = [];
1722
1783
  files.forEach((file) => {
1723
- const measure = _bamboocss_logger.logger.time.debug(`Parsed ${file}`);
1724
- const result = this.project.parseSourceFile(file, encoder);
1725
- measure();
1726
- if (result) this.reportUnresolvedStyles(result);
1784
+ const result = this.parseFile(file, encoder);
1727
1785
  if (!result || result.isEmpty() || encoder.isEmpty()) return;
1728
1786
  filesWithCss.push(file);
1729
1787
  results.push(result);
1730
1788
  });
1789
+ this.assertExtracted(files);
1731
1790
  return {
1732
1791
  filesWithCss,
1733
1792
  files,
@@ -2528,7 +2587,7 @@ function* sourceTexts(ctx) {
2528
2587
  * The token prune, as all three build paths need to run it.
2529
2588
  *
2530
2589
  * One function because it was three copies of one conditional, and the `false` branch went
2531
- * missing from a copy: a watch rebuild with `prune: { tokens: false }` skipped `pruneTokens`
2590
+ * missing from a copy: a watch rebuild with `prune: { tokens: 'off' }` skipped `pruneTokens`
2532
2591
  * altogether, so it kept `@property` registrations that a full build of the same source
2533
2592
  * strips. The other two copies carried a comment pointing at that file for the reasoning,
2534
2593
  * which is how a missing branch reads as intentional.
@@ -2564,12 +2623,15 @@ function pruneTokensForBuild(ctx, sheet, results) {
2564
2623
  if (accounts) accountSnapshot(ctx, snapshot, accounting);
2565
2624
  }
2566
2625
  for (const name of tokenVarsFor(ctx, paths)) vars.add(name);
2626
+ const declared = declaredKeeps(ctx);
2627
+ for (const name of tokenVarsFor(ctx, declared)) vars.add(name);
2567
2628
  if (!accounts) {
2568
2629
  ctx.pruneTokens(sheet, vars, reachable);
2569
2630
  return;
2570
2631
  }
2571
2632
  for (const name of tokenVarsFor(ctx, accounting.paths)) vars.add(name);
2572
- if (accounting.prefixes.size && !accounting.declined.length) {
2633
+ const bounded = (ctx.config.prune?.keepTokens?.length ?? 0) > 0;
2634
+ if (accounting.prefixes.size && (bounded || !accounting.declined.length)) {
2573
2635
  const prefixes = Array.from(accounting.prefixes);
2574
2636
  const matched = [];
2575
2637
  for (const token of ctx.tokens.allTokens) if (prefixes.some((prefix) => token.name.startsWith(prefix))) matched.push(token.name);
@@ -2577,13 +2639,59 @@ function pruneTokensForBuild(ctx, sheet, results) {
2577
2639
  }
2578
2640
  const failing = accounting.declined.filter(failsStrict);
2579
2641
  const reported = accounting.declined.filter((entry) => !failsStrict(entry));
2580
- if (failing.length) {
2581
- const message = `${failing.length} token reference(s) could not be resolved.\n\n${formatDeclined(ctx, failing)}\n\n\`prune.tokens: 'accounted'\` asserts that every token path resolves at build time. 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\`, set \`prune: { unresolvedPath: 'warn' }\` to keep the assertion without failing, or \`prune: { tokens: 'reachable' }\` to stop asserting.`;
2582
- if (unresolved === "error") throw new _bamboocss_shared.BambooError("TOKEN_REFERENCE_UNRESOLVED", message);
2583
- _bamboocss_logger.logger.warn("tokens:unresolved", message);
2642
+ if (bounded && unresolved === "error" && accounting.declined.length) throw new _bamboocss_shared.BambooError("TOKEN_REFERENCE_UNRESOLVED", `${accounting.declined.length} token reference(s) could not be accounted for.\n\n${formatDeclined(ctx, accounting.declined)}\n\n\`prune.unresolvedPath: 'error'\` asserts that every token path resolves at build time, and \`prune.keepTokens\` declares where the ones that do not will land. Those are contradictory, so one has to go: drop \`keepTokens\` and respell the paths, or set \`prune: { unresolvedPath: 'warn' }\` and let the keeps cover them.`);
2643
+ if (failing.length && unresolved !== "off") {
2644
+ const where = `${failing.length} token reference(s) could not be resolved.\n\n${formatDeclined(ctx, failing)}\n\n`;
2645
+ if (unresolved === "error") throw new _bamboocss_shared.BambooError("TOKEN_REFERENCE_UNRESOLVED", where + "`prune.tokens: 'accounted'` asserts that every token path resolves at build time. Spell the path as a string literal at the call, give a template a static prefix so it can be bounded, name the category they land in with `prune: { keepTokens: ['colors.*'] }` and drop to `prune: { unresolvedPath: 'warn' }`, or set `prune: { tokens: 'reachable' }` to stop asserting.");
2646
+ _bamboocss_logger.logger.warn("tokens:unresolved", bounded ? where + "`prune.keepTokens` covers them: they keep what it names rather than every declaration in the theme. Nothing checks that they stay inside it, which is why it is yours to declare — a read landing outside the patterns loses its declaration and resolves to a `var()` with nothing behind it. Respell what you can, and widen the patterns for what you cannot." : where + "`prune.tokens: 'accounted'` asserts that every token path resolves at build time. Spell the path as a string literal at the call, give a template a static prefix so it can be bounded, name the category they land in with `prune: { keepTokens: ['colors.*'] }`, or set `prune: { tokens: 'reachable' }` to stop asserting.");
2584
2647
  }
2585
- if (reported.length && unresolved !== "off") _bamboocss_logger.logger.warn("tokens:unresolved", `${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.`);
2586
- ctx.pruneTokens(sheet, vars, accounting.declined.length > 0 && reachable);
2648
+ if (reported.length && unresolved !== "off") _bamboocss_logger.logger.warn("tokens:unresolved", `${reported.length} reference(s) could not be accounted for, so ` + (bounded ? `\`prune.keepTokens\` decides what they keep` : `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()\`. ` + (bounded ? "Nothing checks that they stay inside `keepTokens`, which is why it is yours to declare: a read landing outside it loses its declaration. Narrow `include`, or widen the patterns." : "Narrow `include`, name the categories they reach with `prune: { keepTokens: [...] }`, or accept the keeps."));
2649
+ ctx.pruneTokens(sheet, vars, !bounded && accounting.declined.length > 0 && reachable);
2650
+ }
2651
+ /**
2652
+ * The dash-cased spelling of a token path, as it appears in the emitted css variable.
2653
+ *
2654
+ * Not a transform this applies — only one it recognises, to tell a user their pattern is
2655
+ * written against the wrong side of the system. The paths are camelCase (`fontSizes.3xl`) and
2656
+ * the variables are dash-cased (`--font-sizes-3xl`), so `font-sizes.*` is the natural thing to
2657
+ * write after reading `styles.css` and it matches nothing at all.
2658
+ */
2659
+ const dashed = (path) => path.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`);
2660
+ /**
2661
+ * The token names `prune.keepTokens` names, matched against the whole theme.
2662
+ *
2663
+ * Patterns are anchored globs over the dotted token *path* — `colors.*`, `colors.brand.*`,
2664
+ * `!colors.legacy.*`, or a bare path for one token. Matched case-sensitively, because a path is
2665
+ * a key in the config rather than free text.
2666
+ *
2667
+ * A pattern that matches nothing is reported rather than ignored. It is nearly always a typo
2668
+ * for one that would have matched, and the failure it causes is the one this whole module is
2669
+ * careful about everywhere else: a declaration dropped while something still asks for it, with
2670
+ * no error and no warning, resolving to a `var()` that inherits instead of falling back.
2671
+ */
2672
+ function declaredKeeps(ctx) {
2673
+ const patterns = ctx.config.prune?.keepTokens;
2674
+ if (!patterns?.length) return [];
2675
+ const includes = patterns.filter((pattern) => !pattern.startsWith("!"));
2676
+ if (!includes.length) _bamboocss_logger.logger.warn("prune:tokens", `\`prune.keepTokens\` holds only exclusions, so it keeps every token they do not name:\n\n${patterns.map((pattern) => ` ${pattern}`).join("\n")}\n\nA leading \`!\` subtracts from a selection and there is none here. Add the categories to keep — \`['colors.*', '!colors.legacy.*']\` — or use \`prune: { tokens: 'off' }\` if keeping everything is the intent.`);
2677
+ const matched = [];
2678
+ const used = /* @__PURE__ */ new Set();
2679
+ for (const token of ctx.tokens.allTokens) {
2680
+ if ((0, matcher.isMatch)(token.name, patterns, { caseSensitive: true })) matched.push(token.name);
2681
+ if (used.size === includes.length) continue;
2682
+ for (const pattern of includes) if ((0, matcher.isMatch)(token.name, pattern, { caseSensitive: true })) used.add(pattern);
2683
+ }
2684
+ const unused = includes.filter((pattern) => !used.has(pattern));
2685
+ if (unused.length) {
2686
+ const paths = ctx.tokens.allTokens.map((token) => token.name);
2687
+ const respell = unused.map((pattern) => {
2688
+ const hit = paths.find((path) => (0, matcher.isMatch)(dashed(path), pattern, { caseSensitive: true }));
2689
+ if (!hit) return ` ${pattern}`;
2690
+ return ` ${pattern} — matches \`${dashed(hit)}\`, which is the css variable's spelling. Write the token path: \`${hit.split(".")[0]}.*\``;
2691
+ }).join("\n");
2692
+ _bamboocss_logger.logger.warn("prune:tokens", `${unused.length} \`prune.keepTokens\` pattern(s) match no token in this theme:\n\n${respell}\n\nA pattern is an anchored glob over the dotted token *path* — \`colors.*\`, not \`colors\`, and \`fontSizes.*\` rather than the \`--font-sizes-\` spelling the css variable uses. One that matches nothing keeps nothing, which is silent everywhere except here.`);
2693
+ }
2694
+ return matched;
2587
2695
  }
2588
2696
  /** The custom properties a set of token paths resolves to. */
2589
2697
  function tokenVarsFor(ctx, paths) {
@@ -2646,7 +2754,7 @@ const keyframeNames = (ctx) => Object.keys(ctx.config.theme?.keyframes ?? {});
2646
2754
  *
2647
2755
  * Lowercase-initial only, so a JSX component (`<Button />`) is not mistaken for an element.
2648
2756
  * That cuts the other way too — a component rendering `<button>` inside a dependency is
2649
- * invisible here, which is why `prune.preflight` is opt-in.
2757
+ * invisible here, which is why `preflight.prune` is opt-in.
2650
2758
  *
2651
2759
  * The commoner blind spot is nearer than a dependency: this reads `include`, and `include`
2652
2760
  * conventionally covers components rather than markup. An entry template — `index.html`,
@@ -2802,16 +2910,17 @@ var Builder = class {
2802
2910
  return parserResult;
2803
2911
  };
2804
2912
  extract = () => {
2913
+ const ctx = this.getContextOrThrow();
2805
2914
  const hasConfigChanged = this.affecteds ? this.affecteds.hasConfigChanged : true;
2806
2915
  if (!this.filesMeta && !hasConfigChanged) {
2807
2916
  _bamboocss_logger.logger.debug("builder", "No files or config changed, skipping extract");
2808
- return;
2917
+ return ctx.assertExtracted();
2809
2918
  }
2810
- const ctx = this.getContextOrThrow();
2811
2919
  const files = ctx.getFiles();
2812
2920
  const done = _bamboocss_logger.logger.time.info("Extracted in");
2813
2921
  files.map((file) => this.extractFile(ctx, file));
2814
2922
  done();
2923
+ ctx.assertExtracted(files);
2815
2924
  };
2816
2925
  isValidRoot = (root) => {
2817
2926
  const ctx = this.getContextOrThrow();
@@ -2849,7 +2958,7 @@ var Builder = class {
2849
2958
  if (layerParams) ctx.appendLayerParams(sheet);
2850
2959
  ctx.appendBaselineCss(sheet);
2851
2960
  pruneTokensForBuild(ctx, sheet, []);
2852
- if (ctx.config.prune?.preflight) ctx.prunePreflight(sheet, collectRenderedElements(ctx));
2961
+ if ((0, _bamboocss_core.prunesPreflight)(ctx.config.preflight)) ctx.prunePreflight(sheet, collectRenderedElements(ctx));
2853
2962
  if (ctx.config.prune?.keyframes) ctx.pruneKeyframes(sheet, collectKeyframeReferences(ctx, keyframeNames(ctx)));
2854
2963
  return ctx.getCss(sheet);
2855
2964
  };
@@ -2933,12 +3042,12 @@ const startProfiling = async (cwd, prefix, isWatching) => {
2933
3042
  //#endregion
2934
3043
  //#region src/cssgen.ts
2935
3044
  const cssgen = async (ctx, options) => {
2936
- const { outfile, type, minimal, splitting } = options;
3045
+ const { outfile, type, splitting } = options;
2937
3046
  const sheet = ctx.createSheet();
2938
3047
  if (type) {
2939
3048
  const done = _bamboocss_logger.logger.time.info(ctx.messages.cssArtifactComplete(type));
2940
3049
  ctx.appendCssOfType(type, sheet);
2941
- if (type === "preflight" && ctx.config.prune?.preflight) ctx.prunePreflight(sheet, collectRenderedElements(ctx));
3050
+ if (type === "preflight" && (0, _bamboocss_core.prunesPreflight)(ctx.config.preflight)) ctx.prunePreflight(sheet, collectRenderedElements(ctx));
2942
3051
  if (outfile) {
2943
3052
  const css = ctx.getCss(sheet);
2944
3053
  _bamboocss_logger.logger.info("css", ctx.runtime.path.resolve(outfile));
@@ -2948,14 +3057,12 @@ const cssgen = async (ctx, options) => {
2948
3057
  } else {
2949
3058
  const { files, results } = ctx.parseFiles();
2950
3059
  const done = _bamboocss_logger.logger.time.info(ctx.messages.buildComplete(files.length));
2951
- if (!minimal) {
2952
- ctx.appendLayerParams(sheet);
2953
- ctx.appendBaselineCss(sheet);
2954
- }
3060
+ ctx.appendLayerParams(sheet);
3061
+ ctx.appendBaselineCss(sheet);
2955
3062
  ctx.appendParserCss(sheet);
2956
- if (!minimal) pruneTokensForBuild(ctx, sheet, results);
2957
- if (!minimal && ctx.config.prune?.preflight) ctx.prunePreflight(sheet, collectRenderedElements(ctx));
2958
- if (!minimal && ctx.config.prune?.keyframes) ctx.pruneKeyframes(sheet, collectKeyframeReferences(ctx, keyframeNames(ctx)));
3063
+ pruneTokensForBuild(ctx, sheet, results);
3064
+ if ((0, _bamboocss_core.prunesPreflight)(ctx.config.preflight)) ctx.prunePreflight(sheet, collectRenderedElements(ctx));
3065
+ if (ctx.config.prune?.keyframes) ctx.pruneKeyframes(sheet, collectKeyframeReferences(ctx, keyframeNames(ctx)));
2959
3066
  if (splitting) await ctx.writeSplitCss(sheet);
2960
3067
  else if (outfile) {
2961
3068
  const css = ctx.getCss(sheet);
@@ -3026,7 +3133,7 @@ async function build(ctx, artifactIds) {
3026
3133
  const parsed = ctx.parseFiles();
3027
3134
  ctx.appendParserCss(sheet);
3028
3135
  pruneTokensForBuild(ctx, sheet, parsed.results);
3029
- if (ctx.config.prune?.preflight) ctx.prunePreflight(sheet, collectRenderedElements(ctx));
3136
+ if ((0, _bamboocss_core.prunesPreflight)(ctx.config.preflight)) ctx.prunePreflight(sheet, collectRenderedElements(ctx));
3030
3137
  if (ctx.config.prune?.keyframes) ctx.pruneKeyframes(sheet, collectKeyframeReferences(ctx, keyframeNames(ctx)));
3031
3138
  await ctx.writeCss(sheet);
3032
3139
  done(ctx.messages.buildComplete(parsed.files.length));
@@ -3072,7 +3179,7 @@ async function generate(config, configPath) {
3072
3179
  ctx.appendBaselineCss(sheet);
3073
3180
  ctx.appendParserCss(sheet);
3074
3181
  pruneTokensForBuild(ctx, sheet, []);
3075
- if (ctx.config.prune?.preflight) ctx.prunePreflight(sheet, collectRenderedElements(ctx));
3182
+ if ((0, _bamboocss_core.prunesPreflight)(ctx.config.preflight)) ctx.prunePreflight(sheet, collectRenderedElements(ctx));
3076
3183
  if (ctx.config.prune?.keyframes) ctx.pruneKeyframes(sheet, collectKeyframeReferences(ctx, keyframeNames(ctx)));
3077
3184
  const css = ctx.getCss(sheet);
3078
3185
  await ctx.runtime.fs.writeFile(outfile, css);
@@ -3174,10 +3281,10 @@ export default defineConfig({
3174
3281
  exclude: [],
3175
3282
 
3176
3283
  // Tokens, keyframes and @property rules nothing in the emitted css reaches are dropped
3177
- // by default — worth 36-78% of a new project's stylesheet. Set \`prune: { tokens: false }\`
3178
- // if you read tokens from somewhere the build cannot see them — \`token()\` with a
3179
- // computed path, or a hand-written stylesheet outside \`include\` — or list those under
3180
- // \`staticCss\` to keep them.
3284
+ // by default — worth 36-78% of a new project's stylesheet. If you read tokens from
3285
+ // somewhere the build cannot see them — \`token()\` with a computed path, or a
3286
+ // hand-written stylesheet outside \`include\` — name the categories they land in with
3287
+ // \`prune: { keepTokens: ['colors.*'] }\`, or set \`prune: { tokens: 'off' }\`.
3181
3288
 
3182
3289
  // Useful for theme customization
3183
3290
  theme: {
package/dist/index.d.cts CHANGED
@@ -51,6 +51,26 @@ declare class BambooContext extends Generator {
51
51
  output: OutputEngine;
52
52
  diff: DiffEngine;
53
53
  explicitDeps: string[];
54
+ /**
55
+ * Files whose extraction threw, keyed by path, holding what it threw.
56
+ *
57
+ * A parse failure is not an opinion about a build that still works. The file's styles never
58
+ * reach the encoder, so every rule it would have contributed is absent from the stylesheet
59
+ * and the classes its components ask for have nothing behind them — the same shape as a
60
+ * naming disagreement, and the reverse of `reportUnresolvedStyles`, where what the build
61
+ * *did* see still applies. Logging it and carrying on is how a build printed error-level
62
+ * lines, dropped rules, and exited 0.
63
+ *
64
+ * Retained rather than rethrown from the `catch`, so one pass names every broken file
65
+ * instead of the first. Keyed by file, so a failure survives the incremental passes that
66
+ * skip an unchanged file: nothing re-parses it, and its styles stay missing until it does.
67
+ *
68
+ * The error rather than its message, so `assertExtracted` can hand the originals on as a
69
+ * `cause`. The aggregate carries a code of its own — `ERR_BAMBOO_EXTRACT_FAILED` — and the
70
+ * codes underneath it are what a caller has to read to tell a retired token spelling from a
71
+ * syntax error.
72
+ */
73
+ parseFailures: Map<string, unknown>;
54
74
  constructor(conf: LoadConfigResult);
55
75
  /**
56
76
  * Report `css()` calls whose styles the build could not fully see.
@@ -65,7 +85,36 @@ declare class BambooContext extends Generator {
65
85
  private getExplicitDependencies;
66
86
  initMessage: () => string;
67
87
  getFiles: () => string[];
88
+ /**
89
+ * Fail the build if any file's extraction threw.
90
+ *
91
+ * Called at the end of an extraction pass rather than from the `catch`, so the message names
92
+ * every broken file at once — a config with one retired token spelling in six components is
93
+ * fixed once, not six builds in a row.
94
+ *
95
+ * This is what makes the integrations agree. `cssgen` already exited non-zero on a file it
96
+ * could not extract, by letting the throw through; every bundler goes through `parseFile`,
97
+ * which caught it. CI running a build passed what CI running `cssgen` rejected, over the same
98
+ * source.
99
+ *
100
+ * `files` is the set still in scope, which the caller has usually just globbed. Deleting the
101
+ * offending file, or taking it out of `include`, is a *fix* — and nothing re-parses a file
102
+ * that is gone, so the entry that outlived it would fail every later build, naming a path
103
+ * that no longer exists. A context outlives rebuilds (it is replaced only when the config
104
+ * changes) and both long-lived integrations hold one, so that wedged a dev server until the
105
+ * process was restarted.
106
+ */
107
+ assertExtracted: (files?: Iterable<string>) => void;
108
+ /** A path as the user typed it, when it is under `cwd`. */
109
+ private relative;
68
110
  parseFile: (filePath: string, styleEncoder?: StyleEncoder) => ParserResult | undefined;
111
+ /**
112
+ * Extract every file in one pass, and fail on the ones that could not be read.
113
+ *
114
+ * Routed through `parseFile` rather than parsing directly, so the two entry points cannot
115
+ * disagree about what a failure means. This one used to let the first throw out, which is
116
+ * why `cssgen` and a bundler build reported different things about the same source.
117
+ */
69
118
  parseFiles: (styleEncoder?: StyleEncoder) => {
70
119
  filesWithCss: string[];
71
120
  files: string[];
@@ -180,7 +229,6 @@ interface CssGenOptions {
180
229
  cwd: string;
181
230
  outfile?: string;
182
231
  type?: CssArtifactType;
183
- minimal?: boolean;
184
232
  splitting?: boolean;
185
233
  }
186
234
  declare const cssgen: (ctx: BambooContext, options: CssGenOptions) => Promise<void>;
package/dist/index.d.mts CHANGED
@@ -51,6 +51,26 @@ declare class BambooContext extends Generator {
51
51
  output: OutputEngine;
52
52
  diff: DiffEngine;
53
53
  explicitDeps: string[];
54
+ /**
55
+ * Files whose extraction threw, keyed by path, holding what it threw.
56
+ *
57
+ * A parse failure is not an opinion about a build that still works. The file's styles never
58
+ * reach the encoder, so every rule it would have contributed is absent from the stylesheet
59
+ * and the classes its components ask for have nothing behind them — the same shape as a
60
+ * naming disagreement, and the reverse of `reportUnresolvedStyles`, where what the build
61
+ * *did* see still applies. Logging it and carrying on is how a build printed error-level
62
+ * lines, dropped rules, and exited 0.
63
+ *
64
+ * Retained rather than rethrown from the `catch`, so one pass names every broken file
65
+ * instead of the first. Keyed by file, so a failure survives the incremental passes that
66
+ * skip an unchanged file: nothing re-parses it, and its styles stay missing until it does.
67
+ *
68
+ * The error rather than its message, so `assertExtracted` can hand the originals on as a
69
+ * `cause`. The aggregate carries a code of its own — `ERR_BAMBOO_EXTRACT_FAILED` — and the
70
+ * codes underneath it are what a caller has to read to tell a retired token spelling from a
71
+ * syntax error.
72
+ */
73
+ parseFailures: Map<string, unknown>;
54
74
  constructor(conf: LoadConfigResult);
55
75
  /**
56
76
  * Report `css()` calls whose styles the build could not fully see.
@@ -65,7 +85,36 @@ declare class BambooContext extends Generator {
65
85
  private getExplicitDependencies;
66
86
  initMessage: () => string;
67
87
  getFiles: () => string[];
88
+ /**
89
+ * Fail the build if any file's extraction threw.
90
+ *
91
+ * Called at the end of an extraction pass rather than from the `catch`, so the message names
92
+ * every broken file at once — a config with one retired token spelling in six components is
93
+ * fixed once, not six builds in a row.
94
+ *
95
+ * This is what makes the integrations agree. `cssgen` already exited non-zero on a file it
96
+ * could not extract, by letting the throw through; every bundler goes through `parseFile`,
97
+ * which caught it. CI running a build passed what CI running `cssgen` rejected, over the same
98
+ * source.
99
+ *
100
+ * `files` is the set still in scope, which the caller has usually just globbed. Deleting the
101
+ * offending file, or taking it out of `include`, is a *fix* — and nothing re-parses a file
102
+ * that is gone, so the entry that outlived it would fail every later build, naming a path
103
+ * that no longer exists. A context outlives rebuilds (it is replaced only when the config
104
+ * changes) and both long-lived integrations hold one, so that wedged a dev server until the
105
+ * process was restarted.
106
+ */
107
+ assertExtracted: (files?: Iterable<string>) => void;
108
+ /** A path as the user typed it, when it is under `cwd`. */
109
+ private relative;
68
110
  parseFile: (filePath: string, styleEncoder?: StyleEncoder) => ParserResult | undefined;
111
+ /**
112
+ * Extract every file in one pass, and fail on the ones that could not be read.
113
+ *
114
+ * Routed through `parseFile` rather than parsing directly, so the two entry points cannot
115
+ * disagree about what a failure means. This one used to let the first throw out, which is
116
+ * why `cssgen` and a bundler build reported different things about the same source.
117
+ */
69
118
  parseFiles: (styleEncoder?: StyleEncoder) => {
70
119
  filesWithCss: string[];
71
120
  files: string[];
@@ -180,7 +229,6 @@ interface CssGenOptions {
180
229
  cwd: string;
181
230
  outfile?: string;
182
231
  type?: CssArtifactType;
183
- minimal?: boolean;
184
232
  splitting?: boolean;
185
233
  }
186
234
  declare const cssgen: (ctx: BambooContext, options: CssGenOptions) => Promise<void>;
package/dist/index.mjs CHANGED
@@ -1,12 +1,12 @@
1
1
  import { Reporter, formatRecipeReport, formatTokenReport } from "@bamboocss/reporter";
2
2
  import { colors, logger, quote } from "@bamboocss/logger";
3
3
  import { convertTsPathsToRegexes, diffConfigs, findConfig, getConfigDependencies, loadConfig, mergeHooks } from "@bamboocss/config";
4
+ import { checkNamingAgreement, formatNamingDisagreement, messages, prunesPreflight } from "@bamboocss/core";
4
5
  import { BambooError, cssVarRefs, uniq } from "@bamboocss/shared";
5
6
  import { appendFileSync, existsSync, readFileSync, statSync, writeFileSync } from "fs";
6
7
  import { dirname, extname, isAbsolute, join, normalize, parse, relative, resolve, sep } from "path";
7
8
  import { pluginSvelte } from "@bamboocss/plugin-svelte";
8
9
  import { pluginVue } from "@bamboocss/plugin-vue";
9
- import { checkNamingAgreement, formatNamingDisagreement, messages } from "@bamboocss/core";
10
10
  import { Generator, generatePackageExports } from "@bamboocss/generator";
11
11
  import { Project } from "@bamboocss/parser";
12
12
  import { debounce } from "perfect-debounce";
@@ -21,6 +21,7 @@ import path from "node:path";
21
21
  import fs, { promises } from "node:fs";
22
22
  import isGlob from "is-glob";
23
23
  import globParent from "glob-parent";
24
+ import { isMatch } from "matcher";
24
25
  import { resolveTsPathPattern } from "@bamboocss/config/ts-path";
25
26
  import { Node, SyntaxKind } from "ts-morph";
26
27
  import readline from "node:readline";
@@ -1596,6 +1597,8 @@ var OutputEngine = class {
1596
1597
  };
1597
1598
  //#endregion
1598
1599
  //#region src/create-context.ts
1600
+ /** A thrown value's message, for a `catch` binding that is typed `unknown`. */
1601
+ const messageOf = (error) => error instanceof Error ? error.message : String(error);
1599
1602
  /**
1600
1603
  * What each loss is, and what the author can do about it.
1601
1604
  *
@@ -1616,6 +1619,26 @@ var BambooContext = class extends Generator {
1616
1619
  output;
1617
1620
  diff;
1618
1621
  explicitDeps = [];
1622
+ /**
1623
+ * Files whose extraction threw, keyed by path, holding what it threw.
1624
+ *
1625
+ * A parse failure is not an opinion about a build that still works. The file's styles never
1626
+ * reach the encoder, so every rule it would have contributed is absent from the stylesheet
1627
+ * and the classes its components ask for have nothing behind them — the same shape as a
1628
+ * naming disagreement, and the reverse of `reportUnresolvedStyles`, where what the build
1629
+ * *did* see still applies. Logging it and carrying on is how a build printed error-level
1630
+ * lines, dropped rules, and exited 0.
1631
+ *
1632
+ * Retained rather than rethrown from the `catch`, so one pass names every broken file
1633
+ * instead of the first. Keyed by file, so a failure survives the incremental passes that
1634
+ * skip an unchanged file: nothing re-parses it, and its styles stay missing until it does.
1635
+ *
1636
+ * The error rather than its message, so `assertExtracted` can hand the originals on as a
1637
+ * `cause`. The aggregate carries a code of its own — `ERR_BAMBOO_EXTRACT_FAILED` — and the
1638
+ * codes underneath it are what a caller has to read to tell a retired token spelling from a
1639
+ * syntax error.
1640
+ */
1641
+ parseFailures = /* @__PURE__ */ new Map();
1619
1642
  constructor(conf) {
1620
1643
  super(conf);
1621
1644
  const config = conf.config;
@@ -1685,6 +1708,35 @@ var BambooContext = class extends Generator {
1685
1708
  cwd
1686
1709
  });
1687
1710
  };
1711
+ /**
1712
+ * Fail the build if any file's extraction threw.
1713
+ *
1714
+ * Called at the end of an extraction pass rather than from the `catch`, so the message names
1715
+ * every broken file at once — a config with one retired token spelling in six components is
1716
+ * fixed once, not six builds in a row.
1717
+ *
1718
+ * This is what makes the integrations agree. `cssgen` already exited non-zero on a file it
1719
+ * could not extract, by letting the throw through; every bundler goes through `parseFile`,
1720
+ * which caught it. CI running a build passed what CI running `cssgen` rejected, over the same
1721
+ * source.
1722
+ *
1723
+ * `files` is the set still in scope, which the caller has usually just globbed. Deleting the
1724
+ * offending file, or taking it out of `include`, is a *fix* — and nothing re-parses a file
1725
+ * that is gone, so the entry that outlived it would fail every later build, naming a path
1726
+ * that no longer exists. A context outlives rebuilds (it is replaced only when the config
1727
+ * changes) and both long-lived integrations hold one, so that wedged a dev server until the
1728
+ * process was restarted.
1729
+ */
1730
+ assertExtracted = (files) => {
1731
+ if (!this.parseFailures.size) return;
1732
+ const inScope = new Set(Array.from(files ?? this.getFiles(), (file) => this.runtime.path.abs(this.config.cwd, file)));
1733
+ for (const file of this.parseFailures.keys()) if (!inScope.has(file)) this.parseFailures.delete(file);
1734
+ if (!this.parseFailures.size) return;
1735
+ const detail = Array.from(this.parseFailures.entries()).map(([file, error]) => `${this.relative(file)}\n${messageOf(error).replace(/^(?=.)/gm, " ")}`).join("\n\n");
1736
+ throw new BambooError("EXTRACT_FAILED", `${this.parseFailures.size} file(s) could not be extracted:\n\n${detail}\n\nNothing emits a rule for a file the build could not read, so every style in these is absent from the stylesheet and the classes their components ask for have nothing behind them.`, { cause: new AggregateError(Array.from(this.parseFailures.values()), `${this.parseFailures.size} file(s) could not be extracted`) });
1737
+ };
1738
+ /** A path as the user typed it, when it is under `cwd`. */
1739
+ relative = (file) => file.startsWith(this.config.cwd) ? file.slice(this.config.cwd.length + 1) : file;
1688
1740
  parseFile = (filePath, styleEncoder) => {
1689
1741
  const file = this.runtime.path.abs(this.config.cwd, filePath);
1690
1742
  logger.debug("file:extract", file);
@@ -1693,27 +1745,34 @@ var BambooContext = class extends Generator {
1693
1745
  try {
1694
1746
  const encoder = styleEncoder || this.parserOptions.encoder;
1695
1747
  result = this.project.parseSourceFile(file, encoder);
1748
+ this.parseFailures.delete(file);
1696
1749
  } catch (error) {
1697
1750
  logger.caughtError("file:extract", `Failed to parse ${file}`, error);
1751
+ this.parseFailures.set(file, error);
1698
1752
  }
1699
1753
  if (result) this.reportUnresolvedStyles(result);
1700
1754
  measure();
1701
1755
  return result;
1702
1756
  };
1757
+ /**
1758
+ * Extract every file in one pass, and fail on the ones that could not be read.
1759
+ *
1760
+ * Routed through `parseFile` rather than parsing directly, so the two entry points cannot
1761
+ * disagree about what a failure means. This one used to let the first throw out, which is
1762
+ * why `cssgen` and a bundler build reported different things about the same source.
1763
+ */
1703
1764
  parseFiles = (styleEncoder) => {
1704
1765
  const encoder = styleEncoder || this.parserOptions.encoder;
1705
1766
  const files = this.getFiles();
1706
1767
  const filesWithCss = [];
1707
1768
  const results = [];
1708
1769
  files.forEach((file) => {
1709
- const measure = logger.time.debug(`Parsed ${file}`);
1710
- const result = this.project.parseSourceFile(file, encoder);
1711
- measure();
1712
- if (result) this.reportUnresolvedStyles(result);
1770
+ const result = this.parseFile(file, encoder);
1713
1771
  if (!result || result.isEmpty() || encoder.isEmpty()) return;
1714
1772
  filesWithCss.push(file);
1715
1773
  results.push(result);
1716
1774
  });
1775
+ this.assertExtracted(files);
1717
1776
  return {
1718
1777
  filesWithCss,
1719
1778
  files,
@@ -2514,7 +2573,7 @@ function* sourceTexts(ctx) {
2514
2573
  * The token prune, as all three build paths need to run it.
2515
2574
  *
2516
2575
  * One function because it was three copies of one conditional, and the `false` branch went
2517
- * missing from a copy: a watch rebuild with `prune: { tokens: false }` skipped `pruneTokens`
2576
+ * missing from a copy: a watch rebuild with `prune: { tokens: 'off' }` skipped `pruneTokens`
2518
2577
  * altogether, so it kept `@property` registrations that a full build of the same source
2519
2578
  * strips. The other two copies carried a comment pointing at that file for the reasoning,
2520
2579
  * which is how a missing branch reads as intentional.
@@ -2550,12 +2609,15 @@ function pruneTokensForBuild(ctx, sheet, results) {
2550
2609
  if (accounts) accountSnapshot(ctx, snapshot, accounting);
2551
2610
  }
2552
2611
  for (const name of tokenVarsFor(ctx, paths)) vars.add(name);
2612
+ const declared = declaredKeeps(ctx);
2613
+ for (const name of tokenVarsFor(ctx, declared)) vars.add(name);
2553
2614
  if (!accounts) {
2554
2615
  ctx.pruneTokens(sheet, vars, reachable);
2555
2616
  return;
2556
2617
  }
2557
2618
  for (const name of tokenVarsFor(ctx, accounting.paths)) vars.add(name);
2558
- if (accounting.prefixes.size && !accounting.declined.length) {
2619
+ const bounded = (ctx.config.prune?.keepTokens?.length ?? 0) > 0;
2620
+ if (accounting.prefixes.size && (bounded || !accounting.declined.length)) {
2559
2621
  const prefixes = Array.from(accounting.prefixes);
2560
2622
  const matched = [];
2561
2623
  for (const token of ctx.tokens.allTokens) if (prefixes.some((prefix) => token.name.startsWith(prefix))) matched.push(token.name);
@@ -2563,13 +2625,59 @@ function pruneTokensForBuild(ctx, sheet, results) {
2563
2625
  }
2564
2626
  const failing = accounting.declined.filter(failsStrict);
2565
2627
  const reported = accounting.declined.filter((entry) => !failsStrict(entry));
2566
- if (failing.length) {
2567
- const message = `${failing.length} token reference(s) could not be resolved.\n\n${formatDeclined(ctx, failing)}\n\n\`prune.tokens: 'accounted'\` asserts that every token path resolves at build time. 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\`, set \`prune: { unresolvedPath: 'warn' }\` to keep the assertion without failing, or \`prune: { tokens: 'reachable' }\` to stop asserting.`;
2568
- if (unresolved === "error") throw new BambooError("TOKEN_REFERENCE_UNRESOLVED", message);
2569
- logger.warn("tokens:unresolved", message);
2628
+ if (bounded && unresolved === "error" && accounting.declined.length) throw new BambooError("TOKEN_REFERENCE_UNRESOLVED", `${accounting.declined.length} token reference(s) could not be accounted for.\n\n${formatDeclined(ctx, accounting.declined)}\n\n\`prune.unresolvedPath: 'error'\` asserts that every token path resolves at build time, and \`prune.keepTokens\` declares where the ones that do not will land. Those are contradictory, so one has to go: drop \`keepTokens\` and respell the paths, or set \`prune: { unresolvedPath: 'warn' }\` and let the keeps cover them.`);
2629
+ if (failing.length && unresolved !== "off") {
2630
+ const where = `${failing.length} token reference(s) could not be resolved.\n\n${formatDeclined(ctx, failing)}\n\n`;
2631
+ if (unresolved === "error") throw new BambooError("TOKEN_REFERENCE_UNRESOLVED", where + "`prune.tokens: 'accounted'` asserts that every token path resolves at build time. Spell the path as a string literal at the call, give a template a static prefix so it can be bounded, name the category they land in with `prune: { keepTokens: ['colors.*'] }` and drop to `prune: { unresolvedPath: 'warn' }`, or set `prune: { tokens: 'reachable' }` to stop asserting.");
2632
+ logger.warn("tokens:unresolved", bounded ? where + "`prune.keepTokens` covers them: they keep what it names rather than every declaration in the theme. Nothing checks that they stay inside it, which is why it is yours to declare — a read landing outside the patterns loses its declaration and resolves to a `var()` with nothing behind it. Respell what you can, and widen the patterns for what you cannot." : where + "`prune.tokens: 'accounted'` asserts that every token path resolves at build time. Spell the path as a string literal at the call, give a template a static prefix so it can be bounded, name the category they land in with `prune: { keepTokens: ['colors.*'] }`, or set `prune: { tokens: 'reachable' }` to stop asserting.");
2570
2633
  }
2571
- if (reported.length && unresolved !== "off") logger.warn("tokens:unresolved", `${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.`);
2572
- ctx.pruneTokens(sheet, vars, accounting.declined.length > 0 && reachable);
2634
+ if (reported.length && unresolved !== "off") logger.warn("tokens:unresolved", `${reported.length} reference(s) could not be accounted for, so ` + (bounded ? `\`prune.keepTokens\` decides what they keep` : `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()\`. ` + (bounded ? "Nothing checks that they stay inside `keepTokens`, which is why it is yours to declare: a read landing outside it loses its declaration. Narrow `include`, or widen the patterns." : "Narrow `include`, name the categories they reach with `prune: { keepTokens: [...] }`, or accept the keeps."));
2635
+ ctx.pruneTokens(sheet, vars, !bounded && accounting.declined.length > 0 && reachable);
2636
+ }
2637
+ /**
2638
+ * The dash-cased spelling of a token path, as it appears in the emitted css variable.
2639
+ *
2640
+ * Not a transform this applies — only one it recognises, to tell a user their pattern is
2641
+ * written against the wrong side of the system. The paths are camelCase (`fontSizes.3xl`) and
2642
+ * the variables are dash-cased (`--font-sizes-3xl`), so `font-sizes.*` is the natural thing to
2643
+ * write after reading `styles.css` and it matches nothing at all.
2644
+ */
2645
+ const dashed = (path) => path.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`);
2646
+ /**
2647
+ * The token names `prune.keepTokens` names, matched against the whole theme.
2648
+ *
2649
+ * Patterns are anchored globs over the dotted token *path* — `colors.*`, `colors.brand.*`,
2650
+ * `!colors.legacy.*`, or a bare path for one token. Matched case-sensitively, because a path is
2651
+ * a key in the config rather than free text.
2652
+ *
2653
+ * A pattern that matches nothing is reported rather than ignored. It is nearly always a typo
2654
+ * for one that would have matched, and the failure it causes is the one this whole module is
2655
+ * careful about everywhere else: a declaration dropped while something still asks for it, with
2656
+ * no error and no warning, resolving to a `var()` that inherits instead of falling back.
2657
+ */
2658
+ function declaredKeeps(ctx) {
2659
+ const patterns = ctx.config.prune?.keepTokens;
2660
+ if (!patterns?.length) return [];
2661
+ const includes = patterns.filter((pattern) => !pattern.startsWith("!"));
2662
+ if (!includes.length) logger.warn("prune:tokens", `\`prune.keepTokens\` holds only exclusions, so it keeps every token they do not name:\n\n${patterns.map((pattern) => ` ${pattern}`).join("\n")}\n\nA leading \`!\` subtracts from a selection and there is none here. Add the categories to keep — \`['colors.*', '!colors.legacy.*']\` — or use \`prune: { tokens: 'off' }\` if keeping everything is the intent.`);
2663
+ const matched = [];
2664
+ const used = /* @__PURE__ */ new Set();
2665
+ for (const token of ctx.tokens.allTokens) {
2666
+ if (isMatch(token.name, patterns, { caseSensitive: true })) matched.push(token.name);
2667
+ if (used.size === includes.length) continue;
2668
+ for (const pattern of includes) if (isMatch(token.name, pattern, { caseSensitive: true })) used.add(pattern);
2669
+ }
2670
+ const unused = includes.filter((pattern) => !used.has(pattern));
2671
+ if (unused.length) {
2672
+ const paths = ctx.tokens.allTokens.map((token) => token.name);
2673
+ const respell = unused.map((pattern) => {
2674
+ const hit = paths.find((path) => isMatch(dashed(path), pattern, { caseSensitive: true }));
2675
+ if (!hit) return ` ${pattern}`;
2676
+ return ` ${pattern} — matches \`${dashed(hit)}\`, which is the css variable's spelling. Write the token path: \`${hit.split(".")[0]}.*\``;
2677
+ }).join("\n");
2678
+ logger.warn("prune:tokens", `${unused.length} \`prune.keepTokens\` pattern(s) match no token in this theme:\n\n${respell}\n\nA pattern is an anchored glob over the dotted token *path* — \`colors.*\`, not \`colors\`, and \`fontSizes.*\` rather than the \`--font-sizes-\` spelling the css variable uses. One that matches nothing keeps nothing, which is silent everywhere except here.`);
2679
+ }
2680
+ return matched;
2573
2681
  }
2574
2682
  /** The custom properties a set of token paths resolves to. */
2575
2683
  function tokenVarsFor(ctx, paths) {
@@ -2632,7 +2740,7 @@ const keyframeNames = (ctx) => Object.keys(ctx.config.theme?.keyframes ?? {});
2632
2740
  *
2633
2741
  * Lowercase-initial only, so a JSX component (`<Button />`) is not mistaken for an element.
2634
2742
  * That cuts the other way too — a component rendering `<button>` inside a dependency is
2635
- * invisible here, which is why `prune.preflight` is opt-in.
2743
+ * invisible here, which is why `preflight.prune` is opt-in.
2636
2744
  *
2637
2745
  * The commoner blind spot is nearer than a dependency: this reads `include`, and `include`
2638
2746
  * conventionally covers components rather than markup. An entry template — `index.html`,
@@ -2788,16 +2896,17 @@ var Builder = class {
2788
2896
  return parserResult;
2789
2897
  };
2790
2898
  extract = () => {
2899
+ const ctx = this.getContextOrThrow();
2791
2900
  const hasConfigChanged = this.affecteds ? this.affecteds.hasConfigChanged : true;
2792
2901
  if (!this.filesMeta && !hasConfigChanged) {
2793
2902
  logger.debug("builder", "No files or config changed, skipping extract");
2794
- return;
2903
+ return ctx.assertExtracted();
2795
2904
  }
2796
- const ctx = this.getContextOrThrow();
2797
2905
  const files = ctx.getFiles();
2798
2906
  const done = logger.time.info("Extracted in");
2799
2907
  files.map((file) => this.extractFile(ctx, file));
2800
2908
  done();
2909
+ ctx.assertExtracted(files);
2801
2910
  };
2802
2911
  isValidRoot = (root) => {
2803
2912
  const ctx = this.getContextOrThrow();
@@ -2835,7 +2944,7 @@ var Builder = class {
2835
2944
  if (layerParams) ctx.appendLayerParams(sheet);
2836
2945
  ctx.appendBaselineCss(sheet);
2837
2946
  pruneTokensForBuild(ctx, sheet, []);
2838
- if (ctx.config.prune?.preflight) ctx.prunePreflight(sheet, collectRenderedElements(ctx));
2947
+ if (prunesPreflight(ctx.config.preflight)) ctx.prunePreflight(sheet, collectRenderedElements(ctx));
2839
2948
  if (ctx.config.prune?.keyframes) ctx.pruneKeyframes(sheet, collectKeyframeReferences(ctx, keyframeNames(ctx)));
2840
2949
  return ctx.getCss(sheet);
2841
2950
  };
@@ -2919,12 +3028,12 @@ const startProfiling = async (cwd, prefix, isWatching) => {
2919
3028
  //#endregion
2920
3029
  //#region src/cssgen.ts
2921
3030
  const cssgen = async (ctx, options) => {
2922
- const { outfile, type, minimal, splitting } = options;
3031
+ const { outfile, type, splitting } = options;
2923
3032
  const sheet = ctx.createSheet();
2924
3033
  if (type) {
2925
3034
  const done = logger.time.info(ctx.messages.cssArtifactComplete(type));
2926
3035
  ctx.appendCssOfType(type, sheet);
2927
- if (type === "preflight" && ctx.config.prune?.preflight) ctx.prunePreflight(sheet, collectRenderedElements(ctx));
3036
+ if (type === "preflight" && prunesPreflight(ctx.config.preflight)) ctx.prunePreflight(sheet, collectRenderedElements(ctx));
2928
3037
  if (outfile) {
2929
3038
  const css = ctx.getCss(sheet);
2930
3039
  logger.info("css", ctx.runtime.path.resolve(outfile));
@@ -2934,14 +3043,12 @@ const cssgen = async (ctx, options) => {
2934
3043
  } else {
2935
3044
  const { files, results } = ctx.parseFiles();
2936
3045
  const done = logger.time.info(ctx.messages.buildComplete(files.length));
2937
- if (!minimal) {
2938
- ctx.appendLayerParams(sheet);
2939
- ctx.appendBaselineCss(sheet);
2940
- }
3046
+ ctx.appendLayerParams(sheet);
3047
+ ctx.appendBaselineCss(sheet);
2941
3048
  ctx.appendParserCss(sheet);
2942
- if (!minimal) pruneTokensForBuild(ctx, sheet, results);
2943
- if (!minimal && ctx.config.prune?.preflight) ctx.prunePreflight(sheet, collectRenderedElements(ctx));
2944
- if (!minimal && ctx.config.prune?.keyframes) ctx.pruneKeyframes(sheet, collectKeyframeReferences(ctx, keyframeNames(ctx)));
3049
+ pruneTokensForBuild(ctx, sheet, results);
3050
+ if (prunesPreflight(ctx.config.preflight)) ctx.prunePreflight(sheet, collectRenderedElements(ctx));
3051
+ if (ctx.config.prune?.keyframes) ctx.pruneKeyframes(sheet, collectKeyframeReferences(ctx, keyframeNames(ctx)));
2945
3052
  if (splitting) await ctx.writeSplitCss(sheet);
2946
3053
  else if (outfile) {
2947
3054
  const css = ctx.getCss(sheet);
@@ -3012,7 +3119,7 @@ async function build(ctx, artifactIds) {
3012
3119
  const parsed = ctx.parseFiles();
3013
3120
  ctx.appendParserCss(sheet);
3014
3121
  pruneTokensForBuild(ctx, sheet, parsed.results);
3015
- if (ctx.config.prune?.preflight) ctx.prunePreflight(sheet, collectRenderedElements(ctx));
3122
+ if (prunesPreflight(ctx.config.preflight)) ctx.prunePreflight(sheet, collectRenderedElements(ctx));
3016
3123
  if (ctx.config.prune?.keyframes) ctx.pruneKeyframes(sheet, collectKeyframeReferences(ctx, keyframeNames(ctx)));
3017
3124
  await ctx.writeCss(sheet);
3018
3125
  done(ctx.messages.buildComplete(parsed.files.length));
@@ -3058,7 +3165,7 @@ async function generate(config, configPath) {
3058
3165
  ctx.appendBaselineCss(sheet);
3059
3166
  ctx.appendParserCss(sheet);
3060
3167
  pruneTokensForBuild(ctx, sheet, []);
3061
- if (ctx.config.prune?.preflight) ctx.prunePreflight(sheet, collectRenderedElements(ctx));
3168
+ if (prunesPreflight(ctx.config.preflight)) ctx.prunePreflight(sheet, collectRenderedElements(ctx));
3062
3169
  if (ctx.config.prune?.keyframes) ctx.pruneKeyframes(sheet, collectKeyframeReferences(ctx, keyframeNames(ctx)));
3063
3170
  const css = ctx.getCss(sheet);
3064
3171
  await ctx.runtime.fs.writeFile(outfile, css);
@@ -3160,10 +3267,10 @@ export default defineConfig({
3160
3267
  exclude: [],
3161
3268
 
3162
3269
  // Tokens, keyframes and @property rules nothing in the emitted css reaches are dropped
3163
- // by default — worth 36-78% of a new project's stylesheet. Set \`prune: { tokens: false }\`
3164
- // if you read tokens from somewhere the build cannot see them — \`token()\` with a
3165
- // computed path, or a hand-written stylesheet outside \`include\` — or list those under
3166
- // \`staticCss\` to keep them.
3270
+ // by default — worth 36-78% of a new project's stylesheet. If you read tokens from
3271
+ // somewhere the build cannot see them — \`token()\` with a computed path, or a
3272
+ // hand-written stylesheet outside \`include\` — name the categories they land in with
3273
+ // \`prune: { keepTokens: ['colors.*'] }\`, or set \`prune: { tokens: 'off' }\`.
3167
3274
 
3168
3275
  // Useful for theme customization
3169
3276
  theme: {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@bamboocss/node",
3
- "version": "1.31.0",
3
+ "version": "1.33.0",
4
4
  "description": "The core css bamboo library",
5
5
  "homepage": "https://bamboocss.com",
6
6
  "license": "MIT",
@@ -41,6 +41,7 @@
41
41
  "is-glob": "4.0.3",
42
42
  "lodash.merge": "4.6.2",
43
43
  "look-it-up": "2.1.0",
44
+ "matcher": "6.0.0",
44
45
  "outdent": " ^0.8.0",
45
46
  "p-limit": "5.0.0",
46
47
  "package-manager-detector": "1.6.0",
@@ -51,17 +52,17 @@
51
52
  "postcss": "8.5.26",
52
53
  "ts-morph": "28.0.0",
53
54
  "ts-pattern": "5.9.0",
54
- "@bamboocss/config": "1.31.0",
55
- "@bamboocss/core": "1.31.0",
56
- "@bamboocss/generator": "1.31.0",
57
- "@bamboocss/logger": "1.31.0",
58
- "@bamboocss/parser": "1.31.0",
59
- "@bamboocss/plugin-svelte": "1.31.0",
60
- "@bamboocss/plugin-vue": "1.31.0",
61
- "@bamboocss/reporter": "1.31.0",
62
- "@bamboocss/shared": "1.31.0",
63
- "@bamboocss/token-dictionary": "1.31.0",
64
- "@bamboocss/types": "1.31.0"
55
+ "@bamboocss/config": "1.33.0",
56
+ "@bamboocss/core": "1.33.0",
57
+ "@bamboocss/generator": "1.33.0",
58
+ "@bamboocss/logger": "1.33.0",
59
+ "@bamboocss/parser": "1.33.0",
60
+ "@bamboocss/plugin-svelte": "1.33.0",
61
+ "@bamboocss/plugin-vue": "1.33.0",
62
+ "@bamboocss/reporter": "1.33.0",
63
+ "@bamboocss/shared": "1.33.0",
64
+ "@bamboocss/token-dictionary": "1.33.0",
65
+ "@bamboocss/types": "1.33.0"
65
66
  },
66
67
  "devDependencies": {
67
68
  "@types/fs-extra": "11.0.4",