@ksmv/ui-checks 0.1.3 → 0.1.5

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 0.1.5 - 2026-09-28
+
+- **Fingerprints de baseline estáveis.** O fingerprint passa a seguir o conteúdo do achado e a ordem entre achados idênticos no mesmo arquivo, e não mais a linha e a coluna. Na 0.1.4, uma linha inserida acima de dívida conhecida fazia toda a dívida seguinte reaparecer como achado novo; numa aplicação consumidora real, um comentário no topo do CSS gerou 115 falsos achados novos. O conteúdo entra no fingerprint só como hash, e nenhum trecho é gravado ou relatado.
+- **Baselines da 0.1.4 ou anteriores precisam ser regeneradas uma vez**, porque os fingerprints mudaram.
+- Espaços dentro de valores entre aspas, como em `[data-state="a  b"]`, continuam distinguindo achados. Uma regra de terceiros que não forneça âncora de conteúdo mantém o fingerprint posicional, para que uma mensagem genérica não faça um achado ocupar o lugar de outro.
+- `css/no-literal-color` deixa de abortar o arquivo quando o parser de cores lança exceção em valores que ele não reconhece, como `calc(100vw-1.5rem)` num valor arbitrário do Tailwind. O valor passa a ser tratado como "não é cor".
+
+## 0.1.4 - 2026-09-28
+
+- A evidência calculada aceita tokens derivados ausentes ou vazios, que é como o navegador informa um token que o tema deixou no padrão, e usa o valor do token de origem. Na 0.1.3, um tema que confiava nos padrões documentados dos derivados nunca produzia evidência válida pela receita do README.
+- Tokens de marca (`brandComposition`) também podem vir vazios na evidência, e a receita do README passa a capturá-los.
+- Com evidência que traz o valor final de um token, `tokens/complete` deixa de marcar como não resolvidas as referências dele a tokens privados do consumidor. Na 0.1.3, uma ponte `--ui-*` que apontava para tokens do produto ficava com cobertura obrigatória pendente mesmo com evidência completa, e não podia entrar em baseline.
+- Um token obrigatório vazio continua sendo recusado.
+
 ## 0.1.3 - 2026-09-28
 
 - Sem mudança nas verificações: regras, contratos, códigos de saída e README são os mesmos da 0.1.2.

package/README.md

@@ -55,6 +55,8 @@ npx ksmv-ui-checks baseline ksmv-ui.config.js --write --first-seen-version=0.1.2
 
 O arquivo guarda fingerprints, regra, papel responsável e meta de redução, sem copiar o trecho encontrado. Uma atualização que aumente a dívida exige `--allow-growth` e uma justificativa em arquivo via `--reason-file`. Erro operacional e cobertura obrigatória ausente nunca entram na baseline.
 
+O fingerprint segue o conteúdo do achado, como seletor, propriedade e valor, e a ordem entre achados idênticos no mesmo arquivo, não a linha. Linhas inseridas ou removidas em outro ponto do arquivo não transformam dívida conhecida em achado novo; mudar o próprio trecho, sim. Baselines gravadas pela `0.1.4` ou anterior usavam a posição e precisam ser regeneradas uma vez com a `0.1.5`.
+
 ## Códigos de saída
 
 - `0`: análise completa, sem violações novas;
@@ -84,6 +86,8 @@ A evidência não é uma exceção manual. O arquivo é recusado, com código `2
 - a identidade de um dos contratos diverge da instalada, ou seja, o pacote React mudou depois da captura;
 - falta algum token exigido, ou algum valor ainda contém `var(...)`.
 
+Tokens opcionais, os derivados e os de marca, podem ficar vazios na captura: é assim que o navegador informa um token que o tema não declarou. Um derivado vazio assume o valor do token de origem, que é o padrão documentado no contrato.
+
 A captura usa a API pública deste pacote e um navegador à sua escolha. Com Playwright, e a aplicação servida localmente:
 
 ```js
@@ -109,6 +113,7 @@ const tokens = [...new Set([
   ...contracts.theme.required,
   ...Object.keys(contracts.theme.derived),
   ...Object.values(contracts.theme.derived),
+  ...contracts.theme.brandComposition,
   ...contracts.contrast.pairs.flatMap(({ background, foreground }) => [background, foreground]),
 ])];
 

