@kerfjs/ui 5.0.0-beta.18 → 5.0.0-beta.21

package/doctor/cli.mjs

@@ -0,0 +1,115 @@
+#!/usr/bin/env node
+
+import console from 'node:console';
+import { execFile } from 'node:child_process';
+import { writeFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import process from 'node:process';
+import { promisify } from 'node:util';
+
+import { formatUiDoctorText, runUiDoctor, UI_DOCTOR_EXIT } from './index.mjs';
+
+const execFileAsync = promisify(execFile);
+const args = process.argv.slice(2);
+const take = (name, repeat = false) => {
+  const values = [];
+  while (args.includes(name)) {
+    const index = args.indexOf(name);
+    const value = args[index + 1];
+    if (!value || value.startsWith('--'))
+      throw new Error(`${name} requires a value.`);
+    args.splice(index, 2);
+    values.push(value);
+    if (!repeat) break;
+  }
+  return repeat ? values : values[0];
+};
+
+async function changedPaths(root) {
+  const { stdout: tracked } = await execFileAsync(
+    'git',
+    ['diff', '--name-only', '--diff-filter=ACMR', 'HEAD', '--'],
+    { cwd: root },
+  );
+  const { stdout: untracked } = await execFileAsync(
+    'git',
+    ['ls-files', '--others', '--exclude-standard'],
+    { cwd: root },
+  );
+  return [
+    ...new Set(`${tracked}\n${untracked}`.split(/\r?\n/).filter(Boolean)),
+  ].sort();
+}
+
+try {
+  if (args.includes('--help') || args.includes('-h')) {
+    console.log(`Usage: kerf-ui-doctor [--full | --changed] [options]
+
+Options:
+  --root <path>          Workspace root (default: current directory)
+  --package <name|path>  Select one workspace package
+  --path <path>          Restrict changed mode (repeatable)
+  --config <path>        Doctor config (default: .kerf-ui-doctor.json)
+  --browser-url <url>    Explicitly enable browser evaluation
+  --browser <list>       Comma-separated chromium,firefox,webkit
+  --eslint <preset>      recommended-ui or strict-ui
+  --format <format>      text or json (default: text)
+  --output <path>        Also write the merged report
+  --no-cache             Disable the content-addressed cache
+
+Exit codes: 0 clean, 1 findings, 2 configuration/tool failure, 130 cancelled.`);
+    process.exit(0);
+  }
+  const root = resolve(take('--root') ?? process.cwd());
+  const packageSelector = take('--package');
+  const explicitPaths = take('--path', true);
+  const configPath = take('--config');
+  const url = take('--browser-url');
+  const browserList = take('--browser');
+  const eslintConfig = take('--eslint') ?? 'recommended-ui';
+  const format = take('--format') ?? 'text';
+  const output = take('--output');
+  const full = args.includes('--full');
+  const changed = args.includes('--changed');
+  const noCache = args.includes('--no-cache');
+  const known = new Set(['--full', '--changed', '--no-cache']);
+  const unknown = args.filter((item) => !known.has(item));
+  if (unknown.length)
+    throw new Error(`Unknown arguments: ${unknown.join(' ')}`);
+  if (full && changed)
+    throw new Error('--full and --changed are mutually exclusive.');
+  if (!['text', 'json'].includes(format))
+    throw new Error('--format must be text or json.');
+  if (!['recommended-ui', 'strict-ui'].includes(eslintConfig))
+    throw new Error('--eslint must be recommended-ui or strict-ui.');
+  const abort = new globalThis.AbortController();
+  process.once('SIGINT', () => abort.abort());
+  const paths =
+    changed && !explicitPaths.length ? await changedPaths(root) : explicitPaths;
+  const report = await runUiDoctor({
+    root,
+    package: packageSelector,
+    mode: changed ? 'changed' : full ? 'full' : undefined,
+    paths,
+    configPath,
+    cache: !noCache,
+    signal: abort.signal,
+    eslintConfig,
+    browser: url
+      ? { url, browsers: browserList?.split(',').map((item) => item.trim()) }
+      : undefined,
+  });
+  const rendered =
+    format === 'json'
+      ? JSON.stringify(report, null, 2)
+      : formatUiDoctorText(report);
+  if (output) await writeFile(resolve(root, output), `${rendered}\n`);
+  else console.log(rendered);
+  process.exitCode = report.exitCode;
+} catch (error) {
+  console.error(`kerf-ui-doctor: ${error.message}`);
+  process.exitCode =
+    process.exitCode === UI_DOCTOR_EXIT.cancelled
+      ? process.exitCode
+      : UI_DOCTOR_EXIT.configuration;
+}

package/doctor/config.schema.json

@@ -0,0 +1,68 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/brianwestphal/kerf/main/ui/doctor/config.schema.json",
+  "title": "Kerf UI doctor configuration",
+  "type": "object",
+  "required": ["schemaVersion"],
+  "properties": {
+    "$schema": { "type": "string" },
+    "schemaVersion": { "const": 1 },
+    "mode": { "enum": ["full", "changed"] },
+    "package": { "type": "string", "minLength": 1 },
+    "stages": {
+      "type": "object",
+      "properties": {
+        "catalog": { "type": "boolean" },
+        "typescript": { "type": "boolean" },
+        "eslint": { "type": "boolean" },
+        "analyzer": { "type": "boolean" },
+        "browser": { "type": "boolean" }
+      },
+      "additionalProperties": false
+    },
+    "browser": {
+      "type": "object",
+      "required": ["url"],
+      "properties": {
+        "url": { "type": "string", "pattern": "^https?://" },
+        "browsers": {
+          "type": "array",
+          "items": { "enum": ["chromium", "firefox", "webkit"] },
+          "uniqueItems": true
+        },
+        "retention": { "enum": ["always", "on-failure", "never"] },
+        "outputDirectory": { "$ref": "#/$defs/path" },
+        "reportPath": { "$ref": "#/$defs/path" }
+      },
+      "additionalProperties": false
+    },
+    "cache": { "type": "boolean" },
+    "suppressions": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "rules", "target", "rationale"],
+        "properties": {
+          "id": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" },
+          "rules": {
+            "type": "array",
+            "items": { "type": "string", "minLength": 1 },
+            "minItems": 1,
+            "uniqueItems": true
+          },
+          "target": { "$ref": "#/$defs/path" },
+          "rationale": { "type": "string", "minLength": 12 }
+        },
+        "additionalProperties": false
+      }
+    }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "path": {
+      "type": "string",
+      "minLength": 1,
+      "pattern": "^(?!/)(?!.*(^|/)\\.\\.(/|$))(?!.*[?*]).+"
+    }
+  }
+}

