@sableui/react 0.3.0 → 0.3.2

package/scripts/agent-setup.mjs

@@ -1,14 +1,40 @@
 import { createHash } from "node:crypto"
-import { existsSync, lstatSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"
-import { dirname, join } from "node:path"
+import { existsSync, lstatSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs"
+import { dirname, isAbsolute, join, relative, resolve } from "node:path"
 
 const hash = content => createHash("sha256").update(content).digest("hex")
 
-/** Install discoverable loaders; the installed package owns the actual workflow. */
-export function installAgentSkill({ root, packageRoot, target = "all", update = false, dryRun = false }) {
+const RESOLVE = `node -p "require.resolve('@sableui/react/registry.json')"`
+const CONTEXT = "From the target project's dependency context, run:"
+
+/**
+ * The entry as written at `root`. When Sable is a dependency of a workspace
+ * package rather than of the root, a bare `require.resolve` from the root fails
+ * (pnpm does not hoist it), so the entry names the package and resolves through it.
+ */
+function entryContent(source, projectPath) {
+	if (!projectPath) return source
+	if (!source.includes(RESOLVE) || !source.includes(CONTEXT)) throw new Error("The installed skill entry has an unexpected shape. Reinstall Sable.")
+	return source
+		.replace(CONTEXT, `Sable is installed in this repository's \`${projectPath}\` package. From the repository root, run:`)
+		.replace(RESOLVE, `node -p "require.resolve('@sableui/react/registry.json', { paths: ['${projectPath}'] })"`)
+}
+
+/**
+ * Install discoverable loaders; the installed package owns the actual workflow.
+ *
+ * `project` is where Sable is a dependency (the directory setup runs in); `root`
+ * is where the agent entries go. They differ in a monorepo, where agents start at
+ * the repository root but Sable belongs to one workspace package.
+ */
+export function installAgentSkill({ root, project = root, packageRoot, target = "all", update = false, dryRun = false }) {
 	const reject = (message) => { throw new Error(message) }
 	if (!["all", "codex", "claude", "cursor"].includes(target)) reject("Choose --target all, codex, claude, or cursor.")
-	if (!existsSync(join(root, "package.json"))) reject("Run setup from a project with a package.json.")
+	if (!existsSync(join(project, "package.json"))) reject("Run setup from a project with a package.json.")
+	if (!existsSync(root) || !statSync(root).isDirectory()) reject(`--root is not a directory: ${root}`)
+	const projectPath = relative(resolve(root), resolve(project)).replaceAll("\\", "/")
+	if (projectPath.startsWith("..") || isAbsolute(projectPath)) reject("--root must be the project directory or one of its ancestors, such as the repository root.")
+	if (/['"\\`]/.test(projectPath)) reject(`Unsupported characters in the project path: ${projectPath}`)
 	const canonical = join(packageRoot, "skills/sable/SKILL.md")
 	const entry = join(packageRoot, "skills/entry/SKILL.md")
 	if (!existsSync(canonical) || !existsSync(entry)) reject("The installed package is missing its skill. Reinstall Sable.")
@@ -29,8 +55,9 @@ export function installAgentSkill({ root, packageRoot, target = "all", update =
 		receipt = JSON.parse(readFileSync(join(root, receiptPath), "utf8"))
 		if (receipt.schemaVersion !== 1 || !receipt.files || typeof receipt.files !== "object") reject("Invalid Sable setup receipt.")
 	}
+	const skill = entryContent(readFileSync(entry, "utf8"), projectPath)
 	const files = destinations.flatMap(destination => [
-		{ path: `${destination}/SKILL.md`, content: readFileSync(entry, "utf8") },
+		{ path: `${destination}/SKILL.md`, content: skill },
 		...(destination.startsWith(".agents/") ? [{ path: `${destination}/agents/openai.yaml`, content: readFileSync(join(packageRoot, "skills/sable/agents/openai.yaml"), "utf8") }] : []),
 	])
 	// Preflight every host and the receipt before any writes; preserve local edits.
@@ -50,5 +77,5 @@ export function installAgentSkill({ root, packageRoot, target = "all", update =
 		mkdirSync(dirname(join(root, receiptPath)), { recursive: true })
 		writeFileSync(join(root, receiptPath), JSON.stringify(receipt, null, 2) + "\n")
 	}
-	return { destination: destinations[0], destinations, files: files.map(file => file.path), dryRun, update, next: "Use $sable build <your brief> in Codex or /sable build <your brief> in Claude Code or Cursor." }
+	return { destination: destinations[0], destinations, root, project: projectPath || ".", files: files.map(file => file.path), dryRun, update, next: "Use $sable build <your brief> in Codex or /sable build <your brief> in Claude Code or Cursor." }
 }

package/scripts/grade.mjs

@@ -45,7 +45,7 @@ const argv = process.argv.slice(2)
 const flags = new Map()
 const targets = []
 const BOOLEAN_FLAGS = new Set(["json", "help", "template", "strict"])
-const VALUE_FLAGS = new Set(["cli-log", "review"])
+const VALUE_FLAGS = new Set(["cli-log", "review", "icons"])
 const JSON_OUT = argv.includes("--json")
 function abort(message) {
 	const error = { type: "error", code: "ERR_GRADE_INPUT", message, suggestions: ["sable grade --help", "sable grade --template"] }
@@ -72,12 +72,13 @@ if (flags.has("help") || !targets.length) {
 		[
 			"grade — check the static contract and recorded review evidence. No model calls.",
 			"",
-			"  sable grade <dir...> [--json] [--review <review.json>] [--strict]",
+			"  sable grade <dir...> [--json] [--review <review.json>] [--icons <icons.json>] [--strict]",
 			"",
 			"  --json           machine-readable scorecard",
 			"  --cli-log        a SABLE_CLI_LOG jsonl, to report whether the CLI was used at all",
 			"  --template       print a review JSON template; fill after inspecting the rendered build",
 			"  --review         validate evidence files and observations; paths are relative to this JSON",
+			'  --icons          icon names the app adds with composeIconSets: { "names": [...] }. Default: .sable/icons.json',
 			"  --strict         exit 1 for static findings or a missing/incomplete/unresolved review",
 			"",
 			"Checks: design-contract violations · hallucinated components and props ·",
@@ -102,7 +103,27 @@ const motionTokens = new Set(
 	].filter(Boolean),
 )
 const RULES = makeRules({ semanticTokens, motionTokens }).filter((r) => r.scope !== "package")
+const PROP_SURFACE = REGISTRY.propSurface?.items ?? {}
 const ICONS = new Set(REGISTRY.iconContract?.names ?? [])
+/**
+ * The names an app adds with `composeIconSets(appExtras, reiconIconSet)`. That is
+ * the sanctioned way to extend the set, and the grade cannot read a set's names
+ * out of a render function, so the app declares them once. Without this every
+ * domain icon read as off-contract.
+ */
+const APP_ICONS = (() => {
+	const explicit = flags.get("icons")
+	const path = resolve(CWD, explicit ?? ".sable/icons.json")
+	if (!existsSync(path)) {
+		if (explicit) abort(`Not found: ${explicit}`)
+		return null
+	}
+	let names
+	try { names = JSON.parse(readFileSync(path, "utf8")).names }
+	catch (error) { abort(`Cannot read ${relative(CWD, path)}: ${error.message}`) }
+	if (!Array.isArray(names) || !names.every((n) => typeof n === "string" && n)) abort(`${relative(CWD, path)} must be { "names": ["icon-name", …] }.`)
+	return { file: relative(CWD, path).replaceAll("\\", "/"), names: new Set(names) }
+})()
 const PATTERNS = REGISTRY.patterns?.items ?? []
 
 /**
@@ -275,11 +296,14 @@ for (const file of files) {
 		}
 	}
 
-	/* 3. Props set on a Sable component that its contract does not declare. */
+	/* 3. Props set on a Sable component that its contract does not declare.
+	      The contract is the component's real type (registry → propSurface),
+	      which includes what it forwards to Base UI — Toggle's `pressed`,
+	      Combobox's `filter` — plus its documented table. */
 	for (const m of text.matchAll(/<([A-Z][\w]*)[\s/>]/g)) {
 		const comp = REGISTRY.components?.find((c) => c.name === m[1])
 		if (!comp?.props?.length) continue
-		const declared = new Set(comp.props.map((p) => p.name))
+		const declared = new Set([...comp.props.map((p) => p.name), ...(PROP_SURFACE[m[1]] ?? [])])
 		for (const sub of comp.subcomponents ?? []) {
 			if (typeof sub !== "string") for (const p of sub.props ?? []) declared.add(p.name)
 		}
@@ -307,9 +331,10 @@ for (const file of files) {
 		if (px >= 20 && px <= 56) findings.hardcodedControl.push({ file: rel, match: m[0], line: lineOf(text, m.index) })
 	}
 
-	/* 6. Icon names outside the contract render nothing at all. */
+	/* 6. Icon names outside the contract render nothing at all — unless the app
+	      supplies them itself and has declared them (APP_ICONS). */
 	for (const m of text.matchAll(/<Icon\s+[^>]*name=["']([^"']+)["']/g)) {
-		if (!ICONS.has(m[1])) findings.offContractIcon.push({ file: rel, name: m[1], line: lineOf(text, m.index) })
+		if (!ICONS.has(m[1]) && !APP_ICONS?.names.has(m[1])) findings.offContractIcon.push({ file: rel, name: m[1], line: lineOf(text, m.index) })
 	}
 
 	/* 7. Composition. Anything exporting a component that returns a big tree is
@@ -447,6 +472,7 @@ const result = {
 	per100loc: Object.fromEntries(Object.entries(counts).map(([k, v]) => [k, per100(v)])),
 	conformance: { informationalOnly: true, mean: meanConformance, routes: conformance },
 	cliUsage,
+	appIcons: APP_ICONS ? { file: APP_ICONS.file, names: APP_ICONS.names.size } : null,
 	findings,
 }
 
@@ -468,7 +494,7 @@ row("hallucinated components", counts.hallucinatedComponent)
 row("hallucinated props", counts.hallucinatedProp)
 row("Radix idioms", counts.radixIdiom, counts.radixIdiom ? "asChild / direct primitive imports" : "")
 row("hardcoded control heights", counts.hardcodedControl)
-row("off-contract icon names", counts.offContractIcon)
+row("off-contract icon names", counts.offContractIcon, APP_ICONS ? `+${APP_ICONS.names.size} app icons from ${APP_ICONS.file}` : counts.offContractIcon ? "app-supplied? list them in .sable/icons.json" : "")
 L()
 if (conformance.length) {
 	L(`  pattern similarity (informational) — ${conformance.length} route-like file(s), mean ${meanConformance}`)