package/dist/anchor.d.ts

@@ -0,0 +1,8 @@
+import type { Declaration } from "postcss";
+import type { Node, SourceFile } from "typescript/unstable/ast";
+/** The selector chain and the declaration, value included. */
+export declare function cssDeclarationAnchor(declaration: Declaration): string;
+/** The selector chain and the property name, for findings about the name. */
+export declare function cssPropertyAnchor(declaration: Declaration): string;
+/** The source text of a TSX node. */
+export declare function tsxNodeAnchor(node: Node, sourceFile: SourceFile): string;

package/dist/anchor.js

@@ -0,0 +1,62 @@
+// Anchors identify a finding by its content rather than its position, so a
+// baseline survives lines inserted or removed elsewhere in the file. They are
+// hashed into the fingerprint and never stored or reported as text.
+// Collapses whitespace outside quoted strings only: inside quotes, as in
+// [data-state="a  b"], whitespace is part of the value and tells findings apart.
+function normalize(text) {
+    let result = "";
+    let quote;
+    let pendingSpace = false;
+    for (let index = 0; index < text.length; index += 1) {
+        const character = text[index];
+        if (quote !== undefined) {
+            result += character;
+            if (character === "\\" && index + 1 < text.length) {
+                index += 1;
+                result += text[index];
+            }
+            else if (character === quote) {
+                quote = undefined;
+            }
+            continue;
+        }
+        if (/\s/.test(character)) {
+            pendingSpace = result.length > 0;
+            continue;
+        }
+        if (pendingSpace) {
+            result += " ";
+            pendingSpace = false;
+        }
+        result += character;
+        if (character === '"' || character === "'" || character === "`") {
+            quote = character;
+        }
+    }
+    return result;
+}
+function cssContext(declaration) {
+    const context = [];
+    for (let parent = declaration.parent; parent && parent.type !== "root"; parent = parent.parent) {
+        if (parent.type === "rule") {
+            context.unshift(parent.selector);
+        }
+        else if (parent.type === "atrule") {
+            const atRule = parent;
+            context.unshift(`@${atRule.name} ${atRule.params}`);
+        }
+    }
+    return context;
+}
+/** The selector chain and the declaration, value included. */
+export function cssDeclarationAnchor(declaration) {
+    return normalize([...cssContext(declaration), `${declaration.prop}: ${declaration.value}`].join(" > "));
+}
+/** The selector chain and the property name, for findings about the name. */
+export function cssPropertyAnchor(declaration) {
+    return normalize([...cssContext(declaration), declaration.prop].join(" > "));
+}
+/** The source text of a TSX node. */
+export function tsxNodeAnchor(node, sourceFile) {
+    return normalize(node.getText(sourceFile));
+}

package/dist/baseline.d.ts

@@ -36,6 +36,14 @@ export interface GrowthApproval {
     errors: string[];
 }
 export declare function normalizeRelativePath(path: string): string;
+/**
+ * Gives every violation a fingerprint that follows its content and its order
+ * among identical findings in the same file, not its line and column, so lines
+ * inserted or removed elsewhere do not turn baselined debt into new findings.
+ * The content comes from the rule's anchor, or the message when a rule sets
+ * none; either way only its hash is kept.
+ */
+export declare function assignFingerprints(violations: Violation[]): void;
 export declare function fingerprintViolation(violation: Violation): string;
 export declare function baselineFor(violations: Violation[], metadata: BaselineMetadata, previous?: BaselineFile): BaselineFile;
 export declare function validateBaseline(value: unknown): BaselineValidation;

package/dist/baseline.js

@@ -48,7 +48,51 @@ function compareEntries(left, right) {
         left.rule.localeCompare(right.rule) ||
         left.fingerprint.localeCompare(right.fingerprint));
 }
