@master/css-cli 2.0.0-rc.75 → 2.0.0-rc.77

package/README.md

@@ -84,6 +84,71 @@ Options:
 | `-v, --verbose <level>` | `number` | `1` | Logging level. Use `0` to silence terminal output. |
 | `-w, --watch` | `boolean` | `false` | Watch files and rebuild continuously. |
 
+### `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:
+
+```bash
+cat src/App.tsx | npx @master/css-cli lint --exit-code never --stdin --stdin-filepath src/App.tsx
+```
+
+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. |
+
 ## Related docs
 
 - [Static rendering guide](https://rc.css.master.co/guide/installation)

package/dist/core.js

@@ -22,6 +22,14 @@ async function runProgram(argv = process.argv) {
 		const { default: runScan } = await import("./scan.js");
 		return runScan(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) => {
+		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) => {
+		const { default: runInspect } = await import("./inspect.js");
+		await runInspect(sourcePaths, options);
+	});
 	const firstArgument = argv[2];
 	if (firstArgument && removedCommands.has(firstArgument)) errorRemovedCommand(program, firstArgument);
 	await program.parseAsync(argv);

package/dist/inspect.js

@@ -0,0 +1,38 @@
+import path from "node:path";
+import { createMasterCSSInspectionReport } from "@master/css-diagnostics";
+//#region src/inspect.ts
+function parseMaxWarnings(value) {
+	if (value === void 0) return Number.POSITIVE_INFINITY;
+	const maxWarnings = Number(value);
+	return Number.isFinite(maxWarnings) && maxWarnings >= 0 ? maxWarnings : 0;
+}
+function formatStylish(report) {
+	const lines = [
+		`Scanned ${report.summary.files} files, ${report.summary.stylesheets} stylesheet entries.`,
+		`Classes: ${report.scanner.counts.valid} valid, ${report.scanner.counts.invalid} invalid, ${report.scanner.counts.usedNative} native.`,
+		`CSS: ${report.css.bytes} bytes.`
+	];
+	if (report.missingCSS.checked.length) lines.push(`Missing CSS: ${report.missingCSS.missing.length}/${report.missingCSS.checked.length}`);
+	for (const diagnostic of report.diagnostics) lines.push(`${diagnostic.severity.toUpperCase()} ${diagnostic.code}: ${diagnostic.message}`);
+	return `${lines.join("\n")}\n`;
+}
+function outputReport(report, format) {
+	if (format === "stylish") process.stdout.write(formatStylish(report));
+	else console.log(JSON.stringify(report, null, 2));
+}
+async function runInspect(specifiedSourcePaths = [], options = {}) {
+	const cwd = path.resolve(options.cwd || process.cwd());
+	const format = options.format || "json";
+	const exitCode = options.exitCode || "diagnostics";
+	const report = await createMasterCSSInspectionReport({
+		cwd,
+		patterns: specifiedSourcePaths.length ? specifiedSourcePaths : void 0,
+		classes: options.classes,
+		includeCss: Boolean(options.includeCss)
+	});
+	outputReport(report, format);
+	if (exitCode !== "never" && (report.summary.errors || report.summary.warnings > parseMaxWarnings(options.maxWarnings))) process.exitCode = 1;
+	return report;
+}
+//#endregion
+export { runInspect as default };

package/dist/lint.js

@@ -0,0 +1,160 @@
+import fs from "node:fs";
+import path from "node:path";
+import { createCSSWithNativeDeclarations } from "@master/css-validator";
+import { fixMasterCSSContent, lintMasterCSSContent, resolveMasterCSSLintRules, summarizeMasterCSSLintFiles } from "@master/css-lint";
+import { loadProjectManifest } from "@master/css-project/manifest";
+import fg from "fast-glob";
+//#region src/lint.ts
+const REPORT_VERSION = 1;
+const DEFAULT_SOURCE_PATTERNS = ["**/*.{html,htm,js,jsx,cjs,ts,tsx,mts,cts,svelte,astro,vue,md,mdx,pug,php,css,scss,less}"];
+const DEFAULT_IGNORE_PATTERNS = ["**/node_modules/**", "node_modules"];
+function normalizeSourcePatterns(specifiedSourcePaths) {
+	return specifiedSourcePaths?.length ? specifiedSourcePaths : DEFAULT_SOURCE_PATTERNS;
+}
+function normalizeGlobPatterns(patterns) {
+	return patterns.map((pattern) => pattern.replace(/\\/g, "/"));
+}
+function resolveSourcePaths(cwd, sourcePatterns, ignore = []) {
+	return fg.sync(normalizeGlobPatterns(sourcePatterns), {
+		cwd,
+		ignore: normalizeGlobPatterns(ignore),
+		onlyFiles: true
+	}).filter(Boolean);
+}
+function parseMaxWarnings(value) {
+	if (value === void 0) return Number.POSITIVE_INFINITY;
+	const maxWarnings = Number(value);
+	return Number.isFinite(maxWarnings) && maxWarnings >= 0 ? maxWarnings : 0;
+}
+function createManifestDiagnostic(cwd, error) {
+	return {
+		ruleId: "manifest",
+		code: "manifest-loading-error",
+		severity: "error",
+		message: `Failed to load Master CSS manifest: ${error instanceof Error ? error.message : String(error)}`,
+		range: {
+			start: 0,
+			end: 0
+		},
+		loc: {
+			start: {
+				line: 1,
+				column: 1
+			},
+			end: {
+				line: 1,
+				column: 1
+			}
+		},
+		source: "Master CSS",
+		sourceKind: "manifest",
+		data: { cwd }
+	};
+}
+function createManifestFileResult(cwd, diagnostics) {
+	return {
+		filePath: cwd,
+		languageId: "manifest",
+		sourceKind: "manifest",
+		diagnostics
+	};
+}
+function createReport(cwd, manifest, files) {
+	return {
+		version: REPORT_VERSION,
+		cwd,
+		manifest,
+		files,
+		summary: summarizeMasterCSSLintFiles(files)
+	};
+}
+function formatStylish(report) {
+	const lines = [];
+	for (const result of report.files) {
+		if (!result.diagnostics.length) continue;
+		lines.push(result.filePath);
+		for (const diagnostic of result.diagnostics) lines.push(`  ${diagnostic.loc.start.line}:${diagnostic.loc.start.column}  ${diagnostic.severity}  ${diagnostic.message}  ${diagnostic.ruleId ? `@master/css/${diagnostic.ruleId}` : diagnostic.code}`);
+	}
+	return lines.length ? `${lines.join("\n")}\n` : "";
+}
+function outputReport(report, format) {
+	if (format === "stylish") {
+		const output = formatStylish(report);
+		if (output) process.stdout.write(output);
+	} else console.log(JSON.stringify(report, null, 2));
+}
+function resolveSourceInputs(cwd, specifiedSourcePaths, options) {
+	if (options.stdin) return [{
+		filePath: path.resolve(cwd, options.stdinFilepath || "stdin.html"),
+		content: fs.readFileSync(0, "utf8"),
+		stdin: true
+	}];
+	return resolveSourcePaths(cwd, normalizeSourcePatterns(specifiedSourcePaths), specifiedSourcePaths.length ? [] : DEFAULT_IGNORE_PATTERNS).map((source) => {
+		const filePath = path.resolve(cwd, source);
+		return {
+			filePath,
+			content: fs.readFileSync(filePath, "utf8")
+		};
+	});
+}
+function lintInputs(inputs, css, rules) {
+	return inputs.map((input) => lintMasterCSSContent({
+		content: input.content,
+		filePath: input.filePath,
+		css,
+		rules
+	})).filter((result) => result.diagnostics.length);
+}
+function applyFileFixes(inputs, css, rules, includeDirectiveFixes) {
+	for (const input of inputs) {
+		if (input.stdin) continue;
+		const fixed = fixMasterCSSContent({
+			content: input.content,
+			filePath: input.filePath,
+			css,
+			rules,
+			includeDirectiveFixes
+		});
+		if (fixed !== input.content) {
+			fs.writeFileSync(input.filePath, fixed);
+			input.content = fixed;
+		}
+	}
+}
+async function runLint(specifiedSourcePaths = [], options = {}) {
+	const cwd = path.resolve(options.cwd || process.cwd());
+	const format = options.format || "json";
+	const exitCode = options.exitCode || "diagnostics";
+	const rules = resolveMasterCSSLintRules(options.rules);
+	const inputs = resolveSourceInputs(cwd, specifiedSourcePaths, options);
+	let manifest;
+	let files;
+	try {
+		const manifestResult = await loadProjectManifest(cwd);
+		const css = createCSSWithNativeDeclarations(manifestResult.manifest);
+		manifest = {
+			status: "loaded",
+			entries: manifestResult.entries,
+			diagnostics: []
+		};
+		files = lintInputs(inputs, css, rules);
+		if (options.fix && !options.fixDryRun) {
+			applyFileFixes(inputs, css, rules, Boolean(options.fixDirectives));
+			files = lintInputs(inputs, css, rules);
+		}
+	} catch (error) {
+		const diagnostic = createManifestDiagnostic(cwd, error);
+		manifest = {
+			status: "error",
+			entries: [],
+			diagnostics: [diagnostic]
+		};
+		files = [createManifestFileResult(cwd, [diagnostic])];
+	}
+	const report = createReport(cwd, manifest, files);
+	outputReport(report, format);
+	if (exitCode !== "never" && (report.summary.errors || report.summary.warnings > parseMaxWarnings(options.maxWarnings))) process.exitCode = 1;
+	return report;
+}
+//#endregion
+export { runLint as default };

package/package.json

@@ -32,17 +32,21 @@
     "commander": "^14.0.3",
     "consola": "^3.4.2",
     "fast-glob": "^3.3.3",
-    "@master/css": "^2.0.0-rc.75",
-    "@master/css-project": "^2.0.0-rc.75",
-    "@master/css-scanner": "^2.0.0-rc.75",
-    "@master/css-stylesheet": "^2.0.0-rc.75"
+    "@master/css": "^2.0.0-rc.77",
+    "@master/css-diagnostics": "^2.0.0-rc.77",
+    "@master/css-lint": "^2.0.0-rc.77",
+    "@master/css-lexer": "^2.0.0-rc.77",
+    "@master/css-project": "^2.0.0-rc.77",
+    "@master/css-scanner": "^2.0.0-rc.77",
+    "@master/css-language": "^2.0.0-rc.77",
+    "@master/css-stylesheet": "^2.0.0-rc.77",
+    "@master/css-validator": "^2.0.0-rc.77"
   },
   "devDependencies": {
     "@types/bytes": "^3.1.5",
-    "upath": "^2.0.1",
-    "@master/css-lexer": "^2.0.0-rc.75"
+    "upath": "^2.0.1"
   },
-  "version": "2.0.0-rc.75",
+  "version": "2.0.0-rc.77",
   "scripts": {
     "build": "tsdown --config ../../shared/tsdown-package.config.ts",
     "dev": "tsdown --config ../../shared/tsdown-package.config.ts --watch",