@fractaldesign/fractalstyler 0.0.0-stage → 0.9.0

package/lint/cli.mjs

@@ -0,0 +1,212 @@
+#!/usr/bin/env node
+// =============================================================================
+// fractalstyler lint — the design system contract linter & agent guard.
+//
+// Verifies code against the styling system contract:
+//   - Svelte files: no scoped <style>, no style="..." attributes, all classes verified
+//   - Stylesheets: token purity (no raw hex, >2px budget, valid var(--tokens))
+//   - Sass files: valid interpolation, radius ladder usage
+//
+// Supports:
+//   Self mode:     node lint/cli.mjs              (inside fractalstyler repo)
+//   Consumer mode: node lint/cli.mjs <dir>        (linting any project using fractalstyler)
+//   Flags:         --json (agent/CI output), --own <file>, --registry <file>
+// =============================================================================
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { loadRegistry } from './lib/registry.mjs';
+import { lintSvelteFile } from './lib/svelte-linter.mjs';
+import { TokenLinter } from './lib/token-linter.mjs';
+import { lintUninterpolatedFunctions, lintHardcodedRadius } from './lib/sass-linter.mjs';
+import { reportDiagnostics } from './lib/agent-reporter.mjs';
+
+const PKG_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+
+function usage() {
+	console.log(`Usage:
+  fractalstyler lint              # self mode: audit fractalstyler package
+  fractalstyler lint <dir>        # consumer mode: audit project directory
+Options:
+  --own <file>    extension stylesheet (default <dir>/_09_own.sass)
+  --registry <f>  registry.json override
+  --json          machine-readable JSON diagnostics for agents and CI
+  --help          show this help message`);
+}
+
+const SVELTE = /\.svelte$/;
+const STYLESHEET = /\.(sass|scss|css)$/;
+
+function walk(dir, filter, out = [], base = dir) {
+	if (!fs.existsSync(dir)) return out;
+	for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+		if (
+			entry.name === 'node_modules' ||
+			entry.name === '.svelte-kit' ||
+			entry.name === 'dist' ||
+			entry.name === '.git' ||
+			entry.name === 'reserve' ||
+			entry.name.startsWith('.')
+		)
+			continue;
+
+		const full = path.join(base, entry.name);
+		if (entry.isDirectory()) walk(full, filter, out, full);
+		else if (filter(entry.name)) out.push(full);
+	}
+	return out;
+}
+
+const rel = (root, file) => path.relative(root, file);
+
+function harvestOwnClasses(content) {
+	const names = new Set();
+	for (const m of content.matchAll(/(?:^|[\s,{}])(\.)([a-zA-Z][a-zA-Z0-9_-]*)/g)) {
+		names.add(m[2]);
+	}
+	return names;
+}
+
+function collectLocalProperties(stylesheets) {
+	const names = new Set();
+	for (const file of stylesheets) {
+		try {
+			const content = fs.readFileSync(file, 'utf8');
+			for (const m of content.matchAll(/(--[a-zA-Z0-9_-]+)\s*:/g)) {
+				names.add(m[1]);
+			}
+		} catch {}
+	}
+	return names;
+}
+
+async function lintSelf(flags) {
+	const diagnostics = [];
+	const { classes, tokens, stems } = loadRegistry(PKG_ROOT, flags.registry);
+	const tokenLinter = new TokenLinter(PKG_ROOT, { tokens });
+
+	// 1. Lint Svelte files in src/
+	const svelteFiles = walk(path.join(PKG_ROOT, 'src'), (f) => SVELTE.test(f));
+	for (const file of svelteFiles) {
+		const source = fs.readFileSync(file, 'utf8');
+		const relPath = rel(PKG_ROOT, file);
+		const result = lintSvelteFile(relPath, source, { allowlist: classes, stems });
+		diagnostics.push(...result.diagnostics);
+	}
+
+	// 2. Lint Sass files in src/lib/styles
+	const sassFiles = walk(path.join(PKG_ROOT, 'src', 'lib', 'styles'), (f) => STYLESHEET.test(f));
+	for (const file of sassFiles) {
+		const source = fs.readFileSync(file, 'utf8');
+		const relPath = rel(PKG_ROOT, file);
+		diagnostics.push(...lintUninterpolatedFunctions(relPath, source));
+	}
+
+	return diagnostics;
+}
+
+async function lintConsumer(targetDir, flags) {
+	const diagnostics = [];
+	const targetRoot = path.resolve(targetDir);
+
+	// Load canonical registry from fractalstyler package
+	const { classes: canonicalClasses, tokens, stems } = loadRegistry(PKG_ROOT, flags.registry);
+
+	// Find consumer's own extension classes
+	const ownFile = flags.own
+		? path.resolve(flags.own)
+		: path.join(targetRoot, 'src', 'lib', 'styles', '_09_own.sass');
+
+	const ownClasses = new Set();
+	if (fs.existsSync(ownFile)) {
+		const ownContent = fs.readFileSync(ownFile, 'utf8');
+		for (const cls of harvestOwnClasses(ownContent)) {
+			ownClasses.add(cls);
+		}
+	}
+
+	// Full allowlist = canonical registry union with own classes
+	const allowlist = new Set([...canonicalClasses, ...ownClasses]);
+
+	// Collect locally defined CSS variables across target
+	const stylesheets = walk(targetRoot, (f) => STYLESHEET.test(f));
+	const localProps = collectLocalProperties(stylesheets);
+
+	const tokenLinter = new TokenLinter(targetRoot, { tokens });
+
+	// Lint Svelte files
+	const svelteFiles = walk(targetRoot, (f) => SVELTE.test(f));
+	for (const file of svelteFiles) {
+		const source = fs.readFileSync(file, 'utf8');
+		const relPath = rel(targetRoot, file);
+		const result = lintSvelteFile(relPath, source, { allowlist, stems });
+		diagnostics.push(...result.diagnostics);
+	}
+
+	// Lint stylesheets (skip canonical system files if present inside target)
+	for (const file of stylesheets) {
+		const base = path.basename(file);
+		// Layer partials _00 to _08 belong to system, and so do the palette
+		// modules (raw hex ladders by design — they are where the hex lives);
+		// _09_own belongs to the user and stays linted.
+		if (
+			/^_(0[0-8]|config|tokens|base|dimensions|containers|layouts|shells|visuals|interactions|typography)/.test(base) ||
+			/^(colorpacks|themeplates|index)\b/.test(base)
+		) {
+			continue;
+		}
+
+		const source = fs.readFileSync(file, 'utf8');
+		const relPath = rel(targetRoot, file);
+
+		diagnostics.push(...tokenLinter.lintFile(relPath, source, localProps));
+		diagnostics.push(...lintUninterpolatedFunctions(relPath, source));
+		diagnostics.push(...lintHardcodedRadius(relPath, source));
+	}
+
+	return diagnostics;
+}
+
+async function main() {
+	const args = process.argv.slice(2);
+	const flags = { json: false, own: null, registry: null };
+	const positional = [];
+
+	for (let i = 0; i < args.length; i++) {
+		const arg = args[i];
+		if (arg === '--help' || arg === '-h') {
+			usage();
+			process.exit(0);
+		} else if (arg === '--json') {
+			flags.json = true;
+		} else if (arg === '--own' && i + 1 < args.length) {
+			flags.own = args[++i];
+		} else if (arg === '--registry' && i + 1 < args.length) {
+			flags.registry = args[++i];
+		} else if (!arg.startsWith('-')) {
+			positional.push(arg);
+		}
+	}
+
+	const targetDir = positional[0] === 'lint' ? positional[1] : positional[0];
+
+	let diagnostics = [];
+	try {
+		if (!targetDir || targetDir === '.') {
+			diagnostics = await lintSelf(flags);
+		} else {
+			diagnostics = await lintConsumer(targetDir, flags);
+		}
+
+		reportDiagnostics(diagnostics, { json: flags.json });
+		const hasErrors = diagnostics.some((d) => d.severity === 'error');
+		process.exit(hasErrors ? 1 : 0);
+	} catch (err) {
+		console.error(`\x1b[31mError during lint: ${err.message}\x1b[0m`);
+		if (process.env.DEBUG) console.error(err);
+		process.exit(2);
+	}
+}
+
+main();

