@bamboocss/vite 1.25.0 → 1.28.0

package/dist/index.d.cts

@@ -1,7 +1,9 @@
 import { Plugin } from "vite";
 import { Context } from "@bamboocss/core";
-import { Dict, ParserResultInterface } from "@bamboocss/types";
+import { Dict, ParserResultInterface, ResultItem } from "@bamboocss/types";
 import MagicString from "magic-string";
+import { SourceFile } from "ts-morph";
+
 //#region src/css.d.ts
 /**
  * What a project imports to get the stylesheet.
@@ -30,6 +32,49 @@ interface BambooCssPluginOptions {
  */
 declare const bamboocssCss: (options?: BambooCssPluginOptions) => Plugin;
 //#endregion
+//#region src/fold-recipe.d.ts
+/**
+ * Lowering a call of an inline recipe to the class string it produces.
+ *
+ * The prize is not the `cva` runtime, which is small. It is the *config*: `cva({ base, variants })`
+ * ships the whole style object to the browser purely so the runtime can hash it into a name and
+ * pick classes off it. Those styles are already in the stylesheet. Once every call of a binding
+ * is lowered, the binding is unreferenced and a bundler drops the config with it — measured at
+ * 81 kB gzipped across one application's 1,297 inline recipes, against 4.5 kB for the runtime.
+ *
+ * Correct by construction rather than by a matching reimplementation: the class names come from
+ * `getRecipeIdentity` and `getRecipeClassNames`, the same functions the browser runs, and the
+ * prefixing and hashing from `classFormatter`, which is what the encoder emitted rules under.
+ */
+type Dict$1 = Record<string, unknown>;
+/** A recipe's config, as the extractor resolved it. */
+interface RecipeConfig {
+  className?: string;
+  base?: Dict$1;
+  variants?: Record<string, Record<string, unknown>>;
+  defaultVariants?: Record<string, unknown>;
+  compoundVariants?: unknown[];
+  /** Present on a slot recipe, which resolves to one class per slot rather than a string. */
+  slots?: unknown;
+}
+/**
+ * A recipe the fold can lower against.
+ *
+ * `name` is hashed once here rather than per call site: `getRecipeIdentity` serialises the
+ * whole config to hash it, which measured as 91% of the per-call work when it sat inside
+ * `lowerRecipeCall`. The runtime does it once per `cva()` for the same reason.
+ *
+ * `box` is the *definition's* node, carried so the fold can register the module the config
+ * came from as a watch dependency. Without it, editing a config in another module leaves
+ * every literal folded against it stale — the stylesheet gets a new identity and the element
+ * keeps the old class.
+ */
+interface RecipeEntry {
+  config: RecipeConfig;
+  name: string;
+  box: ResultItem['box'];
+}
+//#endregion
 //#region src/runtime-css.d.ts
 /**
  * The generated runtime's `css`, rebuilt in-process from a resolved context.
@@ -60,7 +105,7 @@ declare const createRuntimeCss: (ctx: Context) => RuntimeCss;
  * Why a call site was left alone. Surfaced through `panda`-style diagnostics so a
  * user can tell the difference between "this folded" and "this silently didn't".
  */