+const fingerprintPattern = /^[a-f0-9]{64}$/;
+/**
+ * Gives every violation a fingerprint that follows its content and its order
+ * among identical findings in the same file, not its line and column, so lines
+ * inserted or removed elsewhere do not turn baselined debt into new findings.
+ * The content comes from the rule's anchor, or the message when a rule sets
+ * none; either way only its hash is kept.
+ */
+export function assignFingerprints(violations) {
+    const ordered = [...violations].sort((left, right) => normalizeRelativePath(left.path).localeCompare(normalizeRelativePath(right.path)) ||
+        left.line - right.line ||
+        left.column - right.column);
+    const occurrences = new Map();
+    for (const violation of ordered) {
+        // Without an anchor there is no content to follow, and a generic message
+        // could let one finding stand in for another; such a violation keeps its
+        // positional fingerprint.
+        if (violation.anchor === undefined) {
+            violation.fingerprint = positionalFingerprint(violation);
+            continue;
+        }
+        const identity = [
+            violation.rule.trim(),
+            normalizeRelativePath(violation.path),
+            normalizeNodeKind(violation.nodeKind),
+            violation.anchor,
+        ];
+        const key = JSON.stringify(identity);
+        const occurrence = occurrences.get(key) ?? 0;
+        occurrences.set(key, occurrence + 1);
+        violation.fingerprint = createHash("sha256")
+            .update(JSON.stringify([2, ...identity, occurrence]))
+            .digest("hex");
+        delete violation.anchor;
+    }
+}
 export function fingerprintViolation(violation) {
+    if (violation.fingerprint !== undefined && fingerprintPattern.test(violation.fingerprint)) {
+        return violation.fingerprint;
+    }
+    return positionalFingerprint(violation);
+}
+// The identity of a violation without an anchor, and of one built outside
+// runChecks: its position, which only compares with others built the same way.
+function positionalFingerprint(violation) {
     const input = JSON.stringify([
         1,
         violation.rule.trim(),

package/dist/color.js

@@ -38,7 +38,15 @@ export function isColorBearingProperty(property) {
         cssProperty === "column-rule");
 }
 function parsedColor(value) {
-    const parsed = parse(value);
+    // culori throws, instead of answering "not a color", on some values Tailwind
+    // allows in arbitrary classes, such as calc(100vw-1.5rem).
+    let parsed;
+    try {
+        parsed = parse(value);
+    }
+    catch {
+        return undefined;
+    }
     const color = parsed ? toRgb(parsed) : undefined;
     if (!color ||
         !Number.isFinite(color.r) ||

package/dist/evidence.js

@@ -38,11 +38,14 @@ function sameIdentity(actual, expected) {
         actual.contractVersion === expected.contractVersion &&
         actual.sha256 === expected.sha256;
 }
+// Derived tokens are not required: a theme may leave them to their documented
+// default, the source token, and the browser then reports them as empty.
 function requiredEvidenceTokens(contracts) {
+    const derived = contracts.theme.derived;
     return new Set([
         ...contracts.theme.required,
-        ...Object.keys(contracts.theme.derived),
-        ...Object.values(contracts.theme.derived),
+        // A source that is itself derived is optional too; its chain is followed.
+        ...Object.values(derived).filter((source) => !(source in derived)),
         ...contracts.contrast.pairs.flatMap(({ background, foreground }) => [
             background,
             foreground,
@@ -73,13 +76,20 @@ function validateEvidenceShape(value, contracts) {
         !isRecord(value.themes)) {
         return false;
     }
+    // A token the evidence must carry is never optional, even when the contract
+    // also lists it as derived or as a brand token.
+    const required = requiredEvidenceTokens(contracts);
+    const optional = new Set([...Object.keys(contracts.theme.derived), ...contracts.theme.brandComposition]
+        .filter((token) => !required.has(token)));
     return Object.values(value.themes).every((theme) => isRecord(theme) &&
         exactKeys(theme, ["selector", "tokens"]) &&
         typeof theme.selector === "string" &&
         isRecord(theme.tokens) &&
         Object.entries(theme.tokens).every(([token, tokenValue]) => tokenNamePattern.test(token) &&
             typeof tokenValue === "string" &&
-            tokenValue.trim().length > 0 &&
+            // Empty means undeclared, which only an optional token may be: a derived
+            // token left to its default, or a brand token the theme does not use.
+            (tokenValue.trim().length > 0 || optional.has(token)) &&
             !/var\s*\(/i.test(tokenValue)));
 }
 export async function loadComputedEvidence({ contracts, evidenceByPath, now = new Date(), root, themes, }) {
@@ -121,7 +131,23 @@ export async function loadComputedEvidence({ contracts, evidenceByPath, now = ne
                         throw new Error("tokens");
                     }
                 }
-                result[theme.name] = { ...computedTheme.tokens };
+                const tokens = Object.fromEntries(Object.entries(computedTheme.tokens).filter(([, tokenValue]) => tokenValue.trim().length > 0));
+                // A derived token left to its default takes its source's value,
+                // following sources that are derived themselves. A chain that does not
+                // end in a real value makes the evidence invalid.
+                const derivedValue = (token, seen) => {
+                    const value = tokens[token];
+                    if (value !== undefined)
+                        return value;
+                    const source = contracts.theme.derived[token];
+                    if (source === undefined || seen.has(token))
+                        throw new Error("tokens");
+                    return derivedValue(source, new Set([...seen, token]));
+                };
+                for (const token of Object.keys(contracts.theme.derived)) {
+                    tokens[token] = derivedValue(token, new Set());
+                }
+                result[theme.name] = tokens;
             }
         }
         return result;

package/dist/result.d.ts

@@ -4,6 +4,14 @@ export interface SourceLocation {
     line: number;
 }
 export interface Violation extends SourceLocation {
+    /**
+     * Content that identifies the finding independently of its position. Rules
+     * set it; `runChecks` hashes it into `fingerprint` and removes it, so it is
+     * never reported or stored.
+     */
+    anchor?: string;
+    /** Stable fingerprint assigned by `runChecks`; see `fingerprintViolation`. */
+    fingerprint?: string;
     message: string;
     nodeKind: string;
     path: string;

package/dist/rules/noLiteralColor.js

@@ -1,4 +1,5 @@
 import { isComputedPropertyName, isIdentifier, isJsxAttribute, isJsxExpression, isObjectLiteralExpression, isPropertyAssignment, isStringLiteralLikeNode, } from "typescript/unstable/ast";
+import { cssDeclarationAnchor, tsxNodeAnchor } from "../anchor.js";
 import { containsLiteralColor, isColorBearingProperty } from "../color.js";
 import { isAllowedThemeDeclaration } from "./theme.js";
 function emptyResult() {
@@ -56,6 +57,7 @@ export function createNoLiteralColorRule({ themes, }) {
                     containsLiteralColor(declaration.value) &&
                     !isAllowedThemeDeclaration(file, declaration, themes)) {
                     result.violations.push({
+                        anchor: cssDeclarationAnchor(declaration),
                         column: declaration.source?.start?.column ?? 1,
                         line: declaration.source?.start?.line ?? 1,
                         message: "Literal colors are allowed only in configured themes.",
@@ -79,7 +81,13 @@ export function createNoLiteralColorRule({ themes, }) {
                     if (value !== undefined &&
                         ((isDirectColor && containsLiteralColor(value)) || isLiteralClass)) {
                         const position = sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile));
+                        // For className, only the classes that carry the literal color
+                        // identify the finding; the other classes may change freely.
+                        const anchor = isLiteralClass && !isDirectColor
+                            ? `className: ${value.split(/\s+/).filter(classContainsLiteralColor).join(" ")}`
+                            : tsxNodeAnchor(node, sourceFile);
                         result.violations.push({
+                            anchor,
                             column: position.character + 1,
                             line: position.line + 1,
                             message: "Literal colors are allowed only in configured themes.",
@@ -107,6 +115,7 @@ export function createNoLiteralColorRule({ themes, }) {
                             containsLiteralColor(property.initializer.text)) {
                             const position = sourceFile.getLineAndCharacterOfPosition(property.initializer.getStart(sourceFile));
                             result.violations.push({
+                                anchor: tsxNodeAnchor(property, sourceFile),
                                 column: position.character + 1,
                                 line: position.line + 1,
                                 message: "Literal colors are allowed only in configured themes.",

package/dist/rules/tokenComplete.js

@@ -58,6 +58,7 @@ export function createTokenCompleteRule({ computed = {}, contract, themes, }) {
                         missingRequired = true;
                         result.violations.push({
                             ...location,
+                            anchor: theme.name,
                             message: `Theme ${theme.name} is missing required token ${token}.`,
                             nodeKind: `theme-token:${token}`,
                             rule: "tokens/complete",
@@ -78,6 +79,7 @@ export function createTokenCompleteRule({ computed = {}, contract, themes, }) {
                         !theme.declarations.has(fallback)) {
                         result.violations.push({
                             ...location,
+                            anchor: theme.name,
                             message: `Derived token ${token} has no available documented fallback.`,
                             nodeKind: `theme-token:${token}`,
                             rule: "tokens/complete",
@@ -92,7 +94,13 @@ export function createTokenCompleteRule({ computed = {}, contract, themes, }) {
                     tokens.set(name, value);
                 }
                 const reportedReferences = new Set();
-                for (const declaration of theme.declarations.values()) {
+                for (const [name, declaration] of theme.declarations) {
+                    // The evidence carries the value the browser computed for this very
+                    // token, so whatever it referenced, private tokens included, has
+                    // already been resolved.
+                    if (computedTheme[name] !== undefined) {
+                        continue;
+                    }
                     for (const reference of unresolvedTokenReferences(declaration.value, tokens)) {
                         if (!reportedReferences.has(reference)) {
                             reportedReferences.add(reference);

package/dist/rules/tokenContrast.js

@@ -157,6 +157,7 @@ export function createTokenContrastRule({ computed = {}, manifest, themes, }) {
                     else if (ratio < pair.minimum) {
                         result.violations.push({
                             ...location,
+                            anchor: theme.name,
                             message: `Contrast pair ${pair.context} is below ${pair.minimum}:1.`,
                             nodeKind: `contrast-pair:${pair.context}:${pair.foreground}:${pair.background}`,
                             rule: "tokens/contrast",

package/dist/rules/tokenPrefix.js

@@ -1,4 +1,5 @@
 import { isComputedPropertyName, isIdentifier, isJsxAttribute, isJsxExpression, isObjectLiteralExpression, isPropertyAssignment, isStringLiteralLikeNode, } from "typescript/unstable/ast";
+import { cssPropertyAnchor, tsxNodeAnchor } from "../anchor.js";
 export function createTokenPrefixRule() {
     return {
         name: "tokens/prefix",
@@ -8,6 +9,7 @@ export function createTokenPrefixRule() {
                 if (declaration.prop.startsWith("--") &&
                     !declaration.prop.startsWith("--ui-")) {
                     violations.push({
+                        anchor: cssPropertyAnchor(declaration),
                         column: declaration.source?.start?.column ?? 1,
                         line: declaration.source?.start?.line ?? 1,
                         message: "Public custom properties must use the --ui- prefix.",
@@ -42,6 +44,7 @@ export function createTokenPrefixRule() {
                             if (name?.startsWith("--") && !name.startsWith("--ui-")) {
                                 const position = sourceFile.getLineAndCharacterOfPosition(propertyNode.getStart(sourceFile));
                                 violations.push({
+                                    anchor: tsxNodeAnchor(propertyNode, sourceFile),
                                     column: position.character + 1,
                                     line: position.line + 1,
                                     message: "Public custom properties must use the --ui- prefix.",

package/dist/scan.js

@@ -5,6 +5,7 @@ import { computeLineStarts, createScanner, LanguageVariant, SyntaxKind, } from "
 import { API } from "typescript/unstable/sync";
 import { resolveContractSet } from "./contracts.js";
 import { loadComputedEvidence } from "./evidence.js";
+import { assignFingerprints } from "./baseline.js";
 import { applyDebtControls } from "./governance.js";
 const supportedExtensions = [".css", ".js", ".jsx", ".ts", ".tsx"];
 function toPosixPath(path) {
@@ -384,6 +385,7 @@ export async function runChecks(config, options = {}) {
     }
     typeScriptSnapshot?.dispose();
     typeScriptApi?.close();
+    assignFingerprints(report.violations);
     if (options.applyGovernance ?? usesDefaultRules) {
         await applyDebtControls(report, config);
     }

package/package.json

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