package/lint/lib/agent-reporter.mjs

@@ -0,0 +1,51 @@
+// =============================================================================
+// Agent-first diagnostic formatter.
+//
+// Box-drawing output is deliberate: it survives terminal piping and gives
+// coding agents an unambiguous, self-describing block per violation, with a
+// prescriptive fix.
+// =============================================================================
+
+const LABEL = 'FRACTALSTYLER';
+
+export function reportDiagnostics(diagnostics, options = {}) {
+	const { json = false, ok = 'All styling system contracts verified. 0 violations found.' } = options;
+
+	if (json) {
+		console.log(JSON.stringify(diagnostics, null, 2));
+		return;
+	}
+
+	if (diagnostics.length === 0) {
+		console.log(`\n\x1b[32m✔ ${ok}\x1b[0m\n`);
+		return;
+	}
+
+	console.log(
+		`\n\x1b[1m\x1b[31m[${LABEL}] Found ${diagnostics.length} system contract violation${diagnostics.length > 1 ? 's' : ''}:\x1b[0m\n`
+	);
+
+	for (const d of diagnostics) {
+		const isError = d.severity === 'error';
+		const badgeColor = isError ? '\x1b[31m' : '\x1b[33m';
+		const loc = d.line ? `${d.file}:${d.line}${d.column ? `:${d.column}` : ''}` : d.file;
+
+		console.log(`${badgeColor}┌─ [${LABEL} ${d.severity.toUpperCase()}: ${d.rule}] ─────────────────────────────────────────────\x1b[0m`);
+		console.log(`│ \x1b[1mLocation:\x1b[0m ${loc}`);
+		console.log(`│ \x1b[1mFound:\x1b[0m    \x1b[36m${d.found}\x1b[0m`);
+		console.log(`├─ \x1b[1m[SYSTEM RATIONALE]\x1b[0m`);
+		console.log(`│  ${d.rationale}`);
+		console.log(`├─ \x1b[1m\x1b[32m[PRESCRIPTIVE AGENT FIX]\x1b[0m`);
+
+		const suggestionLines = String(d.suggestion || '').split('\n');
+		for (const sLine of suggestionLines) {
+			console.log(`│  \x1b[32m${sLine}\x1b[0m`);
+		}
+		console.log(`${badgeColor}└─────────────────────────────────────────────────────────────────────────────────\x1b[0m\n`);
+	}
+
+	const errors = diagnostics.filter((d) => d.severity === 'error').length;
+	const warnings = diagnostics.filter((d) => d.severity === 'warning').length;
+
+	console.log(`\x1b[1mResult: ${errors} error${errors === 1 ? '' : 's'}, ${warnings} warning${warnings === 1 ? '' : 's'}.\x1b[0m\n`);
+}