-type SkipReason = 'dynamic' | 'raw-call' | 'not-foldable' | 'recipe-call' | 'unsupported-kind' | 'not-imported' | 'no-call-expression' | 'overlapping' | 'empty' | 'unresolved-token';
+type SkipReason = 'dynamic' | 'raw-call' | 'not-foldable' | 'recipe-call' | 'unsupported-kind' | 'not-imported' | 'no-call-expression' | 'overlapping' | 'empty' | 'unresolved-token' | 'runtime-binding';
 interface FoldedCall {
   name: string;
   /**
@@ -119,6 +164,61 @@ interface FoldOptions {
    * On by default.
    */
   partial?: boolean;
+  /**
+   * Parse another module, for a recipe whose `cva` config lives outside this one.
+   *
+   * Threaded in rather than read off `ctx`, because the project belongs to the node
+   * context and this signature takes the core one. Its absence is a supported state:
+   * without it a cross-module recipe call is still *reported*, which is the half that
+   * used to be missing entirely — it simply cannot be lowered.
+   *
+   * Pulling the module on demand is also what makes the fold order-independent. A
+   * bundler transforms a consumer before the module it imports, so a registry built
+   * from what has been transformed so far would fold or decline the same file
+   * depending on discovery order.
+   */
+  parseModule?: (filePath: string) => ParserResultInterface | undefined;
+  /**
+   * Configs of modules other than this one, shared across a build.
+   *
+   * Owned by the caller because it has to outlive one call: the declaring module would
+   * otherwise be re-parsed once per module that imports it, which is `consumers x module
+   * size` on the transform path — measured at 909ms against 8.3ms for fifty consumers of a
+   * hundred-recipe module. The caller clears an entry when the file changes, which is the
+   * only place that knows.
+   */
+  recipeConfigCache?: Map<string, ForeignRecipes>;
+  /**
+   * Also report bamboo bindings the rewrite left behind, whatever the skip ledger says.
+   *
+   * The ledger holds only calls something recognised, so it answers "of the calls I looked
+   * at, which survived" — and a guarantee built on it is worth exactly what the recogniser
+   * is. A cross-module recipe call used to appear in neither column, so a build could report
+   * a clean sweep while shipping hundreds of them.
+   *
+   * This asks what the guarantee actually claims: after the rewrite, is anything from a
+   * bamboo module still referenced? Off by default because it costs an identifier walk, and
+   * only `strict` needs an answer it can fail a build on.
+   */
+  reportSurvivors?: boolean;
+  /**
+   * The module's own AST, when the caller already holds it.
+   *
+   * Only `reportSurvivors` needs it, and only for the case it exists to catch: a module whose
+   * bamboo usage produced no parser result at all has no call to reach the AST through.
+   */
+  sourceFile?: SourceFile;
+}
+/**
+ * What one foreign module contributes, in a form that outlives it.
+ *
+ * Plain data only. Anything holding a ts-morph node would be read after the next
+ * `addSourceFile` forgets that module's tree.
+ */
+interface ForeignRecipes {
+  configs: Map<string, RecipeEntry>;
+  /** How that module spelled the css module, for a helper import written into a consumer. */
+  cssSpecifier?: string;
 }
 declare const foldSource: (options: FoldOptions) => FoldResult;
 //#endregion

package/dist/index.d.mts

@@ -1,8 +1,8 @@
 import MagicString from "magic-string";
-import { Node } from "ts-morph";
+import { Node, SourceFile } from "ts-morph";
 import { Context } from "@bamboocss/core";
 import { Plugin } from "vite";
-import { Dict, ParserResultInterface } from "@bamboocss/types";
+import { Dict, ParserResultInterface, ResultItem } from "@bamboocss/types";
 
 //#region src/css.d.ts
 /**
@@ -32,6 +32,49 @@ interface BambooCssPluginOptions {
  */
 declare const bamboocssCss: (options?: BambooCssPluginOptions) => Plugin;
 //#endregion
+//#region src/fold-recipe.d.ts
+/**
+ * Lowering a call of an inline recipe to the class string it produces.
+ *
+ * The prize is not the `cva` runtime, which is small. It is the *config*: `cva({ base, variants })`
+ * ships the whole style object to the browser purely so the runtime can hash it into a name and
+ * pick classes off it. Those styles are already in the stylesheet. Once every call of a binding
+ * is lowered, the binding is unreferenced and a bundler drops the config with it — measured at
+ * 81 kB gzipped across one application's 1,297 inline recipes, against 4.5 kB for the runtime.
+ *
+ * Correct by construction rather than by a matching reimplementation: the class names come from
+ * `getRecipeIdentity` and `getRecipeClassNames`, the same functions the browser runs, and the
+ * prefixing and hashing from `classFormatter`, which is what the encoder emitted rules under.
+ */
+type Dict$1 = Record<string, unknown>;
+/** A recipe's config, as the extractor resolved it. */
+interface RecipeConfig {
+  className?: string;
+  base?: Dict$1;
+  variants?: Record<string, Record<string, unknown>>;
+  defaultVariants?: Record<string, unknown>;
+  compoundVariants?: unknown[];
+  /** Present on a slot recipe, which resolves to one class per slot rather than a string. */
+  slots?: unknown;
+}
+/**
+ * A recipe the fold can lower against.
+ *
+ * `name` is hashed once here rather than per call site: `getRecipeIdentity` serialises the
+ * whole config to hash it, which measured as 91% of the per-call work when it sat inside
+ * `lowerRecipeCall`. The runtime does it once per `cva()` for the same reason.
+ *
+ * `box` is the *definition's* node, carried so the fold can register the module the config
+ * came from as a watch dependency. Without it, editing a config in another module leaves
+ * every literal folded against it stale — the stylesheet gets a new identity and the element
+ * keeps the old class.
+ */
+interface RecipeEntry {
+  config: RecipeConfig;
+  name: string;
+  box: ResultItem['box'];
+}
+//#endregion
 //#region src/runtime-css.d.ts
 /**
  * The generated runtime's `css`, rebuilt in-process from a resolved context.
@@ -62,7 +105,7 @@ declare const createRuntimeCss: (ctx: Context) => RuntimeCss;
  * Why a call site was left alone. Surfaced through `panda`-style diagnostics so a
  * user can tell the difference between "this folded" and "this silently didn't".
  */
