@ksmv/ui-checks 0.1.0 → 0.1.2

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 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`.
+- O README passa a ser a documentação completa para quem não vê o repositório de origem, que é privado: formato de `ksmv-ui.config.js`, `contractSource`, baseline, códigos de saída, quando a evidência calculada é necessária, o que a invalida e uma receita de captura com a API pública.
+- `homepage` aponta para a página do pacote no npm, e `bugs` foi removido. Os dois levavam ao repositório privado, que responde 404 a quem está de fora.
+- Nenhuma mudança nas verificações: regras, contratos e códigos de saída são os mesmos da 0.1.1.
+
+## 0.1.1 - 2026-09-27
+
+- A CLI responde a `--help`/`-h` e a `--version`/`-v` antes de ler qualquer configuração, com código de saída 0. Na 0.1.0 essas opções caíam no carregamento da configuração e terminavam com código 2, e `-h` era interpretado como caminho de arquivo de configuração.
+- A ajuda lista os comandos de análise e de baseline, as opções que cada um aceita e os três códigos de saída.
+- Sem configuração e sem essas opções, a CLI continua falhando fechada com código 2.
+
 ## 0.1.0 - 2026-09-22
 
 - Primeira versão pública das verificações de contrato e acessibilidade.

package/README.md

@@ -1,12 +1,149 @@
 # @ksmv/ui-checks
 
-Verificações de qualidade para o contrato semântico `--ui-*`, incluindo completude de tokens, contraste, cores literais e evidências calculadas vinculadas à fonte.
+Verificações de qualidade para o contrato semântico `--ui-*` de `@ksmv/ui-react`: completude dos temas, contraste dos pares do contrato, prefixo dos tokens, cores literais fora dos arquivos de tema e evidência calculada vinculada às fontes.
+
+## Antes de depender deste pacote
+
+Os pacotes são publicados no registro público do npm para que as aplicações do próprio mantenedor os instalem sem autenticação. **O repositório de origem é privado.** Não há equipe de suporte, canal público de issues nem compromisso de atendimento a terceiros. Este README é a documentação completa para quem está de fora.
+
+Vulnerabilidades não devem ser publicadas em nenhum canal público. Quem não tem acesso ao repositório relata pelo suporte do próprio npm, que encaminha relatos sobre pacotes publicados: https://www.npmjs.com/support
+
+## Instalação e execução
 
 ```bash
 npm install --save-dev @ksmv/ui-checks
