@rokkit/cli 1.4.0 → 1.4.1

package/src/contrast.js

@@ -24,20 +24,38 @@ const PALETTE_REF = /^([a-z][\w-]*)\.(\d{2,3})$/i
  */
 export function parseColor(value, palettes = {}) {
 	if (typeof value !== 'string') return null
-	let raw = value.trim()
-	const ref = raw.match(PALETTE_REF)
-	if (ref) {
-		const shade = palettes[ref[1]]?.[ref[2]]
-		if (!shade) return null
-		raw = String(shade).trim()
-	}
-	const fn = raw.match(/^oklch\(\s*([^)]+)\)$/i)
-	if (fn) raw = fn[1].trim()
-	const parts = raw.split(/[\s,/]+/).filter(Boolean).map(Number)
+	const raw = resolvePaletteRef(value.trim(), palettes)
+	if (raw === null) return null
+	const parts = stripColorFn(raw).split(/[\s,/]+/).filter(Boolean).map(Number)
 	if (parts.length < 3 || parts.some((n) => Number.isNaN(n))) return null
 	return [parts[0], parts[1], parts[2]]
 }
 
+/**
+ * Follow a `"kami.400"` palette reference to its value. Non-references pass
+ * through unchanged; a reference pointing at a missing shade returns null,
+ * which the caller treats as unparseable.
+ * @param {string} raw
+ * @param {Record<string, Record<string|number,string>>} palettes
+ * @returns {string | null}
+ */
+function resolvePaletteRef(raw, palettes) {
+	const ref = raw.match(PALETTE_REF)
+	if (!ref) return raw
+	const shade = palettes[ref[1]]?.[ref[2]]
+	return shade ? String(shade).trim() : null
+}
+
+/**
+ * Unwrap `oklch(L C H)` to its bare channels; anything else passes through.
+ * @param {string} raw
+ * @returns {string}
+ */
+function stripColorFn(raw) {
+	const fn = raw.match(/^oklch\(\s*([^)]+)\)$/i)
+	return fn ? fn[1].trim() : raw
+}
+
 /**
  * OKLCH → linear sRGB (the space WCAG relative luminance is defined in).
  * @param {[number, number, number]} oklch
@@ -82,28 +100,127 @@ export function contrastRatio(a, b) {
 	return (Math.max(la, lb) + 0.05) / (Math.min(la, lb) + 0.05)
 }
 
+/**
+ * Unwrap a `{ light, dark }` dual to the value for `mode`; scalars pass through.
+ * Both skin roles and config overrides accept the dual form, so this is the one
+ * place that knows the shape.
+ * @param {unknown} value
+ * @param {string} mode
+ */
+function pickMode(value, mode) {
+	if (value && typeof value === 'object' && !Array.isArray(value)) {
+		return mode === 'dark' ? value.dark : value.light
+	}
+	return value
+}
+
 /** Pick a skin role's palette name for a mode (handles `{light,dark}` duals). */
 function roleName(skin, role, mode) {
-	const v = skin?.[role]
-	if (v && typeof v === 'object' && !Array.isArray(v)) return mode === 'dark' ? v.dark : v.light
-	return v
+	return pickMode(skin?.[role], mode)
 }
 
 /**
  * Resolve a named token's OKLCH for a mode: config `overrides` win, else the
  * role palette at the token's shade.
+ * @param {{ config: Record<string, any>, skin: Record<string, any>, role: string,
+ *   shade: number, name: string, mode: string }} args
  */