package/doctor/index.d.mts

@@ -0,0 +1,116 @@
+export type UiDoctorSeverity = 'error' | 'warning' | 'review' | 'info';
+export type UiDoctorStageId =
+  | 'catalog'
+  | 'typescript'
+  | 'eslint'
+  | 'analyzer'
+  | 'browser'
+  | 'doctor'
+  | 'merged';
+export type UiDoctorStageStatus =
+  'ran' | 'cached' | 'skipped' | 'unavailable' | 'failed' | 'cancelled';
+
+export interface UiDoctorSuppression {
+  id: string;
+  rules: string[];
+  target: string;
+  rationale: string;
+}
+
+export interface UiDoctorConfig {
+  $schema?: string;
+  schemaVersion: 1;
+  mode?: 'full' | 'changed';
+  package?: string;
+  stages?: Partial<
+    Record<
+      'catalog' | 'typescript' | 'eslint' | 'analyzer' | 'browser',
+      boolean
+    >
+  >;
+  browser?: {
+    url: string;
+    browsers?: Array<'chromium' | 'firefox' | 'webkit'>;
+    retention?: 'always' | 'on-failure' | 'never';
+    outputDirectory?: string;
+    reportPath?: string;
+  };
+  cache?: boolean;
+  suppressions?: UiDoctorSuppression[];
+}
+
+export interface UiDoctorDiagnostic {
+  id: string;
+  severity: UiDoctorSeverity;
+  stage: UiDoctorStageId | string;
+  message: string;
+  location?: { file: string; line: number; column: number; path?: string };
+  dom?: { context?: string; selector: string };
+  evidence?: unknown;
+  catalogFacts?: unknown;
+  documentation?: string;
+  action?: string;
+  sources?: string[];
+}
+
+export interface UiDoctorReport {
+  schemaVersion: 1;
+  tool: { name: '@kerfjs/ui/doctor'; reportVersion: 1 };
+  mode: 'full' | 'changed';
+  root: '.';
+  package: string;
+  paths: string[];
+  stages: Array<{ id: string; status: UiDoctorStageStatus; detail?: string }>;
+  diagnostics: UiDoctorDiagnostic[];
+  suppressions: Array<
+    UiDoctorDiagnostic & { suppression: { id: string; rationale: string } }
+  >;
+  summary: {
+    errors: number;
+    warnings: number;
+    review: number;
+    suppressed: number;
+  };
+  exitCode: 0 | 1 | 2 | 130;
+  cache: { hit: boolean; key: string };
+}
+
+export const UI_DOCTOR_SCHEMA_VERSION: 1;
+export const UI_DOCTOR_EXIT: Readonly<{
+  clean: 0;
+  findings: 1;
+  configuration: 2;
+  cancelled: 130;
+}>;
+export const UI_DOCTOR_RULES: Readonly<
+  Record<string, { severity: UiDoctorSeverity; title: string }>
+>;
+export function validateUiDoctorConfig(
+  config: unknown,
+  source?: string,
+): UiDoctorDiagnostic[];
+export function readUiDoctorConfig(
+  root: string,
+  path?: string,
+): Promise<{
+  path: string;
+  config: UiDoctorConfig;
+  diagnostics: UiDoctorDiagnostic[];
+}>;
+export function resolveUiDoctorPackage(
+  root: string,
+  selector?: string,
+): Promise<string>;
+export function runUiDoctor(options?: {
+  root?: string;
+  package?: string;
+  mode?: 'full' | 'changed';
+  paths?: string[];
+  config?: UiDoctorConfig;
+  configPath?: string;
+  cache?: boolean;
+  signal?: AbortSignal;
+  browser?: UiDoctorConfig['browser'];
+  eslintConfig?: 'recommended-ui' | 'strict-ui';
+}): Promise<UiDoctorReport>;
+export function formatUiDoctorText(report: UiDoctorReport): string;