@sableui/react 0.7.1 → 0.8.1

package/scripts/sources.mjs

@@ -0,0 +1,247 @@
+/**
+ * sable sources — point Tailwind at the Sable modules an app actually imports.
+ *
+ * The install recipe's `@source` covers the whole published `dist`, so Tailwind
+ * generates every component's classes whether the app renders it or not:
+ * Sable's own stylesheet is about 6 KB gzipped, and the whole-dist scan takes an
+ * app to about 32 KB. A support app measured that, a third more CSS than the
+ * same app on shadcn.
+ *
+ * This follows the app's imports from `@sableui/react` (and its subpaths)
+ * through the published module graph — each name to the module that defines it,
+ * then every module that one imports, static and lazy — and writes one
+ * `@source` per module. The app's own files are Tailwind's to find as before.
+ *
+ * The cost is that the list goes stale when the app imports something new, and
+ * a component missing from it renders unstyled without an error. So the file
+ * says where it came from, and `sable doctor` (and `sable check`) recompute it
+ * and fail when a module the app needs is not covered.
+ */
+import { existsSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs"
+import { dirname, join, relative, resolve } from "node:path"
+import { fileURLToPath } from "node:url"
+
+export const SOURCES_MARKER = "Generated by sable sources"
+const SKIP = new Set(["node_modules", "dist", "build", "out", ".next", ".git", "coverage", ".turbo"])
+
+/** `@sableui/react[/sub]` specifier → the published module, from the package's exports map. */
+function entryFor(pkgRoot, specifier) {
+	const pkg = JSON.parse(readFileSync(join(pkgRoot, "package.json"), "utf8"))
+	const exports = pkg.publishConfig?.exports ?? pkg.exports ?? {}
+	const key = specifier === "@sableui/react" ? "." : `.${specifier.slice("@sableui/react".length)}`
+	const target = exports[key]
+	const path = typeof target === "string" ? target : target?.default ?? target?.import
+	if (!path || !path.endsWith(".js")) return null
+	const file = join(pkgRoot, path)
+	return existsSync(file) ? file : null
+}
+
+const moduleCache = new Map()
+/** A module's imports and exports, read lexically from the bundler's plain ESM output. */
+function parseModule(file) {
+	if (moduleCache.has(file)) return moduleCache.get(file)
+	const text = readFileSync(file, "utf8")
+	const rel = (spec) => resolve(dirname(file), spec)
+	const names = (list) =>
+		list
+			.split(",")
+			.map((s) => s.trim())
+			.filter(Boolean)
+			.map((s) => {
+				const [from, as] = s.split(/\s+as\s+/)
+				return { from: from.trim(), as: (as ?? from).trim() }
+			})
+	const imports = new Map() // local → { file, name }
+	for (const m of text.matchAll(/import\s*\{([^}]*)\}\s*from\s*"(\.[^"]+)"/g))
+		for (const n of names(m[1])) imports.set(n.as, { file: rel(m[2]), name: n.from })
+	const reexports = new Map() // exported → { file, name }
+	const local = new Set()
+	const stars = []
+	for (const m of text.matchAll(/export\s*\{([^}]*)\}\s*from\s*"(\.[^"]+)"/g))
+		for (const n of names(m[1])) reexports.set(n.as, { file: rel(m[2]), name: n.from })
+	for (const m of text.matchAll(/export\s*\*\s*from\s*"(\.[^"]+)"/g)) stars.push(rel(m[1]))
+	for (const m of text.matchAll(/export\s*\{([^}]*)\}\s*(?:;|\n|$)/g))
+		for (const n of names(m[1])) {
+			if (imports.has(n.from)) reexports.set(n.as, imports.get(n.from))
+			else local.add(n.as)
+		}
+	for (const m of text.matchAll(/export\s+(?:async\s+)?(?:function\*?|const|let|var|class)\s+([\w$]+)/g)) local.add(m[1])
+	const deps = [
+		...[...text.matchAll(/(?:import|export)\s[^"']*?from\s*"(\.[^"]+)"/g)].map((m) => rel(m[1])),
+		...[...text.matchAll(/import\s*"(\.[^"]+)"/g)].map((m) => rel(m[1])),
+		...[...text.matchAll(/import\(\s*"(\.[^"]+)"\s*\)/g)].map((m) => rel(m[1])),
+	]
+	const parsed = { local, reexports, stars, deps }
+	moduleCache.set(file, parsed)
+	return parsed
+}
+
+/** The module that defines `name`, following re-exports and `export *`. */
+function definingModule(file, name, seen = new Set()) {
+	if (seen.has(file) || !existsSync(file)) return null
+	seen.add(file)
+	const m = parseModule(file)
+	if (m.local.has(name)) return file
+	const re = m.reexports.get(name)
+	if (re) return definingModule(re.file, re.name, seen)
+	for (const star of m.stars) {
+		const hit = definingModule(star, name, seen)
+		if (hit) return hit
+	}
+	return null
+}
+
+/** Every module reachable from `roots` by relative import. */
+function closure(roots) {
+	const out = new Set()
+	const stack = [...roots]
+	while (stack.length) {
+		const file = stack.pop()
+		if (out.has(file) || !existsSync(file)) continue
+		out.add(file)
+		stack.push(...parseModule(file).deps)
+	}
+	return out
+}
+
+/** The app's source files, outside dependencies and build output. */
+export function appSources(root) {
+	const out = []
+	const walk = (dir) => {
+		let entries
+		try {
+			entries = readdirSync(dir)
+		} catch {
+			return
+		}
+		for (const name of entries) {
+			if (SKIP.has(name) || name.startsWith(".")) continue
+			const full = join(dir, name)
+			const st = statSync(full)
+			if (st.isDirectory()) walk(full)
+			else if (/\.(?:[cm]?[jt]sx?)$/.test(name) && !/\.d\.ts$/.test(name)) out.push(full)
+		}
+	}
+	walk(root)
+	return out
+}
+
+/**
+ * The published modules an app's imports reach. `unresolved` lists what could
+ * not be traced (a namespace import, a name the package does not export); any
+ * of those means the whole package is needed.
+ */
+export function sableModules(pkgRoot, files) {
+	const roots = new Set()
+	const unresolved = []
+	const spec = /(?:import|export)\s+(type\s+)?([^;"'`]*?)\s*from\s*["'](@sableui\/react(?:\/[\w./-]+)?)["']|import\(\s*["'](@sableui\/react(?:\/[\w./-]+)?)["']\s*\)/g
+	for (const path of files) {
+		const text = readFileSync(path, "utf8")
+		for (const m of text.matchAll(spec)) {
+			if (m[1]) continue // `import type` brings no runtime module
+			const specifier = m[3] ?? m[4]
+			if (/\.css$/.test(specifier)) continue
+			const entry = entryFor(pkgRoot, specifier)
+			if (!entry) {
+				unresolved.push(specifier)
+				continue
+			}
+			const clause = m[2] ?? ""
+			const braces = /\{([^}]*)\}/.exec(clause)?.[1]
+			// A namespace import, a default import, `export *` or a dynamic import
+			// can reach anything the entry exports.
+			if (m[4] || /\*/.test(clause) || !braces || /^\s*[\w$]+\s*(?:,|$)/.test(clause)) {
+				roots.add(entry)
+				if (!braces) continue
+			}
+			for (const part of braces.split(",")) {
+				const name = part.trim().replace(/^type\s+/, "").split(/\s+as\s+/)[0].trim()
+				if (!name || /^type\s/.test(part.trim())) continue
+				const file = definingModule(entry, name)
+				if (file) roots.add(file)
+				else unresolved.push(`${name} from ${specifier}`)
+			}
+		}
+	}
+	// A component's .meta.js is its docs: class names there are example strings,
+	// never rendered, and a barrel import would otherwise ship them all.
+	return { modules: [...closure(roots)].filter((f) => !f.endsWith(".meta.js")).sort(), unresolved }
+}
+
+/** Where the app reaches the package: its own node_modules link when there is one. */
+function packageBase(pkgRoot, root) {
+	const linked = join(root, "node_modules", "@sableui", "react")
+	return existsSync(join(linked, "package.json")) ? linked : pkgRoot
+}
+
+export function sourcesCss(pkgRoot, root, outFile) {
+	const { modules, unresolved } = sableModules(pkgRoot, appSources(root))
+	const base = packageBase(pkgRoot, root)
+	const from = dirname(resolve(root, outFile))
+	const line = (file) => `@source "${relative(from, join(base, relative(pkgRoot, file))).split("\\").join("/")}";`
+	const body = unresolved.length ? [line(join(pkgRoot, "dist")).replace(/";$/, '/**/*.{js,mjs}";')] : modules.map(line)
+	const css = [
+		`/* ${SOURCES_MARKER}: the @sableui/react modules this app imports, so Tailwind`,
+		"   generates their classes and no others. Re-run `sable sources --write` after",
+		"   importing something new from Sable; `sable check` fails while it is stale. */",
+		...body,
+		"",
+	].join("\n")
+	return { css, modules, unresolved }
+}
+
+/**
+ * Doctor: a sources file that is missing a module the app now imports renders
+ * that component unstyled, silently — so it fails. A whole-package @source is
+ * correct, just heavy, so it only gets a note.
+ */
+export function sourcesCheck(pkgRoot, root, cssFiles) {
+	const generated = cssFiles.find((f) => f.text.includes(SOURCES_MARKER))
+	if (!generated) {
+		const whole = cssFiles.some((f) => /@source[^;]*(?:@sableui\/react|packages\/sable)\/dist(?:\/\*\*)?[^;]*;/.test(f.text))
+		return whole ? [{ status: "info", name: "css:size", detail: "@source scans all of Sable's dist, so every component's classes ship (about 32 KB gzipped).", fix: "sable sources --write src/sable-sources.css, then import it in place of that @source." }] : []
+	}
+	const rel = relative(root, generated.path)
+	const { modules, unresolved } = sableModules(pkgRoot, appSources(root))
+	if (unresolved.length && !/\/dist\/\*\*\//.test(generated.text))
+		return [{ status: "fail", name: "css:sources", detail: `${rel} lists modules, but these imports could not be traced: ${unresolved.slice(0, 4).join(", ")}.`, fix: `sable sources --write ${rel}` }]
+	const base = packageBase(pkgRoot, root)
+	const covered = new Set(
+		[...generated.text.matchAll(/@source\s+"([^"]+)"/g)].map((m) => resolve(dirname(generated.path), m[1])),
+	)
+	const wholeDist = [...covered].some((p) => /[\\/]dist[\\/]\*\*/.test(p))
+	if (wholeDist) return [{ status: "pass", name: "css:sources", detail: `${rel} covers all of Sable.` }]
+	const missing = modules.filter((file) => !covered.has(join(base, relative(pkgRoot, file))))
+	if (missing.length)
+		return [{ status: "fail", name: "css:sources", detail: `${rel} is stale: ${missing.length} module(s) the app now imports are not in it (${missing.slice(0, 3).map((f) => relative(join(pkgRoot, "dist"), f).split("\\").join("/")).join(", ")}${missing.length > 3 ? ", …" : ""}). Their components render unstyled.`, fix: `sable sources --write ${rel}` }]
+	return [{ status: "pass", name: "css:sources", detail: `${rel} covers the ${modules.length} Sable modules the app imports.` }]
+}
+
+/* ── CLI ────────────────────────────────────────────────────────────────────── */
+
+const isMain = process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)
+if (isMain) {
+	const args = process.argv.slice(2)
+	const json = args.includes("--json")
+	try {
+		const pkgRoot = fileURLToPath(new URL("../", import.meta.url))
+		const root = process.cwd()
+		const at = args.indexOf("--write")
+		const out = at === -1 ? null : args[at + 1]
+		if (at !== -1 && (!out || out.startsWith("--"))) throw Object.assign(new Error("--write needs a stylesheet path, e.g. src/sable-sources.css."), { code: "ERR_BAD_ARGUMENT" })
+		const unknown = args.filter((a, i) => a.startsWith("--") && !["--write", "--json"].includes(a) && args[i - 1] !== "--write")
+		if (unknown.length) throw Object.assign(new Error(`Unknown flag: ${unknown[0]}`), { code: "ERR_BAD_FLAG" })
+		const target = out ?? "src/sable-sources.css"
+		const result = sourcesCss(pkgRoot, root, target)
+		if (out) writeFileSync(resolve(root, out), result.css)
+		const note = result.unresolved.length
+			? `Could not trace ${result.unresolved.slice(0, 4).join(", ")}, so it covers all of Sable.`
+			: `${result.modules.length} modules.`
+		if (json) process.stdout.write(`${JSON.stringify({ type: "sources", data: { file: out, modules: result.modules.length, unresolved: result.unresolved, css: result.css } })}\n`)
+		else if (out) process.stdout.write(`Wrote ${out}: ${note}\nImport it in your stylesheet in place of the whole-package @source:\n  @import "./${relative(dirname(resolve(root, "src/app.css")), resolve(root, out)).split("\\").join("/")}";\n`)
+		else process.stdout.write(result.css)
+	} catch (error) {
+		process.stderr.write(`${JSON.stringify({ type: "error", code: error.code ?? "ERR_SOURCES", message: error.message, suggestions: ["sable sources --write src/sable-sources.css"] })}\n`)
+		process.exitCode = 1
+	}
+}

package/skills/sable/SKILL.md

@@ -13,7 +13,9 @@ References inform an original direction. A reference or preset is optional.
 
 1. Run `sable check <source paths>` (default `src`). It runs `sable doctor`,
    `sable lint`, and `sable grade` and exits 1 if any fails. Repair the findings
-   instead of suppressing them, then run it again until it passes. Also run the
+   instead of suppressing them, then run it again until it passes. Act on its
+   notes too: they don't fail the check but name real work, such as trimming the
+   CSS to the components the app imports (`sable sources`). Also run the
    project's own build and type checks.
 2. Review the rendered design: `sable docs reviewing-a-design`. Capture desktop and
    mobile in every promised colour mode, and judge brief fit, composition,
@@ -34,7 +36,7 @@ References inform an original direction. A reference or preset is optional.
    lessons with evidence; never fabricate human approval or preference records.
 
 Steps 2–7 are what no tool can verify; `sable check` prints them after its
-results. A passing check is a contract result, not design approval.
+results, plus any step its notes call for. A passing check is a contract result, not design approval.
 
 ## Route the request
 
@@ -227,6 +229,9 @@ Every build ends with the finish checklist at the top of this skill. Notes on it
   the smallest necessary addition, and include the inventory with the build's
   evidence so conformance is reviewable.
 
-Iterate on observed defects and recapture changed states. Contract checks cannot
-judge beauty. Deliver the result, the preset/revision used, the checks performed,
+Iterate on observed defects and recapture changed states. A defect inside a Sable
+component is patched, not restyled: `sable patch <Component> --reason … --repro …`,
+then the package manager's patch (`sable docs patching-a-component`). When `sable
+doctor` fails on a patch after an upgrade, re-run its repro on Sable's own files
+and keep or drop it. Contract checks cannot judge beauty. Deliver the result, the preset/revision used, the checks performed,
 and material limitations.