admin-ui-starter-kit 0.1.4 → 0.4.2

package/.agents/skills/component-library-rules/references/components/ui__separator.md

@@ -23,7 +23,7 @@ tags:
 
 Horizontal & vertical dividers.
 
-**Layer:** `ui`  
+**Layer:** `ui`
 **Source:** `src/components/ui/separator`
 
 ## Examples

package/.agents/skills/component-library-rules/references/components/ui__skeleton.md

@@ -24,7 +24,7 @@ tags:
 
 Animated loading placeholders.
 
-**Layer:** `ui`  
+**Layer:** `ui`
 **Source:** `src/components/ui/skeleton`
 
 ## Examples

package/.agents/skills/component-library-rules/references/components/ui__sonner.md

@@ -23,7 +23,7 @@ tags:
 
 Toast notifications.
 
-**Layer:** `ui`  
+**Layer:** `ui`
 **Source:** `src/components/ui/button`
 
 ## Examples

package/.agents/skills/component-library-rules/references/components/ui__spinner.md

@@ -24,7 +24,7 @@ tags:
 
 Loading spinner — sized via className.
 
-**Layer:** `ui`  
+**Layer:** `ui`
 **Source:** `src/components/ui/spinner`
 
 ## Examples
@@ -53,7 +53,7 @@ export function ColorViaClassName() {
 			<Row>
 								<Spinner className="size-5 text-primary" />
 								<Spinner className="size-5 text-destructive" />
-								<Spinner className="size-5 text-chart-2" />
+								<Spinner className="size-5 text-info" />
 								<Spinner className="size-5 text-muted-foreground" />
 							</Row>
 		</>

package/.agents/skills/component-library-rules/references/components/ui__tabs.md

@@ -23,7 +23,7 @@ tags:
 
 Tab list with content panels.
 
-**Layer:** `ui`  
+**Layer:** `ui`
 **Source:** `src/components/ui/tabs`
 
 ## Examples

package/.agents/skills/component-library-rules/references/components/ui__toggles-group.md

@@ -24,7 +24,7 @@ tags:
 
 Single toggle + radio/multiple group.
 
-**Layer:** `ui`  
+**Layer:** `ui`
 **Source:** `src/components/ui`
 
 ## Examples

package/.agents/skills/component-library-rules/references/components/ui__toggles.md

@@ -28,7 +28,7 @@ tags:
 
 Checkbox, Switch, RadioGroup, Slider primitives.
 
-**Layer:** `ui`  
+**Layer:** `ui`
 **Source:** `src/components/ui`
 
 ## Examples

package/.agents/skills/component-library-rules/references/components/ui__ui-badge.md

@@ -25,7 +25,7 @@ tags:
 
 shadcn badge primitive (no theming wrapper).
 
-**Layer:** `ui`  
+**Layer:** `ui`
 **Source:** `src/components/ui/badge`
 
 ## Examples

package/.agents/skills/component-library-rules/references/components/ui__ui-card.md

@@ -24,7 +24,7 @@ tags:
 
 shadcn primitive card with header / title / description / content / footer.
 
-**Layer:** `ui`  
+**Layer:** `ui`
 **Source:** `src/components/ui/card`
 
 ## Examples

package/.agents/skills/component-library-rules/references/components/ui__ui-table.md

@@ -23,7 +23,7 @@ tags:
 
 shadcn table primitive (no data layer).
 
-**Layer:** `ui`  
+**Layer:** `ui`
 **Source:** `src/components/ui/table`
 
 ## Examples

package/.agents/skills/component-library-rules/references/visual-eval.md

@@ -10,7 +10,7 @@ Any change observable in the browser preview:
 - Restyled component (className, density, spacing, color)
 - Refactored typography (Text/Heading)
 - New preview page or section
-- Changes to `App.css` tokens
+- Changes to CSS tokens in `src/css/themes/default.css` or `src/css/defaults.css`
 
 When the change is purely structural (types, refactors that pass tsc, hooks with no UI surface), skip this — but say so explicitly rather than silently dropping the check.
 

package/.agents/skills/component-quality-pass/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: component-quality-pass
+description: Reusable audit workflow for this admin-ui-starter-kit component library. Use when asked to test, visually inspect, iron out inconsistencies, or clean up component quality across base, composed, features, layout, or preview pages, especially for whitespace, typography, tokenization, structure, API callbacks, strings, BEM hooks, visual screenshots, and functional tests.
+---
+
+# Component Quality Pass
+
+Use this skill to run a disciplined pass over component surfaces instead of clicking one page, fixing one visible defect, and missing the next one. It complements `component-library-rules`; load that skill first before editing `src/components/**`.
+
+## Workflow
+
+1. **Scope the pass.** Identify affected layers and routes: base, composed, features, layout, preview docs. If the user says "all", cover every registered preview route in the relevant sections.
+2. **Read the owning code.** Read the component, types, strings, partials/hooks, index export, preview example, tests, and nearby components in the same family.
+3. **Run static scans.** Use `scripts/scan-quality-smells.mjs` for token/layer/style smells and `scripts/list-preview-routes.mjs` to build the route list.
+4. **Inspect visually, slowly.** Use the Browser plugin's in-app browser and Playwright automation for visual validation. Visit each route, wait for lazy modules/fonts/rendering, then validate every visible example/variant/state on the page. Scroll top/middle/bottom, check desktop plus narrow widths, and capture screenshots for any changed or suspicious page.
+5. **Fix the component, not the preview.** If a preview exposes a defect, move the fix into `src/components/**` unless the preview is genuinely misusing the API.
+6. **Verify behavior.** Add or update tests for functional features and non-obvious base/composed behavior. Prefer callback/data/strings assertions over snapshots.
+7. **Run checks.** At minimum run focused tests/lint/typecheck for touched files, then broader `npm run lint:architecture`, `npm run test:exports`, `npm run typecheck`, `npm run lint`, and relevant Vitest suites.
+8. **Report residual risk.** Say which routes were visually inspected, which commands passed, and any generator checks or dirty-worktree areas that still need review.
+
+## Quality Bar
+
+Treat these as blocking defects:
+
+- Text hierarchy inconsistent for equivalent roles.
+- Whitespace disconnects related elements or smashes header/body/content.
+- Size variants in the same component family drift in height, padding, icon scale, text scale, or density without an intentional API reason.
+- Similar examples/variants disagree on spacing, alignment, tone, empty/loading/error states, focus treatment, or action placement.
+- Raw layout reimplements `SmartCard`, `Item`, `MetadataList`, `FormField`, `Button`, `Badge`, `Table`, or overlay primitives.
+- Feature components hardcode routing, data fetching, locale, strings, or consumer app types.
+- Components use raw color utilities where semantic tokens exist.
+- Preview pages duplicate implementation instead of demonstrating exported components.
+- Functional features lack callback/API tests for submit, select, add, remove, edit, async fetcher, error, or controlled state.
+- Public components lack stable `{name}--component` BEM hooks on real DOM roots.
+
+## References
+
+Read [references/audit-workflow.md](references/audit-workflow.md) when doing a real pass. It contains the concrete visual, structure, functionality, token, testing, and verification checklist.
+
+## Scripts
+
+- `node .agents/skills/component-quality-pass/scripts/list-preview-routes.mjs`
+  Lists registered preview routes as `http://localhost:5173/#/<id>`. Supports `--section`, `--family`, `--scope`, `--id`, `--json`.
+- `node .agents/skills/component-quality-pass/scripts/scan-quality-smells.mjs`
+  Reports common token, style, layering, and API smells. Treat output as a triage list, not proof of a bug.
+
+Use the scripts to focus the audit, but do not stop at script output. The Browser plugin + Playwright visual pass is mandatory for UI consistency work; do not replace it with static checks or a single screenshot.

package/.agents/skills/component-quality-pass/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Component Quality Pass"
+  short_description: "Audit component visuals, APIs, and tests"
+  default_prompt: "Use $component-quality-pass to run a visual, API, token, and test consistency pass over this component library."

package/.agents/skills/component-quality-pass/references/audit-workflow.md

@@ -0,0 +1,133 @@
+# Component Quality Audit Workflow
+
+## Route Coverage
+
+Start with the registered preview routes, not memory:
+
+```bash
+node .agents/skills/component-quality-pass/scripts/list-preview-routes.mjs
+node .agents/skills/component-quality-pass/scripts/list-preview-routes.mjs --section Features
+node .agents/skills/component-quality-pass/scripts/list-preview-routes.mjs --scope composed/commerce
+```
+
+For each relevant route:
+
+1. Open the route with the Browser plugin's in-app browser and Playwright automation.
+2. Wait for lazy modules, rendering, fonts, and async example data to settle.
+3. Inspect the first viewport.
+4. Validate every visible example/variant/state on the page, not just the first demo. For tabbed Preview/Code examples, inspect the rendered Preview pane; inspect Code only when source display is part of the defect.
+5. Exercise interactive examples enough to expose their states: open menus/popovers/dialogs, toggle density/selection controls, type into search fields, trigger empty/loading/error states when the page exposes them.
+6. Scroll to the middle and bottom; many defects appear below the fold.
+7. Check desktop and narrow widths.
+8. Capture screenshots when changing visuals or when reporting defects.
+
+Do not claim a route is clean after only opening it at the top.
+Do not claim a component family is clean until every documented size variant, tone variant, density variant, and meaningful state shown in preview has been inspected.
+
+## Visual Checklist
+
+Check every inspected page for:
+
+- Header/body spacing: content must not touch the title band, and related elements should not be separated by ornamental gaps.
+- Local rhythm: compact rows usually use `gap-0.5`, `gap-1`, or `gap-1.5`; larger `gap-3+` needs real grouping intent.
+- Typography: admin surfaces default to `sm` and `xs`; `text-base` is rare and should not appear in dense rows/cards.
+- Color: semantic states use `success`, `warning`, `destructive`, `info`, `primary`, `muted`; avoid raw hue classes and accidental `primary-foreground` text.
+- Tokenization: spacing, radius, text, row density, semantic color, and component-specific values should come from tokens or established wrappers. Literal one-off values need a clear, local reason.
+- Size consistency: `xs`/`sm`/`md`/`lg` variants should progress predictably across height, padding, icon size, text size, and radius. Compare siblings side-by-side and flag accidental jumps.
+- Borders: avoid one-sided "AI-looking" accent borders unless the component domain explicitly calls for it.
+- Icons: no icon clutter in metadata/labels; prefer text, `MetadataList`, or `Item` where the data is descriptive rather than actionable.
+- Cards: no cards inside cards unless the inner unit is a genuine repeated item, modal, or framed tool.
+- Tables: row actions belong in the table row action affordance/menu pattern, not permanent inline action columns unless the table API explicitly calls for action cells.
+- Responsive behavior: text must not overflow or collide on narrow widths; fixed-format elements need stable dimensions.
+- Cross-variant consistency: variants of the same surface should keep matching whitespace, alignment, action placement, focus states, and content hierarchy unless the variant intentionally changes those rules.
+
+## Structure Checklist
+
+Read the component and its neighbors before editing. Verify:
+
+- Layer boundaries match `component-library-rules`.
+- `base` wrappers are used instead of raw shadcn imports outside `base`.
+- `Item` is used for media + title/description + actions rows.
+- `SmartCard` is used for card chrome, title, description, footer, and dividers.
+- `MetadataList` or display primitives are used for label/value metadata.
+- `FormField` / `ControlledFormField` wraps label/control/error rows.
+- Feature folders expose `index.ts`, types, strings, hooks/partials where relevant.
+- Public roots include `{kebab-name}--component` on the actual DOM element.
+- Preview pages remain thin examples of real APIs, not private component copies.
+
+## Functionality Checklist
+
+For functional features, verify default props and all relevant callbacks:
+
+- Controlled value + `onValueChange` or `onChange`.
+- Submit/add/edit/remove/delete callbacks.
+- Row/item/result selection callbacks.
+- Async `fetcher` callback, debounce/cancel behavior, empty/error/loading states.
+- `onError` for async failures.
+- `strings` deep-partial overrides.
+- Slots and render-props for replaceable internals.
+- Accessors for consumer domain shapes.
+- No router, query library, framework, backend SDK, locale detection, or app ambient types.
+
+If a component cannot be used standalone with realistic default props and callbacks, fix the component API.
+
+## Tokenization And Static Scan
+
+Run:
+
+```bash
+node .agents/skills/component-quality-pass/scripts/scan-quality-smells.mjs
+```
+
+Investigate every report in touched areas. Common valid exceptions exist, but they must be intentional.
+
+High-priority smells:
+
+- `text-[10px]`, `text-[11px]`, `text-[13px]`, raw arbitrary colors.
+- `text-orange-*`, `bg-blue-*`, `border-purple-*`, etc. where semantic tokens exist.
+- `text-primary-foreground` outside actual primary backgrounds.
+- `bg-chart-*` outside real multi-series charts.
+- `focus:` instead of `focus-visible:`.
+- Raw `<button>`/`<input>` where base components exist.
+- Direct `@/components/ui/*` imports outside `src/components/base/**`.
+- Unguarded `console.warn` / `console.error`.
+- `navigator.language`, router imports, query-library imports, backend SDK imports.
+
+## Testing Checklist
+
+Use tests to lock functional contracts, not screenshots:
+
+- Base/composed: render contract, provider size/default resolution, slots, BEM hook if public.
+- Features: callback payloads, controlled state, strings overrides, slots/render-props, async fetcher success/error, add/edit/remove flows.
+- Hooks: state transitions, debounce/cancel behavior, error callbacks.
+- Avoid snapshots; use explicit assertions.
+
+Useful commands:
+
+```bash
+npm run typecheck
+npm run lint:architecture
+npm run test:exports
+npm run lint
+npx vitest run src/components/features --pool=threads --maxWorkers=1
+npm test -- --pool=threads --maxWorkers=1
+```
+
+For generated docs:
+
+```bash
+npm run docs:check-props
+npm run docs:sync-skill -- --check
+```
+
+If a generator check rewrites files on each run, report it as non-converging and inspect the diff; do not call it passed.
+
+## Final Report
+
+Keep the final report concrete:
+
+- Files/components changed.
+- Routes visually inspected and viewport coverage.
+- Functional tests added or updated.
+- Commands run and pass/fail status.
+- Remaining defects, generator drift, or dirty-worktree risks.

package/.agents/skills/component-quality-pass/scripts/list-preview-routes.mjs

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+const args = process.argv.slice(2);
+const filters = new Map();
+let asJson = false;
+
+for (let i = 0; i < args.length; i += 1) {
+	const arg = args[i];
+	if (arg === '--json') {
+		asJson = true;
+		continue;
+	}
+	if (arg.startsWith('--')) {
+		const key = arg.slice(2);
+		const value = args[i + 1];
+		if (!value || value.startsWith('--')) {
+			throw new Error(`Missing value for ${arg}`);
+		}
+		filters.set(key, value.toLowerCase());
+		i += 1;
+	}
+}
+
+const registryPath = resolve(process.cwd(), 'src/preview/registry.tsx');
+const source = readFileSync(registryPath, 'utf8');
+const entries = [];
+const scopeRules = [];
+const scopeRulePattern = /\{\s*prefix:\s*'([^']+)'\s*,\s*scope:\s*'([^']+)'\s*\}/g;
+
+for (const match of source.matchAll(scopeRulePattern)) {
+	scopeRules.push({ prefix: match[1], scope: match[2] });
+}
+
+const entryPattern = /\{\s*id:\s*'([^']+)'\s*,\s*label:\s*'([^']+)'\s*,\s*section:\s*'([^']+)'\s*,\s*family:\s*'([^']+)'([^}]*)\}/g;
+
+for (const match of source.matchAll(entryPattern)) {
+	const [, id, label, section, family, rest] = match;
+	const explicitScope = rest.match(/scope:\s*'([^']+)'/)?.[1];
+	const derivedScope =
+		explicitScope ?? scopeRules.find((rule) => id.startsWith(rule.prefix))?.scope ?? '';
+	const status = rest.match(/status:\s*'([^']+)'/)?.[1] ?? '';
+	entries.push({
+		id,
+		label,
+		section,
+		family,
+		scope: derivedScope,
+		status,
+		url: `http://localhost:5173/#/${id}`,
+	});
+}
+
+const filtered = entries.filter((entry) => {
+	for (const [key, value] of filters) {
+		const actual = String(entry[key] ?? '').toLowerCase();
+		if (!actual.includes(value)) return false;
+	}
+	return true;
+});
+
+if (asJson) {
+	console.log(JSON.stringify(filtered, null, 2));
+} else {
+	for (const entry of filtered) {
+		const scope = entry.scope ? ` scope=${entry.scope}` : '';
+		const status = entry.status ? ` status=${entry.status}` : '';
+		console.log(`${entry.url}  [${entry.section} / ${entry.family}] ${entry.label}${scope}${status}`);
+	}
+}

