@hyperfixi/testing-framework 2.7.2 → 2.9.0

package/src/vocab/cli.ts

@@ -0,0 +1,196 @@
+/**
+ * Vocab-consistency CLI (Arc A — docs-internal/HANDOFF_vocab-consistency.md).
+ *
+ *   npx tsx src/vocab/cli.ts validate [--language xx[,yy]] [--check V1,V4]
+ *                                     [--json [path]] [--waivers path] [--warn-only]
+ *   npx tsx src/vocab/cli.ts dump [keywords|markers|events] [--concept toggle]
+ *                                 [--language xx[,yy]] [--format md|tsv|json]
+ *
+ * Exit codes (validate): 0 = no unwaived error-tier findings (or --warn-only);
+ * 1 = unwaived errors; 2 = refused (stale dist).
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import type { CheckId } from './types';
+import { loadWaivers, buildLedger, printLedger } from './report';
+import type { DumpFormat, DumpTarget } from './dump';
+
+// --- stale-dist guard (same pattern as the multilingual CLI) -----------------
+// The model loads @lokascript/semantic and @lokascript/i18n through their
+// package entries, i.e. their dist/. A stale dist scores code that differs
+// from the checkout, so refuse to run rather than report vacuously.
+
+const DIST_GUARD_PACKAGES = ['intent', 'framework', 'semantic', 'i18n'];
+
+function hasNewerTs(dir: string, builtAt: number): boolean {
+  if (!fs.existsSync(dir)) return false;
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const p = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (hasNewerTs(p, builtAt)) return true;
+    } else if (entry.name.endsWith('.ts') && fs.statSync(p).mtimeMs > builtAt) {
+      return true;
+    }
+  }
+  return false;
+}
+
+function findStaleDists(): string[] {
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  const packagesRoot = path.resolve(here, '../../..');
+  const stale: string[] = [];
+  for (const name of DIST_GUARD_PACKAGES) {
+    const srcDir = path.join(packagesRoot, name, 'src');
+    const marker = path.join(packagesRoot, name, 'dist', 'index.js');
+    if (!fs.existsSync(marker) || hasNewerTs(srcDir, fs.statSync(marker).mtimeMs)) {
+      stale.push(name);
+    }
+  }
+  return stale;
+}
+
+// --- arg parsing --------------------------------------------------------------
+
+interface Args {
+  command: 'validate' | 'dump';
+  languages?: string[] | undefined;
+  checks?: CheckId[] | undefined;
+  json?: string | true | undefined;
+  waivers: string;
+  warnOnly: boolean;
+  target: DumpTarget;
+  concept?: string | undefined;
+  format: DumpFormat;
+}
+
+const VALID_CHECKS: readonly CheckId[] = ['V1', 'V1b', 'V2', 'V3', 'V3b', 'V3c', 'V4'];
+
+function parseArgs(argv: string[]): Args {
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  const args: Args = {
+    command: 'validate',
+    waivers: path.resolve(here, '../../vocab-waivers.json'),
+    warnOnly: false,
+    target: 'keywords',
+    format: 'md',
+  };
+  const rest = [...argv];
+  while (rest.length > 0) {
+    const a = rest.shift()!;
+    switch (a) {
+      case 'validate':
+        args.command = 'validate';
+        break;
+      case 'dump':
+        args.command = 'dump';
+        break;
+      case 'keywords':
+      case 'markers':
+      case 'events':
+        args.target = a;
+        break;
+      case '--language':
+      case '-l':
+      case '--languages':
+        args.languages = (rest.shift() ?? '').split(',').filter(Boolean);
+        break;
+      case '--check':
+      case '--checks': {
+        const ids = (rest.shift() ?? '').split(',').filter(Boolean) as CheckId[];
+        for (const id of ids) {
+          if (!VALID_CHECKS.includes(id))
+            throw new Error(`unknown check "${id}" (valid: ${VALID_CHECKS.join(', ')})`);
+        }
+        args.checks = ids;
+        break;
+      }
+      case '--json':
+        args.json = rest[0] && !rest[0].startsWith('-') ? rest.shift()! : true;
+        break;
+      case '--waivers':
+        args.waivers = path.resolve(rest.shift() ?? args.waivers);
+        break;
+      case '--warn-only':
+        args.warnOnly = true;
+        break;
+      case '--concept':
+        args.concept = rest.shift();
+        break;
+      case '--format': {
+        const f = rest.shift() as DumpFormat;
+        if (!['md', 'tsv', 'json'].includes(f)) throw new Error(`unknown format "${f}"`);
+        args.format = f;
+        break;
+      }
+      case '--help':
+      case '-h':
+        console.log(
+          'vocab cli — validate (V1–V4 cross-surface consistency) | dump (concept × language table)\n' +
+            'see file header for flags'
+        );
+        process.exit(0);
+        break;
+      default:
+        throw new Error(`unknown argument "${a}"`);
+    }
+  }
+  return args;
+}
+
+// --- main ----------------------------------------------------------------------
+
+async function main(): Promise<void> {
+  const args = parseArgs(process.argv.slice(2));
+
+  const stale = findStaleDists();
+  if (stale.length > 0) {
+    console.error(
+      `REFUSING to run: stale dist for ${stale.join(', ')} (src newer than dist/index.js).\n` +
+        `Rebuild first: npm run check:fresh   (or npm run build --prefix packages/<pkg>)`
+    );
+    process.exit(2);
+  }
+
+  // Deferred so the guard runs before the package entries are loaded.
+  const { loadVocabModel } = await import('./model');
+  const model = loadVocabModel(args.languages);
+
+  if (args.command === 'dump') {
+    const { renderDump } = await import('./dump');
+    console.log(renderDump(model, args.target, args.format, args.concept));
+    return;
+  }
+
+  const { runChecks } = await import('./checks');
+  const findings = runChecks(model, args.checks);
+  const waivers = loadWaivers(args.waivers);
+  const ledger = buildLedger(findings, waivers);
+
+  printLedger(ledger);
+
+  if (args.json) {
+    const target = args.json === true ? undefined : args.json;
+    const payload = JSON.stringify(ledger, null, 2);
+    if (target) {
+      fs.writeFileSync(target, payload);
+      console.log(`ledger written: ${target}`);
+    } else {
+      console.log(payload);
+    }
+  }
+
+  if (ledger.unwaivedErrors > 0 && !args.warnOnly) {
+    console.error(`\n✗ ${ledger.unwaivedErrors} unwaived error(s)`);
+    process.exit(1);
+  }
+  console.log(
+    '\n✓ vocab consistency: no unwaived errors' + (args.warnOnly ? ' enforced (--warn-only)' : '')
+  );
+}
+
+main().catch(err => {
+  console.error(err instanceof Error ? err.message : err);
+  process.exit(2);
+});

package/src/vocab/dump.ts

@@ -0,0 +1,80 @@
+/**
+ * `dump` — one concept × language table over the loaded vocab model, so a
+ * translation can be reviewed in a single view instead of five files.
+ */
+
+import type { VocabModel } from './types';
+
+export type DumpTarget = 'keywords' | 'markers' | 'events';
+export type DumpFormat = 'md' | 'tsv' | 'json';
+
+interface Table {
+  header: string[];
+  rows: string[][];
+}
+
+function buildTable(model: VocabModel, target: DumpTarget, conceptFilter?: string): Table {
+  const langs = model.languages.map(l => l.language);
+  const header = [
+    target === 'markers' ? 'role' : target === 'events' ? 'event' : 'concept',
+    ...langs,
+  ];
+
+  const keys = new Set<string>();
+  for (const lang of model.languages) {
+    if (target === 'keywords') Object.keys(lang.keywords).forEach(k => keys.add(k));
+    else if (target === 'markers') Object.keys(lang.roleMarkers).forEach(k => keys.add(k));
+    else for (const english of Object.values(lang.eventTranslations ?? {})) keys.add(english);
+  }
+
+  const rows: string[][] = [];
+  for (const key of [...keys].sort()) {
+    if (conceptFilter && key !== conceptFilter) continue;
+    const row = [key];
+    for (const lang of model.languages) {
+      if (target === 'keywords') {
+        const e = lang.keywords[key];
+        row.push(
+          e ? e.primary + (e.alternatives?.length ? ` (${e.alternatives.join('|')})` : '') : ''
+        );
+      } else if (target === 'markers') {
+        const e = lang.roleMarkers[key];
+        row.push(
+          e ? e.primary + (e.alternatives?.length ? ` (${e.alternatives.join('|')})` : '') : ''
+        );
+      } else {
+        const natives = Object.entries(lang.eventTranslations ?? {})
+          .filter(([, english]) => english === key)
+          .map(([native]) => native);
+        row.push(natives.join('|'));
+      }
+    }
+    rows.push(row);
+  }
+  return { header, rows };
+}
+
+export function renderDump(
+  model: VocabModel,
+  target: DumpTarget,
+  format: DumpFormat,
+  conceptFilter?: string
+): string {
+  const { header, rows } = buildTable(model, target, conceptFilter);
+  if (format === 'json') {
+    return JSON.stringify(
+      rows.map(r => Object.fromEntries(header.map((h, i) => [h, r[i]]))),
+      null,
+      2
+    );
+  }
+  if (format === 'tsv') {
+    return [header.join('\t'), ...rows.map(r => r.join('\t'))].join('\n');
+  }
+  const md = [
+    `| ${header.join(' | ')} |`,
+    `| ${header.map(() => '---').join(' | ')} |`,
+    ...rows.map(r => `| ${r.map(c => c.replace(/\|/g, '\\|')).join(' | ')} |`),
+  ];
+  return md.join('\n');
+}

