@kerfjs/ui 5.0.0-beta.8 → 5.0.0-beta.81

package/doctor/cli.mjs

@@ -0,0 +1,120 @@
+#!/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)
+  --fail-on <severity>   error, review, or warning (default: error)
+  --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 failOn = take('--fail-on');
+  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 (failOn && !['error', 'review', 'warning'].includes(failOn))
+    throw new Error('--fail-on must be error, review, or warning.');
+  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,
+    failOn,
+    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/component-style-checks.mjs

@@ -0,0 +1,457 @@
+import { readFile } from 'node:fs/promises';
+import { basename, dirname, extname, relative, resolve } from 'node:path';
+
+import postcss from 'postcss';
+import ts from 'typescript';
+
+import { loadApplicationUiProfile } from '../ai/application-ui-profile.mjs';
+import { isUiTraversalExcluded } from '../traversal-exclusions.mjs';
+
+const scriptExtensions = new Set(['.tsx', '.jsx']);
+const kebab = (name) =>
+  name
+    .replace(/([A-Z])([A-Z][a-z])/g, '$1-$2')
+    .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+    .toLowerCase();
+const componentName = (name) => /^[A-Z][A-Za-z0-9]*$/.test(name);
+const classNames = (value) =>
+  [...value.matchAll(/(?:^|\s)([a-z][a-z0-9_-]*)(?=\s|$)/g)].map(
+    (match) => match[1],
+  );
+const block = (name) => name.split(/__|--/)[0];
+const unknown = '\u0000';
+
+function combinations(left, right) {
+  if (left.length * right.length > 32) return [unknown];
+  return left.flatMap((a) => right.map((b) => a + b));
+}
+
+function staticPatterns(node, bindings = new Map(), seen = new Set()) {
+  if (!node) return [unknown];
+  if (ts.isIdentifier(node) && bindings.has(node.text) && !seen.has(node.text))
+    return staticPatterns(
+      bindings.get(node.text),
+      bindings,
+      new Set([...seen, node.text]),
+    );
+  if (
+    ts.isCallExpression(node) &&
+    ts.isPropertyAccessExpression(node.expression) &&
+    node.expression.name.text === 'join'
+  ) {
+    const target = node.expression.expression;
+    const array = ts.isIdentifier(target) ? bindings.get(target.text) : target;
+    if (array && ts.isArrayLiteralExpression(array)) {
+      const separator =
+        node.arguments[0] && ts.isStringLiteral(node.arguments[0])
+          ? node.arguments[0].text
+          : ',';
+      let patterns = [''];
+      for (const [index, element] of array.elements.entries())
+        patterns = combinations(
+          patterns,
+          staticPatterns(element, bindings, seen).map(
+            (part) => `${index ? separator : ''}${part}`,
+          ),
+        );
+      return patterns;
+    }
+  }
+  if (
+    ts.isParenthesizedExpression(node) ||
+    ts.isAsExpression(node) ||
+    ts.isTypeAssertionExpression(node)
+  )
+    return staticPatterns(node.expression, bindings, seen);
+  if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node))
+    return [node.text];
+  if (ts.isConditionalExpression(node))
+    return [
+      ...new Set([
+        ...staticPatterns(node.whenTrue, bindings, seen),
+        ...staticPatterns(node.whenFalse, bindings, seen),
+      ]),
+    ];
+  if (ts.isTemplateExpression(node)) {
+    let patterns = [node.head.text];
+    for (const span of node.templateSpans)
+      patterns = combinations(
+        combinations(patterns, staticPatterns(span.expression, bindings, seen)),
+        [span.literal.text],
+      );
+    return patterns;
+  }
+  if (
+    ts.isBinaryExpression(node) &&
+    node.operatorToken.kind === ts.SyntaxKind.PlusToken
+  )
+    return combinations(
+      staticPatterns(node.left, bindings, seen),
+      staticPatterns(node.right, bindings, seen),
+    );
+  return [unknown];
+}
+
+function guaranteedClasses(node, bindings) {
+  if (!node) return new Set();
+  if (
+    ts.isParenthesizedExpression(node) ||
+    ts.isAsExpression(node) ||
+    ts.isTypeAssertionExpression(node)
+  )
+    return guaranteedClasses(node.expression, bindings);
+  const patterns = staticPatterns(node, bindings);
+  const classes = new Set(classNames(patterns[0]));
+  for (const pattern of patterns.slice(1)) {
+    const other = new Set(classNames(pattern));
+    for (const name of classes) if (!other.has(name)) classes.delete(name);
+  }
+  return classes;
+}
+
+function returnedIntrinsic(node) {
+  while (node && ts.isParenthesizedExpression(node)) node = node.expression;
+  if (node && ts.isConditionalExpression(node))
+    return (
+      returnedIntrinsic(node.whenTrue) && returnedIntrinsic(node.whenFalse)
+    );
+  const tag =
+    node && ts.isJsxElement(node)
+      ? node.openingElement.tagName
+      : node && ts.isJsxSelfClosingElement(node)
+        ? node.tagName
+        : undefined;
+  return Boolean(tag && ts.isIdentifier(tag) && /^[a-z]/.test(tag.text));
+}
+
+function belongsToComponentReturn(node, owner) {
+  let scope = node.parent;
+  while (scope && !ts.isFunctionLike(scope)) scope = scope.parent;
+  if (!scope) return false;
+  if (ts.isFunctionDeclaration(scope)) return scope.name?.text === owner;
+  return (
+    ts.isArrowFunction(scope) &&
+    ts.isVariableDeclaration(scope.parent) &&
+    ts.isIdentifier(scope.parent.name) &&
+    scope.parent.name.text === owner
+  );
+}
+
+async function catalogAliases(workspaceRoot, packageRoot) {
+  const aliases = new Map();
+  const profile = await loadApplicationUiProfile({
+    workspaceRoot,
+    startDirectory: packageRoot,
+    knownRules: [],
+    packageProfile: resolve(
+      import.meta.dirname,
+      '../ai/application-ui-profile.defaults.json',
+    ),
+  });
+  for (const catalog of profile.profile?.catalogs ?? []) {
+    const owner = profile.provenance?.[`$catalogs.${catalog.package}`];
+    if (!owner || !catalog.selection?.path) continue;
+    try {
+      const selection = JSON.parse(
+        await readFile(resolve(dirname(owner), catalog.selection.path), 'utf8'),
+      );
+      const composition = catalog.composition?.path
+        ? JSON.parse(
+            await readFile(
+              resolve(dirname(owner), catalog.composition.path),
+              'utf8',
+            ),
+          )
+        : { entries: [] };
+      const composed = new Map(
+        (composition.entries ?? []).map((entry) => [entry.key, entry]),
+      );
+      for (const entry of selection.entries ?? []) {
+        if (!entry.source || !entry.name) continue;
+        const source = resolve(dirname(owner), entry.source);
+        const relativeSource = relative(packageRoot, source);
+        if (relativeSource === '..' || relativeSource.startsWith('../'))
+          continue;
+        const detail = composed.get(
+          `${selection.package ?? catalog.package}:${entry.id}`,
+        );
+        const classes = [
+          detail?.boundaries?.rootClass,
+          ...(detail?.boundaries?.publicClasses ?? []),
+          ...(entry.publicClasses ?? []),
+        ].filter(Boolean);
+        const styleSources = [
+          ...(detail?.styleSources ?? []),
+          ...(entry.styleSources ?? []),
+        ].map((style) => resolve(dirname(owner), style));
+        aliases.set(`${source}:${entry.name}`, {
+          classes: new Set(classes),
+          styles: new Set(styleSources),
+        });
+      }
+    } catch {
+      // The catalog stage reports invalid or missing artifacts.
+    }
+  }
+  return aliases;
+}
+
+function componentFacts(file, source) {
+  const syntax = file.endsWith('.tsx') ? ts.ScriptKind.TSX : ts.ScriptKind.JSX;
+  const ast = ts.createSourceFile(
+    file,
+    source,
+    ts.ScriptTarget.Latest,
+    true,
+    syntax,
+  );
+  const components = new Map();
+  const visit = (node, owner) => {
+    if (
+      ts.isFunctionDeclaration(node) &&
+      node.name &&
+      componentName(node.name.text)
+    )
+      owner = node.name.text;
+    if (
+      ts.isVariableDeclaration(node) &&
+      ts.isIdentifier(node.name) &&
+      componentName(node.name.text)
+    )
+      owner = node.name.text;
+    else if (
+      owner &&
+      ts.isVariableDeclaration(node) &&
+      ts.isIdentifier(node.name) &&
+      node.initializer
+    )
+      components.get(owner)?.bindings.set(node.name.text, node.initializer);
+    if (
+      owner &&
+      (ts.isJsxOpeningElement(node) || ts.isJsxSelfClosingElement(node))
+    ) {
+      if (ts.isIdentifier(node.tagName) && /^[a-z]/.test(node.tagName.text)) {
+        for (const attribute of node.attributes.properties) {
+          if (
+            !ts.isJsxAttribute(attribute) ||
+            !['class', 'className'].includes(attribute.name.text)
+          )
+            continue;
+          const value = attribute.initializer;
+          const classes =
+            value && ts.isStringLiteral(value)
+              ? classNames(value.text)
+              : value && ts.isJsxExpression(value)
+                ? guaranteedClasses(
+                    value.expression,
+                    components.get(owner)?.bindings,
+                  )
+                : [];
+          if (
+            value &&
+            ts.isJsxExpression(value) &&
+            staticPatterns(
+              value.expression,
+              components.get(owner)?.bindings,
+            ).every((pattern) => pattern === unknown)
+          )
+            components.get(owner).uncertain = true;
+          for (const name of classes) components.get(owner)?.add(name);
+        }
+      }
+    }
+    if (
+      owner &&
+      ts.isReturnStatement(node) &&
+      belongsToComponentReturn(node, owner) &&
+      returnedIntrinsic(node.expression)
+    )
+      components.get(owner).intrinsic = true;
+    if (
+      owner &&
+      ts.isArrowFunction(node) &&
+      ts.isVariableDeclaration(node.parent) &&
+      ts.isIdentifier(node.parent.name) &&
+      node.parent.name.text === owner &&
+      returnedIntrinsic(node.body)
+    )
+      components.get(owner).intrinsic = true;
+    ts.forEachChild(node, (child) => visit(child, owner));
+  };
+  const declarations = (node) => {
+    if (
+      ts.isFunctionDeclaration(node) &&
+      node.name &&
+      componentName(node.name.text)
+    )
+      components.set(
+        node.name.text,
+        Object.assign(new Set(), { bindings: new Map() }),
+      );
+    if (
+      ts.isVariableDeclaration(node) &&
+      ts.isIdentifier(node.name) &&
+      componentName(node.name.text)
+    )
+      components.set(
+        node.name.text,
+        Object.assign(new Set(), { bindings: new Map() }),
+      );
+    ts.forEachChild(node, declarations);
+  };
+  declarations(ast);
+  visit(ast);
+  return components;
+}
+
+function diagnostic(id, file, line, message, action) {
+  return {
+    id,
+    severity: 'error',
+    stage: 'analyzer',
+    message,
+    location: { file, line, column: 1 },
+    action,
+    documentation: '@kerfjs/ui/docs/ui-doctor.md#component-style-naming',
+    meaning: {
+      'KUI-D030': 'Component root class does not match its name',
+      'KUI-D031': 'Component stylesheet does not match its name',
+      'KUI-D032': 'Stylesheet selects another component class',
+    }[id],
+  };
+}
+
+export async function checkComponentStyles(
+  packageRoot,
+  inputs,
+  ownershipGroups = [],
+  selectedPaths,
+  workspaceRoot = packageRoot,
+) {
+  const aliases = await catalogAliases(workspaceRoot, packageRoot);
+  const scripts = new Map();
+  const styles = new Map();
+  const importedBy = new Map();
+  for (const file of inputs) {
+    if (isUiTraversalExcluded(packageRoot, file)) continue;
+    const extension = extname(file);
+    if (scriptExtensions.has(extension)) {
+      const source = await readFile(file, 'utf8');
+      scripts.set(file, componentFacts(file, source));
+      for (const match of source.matchAll(
+        /\bimport\s*(?:['"]|[^;]*?\bfrom\s*['"])(\.[^'"]+\.css)['"]/g,
+      )) {
+        const style = resolve(dirname(file), match[1]);
+        const importers = importedBy.get(style) ?? [];
+        importers.push(file);
+        importedBy.set(style, importers);
+      }
+    } else if (extension === '.css')
+      styles.set(file, await readFile(file, 'utf8'));
+  }
+  const owners = new Map();
+  for (const [file, components] of scripts)
+    for (const [name, classes] of components)
+      if (classes.has(kebab(name)))
+        owners.set(kebab(name), { file, name, classes });
+  const diagnostics = [];
+  for (const [file, source] of styles) {
+    if (
+      ownershipGroups.some((group) =>
+        group.styleSources?.some(
+          (style) => resolve(packageRoot, style) === file,
+        ),
+      )
+    )
+      continue;
+    const stem = basename(file, '.css');
+    const pair =
+      [...scriptExtensions]
+        .map((extension) => resolve(dirname(file), `${stem}${extension}`))
+        .find((candidate) => scripts.has(candidate)) ??
+      (importedBy.get(file)?.length === 1
+        ? importedBy.get(file)[0]
+        : undefined);
+    if (!pair) continue;
+    const path = relative(packageRoot, file).replaceAll('\\', '/');
+    if (
+      selectedPaths?.length &&
+      !selectedPaths.includes(path) &&
+      !selectedPaths.includes(relative(packageRoot, pair).replaceAll('\\', '/'))
+    )
+      continue;
+    const components = scripts.get(pair);
+    const matching =
+      [...components].find(([name]) => kebab(name) === stem) ??
+      [...components].find(([name]) =>
+        aliases.get(`${pair}:${name}`)?.styles.has(file),
+      );
+    if (!matching) {
+      const names = [...components.keys()];
+      if (names.length === 1)
+        diagnostics.push(
+          diagnostic(
+            'KUI-D031',
+            path,
+            1,
+            `${basename(file)} is paired with ${basename(pair)}, but its component ${names[0]} calls for ${kebab(names[0])}.css.`,
+            `Rename the stylesheet and its import to ${kebab(names[0])}.css, or rename the component and source pair.`,
+          ),
+        );
+      continue;
+    }
+    const [name, renderedClasses] = matching;
+    const declaredClasses =
+      aliases.get(`${pair}:${name}`)?.classes ?? new Set();
+    if (
+      renderedClasses.intrinsic &&
+      !renderedClasses.uncertain &&
+      !renderedClasses.has(stem) &&
+      ![...declaredClasses].some((className) => renderedClasses.has(className))
+    )
+      diagnostics.push(
+        diagnostic(
+          'KUI-D030',
+          relative(packageRoot, pair).replaceAll('\\', '/'),
+          1,
+          `${name} must render its own .${stem} root class.`,
+          `Add class="${stem}" to an element rendered by ${name}, then select that class in ${basename(file)}.`,
+        ),
+      );
+    let sheet;
+    try {
+      sheet = postcss.parse(source, { from: file });
+    } catch {
+      continue;
+    }
+    sheet.walkRules((rule) => {
+      if (
+        rule.parent?.type === 'atrule' &&
+        /keyframes$/i.test(rule.parent.name)
+      )
+        return;
+      const selected = [
+        ...new Set(
+          [...rule.selector.matchAll(/\.([a-z][a-z0-9_-]*)/gi)].map(
+            (match) => match[1],
+          ),
+        ),
+      ];
+      for (const className of selected) {
+        const foreign = owners.get(block(className));
+        if (!foreign || foreign.name === name || foreign.file === pair)
+          continue;
+        diagnostics.push(
+          diagnostic(
+            'KUI-D032',
+            path,
+            rule.source?.start?.line ?? 1,
+            `${basename(file)} selects .${className}, which belongs to ${foreign.name} in ${relative(packageRoot, foreign.file).replaceAll('\\', '/')}.`,
+            `Move this rule to ${kebab(foreign.name)}.css or configure ${foreign.name} through its public API.`,
+          ),
+        );
+      }
+    });
+  }
+  return diagnostics;
+}

package/doctor/config.schema.json

@@ -0,0 +1,94 @@
+{
+  "$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 },
+    "ownership": { "enum": ["package", "component"] },
+    "ownershipContext": { "enum": ["subject", "any", "any-package"] },
+    "implicitComponentOwnership": { "type": "boolean" },
+    "ownershipGroups": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["styleSources", "sources"],
+        "properties": {
+          "styleSources": {
+            "type": "array",
+            "minItems": 1,
+            "uniqueItems": true,
+            "items": { "$ref": "#/$defs/path" }
+          },
+          "sources": {
+            "type": "array",
+            "minItems": 1,
+            "uniqueItems": true,
+            "items": { "$ref": "#/$defs/path" }
+          }
+        },
+        "additionalProperties": false
+      }
+    },
+    "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" },
+    "failOn": { "enum": ["error", "review", "warning"] },
+    "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/eslint-diagnostics.d.mts

@@ -0,0 +1,24 @@
+export interface EslintDiagnosticLike {
+  ruleId?: string | null;
+  message: string;
+}
+
+export function isForeignRuleDefinitionDiagnostic(
+  item: EslintDiagnosticLike,
+): boolean;
+
+export interface ConsumerEslintConfigLike {
+  rules?: Record<string, unknown>;
+  linterOptions?: Record<string, unknown>;
+}
+
+export interface ProjectedConsumerCoreConfig {
+  files: string[];
+  rules?: Record<string, unknown>;
+  linterOptions?: Record<string, unknown>;
+}
+
+export function projectConsumerCoreConfig(
+  config: ConsumerEslintConfigLike | undefined,
+  file: string,
+): ProjectedConsumerCoreConfig | undefined;