-function resolveToken(config, skin, role, shade, name, mode) {
-	const ov = config.overrides?.[name]
-	if (ov !== undefined) {
-		const v = ov && typeof ov === 'object' && !Array.isArray(ov) ? (mode === 'dark' ? ov.dark : ov.light) : ov
-		return parseColor(v, config.palettes)
-	}
-	const pal = config.palettes?.[roleName(skin, role, mode)]
-	return pal ? parseColor(String(pal[shade]), config.palettes) : null
+function resolveToken({ config, skin, role, shade, name, mode }) {
+	const override = config.overrides?.[name]
+	if (override !== undefined) return parseColor(pickMode(override, mode), config.palettes)
+	const palette = config.palettes?.[roleName(skin, role, mode)]
+	return palette ? parseColor(String(palette[shade]), config.palettes) : null
 }
 
 const AA = 4.5
+/** Below this ratio a hairline border is effectively invisible against the canvas. */
+const EDGE_MIN = 1.18
+/** Float slack, so noise in the ramp doesn't read as a real inversion. */
+const RAMP_SLACK = 0.01
+/** The ink ramp, darkest first — the order the monotonic check asserts. */
+const INK_RAMP = [
+	['ink', 900],
+	['ink-mute', 700],
+	['ink-soft', 500],
+	['ink-faint', 300]
+]
+/** The two ink tones that carry readable text, and so must clear AA. */
+const READABLE = new Set(['ink', 'ink-mute'])
+
+/** The skin block, under whichever of the three accepted config keys holds it. */
+function skinOf(config) {
+	return config.skins?.default ?? config.skin ?? config.colors
+}
+
+/** Each ink tone's contrast against paper, in ramp order; null where unresolvable. */
+function inkRamp(config, skin, paper, mode) {
+	return INK_RAMP.map(([name, shade]) => {
+		const token = resolveToken({ config, skin, role: 'ink', shade, name, mode })
+		return { name, c: token ? contrastRatio(token, paper) : null }
+	})
+}
+
+/** AA gate on the tones that actually carry text. */
+function checkReadableText(ramp, mode) {
+	return ramp
+		.filter(({ name, c }) => READABLE.has(name) && c !== null && c < AA)
+		.map(({ name, c }) => ({
+			id: `contrast-${name}-${mode}`,
+			label: `${name} on paper clears AA in ${mode}`,
+			status: 'warn',
+			fixable: false,
+			fix: `${name} vs paper is ${c.toFixed(2)}:1 in ${mode} (need ≥ ${AA}). It backs ${name === 'ink' ? 'primary' : 'secondary'} text — darken ${name} (or lighten paper) in this mode.`
+		}))
+}
+
+/**
+ * ink > ink-mute > ink-soft > ink-faint. Reports the FIRST inversion only —
+ * once the ramp is out of order every later pair is suspect too, and four
+ * findings for one mistake is noise.
+ */
+function checkRampMonotonic(ramp, mode) {
+	const seq = ramp.filter((r) => r.c !== null)
+	const broken = seq.findIndex((r, i) => i > 0 && r.c > seq[i - 1].c + RAMP_SLACK)
+	if (broken < 0) return []
+	return [
+		{
+			id: `contrast-ramp-${mode}`,
+			label: `ink ramp is monotonic in ${mode}`,
+			status: 'warn',
+			fixable: false,
+			fix: `${seq[broken].name} (${seq[broken].c.toFixed(2)}:1) has MORE contrast than ${seq[broken - 1].name} (${seq[broken - 1].c.toFixed(2)}:1) in ${mode} — the ramp ink > ink-mute > ink-soft > ink-faint is inverted/compressed.`
+		}
+	]
+}
+
+/** paper-edge must be distinguishable from paper, or the hairline border vanishes. */
+function checkEdgeVisible(config, skin, paper, mode) {
+	const edge = resolveToken({ config, skin, role: 'surface', shade: 400, name: 'paper-edge', mode })
+	if (!edge) return []
+	const ratio = contrastRatio(edge, paper)
+	if (ratio >= EDGE_MIN) return []
+	return [
+		{
+			id: `contrast-paper-edge-${mode}`,
+			label: `paper-edge is visible against paper in ${mode}`,
+			status: 'warn',
+			fixable: false,
+			fix: `paper-edge vs paper is only ${ratio.toFixed(2)}:1 in ${mode} — the hairline border is effectively invisible. Pick a paper-edge value with more lightness separation from the canvas in this mode.`
+		}
+	]
+}
+
+/** All three checks for one mode. */
+function checksForMode(config, skin, mode) {
+	const paper = resolveToken({ config, skin, role: 'surface', shade: 50, name: 'paper', mode })
+	if (!paper) return []
+	const ramp = inkRamp(config, skin, paper, mode)
+	return [
+		...checkReadableText(ramp, mode),
+		...checkRampMonotonic(ramp, mode),
+		...checkEdgeVisible(config, skin, paper, mode)
+	]
+}
 
 /**
  * Verify text/border contrast tokens from the parsed config, in light + dark.
@@ -112,65 +229,7 @@ const AA = 4.5
  */
 export function checkContrastTokens(config) {
 	if (!config?.palettes) return []
-	const skin = config.skins?.default ?? config.skin ?? config.colors
-	if (!skin || !skin.ink || !skin.surface) return []
-
-	const findings = []
-	for (const mode of ['light', 'dark']) {
-		const paper = resolveToken(config, skin, 'surface', 50, 'paper', mode)
-		if (!paper) continue
-		const ramp = [
-			['ink', 900],
-			['ink-mute', 700],
-			['ink-soft', 500],
-			['ink-faint', 300]
-		].map(([name, shade]) => ({ name, c: (() => {
-			const tok = resolveToken(config, skin, 'ink', shade, name, mode)
-			return tok ? contrastRatio(tok, paper) : null
-		})() }))
-
-		// AA gate on the readable text tones.
-		for (const { name, c } of ramp) {
-			if ((name === 'ink' || name === 'ink-mute') && c !== null && c < AA) {
-				findings.push({
-					id: `contrast-${name}-${mode}`,
-					label: `${name} on paper clears AA in ${mode}`,
-					status: 'warn',
-					fixable: false,
-					fix: `${name} vs paper is ${c.toFixed(2)}:1 in ${mode} (need ≥ ${AA}). It backs ${name === 'ink' ? 'primary' : 'secondary'} text — darken ${name} (or lighten paper) in this mode.`
-				})
-			}
-		}
-
-		// Monotonic ramp: ink > ink-mute > ink-soft > ink-faint.
-		const seq = ramp.filter((r) => r.c !== null)
-		for (let i = 1; i < seq.length; i++) {
-			if (seq[i].c > seq[i - 1].c + 0.01) {
-				findings.push({
-					id: `contrast-ramp-${mode}`,
-					label: `ink ramp is monotonic in ${mode}`,
-					status: 'warn',
-					fixable: false,
-					fix: `${seq[i].name} (${seq[i].c.toFixed(2)}:1) has MORE contrast than ${seq[i - 1].name} (${seq[i - 1].c.toFixed(2)}:1) in ${mode} — the ramp ink > ink-mute > ink-soft > ink-faint is inverted/compressed.`
-				})
-				break
-			}
-		}
-
-		// Border visibility: paper-edge must be distinguishable from paper.
-		const edge = resolveToken(config, skin, 'surface', 400, 'paper-edge', mode)
-		if (edge) {
-			const ec = contrastRatio(edge, paper)
-			if (ec < 1.18) {
-				findings.push({
-					id: `contrast-paper-edge-${mode}`,
-					label: `paper-edge is visible against paper in ${mode}`,
-					status: 'warn',
-					fixable: false,
-					fix: `paper-edge vs paper is only ${ec.toFixed(2)}:1 in ${mode} — the hairline border is effectively invisible. Pick a paper-edge value with more lightness separation from the canvas in this mode.`
-				})
-			}
-		}
-	}
-	return findings
+	const skin = skinOf(config)
+	if (!skin?.ink || !skin.surface) return []
+	return ['light', 'dark'].flatMap((mode) => checksForMode(config, skin, mode))
 }

package/src/doctor.js

@@ -30,43 +30,36 @@ export async function doctor(opts = {}) {
 	const failures = printChecks(checks)
 
 	const parsed = await loadParsedConfig({ cwd })
-	const shapeChecks = validateConfigShape(parsed)
-	/* v8 ignore next 8 -- loadConfig uses dynamic file:// import which always fails in
-	   JSDOM; validateConfigShape(null) returns [] so this branch is unreachable in tests */
-	if (shapeChecks.length > 0) {
-		console.info('\nConfig shape:')
-		for (const c of shapeChecks) {
-			console.info(`  WARN  ${c.label}`)
-			console.info(`        ${c.fix}`)
-		}
-	}
-
-	const contrastChecks = checkContrastTokens(parsed)
-	/* v8 ignore start -- loadConfig uses a dynamic file:// import which always fails in
-	   JSDOM, so parsed is null and contrastChecks is [] → this print block is unreachable
-	   in tests. The check logic itself is covered directly in contrast.spec.js. */
-	if (contrastChecks.length > 0) {
-		console.info('\nContrast (WCAG AA · light + dark):')
-		for (const c of contrastChecks) {
-			console.info(`  WARN  ${c.label}`)
-			console.info(`        ${c.fix}`)
-		}
-	}
-	/* v8 ignore stop */
-
-	const usageChecks = checkTextTokenUsage(createFsAdapter(cwd))
-	/* v8 ignore start -- this print block depends on the real filesystem walk finding
-	   a misused token in cwd; in the JSDOM doctor() test the temp project is clean, so
-	   usageChecks is [] and this is unreachable. checkTextTokenUsage is covered directly. */
-	if (usageChecks.length > 0) {
-		console.info('\nToken usage:')
-		for (const c of usageChecks) {
-			console.info(`  WARN  ${c.label}`)
-			console.info(`        ${c.fix}`)
-		}
-	}
-	/* v8 ignore stop */
+	printAdvisories('Config shape', validateConfigShape(parsed))
+	printAdvisories('Contrast (WCAG AA · light + dark)', checkContrastTokens(parsed))
+	printAdvisories('Token usage', checkTextTokenUsage(createFsAdapter(cwd)))
 
 	handleResults(checks, cwd, failures, opts.fix ?? false)
 	console.info('')
 }
+
+/**
+ * Print one titled advisory section, or nothing at all when there is nothing to
+ * report. Replaces three identical if/heading/loop blocks — and, with them,
+ * three separate coverage-ignore comments saying the same thing.
+ *
+ * @param {string} title
+ * @param {Array<{ label: string, fix: string }>} findings
+ */
+/* v8 ignore start -- every caller is empty under test: loadConfig uses a dynamic
+   file:// import that always fails in JSDOM (so parsed is null and both config-derived
+   lists are []), and the doctor() test's temp project is clean (so the usage walk finds
+   nothing), which means this never gets past its own guard. The check logic itself is
+   covered directly in contrast.spec.js and via validateConfigShape /
+   checkTextTokenUsage. The ignore wraps the WHOLE function rather than a counted line
+   range: with an early return the function's tail is unreached too, and a `next N` count
+   silently drifts the moment a line is added. */
+function printAdvisories(title, findings) {
+	if (findings.length === 0) return
+	console.info(`\n${title}:`)
+	for (const c of findings) {
+		console.info(`  WARN  ${c.label}`)
+		console.info(`        ${c.fix}`)
+	}
+}
+/* v8 ignore stop */

package/src/init.js

@@ -222,36 +222,59 @@ export function generateChartConfig({ chartColors, chartShades }) {
  *   storageKey?: string }} [opts]
  * @returns {Record<string, unknown>}
  */
