@master/css-cli 2.0.0-rc.87 → 2.0.0

package/README.md

@@ -1,155 +1,42 @@
-<br>
-<div align="center">
+# @master/css-cli
 
-<p align="center">
-  <a href="https://css.master.co">
-    <picture>
-      <source media="(prefers-color-scheme: dark)" srcset="https://user-images.githubusercontent.com/33840671/201701649-3bb7d698-abec-4d5f-ac30-ccc4d7bafcd4.svg">
-      <source media="(prefers-color-scheme: light)" srcset="https://user-images.githubusercontent.com/33840671/201703010-77bf2373-9899-40cc-98f5-30cf9b546941.svg">
-      <img alt="Master CSS" src="https://user-images.githubusercontent.com/33840671/201703010-77bf2373-9899-40cc-98f5-30cf9b546941.svg" width="100%">
-    </picture>
-  </a>
-</p>
-<p align="center">Master CSS CLI</p>
-
-<p align="center">
-  <a aria-label="GitHub release (latest by date including pre-releases)" href="https://github.com/master-co/css/releases">
-    <picture>
-      <source media="(prefers-color-scheme: dark)" srcset="https://img.shields.io/github/v/release/master-co/css?include_prereleases&color=212022&label=&style=for-the-badge&logo=github&logoColor=fff">
-      <source media="(prefers-color-scheme: light)" srcset="https://img.shields.io/github/v/release/master-co/css?include_prereleases&color=f6f7f8&label=&style=for-the-badge&logo=github&logoColor=%23000">
-      <img alt="NPM Version" src="https://img.shields.io/github/v/release/master-co/css?include_prereleases&color=f6f7f8&label=&style=for-the-badge&logo=github">
-    </picture>
-  </a>
-  <a aria-label="NPM Package" href="https://www.npmjs.com/package/@master/css-cli">
-    <picture>
-      <source media="(prefers-color-scheme: dark)" srcset="https://img.shields.io/npm/dm/@master/css-cli?color=212022&label=%20&logo=npm&style=for-the-badge">
-      <source media="(prefers-color-scheme: light)" srcset="https://img.shields.io/npm/dm/@master/css-cli?color=f6f7f8&label=%20&logo=npm&style=for-the-badge">
-      <img alt="NPM package ( download / month )" src="https://img.shields.io/npm/dm/@master/css-cli?color=f6f7f8&label=%20&logo=npm&style=for-the-badge">
-    </picture>
-  </a>
-  <a aria-label="Discord Community" href="https://discord.gg/sZNKpAAAw6">
-    <picture>
-      <source media="(prefers-color-scheme: dark)" srcset="https://img.shields.io/discord/917780624314613760?color=212022&label=%20&logo=discord&style=for-the-badge">
-      <source media="(prefers-color-scheme: light)" srcset="https://img.shields.io/discord/917780624314613760?color=f6f7f8&label=%20&logo=discord&style=for-the-badge">
-      <img alt="Discord online" src="https://img.shields.io/discord/917780624314613760?color=f6f7f8&label=%20&logo=discord&style=for-the-badge">
-    </picture>
-  </a>
-  <a aria-label="Follow @mastercorg" href="https://twitter.com/mastercorg">
-    <picture>
-      <source media="(prefers-color-scheme: dark)" srcset="https://img.shields.io/static/v1?label=%20&message=twitter&color=212022&logo=twitter&style=for-the-badge">
-      <source media="(prefers-color-scheme: light)" srcset="https://img.shields.io/static/v1?label=%20&message=twitter&color=f6f7f8&logo=twitter&style=for-the-badge">
-      <img alt="Follow @mastercorg" src="https://img.shields.io/static/v1?label=%20&message=twitter&color=f6f7f8&logo=twitter&style=for-the-badge">
-    </picture>
-  </a>
-  <a aria-label="Github Actions" href="https://github.com/master-co/css/actions/workflows/ci-release.yml">
-    <picture>
-      <source media="(prefers-color-scheme: dark)" srcset="https://img.shields.io/github/actions/workflow/status/master-co/css/ci-release.yml?branch=rc&label=%20&message=twitter&color=212022&logo=githubactions&style=for-the-badge">
-      <source media="(prefers-color-scheme: light)" srcset="https://img.shields.io/github/actions/workflow/status/master-co/css/ci-release.yml?branch=rc&label=%20&message=twitter&color=f6f7f8&logo=githubactions&style=for-the-badge&logoColor=%23000">
-      <img alt="Github release actions" src="https://img.shields.io/github/actions/workflow/status/master-co/css/ci-release.yml?branch=rc&label=%20&message=twitter&color=f6f7f8&logo=githubactions&style=for-the-badge&logoColor=%23000">
-    </picture>
-  </a>
-</p>
-
-</div>
-
-## Installation
+Generate and inspect Master CSS with the project's installed compiler.
 
 ```bash
-npm install -D @master/css-cli
+npm install --save-dev @master/css-cli
+npx @master/css-cli generate
 ```
 
