@kerfjs/ui 4.4.1 → 4.5.0-beta.1

package/doctor/report.schema.json

@@ -0,0 +1,118 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/brianwestphal/kerf/main/ui/doctor/report.schema.json",
+  "title": "Kerf UI doctor report",
+  "type": "object",
+  "required": [
+    "schemaVersion",
+    "tool",
+    "mode",
+    "root",
+    "package",
+    "paths",
+    "stages",
+    "diagnostics",
+    "suppressions",
+    "summary",
+    "exitCode",
+    "cache"
+  ],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "tool": { "const": { "name": "@kerfjs/ui/doctor", "reportVersion": 1 } },
+    "mode": { "enum": ["full", "changed"] },
+    "root": { "const": "." },
+    "package": { "type": "string" },
+    "paths": { "type": "array", "items": { "type": "string" } },
+    "stages": { "type": "array", "items": { "$ref": "#/$defs/stage" } },
+    "diagnostics": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/diagnostic" }
+    },
+    "suppressions": {
+      "type": "array",
+      "items": {
+        "allOf": [
+          { "$ref": "#/$defs/diagnostic" },
+          {
+            "type": "object",
+            "required": ["suppression"],
+            "properties": {
+              "suppression": {
+                "type": "object",
+                "required": ["id", "rationale"],
+                "properties": {
+                  "id": { "type": "string" },
+                  "rationale": { "type": "string" }
+                },
+                "additionalProperties": false
+              }
+            }
+          }
+        ]
+      }
+    },
+    "summary": {
+      "type": "object",
+      "required": ["errors", "warnings", "review", "suppressed"],
+      "properties": {
+        "errors": { "type": "integer", "minimum": 0 },
+        "warnings": { "type": "integer", "minimum": 0 },
+        "review": { "type": "integer", "minimum": 0 },
+        "suppressed": { "type": "integer", "minimum": 0 }
+      },
+      "additionalProperties": false
+    },
+    "exitCode": { "enum": [0, 1, 2, 130] },
+    "cache": {
+      "type": "object",
+      "required": ["hit", "key"],
+      "properties": {
+        "hit": { "type": "boolean" },
+        "key": { "type": "string", "pattern": "^[a-f0-9]{64}$" }
+      },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "stage": {
+      "type": "object",
+      "required": ["id", "status"],
+      "properties": {
+        "id": { "type": "string" },
+        "status": {
+          "enum": [
+            "ran",
+            "cached",
+            "skipped",
+            "unavailable",
+            "failed",
+            "cancelled"
+          ]
+        },
+        "detail": { "type": "string" }
+      },
+      "additionalProperties": false
+    },
+    "diagnostic": {
+      "type": "object",
+      "required": ["id", "severity", "stage", "message"],
+      "properties": {
+        "id": { "type": "string" },
+        "severity": { "enum": ["error", "warning", "review", "info"] },
+        "stage": { "type": "string" },
+        "message": { "type": "string" },
+        "location": { "type": "object" },
+        "dom": { "type": "object" },
+        "evidence": {},
+        "catalogFacts": {},
+        "documentation": { "type": "string" },
+        "action": { "type": "string" },
+        "sources": { "type": "array", "items": { "type": "string" } },
+        "suppression": { "type": "object" }
+      },
+      "additionalProperties": false
+    }
+  }
+}

package/evaluator/cli.mjs

