@ksmv/ui-checks 0.2.0 → 0.3.1

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.3.1 - 2026-09-30
+
+- **O CLI volta a rodar quando é chamado por um link simbólico.** Na 0.3.0 e anteriores, pelo `npx`, por um script npm ou pelo `node_modules/.bin` no Linux e no macOS, e em qualquer sistema quando `node_modules` é um link ou uma junção, o comando não executava nada e saía com código `0`: uma verificação verde que não tinha acontecido. A detecção do ponto de entrada passa a comparar os caminhos reais. **Quem roda o verificador num CI Linux deve atualizar e conferir que o passo de fato imprime o relatório.**
+- **Um `#` que não inicia um nome deixa de travar a análise.** Um arquivo TypeScript ou TSX com `#` dentro de uma expressão regular literal, como `/^#\/rota/`, fazia a varredura nunca terminar, até o processo esgotar a memória. A varredura agora sempre avança. Um `#` solto que não compila continua sendo erro operacional de parse (saída 2).
+
+## 0.3.0 - 2026-09-30
+
+- **Regra `components/override`**, opt-in pelo bloco `components` da configuração. Num componente da biblioteca, ajuste de encaixe por `className` ou `style` (margem, largura, item de flex/grid, posição, visibilidade, alinhamento do texto) é livre; ajuste de aparência ou de arranjo interno exige `data-ui-override="motivo"` no mesmo elemento. Classes fora do catálogo contam como aparência. `className` ou `style` que o checker não consegue ler e props repassadas depois de `className`/`style` também exigem a marca.
+- Os achados são violações comuns (saída 1) e podem entrar em baseline durante a migração; os elementos marcados aparecem na lista nova `overrides` do relatório, com o motivo.
+- O bloco `components` tem arquivos próprios (`include`, `exclude`), fontes (`sources`, padrão `@ksmv/ui-react`) e helpers de classe (`classHelpers`, que somam aos padrões). Arquivos só desse bloco recebem só esta regra: nem a cobertura dinâmica nem as regras de cor passam a valer neles.
+- Furos conhecidos, documentados: componente do produto que repassa props para um componente da biblioteca, CSS do produto que mira as classes internas `.ui-*`, props repassadas sozinhas ou antes de `className`/`style`, componente usado como valor e arquivo que não compila (erro operacional de parse, fora do alcance da regra). Um `components.include` que não casa nenhum arquivo é erro operacional (saída 2).
+
 ## 0.2.0 - 2026-09-29
 
 - **Contrato de tema 2.0.0** empacotado, com os 20 tokens de densidade obrigatórios e os 3 derivados. Pontes da 0.1.x ficam incompletas em `tokens/complete`, e evidência capturada antes da mudança deixa de conferir com a identidade do contrato.

package/README.md

@@ -147,6 +147,35 @@ await writeFile(target, `${JSON.stringify({
 
 Capture de novo sempre que um arquivo de tema mudar ou o pacote React for atualizado; a verificação recusa a evidência antiga, que é exatamente o objetivo.
 
+## Ajustes em componentes
+
+A regra `components/override` confere como o produto ajusta os componentes da biblioteca. Ela só roda quando a configuração tem o bloco `components`:
+
+```js
+components: {
+  include: ["src/**/*.tsx"],
+  exclude: ["src/**/*.test.tsx"],
+  sources: ["@ksmv/ui-react", "@/ui"],
+  classHelpers: ["tw"],
+}
+```
+
+- **Livre:** o que encaixa o componente no pai — margem, largura, item de flex/grid (`flex-1`, `self-*`, `col-span-*`…), posição, `z-*`, visibilidade (`hidden`, `sr-only`) e alinhamento do texto. No `style`, as propriedades equivalentes.
+- **Exige `data-ui-override="motivo"` no mesmo elemento:** aparência (cor, fundo, borda, raio, sombra, fonte, altura, padding, `gap-*`, `overflow-*`), arranjo interno (`flex`, `grid-cols-*`, `justify-*`, `items-*`, `block`) e qualquer classe fora do catálogo, inclusive classes próprias do produto. Também exigem a marca `className` ou `style` que a regra não consegue ler e props repassadas depois de `className` ou `style`.
+- **Relatório:** sem marca, é uma violação (saída 1), que pode entrar em baseline durante a migração. Com marca, o elemento aparece em `overrides`, com o motivo.
+- **Arquivos:** os do `components.include` recebem só esta regra. Um arquivo que também está no `include` principal recebe as duas coisas, e aí a cobertura dinâmica volta a valer nele.
+- **O que a regra não vê:** um componente do produto que repassa props para um componente da biblioteca, e CSS do produto que mira as classes internas `.ui-*`; props repassadas sozinhas ou antes de `className`/`style` (`<Button {...props} />`); componente usado como valor (`const X = Button; <X />`); arquivos que não compilam — aparecem como erro operacional de parse (saída 2) e não são analisados pela regra.
+
+### Detalhes
+
+- `sources` substitui o padrão: mantenha `@ksmv/ui-react` na lista ao acrescentar um barril; a comparação é pelo especificador exato do import (subcaminhos e imports relativos precisam de entrada própria).
+- `classHelpers` soma aos padrões (`cn`, `clsx`, `cx`, `classnames`, `classNames`, `twMerge`, `twJoin`, `cva`) e entende chamadas no estilo clsx; de `cva(...)` só os textos literais são lidos. Template marcado (`tw\`...\``) e funções de variante geradas por `cva` contam como ilegíveis.
+- `undefined`, `null`, `true`, `false` e `0` dentro de uma expressão de classe não contribuem classe.
+- `overrides[]` tem `path`, `line`, `column`, `component`, `reason` e `classes`; `classes` lista as classes visuais autorizadas, as propriedades de `style` como `style:<propriedade>` e os tipos de achado (`dynamic-class`, `dynamic-style`, `spread-after`).
+- componente do produto com `forwardRef` que faz `<Button className={cn("mt-2", className)} {...props} />`: gera `dynamic-class` e `spread-after`; passe o spread antes do `className` e marque o elemento com o motivo ("repassa className do chamador"), ou use a baseline durante a migração.
+- o padrão responsivo `hidden md:inline-flex` exige marca (`inline-flex` é arranjo interno).
+- um `components.include` que não casa nenhum arquivo é erro operacional (saída 2).
+
 ## API programática
 
 O ponto de entrada `@ksmv/ui-checks` exporta `runChecks`, as regras, `resolveContractSet`, `computeThemeSourceHash`, `loadComputedEvidence`, as funções de baseline e os formatadores de relatório, com os tipos TypeScript correspondentes. Os contratos embutidos estão em `@ksmv/ui-checks/theme-contract.json` e `@ksmv/ui-checks/contrast-contract.json`.