+/**
+ * The zen-sumi design decisions themselves — fixed, so they live outside the
+ * function rather than being rebuilt per call alongside the user's answers.
+ */
+const ZEN_SUMI_BASE = {
+	palettes: ZEN_SUMI_PALETTES,
+	colorSpace: 'oklch',
+	tokens: 'core',
+	skin: {
+		surface: { light: 'kami', dark: 'sumi' },
+		ink: { light: 'kami', dark: 'sumi' },
+		primary: 'shu',
+		accent: 'shu',
+		success: 'hisui',
+		warning: 'kohaku',
+		danger: 'shu',
+		error: 'shu',
+		info: 'kohaku'
+	},
+	shape: { radius: 'soft' },
+	typography: {
+		display: "'Fraunces', 'Iowan Old Style', Georgia, serif",
+		sans: "'Inter', system-ui, -apple-system, sans-serif",
+		mono: "'JetBrains Mono', 'SF Mono', Menlo, monospace"
+	}
+}
+
+/** `{ storageKey }` when one was derived, else nothing to spread. */
+const storageSection = (storageKey) => (storageKey ? { storageKey } : {})
+
+/** `{ chart }` when charts were requested, else nothing to spread. */
+function chartSection(includeChart, chartColors, chartShades) {
+	return includeChart ? { chart: generateChartConfig({ chartColors, chartShades }) } : {}
+}
+
+/** `{ icons }` when a style or a custom path was chosen, else nothing to spread. */
+function iconSection(icons, iconPath, iconStyle) {
+	const config = {}
+	if (iconStyle) config.style = iconStyle
+	if (icons === 'custom' && iconPath) config.custom = iconPath
+	return Object.keys(config).length > 0 ? { icons: config } : {}
+}
+
 export function generateZenSumiConfig(opts = {}) {
 	const { themes, defaultTheme, switcher, includeChart, chartColors, chartShades, storageKey } = opts
-	const config = {
-		palettes: ZEN_SUMI_PALETTES,
-		colorSpace: 'oklch',
-		tokens: 'core',
-		skin: {
-			surface: { light: 'kami', dark: 'sumi' },
-			ink: { light: 'kami', dark: 'sumi' },
-			primary: 'shu',
-			accent: 'shu',
-			success: 'hisui',
-			warning: 'kohaku',
-			danger: 'shu',
-			error: 'shu',
-			info: 'kohaku'
-		},
-		shape: { radius: 'soft' },
-		typography: {
-			display: "'Fraunces', 'Iowan Old Style', Georgia, serif",
-			sans: "'Inter', system-ui, -apple-system, sans-serif",
-			mono: "'JetBrains Mono', 'SF Mono', Menlo, monospace"
-		},
-		themes: themes && themes.length ? themes : ['rokkit', 'zen-sumi'],
+	return {
+		...ZEN_SUMI_BASE,
+		themes: themes?.length ? themes : ['rokkit', 'zen-sumi'],
 		defaultTheme: defaultTheme || 'zen-sumi',
 		switcher: switcher || 'full',
-		...(storageKey ? { storageKey } : {})
+		...storageSection(storageKey),
+		...chartSection(includeChart, chartColors, chartShades)
 	}
-	if (includeChart) config.chart = generateChartConfig({ chartColors, chartShades })
-	return config
 }
 
 /**
@@ -264,25 +287,26 @@ export function generateZenSumiConfig(opts = {}) {
  *   storageKey?: string }} opts
  * @returns {Record<string, unknown>}
  */
-export function generateConfig({
-	palette,
-	customColors,
-	icons,
-	iconPath,
-	iconStyle,
-	themes,
-	defaultTheme,
-	switcher,
-	includeChart,
-	chartColors,
-	chartShades,
-	storageKey
-}) {
-	if (palette === 'zen-sumi') {
-		return generateZenSumiConfig({ themes, defaultTheme, switcher, includeChart, chartColors, chartShades, storageKey })
-	}
+export function generateConfig(opts) {
+	const {
+		palette,
+		customColors,
+		icons,
+		iconPath,
+		iconStyle,
+		themes,
+		defaultTheme,
+		switcher,
+		includeChart,
+		chartColors,
+		chartShades,
+		storageKey
+	} = opts
+	// Forwarding the whole `opts` is safe: generateZenSumiConfig destructures only
+	// the keys it needs and ignores the palette/icon answers.
+	if (palette === 'zen-sumi') return generateZenSumiConfig(opts)
 
-	const config = {
+	return {
 		skin: resolveSkin(palette, customColors),
 		colorSpace: 'rgb',
 		tokens: 'core',
@@ -290,19 +314,10 @@ export function generateConfig({
 		themes,
 		defaultTheme: defaultTheme || themes[0],
 		switcher,
-		...(storageKey ? { storageKey } : {})
+		...storageSection(storageKey),
+		...iconSection(icons, iconPath, iconStyle),
+		...chartSection(includeChart, chartColors, chartShades)
 	}
-
-	const iconConfig = {}
-	if (iconStyle) iconConfig.style = iconStyle
-	if (icons === 'custom' && iconPath) iconConfig.custom = iconPath
-	if (Object.keys(iconConfig).length > 0) config.icons = iconConfig
-
-	if (includeChart) {
-		config.chart = generateChartConfig({ chartColors, chartShades })
-	}
-
-	return config
 }
 
 /**
@@ -520,52 +535,76 @@ function writeAppHtml(cwd, initScript, storageKey) {
 	console.info('  Patched app.html — added theme init script')
 }
 
+/**
+ * When this doesn't look like a SvelteKit project, warn and ask. Returns false
+ * to abort the whole command.
+ * @param {string} cwd
+ * @returns {Promise<boolean>}
+ */
+async function confirmSvelteKit(cwd) {
+	if (detectSvelteKit(cwd)) return true
+	console.warn('No svelte.config.js found — this may not be a SvelteKit project.')
+	const { proceed } = await prompts({
+		type: 'confirm',
+		name: 'proceed',
+		message: 'Continue anyway?',
+		initial: false
+	})
+	return Boolean(proceed)
+}
+
+/**
+ * The host package's name, or undefined when there's no readable package.json —
+ * the storage key is derived from it, and a missing name is not an error.
+ * @param {string} cwd
+ * @returns {string | undefined}
+ */
+function readAppName(cwd) {
+	try {
+		return JSON.parse(readFileSync(resolve(cwd, 'package.json'), 'utf-8')).name
+	} catch {
+		return undefined
+	}
+}
+
+/**
+ * Fold the three separate custom-colour answers into the single `customColors`
+ * shape `generateConfig` expects. Mutates `response` in place, like the rest of
+ * the prompt post-processing.
+ * @param {Record<string, unknown>} response
+ */
+/* v8 ignore start -- prompts mutates PROMPTS_CONFIG[n].type in-place on the first call,
+   so the conditional primary/accent/surface prompts always resolve to null on subsequent
+   runs and this never gets past its own guard; the behaviour is tested via generateConfig
+   directly. Wrapping the whole function rather than counting lines: with an early return
+   the tail is unreached too, and a `next N` count drifts as soon as a line moves. */
+function applyCustomColors(response) {
+	if (response.palette !== 'custom') return
+	response.customColors = {
+		primary: response.primary,
+		accent: response.accent,
+		surface: response.surface
+	}
+}
+/* v8 ignore stop */
+
 /**
  * Interactive init command — prompts the user, writes config files.
  * @param {Record<string, unknown>} [_opts]
  * @param {{ runInstall?: (bin: string, args: string[]) => void }} [adapters] — injectable for testing
  */
-// eslint-disable-next-line max-lines-per-function
 export async function init(_opts = {}, adapters = {}) {
 	const cwd = process.cwd()
 
-	// Detect SvelteKit project
-	if (!detectSvelteKit(cwd)) {
-		console.warn('No svelte.config.js found — this may not be a SvelteKit project.')
-		const { proceed } = await prompts({
-			type: 'confirm',
-			name: 'proceed',
-			message: 'Continue anyway?',
-			initial: false
-		})
-		if (!proceed) return
-	}
+	if (!(await confirmSvelteKit(cwd))) return
 
 	console.info('Rokkit Init — Setting up your SvelteKit project\n')
 
-	// Install packages
 	installPackages(cwd, adapters)
 
 	const response = await prompts(PROMPTS_CONFIG)
-
-	/* v8 ignore next 10 -- prompts mutates PROMPTS_CONFIG[n].type in-place on the
-	   first call, so the conditional primary/accent/surface prompts always resolve
-	   to null on subsequent runs; the branch is tested via generateConfig directly */
-	if (response.palette === 'custom') {
-		response.customColors = {
-			primary: response.primary,
-			accent: response.accent,
-			surface: response.surface
-		}
-	}
-
-	let appName
-	try {
-		appName = JSON.parse(readFileSync(resolve(cwd, 'package.json'), 'utf-8')).name
-	} catch {
-		appName = undefined
-	}
-	response.storageKey = storageKeyFromName(appName)
+	applyCustomColors(response)
+	response.storageKey = storageKeyFromName(readAppName(cwd))
 
 	const config = generateConfig(response)