kg-ssot 4.17.2 → 4.19.0

package/README.md

@@ -1,85 +1,138 @@
 # kg-ssot
 
-**O leitor JavaScript do contrato do KG-SSOT, o grafo de conhecimento verificável: toda afirmação diz de onde veio,
-quando foi conferida e o que depende dela.**
+[![npm](https://img.shields.io/npm/v/kg-ssot)](https://www.npmjs.com/package/kg-ssot)
+[![license](https://img.shields.io/npm/l/kg-ssot)](https://github.com/marciocar/kg-ssot/blob/main/LICENSE)
+[![node](https://img.shields.io/node/v/kg-ssot)](https://github.com/marciocar/kg-ssot)
 
-Este pacote julga um grafo `.kg.yaml` ou `.kg.json` contra o contrato vigente e devolve o veredito MUST e os avisos
-SHOULD, com os códigos estáveis da suíte de conformidade. Ele traz:
-- o **núcleo do leitor**, sem `fs` e sem processo;
-- os **validadores do contrato pré-compilados**, MUST e SHOULD, que não usam `new Function` nem `eval`. Por isso rodam
-  em motores sem geração de código, como o Hermes do React Native e do Expo, e no Node;
-- os **schemas** do contrato e do veredito.
+**The JavaScript reader for the KG-SSOT contract, the verifiable knowledge graph. Every claim says where it came
+from, when someone verified it, and what depends on it.**
 
-O leitor de referência é o pacote Python [`kg-ssot`](https://pypi.org/project/kg-ssot/). Este leitor passa em todos
-os casos da suíte de conformidade (`latest/`), com o veredito, os códigos e os avisos esperados. O CI confere isso
-pelo pacote instalado a cada mudança no leitor.
+`kg-ssot` checks a `.kg.yaml` or `.kg.json` graph against the current contract (v4). It returns the MUST verdict and
+the SHOULD warnings, with the stable codes of the conformance suite. The package ships:
 
-## Instalar
+- **The reader core**, which uses neither `fs` nor `process`.
+- **Precompiled contract validators**, MUST and SHOULD, that never call `new Function` or `eval`. They run on engines
+  without runtime code generation, like Hermes in React Native and Expo, and on Node.
+- **The schemas** of the contract and of the verdict.
+
+The reference reader is the Python package [`kg-ssot`](https://pypi.org/project/kg-ssot/). This reader passes every
+case in the conformance suite (`latest/`) with the expected verdict, codes, and warnings. On every change to the
+reader, CI runs the whole suite against the installed tarball.
+
+## Install
 
 ```bash
 npm install kg-ssot
 ```
 
-## No código
+On Node, you need version 22.12 or later. The package is ESM and ships its own TypeScript types.
+
+## Use it in code
 
 ```js
 import { verdict } from 'kg-ssot';
 
-verdict(texto);                      // .kg.yaml (o default)
-verdict(texto, { format: 'json' });  // .kg.json
+verdict(text);                      // .kg.yaml (the default)
+verdict(text, { format: 'json' });  // .kg.json
 // { verdict: 'accept', codes: [], warnings: [], detail: '' }
 // { verdict: 'accept', codes: [], warnings: ['yaml.unquoted-date'], detail: '' }
-// { verdict: 'reject', codes: ['form.range.node.impact'], warnings: [], detail: '' }
+// { verdict: 'reject', codes: ['form.range.node.impact', 'form.type.node.impact'], warnings: [], detail: '' }
 ```
 
-- `verdict(texto, { format, corpus })` devolve o veredito no contrato de runner da suíte: `verdict` é `accept` ou
-  `reject`, `codes` traz os códigos MUST e `warnings` os avisos SHOULD, os dois ordenados e sem repetição. Um aviso
-  não reprova: o grafo com aviso continua `accept`.
-- `check(texto, { format, corpus })` devolve só os códigos MUST (vazio quando passa), e `checkWarnings(texto,
-  { format })` só os avisos.
-- `kg-ssot/core` é o núcleo sem o validador, para quem compila o schema por conta própria. `kg-ssot/node` traz os
-  auxiliares de Node, como `corpusIndex(dir)`, que indexa os `.kg.yaml` de um diretório para conferir as
-  `external_edges`. Os schemas ficam em `kg-ssot/spec/*`.
+- `verdict(text, { format, corpus })` returns the verdict in the suite's runner contract. `verdict` is `accept` or
+  `reject`, `codes` lists the MUST codes, and `warnings` lists the SHOULD codes. Both lists are sorted, with no
+  duplicates. A warning never fails a graph: a graph with warnings is still `accept`.
+- `check(text, { format, corpus })` returns only the MUST codes (empty when the graph passes).
+  `checkWarnings(text, { format, corpus })` returns only the warnings.
+- `corpus` lets the reader verify the far end of each `external_edges` entry. It is a
+  `Map<path, Set<nodeId>>`. Build it with `corpusIndex(dir)` from `kg-ssot/node`, or, without a file system, with
+  `indexTexts([[path, text], ...])` from the main entry.
+
+### Entry points
+
+| Import | What you get |
+|---|---|
+| `kg-ssot` | `verdict`, `check`, `checkWarnings`, the precompiled `validateMust` and `validateShould`, and the core |
+| `kg-ssot/core` | The core without the validators, for when you compile the schema yourself (`verdictOf`, `codes`, `warnings`, `parse`, `indexTexts`) |
+| `kg-ssot/must`, `kg-ssot/should` | The precompiled MUST and SHOULD validators alone |
+| `kg-ssot/node` | Node helpers: `corpusIndex(dir)` indexes the `.kg.yaml` and `.kg.json` graphs under a directory (the tracked ones, in a git repository); `compileMust()` compiles the schema with `ajv` at runtime |
+| `kg-ssot/spec/*` | The contract and verdict schemas |
 
-Desde a 4.10.0, este leitor também mede os avisos SHOULD, com os mesmos códigos do leitor de referência em todos os
-casos da suíte, e desde a 4.13.0 trata o `\r` como quebra de linha, como a referência. Desde a 4.11.0, as três construções raras do YAML em que ele divergia da referência (a tag `!` sem
-nome, o `!!timestamp` com texto que não é data e o tab fora de aspas) reprovam nos dois, com casos na suíte. A linha de cada ocorrência e as dicas de correção continuam só no leitor de referência em Python.
+Since 4.10.0, this reader also measures the SHOULD warnings, with the same codes as the reference reader on every
+suite case. Since 4.13.0, it treats `\r` as a line break, like the reference. Since 4.11.0, the three rare YAML
+constructs where it used to diverge from the reference (the unnamed `!` tag, a `!!timestamp` whose text is not a
+date, and a tab outside quotes) now fail in both, and the suite has cases for them. Only the Python reference reader
+reports the line of each finding and the fix hints.
 
-## TypeScript e CommonJS
+## TypeScript and CommonJS
 
-O pacote traz os tipos (`index.d.mts`, `core.d.mts` e `node.d.mts`) e funciona com `moduleResolution` `bundler` ou
-`nodenext`, o que cobre o template TypeScript do Expo. É um pacote ESM. Num projeto CommonJS, o `require('kg-ssot')`
-funciona a partir do Node 22.12, que é o mínimo declarado em `engines`.
+The package ships types (`index.d.mts`, `core.d.mts`, `node.d.mts`, and `validator.d.mts`). It works with
+`moduleResolution` set to `bundler` or `nodenext`, which covers the Expo TypeScript template. It is an ESM package.
+In a CommonJS project, `require('kg-ssot')` works from Node 22.12, the minimum declared in `engines`.
 
-## Na linha de comando
+## Use it from the command line
 
 ```bash
-npx kg-ssot-validate grafo.kg.yaml outro.kg.json
+npx kg-ssot-validate decisions.kg.yaml graph.kg.yaml other.kg.json
 ```
 
 ```text
-PASSA   grafo.kg.yaml
-  AVISO  yaml.unquoted-date
-REPROVA outro.kg.json
-  MUST   form.range.node.impact · integrity.orphan-node
+PASS    decisions.kg.yaml
+PASS    graph.kg.yaml
+  WARNING  yaml.unquoted-date
+FAIL    other.kg.json
+  MUST   form.range.node.impact · form.type.node.impact
+```
+
+The exit code is 0 when every file passes, 1 when any file fails, and 2 on broken input: an unreadable file, invalid
+UTF-8, an unknown option, or a `--corpus` that is not a directory. Warnings never change the exit code.
+
+- `--json` prints one JSON line per file, in the suite's runner contract:
+
+  ```text
+  {"file":"graph.kg.yaml","verdict":"accept","codes":[],"warnings":["yaml.unquoted-date"],"detail":""}
+  {"file":"other.kg.json","verdict":"reject","codes":["form.range.node.impact","form.type.node.impact"],"warnings":[],"detail":""}
+  ```
+
+- `--corpus DIR` verifies the far end of each `external_edges` entry against the `.kg.yaml` and `.kg.json` graphs
+  under `DIR`.
+
+The human output is in English. The CLI speaks Brazilian Portuguese when you set `KG_SSOT_LANG=pt-BR` (or when your
+locale is `pt_BR`):
+
+```bash
+KG_SSOT_LANG=pt-BR npx kg-ssot-validate graph.kg.yaml
 ```
 
-O rc é 0 quando todos passam, 1 quando algum reprova e 2 com arquivo ilegível ou opção desconhecida. Os avisos não
-mudam o rc. Com `--json`, sai uma linha JSON por
-arquivo. Com `--corpus DIR`, a ponta externa das `external_edges` é conferida contra os `.kg.yaml` sob `DIR`.
+The codes and the `--json` output are data, so they never change language. The documentation in Portuguese is in
+[README.pt-BR](https://github.com/marciocar/kg-ssot/blob/main/README.pt-BR.md).
+
+## Use it in a React Native or Expo app
 
-## Num app React Native ou Expo
+The package is ESM, and the main entry imports nothing from Node. Your bundler (Metro, esbuild) resolves the two
+dependencies, `yaml` and the `ajv` runtime. The validators come precompiled, so nothing has to generate code on the
+device. We ran the conformance suite on Hermes, and it returns the same verdicts as Node.
+
+```js
+import { verdict, indexTexts } from 'kg-ssot';
+
+const corpus = indexTexts([['other.kg.yaml', otherText]]); // optional, for external_edges
+const result = verdict(graphText, { corpus });
+if (result.verdict === 'reject') console.warn(result.codes);
+```
 
-O pacote é ESM e a entrada não importa nada do Node. Um bundler (Metro, esbuild) resolve as dependências, `yaml` e o
-runtime do `ajv`. O validador já vem compilado, então nada precisa gerar código no aparelho. O comportamento foi
-medido no Hermes: os mesmos vereditos do Node.
+## Documentation
 
-## Documentação
+- [Manual](https://github.com/marciocar/kg-ssot/tree/main/docs/manual): the format, the contract, the tools, and
+  common problems
+- [Conformance suite](https://github.com/marciocar/kg-ssot/blob/main/spec/conformance/README.md)
+- [Adoption guide](https://github.com/marciocar/kg-ssot/blob/main/ADOPTING.md)
+- [Changelog](https://github.com/marciocar/kg-ssot/blob/main/CHANGELOG.md)
+- [Issues](https://github.com/marciocar/kg-ssot/issues)
 
-- [Manual](https://github.com/marciocar/kg-ssot/tree/main/docs/manual): o formato, o contrato, as ferramentas e os problemas comuns
-- [Suíte de conformidade](https://github.com/marciocar/kg-ssot/blob/main/spec/conformance/README.md)
-- [Guia de adoção](https://github.com/marciocar/kg-ssot/blob/main/ADOPTING.md)
+## License
 
-## Licença
+Apache-2.0. See [`LICENSE`](https://github.com/marciocar/kg-ssot/blob/main/LICENSE) and
+[`NOTICE`](https://github.com/marciocar/kg-ssot/blob/main/NOTICE).
 
-Apache-2.0. Veja `LICENSE` e `NOTICE`.
+Documentação em português: [README.pt-BR](https://github.com/marciocar/kg-ssot/blob/main/README.pt-BR.md).

package/cli.mjs

@@ -4,14 +4,60 @@
 //   kg-ssot-validate <arquivo>... [--json] [--corpus DIR]
 //
 // rc 0 quando todos passam no MUST, 1 quando algum reprova, 2 com entrada quebrada (arquivo ilegível, UTF-8
-// inválido). Os avisos SHOULD saem numa linha AVISO e não mudam o rc. --json imprime uma linha JSON por arquivo, no contrato de runner da suíte. --corpus confere a ponta
+// inválido). Os avisos SHOULD saem numa linha WARNING e não mudam o rc. --json imprime uma linha JSON por arquivo, no contrato de runner da suíte. --corpus confere a ponta
 // externa das external_edges contra os .kg.yaml e .kg.json sob DIR.
+//
+// A saída humana sai em inglês (a língua-fonte) ou na tradução pt-BR, negociada como no kg_i18n do Python:
+// KG_SSOT_LANG, LANGUAGE, LC_ALL, LC_MESSAGES e LANG, parando na primeira definida; C, POSIX e vazio são o inglês.
+// Como no gettext, o LANGUAGE só vale quando o locale efetivo (LC_ALL, LC_MESSAGES, LANG) não é o C.
+// As frases ficam também no catálogo locale/pt_BR/LC_MESSAGES/kg-ssot.po (referência #: packaging/npm/cli.mjs), para o tradutor ter um lugar
+// só. A saída --json é dado e não se traduz.
 import { readFileSync } from 'node:fs';
 
 import { verdict } from './index.mjs';
 import { corpusIndex } from './run.mjs';
 
-const USAGE = 'uso: kg-ssot-validate <arquivo.kg.yaml|arquivo.kg.json>... [--json] [--corpus DIR]\n';
+// A tradução pt-BR (igual às entradas do cli.mjs no kg-ssot.po); a chave é o msgid em inglês.
+const PT_BR = {
+  'usage: kg-ssot-validate <file.kg.yaml|file.kg.json>... [--json] [--corpus DIR]':
+    'uso: kg-ssot-validate <arquivo.kg.yaml|arquivo.kg.json>... [--json] [--corpus DIR]',
+  'BROKEN INPUT': 'ENTRADA QUEBRADA',
+  '--corpus without a directory': '--corpus sem diretório',
+  'unknown option: {option}': 'opção desconhecida: {option}',
+  'corpus {root} is not a directory': 'corpus {root} não é um diretório',
+  PASS: 'PASSA',
+  FAIL: 'REPROVA',
+  ERROR: 'ERRO',
+  WARNING: 'AVISO',
+};
+
+// true quando a língua do ambiente é o português (pt, pt_BR e afins); o inglês e língua sem tradução dão false.
+function wantsPortuguese(vars) {
+  const isC = (v) => { const t = v.trim().split('.')[0].split('@')[0].toLowerCase(); return !t || t === 'c' || t === 'posix'; };
+  const effective = ['LC_ALL', 'LC_MESSAGES', 'LANG'].map((n) => vars[n]).find((v) => v);
+  const localeIsC = !effective || isC(effective);
+  for (const name of ['KG_SSOT_LANG', 'LANGUAGE', 'LC_ALL', 'LC_MESSAGES', 'LANG']) {
+    const value = vars[name];
+    if (!value || (name === 'LANGUAGE' && localeIsC)) continue;
+    for (const raw of name === 'LANGUAGE' ? value.split(':') : [value]) {
+      const tag = raw.trim().split('.')[0].split('@')[0].replace(/-/g, '_').toLowerCase();
+      if (!tag || tag === 'c' || tag === 'posix') return false;
+      const lang = tag.split('_')[0];
+      if (lang === 'pt') return true;
+      if (lang === 'en') return false;
+    }
+    return false; // a variável definida decide, mesmo sem tradução: o inglês
+  }
+  return false;
+}
+
+const TABLE = wantsPortuguese(process.env) ? PT_BR : {};
+const _ = (msgid, vals = {}) =>
+  (TABLE[msgid] ?? msgid).replace(/\{(\w+)\}/g, (m, k) => (k in vals ? String(vals[k]) : m));
+// o rótulo da linha do arquivo, com a coluna do nome alinhada
+const label = (msgid) => `${_(msgid).padEnd(7)} `;
+
+const USAGE = `${_('usage: kg-ssot-validate <file.kg.yaml|file.kg.json>... [--json] [--corpus DIR]')}\n`;
 const args = process.argv.slice(2);
 let json = false;
 let corpusDir = null;
@@ -25,12 +71,12 @@ for (let i = 0; i < args.length; i += 1) {
   else if (a === '--corpus') {
     corpusDir = args[++i];
     if (!corpusDir) {
-      process.stdout.write(`ENTRADA QUEBRADA  --corpus sem diretório\n${USAGE}`);
+      process.stdout.write(`${_('BROKEN INPUT')}  ${_('--corpus without a directory')}\n${USAGE}`);
       process.exit(2);
     }
   } else if (a === '--') files.push(...args.slice(i + 1)), (i = args.length);
   else if (a.startsWith('-')) {
-    process.stdout.write(`ENTRADA QUEBRADA  opção desconhecida: ${a}\n${USAGE}`);
+    process.stdout.write(`${_('BROKEN INPUT')}  ${_('unknown option: {option}', { option: a })}\n${USAGE}`);
     process.exit(2);
   } else files.push(a);
 }
@@ -43,7 +89,8 @@ let corpus = null;
 try {
   corpus = corpusDir ? corpusIndex(corpusDir) : null;
 } catch (exc) {
-  process.stdout.write(`ENTRADA QUEBRADA  ${exc.message}\n`);
+  const msg = exc?.kgMsgid ? _(exc.kgMsgid, exc.kgArgs) : exc?.message;
+  process.stdout.write(`${_('BROKEN INPUT')}  ${msg}\n`);
   process.exit(2);
 }
 for (const file of files) {
@@ -57,9 +104,9 @@ for (const file of files) {
   if (out.verdict === 'error') rc = 2;
   else if (out.verdict === 'reject' && rc === 0) rc = 1;
   if (json) process.stdout.write(`${JSON.stringify({ file, ...out })}\n`);
-  else if (out.verdict === 'accept') process.stdout.write(`PASSA   ${file}\n`);
-  else if (out.verdict === 'reject') process.stdout.write(`REPROVA ${file}\n  MUST   ${out.codes.join(' · ')}\n`);
-  else process.stdout.write(`ERRO    ${file}\n  ${out.detail}\n`);
-  if (!json && out.warnings?.length) process.stdout.write(`  AVISO  ${out.warnings.join(' · ')}\n`);
+  else if (out.verdict === 'accept') process.stdout.write(`${label('PASS')}${file}\n`);
+  else if (out.verdict === 'reject') process.stdout.write(`${label('FAIL')}${file}\n  MUST   ${out.codes.join(' · ')}\n`);
+  else process.stdout.write(`${label('ERROR')}${file}\n  ${out.detail}\n`);
+  if (!json && out.warnings?.length) process.stdout.write(`  ${_('WARNING')}  ${out.warnings.join(' · ')}\n`);
 }
 process.exit(rc);

package/kg.mjs

@@ -493,7 +493,8 @@ export function formCodes(err, doc) {
   }
   scope = path.length >= 2 ? scopeOf(path) : 'top';
   if (path.length && typeof path[path.length - 1] === 'number') {
-    const lead = scope === 'top' ? path.slice(0, -1).filter(notIndex) : [];
+    // num item de lista dentro do nó (x_term.labels, v4.11), o caminho até a lista entra no código
+    const lead = scope === 'top' ? path.slice(0, -1).filter(notIndex) : path.length > 2 ? innerNames(path.slice(0, -1)) : [];
     return [`form.${kind}.${scope}.${[...lead, 'item'].join('.')}`];
   }
   const names = scope !== 'top' ? innerNames(path) : path.filter(notIndex);