package/dist/cli.d.ts

@@ -1,2 +1,9 @@
 #!/usr/bin/env node
 export declare function main(argv?: string[]): Promise<import("./result.js").ExitCode>;
+/**
+ * Whether this module is the script Node was started with. Compared by real
+ * path: through a symbolic link (npm's `.bin` on POSIX, a linked node_modules)
+ * `process.argv[1]` names the link while `import.meta.url` names the file, and
+ * comparing them as written made the CLI do nothing and exit 0.
+ */
+export declare function isEntryPoint(scriptPath: string | undefined, moduleUrl: string): boolean;

package/dist/cli.js

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
+import { realpathSync } from "node:fs";
 import { readFile } from "node:fs/promises";
 import { resolve } from "node:path";
-import { pathToFileURL } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
 import { approveBaselineGrowth, baselineFor, validateBaseline, writeBaselineFile, } from "./baseline.js";
 import { applyConfiguredSuppressions } from "./governance.js";
 import { formatHumanReport, formatJsonReport, } from "./result.js";
@@ -169,9 +170,23 @@ export async function main(argv = process.argv.slice(2)) {
         return 2;
     }
 }
-const entryPoint = process.argv[1]
-    ? pathToFileURL(resolve(process.argv[1])).href
-    : undefined;
-if (entryPoint === import.meta.url) {
+/**
+ * Whether this module is the script Node was started with. Compared by real
+ * path: through a symbolic link (npm's `.bin` on POSIX, a linked node_modules)
+ * `process.argv[1]` names the link while `import.meta.url` names the file, and
+ * comparing them as written made the CLI do nothing and exit 0.
+ */
+export function isEntryPoint(scriptPath, moduleUrl) {
+    if (!scriptPath)
+        return false;
+    try {
+        return (realpathSync.native(resolve(scriptPath)) ===
+            realpathSync.native(fileURLToPath(moduleUrl)));
+    }
+    catch {
+        return false;
+    }
+}
+if (isEntryPoint(process.argv[1], import.meta.url)) {
     process.exitCode = await main();
 }

package/dist/config.d.ts

@@ -10,8 +10,15 @@ export interface ThemeConfig {
     name: string;
     selector: string;
 }
+export interface ComponentsConfig {
+    classHelpers?: string[];
+    exclude?: string[];
+    include: string[];
+    sources?: string[];
+}
 export interface ChecksConfig {
     baseline?: string;
+    components?: ComponentsConfig;
     contractSource?: ContractSource;
     exclude?: string[];
     failOnUncovered?: boolean;

package/dist/index.d.ts

@@ -1,11 +1,11 @@
 export { defineConfig } from "./config.js";
-export type { ChecksConfig, ComputedEvidenceRef, ThemeConfig } from "./config.js";
+export type { ChecksConfig, ComponentsConfig, ComputedEvidenceRef, ThemeConfig, } from "./config.js";
 export { parseContrastManifest, parseThemeContract, resolveContractSet, tokenNamePattern, } from "./contracts.js";
 export type { ContractIdentity, ContractSet, ContractSource, ContrastManifest, ContrastPair, ThemeContract, } from "./contracts.js";
 export { computeThemeSourceHash, loadComputedEvidence } from "./evidence.js";
 export type { ThemeEvidence } from "./evidence.js";
 export { formatHumanReport, formatJsonReport } from "./result.js";
-export type { BaselineDebt, CheckReport, ExitCode, IgnoredFile, OperationalError, SourceLocation, Suppression, Uncovered, Violation, } from "./result.js";
+export type { BaselineDebt, CheckReport, ComponentOverride, ExitCode, IgnoredFile, OperationalError, SourceLocation, Suppression, Uncovered, Violation, } from "./result.js";
 export { approveBaselineGrowth, baselineFor, compareBaseline, fingerprintViolation, normalizeRelativePath, serializeBaseline, validateBaseline, writeBaselineFile, } from "./baseline.js";
 export type { BaselineComparison, BaselineEntry, BaselineFile, BaselineMetadata, BaselineValidation, GrowthApproval, GrowthApprovalOptions, } from "./baseline.js";
 export { validateSuppressions } from "./suppressions.js";
@@ -17,6 +17,8 @@ export type { NoLiteralColorOptions } from "./rules/noLiteralColor.js";
 export { createDefaultRules } from "./rules/default.js";
 export type { DefaultRulesOptions } from "./rules/default.js";
 export { createTokenPrefixRule } from "./rules/tokenPrefix.js";
+export { createComponentOverrideRule } from "./rules/componentOverride.js";
+export type { ComponentOverrideOptions } from "./rules/componentOverride.js";
 export { createTokenCompleteRule, loadThemeContract, } from "./rules/tokenComplete.js";
 export type { TokenCompleteOptions, } from "./rules/tokenComplete.js";
 export { createTokenContrastRule, loadContrastManifest, } from "./rules/tokenContrast.js";

package/dist/index.js

@@ -8,5 +8,6 @@ export { runChecks } from "./scan.js";
 export { createNoLiteralColorRule } from "./rules/noLiteralColor.js";
 export { createDefaultRules } from "./rules/default.js";
 export { createTokenPrefixRule } from "./rules/tokenPrefix.js";
+export { createComponentOverrideRule } from "./rules/componentOverride.js";
 export { createTokenCompleteRule, loadThemeContract, } from "./rules/tokenComplete.js";
 export { createTokenContrastRule, loadContrastManifest, } from "./rules/tokenContrast.js";

package/dist/result.d.ts

@@ -24,6 +24,12 @@ export interface Uncovered extends SourceLocation {
     rule: string;
     required?: boolean;
 }
+export interface ComponentOverride extends SourceLocation {
+    classes: string[];
+    component: string;
+    path: string;
+    reason: string;
+}
 export interface Suppression {
     expires: string;
     fingerprint: string;
@@ -62,6 +68,7 @@ export interface CheckReport {
     filesRead: number;
     nodesChecked: number;
     operationalErrors: OperationalError[];
+    overrides: ComponentOverride[];
     rulesExecuted: string[];
     schemaVersion: 1;
     suppressions: Suppression[];

package/dist/result.js

@@ -15,6 +15,7 @@ export function formatHumanReport(report) {
         `Baseline matches: ${report.baselineMatches.length}`,
         `Uncovered: ${report.uncovered.length}`,
         `Suppressions: ${report.suppressions.length}`,
+        `Overrides: ${report.overrides.length}`,
         `Operational errors: ${report.operationalErrors.length}`,
     ];
     for (const debt of report.baselineDebt) {
@@ -32,6 +33,9 @@ export function formatHumanReport(report) {
     for (const suppression of report.suppressions) {
         lines.push(`Suppression: ${suppression.path} ${suppression.rule} expires ${suppression.expires}`);
     }
+    for (const override of report.overrides) {
+        lines.push(`Override: ${override.path}:${override.line}:${override.column} ${override.component} "${override.reason}" ${override.classes.join(" ")}`.trimEnd());
+    }
     for (const finding of [...report.violations, ...report.uncovered]) {
         lines.push(`${finding.path}:${finding.line}:${finding.column} ${finding.rule} ${finding.message}`);
     }

package/dist/rules/componentOverride.d.ts

@@ -0,0 +1,6 @@
+import type { CheckRule } from "../scan.js";
+export interface ComponentOverrideOptions {
+    classHelpers?: string[];
+    sources?: string[];
+}
+export declare function createComponentOverrideRule({ classHelpers, sources, }?: ComponentOverrideOptions): CheckRule;

package/dist/rules/componentOverride.js

@@ -0,0 +1,354 @@
+import { isArrayLiteralExpression, isAsExpression, isBinaryExpression, isCallExpression, isComputedPropertyName, isConditionalExpression, isFalseLiteral, isIdentifier, isImportDeclaration, isJsxAttribute, isJsxExpression, isJsxOpeningElement, isJsxSelfClosingElement, isJsxSpreadAttribute, isNamedImports, isNamespaceImport, isNonNullExpression, isNullLiteral, isNumericLiteral, isObjectLiteralExpression, isParenthesizedExpression, isPropertyAccessExpression, isPropertyAssignment, isSatisfiesExpression, isShorthandPropertyAssignment, isStringLiteral, isStringLiteralLikeNode, isTrueLiteral, SyntaxKind, } from "typescript/unstable/ast";
+import { classifyClass, classifyStyleProperty } from "./overrideCatalog.js";
+const defaultHelpers = ["cn", "clsx", "cx", "cva", "twMerge", "twJoin", "classnames", "classNames"];
+const kindMessages = {
+    "dynamic-class": "a class expression the checker cannot read",
+    "dynamic-style": "a style the checker cannot read",
+    "spread-after": "props spread after className or style",
+};
+function collectImports(sourceFile, sources) {
+    const bindings = new Map();
+    for (const statement of sourceFile.statements) {
+        if (!isImportDeclaration(statement) || !isStringLiteral(statement.moduleSpecifier))
+            continue;
+        if (!sources.has(statement.moduleSpecifier.text))
+            continue;
+        const clause = statement.importClause;
+        if (!clause || clause.phaseModifier === SyntaxKind.TypeKeyword)
+            continue;
+        const named = clause.namedBindings;
+        if (named && isNamespaceImport(named))
+            bindings.set(named.name.text, { namespace: true });
+        if (named && isNamedImports(named)) {
+            for (const element of named.elements) {
+                if (element.isTypeOnly)
+                    continue;
+                bindings.set(element.name.text, {
+                    imported: (element.propertyName ?? element.name).text,
+                    namespace: false,
+                });
+            }
+        }
+    }
+    return bindings;
+}
+function bindingNames(name, into) {
+    if (!name)
+        return;
+    if (isIdentifier(name)) {
+        into.add(name.text);
+        return;
+    }
+    name.forEachChild((child) => {
+        if (child.kind === SyntaxKind.BindingElement) {
+            bindingNames(child.name, into);
+        }
+    });
+}
+/** Names declared directly in a scope-creating node (parameters or block statements). */
+function scopeNames(node) {
+    const record = node;
+    const isBlock = node.kind === SyntaxKind.Block;
+    if (!record.parameters && !isBlock)
+        return undefined;
+    const names = new Set();
+    for (const parameter of record.parameters ?? []) {
+        bindingNames(parameter.name, names);
+    }
+    if (isBlock) {
+        for (const statement of record.statements ?? []) {
+            if (statement.kind === SyntaxKind.VariableStatement) {
+                const list = statement.declarationList;
+                for (const declaration of list.declarations) {
+                    bindingNames(declaration.name, names);
+                }
+            }
+            if (statement.kind === SyntaxKind.FunctionDeclaration || statement.kind === SyntaxKind.ClassDeclaration) {
+                bindingNames(statement.name, names);
+            }
+        }
+    }
+    return names;
+}
+function tagParts(tagName) {
+    const path = [];
+    let current = tagName;
+    while (isPropertyAccessExpression(current)) {
+        path.unshift(current.name.text);
+        current = current.expression;
+    }
+    return isIdentifier(current) ? { path, root: current.text } : undefined;
+}
+function propertyKey(node) {
+    if (isIdentifier(node) || isStringLiteralLikeNode(node))
+        return node.text;
+    return isComputedPropertyName(node) && isStringLiteralLikeNode(node.expression)
+        ? node.expression.text
+        : undefined;
+}
+/** Unwraps type assertions, `satisfies` and `!` before reading an expression. */
+function unwrapTypeWrappers(node) {
+    let current = node;
+    while (isParenthesizedExpression(current) ||
+        isAsExpression(current) ||
+        isSatisfiesExpression(current) ||
+        isNonNullExpression(current)) {
+        current = current.expression;
+    }
+    return current;
+}
+/** `undefined`, `null`, `true`, `false` and `0` contribute no classes and are not unreadable. */
+function isInertLiteral(expression) {
+    return ((isIdentifier(expression) && expression.text === "undefined") ||
+        isNullLiteral(expression) ||
+        isTrueLiteral(expression) ||
+        isFalseLiteral(expression) ||
+        (isNumericLiteral(expression) && expression.text === "0"));
+}
+function readClassExpression(node, helpers) {
+    const reading = { literals: [] };
+    const markUnreadable = (at) => {
+        reading.unreadableAt ??= at;
+    };
+    const visit = (rawExpression) => {
+        const expression = unwrapTypeWrappers(rawExpression);
+        if (isStringLiteralLikeNode(expression)) {
+            reading.literals.push(...expression.text.split(/\s+/u).filter(Boolean));
+        }
+        else if (isInertLiteral(expression)) {
+            // no contribution
+        }
+        else if (isJsxExpression(expression)) {
+            if (expression.expression)
+                visit(expression.expression);
+            else
+                markUnreadable(expression);
+        }
+        else if (isCallExpression(expression) && isIdentifier(expression.expression) && helpers.has(expression.expression.text)) {
+            const isCva = expression.expression.text === "cva";
+            for (const argument of expression.arguments) {
+                if (isCva && isObjectLiteralExpression(unwrapTypeWrappers(argument)))
+                    continue;
+                visit(argument);
+            }
+        }
+        else if (isArrayLiteralExpression(expression)) {
+            for (const element of expression.elements)
+                visit(element);
+        }
+        else if (isConditionalExpression(expression)) {
+            visit(expression.whenTrue);
+            visit(expression.whenFalse);
+        }
+        else if (isBinaryExpression(expression) && expression.operatorToken.kind === SyntaxKind.AmpersandAmpersandToken) {
+            visit(expression.right);
+        }
+        else if (isBinaryExpression(expression) &&
+            (expression.operatorToken.kind === SyntaxKind.BarBarToken ||
+                expression.operatorToken.kind === SyntaxKind.QuestionQuestionToken)) {
+            visit(expression.left);
+            visit(expression.right);
+        }
+        else if (isObjectLiteralExpression(expression)) {
+            for (const property of expression.properties) {
+                const key = isPropertyAssignment(property) || isShorthandPropertyAssignment(property)
+                    ? propertyKey(property.name)
+                    : undefined;
+                if (key === undefined)
+                    markUnreadable(property);
+                else
+                    reading.literals.push(...key.split(/\s+/u).filter(Boolean));
+            }
+        }
+        else {
+            markUnreadable(expression);
+        }
+    };
+    visit(node);
+    return reading;
+}
+function markerReason(initializer) {
+    const text = initializer && isStringLiteralLikeNode(initializer)
+        ? initializer.text
+        : initializer && isJsxExpression(initializer) && initializer.expression && isStringLiteralLikeNode(initializer.expression)
+            ? initializer.expression.text
+            : undefined;
+    const reason = text?.trim().replace(/\s+/gu, " ");
+    return reason ? reason : undefined;
+}
+export function createComponentOverrideRule({ classHelpers = [], sources = ["@ksmv/ui-react"], } = {}) {
+    const sourceSet = new Set(sources);
+    const helpers = new Set([...defaultHelpers, ...classHelpers]);
+    return {
+        name: "components/override",
+        scope: "components",
+        check(file) {
+            const result = {
+                overrides: [],
+                uncovered: [],
+                violations: [],
+            };
+            const sourceFile = file.sourceFile;
+            if (!sourceFile)
+                return result;
+            const imports = collectImports(sourceFile, sourceSet);
+            if (imports.size === 0)
+                return result;
+            const scopes = [];
+            const analyze = (element) => {
+                const opening = element;
+                const parts = tagParts(opening.tagName);
+                if (!parts)
+                    return;
+                const binding = imports.get(parts.root);
+                if (!binding || scopes.some((names) => names.has(parts.root)))
+                    return;
+                if (binding.namespace && parts.path.length === 0)
+                    return;
+                const component = binding.namespace ? parts.path.join(".") : [binding.imported, ...parts.path].join(".");
+                const visual = new Set();
+                const styleVisual = new Set();
+                const kinds = new Set();
+                // Where each kind of unreadable finding originates, so two findings on
+                // the same element sort by position instead of falling back to message text.
+                const kindNodes = new Map();
+                let reason;
+                let sawClassOrStyle = false;
+                const readClass = (initializer) => {
+                    sawClassOrStyle = true;
+                    if (!initializer)
+                        return;
+                    const reading = readClassExpression(initializer, helpers);
+                    for (const token of reading.literals) {
+                        if (classifyClass(token) === "visual")
+                            visual.add(token);
+                    }
+                    if (reading.unreadableAt) {
+                        kinds.add("dynamic-class");
+                        kindNodes.set("dynamic-class", reading.unreadableAt);
+                    }
+                };
+                const readStyle = (initializer) => {
+                    sawClassOrStyle = true;
+                    const unwrappedInitializer = initializer && isJsxExpression(initializer) ? initializer.expression : initializer;
+                    const expression = unwrappedInitializer && unwrapTypeWrappers(unwrappedInitializer);
+                    if (!expression || !isObjectLiteralExpression(expression)) {
+                        kinds.add("dynamic-style");
+                        kindNodes.set("dynamic-style", expression ?? initializer ?? element);
+                        return;
+                    }
+                    for (const property of expression.properties) {
+                        const key = isPropertyAssignment(property) || isShorthandPropertyAssignment(property)
+                            ? propertyKey(property.name)
+                            : undefined;
+                        if (key === undefined) {
+                            kinds.add("dynamic-style");
+                            kindNodes.set("dynamic-style", kindNodes.get("dynamic-style") ?? property);
+                        }
+                        else if (classifyStyleProperty(key) === "visual")
+                            styleVisual.add(key);
+                    }
+                };
+                for (const attribute of opening.attributes.properties) {
+                    if (isJsxSpreadAttribute(attribute)) {
+                        const markSpread = (node) => {
+                            if (!sawClassOrStyle)
+                                return;
+                            kinds.add("spread-after");
+                            kindNodes.set("spread-after", kindNodes.get("spread-after") ?? node);
+                        };
+                        const spread = unwrapTypeWrappers(attribute.expression);
+                        if (!isObjectLiteralExpression(spread)) {
+                            markSpread(attribute);
+                            continue;
+                        }
+                        for (const property of spread.properties) {
+                            // A nested spread or a key the checker cannot name may carry
+                            // className or style, so it counts as a spread at that point.
+                            const value = isPropertyAssignment(property)
+                                ? property.initializer
+                                : isShorthandPropertyAssignment(property)
+                                    ? property.name
+                                    : undefined;
+                            const key = isPropertyAssignment(property) || isShorthandPropertyAssignment(property)
+                                ? propertyKey(property.name)
+                                : undefined;
+                            if (value === undefined || key === undefined)
+                                markSpread(property);
+                            else if (key === "className")
+                                readClass(value);
+                            else if (key === "style")
+                                readStyle(value);
+                        }
+                        continue;
+                    }
+                    if (!isJsxAttribute(attribute))
+                        continue;
+                    const name = isIdentifier(attribute.name) ? attribute.name.text : undefined;
+                    if (name === "data-ui-override")
+                        reason = markerReason(attribute.initializer);
+                    if (name === "className")
+                        readClass(attribute.initializer);
+                    if (name === "style")
+                        readStyle(attribute.initializer);
+                }
+                const locationOf = (node) => {
+                    const position = sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile));
+                    return { column: position.character + 1, line: position.line + 1, path: file.path };
+                };
+                const location = locationOf(element);
+                const classes = [...visual].sort();
+                const styles = [...styleVisual].sort();
+                const findingKinds = [...kinds].sort();
+                if (reason !== undefined) {
+                    result.overrides.push({
+                        ...location,
+                        classes: [...classes, ...styles.map((key) => `style:${key}`), ...findingKinds],
+                        component,
+                        reason,
+                    });
+                    return;
+                }
+                if (classes.length > 0) {
+                    result.violations.push({
+                        ...location,
+                        anchor: `${component}|classes|${classes.join(" ")}`,
+                        message: `${component} has visual classes without data-ui-override: ${classes.join(", ")}.`,
+                        nodeKind: "component-override:classes",
+                        rule: "components/override",
+                    });
+                }
+                if (styles.length > 0) {
+                    result.violations.push({
+                        ...location,
+                        anchor: `${component}|style|${styles.join(" ")}`,
+                        message: `${component} has visual style properties without data-ui-override: ${styles.join(", ")}.`,
+                        nodeKind: "component-override:style",
+                        rule: "components/override",
+                    });
+                }
+                for (const kind of findingKinds) {
+                    result.violations.push({
+                        ...locationOf(kindNodes.get(kind) ?? element),
+                        anchor: `${component}|${kind}`,
+                        message: `${component} has ${kindMessages[kind]} without data-ui-override.`,
+                        nodeKind: `component-override:${kind}`,
+                        rule: "components/override",
+                    });
+                }
+            };
+            const visit = (node) => {
+                const names = scopeNames(node);
+                if (names)
+                    scopes.push(names);
+                if (isJsxOpeningElement(node) || isJsxSelfClosingElement(node))
+                    analyze(node);
+                node.forEachChild(visit);
+                if (names)
+                    scopes.pop();
+            };
+            sourceFile.forEachChild(visit);
+            return result;
+        },
+    };
+}

package/dist/rules/default.d.ts

@@ -1,10 +1,11 @@
-import type { ThemeConfig } from "../config.js";
+import type { ComponentsConfig, ThemeConfig } from "../config.js";
 import type { ContrastManifest, ThemeContract } from "../contracts.js";
 import type { CheckRule } from "../scan.js";
 export interface DefaultRulesOptions {
+    components?: ComponentsConfig;
     computed?: Record<string, Record<string, string>>;
     contract?: ThemeContract;
     manifest?: ContrastManifest;
     themes: ThemeConfig[];
 }
-export declare function createDefaultRules({ computed, contract, manifest, themes, }: DefaultRulesOptions): Promise<CheckRule[]>;
+export declare function createDefaultRules({ components, computed, contract, manifest, themes, }: DefaultRulesOptions): Promise<CheckRule[]>;

package/dist/rules/default.js

@@ -1,8 +1,9 @@
+import { createComponentOverrideRule } from "./componentOverride.js";
 import { createNoLiteralColorRule } from "./noLiteralColor.js";
 import { createTokenCompleteRule, loadThemeContract } from "./tokenComplete.js";
 import { createTokenContrastRule, loadContrastManifest, } from "./tokenContrast.js";
 import { createTokenPrefixRule } from "./tokenPrefix.js";
-export async function createDefaultRules({ computed, contract, manifest, themes, }) {
+export async function createDefaultRules({ components, computed, contract, manifest, themes, }) {
     const [resolvedContract, resolvedManifest] = await Promise.all([
         contract ?? loadThemeContract(),
         manifest ?? loadContrastManifest(),
@@ -12,5 +13,8 @@ export async function createDefaultRules({ computed, contract, manifest, themes,
         createTokenPrefixRule(),
         createTokenCompleteRule({ computed, contract: resolvedContract, themes }),
         createTokenContrastRule({ computed, manifest: resolvedManifest, themes }),
+        ...(components
+            ? [createComponentOverrideRule({ classHelpers: components.classHelpers, sources: components.sources })]
+            : []),
     ];
 }

package/dist/rules/overrideCatalog.d.ts

@@ -0,0 +1,5 @@
+export type OverrideClass = "free" | "visual";
+/** The utility a class applies, without variants, importance or negative sign. */
+export declare function utilityOf(token: string): string;
+export declare function classifyClass(token: string): OverrideClass;
+export declare function classifyStyleProperty(name: string): OverrideClass;

package/dist/rules/overrideCatalog.js

@@ -0,0 +1,85 @@
+/**
+ * Splits a class at its variant separators: the colons outside square
+ * brackets, so `[&:hover]:bg-red-500` and `bg-[color:var(--x)]` stay intact.
+ */
+function splitVariants(token) {
+    const parts = [];
+    let depth = 0;
+    let current = "";
+    for (const char of token) {
+        if (char === "[")
+            depth += 1;
+        if (char === "]")
+            depth = Math.max(0, depth - 1);
+        if (char === ":" && depth === 0) {
+            parts.push(current);
+            current = "";
+            continue;
+        }
+        current += char;
+    }
+    parts.push(current);
+    return parts;
+}
+/** The utility a class applies, without variants, importance or negative sign. */
+export function utilityOf(token) {
+    let utility = splitVariants(token).at(-1) ?? "";
+    if (utility.startsWith("!"))
+        utility = utility.slice(1);
+    if (utility.endsWith("!"))
+        utility = utility.slice(0, -1);
+    if (utility.startsWith("-"))
+        utility = utility.slice(1);
+    return utility;
+}
+// Spec §4.1: fitting into the parent is free; everything else, including any
+// class outside this list, changes the component and needs a marker. A class
+// is free only when its utility AND its value match the family's grammar —
+// matching only the prefix would also free look-alike product classes such as
+// `top-bar` or `order-summary`.
+const num = String.raw `\d+(?:\.\d+)?`;
+const frac = String.raw `\d+\/\d+`;
+// An arbitrary value may nest brackets or parentheses (`mt-[theme(spacing[2])]`);
+// the family prefix already fixes the property, so any bracketed value is fine.
+const arb = String.raw `\[\S+\]|\(\S+\)`;
+const size = String.raw `3xs|2xs|xs|sm|md|lg|xl|2xl|3xl|4xl|5xl|6xl|7xl|prose`;
+const vw = String.raw `screen|svw|lvw|dvw`;
+const freeUtilities = [
+    new RegExp(`^m[trblxyse]?-(?:${num}|px|auto|${arb})$`, "u"),
+    new RegExp(`^(?:min-|max-)?w-(?:${num}|${frac}|px|auto|full|${vw}|min|max|fit|${size}|${arb})$`, "u"),
+    /^max-w-none$/u,
+    /^flex-(?:1|none|auto|initial)$/u,
+    /^grow$/u,
+    new RegExp(`^grow-(?:${num}|${arb})$`, "u"),
+    /^shrink$/u,
+    new RegExp(`^shrink-(?:${num}|${arb})$`, "u"),
+    new RegExp(`^basis-(?:${num}|${frac}|px|auto|full|${size}|${arb})$`, "u"),
+    new RegExp(`^order-(?:${num}|first|last|none|${arb})$`, "u"),
+    /^(?:self|justify-self|place-self)-(?:auto|start|end|center|stretch|baseline)$/u,
+    new RegExp(`^(?:col|row)-span-(?:${num}|full|${arb})$`, "u"),
+    new RegExp(`^(?:col|row)-(?:start|end)-(?:${num}|auto|${arb})$`, "u"),
+    /^(?:static|relative|absolute|fixed|sticky)$/u,
+    new RegExp(`^inset(?:-[xy])?-(?:${num}|${frac}|px|auto|full|${arb})$`, "u"),
+    new RegExp(`^(?:top|right|bottom|left|start|end)-(?:${num}|${frac}|px|auto|full|${arb})$`, "u"),
+    new RegExp(`^z-(?:${num}|auto|${arb})$`, "u"),
+    /^(?:hidden|sr-only|not-sr-only|invisible|visible)$/u,
+    /^text-(?:left|center|right|justify|start|end)$/u,
+];
+export function classifyClass(token) {
+    const utility = utilityOf(token);
+    return freeUtilities.some((pattern) => pattern.test(utility)) ? "free" : "visual";
+}
+// Spec §4.2, by property name; kebab-case keys are read as camelCase.
+const freeStyleProperties = new Set([
+    "margin", "marginTop", "marginRight", "marginBottom", "marginLeft", "marginBlock",
+    "marginBlockStart", "marginBlockEnd", "marginInline", "marginInlineStart", "marginInlineEnd",
+    "width", "minWidth", "maxWidth", "flex", "flexGrow", "flexShrink", "flexBasis", "order",
+    "alignSelf", "justifySelf", "placeSelf", "gridColumn", "gridColumnStart", "gridColumnEnd",
+    "gridRow", "gridRowStart", "gridRowEnd", "gridArea", "position", "inset", "insetBlock",
+    "insetBlockStart", "insetBlockEnd", "insetInline", "insetInlineStart", "insetInlineEnd",
+    "top", "right", "bottom", "left", "zIndex", "textAlign", "visibility",
+]);
+export function classifyStyleProperty(name) {
+    const camel = name.replace(/-([a-z])/gu, (_, letter) => letter.toUpperCase());
+    return freeStyleProperties.has(camel) ? "free" : "visual";
+}

package/dist/scan.d.ts

@@ -1,7 +1,7 @@
 import { type Root } from "postcss";
 import { SyntaxKind, type SourceFile } from "typescript/unstable/ast";
 import type { ChecksConfig } from "./config.js";
-import type { CheckReport, Uncovered, Violation } from "./result.js";
+import type { CheckReport, ComponentOverride, Uncovered, Violation } from "./result.js";
 export interface ScannedFile {
     content: string;
     cssRoot?: Root;
@@ -16,6 +16,7 @@ export interface TypeScriptToken {
     text: string;
 }
 export interface RuleResult {
+    overrides?: ComponentOverride[];
     uncovered: Uncovered[];
     violations: Violation[];
 }
@@ -24,6 +25,8 @@ export interface CheckRule {
     check(file: ScannedFile): Promise<RuleResult> | RuleResult;
     complete?(): Promise<RuleResult> | RuleResult;
     name: string;
+    /** Which file set the rule runs on; "main" (the default) is `include`. */
+    scope?: "main" | "components";
 }
 export interface RunChecksOptions {
     applyGovernance?: boolean;

package/dist/scan.js

@@ -24,6 +24,19 @@ function scanTypeScript(content, path) {
     const uncovered = [];
     let kind = scanner.scan();
     while (kind !== SyntaxKind.EndOfFile) {
+        // This scan has no parser behind it, so a "#" that starts no name (the one
+        // in /#/, read here as a division) comes back as a zero-width token and
+        // the scanner stays where it was. Read it as the hash it is; if a token
+        // still has no width, step over one character so the scan always ends.
+        if (scanner.getTokenEnd() <= scanner.getTokenStart()) {
+            if (kind === SyntaxKind.PrivateIdentifier)
+                kind = scanner.reScanHashToken();
+            if (scanner.getTokenEnd() <= scanner.getTokenStart()) {
+                scanner.resetTokenState(scanner.getTokenStart() + 1);
+                kind = scanner.scan();
+                continue;
+            }
+        }
         tokens.push({
             end: scanner.getTokenEnd(),
             kind,
@@ -88,6 +101,7 @@ function emptyReport(rulesExecuted) {
         filesRead: 0,
         nodesChecked: 0,
         operationalErrors: [],
+        overrides: [],
         rulesExecuted,
         schemaVersion: 1,
         suppressions: [],
@@ -150,6 +164,25 @@ function validateRuntimeConfig(value) {
                         theme.computedEvidence.theme.length === 0))))) {
         return "Themes must be an array of named selectors with files.";
     }
+    if (candidate.components !== undefined) {
+        const components = candidate.components;
+        const isList = (value, nonEmpty) => Array.isArray(value) &&
+            (!nonEmpty || value.length > 0) &&
+            value.every((item) => typeof item === "string" && item.length > 0);
+        if (!components ||
+            typeof components !== "object" ||
+            Array.isArray(components) ||
+            Object.keys(components).some((key) => !["classHelpers", "exclude", "include", "sources"].includes(key)) ||
+            !isList(components.include, true) ||
+            (components.exclude !== undefined &&
+                !isList(components.exclude, false)) ||
+            (components.sources !== undefined &&
+                !isList(components.sources, true)) ||
+            (components.classHelpers !== undefined &&
+                !isList(components.classHelpers, false))) {
+            return "components needs include patterns and optional exclude, sources and classHelpers string lists.";
+        }
+    }
     return undefined;
 }
 export async function runChecks(config, options = {}) {
@@ -192,6 +225,7 @@ export async function runChecks(config, options = {}) {
                 themes: config.themes ?? [],
             });
             configuredRules = await (await import("./rules/default.js")).createDefaultRules({
+                components: config.components,
                 computed,
                 contract: contracts.theme,
                 manifest: contracts.contrast,
@@ -251,7 +285,19 @@ export async function runChecks(config, options = {}) {
     }))
         .sort((left, right) => left.path.localeCompare(right.path));
     report.filesDiscovered = includedBeforeExcludes.length;
-    if (absolutePaths.length === 0) {
+    const componentPaths = config.components
+        ? (await discoverFiles(root, config.components.include, config.components.exclude)).filter((path) => extname(path).toLowerCase() !== ".css")
+        : [];
+    if (config.components && componentPaths.length === 0) {
+        report.operationalErrors.push({
+            code: "no-files",
+            message: "No files matched components.include.",
+        });
+    }
+    const mainPaths = new Set(absolutePaths);
+    const componentSet = new Set(componentPaths);
+    const allPaths = [...new Set([...absolutePaths, ...componentPaths])].sort((left, right) => left.localeCompare(right));
+    if (allPaths.length === 0) {
         report.operationalErrors.push({
             code: "no-files",
             message: "No files matched the configured include patterns.",
@@ -267,7 +313,7 @@ export async function runChecks(config, options = {}) {
     // in one report, so type analysis is refused rather than silently mixed.
     const typeScriptPaths = options.readFile
         ? []
-        : absolutePaths.filter((path) => extname(path).toLowerCase() !== ".css");
+        : allPaths.filter((path) => extname(path).toLowerCase() !== ".css");
     if (options.readFile) {
         report.operationalErrors.push({
             code: "internal",
@@ -292,8 +338,10 @@ export async function runChecks(config, options = {}) {
             });
         }
     }
-    for (const absolutePath of absolutePaths) {
+    for (const absolutePath of allPaths) {
         const path = toPosixPath(relative(root, absolutePath));
+        const inMain = mainPaths.has(absolutePath);
+        const inComponents = componentSet.has(absolutePath);
         let content;
         try {
             content = await readSource(absolutePath);
@@ -307,7 +355,8 @@ export async function runChecks(config, options = {}) {
             });
             continue;
         }
-        if (usesDefaultRules &&
+        if (inMain &&
+            usesDefaultRules &&
             config.contractSource === "bundled" &&
             /(?:from\s*|import\s*(?:\(\s*)?)["']@ksmv\/ui-react(?:\/[^"']*)?["']/.test(content) &&
             !report.operationalErrors.some(({ code, message }) => code === "config" &&
@@ -341,7 +390,8 @@ export async function runChecks(config, options = {}) {
                     file.sourceFile = project.program.getSourceFile(absolutePath);
                 }
                 report.nodesChecked += coverage.nodesChecked;
-                report.uncovered.push(...coverage.uncovered);
+                if (inMain)
+                    report.uncovered.push(...coverage.uncovered);
             }
         }
         catch {
@@ -353,10 +403,14 @@ export async function runChecks(config, options = {}) {
             continue;
         }
         for (const rule of rules) {
+            const runsHere = (rule.scope ?? "main") === "components" ? inComponents : inMain;
+            if (!runsHere)
+                continue;
             try {
                 const result = await rule.check(file);
                 report.violations.push(...result.violations);
                 report.uncovered.push(...result.uncovered);
+                report.overrides.push(...(result.overrides ?? []));
             }
             catch {
                 report.operationalErrors.push({
@@ -375,6 +429,7 @@ export async function runChecks(config, options = {}) {
             const result = await rule.complete();
             report.violations.push(...result.violations);
             report.uncovered.push(...result.uncovered);
+            report.overrides.push(...(result.overrides ?? []));
         }
         catch {
             report.operationalErrors.push({
@@ -394,6 +449,10 @@ export async function runChecks(config, options = {}) {
     report.uncovered.sort(compareFindings);
     report.operationalErrors.sort((left, right) => (left.path ?? "").localeCompare(right.path ?? "") ||
         left.code.localeCompare(right.code));
+    report.overrides.sort((left, right) => left.path.localeCompare(right.path) ||
+        left.line - right.line ||
+        left.column - right.column ||
+        left.component.localeCompare(right.component));
     report.exitCode = resolveExitCode(report, config.failOnUncovered ?? true);
     report.durationMs = Math.round((performance.now() - startedAt) * 100) / 100;
     return report;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ksmv/ui-checks",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Static and computed quality checks for semantic UI token contracts.",
   "keywords": ["accessibility", "design-tokens", "quality", "static-analysis"],
   "license": "Apache-2.0",