package/.agents/skills/component-quality-pass/scripts/scan-quality-smells.mjs

@@ -0,0 +1,213 @@
+#!/usr/bin/env node
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { join, relative } from 'node:path';
+
+const roots = ['src/components', 'src/preview/pages'];
+const exts = new Set(['.ts', '.tsx', '.mdx']);
+const maxReportsPerRule = 80;
+
+function isCommentLine(line) {
+	const trimmed = line.trim();
+	return (
+		trimmed.startsWith('//') ||
+		trimmed.startsWith('*') ||
+		trimmed.startsWith('{/*') ||
+		trimmed.startsWith('/*')
+	);
+}
+
+function countUnescapedBackticks(line) {
+	let count = 0;
+	for (let index = 0; index < line.length; index += 1) {
+		if (line[index] !== '`') continue;
+		let slashCount = 0;
+		for (let cursor = index - 1; cursor >= 0 && line[cursor] === '\\'; cursor -= 1) {
+			slashCount += 1;
+		}
+		if (slashCount % 2 === 0) count += 1;
+	}
+	return count;
+}
+
+function getTemplateLiteralLines(lines) {
+	const templateLines = new Set();
+	let inTemplate = false;
+
+	for (let index = 0; index < lines.length; index += 1) {
+		const backtickCount = countUnescapedBackticks(lines[index]);
+		if (inTemplate || backtickCount > 0) {
+			templateLines.add(index);
+		}
+		if (backtickCount % 2 === 1) {
+			inTemplate = !inTemplate;
+		}
+	}
+
+	return templateLines;
+}
+
+function hasNearbyDevGuard(lines, index) {
+	const start = Math.max(0, index - 10);
+	for (let cursor = start; cursor <= index; cursor += 1) {
+		if (/import\.meta\.env(?:\?\.DEV|\.DEV)/.test(lines[cursor])) return true;
+	}
+	return false;
+}
+
+function hasNearbyPrimarySurface(lines, index) {
+	const start = Math.max(0, index - 2);
+	const end = Math.min(lines.length - 1, index + 4);
+	for (let cursor = start; cursor <= end; cursor += 1) {
+		if (
+			/\bbg-primary\b|selection:bg-primary|data-\[[^\]]+\]:bg-primary|\bfill-primary\b|\bstroke-primary-foreground\b/.test(
+				lines[cursor],
+			)
+		) {
+			return true;
+		}
+	}
+	return false;
+}
+
+function hasNearbyNativeHiddenInputReason(lines, index) {
+	const end = Math.min(lines.length - 1, index + 8);
+	for (let cursor = index; cursor <= end; cursor += 1) {
+		if (/\btype=["'](?:hidden|file)["']|\bhidden\b/.test(lines[cursor])) return true;
+	}
+	return false;
+}
+
+function hasNearbyHiddenTriggerReason(lines, index) {
+	const end = Math.min(lines.length - 1, index + 8);
+	for (let cursor = index; cursor <= end; cursor += 1) {
+		if (/className=["']sr-only["']|tabIndex=\{-1\}/.test(lines[cursor])) return true;
+	}
+	return false;
+}
+
+const rules = [
+	{
+		id: 'arbitrary-text-px',
+		pattern: /text-\[(?:10|11|13)px\]|text-\[[0-9.]+px\]/,
+		message: 'Arbitrary pixel text size; use typography tokens/components.',
+	},
+	{
+		id: 'raw-hue-color',
+		pattern: /\b(?:text|bg|border|ring|fill|stroke)-(?:red|orange|yellow|green|blue|purple|pink|indigo|cyan|teal|emerald|amber|lime|rose|sky|violet)-\d{2,3}\b/,
+		message: 'Raw hue utility; prefer semantic tokens.',
+	},
+	{
+		id: 'primary-foreground-text',
+		pattern: /\btext-primary-foreground\b/,
+		message: 'primary-foreground text outside primary backgrounds is usually wrong.',
+		ignoreLine: (line, context) =>
+			/\bbg-primary\b|selection:bg-primary|data-\[[^\]]+\]:bg-primary/.test(line) ||
+			hasNearbyPrimarySurface(context.lines, context.index),
+	},
+	{
+		id: 'chart-token-outside-chart',
+		pattern: /\b(?:text|bg|border|fill|stroke)-chart-[1-5]\b/,
+		message: 'Chart token outside real chart usage; use semantic tokens.',
+		skipPath: /chart|Chart/,
+	},
+	{
+		id: 'focus-not-focus-visible',
+		pattern: /\bfocus:(?!visible)(?!\s*\()/,
+		message: 'Use focus-visible for interactive focus rings.',
+		skipPath: /src\/components\/ui\//,
+	},
+	{
+		id: 'raw-button',
+		pattern: /<button\b/,
+		message: 'Raw button; use base Button unless this is primitive/internal code.',
+		skipPath: /\.test\.|src\/components\/ui\/|src\/components\/base\//,
+		ignoreLine: (line, context) =>
+			/render=\{\s*<button\b/.test(line) ||
+			hasNearbyHiddenTriggerReason(context.lines, context.index),
+	},
+	{
+		id: 'raw-input',
+		pattern: /<input\b/,
+		message: 'Raw input; use base form fields unless hidden/native input is required.',
+		skipPath: /\.test\.|src\/components\/ui\/|src\/components\/base\/forms\//,
+		ignoreLine: (_line, context) =>
+			hasNearbyNativeHiddenInputReason(context.lines, context.index),
+	},
+	{
+		id: 'direct-ui-import',
+		pattern: /from ['"]@\/components\/ui\//,
+		message: 'Direct ui primitive import outside base wrapper.',
+		skipPath: /src\/components\/base\/|src\/components\/ui\/|src\/preview\/pages\/ui\//,
+	},
+	{
+		id: 'framework-import',
+		pattern: /from ['"](?:@inertiajs|next\/|react-router|@tanstack\/react-router|@tanstack\/react-query|ziggy-js|vite-bundled-i18n)/,
+		message: 'Framework/query/i18n import in component library surface.',
+	},
+	{
+		id: 'locale-detection',
+		pattern: /navigator\.language|navigator\.languages/,
+		message: 'Library should accept locale; do not detect browser locale.',
+	},
+	{
+		id: 'console-unguarded',
+		pattern: /console\.(?:warn|error)\(/,
+		message: 'Console calls must be DEV-guarded and paired with callbacks for real errors.',
+		ignoreLine: (_line, context) =>
+			hasNearbyDevGuard(context.lines, context.index),
+	},
+];
+
+function walk(dir, files = []) {
+	for (const name of readdirSync(dir)) {
+		if (name === 'node_modules' || name === 'dist') continue;
+		const path = join(dir, name);
+		const stat = statSync(path);
+		if (stat.isDirectory()) walk(path, files);
+		else if (exts.has(path.slice(path.lastIndexOf('.')))) files.push(path);
+	}
+	return files;
+}
+
+const reports = new Map(rules.map((rule) => [rule.id, []]));
+
+for (const root of roots) {
+	for (const file of walk(root)) {
+		const rel = relative(process.cwd(), file);
+		const lines = readFileSync(file, 'utf8').split(/\r?\n/);
+		const templateLiteralLines = getTemplateLiteralLines(lines);
+		for (const rule of rules) {
+			if (rule.skipPath?.test(rel)) continue;
+			for (let index = 0; index < lines.length; index += 1) {
+				if (isCommentLine(lines[index]) || templateLiteralLines.has(index)) continue;
+				if (!rule.pattern.test(lines[index])) continue;
+				if (rule.ignoreLine?.(lines[index], { lines, index, rel })) continue;
+				const bucket = reports.get(rule.id);
+				if (bucket.length < maxReportsPerRule) {
+					bucket.push({ file: rel, line: index + 1, text: lines[index].trim() });
+				}
+			}
+		}
+	}
+}
+
+let total = 0;
+for (const rule of rules) {
+	const bucket = reports.get(rule.id);
+	if (bucket.length === 0) continue;
+	total += bucket.length;
+	console.log(`\n${rule.id}: ${rule.message}`);
+	for (const report of bucket) {
+		console.log(`  ${report.file}:${report.line}  ${report.text}`);
+	}
+	if (bucket.length === maxReportsPerRule) {
+		console.log(`  ... capped at ${maxReportsPerRule} reports`);
+	}
+}
+
+if (total === 0) {
+	console.log('No quality smells found by static scan.');
+} else {
+	console.log(`\n${total} potential smells found. Triage manually; static output is not proof of a bug.`);
+	process.exitCode = 1;
+}