package/lint/lib/fuzzy.mjs

@@ -0,0 +1,45 @@
+// =============================================================================
+// Levenshtein distance & fuzzy match suggestions.
+// Zero dependencies. Used to suggest closest registered classes/tokens to agents.
+// =============================================================================
+
+function levenshtein(a, b) {
+	const m = a.length;
+	const n = b.length;
+	const dp = Array.from({ length: m + 1 }, () => new Array(n + 1).fill(0));
+
+	for (let i = 0; i <= m; i++) dp[i][0] = i;
+	for (let j = 0; j <= n; j++) dp[0][j] = j;
+
+	for (let i = 1; i <= m; i++) {
+		for (let j = 1; j <= n; j++) {
+			const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+			dp[i][j] = Math.min(
+				dp[i - 1][j] + 1,      // deletion
+				dp[i][j - 1] + 1,      // insertion
+				dp[i - 1][j - 1] + cost // substitution
+			);
+		}
+	}
+	return dp[m][n];
+}
+
+/**
+ * Finds closest matches in a candidates set or array.
+ * @param {string} target
+ * @param {Iterable<string>} candidates
+ * @param {number} maxResults
+ * @param {number} maxDistance
+ * @returns {string[]}
+ */
+export function findClosestMatches(target, candidates, maxResults = 3, maxDistance = 4) {
+	const scored = [];
+	for (const cand of candidates) {
+		const dist = levenshtein(target, cand);
+		if (dist <= maxDistance) {
+			scored.push({ cand, dist });
+		}
+	}
+	scored.sort((a, b) => a.dist - b.dist);
+	return scored.slice(0, maxResults).map((s) => s.cand);
+}

package/lint/lib/registry.mjs

