@kanso-labs/unplugin-style-dictionary 0.6.2 → 0.8.0

package/dist/types.d.ts

@@ -11,12 +11,69 @@ import { Config } from "style-dictionary";
  * build (e.g. `tsdown`/`rolldown build` without `--watch`) only builds once, in
  * `buildStart`.
  *
+ * Everything the plugin says goes through the host rather than to the console:
+ * Vite's `config.logger`, the plugin context under rollup and rolldown, and
+ * `compilation.warnings` under webpack, which is what puts a failed compile in
+ * `stats.toJson()`. A failure is reported on the warning channel and never the
+ * error one — rollup's `this.error` aborts the bundle, and that decision is
+ * `failOnError`'s alone. Where no host offers a channel the console is used,
+ * with colour gated on `NO_COLOR`, `FORCE_COLOR` and whether the stream is a
+ * terminal.
+ *
+ * The three `onBuild*` hooks are called synchronously and their return value
+ * is not awaited, so a build never waits for one. A hook may still be written
+ * `async`: a promise it returns is left to run on its own, and a rejection is
+ * caught and reported rather than reaching the host as an unhandled one. A
+ * hook that throws is reported and does not fail the build that called it.
+ *
+ * They return `Promise<void> | void` rather than `void` for that reason. Both
+ * accept an `async` hook as far as the compiler is concerned, but `void` alone
+ * makes one a `no-misused-promises` error under the type-aware lint rules a
+ * consumer is likely to be running — for a hook this documents as supported.
+ *
  * Rolldown's watch mode is the exception, and it is not about glob patterns.
  * `addWatchFile` is accepted either way, but what happens next differs by
  * platform — on macOS a file registered through it is watched by nothing, while
  * on a Linux runner the same edit reaches a rebuild. Do not rely on a token
  * edit triggering a rebuild there.
  */
