@ksmv/ui-checks 0.1.2 → 0.1.4

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 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.
+- `bugs` passa a ser declarado vazio. Na 0.1.2 o campo foi omitido, e o npm o derivou do endereço de `repository` ao publicar, então a página do pacote continuou apontando para as issues do repositório privado, que respondem 404. Declarado vazio, o npm o descarta sem derivá-lo. Não há canal público de issues, e o README indica o canal de relato de segurança.
+
 ## 0.1.2 - 2026-09-28
 
 - `./package.json` passa a ser exportado, como já era em `@ksmv/ui-react`. Ler a versão instalada por `require.resolve("@ksmv/ui-checks/package.json")` terminava com `ERR_PACKAGE_PATH_NOT_EXPORTED`.

package/README.md

@@ -84,6 +84,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 +111,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/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/rules/tokenComplete.js

@@ -92,7 +92,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ksmv/ui-checks",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Static and computed quality checks for semantic UI token contracts.",
   "keywords": ["accessibility", "design-tokens", "quality", "static-analysis"],
   "license": "Apache-2.0",
@@ -29,5 +29,6 @@
   "engines": { "node": ">=22.14" },
   "repository": { "type": "git", "url": "https://github.com/AxisGov/ui.git", "directory": "packages/checks" },
   "homepage": "https://www.npmjs.com/package/@ksmv/ui-checks",
+  "bugs": {},
   "publishConfig": { "access": "public", "registry": "https://registry.npmjs.org/" }
 }