@@ -0,0 +1,107 @@
+// =============================================================================
+// Registry loader — the source of truth for every class and token check.
+//
+// Reads registry.json and pairs it with compiled stylesheet verification
+// so loop-generated wildcard families (.gap-*, .pad-*, .radius-*) and exact
+// selectors are both known without guesswork.
+// =============================================================================
+
+import fs from 'node:fs';
+import path from 'node:path';
+import * as sass from 'sass';
+
+/**
+ * Loads the style registry for verification.
+ * @param {string} rootDir Root of the fractalstyler package or consumer project.
+ * @param {string} [registryPath] Path to registry.json override.
+ */
+export function loadRegistry(rootDir, registryPath) {
+	const defaultRegistry = path.join(rootDir, 'registry.json');
+	const regFile = registryPath || (fs.existsSync(defaultRegistry) ? defaultRegistry : path.join(rootDir, 'src', 'lib', 'data', 'registry.json'));
+
+	if (!fs.existsSync(regFile)) {
+		throw new Error(`registry.json not found at ${regFile} — run "pnpm registry" first.`);
+	}
+
+	const data = JSON.parse(fs.readFileSync(regFile, 'utf8'));
+	const classes = new Set();
+	const tokens = new Set();
+	const ownLayerClasses = new Set();
+	const layerIds = new Set();
+	const layerOf = new Map();
+	const fileOfLayer = new Map();
+	const stems = [];
+
+	// 1. Process registry.json (handles both array format and { layers: [...] } format)
+	if (Array.isArray(data)) {
+		for (const entry of data) {
+			const rawClass = (entry.class || '').replace(/^\./, '').trim();
+			if (!rawClass) continue;
+
+			if (rawClass.includes('*')) {
+				stems.push(rawClass.replace(/\*.*$/, ''));
+			} else {
+				classes.add(rawClass);
+			}
+
+			const layer = entry.layer || 'L0';
+			layerIds.add(layer);
+			layerOf.set(rawClass, layer);
+			if (entry.file) fileOfLayer.set(layer, entry.file);
+
+			if (layer.toLowerCase().includes('own') || (entry.file && entry.file.includes('own'))) {
+				ownLayerClasses.add(rawClass);
+			}
+		}
+	} else if (data.layers && Array.isArray(data.layers)) {
+		for (const layer of data.layers) {
+			const isOwn = /own/i.test(layer.id || '') || /own/i.test(layer.file || '');
+			layerIds.add(layer.id);
+			if (!fileOfLayer.has(layer.id)) fileOfLayer.set(layer.id, layer.file || layer.id);
+
+			for (const item of layer.items || []) {
+				if (item.kind === 'class') {
+					const name = item.name.replace(/^\./, '');
+					if (name.includes('*')) {
+						stems.push(name.replace(/\*.*$/, ''));
+					} else {
+						classes.add(name);
+					}
+					if (!layerOf.has(name)) layerOf.set(name, layer.id);
+					if (isOwn) ownLayerClasses.add(name);
+				} else if (item.kind === 'token') {
+					tokens.add(item.name);
+				}
+			}
+		}
+	}
+
+	// 2. Also harvest compiled stylesheet if index.sass exists (for exact wildcard matches)
+	const indexSass = path.join(rootDir, 'src', 'lib', 'styles', 'index.sass');
+	if (fs.existsSync(indexSass)) {
+		try {
+			const compiled = sass.compile(indexSass, { style: 'expanded' }).css;
+			for (const m of compiled.matchAll(/\.([a-zA-Z][\w-]*)/g)) {
+				classes.add(m[1]);
+			}
+			for (const m of compiled.matchAll(/(--[a-zA-Z0-9_-]+):/g)) {
+				tokens.add(m[1]);
+			}
+		} catch (e) {
+			// If standalone compile fails in consumer mode, fallback to registry.json
+		}
+	}
+
+	// 3. Fallback token extraction from _00_tokens.sass if tokens set is empty
+	if (tokens.size === 0) {
+		const tokenFile = path.join(rootDir, 'src', 'lib', 'styles', '_00_tokens.sass');
+		if (fs.existsSync(tokenFile)) {
+			const tokenContent = fs.readFileSync(tokenFile, 'utf8');
+			for (const m of tokenContent.matchAll(/(--[a-zA-Z0-9_-]+):/g)) {
+				tokens.add(m[1]);
+			}
+		}
+	}
+
+	return { classes, tokens, ownLayerClasses, layerIds, layerOf, fileOfLayer, stems };
+}

package/lint/lib/sass-linter.mjs