package/src/vocab/model.ts

@@ -0,0 +1,110 @@
+/**
+ * Loads the real five-surface vocab model.
+ *
+ * S1/S2/S5 come from `@lokascript/semantic`, S3/S4 from `@lokascript/i18n` —
+ * all via the package entries, so a stale `dist/` scores code that differs
+ * from the checkout (the CLI guards this before loading).
+ */
+
+import {
+  KNOWN_PROFILES,
+  commandSchemas,
+  getTokenizer,
+  eventNameTranslations,
+  getSOVEventMarkers,
+  getEventLocalizationDenylist,
+} from '@lokascript/semantic';
+import { dictionaries, profiles as grammarProfiles } from '@lokascript/i18n';
+import type { LangVocab, VocabModel } from './types';
+
+export function loadVocabModel(languageFilter?: readonly string[]): VocabModel {
+  const codes = Object.keys(KNOWN_PROFILES).filter(
+    code => !languageFilter || languageFilter.includes(code)
+  );
+  const sovEventMarkers = getSOVEventMarkers();
+  const eventDenylists = getEventLocalizationDenylist();
+
+  const languages: LangVocab[] = [];
+  for (const code of codes) {
+    const profile = KNOWN_PROFILES[code];
+    if (!profile) continue;
+
+    const keywords: LangVocab['keywords'] = {};
+    for (const [concept, t] of Object.entries(profile.keywords ?? {})) {
+      keywords[concept] = { primary: t.primary, alternatives: t.alternatives };
+    }
+
+    const roleMarkers: LangVocab['roleMarkers'] = {};
+    for (const [role, m] of Object.entries(profile.roleMarkers ?? {})) {
+      if (m) roleMarkers[role] = { primary: m.primary, alternatives: m.alternatives };
+    }
+
+    const schemaMarkers: LangVocab['schemaMarkers'] = [];
+    for (const [action, schema] of Object.entries(commandSchemas)) {
+      for (const spec of schema.roles ?? []) {
+        const override = spec.markerOverride?.[code];
+        if (override) {
+          schemaMarkers.push({ action, role: spec.role, marker: override, kind: 'override' });
+        }
+        for (const variant of spec.markerVariants?.[code] ?? []) {
+          if (variant)
+            schemaMarkers.push({ action, role: spec.role, marker: variant, kind: 'variant' });
+        }
+      }
+    }
+
+    const grammar = (
+      grammarProfiles as Record<string, { markers?: readonly unknown[] } | undefined>
+    )[code];
+    const grammarMarkers: LangVocab['grammarMarkers'] = [];
+    for (const raw of grammar?.markers ?? []) {
+      const m = raw as {
+        form: string;
+        role: string;
+        position?: string;
+        alternatives?: readonly string[];
+      };
+      if (m.form)
+        grammarMarkers.push({
+          form: m.form,
+          role: m.role,
+          position: m.position,
+          alternatives: m.alternatives,
+        });
+    }
+
+    const dictionary = (
+      dictionaries as unknown as Record<string, Record<string, Record<string, string>> | undefined>
+    )[code];
+
+    const tokenizer = getTokenizer(code);
+
+    languages.push({
+      language: code,
+      keywords,
+      roleMarkers,
+      schemaMarkers,
+      dictionary,
+      grammarMarkers,
+      eventTranslations: eventNameTranslations[code],
+      sovEventMarkers: sovEventMarkers[code],
+      classify: tokenizer ? (word: string) => tokenizer.classifyToken(word) : undefined,
+      normalizeWord: tokenizer
+        ? (word: string) => {
+            // Parse-authority resolution: what the keyword table turns this
+            // word into. Only trustworthy when the word survives as ONE token
+            // (a shattered compound resolves to its first fragment — that is
+            // the broken-listener class itself, not a resolution).
+            const stream = tokenizer.tokenize(word) as {
+              tokens?: readonly { normalized?: string }[];
+            };
+            const toks = stream.tokens ?? [];
+            return toks.length === 1 ? toks[0]?.normalized : undefined;
+          }
+        : undefined,
+      eventDenylist: eventDenylists[code],
+    });
+  }
+
+  return { languages };
+}