@@ -0,0 +1,89 @@
+#!/usr/bin/env node
+
+import console from 'node:console';
+import { resolve } from 'node:path';
+import process from 'node:process';
+
+import { evaluateUi, formatUiEvaluationText } from './index.mjs';
+
+const args = process.argv.slice(2);
+const take = (name) => {
+  const index = args.indexOf(name);
+  if (index < 0) return undefined;
+  const value = args[index + 1];
+  if (!value || value.startsWith('--'))
+    throw new Error(`${name} requires a value.`);
+  args.splice(index, 2);
+  return value;
+};
+
+try {
+  if (args.includes('--help') || args.includes('-h')) {
+    console.log(`Usage: kerf-ui-evaluate --url <running-app> [options]
+
+Options:
+  --root <path>          Workspace root (default: current directory)
+  --start <path>         Profile discovery start directory (default: root)
+  --profile <path>       Override the package-default profile
+  --browser <list>       Comma-separated chromium,firefox,webkit
+  --output <directory>   Evidence directory (default: kerf-ui-evidence)
+  --report <path>        Report JSON path (default: <output>/report.json)
+  --timeout <ms>         Per-operation timeout (default: 15000)
+  --settle <ms>          App settle delay after navigation (default: 100)
+  --retention <policy>   always, on-failure, or never
+  --format <format>      text or json (default: text)
+  --no-fail              Exit zero even when objective diagnostics fail`);
+    process.exit(0);
+  }
+  const url = take('--url');
+  const root = resolve(take('--root') ?? process.cwd());
+  const startDirectory = resolve(root, take('--start') ?? '.');
+  const packageProfile = take('--profile');
+  const outputDirectory = resolve(root, take('--output') ?? 'kerf-ui-evidence');
+  const reportValue = take('--report');
+  const reportPath = reportValue
+    ? resolve(root, reportValue)
+    : resolve(outputDirectory, 'report.json');
+  const browserValue = take('--browser');
+  const browsers = browserValue
+    ? browserValue.split(',').map((value) => value.trim())
+    : undefined;
+  const timeoutMs = Number(take('--timeout') ?? 15_000);
+  const settleMs = Number(take('--settle') ?? 100);
+  const retention = take('--retention') ?? 'on-failure';
+  const format = take('--format') ?? 'text';
+  const noFail = args.includes('--no-fail');
+  const unknown = args.filter((argument) => argument !== '--no-fail');
+  if (unknown.length)
+    throw new Error(`Unknown arguments: ${unknown.join(' ')}`);
+  if (!url) throw new Error('--url is required.');
+  if (!['text', 'json'].includes(format))
+    throw new Error('--format must be text or json.');
+  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0)
+    throw new Error('--timeout must be a positive number.');
+  if (!Number.isFinite(settleMs) || settleMs < 0)
+    throw new Error('--settle must be a non-negative number.');
+
+  const report = await evaluateUi({
+    url,
+    workspaceRoot: root,
+    startDirectory,
+    packageProfile: packageProfile && resolve(root, packageProfile),
+    outputDirectory,
+    reportPath,
+    browsers,
+    timeoutMs,
+    settleMs,
+    retention,
+  });
+  console.log(
+    format === 'json'
+      ? JSON.stringify(report, null, 2)
+      : formatUiEvaluationText(report),
+  );
+  console.error(`Report: ${reportPath}`);
+  if (!noFail && !report.summary.passed) process.exitCode = 1;
+} catch (error) {
+  console.error(`kerf-ui-evaluate: ${error.message}`);
+  process.exitCode = 2;
+}

package/evaluator/index.d.mts

@@ -0,0 +1,90 @@
+export type UiEvaluationBrowser = 'chromium' | 'firefox' | 'webkit';
+export type UiEvaluationRetention = 'always' | 'on-failure' | 'never';
+
+export interface UiEvaluationContext {
+  id: string;
+  width: number;
+  height: number;
+  zoom: number;
+  colorScheme: 'light' | 'dark';
+  reducedMotion?: 'reduce' | 'no-preference';
+}
+
+export interface UiEvaluationDiagnostic {
+  code: `KUI-B${number}`;
+  severity: 'error' | 'warning';
+  context: string;
+  message: string;
+  repair?: string;
+  selector?: string;
+  evidence?: unknown;
+}
+
+export interface UiEvaluationReport {
+  schemaVersion: 1;
+  tool: { name: '@kerfjs/ui/evaluator'; reportVersion: 1 };
+  target: { url: string };
+  recordedAt: string;
+  profileFiles: string[];
+  contexts: Array<
+    UiEvaluationContext & {
+      browser: UiEvaluationBrowser;
+      evidence: unknown;
+      summary: { errors: number; warnings: number; passed: boolean };
+    }
+  >;
+  diagnostics: UiEvaluationDiagnostic[];
+  summary: { errors: number; warnings: number; passed: boolean };
+  artifacts: {
+    retention: UiEvaluationRetention;
+    files: Array<{ path: string; sha256: string }>;
+  };
+  subjectiveReview: {
+    status: 'not-recorded';
+    rubric: Array<{ id: string; prompt: string }>;
+    ratings: [];
+    note: string;
+  };
+}
+
+export const UI_EVALUATION_SCHEMA_VERSION: 1;
+export const UI_EVALUATION_RULES: Readonly<
+  Record<`KUI-B${number}`, { severity: 'error' | 'warning'; title: string }>
+>;
+export const SUBJECTIVE_REVIEW_RUBRIC: ReadonlyArray<{
+  id: string;
+  prompt: string;
+}>;
+export function buildEvaluationContexts(
+  overrides?: UiEvaluationContext[],
+): UiEvaluationContext[];
+export function contrastRatio(
+  foreground: string | number[],
+  background: string | number[],
+): number | null;
+export function createEvaluationReport(options: {
+  target: { url: string };
+  profileFiles: string[];
+  contexts: UiEvaluationReport['contexts'];
+  diagnostics: UiEvaluationDiagnostic[];
+  artifacts: UiEvaluationReport['artifacts']['files'];
+  recordedAt: string;
+  retention: UiEvaluationRetention;
+}): UiEvaluationReport;
+export function evaluateUi(options: {
+  url: string;
+  workspaceRoot?: string;
+  startDirectory?: string;
+  packageProfile?: string;
+  outputDirectory?: string;
+  reportPath?: string;
+  browsers?: UiEvaluationBrowser[];
+  contexts?: UiEvaluationContext[];
+  timeoutMs?: number;
+  settleMs?: number;
+  retention?: UiEvaluationRetention;
+  recordedAt?: string;
+  playwright?: unknown;
+  signal?: AbortSignal;
+}): Promise<UiEvaluationReport>;
+export function formatUiEvaluationText(report: UiEvaluationReport): string;