@@ -0,0 +1,71 @@
+// =============================================================================
+// Sass declaration linters for fractalstyler.
+//
+// 1. fs/sass-interpolation — Sass parses custom-property values literally.
+//    Functions like list.nth(...) or map.get(...) inside `--name: ...`
+//    must be wrapped in `#{...}` to be evaluated rather than emitted verbatim.
+//
+// 2. fs/hardcoded-radius — Corners should route through the radius ladder
+//    `var(--radius-*)` so theme shape modifiers can restyle them.
+// =============================================================================
+
+const SASS_NAMESPACED = /\b(?:map|list|math|color|string|meta|selector|sass)\.[a-z-]+\s*\(/;
+const SASS_CORE =
+	/\b(?:if|nth|append|join|zip|index|list-separator|is-bracketed|length|set-nth|unit|unitless|percentage|floor|ceil|abs|random|quote|unquote|str-length|str-insert|str-index|str-slice|to-upper-case|to-lower-case|type-of|comparable|call|get-function|inspect|variable-exists|function-exists|global-variable-exists|feature-exists|keywords|mix|lighten|darken|saturate|desaturate|grayscale|invert|opacify|fade-in|transparentize|fade-out|adjust-hue|scale-color|change-color|adjust-color|ie-hex-str|red|green|blue|hue|saturation|lightness|alpha|opacity)\s*\(/;
+
+export function lintUninterpolatedFunctions(relPath, content) {
+	const diagnostics = [];
+	content.split('\n').forEach((line, idx) => {
+		const cleanLine = line.replace(/\/\/.*$/, '').replace(/\/\*[\s\S]*?\*\//, '');
+		const decl = cleanLine.match(/(^|\s)(--[a-zA-Z0-9_-]+)\s*:\s*(.+)$/);
+		if (!decl) return;
+
+		const value = decl[3].replace(/#\{[\s\S]*?\}/g, '');
+		const hit = value.match(SASS_NAMESPACED) || value.match(SASS_CORE);
+		if (!hit) return;
+
+		diagnostics.push({
+			rule: 'fs/sass-interpolation',
+			severity: 'error',
+			file: relPath,
+			line: idx + 1,
+			column: line.indexOf(decl[2]) + 1,
+			found: `${decl[2]}: ${decl[3].trim()}`,
+			rationale:
+				'Sass parses custom-property values literally: this function call is NOT evaluated — its source text ships to the browser as the value. Only #{…} interpolation is evaluated inside a custom property.',
+			suggestion: `Wrap the function call in interpolation: ${decl[2]}: #{${decl[3].trim()}} — or compute the value into a Sass variable first.`
+		});
+	});
+	return diagnostics;
+}
+
+const RADIUS_OK = /^(?:0(?:px)?|inherit|initial|unset|var\(--radius[^)]*\))$/;
+
+export function lintHardcodedRadius(relPath, content) {
+	const diagnostics = [];
+	content.split('\n').forEach((line, idx) => {
+		const cleanLine = line.replace(/\/\/.*$/, '').replace(/\/\*[\s\S]*?\*\//, '');
+		const decl = cleanLine.match(/(^|\s)(border-radius)\s*:\s*(.+)$/);
+		if (!decl) return;
+
+		const bad = decl[3]
+			.replace(/#\{[^}]*\}/g, ' ')
+			.trim()
+			.split(/\s+/)
+			.filter((token) => token && !RADIUS_OK.test(token));
+		if (bad.length === 0) return;
+
+		diagnostics.push({
+			rule: 'fs/hardcoded-radius',
+			severity: 'warning',
+			file: relPath,
+			line: idx + 1,
+			column: line.indexOf(decl[2]) + 1,
+			found: `border-radius: ${decl[3].trim()}`,
+			rationale:
+				'Literal border-radius values are unreachable by the theme shape axis. Data attributes rewrite the --radius-* ladder.',
+			suggestion: `Route the corner through the ladder — var(--radius-xs/sm/md/bs/lg/xl) or system radius classes.`
+		});
+	});
+	return diagnostics;
+}

package/lint/lib/svelte-linter.mjs

@@ -0,0 +1,116 @@
+// =============================================================================
+// Svelte contract scanner for fractalstyler.
+//
+// Zero-dependency regex scanner that runs via CLI or in CI. Enforces:
+//   fs/no-in-component-styles — no scoped <style> blocks.
+//   fs/no-inline-styles       — no style="..." attributes.
+//   fs/unknown-class          — every class used in markup must exist in registry.
+// =============================================================================
+
+import { findClosestMatches } from './fuzzy.mjs';
+
+const CLASS_ATTR = /\sclass\s*=\s*(?:"([^"]*)"|'([^']*)')/g;
+const CLASS_DIRECTIVE = /\sclass:([a-zA-Z0-9_-]+)/g;
+const STYLE_BLOCK = /<style[\s>]/;
+const STYLE_ATTR = /\sstyle\s*=/;
+
+/**
+ * Lints a Svelte file for styling system compliance.
+ * @param {string} relPath
+ * @param {string} source
+ * @param {{ allowlist?: Set<string>, stems?: string[] }} [options]
+ * @returns {{ diagnostics: Array, classes: Set<string> }}
+ */
+export function lintSvelteFile(relPath, source, options = {}) {
+	const diagnostics = [];
+	const classes = new Set();
+	const { allowlist, stems = [] } = options;
+
+	// Rule 1: No scoped <style> blocks
+	if (STYLE_BLOCK.test(source)) {
+		const line = source.slice(0, source.search(STYLE_BLOCK)).split('\n').length;
+		diagnostics.push({
+			rule: 'fs/no-in-component-styles',
+			severity: 'error',
+			file: relPath,
+			line,
+			found: '<style> block detected',
+			rationale:
+				'Components must remain pure markup & logic. Scoped styles fragment the design system, block global theme changes, and leak ad-hoc CSS.',
+			suggestion:
+				'Remove the <style> block and express the design using fractalstyler classes. If a class is missing, add it to the designated layer in src/lib/styles or your _09_own.sass.'
+		});
+	}
+
+	// Strip <script> content first so JS assignments like `style = ...` are not flagged
+	const scriptStart = source.indexOf('<script');
+	let markup = source;
+	if (scriptStart !== -1) {
+		const scriptEnd = source.indexOf('</script>', scriptStart);
+		if (scriptEnd !== -1) {
+			markup = source.slice(0, scriptStart) + source.slice(scriptEnd + '</script>'.length);
+		}
+	}
+
+	// Rule 2: No inline style="..." attributes
+	if (STYLE_ATTR.test(markup)) {
+		const match = markup.match(STYLE_ATTR);
+		const line = markup.slice(0, match.index).split('\n').length;
+		diagnostics.push({
+			rule: 'fs/no-inline-styles',
+			severity: 'error',
+			file: relPath,
+			line,
+			found: match[0].trim(),
+			rationale:
+				'Inline styles are unconstrained ad-hoc CSS: invisible to the registry, unreachable by theme switches, and unaccountable to the design system.',
+			suggestion:
+				'Express the styling intent using canonical classes (e.g. .w-full, .pad-sm, .gap-md). Never patch elements with inline CSS.'
+		});
+	}
+
+	// Harvest classes
+	for (const m of markup.matchAll(CLASS_ATTR)) {
+		const value = m[1] ?? m[2] ?? '';
+		for (const name of value.split(/\s+/)) {
+			// Skip interpolated fragments (class="x {expr} y")
+			if (name && !/[{()}]/.test(name) && !name.startsWith('{')) {
+				classes.add(name);
+			}
+		}
+	}
+	for (const m of markup.matchAll(CLASS_DIRECTIVE)) {
+		classes.add(m[1]);
+	}
+
+	// Rule 3: Check unknown classes against allowlist if provided
+	if (allowlist && allowlist.size > 0) {
+		for (const cls of classes) {
+			// Check exact match, modifier, or stem match
+			const isAllowed =
+				allowlist.has(cls) ||
+				stems.some((stem) => cls.startsWith(stem)) ||
+				/-(mob|desk)$/.test(cls);
+
+			if (!isAllowed) {
+				const closest = findClosestMatches(cls, allowlist, 3, 4);
+				const suggestion =
+					closest.length > 0
+						? `Class ".${cls}" is not in the system registry. Did you mean one of these?\n  - .${closest.join('\n  - .')}`
+						: `Class ".${cls}" is not in the system registry. Compose using existing classes in REGISTRY.md, or add it to the appropriate system partial in src/lib/styles (or _09_own.sass).`;
+
+				diagnostics.push({
+					rule: 'fs/unknown-class',
+					severity: 'error',
+					file: relPath,
+					found: `.${cls}`,
+					rationale:
+						`The closed-world styling contract forbids ad-hoc or hallucinated classes. Every class must resolve to the verified system registry.`,
+					suggestion
+				});
+			}
+		}
+	}
+
+	return { diagnostics, classes };
+}