package/src/vocab/report.ts

@@ -0,0 +1,120 @@
+/**
+ * Waiver application + console/JSON reporting for the vocab checks.
+ *
+ * Waivers apply to error-tier findings only (warn/info never gate), keyed by
+ * `check|language|key` with a mandatory reason. A waiver that matches nothing
+ * is stale and reported so the file cannot rot silently.
+ */
+
+import * as fs from 'node:fs';
+import type { Finding, Tier, Waiver } from './types';
+
+export interface Ledger {
+  generatedAt: string;
+  totals: Record<Tier, number>;
+  unwaivedErrors: number;
+  staleWaivers: string[];
+  findings: Array<Finding & { waived?: string | undefined }>;
+}
+
+export function loadWaivers(path: string): Waiver[] {
+  if (!fs.existsSync(path)) return [];
+  const raw = JSON.parse(fs.readFileSync(path, 'utf8')) as Waiver[];
+  for (const w of raw) {
+    if (!w.key || !w.reason) throw new Error(`waiver missing key or reason: ${JSON.stringify(w)}`);
+  }
+  return raw;
+}
+
+/**
+ * A waiver key is `check|language|key` where any segment may be `*` — a class
+ * waiver covering every finding in that class (e.g. `V1|*|*` = "all V1s,
+ * pending Arc B"). Exact keys still work; first matching waiver wins.
+ */
+function waiverMatches(waiverKey: string, f: Finding): boolean {
+  const parts = waiverKey.split('|');
+  if (parts.length !== 3) return false;
+  const [c, l, k] = parts;
+  return (
+    (c === '*' || c === f.check) && (l === '*' || l === f.language) && (k === '*' || k === f.key)
+  );
+}
+
+export function buildLedger(findings: Finding[], waivers: Waiver[]): Ledger {
+  const used = new Set<string>();
+
+  const annotated: Array<Finding & { waived?: string | undefined }> = findings.map(f => {
+    const w = f.tier === 'error' ? waivers.find(w => waiverMatches(w.key, f)) : undefined;
+    if (w) used.add(w.key);
+    return w ? { ...f, waived: w.reason } : { ...f };
+  });
+
+  const totals: Record<Tier, number> = { error: 0, warn: 0, info: 0 };
+  for (const f of annotated) totals[f.tier]++;
+
+  return {
+    generatedAt: new Date().toISOString(),
+    totals,
+    unwaivedErrors: annotated.filter(f => f.tier === 'error' && !f.waived).length,
+    staleWaivers: waivers.map(w => w.key).filter(k => !used.has(k)),
+    findings: annotated,
+  };
+}
+
+const PRINT_CAPS: Record<Tier, number> = { error: 50, warn: 20, info: 0 };
+
+export function printLedger(ledger: Ledger): void {
+  const { totals } = ledger;
+  console.log('Vocab consistency — cross-surface check (V1–V4)');
+  console.log(
+    `  errors: ${totals.error} (${ledger.unwaivedErrors} unwaived) · warns: ${totals.warn} · infos: ${totals.info}\n`
+  );
+
+  // Per-check × per-language matrix of error/warn counts.
+  const cells = new Map<string, { error: number; warn: number; info: number }>();
+  for (const f of ledger.findings) {
+    const key = `${f.check}|${f.language}`;
+    const cell = cells.get(key) ?? { error: 0, warn: 0, info: 0 };
+    cell[f.tier]++;
+    cells.set(key, cell);
+  }
+  const checks = [...new Set(ledger.findings.map(f => f.check))].sort();
+  const langs = [...new Set(ledger.findings.map(f => f.language))].sort();
+  if (checks.length > 0) {
+    console.log(`  ${'lang'.padEnd(6)}${checks.map(c => c.padEnd(14)).join('')}`);
+    for (const lang of langs) {
+      const row = checks
+        .map(c => {
+          const cell = cells.get(`${c}|${lang}`);
+          if (!cell) return '—'.padEnd(14);
+          return `${cell.error}e/${cell.warn}w/${cell.info}i`.padEnd(14);
+        })
+        .join('');
+      console.log(`  ${lang.padEnd(6)}${row}`);
+    }
+    console.log('');
+  }
+
+  for (const tier of ['error', 'warn'] as const) {
+    const cap = PRINT_CAPS[tier];
+    const list = ledger.findings.filter(f => f.tier === tier && !f.waived);
+    if (list.length === 0) continue;
+    console.log(
+      `  ${tier.toUpperCase()}S${list.length > cap ? ` (first ${cap} of ${list.length} — full list via --json)` : ''}:`
+    );
+    for (const f of list.slice(0, cap)) {
+      console.log(
+        `    [${f.check}|${f.language}|${f.key}] ${f.message}${f.source ? ` (${f.source})` : ''}`
+      );
+    }
+    console.log('');
+  }
+
+  const waived = ledger.findings.filter(f => f.waived);
+  if (waived.length > 0) console.log(`  waived errors: ${waived.length}`);
+  if (ledger.staleWaivers.length > 0) {
+    console.log(
+      `  STALE waivers (match no finding — remove them): ${ledger.staleWaivers.join(', ')}`
+    );
+  }
+}