+/**
+ * What the host is doing, handed to the function form of `config` so it can
+ * decide what to build.
+ *
+ * Only Vite reports all three. Where a host does not say, the value is
+ * derived rather than guessed at, and each field below says how.
+ */
+export interface StyleDictionaryConfigContext {
+  /**
+   * Whether the host is serving or building.
+   *
+   * `'serve'` comes from Vite's own `config.command` and is the dev server.
+   * Every other target builds, so it is `'build'` there — rollup, rolldown and
+   * webpack have no serving mode of their own to report.
+   */
+  command: 'build' | 'serve';
+  /**
+   * The host's mode, as it names it.
+   *
+   * Vite reports its `config.mode` — `'development'` serving,
+   * `'production'` building, or whatever `--mode` named. webpack reports its
+   * `mode` option. rollup and rolldown have no such concept, so the value
+   * follows `command`: `'development'` when serving, `'production'` when
+   * building.
+   */
+  mode: string;
+  /**
+   * Whether the host will keep rebuilding.
+   *
+   * `true` under Vite's dev server, `rollup --watch`, `rolldown.watch()` and
+   * `webpack --watch`; `false` for a one-shot build. It is read from the
+   * host — the plugin context's `meta.watchMode` on the three rollup-shaped
+   * targets, and `compiler.watchMode` on webpack — rather than inferred from
+   * `command`, because `rollup --watch` both watches and builds.
+   */
+  watch: boolean;
+}
 export interface UnpluginStyleDictionaryOptions {
   /**
    * Whether a configuration whose output is already up to date may skip its
@@ -57,10 +114,42 @@ export interface UnpluginStyleDictionaryOptions {
    * - A function that returns a config or array of configs (or resolves to them).
    *   Useful for calling `StyleDictionary.registerFormat()` (or other `register*`
    *   methods) before returning a config that references the custom format by name.
+   *   It is handed a `StyleDictionaryConfigContext` describing what the host is
+   *   doing, so an expensive platform can be built only when it is wanted —
+   *   skipped under the dev server, built by `vite build`. A function taking no
+   *   arguments stays valid: TypeScript accepts one of fewer parameters, and
+   *   JavaScript ignores the extra argument.
    *
-   * If not provided, it will look for 'sd.config.json' or 'config.json' in the root directory.
+   * If not provided, the root directory is searched for 'sd.config.json',
+   * 'config.json', 'sd.config.js' and 'sd.config.mjs', in that order. The
+   * first one that exists wins, and the rest are not looked at.
    */
-  config?: (() => Config | Config[] | Promise<Config | Config[]>) | Config | Config[] | string | string[];
+  config?: ((context: StyleDictionaryConfigContext) => Config | Config[] | Promise<Config | Config[]>) | Config | Config[] | string | string[];
+  /**
+   * Whether a failed rebuild is pushed to Vite's error overlay.
+   *
+   * A rebuild that fails under the dev server used to reach the browser
+   * nowhere: the page went on rendering the last good generated file, and the
+   * only trace was one red terminal line the developer may not have been
+   * looking at. With this on, the failure is sent to the page as an error
+   * frame naming this plugin, and the overlay is dismissed on the next
+   * rebuild that succeeds.
+   *
+   * This is Vite's overlay, so it does nothing on the other three targets,
+   * and nothing under `vite build` — there is no page to draw on.
+   *
+   * It is not `failOnError`'s job, and the two are independent. `failOnError`
+   * decides whether the host stops; this decides whether the browser is told.
+   * A dev server deliberately keeps serving through a failed rebuild, which is
+   * precisely the case where the overlay is the only thing that can say so.
+   *
+   * A failure Style Dictionary raises before this plugin can catch it — a
+   * token file that is not valid JSON, which rejects out of band — reaches
+   * neither the overlay nor this option.
+   *
+   * @default true
+   */
+  errorOverlay?: boolean;
   /**
    * Whether a compile that fails should throw rather than only be reported.
    *
@@ -99,10 +188,55 @@ export interface UnpluginStyleDictionaryOptions {
    * A compile that fails is reported at every level, so there is no
    * `'error'`: `'silent'` is the quietest and still reports a failure.
    *
+   * This option governs what the plugin says, not where it goes. The messages
+   * are handed to the host — Vite's `config.logger`, the rollup and rolldown
+   * plugin context, webpack's `compilation` — so a host silenced by its own
+   * log level suppresses them after this option has let them through. A
+   * failure still stops the build whenever `failOnError` says it should,
+   * printed or not.
+   *
    * @default undefined, which prints the plugin's own lines and leaves the
    * configuration's `log.verbosity` alone
    */
   logLevel?: 'info' | 'silent' | 'verbose' | 'warn';
+  /**
+   * Called once a build has finished, with every file it declares and how long
+   * it took in milliseconds.
+   *
+   * The paths are absolute and platform-native, sorted so two runs of the same
+   * configuration hand back the same order. They are what the build declares
+   * rather than what it wrote this time: a configuration skipped by `cache`
+   * contributes its destinations too, because they are on disk and current,
+   * and a post-processing step that ignored them would leave half the output
+   * untouched on a rebuild that changed one file.
+   *
+   * This is where formatting the generated files, type-checking them, or
+   * telling something else they have landed belongs.
+   *
+   * @default undefined
+   */
+  onBuildEnd?: (files: string[], durationMs: number) => Promise<void> | void;
+  /**
+   * Called when a build fails, with whatever was thrown.
+   *
+   * It fires whatever `failOnError` is set to, and before that option decides
+   * whether to rethrow — the two answer different questions, and under a dev
+   * server the default is not to throw at all.
+   *
+   * The failure is reported to the console either way, so this is for reacting
+   * to one rather than for noticing it.
+   *
+   * @default undefined
+   */
+  onBuildError?: (error: unknown) => Promise<void> | void;
+  /**
+   * Called before a build begins, once per build.
+   *
+   * A watch-triggered rebuild is a build, so this fires again for each one.
+   *
+   * @default undefined
+   */
+  onBuildStart?: () => Promise<void> | void;
   /**
    * Whether the table of generated files and their sizes is produced.
    *

package/dist/vite.d.ts

@@ -1,6 +1,6 @@
-import { UnpluginStyleDictionaryOptions } from "./types.js";
+import { StyleDictionaryConfigContext, UnpluginStyleDictionaryOptions } from "./types.js";
 //#region src/vite.d.ts
 declare const _default: (options?: UnpluginStyleDictionaryOptions | undefined) => import("vite").Plugin<any>;
 //#endregion
-export { type UnpluginStyleDictionaryOptions, _default as default };
+export { type StyleDictionaryConfigContext, type UnpluginStyleDictionaryOptions, _default as default };
 //# sourceMappingURL=vite.d.ts.map

package/dist/watch-filter.js

@@ -0,0 +1,13 @@
+import picomatch from "picomatch";
+//#region src/watch-filter.ts
+function matchesWatchedFile(file, patterns) {
+	const normalizedFile = file.replace(/\\/g, "/");
+	return patterns.some((pattern) => {
+		const normalizedPattern = pattern.replace(/\\/g, "/");
+		return normalizedPattern === normalizedFile || picomatch.isMatch(normalizedFile, normalizedPattern);
+	});
+}
+//#endregion
+export { matchesWatchedFile };
+
+//# sourceMappingURL=watch-filter.js.map

package/dist/watch-filter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"watch-filter.js","names":[],"sources":["../src/watch-filter.ts"],"sourcesContent":["import picomatch from 'picomatch'\n\n// Whether `file` matches one of the resolved config/token watch patterns.\n// Shared by the Vite-specific `configureServer` watcher and the universal\n// `watchChange` hook — both need it, and both must skip files that don't\n// match: without this filter, `watchChange` reacts to *any* changed\n// module-graph file, including this plugin's own generated output (since\n// consuming code imports it). Every regenerate is itself a \"change\", which\n// without filtering re-triggers a rebuild forever.\n//\n// Matching a pattern is only half of that, and this function is only the half\n// it can answer. A `buildPath` inside a `source` directory is a supported\n// layout, and under any correct matcher its output matches the very glob that\n// produced it — so the caller also subtracts what the last build wrote. See\n// `generatedDestinations` and `isWatchedSource` in the factory below.\n//\n// The patterns are Style Dictionary's own `source` and `include` globs, so the\n// filter has to admit exactly what the build reads — which is why the matching\n// is a real globber's rather than hand-rolled. The version this replaces was\n// wrong in both directions at once: it stripped `/**` out of a pattern and\n// prefix-matched the remainder, so `tokens/**/*.json` matched nothing sitting\n// directly in `tokens/` and `tokens/**` matched a `tokens-backup/` sibling,\n// while its regex branch mapped every `*` to `.*` — crossing `/` — and tested\n// it unanchored, so generated output under a watched directory matched its own\n// source glob and rebuilt forever.\n//\n// picomatch rather than `path.matchesGlob`, which would need no dependency at\n// all: that function is documented experimental, and on Node 20 — the floor\n// `engines` declares — it prints `ExperimentalWarning: glob is an experimental\n// feature and might change at any time` into the consumer's build output. The\n// dependency is free in practice, since `unplugin` depends on the same\n// picomatch and is already installed wherever this plugin is. Its `dot: false`\n// default is deliberate: it is what glob, and so Style Dictionary, reads\n// sources with, so a dotfile is invisible to the filter and to the build alike.\nexport function matchesWatchedFile(file: string, patterns: string[]): boolean {\n  const normalizedFile = file.replace(/\\\\/g, '/')\n\n  return patterns.some((pattern) => {\n    const normalizedPattern = pattern.replace(/\\\\/g, '/')\n\n    // A config file reaches this function as its own literal path, which is\n    // both the common case and the one shape that is not a glob at all.\n    return (\n      normalizedPattern === normalizedFile ||\n      picomatch.isMatch(normalizedFile, normalizedPattern)\n    )\n  })\n}\n"],"mappings":";;AAkCA,SAAgB,mBAAmB,MAAc,UAA6B;CAC5E,MAAM,iBAAiB,KAAK,QAAQ,OAAO,GAAG;CAE9C,OAAO,SAAS,MAAM,YAAY;EAChC,MAAM,oBAAoB,QAAQ,QAAQ,OAAO,GAAG;EAIpD,OACE,sBAAsB,kBACtB,UAAU,QAAQ,gBAAgB,iBAAiB;CAEvD,CAAC;AACH"}

package/dist/webpack.d.ts

@@ -1,6 +1,6 @@
-import { UnpluginStyleDictionaryOptions } from "./types.js";
+import { StyleDictionaryConfigContext, UnpluginStyleDictionaryOptions } from "./types.js";
 //#region src/webpack.d.ts
 declare const _default: (options?: UnpluginStyleDictionaryOptions | undefined) => import("webpack").WebpackPluginInstance;
 //#endregion
-export { type UnpluginStyleDictionaryOptions, _default as default };
+export { type StyleDictionaryConfigContext, type UnpluginStyleDictionaryOptions, _default as default };
 //# sourceMappingURL=webpack.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kanso-labs/unplugin-style-dictionary",
-  "version": "0.6.2",
+  "version": "0.8.0",
   "description": "Compile Style Dictionary design tokens ahead of your bundler (Vite, Rolldown, Rollup, or Webpack) from a single unplugin-based plugin, with automatic watching and rebuilding under Vite",
   "keywords": [
     "unplugin",