@kerfjs/ui 5.0.0-beta.56 → 5.0.0-beta.58

package/analyzer/component-ownership.mjs

@@ -0,0 +1,184 @@
+/**
+ * Downstream component-ownership facts for `kerf-ui-analyze` (`KUI-L019` –
+ * `KUI-L022`): the consumer-side form of the package's own
+ * `check:css-ownership` rules.
+ *
+ * Components own their styles and are configured, never overridden. An
+ * application or component package may style its own elements, including in a
+ * cataloged component's context (`.kui-toolbar > .my-widget` lives in the
+ * application's stylesheet), but it never makes another package's component
+ * the subject of a rule, writes that component's private variables, overrides
+ * a token its typed prop configures, or restyles it through a hook class on
+ * its root. Every fact here comes from the loaded composition catalogs, so
+ * third-party component packages get the same protection as `@kerfjs/ui`.
+ */
+import {
+  classNames,
+  complexSelectorParts,
+  dataComponents,
+  subjectTypes,
+  withoutRelationalArguments,
+} from './selectors.mjs';
+
+const kebab = (value) =>
+  value.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`);
+
+function isWebAwesomeTagEntry(entry) {
+  return entry.source === 'webawesome' && /^wa-[a-z0-9-]+$/.test(entry.id);
+}
+
+/**
+ * Index the loaded catalog entries by every handle a stylesheet can use to
+ * reach them: public classes, `data-component` values, Web Awesome tags the
+ * package themes, private-variable prefixes, and component tokens a typed
+ * prop configures.
+ */
+export function componentOwnershipFacts(entries) {
+  const classOwners = new Map();
+  const dataComponentOwners = new Map();
+  const tagOwners = new Map();
+  const privatePrefixes = [];
+  const typedTokens = new Map();
+  const setOnce = (map, key, entry) => {
+    if (!map.has(key)) map.set(key, entry);
+  };
+  for (const entry of entries) {
+    const boundaries = entry.boundaries ?? {};
+    for (const className of boundaries.publicClasses ?? []) {
+      setOnce(classOwners, className, entry);
+      if (
+        className.startsWith('kui-') &&
+        !className.includes('__') &&
+        !className.includes('--')
+      )
+        setOnce(dataComponentOwners, className.slice('kui-'.length), entry);
+    }
+    if (entry.id && !isWebAwesomeTagEntry(entry))
+      setOnce(dataComponentOwners, entry.id, entry);
+    if (isWebAwesomeTagEntry(entry)) setOnce(tagOwners, entry.id, entry);
+    // Every root-like public class names the component (Toolbar Control
+    // Group's first class is its action link, not the group).
+    const roots = [
+      ...new Set(
+        [boundaries.rootClass, ...(boundaries.publicClasses ?? [])].filter(
+          (name) => name && !name.includes('__') && !name.includes('--'),
+        ),
+      ),
+    ];
+    const tokens = new Set(boundaries.publicTokens ?? []);
+    for (const root of roots) {
+      privatePrefixes.push({ prefix: `--_${root}`, entry });
+      for (const contract of entry.cssValueProps ?? []) {
+        const [head] = contract.path.split('[].');
+        const token = `--${root}-${kebab(head)}`;
+        if (tokens.has(token))
+          setOnce(typedTokens, token, { entry, path: contract.path });
+      }
+    }
+  }
+  privatePrefixes.sort((a, b) => b.prefix.length - a.prefix.length);
+  return {
+    classOwners,
+    dataComponentOwners,
+    tagOwners,
+    privatePrefixes,
+    typedTokens,
+  };
+}
+
+/**
+ * The cataloged components a selector list makes its subject: the rightmost
+ * compound of each complex selector, with `:has()` / `:not()` arguments
+ * removed because keying on or excluding a component does not style it. A
+ * subject that is a `::part()` is left to the shadow-part rule (`KUI-L011`).
+ * Returns `{ entry, via, name }` records; `isForeign(entry)` decides which
+ * entries the stylesheet does not own.
+ */
+export function restyledComponents(selectorList, facts, isForeign) {
+  const found = [];
+  const seen = new Set();
+  const add = (entry, via, name) => {
+    if (!entry || !isForeign(entry)) return;
+    const key = `${entry.key}|${via}|${name}`;
+    if (seen.has(key)) return;
+    seen.add(key);
+    found.push({ entry, via, name });
+  };
+  for (const parts of complexSelectorParts(selectorList)) {
+    const subject = parts.at(-1)?.compound;
+    if (!subject || /::part\(/i.test(subject)) continue;
+    const bare = withoutRelationalArguments(subject);
+    for (const className of classNames(bare))
+      add(facts.classOwners.get(className), 'class', `.${className}`);
+    for (const value of dataComponents(bare))
+      add(
+        facts.dataComponentOwners.get(value),
+        'data-component',
+        `[data-component="${value}"]`,
+      );
+    // An application class on the subject scopes a Web Awesome tag to the
+    // application's own element; a component package never places one there.
+    if (classNames(bare).some((name) => !facts.classOwners.has(name))) continue;
+    for (const type of subjectTypes(subject) ?? [])
+      add(facts.tagOwners.get(type), 'tag', type);
+  }
+  return found;
+}
+
+/** The catalog entry whose private `--_<root>-*` variable `property` is. */
+export function privateVariableOwner(property, facts) {
+  if (!property.startsWith('--_')) return undefined;
+  const owner = facts.privatePrefixes.find(
+    ({ prefix }) => property === prefix || property.startsWith(`${prefix}-`),
+  );
+  if (owner) return owner.entry;
+  return property.startsWith('--_kui-') ? null : undefined;
+}
+
+/** The typed prop that configures a component token, if one does. */
+export function typedPropForToken(token, facts) {
+  return facts.typedTokens.get(token);
+}
+
+/** Every configuration seam an entry publishes, as prose. */
+export function configurationFor(entry) {
+  if (!entry) return 'its documented props and variants';
+  if (isWebAwesomeTagEntry(entry))
+    return `<${entry.id}>'s documented attributes and ${entry.package}'s Web Awesome theme tokens`;
+  const props = (entry.cssValueProps ?? []).map(({ path }) => `\`${path}\``);
+  const rootClass = entry.boundaries?.rootClass;
+  const tokens = (entry.boundaries?.publicTokens ?? []).filter(
+    (token) => rootClass && token.startsWith(`--${rootClass}-`),
+  );
+  const seams = [
+    ...(props.length ? [`its props (${props.join(', ')})`] : []),
+    ...(tokens.length
+      ? [
+          `its public tokens (${tokens.map((item) => `\`${item}\``).join(', ')})`,
+        ]
+      : []),
+  ];
+  return seams.length
+    ? `${seams.join(' or ')}, or its documented variants`
+    : 'its documented props and variants';
+}
+
+/** The shared closing guidance: a missing seam is a component gap. */
+export function reportGap(entry) {
+  const owner = entry?.package ?? '@kerfjs/ui';
+  return `If no configuration covers this need, report the component gap to ${owner} (open a feature request) instead of overriding it.`;
+}
+
+/** A component's short name: its export, or its Web Awesome tag. */
+export function componentName(entry) {
+  if (!entry) return 'a Kerf component';
+  return isWebAwesomeTagEntry(entry) ? `<${entry.id}>` : entry.name;
+}
+
+/** A component's name with its catalog key. */
+export function componentLabel(entry) {
+  if (!entry) return 'a Kerf component';
+  return isWebAwesomeTagEntry(entry)
+    ? `<${entry.id}>`
+    : `${entry.name} (${entry.key})`;
+}

package/analyzer/index.d.mts

@@ -34,6 +34,9 @@ export const UI_ANALYSIS_RULES: Readonly<
   Record<`KUI-L${string}`, { severity: UiAnalysisSeverity; title: string }>
 >;
 
+/** The doctor's repair action for rules whose fix is more specific than the default. */
+export const UI_ANALYSIS_ACTIONS: Readonly<Record<`KUI-L${string}`, string>>;
+
 export function analyzeUiProject(options?: {
   root?: string;
   paths?: string[];

package/analyzer/index.mjs

@@ -14,7 +14,22 @@ import ts from 'typescript';
 
 import { loadApplicationUiProfile } from '../ai/application-ui-profile.mjs';
 import { isUiTraversalExcluded } from '../traversal-exclusions.mjs';
+import {
+  componentLabel,
+  componentName,
+  componentOwnershipFacts,
+  configurationFor,
+  privateVariableOwner,
+  reportGap,
+  restyledComponents,
+  typedPropForToken,
+} from './component-ownership.mjs';
 import { collectLoudDeclarations, inspectLoudPairs } from './loud-pairs.mjs';
+import {
+  classNames,
+  complexSelectorParts,
+  withoutRelationalArguments,
+} from './selectors.mjs';
 
 export const UI_ANALYSIS_SCHEMA_VERSION = 1;
 
@@ -23,7 +38,10 @@ export const UI_ANALYSIS_RULES = Object.freeze({
   'KUI-L002': { severity: 'error', title: 'Unknown Kerf token' },
   'KUI-L003': { severity: 'error', title: 'Competing geometry owners' },
   'KUI-L004': { severity: 'review', title: 'Repeated content inset' },
-  'KUI-L005': { severity: 'review', title: 'Forced component dimension' },
+  // KUI-L005 ('Forced component dimension') is retired: KUI-L019 reports any
+  // restyle of a cataloged component, dimensions included, and L005's only
+  // other shape (a public class as an ancestor) sizes an application element.
+  // The id stays in the diagnostic registry so existing exceptions still load.
   'KUI-L006': {
     severity: 'review',
     title: 'Hard-coded spacing outside the approved scale',
@@ -46,6 +64,34 @@ export const UI_ANALYSIS_RULES = Object.freeze({
     severity: 'review',
     title: 'Loud fill override without its on-loud pair',
   },
+  'KUI-L019': {
+    severity: 'error',
+    title: 'Application CSS restyles a cataloged component',
+  },
+  'KUI-L020': {
+    severity: 'error',
+    title: "Another component's private variable",
+  },
+  'KUI-L021': {
+    severity: 'error',
+    title: 'Component token overridden where a typed prop exists',
+  },
+  'KUI-L022': {
+    severity: 'error',
+    title: "Hook class restyles a cataloged component's root",
+  },
+});
+
+const ownershipAction =
+  "Configure the component through its typed props, variants, or public tokens; style only your own elements (in the component's context when needed). If no configuration covers the need, report the component gap to its package instead of overriding it.";
+
+/** The doctor's per-rule repair action, where it is more specific than the default. */
+export const UI_ANALYSIS_ACTIONS = Object.freeze({
+  'KUI-L019': ownershipAction,
+  'KUI-L020': ownershipAction,
+  'KUI-L021':
+    'Set the typed prop the diagnostic names on the component instead of overriding its token.',
+  'KUI-L022': ownershipAction,
 });
 
 const adoptionRules = new Set([
@@ -54,12 +100,14 @@ const adoptionRules = new Set([
   'KUI-L010',
   'KUI-L011',
   'KUI-L012',
+  'KUI-L019',
+  'KUI-L020',
+  'KUI-L021',
+  'KUI-L022',
 ]);
 
 const sourceExtensions = new Set(['.js', '.jsx', '.mjs', '.ts', '.tsx']);
 const spacingProperties = /^(?:margin|padding|gap|inset)(?:-|$)/;
-const dimensionProperties =
-  /^(?:width|height|min-width|max-width|min-height|max-height)$/;
 const approvedSpacing = new Set([0, 4, 8, 16, 24]);
 async function collectFiles(root, paths) {
   const files = [];
@@ -177,6 +225,7 @@ function reachableStyleFacts(file, imports, styleFacts) {
       const current = result.get(className) ?? { scroll: false, inset: false };
       current.scroll ||= facts.scroll;
       current.inset ||= facts.inset;
+      current.styled ??= facts.styled;
       result.set(className, current);
     }
   }
@@ -326,6 +375,7 @@ function catalogFacts(entries) {
     publicParts,
     classEntries,
     exportEntries,
+    ownership: componentOwnershipFacts(entries),
   };
 }
 
@@ -342,6 +392,121 @@ function escapeRegExp(value) {
   return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
 
+// A declaration that restyles, as opposed to one that only sets a custom
+// property: setting a component's public token on its host is configuration,
+// which the token rules (KUI-L002, KUI-L012, KUI-L020, KUI-L021) judge.
+function restylingDeclarations(rule) {
+  return (rule.nodes ?? []).filter(
+    (node) => node.type === 'decl' && !node.prop.startsWith('--'),
+  );
+}
+
+function inKeyframes(rule) {
+  return rule.parent?.type === 'atrule' && /keyframes$/i.test(rule.parent.name);
+}
+
+// The classes a rule makes its subject (the rightmost compound of each complex
+// selector, outside :has()/:not()).
+function subjectClasses(selector) {
+  return complexSelectorParts(selector).flatMap((parts) => {
+    const subject = parts.at(-1)?.compound;
+    return subject ? classNames(withoutRelationalArguments(subject)) : [];
+  });
+}
+
+function inspectComponentOwnership(
+  file,
+  rule,
+  facts,
+  diagnostics,
+  adoption,
+  isForeign,
+) {
+  if (inKeyframes(rule)) return;
+  const restyling = restylingDeclarations(rule);
+  if (restyling.length === 0) return;
+  const properties = [...new Set(restyling.map((decl) => decl.prop))];
+  for (const { entry, via, name } of restyledComponents(
+    rule.selector,
+    facts.ownership,
+    isForeign,
+  ))
+    diagnostics.push(
+      diagnostic(
+        'KUI-L019',
+        location(file, rule),
+        `\`${name}\` makes ${componentLabel(entry)} the subject of an application rule (${properties.join(', ')}); components own their styles. Configure it through ${configurationFor(entry)}. To place your own content in its context, style your own element (\`${name} > .your-element\`). ${reportGap(entry)}`,
+        {
+          selector: rule.selector,
+          component: entry.key,
+          via,
+          target: name,
+          properties,
+        },
+        undefined,
+        adoption,
+      ),
+    );
+}
+
+function inspectVariableOwnership(
+  file,
+  decl,
+  facts,
+  diagnostics,
+  adoption,
+  isForeign,
+) {
+  const at = location(file, decl);
+  const privates = new Set([
+    ...(decl.prop.match(/--_[a-z0-9_-]+/gi) ?? []),
+    ...(decl.value.match(/--_[a-z0-9_-]+/gi) ?? []),
+  ]);
+  for (const variable of privates) {
+    const owner = privateVariableOwner(variable, facts.ownership);
+    if (owner === undefined || (owner && !isForeign(owner))) continue;
+    const written = decl.prop === variable;
+    diagnostics.push(
+      diagnostic(
+        'KUI-L020',
+        at,
+        `\`${variable}\` is ${owner ? `${componentName(owner)}'s` : "a Kerf component's"} private variable; ${written ? 'writing it overrides' : 'reading it couples to'} that component's implementation. Configure it through ${configurationFor(owner)}. ${reportGap(owner)}`,
+        {
+          property: decl.prop,
+          value: decl.value,
+          variable,
+          ...(owner ? { component: owner.key } : {}),
+          access: written ? 'write' : 'read',
+        },
+        undefined,
+        adoption,
+      ),
+    );
+  }
+  if (!decl.prop.startsWith('--')) return;
+  const typed = typedPropForToken(decl.prop, facts.ownership);
+  if (!typed || !isForeign(typed.entry)) return;
+  const contract = (typed.entry.cssValueProps ?? []).find(
+    ({ path }) => path === typed.path,
+  );
+  const example = contract?.examples?.[0];
+  diagnostics.push(
+    diagnostic(
+      'KUI-L021',
+      at,
+      `\`${decl.prop}\` is what ${typed.entry.name}'s typed \`${typed.path}\` prop sets; set the prop on ${typed.entry.name}${example ? ` (\`<${typed.entry.name} ${example} />\`)` : ''} instead of overriding the token. ${reportGap(typed.entry)}`,
+      {
+        property: decl.prop,
+        value: decl.value,
+        component: typed.entry.key,
+        prop: typed.path,
+      },
+      undefined,
+      adoption,
+    ),
+  );
+}
+
 async function inspectCss(
   file,
   source,
@@ -350,6 +515,7 @@ async function inspectCss(
   cssFacts,
   adoption = false,
   siblingOnLoud = [],
+  isForeign = () => true,
 ) {
   let root;
   try {
@@ -374,6 +540,27 @@ async function inspectCss(
     siblingOnLoud,
   );
   root.walkRules((rule) => {
+    inspectComponentOwnership(
+      file,
+      rule,
+      facts,
+      diagnostics,
+      adoption,
+      isForeign,
+    );
+    if (!inKeyframes(rule) && restylingDeclarations(rule).length > 0)
+      for (const className of subjectClasses(rule.selector)) {
+        const record = cssFacts.get(className) ?? {
+          scroll: false,
+          inset: false,
+        };
+        record.styled ??= {
+          stylesheet: file,
+          line: rule.source?.start?.line ?? 1,
+          selector: rule.selector,
+        };
+        cssFacts.set(className, record);
+      }
     const classes = [
       ...rule.selector.matchAll(/\.([_a-zA-Z]+[_a-zA-Z0-9-]*)/g),
     ].map((match) => match[1]);
@@ -444,6 +631,14 @@ async function inspectCss(
         );
     }
     rule.walkDecls((decl) => {
+      inspectVariableOwnership(
+        file,
+        decl,
+        facts,
+        diagnostics,
+        adoption,
+        isForeign,
+      );
       const at = location(file, decl);
       const tokens = [
         ...(decl.prop.match(/--kui-[a-z0-9-]+/g) ?? []),
@@ -496,22 +691,6 @@ async function inspectCss(
         if (/^padding(?:-|$)/.test(decl.prop) && decl.value !== '0')
           record.inset = true;
         cssFacts.set(className, record);
-        if (
-          facts.publicClasses.has(className) &&
-          dimensionProperties.test(decl.prop)
-        )
-          diagnostics.push(
-            diagnostic(
-              'KUI-L005',
-              at,
-              `.${className} forces ${decl.prop}; prefer the component's public sizing contract.`,
-              {
-                selector: rule.selector,
-                property: decl.prop,
-                value: decl.value,
-              },
-            ),
-          );
       }
     });
   });