-npx --package @ksmv/ui-checks ksmv-ui-checks ksmv-ui.config.js
+npx ksmv-ui-checks ksmv-ui.config.js
+```
+
+Requer Node.js 22.14 ou superior. `npx ksmv-ui-checks --help` mostra os comandos; sem argumento, a configuração lida é `ksmv-ui.config.js` no diretório atual. `--json` troca o relatório legível por JSON.
+
+## Configuração
+
+```js
+// ksmv-ui.config.js
+import { defineConfig } from "@ksmv/ui-checks/config";
+
+export default defineConfig({
+  contractSource: "@ksmv/ui-react",
+  root: ".",
+  include: ["src/**/*.{css,tsx}"],
+  themes: [
+    { name: "light", files: ["src/theme.css"], selector: '[data-theme="light"]' },
+    { name: "dark", files: ["src/theme.css"], selector: '[data-theme="dark"]' },
+  ],
+  baseline: ".ksmv-ui-baseline.json",
+  failOnUncovered: true,
+});
+```
+
+`contractSource` é obrigatório e explícito:
+
+- `"@ksmv/ui-react"`: use quando a aplicação importa o pacote React. O verificador resolve os contratos da versão realmente instalada, então uma atualização do pacote é verificada contra os contratos novos;
+- `"bundled"`: usa os contratos embutidos neste pacote, apenas para análises que não usam o pacote React, e falha fechado se encontrar essa importação.
+
+O valor de `selector` deve ser **textualmente idêntico** ao seletor escrito no CSS, inclusive nas aspas. O verificador não tenta provar que grafias diferentes são equivalentes.
+
+`include` precisa encontrar arquivos: nenhum arquivo analisado é falha, não sucesso. `exclude` e `suppressions` são opcionais.
+
+## Baseline
+
+`baseline` é opcional. Quando configurado, o arquivo precisa existir. Crie-o somente depois de revisar a análise completa:
+
+```bash
+npx ksmv-ui-checks baseline ksmv-ui.config.js --write --first-seen-version=0.1.2 --owner-role=frontend --reduction-target=2099-12-31
+```
+
+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.
+
+## Códigos de saída
+
+- `0`: análise completa, sem violações novas;
+- `1`: existe violação nova ou regressão em relação à baseline;
+- `2`: configuração inválida, leitura ou operação falhou, nenhum arquivo encontrado, ou há cobertura obrigatória não resolvida.
+
+Trate `2` como falha do pipeline, não como violação comum.
+
+## Evidência calculada
+
+Seletores disjuntos, como `[data-theme="light"]` e `[data-theme="dark"]`, são verificados estaticamente e dispensam evidência. Quando a cascata de um tema legado se sobrepõe, como `.theme` e `.theme.active`, só o navegador sabe o valor final de cada token. Nesse caso o tema declara `computedEvidence`:
+
+```js
+{
+  name: "legacy",
+  files: ["src/theme.css"],
+  selector: ".theme.active",
+  computedEvidence: { file: "artifacts/theme-evidence.json", theme: "legacy" },
+}
 ```
 
-Defina explicitamente `contractSource` como `"bundled"` ou `"@ksmv/ui-react"`. A segunda opção vincula a validação aos contratos da versão do pacote React instalada no consumidor.
+A evidência não é uma exceção manual. O arquivo é recusado, com código `2`, quando:
+
+- `capturedAt` está no futuro;
+- os seletores diferem dos configurados;
+- o hash das fontes diverge, ou seja, o tema mudou depois da captura;
+- 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(...)`.
+
+A captura usa a API pública deste pacote e um navegador à sua escolha. Com Playwright, e a aplicação servida localmente:
+
+```js
+// capture-theme-evidence.mjs
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { computeThemeSourceHash, resolveContractSet } from "@ksmv/ui-checks";
+import { chromium } from "playwright";
+
+// Tudo aqui espelha ksmv-ui.config.js: o mesmo `root`, o mesmo
+// `computedEvidence.file`, os mesmos arquivos de tema, e os mesmos nomes de
+// `computedEvidence.theme` com seus seletores, cada um com uma URL em que o
+// seletor está aplicado. O verificador resolve os caminhos a partir de `root`.
+const root = resolve(".");
+const evidenceFile = "artifacts/theme-evidence.json";
+const themes = {
+  legacy: { selector: ".theme.active", url: "http://localhost:4173/" },
+};
+const files = ["src/theme.css"];
+
+const contracts = await resolveContractSet({ root, source: "@ksmv/ui-react" });
+const tokens = [...new Set([
+  ...contracts.theme.required,
+  ...Object.keys(contracts.theme.derived),
+  ...Object.values(contracts.theme.derived),
+  ...contracts.contrast.pairs.flatMap(({ background, foreground }) => [background, foreground]),
+])];
+
+const browser = await chromium.launch();
+const captured = {};
+for (const [name, { selector, url }] of Object.entries(themes)) {
+  const page = await browser.newPage();
+  await page.goto(url);
+  const values = await page.evaluate(({ selector, tokens }) => {
+    const style = getComputedStyle(document.querySelector(selector));
+    return Object.fromEntries(tokens.map((token) => [token, style.getPropertyValue(token).trim()]));
+  }, { selector, tokens });
+  captured[name] = { selector, tokens: values };
+  await page.close();
+}
+await browser.close();
+
+const target = resolve(root, evidenceFile);
+await mkdir(dirname(target), { recursive: true });
+await writeFile(target, `${JSON.stringify({
+  capturedAt: new Date().toISOString(),
+  contracts: { contrast: contracts.identities.contrast, theme: contracts.identities.theme },
+  schemaVersion: 1,
+  selectors: [...new Set(Object.values(themes).map(({ selector }) => selector))],
+  sourceHash: await computeThemeSourceHash(root, files),
+  themes: captured,
+}, null, 2)}\n`);
+```
+
+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.
+
+## 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`.
+
+## Licença
 