-Run the package binary directly with `npx @master/css-cli`. The package does not expose `mcss` or `mastercss` aliases.
-
-## Commands
+Use the explicit `generate`, `lint`, `inspect`, or `suggest` command. The app CSS entry starts with `@import '@master/css';`, loading the complete preset. Static generation emits CSS without a Master browser runtime. Native CSS is preserved unless pruning is explicitly enabled.
 
-### `npx @master/css-cli [source paths]`
-
-Scan source files, detect Master CSS classes, generate CSS rules, and write the generated CSS file.
+`generate --output` flattens the import graph into the output file in cascade order and writes referenced images and fonts beside it. External imports at the top of an imported stylesheet move up with it when only other external imports precede it. An imported stylesheet that keeps a namespace or an import under a media, supports or layer qualifier, or whose external imports would follow inlined rules, stays a sibling CSS file, as do the imports before it; deploy the output directory as a whole.
 
 ```bash
-npx @master/css-cli index.html main.js
+npx @master/css-cli generate 'src/**/*.{html,tsx}' --output public/master.css
+npx @master/css-cli generate --watch
+npx @master/css-cli lint --format json
+npx @master/css-cli inspect --include-css --format json
+npx @master/css-cli suggest 'display: flex; align-items: center;'
 ```
 
-When no source paths are passed, the CLI scans the current project with the default scanner `include` and `exclude` options.
+Without source paths, `lint` follows the scanner source policy and skips generated output and `.gitignore` matches. Pass a path or glob to lint an ignored artifact explicitly.
 
-```bash
-npx @master/css-cli
-```
+`suggest` proposes project-aware classes for an isolated CSS declaration block without writing files. It checks declaration output; review the surrounding cascade and browser rendering before applying a suggestion.
 
-Options:
+Inspection reports distinguish class matching, CSS syntax, CSS values and browser support. Generated CSS is not visual verification. `--exit-code never` suppresses the diagnostic failure exit code; `--max-warnings` sets the warning threshold.
 
-| Option | Type | Default | Description |
-| --- | --- | --- | --- |
-| `-o, --output <path>` | `string` | `master.css` | Generated CSS output path. |
-| `-v, --verbose <level>` | `number` | `1` | Logging level. Use `0` to silence terminal output. |
-| `-w, --watch` | `boolean` | `false` | Watch files and rebuild continuously. |
+## Compare project changes
 
-### `npx @master/css-cli lint [source paths]`
-
-Run machine-readable Master CSS diagnostics for agents, MCP servers, editor tools, and native CI checks. JavaScript and VS Code projects should still use ESLint as the main human lint workflow; this command is a native preflight surface that shares the same class policy engine.
-
-```bash
-npx @master/css-cli lint index.html main.js
-```
-
-Use JSON output for tools:
+Capture the known source classes, independently resolved manifest, native stylesheets and output assets before changing a token, mixin or stylesheet:
 
 ```bash
-cat src/App.tsx | npx @master/css-cli lint --exit-code never --stdin --stdin-filepath src/App.tsx
+npx @master/css-cli inspect --snapshot > before.json
+# Edit the project, then compare against the saved snapshot.
+npx @master/css-cli inspect --compare before.json > impact.json
 ```
 