package/src/vocab/types.ts

@@ -0,0 +1,100 @@
+/**
+ * Vocab-consistency model + finding types (Arc A — HANDOFF_vocab-consistency.md).
+ *
+ * Checks operate on a `VocabModel`, not on the packages directly, so tests can
+ * seed synthetic disagreements without importing the real surfaces.
+ */
+
+export type Tier = 'error' | 'warn' | 'info';
+
+export type CheckId = 'V1' | 'V1b' | 'V2' | 'V3' | 'V3b' | 'V3c' | 'V4';
+
+export interface Finding {
+  check: CheckId;
+  tier: Tier;
+  language: string;
+  /** Stable identifier within (check, language) — concept, role, event or word. */
+  key: string;
+  message: string;
+  /** Where the offending entry lives (e.g. `schema.bind.source`, `grammar.destination`). */
+  source?: string | undefined;
+}
+
+/** Stable waiver key: check|language|key. */
+export function findingKey(f: Pick<Finding, 'check' | 'language' | 'key'>): string {
+  return `${f.check}|${f.language}|${f.key}`;
+}
+
+export interface Waiver {
+  key: string;
+  reason: string;
+}
+
+/** One language's view over the five authoring surfaces. */
+export interface LangVocab {
+  language: string;
+  /** S1 — semantic profile keywords: concept → forms. */
+  keywords: Record<string, { primary: string; alternatives?: readonly string[] | undefined }>;
+  /** S1 — semantic profile role markers: role → forms. */
+  roleMarkers: Record<string, { primary: string; alternatives?: readonly string[] | undefined }>;
+  /** S2 — command-schema per-language markers (flattened over all schemas/roles). */
+  schemaMarkers: Array<{
+    action: string;
+    role: string;
+    marker: string;
+    kind: 'override' | 'variant';
+  }>;
+  /** S3 — i18n dictionary: category → English key → native value. Absent if the language has no dictionary. */
+  dictionary?: Record<string, Record<string, string>> | undefined;
+  /** S4 — i18n grammar-profile markers (render side). */
+  grammarMarkers: Array<{
+    form: string;
+    role: string;
+    position?: string | undefined;
+    alternatives?: readonly string[] | undefined;
+  }>;
+  /** S5b — native event word → English event name. Absent for the 11 uncovered languages. */
+  eventTranslations?: Record<string, string> | undefined;
+  /**
+   * Surface #6 — hardcoded SOV event markers from `semantic-parser.ts`
+   * (`getSOVEventMarkers()`): parse-side event-marker knowledge that lives in
+   * neither profiles, schemas, nor grammar profiles. Feeds V2's parse-side
+   * union for the `event` role only.
+   */
+  sovEventMarkers?: readonly string[] | undefined;
+  /** S5a — word-level tokenizer classification. Absent if no tokenizer registered. */
+  classify?: ((word: string) => string) | undefined;
+  /**
+   * S5a — tokenizer keyword-table normalization for a SINGLE word: what the
+   * parse side actually resolves the word to (undefined when the word doesn't
+   * tokenize as exactly one token, or has no normalization). The parse
+   * authority for V3c — S5b can be aspirational (Batch 2).
+   */
+  normalizeWord?: ((word: string) => string | undefined) | undefined;
+  /**
+   * English events INTENTIONALLY kept English for this language (the
+   * test-locked `eventLocalizationDenylist` from `@lokascript/semantic`):
+   * a dict event word for a denylisted pair is expected not to round-trip —
+   * V3c must not flag it.
+   */
+  eventDenylist?: ReadonlySet<string> | undefined;
+}
+
+export interface VocabModel {
+  languages: LangVocab[];
+}
+
+/** NFC + lowercase + trim — the comparison normal form for every check. */
+export function norm(s: string): string {
+  return s.normalize('NFC').toLowerCase().trim();
+}
+
+export function formSet(entry: {
+  primary: string;
+  alternatives?: readonly string[] | undefined;
+}): Set<string> {
+  const out = new Set<string>();
+  if (entry.primary) out.add(norm(entry.primary));
+  for (const a of entry.alternatives ?? []) if (a) out.add(norm(a));
+  return out;
+}