@@ -696,7 +875,15 @@ function inspectCssValues(
   }
 }
 
-function inspectTsx(file, sourceText, facts, cssFacts, diagnostics) {
+function inspectTsx(
+  file,
+  sourceText,
+  facts,
+  cssFacts,
+  diagnostics,
+  adoption = false,
+  isForeign = () => true,
+) {
   const source = ts.createSourceFile(
     file,
     sourceText,
@@ -769,6 +956,29 @@ function inspectTsx(file, sourceText, facts, cssFacts, diagnostics) {
           namespaces,
           diagnostics,
         );
+      if (entry && isForeign(entry))
+        for (const className of classes.values) {
+          if (facts.ownership.classOwners.has(className)) continue;
+          const styled = cssFacts.get(className)?.styled;
+          if (!styled) continue;
+          diagnostics.push(
+            diagnostic(
+              'KUI-L022',
+              at,
+              `\`${className}\` is placed on ${entry.name}'s root and styled by ${basename(styled.stylesheet)}:${styled.line} (\`${styled.selector}\`), which restyles ${componentLabel(entry)}; components own their styles. Configure it through ${configurationFor(entry)}, or wrap it in your own element and style that. ${reportGap(entry)}`,
+              {
+                tag,
+                component: entry.key,
+                className,
+                stylesheet: styled.stylesheet,
+                line: styled.line,
+                selector: styled.selector,
+              },
+              undefined,
+              adoption,
+            ),
+          );
+        }
       if (classes.dynamic)
         diagnostics.push(
           diagnostic(
@@ -932,6 +1142,39 @@ export async function analyzeUiProject({
   const imports = new Map(
     files.map((file) => [file, relativeStyleImports(file, contents.get(file))]),
   );
+  // A stylesheet or source file belongs to the package whose manifest is
+  // nearest it; entries of every other catalog package are foreign to it.
+  const packageNames = new Map();
+  const packageNameOf = async (directory) => {
+    if (!packageNames.has(directory))
+      packageNames.set(
+        directory,
+        (async () => {
+          try {
+            const manifest = JSON.parse(
+              await readFile(resolve(directory, 'package.json'), 'utf8'),
+            );
+            if (typeof manifest.name === 'string') return manifest.name;
+          } catch {
+            // No readable manifest here; keep walking up.
+          }
+          const parent = dirname(directory);
+          const inside = relative(root, parent);
+          if (
+            parent === directory ||
+            inside === '..' ||
+            inside.startsWith('../')
+          )
+            return undefined;
+          return packageNameOf(parent);
+        })(),
+      );
+    return packageNames.get(directory);
+  };
+  const foreignTo = async (file) => {
+    const own = await packageNameOf(dirname(file));
+    return (entry) => entry.package !== own;
+  };
   const styleFacts = new Map();
   const recordDiagnostics = (items, context) => {
     for (const item of items) {
@@ -1022,6 +1265,8 @@ export async function analyzeUiProject({
       context.facts,
       reachableStyleFacts(file, imports, styleFacts),
       fileDiagnostics,
+      adoption,
+      await foreignTo(file),
     );
     recordDiagnostics(fileDiagnostics, context);
   }
@@ -1039,6 +1284,7 @@ export async function analyzeUiProject({
         new Map(),
         adoption,
         siblingOnLoud(file),
+        await foreignTo(file),
       );
       recordDiagnostics(fileDiagnostics, context);
     }
@@ -1121,6 +1367,14 @@ export async function analyzeUiProject({
         ...item.location,
         file: portablePath(item.location.file),
       },
+      ...(item.evidence?.stylesheet
+        ? {
+            evidence: {
+              ...item.evidence,
+              stylesheet: portablePath(item.evidence.stylesheet),
+            },
+          }
+        : {}),
     })),
     summary: {
       errors:

package/analyzer/selectors.d.mts

@@ -0,0 +1,21 @@
+export interface SelectorCompound {
+  combinator: '' | ' ' | '>' | '+' | '~';
+  compound: string;
+}
+
+export function ownsClass(rootClass: string, candidate: string): boolean;
+export function complexSelectorParts(
+  selectorList: string,
+): SelectorCompound[][];
+export function complexSelectors(selectorList: string): string[][];
+export function kuiClasses(selector: string): string[];
+export function classNames(selector: string): string[];
+export function dataComponents(selector: string): string[];
+export function withoutPseudoArguments(
+  compound: string,
+  names: string[],
+): string;
+export function withoutRelationalArguments(compound: string): string;
+export function pseudoArguments(compound: string, name: string): string[];
+export function splitTopLevel(list: string): string[];
+export function subjectTypes(compound: string): string[] | null;