-Options:
-
-| Option | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--stdin` | `boolean` | `false` | Read one source buffer from stdin. |
-| `--stdin-filepath <path>` | `string` | `stdin.html` | File path used to infer the stdin language. |
-| `--fix` | `boolean` | `false` | Apply safe class-list fixes to files. |
-| `--fix-dry-run` | `boolean` | `false` | Return fix proposals without writing files. |
-| `--fix-directives` | `boolean` | `false` | Allow structural directive fixes when `--fix` writes files. |
-| `--format <format>` | `json` or `stylish` | `json` | Print machine-readable diagnostics or human-readable output. |
-| `--rules <rules>` | comma list | recommended | Select lint rules, `recommended`, or `all`. |
-| `--exit-code <mode>` | `diagnostics` or `never` | `diagnostics` | Control whether diagnostics set a non-zero exit code. |
-| `--max-warnings <number>` | `number` | none | Exit with a non-zero status when warnings exceed this count. |
-
-The JSON report uses `version: 1`. Tooling can rely on the top-level `version`, `cwd`, `manifest`, `files`, and `summary` fields. Diagnostic `data` objects may gain additional fields as Master CSS reports become more precise.
-
-### `npx @master/css-cli inspect [source paths]`
-
-Inspect scanner state, managed stylesheet entries, generated CSS size, and explicit missing CSS checks. This command is for MCP servers, AI agents, build diagnostics, and support tooling that need machine-readable extraction state, not class policy linting.
-
-```bash
-npx @master/css-cli inspect --classes "btn card" --format json --exit-code never
-```
-
-Use `--classes` to ask whether specific class names are present in the generated CSS path. The report explains each checked class as `generated`, `native-css`, `safelist`, `invalid`, `blocklisted`, or `not-detected`.
-
-The JSON report includes:
-
-| Field | Description |
-| --- | --- |
-| `inputs` | Source patterns, resolved files, and explicit classes checked by this run. |
-| `scanner` | Global scanner class sets, counts, safelist/blocklist counts, and reset dependencies. |
-| `stylesheets` | Managed CSS entries, dependency metadata, warnings, and entry loading errors. |
-| `css` | Generated CSS byte size, emitted global counts, and optional CSS text. |
-| `missingCSS` | Present and missing results for `--classes`. |
-| `files` | Per-file scanner discoveries for latent, valid, invalid, and native CSS classes. |
-| `diagnostics` | Machine-readable `scanner`, `stylesheet`, and `missing-css` diagnostics. |
-| `summary` | File, stylesheet, diagnostic, error, warning, missing CSS, and invalid class totals. |
-
-The JSON report uses `version: 1`. Tooling can rely on the top-level `version`, `cwd`, `inputs`, `scanner`, `stylesheets`, `css`, `missingCSS`, `files`, `diagnostics`, and `summary` fields. Nested diagnostic `data` and stylesheet details may evolve unless documented for a specific diagnostic code.
-
-Options:
-
-| Option | Type | Default | Description |
-| --- | --- | --- | --- |
-| `--classes <classes>` | whitespace list | none | Class names to verify against scanner state and generated CSS. |
-| `--include-css` | `boolean` | `false` | Include generated CSS text in the JSON report. |
-| `--format <format>` | `json` or `stylish` | `json` | Print machine-readable diagnostics or human-readable output. |
-| `--exit-code <mode>` | `diagnostics` or `never` | `diagnostics` | Control whether diagnostics set a non-zero exit code. |
-| `--max-warnings <number>` | `number` | none | Exit with a non-zero status when warnings exceed this count. |
+Both options produce JSON on stdout and are mutually exclusive. Snapshots and comparison reports have independent `version: 1` contracts. `--compare` resolves its path relative to the current working directory. Invalid snapshots or failed project resolution, stylesheet compilation or extraction fail the command. Class validation errors remain comparable, so deleting a token can reveal consumers that lose their generated rules. Differences alone do not fail; run ordinary `inspect` for diagnostic exit codes.
 
-## Related docs
+The impact report includes changed definitions, known consumers and files, before/after rules, transitive dependencies and asset/order changes. Read `coverage` for excluded and unresolved sources. Native references are conservative at stylesheet granularity; the report does not evaluate the DOM cascade, remote stylesheets or binary resource contents. Capture uses local file URLs for asset identities.
 
-- [Static rendering guide](https://rc.css.master.co/guide/installation)
-- [Scanner package](../scanner)
+See [CLI installation](https://css.master.co/guide/installation#cli) and [AI review workflow](https://css.master.co/guide/ai-coding) for project setup and review.

package/dist/asset-ownership.js

@@ -0,0 +1,150 @@
+import { publishStylesheet, replaceStylesheetFile, resolveEntryTarget } from "./publication.js";
+import fs from "node:fs";
+import path from "node:path";
+import { createHash } from "node:crypto";
+// src/asset-ownership.ts
+const ASSET_RETENTION_MS = 864e5;
+const suffix = ".master-css.json";
+const digest = (bytes) => createHash("sha256").update(bytes).digest("hex");
+const stylesheetStatePath = (entry) => path.join(path.dirname(entry), `.${path.basename(entry)}${suffix}`);
+const name = (value) => typeof value === "string" && value !== "." && value !== ".." && value.length > 0 && !/[\\/\0]/.test(value);
+const assetName = (value) => name(value) && /^master-[a-f0-9]+-/.test(value);
+const hash = (value) => typeof value === "string" && /^[a-f0-9]{64}$/.test(value);
+const timestamp = (value) => typeof value === "number" && Number.isFinite(value) && value >= 0;
+const object = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+const identityKeys = [
+	"dev",
+	"ino",
+	"birthtimeNs",
+	"mtimeNs",
+	"mode"
+];
+const temporaryName = (value) => typeof value === "string" && /^\.master-css-[a-f0-9-]+\.tmp$/.test(value);
+const validIdentity = (value) => object(value) && identityKeys.every((key) => typeof value[key] === "string" && /^\d+$/.test(value[key]));
+const generation = (value) => object(value) && hash(value.hash) && Array.isArray(value.assets) && value.assets.every(assetName);
+function identity(file) {
+	const stat = fs.lstatSync(file, {
+		bigint: true,
+		throwIfNoEntry: false
+	});
+	if (!stat?.isFile()) return void 0;
+	return {
+		dev: String(stat.dev),
+		ino: String(stat.ino),
+		birthtimeNs: String(stat.birthtimeNs),
+		mtimeNs: String(stat.mtimeNs),
+		mode: String(stat.mode & 511n)
+	};
+}
+function sameIdentity(left, right) {
+	return left && identityKeys.every((key) => left[key] === right[key]);
+}
+function readState(file, entry) {
+	const stat = fs.lstatSync(file, { throwIfNoEntry: false });
+	if (!stat) return void 0;
+	if (!stat.isFile()) throw new Error(`Invalid stylesheet ownership file: ${file}`);
+	const value = JSON.parse(fs.readFileSync(file, "utf8"));
+	if (!object(value) || value.version !== 1 || !name(value.entry) || entry !== void 0 && value.entry !== entry || value.current !== void 0 && !generation(value.current) || !Array.isArray(value.retained) || !value.retained.every((item) => generation(item) && timestamp(item.retiredAt)) || !object(value.owned) || !Object.entries(value.owned).every(([file, item]) => assetName(file) && validIdentity(item) && object(item) && hash(item.hash) && timestamp(item.createdAt)) || value.pending !== void 0 && (!object(value.pending) || !generation(value.pending.generation) || !validIdentity(value.pending.entryIdentity) || !temporaryName(value.pending.entryTemporary) || !object(value.pending.temporaries) || !Object.entries(value.pending.temporaries).every(([file, item]) => temporaryName(file) && validIdentity(item)))) throw new Error(`Invalid stylesheet ownership file: ${file}`);
+	return value;
+}
+function promote(state, next, now) {
+	if (state.current && (state.current.hash !== next.hash || JSON.stringify(state.current.assets) !== JSON.stringify(next.assets))) state.retained.unshift({
+		...state.current,
+		retiredAt: now
+	});
+	state.current = next;
+	delete state.pending;
+}
+function referenced(state) {
+	return [
+		state.current,
+		...state.retained,
+		state.pending?.generation
+	].flatMap((item) => item?.assets ?? []);
+}
+/** Called inside the cooperating CLI publication gate. */
+function publishOwnedStylesheet(entry, css, assets, outputFiles, now = Date.now()) {
+	entry = path.resolve(entry);
+	const directory = path.dirname(entry);
+	const stateFile = stylesheetStatePath(entry);
+	outputFiles.add(stateFile);
+	const state = readState(stateFile, path.basename(entry)) ?? {
+		version: 1,
+		entry: path.basename(entry),
+		retained: [],
+		owned: {}
+	};
+	const save = () => {
+		const stat = fs.lstatSync(stateFile, { throwIfNoEntry: false });
+		if (stat) {
+			if (!stat.isFile()) throw new Error(`Invalid stylesheet ownership file: ${stateFile}`);
+			fs.accessSync(stateFile, fs.constants.W_OK);
+		}
+		replaceStylesheetFile(stateFile, Buffer.from(JSON.stringify(state, null, 2) + "\n"), outputFiles, 384);
+	};
+	const target = resolveEntryTarget(entry);
+	if (state.pending) {
+		const entryTemporary = path.join(path.dirname(target), state.pending.entryTemporary);
+		if (sameIdentity(identity(entryTemporary), state.pending.entryIdentity)) fs.unlinkSync(entryTemporary);
+		for (const [file, expected] of Object.entries(state.pending.temporaries)) {
+			const temporary = path.join(directory, file);
+			if (sameIdentity(identity(temporary), expected)) fs.unlinkSync(temporary);
+		}
+		if (sameIdentity(identity(target), state.pending.entryIdentity) && digest(fs.readFileSync(target)) === state.pending.generation.hash) promote(state, state.pending.generation, now);
+		else delete state.pending;
+		save();
+	}
+	const names = [...assets.keys()].map((file) => {
+		if (path.dirname(file) !== directory || !assetName(path.basename(file))) throw new Error(`Invalid stylesheet asset path: ${file}`);
+		outputFiles.add(file);
+		return path.basename(file);
+	}).sort();
+	const next = {
+		hash: digest(css),
+		assets: names
+	};
+	const unchanged = state.current?.hash === next.hash && JSON.stringify(state.current.assets) === JSON.stringify(names) && fs.existsSync(target) && digest(fs.readFileSync(target)) === next.hash && [...assets].every(([file, bytes]) => identity(file) && fs.readFileSync(file).equals(bytes));
+	if (!unchanged) publishStylesheet(entry, css, assets, outputFiles, {
+		beforePublish(created, temporary) {
+			for (const [file, prepared] of created) state.owned[path.basename(file)] = {
+				...identity(prepared),
+				hash: digest(assets.get(file)),
+				createdAt: now
+			};
+			state.pending = {
+				generation: next,
+				entryIdentity: identity(temporary),
+				entryTemporary: path.basename(temporary),
+				temporaries: Object.fromEntries([...created.values()].map((file) => [path.basename(file), identity(file)]))
+			};
+			save();
+		},
+		afterPublish() {
+			promote(state, next, now);
+			save();
+		}
+	});
+	const beforeCleanup = JSON.stringify(state);
+	state.retained = state.retained.filter((item, index) => index === 0 || now - item.retiredAt < 864e5);
+	const protectedFiles = new Set(referenced(state));
+	try {
+		for (const file of fs.readdirSync(directory)) {
+			if (!file.startsWith(".") || !file.endsWith(suffix) || path.join(directory, file) === stateFile) continue;
+			const other = readState(path.join(directory, file));
+			if (other) for (const asset of referenced(other)) protectedFiles.add(asset);
+		}
+		for (const [file, owned] of Object.entries(state.owned)) {
+			const target = path.join(directory, file);
+			if (!sameIdentity(identity(target), owned) || digest(fs.readFileSync(target)) !== owned.hash) delete state.owned[file];
+			else if (!protectedFiles.has(file) && now - owned.createdAt >= 864e5) {
+				fs.unlinkSync(target);
+				delete state.owned[file];
+			}
+		}
+		if (JSON.stringify(state) !== beforeCleanup) save();
+	} catch (error) {
+		process.stderr.write(`Cannot clean stylesheet assets: ${error}\n`);
+	}
+	return !unchanged;
+}
+export { ASSET_RETENTION_MS, publishOwnedStylesheet, stylesheetStatePath };

package/dist/bin/index.js

@@ -1,6 +1,5 @@
 #!/usr/bin/env node
 import runProgram from "../core.js";
-//#region src/bin/index.ts
+// src/bin/index.ts
 await runProgram();
-//#endregion
 export {};

package/dist/constants.js

@@ -1,4 +1,3 @@
-//#region src/constants.ts
+// src/constants.ts
 const DEFAULT_SCAN_OUTPUT = "master.css";
-//#endregion
 export { DEFAULT_SCAN_OUTPUT };

package/dist/core.js

@@ -2,38 +2,35 @@ import { DEFAULT_SCAN_OUTPUT } from "./constants.js";
 import { readFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { Command } from "commander";
-//#region src/core.ts
-const __dirname = dirname(fileURLToPath(import.meta.url));
+import { Command, Option } from "commander";
+// src/core.ts
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
 const pkg = JSON.parse(readFileSync(resolve(__dirname, "../package.json"), "utf8"));
-const removedCommands = /* @__PURE__ */ new Set([
-	"extract",
-	"render",
-	"scan"
-]);
-function errorRemovedCommand(program, command) {
-	program.error(`The "${command}" command was removed. Use "${pkg.name}" directly, for example "${pkg.name} -w".`);
-}
 async function runProgram(argv = process.argv) {
 	const program = new Command();
-	program.name(pkg.name).description(pkg.description).version(pkg.version || "0.0.0").argument("[source paths...]", "The glob pattern paths to scan sources").option("-w, --watch", "Watch file changes and generate CSS rules.").option("-o, --output <path>", "Specify your CSS file output path", DEFAULT_SCAN_OUTPUT).option("-v, --verbose <level>", "Verbose logging 0~N", "1").option("--no-export", "Print only CSS results.").action(async (sourcePaths, options) => {
-		const removedCommand = sourcePaths[0];
-		if (removedCommand && removedCommands.has(removedCommand)) errorRemovedCommand(program, removedCommand);
-		const { default: runScan } = await import("./scan.js");
-		return runScan(sourcePaths, options);
+	program.name("master-css").description(pkg.description).version(pkg.version || "0.0.0");
+	program.command("generate").description("Generate CSS from project source files.").argument("[source paths...]", "The glob pattern paths to scan sources").option("-w, --watch", "Watch file changes and generate CSS rules.").option("-o, --output <path>", "Specify your CSS file output path", DEFAULT_SCAN_OUTPUT).option("-v, --verbose <level>", "Verbose logging 0~N", "1").addOption(new Option("--binding <binding>", "Execution binding: auto, native, or wasm.").choices([
+		"auto",
+		"native",
+		"wasm"
+	]).default("auto")).option("--no-export", "Print only CSS results.").option("--strict", "Fail CSS syntax or value validation before publishing any generated assets.").option("--prune-native-css", "Prune unused native CSS only in project-owned source files.").action(async (sourcePaths, options) => {
+		const { default: runGenerate } = await import("./generate.js");
+		return runGenerate(sourcePaths, options);
 	});
-	program.command("lint").description("Run machine-readable Master CSS diagnostics for source files.").argument("[source paths...]", "The glob pattern paths to lint sources").option("--stdin", "Read source content from stdin.").option("--stdin-filepath <path>", "File path used to infer the stdin source language.").option("--fix", "Apply safe class-list fixes to files.").option("--fix-dry-run", "Return fix proposals without writing files.").option("--fix-directives", "Allow structural directive fixes when --fix writes files.").option("--format <format>", "Diagnostic output format: json or stylish.", "json").option("--rules <rules>", "Comma-separated lint rules, \"recommended\", or \"all\".").option("--exit-code <mode>", "Exit code behavior: diagnostics or never.", "diagnostics").option("--max-warnings <number>", "Exit with a non-zero status if warnings exceed this count.").action(async (sourcePaths, options) => {
+	program.command("lint").description("Run machine-readable Master CSS diagnostics for source files.").argument("[source paths...]", "The glob pattern paths to lint sources").option("--stdin", "Read source content from stdin.").option("--stdin-filepath <path>", "File path used to infer the stdin source language.").option("--fix", "Apply safe class-list fixes to files.").option("--fix-dry-run", "Return fix proposals without writing files.").option("--format <format>", "Diagnostic output format: json or stylish.", "json").option("--rules <rules>", "Comma-separated lint rules, \"recommended\", or \"all\".").option("--exit-code <mode>", "Exit code behavior: diagnostics or never.", "diagnostics").option("--max-warnings <number>", "Exit with a non-zero status if warnings exceed this count.").action(async (sourcePaths, options) => {
 		const { default: runLint } = await import("./lint.js");
 		await runLint(sourcePaths, options);
 	});
-	program.command("inspect").description("Inspect scanner state, stylesheet entries, generated CSS, and missing CSS.").argument("[source paths...]", "The glob pattern paths to inspect").option("--classes <classes>", "Whitespace-separated class names to verify in generated CSS.").option("--include-css", "Include generated CSS text in the JSON report.").option("--format <format>", "Diagnostic output format: json or stylish.", "json").option("--exit-code <mode>", "Exit code behavior: diagnostics or never.", "diagnostics").option("--max-warnings <number>", "Exit with a non-zero status if warnings exceed this count.").action(async (sourcePaths, options) => {
+	program.command("inspect").description("Inspect scanner state, stylesheet entries, generated CSS, and missing CSS.").argument("[source paths...]", "The glob pattern paths to inspect; with --design-system, route and component stylesheets to add").option("--classes <classes>", "Whitespace-separated class names to verify in generated CSS.").option("--include-css", "Include generated CSS text in the JSON report.").option("--design-system", "Inspect token references, definition metadata, policy and collisions in managed and route stylesheets.").option("--design-system-options <path>", "JSON file containing version: 1, optional metadata and rawValuePolicy.").option("--snapshot", "Capture a resolved project snapshot as JSON.").option("--compare <snapshot>", "Compare a saved JSON snapshot with the current project.").option("--format <format>", "Diagnostic output format: json or stylish.", "json").option("--exit-code <mode>", "Exit code behavior: diagnostics or never.", "diagnostics").option("--max-warnings <number>", "Exit with a non-zero status if warnings exceed this count.").action(async (sourcePaths, options) => {
 		const { default: runInspect } = await import("./inspect.js");
 		await runInspect(sourcePaths, options);
 	});
-	const firstArgument = argv[2];
-	if (firstArgument && removedCommands.has(firstArgument)) errorRemovedCommand(program, firstArgument);
+	program.command("suggest").description("Suggest classes for a CSS declaration block without editing files.").argument("[declarations]", "A quoted CSS declaration block, without a selector or braces.").option("--stdin", "Read the declaration block from stdin instead of an argument.").option("--cwd <path>", "Project root used to load the active manifest.", ".").action(async (declarations, options) => {
+		const { default: runSuggest } = await import("./suggest.js");
+		await runSuggest(declarations, options);
+	});
 	await program.parseAsync(argv);
 	return program;
 }
-//#endregion
 export { runProgram as default };

package/dist/dependency-rebuild.js

@@ -0,0 +1,43 @@
+import { readFileSync, statSync } from "node:fs";
+import { resolve } from "node:path";
+import { createHash } from "node:crypto";
+// src/dependency-rebuild.ts
+const identity = (stat) => [
+	stat.dev,
+	stat.ino,
+	stat.mode,
+	stat.size,
+	stat.mtimeNs,
+	stat.ctimeNs
+].join(":");
+function fileRevision(file) {
+	try {
+		const stat = statSync(file, {
+			bigint: true,
+			throwIfNoEntry: false
+		});
+		if (!stat?.isFile()) return void 0;
+		const hash = createHash("sha256").update(readFileSync(file)).digest("hex");
+		const after = statSync(file, {
+			bigint: true,
+			throwIfNoEntry: false
+		});
+		return after && identity(stat) === identity(after) ? `${identity(stat)}:${hash}` : void 0;
+	} catch (error) {
+		if (["ENOENT", "ENOTDIR"].includes(error.code ?? "")) return void 0;
+		throw error;
+	}
+}
+/** Called inside the watch queue, so each comparison follows the previous rebuild. */
+function createDependencyRebuild(rebuild, ready) {
+	const completed = /* @__PURE__ */ new Map();
+	return async (file) => {
+		const absolute = resolve(file);
+		const revision = fileRevision(absolute);
+		if (ready() && revision !== void 0 && completed.get(absolute) === revision) return;
+		completed.delete(absolute);
+		await rebuild();
+		if (revision !== void 0) completed.set(absolute, revision);
+	};
+}
+export { createDependencyRebuild };