-type SkipReason = 'dynamic' | 'raw-call' | 'not-foldable' | 'recipe-call' | 'unsupported-kind' | 'not-imported' | 'no-call-expression' | 'overlapping' | 'empty' | 'unresolved-token';
+type SkipReason = 'dynamic' | 'raw-call' | 'not-foldable' | 'recipe-call' | 'unsupported-kind' | 'not-imported' | 'no-call-expression' | 'overlapping' | 'empty' | 'unresolved-token' | 'runtime-binding';
 interface FoldedCall {
   name: string;
   /**
@@ -121,6 +164,61 @@ interface FoldOptions {
    * On by default.
    */
   partial?: boolean;
+  /**
+   * Parse another module, for a recipe whose `cva` config lives outside this one.
+   *
+   * Threaded in rather than read off `ctx`, because the project belongs to the node
+   * context and this signature takes the core one. Its absence is a supported state:
+   * without it a cross-module recipe call is still *reported*, which is the half that
+   * used to be missing entirely — it simply cannot be lowered.
+   *
+   * Pulling the module on demand is also what makes the fold order-independent. A
+   * bundler transforms a consumer before the module it imports, so a registry built
+   * from what has been transformed so far would fold or decline the same file
+   * depending on discovery order.
+   */
+  parseModule?: (filePath: string) => ParserResultInterface | undefined;
+  /**
+   * Configs of modules other than this one, shared across a build.
+   *
+   * Owned by the caller because it has to outlive one call: the declaring module would
+   * otherwise be re-parsed once per module that imports it, which is `consumers x module
+   * size` on the transform path — measured at 909ms against 8.3ms for fifty consumers of a
+   * hundred-recipe module. The caller clears an entry when the file changes, which is the
+   * only place that knows.
+   */
+  recipeConfigCache?: Map<string, ForeignRecipes>;
+  /**
+   * Also report bamboo bindings the rewrite left behind, whatever the skip ledger says.
+   *
+   * The ledger holds only calls something recognised, so it answers "of the calls I looked
+   * at, which survived" — and a guarantee built on it is worth exactly what the recogniser
+   * is. A cross-module recipe call used to appear in neither column, so a build could report
+   * a clean sweep while shipping hundreds of them.
+   *
+   * This asks what the guarantee actually claims: after the rewrite, is anything from a
+   * bamboo module still referenced? Off by default because it costs an identifier walk, and
+   * only `strict` needs an answer it can fail a build on.
+   */
+  reportSurvivors?: boolean;
+  /**
+   * The module's own AST, when the caller already holds it.
+   *
+   * Only `reportSurvivors` needs it, and only for the case it exists to catch: a module whose
+   * bamboo usage produced no parser result at all has no call to reach the AST through.
+   */
+  sourceFile?: SourceFile;
+}
+/**
+ * What one foreign module contributes, in a form that outlives it.
+ *
+ * Plain data only. Anything holding a ts-morph node would be read after the next
+ * `addSourceFile` forgets that module's tree.
+ */
+interface ForeignRecipes {
+  configs: Map<string, RecipeEntry>;
+  /** How that module spelled the css module, for a helper import written into a consumer. */
+  cssSpecifier?: string;
 }
 declare const foldSource: (options: FoldOptions) => FoldResult;
 //#endregion