-Licenciado sob Apache-2.0.
+Apache-2.0.

package/dist/cli.js

@@ -6,6 +6,28 @@ import { approveBaselineGrowth, baselineFor, validateBaseline, writeBaselineFile
 import { applyConfiguredSuppressions } from "./governance.js";
 import { formatHumanReport, formatJsonReport, } from "./result.js";
 import { runChecks } from "./scan.js";
+const usage = `Usage:
+  ksmv-ui-checks [config] [--json | --format=json]
+  ksmv-ui-checks baseline [config] --write --first-seen-version=<version>
+      --owner-role=<role> --reduction-target=<YYYY-MM-DD>
+      [--allow-growth --reason-file=<path>]
+  ksmv-ui-checks --help | -h
+  ksmv-ui-checks --version | -v
+
+[config] defaults to ksmv-ui.config.js in the current directory.
+
+Exit codes:
+  0  analysis complete, no new violations
+  1  a new violation, or a regression against the baseline
+  2  invalid configuration, a failed read or operation, no files found,
+     or mandatory coverage left unresolved
+`;
+// The manifest sits one level above both src/ and the published dist/, so the
+// same relative URL resolves in the repository and in an installed package.
+async function packageVersion() {
+    const manifest = JSON.parse(await readFile(new URL("../package.json", import.meta.url), "utf8"));
+    return manifest.version;
+}
 function optionValue(argv, name) {
     return argv
         .find((argument) => argument.startsWith(`--${name}=`))
@@ -94,6 +116,24 @@ async function runBaselineWrite(config, argv) {
     return 0;
 }
 export async function main(argv = process.argv.slice(2)) {
+    // Answered before anything else, and before any configuration is read. In
+    // 0.1.0 both flags fell through to configuration loading and failed with
+    // exit code 2, and `-h`, which does not start with `--`, was taken for a
+    // configuration path.
+    if (argv.some((argument) => argument === "--help" || argument === "-h")) {
+        process.stdout.write(usage);
+        return 0;
+    }
+    if (argv.some((argument) => argument === "--version" || argument === "-v")) {
+        try {
+            process.stdout.write(`${await packageVersion()}\n`);
+            return 0;
+        }
+        catch {
+            process.stderr.write("ksmv-ui-checks: unable to read the package version.\n");
+            return 2;
+        }
+    }
     const useJson = argv.includes("--json") || argv.includes("--format=json");
     const baselineCommand = argv[0] === "baseline";
     const commandArguments = baselineCommand ? argv.slice(1) : argv;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ksmv/ui-checks",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Static and computed quality checks for semantic UI token contracts.",
   "keywords": ["accessibility", "design-tokens", "quality", "static-analysis"],
   "license": "Apache-2.0",
@@ -10,7 +10,8 @@
     ".": { "types": "./dist/index.d.ts", "default": "./dist/index.js" },
     "./config": { "types": "./dist/config.d.ts", "default": "./dist/config.js" },
     "./theme-contract.json": "./dist/theme-contract.json",
-    "./contrast-contract.json": "./dist/contrast-contract.json"
+    "./contrast-contract.json": "./dist/contrast-contract.json",
+    "./package.json": "./package.json"
   },
   "files": ["CHANGELOG.md", "dist/**/*.d.ts", "dist/**/*.js", "dist/*.json"],
   "scripts": {
@@ -27,7 +28,6 @@
   "devDependencies": { "@types/node": "26.6.2", "vitest": "5.0.1" },
   "engines": { "node": ">=22.14" },
   "repository": { "type": "git", "url": "https://github.com/AxisGov/ui.git", "directory": "packages/checks" },
-  "homepage": "https://github.com/AxisGov/ui#readme",
-  "bugs": { "url": "https://github.com/AxisGov/ui/issues" },
+  "homepage": "https://www.npmjs.com/package/@ksmv/ui-checks",
   "publishConfig": { "access": "public", "registry": "https://registry.npmjs.org/" }
 }