@fractaldesign/fractalstyler 0.0.0-stage → 0.9.0

package/lint/lib/token-linter.mjs

@@ -0,0 +1,97 @@
+// =============================================================================
+// Token-purity linter for fractalstyler.
+//
+// Enforces:
+//   fs/token-purity:
+//     - No raw hex colors (#fff, #123456) — all colors must resolve via tokens.
+//     - >2px pixel budget — arbitrary pixels break density and design scale.
+//     - No unmapped custom properties — var(--name) must resolve to a valid token.
+// =============================================================================
+
+import { findClosestMatches } from './fuzzy.mjs';
+
+const PX_BUDGET = 2; // 1-2px stays legal for hairlines and borders.
+
+export class TokenLinter {
+	/**
+	 * @param {string} rootDir
+	 * @param {{ tokens: Set<string> }} opts
+	 */
+	constructor(rootDir, opts) {
+		this.rootDir = rootDir;
+		this.validTokens = new Set(opts.tokens);
+	}
+
+	/**
+	 * Scans a stylesheet string.
+	 * @param {string} relPath
+	 * @param {string} content
+	 * @param {Set<string>} [localProperties] Locally defined custom properties in project.
+	 */
+	lintFile(relPath, content, localProperties = new Set()) {
+		const diagnostics = [];
+		const lines = content.split('\n');
+
+		lines.forEach((line, idx) => {
+			const lineNum = idx + 1;
+			const cleanLine = line.replace(/\/\/.*$/, '').replace(/\/\*[\s\S]*?\*\//, '').trim();
+			if (!cleanLine) return;
+
+			// Rule 1: No raw hex colors
+			for (const m of cleanLine.matchAll(/#[0-9a-fA-F]{3,8}\b/g)) {
+				diagnostics.push({
+					rule: 'fs/token-purity',
+					severity: 'error',
+					file: relPath,
+					line: lineNum,
+					column: m.index + 1,
+					found: m[0],
+					rationale:
+						'Raw hex colors bypass semantic theming. Every color must resolve through a system token (var(--bg), var(--text-primary), var(--brand), etc.) so light/dark mode and presets reach it.',
+					suggestion: `Replace "${m[0]}" with the semantic color token it expresses, or define it in _00_tokens.sass.`
+				});
+			}
+
+			// Rule 2: The px budget (>2px must come from dimension ladder or tokens)
+			for (const m of cleanLine.matchAll(/(?<![0-9a-zA-Z_.-])(-?\d+)px\b/g)) {
+				const px = parseInt(m[1], 10);
+				if (Math.abs(px) <= PX_BUDGET) continue;
+				diagnostics.push({
+					rule: 'fs/token-purity',
+					severity: 'error',
+					file: relPath,
+					line: lineNum,
+					column: m.index + 1,
+					found: m[0],
+					rationale:
+						'Arbitrary pixel dimensions bypass the dimension ladder and token scale. Only 1-2px (borders, outlines, hairlines) may be literal.',
+					suggestion: `Replace "${m[0]}" with the nearest system class (e.g. .gap-16, .pad-sm, .w-64) or a spacing/dimension token.`
+				});
+			}
+
+			// Rule 3: Unmapped variables
+			for (const vm of cleanLine.matchAll(/var\((--[a-zA-Z0-9_-]+)/g)) {
+				const varName = vm[1];
+				if (this.validTokens.has(varName) || localProperties.has(varName)) continue;
+				const closest = findClosestMatches(varName, this.validTokens, 3, 5);
+				const suggestion =
+					closest.length > 0
+						? `Did you mean one of these?\n  - ${closest.map((t) => `var(${t})`).join('\n  - ')}`
+						: `Token "${varName}" is not in the system contract. Use an existing token or define it in _00_tokens.sass / _09_own.sass.`;
+
+				diagnostics.push({
+					rule: 'fs/token-purity',
+					severity: 'error',
+					file: relPath,
+					line: lineNum,
+					column: vm.index + 1,
+					found: vm[0],
+					rationale: `The custom property "${varName}" is not defined in the system token contract.`,
+					suggestion
+				});
+			}
+		});
+
+		return diagnostics;
+	}
+}

package/package.json

@@ -1,6 +1,113 @@
 {
-  "name": "@fractaldesign/fractalstyler",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@fractaldesign/fractalstyler",
+	"version": "0.9.0",
+	"license": "MIT",
+	"description": "A composition styling system, shipped as plain CSS and as editable SASS. The class registry is the public API: compose in markup, write no stylesheet.",
+	"bin": {
+		"fractalstyler": "cli/main.mjs",
+		"fractalstyler-lint": "lint/cli.mjs"
+	},
+	"scripts": {
+		"registry": "node scripts/update-registry.js && node scripts/class-vocab.js",
+		"vocab": "node scripts/class-vocab.js",
+		"lint": "node lint/cli.mjs",
+		"browser": "node lint/browser.mjs",
+		"dev": "vite dev",
+		"preview": "vite preview",
+		"build": "npm run registry && npm run prepack",
+		"prepare": "svelte-kit sync || echo ''",
+		"prepack": "npm run registry && svelte-kit sync && svelte-package && npm run css && ([ -f lint/cli.mjs ] && chmod +x lint/cli.mjs || true) && publint",
+		"check": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json && node scripts/validate-deck.js && node lint/cli.mjs",
+		"check:watch": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json --watch",
+		"validate:deck": "node scripts/validate-deck.js",
+		"css": "node scripts/build-css.js",
+		"version": "npm run registry && git add -A",
+		"pair": "node scripts/generate-pairs.mjs && node scripts/update-registry.js"
+	},
+	"files": [
+		"dist",
+		"!dist/**/*.test.*",
+		"!dist/**/*.spec.*",
+		"registry.json",
+		"skills",
+		"lint",
+		"data",
+		"cli",
+		"docs/REGISTRY.md",
+		"docs/REGISTRY.api.md",
+		"docs/references",
+		"scripts/update-registry.js",
+		"scripts/class-vocab.js"
+	],
+	"sideEffects": [
+		"**/*.css"
+	],
+	"svelte": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"type": "module",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"svelte": "./dist/index.js",
+			"default": "./dist/index.js"
+		},
+		"./styles": {
+			"types": "./dist/asset.d.ts",
+			"default": "./dist/styles/index.sass"
+		},
+		"./styles/*": "./dist/styles/*",
+		"./tokens": {
+			"types": "./dist/asset.d.ts",
+			"default": "./dist/styles/_00_tokens.sass"
+		},
+		"./css": {
+			"types": "./dist/asset.d.ts",
+			"default": "./dist/css/fractalstyler.css"
+		},
+		"./css/min": {
+			"types": "./dist/asset.d.ts",
+			"default": "./dist/css/fractalstyler.min.css"
+		},
+		"./recipes": "./data/recipes.json",
+		"./package.json": "./package.json"
+	},
+	"peerDependencies": {
+		"svelte": "^5.0.0",
+		"sass": "^1.102.0"
+	},
+	"devDependencies": {
+		"@sveltejs/adapter-auto": "^7.0.1",
+		"@sveltejs/kit": "^2.63.0",
+		"@sveltejs/package": "^2.5.8",
+		"@sveltejs/vite-plugin-svelte": "^7.1.2",
+		"@types/node": "^26.2.0",
+		"publint": "^0.3.21",
+		"sass": "^1.102.0",
+		"svelte": "^5.56.1",
+		"svelte-check": "^4.6.0",
+		"typescript": "^6.0.3",
+		"vite": "^8.0.16"
+	},
+	"keywords": [
+		"css",
+		"sass",
+		"design-system",
+		"styling",
+		"svelte",
+		"sveltekit",
+		"utility-classes",
+		"design-tokens",
+		"fractal"
+	],
+	"dependencies": {
+		"@modelcontextprotocol/sdk": "^1.30.0"
+	},
+	"engines": {
+		"node": ">=18"
+	},
+	"peerDependenciesMeta": {
+		"sass": {
+			"optional": true
+		}
+	}
+}