@kerfjs/ui 4.5.0-beta.1 → 5.0.0-beta.100

package/doctor/index.mjs

@@ -21,13 +21,19 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 import { createRequire } from 'node:module';
 
 import { loadApplicationUiProfile } from '../ai/application-ui-profile.mjs';
-import { analyzeUiProject, UI_ANALYSIS_RULES } from '../analyzer/index.mjs';
+import {
+  analyzeUiProject,
+  UI_ANALYSIS_ACTIONS,
+  UI_ANALYSIS_RULES,
+} from '../analyzer/index.mjs';
 import { evaluateUi, UI_EVALUATION_RULES } from '../evaluator/index.mjs';
-import { isForeignRuleDefinitionDiagnostic } from './eslint-diagnostics.mjs';
+import { checkComponentStyles } from './component-style-checks.mjs';
+import { checkCopyCapitalization } from './copy-capitalization-checks.mjs';
 import {
-  isUiTraversalExcluded,
-  UI_TRAVERSAL_ESLINT_IGNORES,
-} from '../traversal-exclusions.mjs';
+  isForeignRuleDefinitionDiagnostic,
+  projectConsumerCoreConfig,
+} from './eslint-diagnostics.mjs';
+import { createUiTraversalFilter } from '../traversal-exclusions.mjs';
 
 export const UI_DOCTOR_SCHEMA_VERSION = 1;
 export const UI_DOCTOR_EXIT = Object.freeze({
@@ -46,6 +52,22 @@ export const UI_DOCTOR_RULES = Object.freeze({
     severity: 'error',
     title: 'Local component catalog is stale or invalid',
   },
+  'KUI-D030': {
+    severity: 'error',
+    title: 'Component root class does not match its name',
+  },
+  'KUI-D031': {
+    severity: 'error',
+    title: 'Component stylesheet does not match its name',
+  },
+  'KUI-D032': {
+    severity: 'error',
+    title: 'Stylesheet selects another component class',
+  },
+  'KUI-D040': {
+    severity: 'warning',
+    title: 'Visible label is not title-style capitalized',
+  },
 });
 
 const sourceExtensions = new Set([
@@ -124,9 +146,14 @@ export function validateUiDoctorConfig(
     'schemaVersion',
     'mode',
     'package',
+    'ownership',
+    'ownershipContext',
+    'implicitComponentOwnership',
+    'ownershipGroups',
     'stages',
     'browser',
     'cache',
+    'failOn',
     'suppressions',
   ]);
   for (const key of Object.keys(config))
@@ -145,6 +172,61 @@ export function validateUiDoctorConfig(
       '$.package',
       'package must be a non-empty workspace package name or path.',
     );
+  if (
+    config.ownership !== undefined &&
+    !['package', 'component'].includes(config.ownership)
+  )
+    add('$.ownership', 'ownership must be package or component.');
+  if (
+    config.ownershipContext !== undefined &&
+    !['subject', 'any', 'any-package'].includes(config.ownershipContext)
+  )
+    add(
+      '$.ownershipContext',
+      'ownershipContext must be subject, any, or any-package.',
+    );
+  if (
+    config.implicitComponentOwnership !== undefined &&
+    typeof config.implicitComponentOwnership !== 'boolean'
+  )
+    add(
+      '$.implicitComponentOwnership',
+      'implicitComponentOwnership must be a boolean.',
+    );
+  if (config.ownershipGroups !== undefined) {
+    if (!Array.isArray(config.ownershipGroups))
+      add('$.ownershipGroups', 'ownershipGroups must be an array.');
+    else
+      config.ownershipGroups.forEach((group, index) => {
+        const path = `$.ownershipGroups[${index}]`;
+        if (!group || typeof group !== 'object' || Array.isArray(group)) {
+          add(path, 'Ownership group must be an object.');
+          return;
+        }
+        for (const key of Object.keys(group))
+          if (!['styleSources', 'sources'].includes(key))
+            add(`${path}.${key}`, 'Unknown ownership group property.');
+        for (const key of ['styleSources', 'sources']) {
+          const paths = group[key];
+          if (
+            !Array.isArray(paths) ||
+            !paths.length ||
+            paths.some(
+              (item) =>
+                typeof item !== 'string' ||
+                !item ||
+                item.startsWith('/') ||
+                /(^|\/)\.\.(\/|$)|[?*]/.test(item),
+            ) ||
+            new Set(paths).size !== paths.length
+          )
+            add(
+              `${path}.${key}`,
+              `${key} must be a non-empty array of unique, relative paths without traversal or globs.`,
+            );
+        }
+      });
+  }
   if (config.stages !== undefined) {
     if (
       !config.stages ||
@@ -217,6 +299,11 @@ export function validateUiDoctorConfig(
   }
   if (config.cache !== undefined && typeof config.cache !== 'boolean')
     add('$.cache', 'cache must be boolean.');
+  if (
+    config.failOn !== undefined &&
+    !['error', 'review', 'warning'].includes(config.failOn)
+  )
+    add('$.failOn', 'failOn must be error, review, or warning.');
   if (config.suppressions !== undefined) {
     if (!Array.isArray(config.suppressions))
       add('$.suppressions', 'suppressions must be an array.');
@@ -357,8 +444,9 @@ export async function resolveUiDoctorPackage(root, selector) {
 
 async function collectInputs(root, paths) {
   const result = [];
+  const excluded = await createUiTraversalFilter(root);
   const visit = async (path) => {
-    if (isUiTraversalExcluded(root, path)) return;
+    if (excluded(path)) return;
     let details;
     try {
       details = await stat(path);
@@ -408,7 +496,7 @@ async function installedPackageVersion(root, name) {
 }
 
 async function cacheKey(root, packageRoot, mode, paths, config) {
-  const files = await collectInputs(packageRoot, paths);
+  const files = await collectInputs(packageRoot);
   for (const directory of new Set([root, packageRoot])) {
     for (const name of [
       'package.json',
@@ -418,6 +506,7 @@ async function cacheKey(root, packageRoot, mode, paths, config) {
       'tsconfig.json',
       '.kerf-ui-profile.json',
       '.kerf-ui-doctor.json',
+      '.gitignore',
     ]) {
       const path = resolve(directory, name);
       if (!files.includes(path) && (await exists(path))) files.push(path);
@@ -449,6 +538,13 @@ async function cacheKey(root, packageRoot, mode, paths, config) {
       }),
     )
     .update(await readFile(fileURLToPath(import.meta.url)));
+  for (const module of [
+    'component-style-checks.mjs',
+    'copy-capitalization-checks.mjs',
+  ])
+    hash.update(
+      await readFile(resolve(dirname(fileURLToPath(import.meta.url)), module)),
+    );
   for (const file of files)
     hash.update(portablePath(root, file)).update(await readFile(file));
   return hash.digest('hex');
@@ -544,6 +640,7 @@ function normalizeAnalyzer(report) {
         evidence: item.evidence,
         catalogFacts: item.chain,
         action:
+          UI_ANALYSIS_ACTIONS[item.ruleId] ??
           'Apply the catalog-declared composition or geometry boundary at this source location.',
         meaning: UI_ANALYSIS_RULES[item.ruleId]?.title ?? item.ruleId,
       }),
@@ -774,13 +871,15 @@ async function runTypeScript({ packageRoot, paths }) {
     { ...ts.default.sys, onUnRecoverableConfigFileDiagnostic: () => {} },
   );
   if (!parsed) throw new Error('TypeScript could not parse tsconfig.json.');
-  parsed.fileNames = parsed.fileNames.filter(
-    (file) => !isUiTraversalExcluded(packageRoot, file),
-  );
-  if (paths?.length) {
-    const selected = new Set(paths.map((path) => resolve(packageRoot, path)));
-    parsed.fileNames = parsed.fileNames.filter((file) => selected.has(file));
-  }
+  const selected = paths?.length
+    ? new Set(paths.map((path) => resolve(packageRoot, path)))
+    : undefined;
+  const excluded = await createUiTraversalFilter(packageRoot);
+  parsed.fileNames = parsed.fileNames.filter((file) => {
+    if (excluded(file)) return false;
+    if (!selected || selected.has(file)) return true;
+    return /\.d\.(?:ts|mts|cts)$/.test(file);
+  });
   const program = ts.default.createProgram(
     parsed.fileNames,
     { ...parsed.options, noEmit: true },
@@ -791,33 +890,50 @@ async function runTypeScript({ packageRoot, paths }) {
   const diagnostics = [
     ...parsed.errors,
     ...ts.default.getPreEmitDiagnostics(program),
-  ].map((item) => {
-    const point =
-      item.file && item.start !== undefined
-        ? item.file.getLineAndCharacterOfPosition(item.start)
-        : undefined;
-    return normalizedDiagnostic({
-      id: `TS${item.code}`,
-      severity:
-        item.category === ts.default.DiagnosticCategory.Error
-          ? 'error'
-          : 'warning',
-      stage: 'typescript',
-      message: ts.default.flattenDiagnosticMessageText(item.messageText, '\n'),
-      location: item.file
-        ? {
-            file: portablePath(packageRoot, item.file.fileName),
-            line: (point?.line ?? 0) + 1,
-            column: (point?.character ?? 0) + 1,
-          }
-        : undefined,
-      action: 'Repair the TypeScript diagnostic at this source location.',
-      meaning: `TypeScript diagnostic TS${item.code}`,
+  ]
+    .filter(
+      (item) =>
+        !selected || !item.file || selected.has(resolve(item.file.fileName)),
+    )
+    .map((item) => {
+      const point =
+        item.file && item.start !== undefined
+          ? item.file.getLineAndCharacterOfPosition(item.start)
+          : undefined;
+      return normalizedDiagnostic({
+        id: `TS${item.code}`,
+        severity:
+          item.category === ts.default.DiagnosticCategory.Error
+            ? 'error'
+            : 'warning',
+        stage: 'typescript',
+        message: ts.default.flattenDiagnosticMessageText(
+          item.messageText,
+          '\n',
+        ),
+        location: item.file
+          ? {
+              file: portablePath(packageRoot, item.file.fileName),
+              line: (point?.line ?? 0) + 1,
+              column: (point?.character ?? 0) + 1,
+            }
+          : undefined,
+        action: 'Repair the TypeScript diagnostic at this source location.',
+        meaning: `TypeScript diagnostic TS${item.code}`,
+      });
     });
-  });
   return { diagnostics };
 }
 
+// ESLint has two severities; the analyzer has a third, `review`. The presets
+// configure every rule whose KUI code the analyzer classifies as `review`
+// (`KUI-L017`) as `warn`, so a warning for such a code is that review finding
+// and merges with the analyzer's report instead of conflicting with it.
+function eslintSeverity(severity, code) {
+  if (severity === 2) return 'error';
+  return UI_ANALYSIS_RULES[code]?.severity === 'review' ? 'review' : 'warning';
+}
+
 async function runEslint({
   packageRoot,
   paths,
@@ -850,7 +966,10 @@ async function runEslint({
       },
     },
   };
-  const configs = [{ ignores: UI_TRAVERSAL_ESLINT_IGNORES }, base];
+  const configs = [
+    { ignores: (await createUiTraversalFilter(packageRoot)).eslintIgnores },
+    base,
+  ];
   if (usesTypeScript) {
     const parserModule = await importFrom(
       packageRoot,
@@ -869,6 +988,18 @@ async function runEslint({
     });
   }
   configs.push(preset);
+  const consumerEslint = new ESLint({ cwd: packageRoot });
+  if (await consumerEslint.findConfigFile()) {
+    const consumerCoreConfigs = await Promise.all(
+      inputs.map(async (file) =>
+        projectConsumerCoreConfig(
+          await consumerEslint.calculateConfigForFile(file),
+          portablePath(packageRoot, file),
+        ),
+      ),
+    );
+    configs.push(...consumerCoreConfigs.filter(Boolean));
+  }
   const eslint = new ESLint({
     cwd: packageRoot,
     overrideConfigFile: true,
@@ -884,7 +1015,7 @@ async function runEslint({
       diagnostics.push(
         normalizedDiagnostic({
           id: code ?? `eslint:${item.ruleId ?? 'parse-error'}`,
-          severity: item.severity === 2 ? 'error' : 'warning',
+          severity: eslintSeverity(item.severity, code),
           stage: 'eslint',
           message: item.message.replace(/^KUI-[A-Z]\d{3}:\s*/, ''),
           location: {
@@ -955,6 +1086,7 @@ export async function runUiDoctor({
   config: suppliedConfig,
   configPath,
   cache,
+  failOn,
   signal,
   browser,
   runners = {},
@@ -988,6 +1120,14 @@ export async function runUiDoctor({
     );
   }
   const selectedMode = mode ?? config.mode ?? 'full';
+  const selectedFailOn = failOn ?? config.failOn ?? 'error';
+  if (failOn !== undefined && !['error', 'review', 'warning'].includes(failOn))
+    initialDiagnostics.push(
+      configDiagnostic('failOn must be error, review, or warning.', {
+        file: '<options>',
+        path: '$.failOn',
+      }),
+    );
   const stages = { ...defaultStages, ...config.stages };
   if (browser?.url || config.browser?.url) stages.browser = true;
   const selectedPaths =
@@ -1015,6 +1155,7 @@ export async function runUiDoctor({
   const cachePath = resolve(root, '.kerf-cache/ui-doctor-v1.json');
   const key = await cacheKey(root, packageRoot, selectedMode, selectedPaths, {
     ...config,
+    failOn: selectedFailOn,
     browser: config.browser
       ? { ...config.browser, url: '<redacted-url>' }
       : undefined,
@@ -1103,16 +1244,40 @@ export async function runUiDoctor({
                 root,
                 packageRoot,
                 paths: selectedPaths,
+                ownership: config.ownership ?? 'package',
+                ownershipContext: config.ownershipContext ?? 'subject',
+                implicitComponentOwnership:
+                  config.implicitComponentOwnership ?? false,
+                ownershipGroups: config.ownershipGroups ?? [],
                 signal,
               })
             : (async () => ({
-                diagnostics: normalizeAnalyzer(
-                  await analyzeUiProject({
-                    root: packageRoot,
-                    paths: selectedPaths,
-                    knownRules: [...registeredRuleIds, ...eslintRuleIds],
-                  }),
-                ),
+                diagnostics: [
+                  ...normalizeAnalyzer(
+                    await analyzeUiProject({
+                      root: packageRoot,
+                      paths: selectedPaths,
+                      ownership: config.ownership ?? 'package',
+                      ownershipContext: config.ownershipContext ?? 'subject',
+                      implicitComponentOwnership:
+                        config.implicitComponentOwnership ?? false,
+                      ownershipGroups: config.ownershipGroups ?? [],
+                      knownRules: [...registeredRuleIds, ...eslintRuleIds],
+                    }),
+                  ),
+                  ...(await checkComponentStyles(
+                    packageRoot,
+                    await collectInputs(packageRoot),
+                    config.ownershipGroups ?? [],
+                    selectedPaths,
+                    root,
+                  )),
+                  ...(await checkCopyCapitalization(
+                    packageRoot,
+                    await collectInputs(packageRoot),
+                    selectedPaths,
+                  )),
+                ],
               }))(),
         signal,
       ),
@@ -1208,7 +1373,9 @@ export async function runUiDoctor({
     ? UI_DOCTOR_EXIT.cancelled
     : infrastructureFailure
       ? UI_DOCTOR_EXIT.configuration
-      : summary.errors
+      : summary.errors ||
+          (selectedFailOn !== 'error' && summary.review) ||
+          (selectedFailOn === 'warning' && summary.warnings)
         ? UI_DOCTOR_EXIT.findings
         : UI_DOCTOR_EXIT.clean;
   const report = redact(root, {

package/evaluator/index.mjs

@@ -336,6 +336,50 @@ async function inspectPage(page, geometryContracts) {
       return null;
     };
 
+    const hitExtent = (element, rect) => {
+      const root = element.getRootNode();
+      const probe = root.elementFromPoint ? root : document;
+      const inViewport = (x, y) =>
+        x >= 0 && y >= 0 && x < innerWidth && y < innerHeight;
+      const owns = (x, y) => {
+        const hit = probe.elementFromPoint(x, y);
+        return !!hit && (hit === element || element.contains(hit));
+      };
+      const x = rect.left + rect.width / 2;
+      const y = rect.top + rect.height / 2;
+      if (!inViewport(x, y) || !owns(x, y)) return null;
+      // Walk out in 1px steps (no further than the 44px goal needs), then
+      // refine the last step in quarter pixels; the reach is the last owned
+      // sample, so it never overstates the target. A walk stopped by
+      // the viewport edge cannot see the rest of the layer, so it is marked
+      // and mirrored from the opposite side (hit layers are symmetric insets).
+      const reach = (dx, dy) => {
+        const at = (distance) => [x + dx * distance, y + dy * distance];
+        let owned = 0;
+        while (owned < 24) {
+          const point = at(owned + 1);
+          if (!inViewport(...point)) return { distance: owned, clipped: true };
+          if (!owns(...point)) break;
+          owned += 1;
+        }
+        if (owned >= 24) return { distance: owned, clipped: false };
+        while (owns(...at(owned + 0.25))) owned += 0.25;
+        return { distance: owned, clipped: false };
+      };
+      const span = (first, second) =>
+        first.clipped && second.clipped
+          ? first.distance + second.distance
+          : first.clipped
+            ? 2 * second.distance
+            : second.clipped
+              ? 2 * first.distance
+              : first.distance + second.distance;
+      return {
+        width: span(reach(-1, 0), reach(1, 0)),
+        height: span(reach(0, -1), reach(0, 1)),
+      };
+    };
+
     for (const element of interactives) {
       const target = selector(element);
       const rect = element.getBoundingClientRect();
@@ -495,14 +539,35 @@ async function inspectPage(page, geometryContracts) {
           'button,input:not([type="hidden"]),select,textarea,[role]',
         ) &&
         (rect.width < 43.5 || rect.height < 43.5)
-      )
-        diagnostics.push({
-          code: 'KUI-B050',
-          selector: target,
-          message: `Hit target is ${rect.width.toFixed(1)}×${rect.height.toFixed(1)}px; expected at least 44×44px.`,
-          repair: repair.target,
-          evidence: { width: rect.width, height: rect.height },
-        });
+      ) {
+        // The border box understates a control whose pointer target is
+        // extended by a transparent hit layer (a positioned ::before/::after
+        // that receives pointer events). Hit-test outward from the center to
+        // measure the area the pointer can actually reach; a probe that finds
+        // no hit (off-screen, covered center) keeps the border box.
+        const hit = hitExtent(element, rect);
+        const width = Math.max(rect.width, hit?.width ?? 0);
+        const height = Math.max(rect.height, hit?.height ?? 0);
+        // Compact density is a deliberate trade-off: its rows are 36px tall,
+        // and a taller hit layer would reach into the neighboring row. Inside
+        // `[data-density="compact"]` a target still needs the full 44px width
+        // but only the 36px compact row height.
+        const compact = element.closest('[data-density="compact"]') !== null;
+        const requiredHeight = compact ? 36 : 44;
+        if (width < 43.5 || height < requiredHeight - 0.5)
+          diagnostics.push({
+            code: 'KUI-B050',
+            selector: target,
+            message: `Hit target is ${width.toFixed(1)}×${height.toFixed(1)}px; expected at least 44×${requiredHeight}px${compact ? ' (compact density)' : ''}.`,
+            repair: repair.target,
+            evidence: {
+              width,
+              height,
+              box: { width: rect.width, height: rect.height },
+              required: { width: 44, height: requiredHeight },
+            },
+          });
+      }
     }
 
     const parse = (value) => {