@lokascript/framework 4.6.0 → 4.8.0

package/src/testing/gate/lint/rules/renderer-coherence.ts

@@ -0,0 +1,100 @@
+/**
+ * R10: Renderer-table coherence (opt-in).
+ *
+ * Some domains ship a natural-language renderer that maintains its own
+ * per-language keyword/marker tables separate from the profile data. This
+ * rule — when the domain passes `input.renderer` — asserts that:
+ *   - Every `commandKeywords[action][lang]` matches `profile.keywords[action].primary`
+ *     for that language.
+ *   - Every `markers[name][lang]` appears as a markerOverride value somewhere
+ *     in the schemas for that language (can't pin to a specific role since
+ *     renderer marker names are arbitrary labels).
+ *
+ * Warnings only. Domains without `input.renderer` get a no-op pass — this
+ * rule is inherently opt-in because not every domain has round-trip
+ * rendering and not every renderer uses the same table shape.
+ *
+ * Catches the exact drift we fixed earlier this session: domain-sql's
+ * Turkish source marker was `dan` in the `get` schema but `den` in the
+ * renderer's MARKERS table. Had this rule existed, it would have warned
+ * the moment `get` was added with the wrong Turkish variant.
+ */
+
+import type { LintFinding, LintRule } from '../types';
+
+const RULE_ID = 'renderer-coherence';
+
+export const rendererCoherenceRule: LintRule = input => {
+  if (!input.renderer) return [];
+  const findings: LintFinding[] = [];
+
+  // commandKeywords ↔ profile primaries
+  for (const [action, langMap] of Object.entries(input.renderer.commandKeywords)) {
+    for (const [lang, rendererWord] of Object.entries(langMap)) {
+      const profile = input.profiles.find(p => p.code === lang);
+      if (!profile) continue; // lang not registered; R6 handles that
+      const profileEntry = profile.keywords[action];
+      if (!profileEntry) {
+        findings.push({
+          rule: RULE_ID,
+          severity: 'warning',
+          message: `renderer has '${action}' keyword for ${lang} ("${rendererWord}") but profile has no entry for that action`,
+          context: { domain: input.name, lang, action, rendererWord },
+        });
+        continue;
+      }
+      const profilePrimary = profileEntry.primary;
+      const profileAlts = profileEntry.alternatives ?? [];
+      if (rendererWord !== profilePrimary && !profileAlts.includes(rendererWord)) {
+        findings.push({
+          rule: RULE_ID,
+          severity: 'warning',
+          message: `renderer '${action}' keyword for ${lang} is "${rendererWord}" but profile has primary="${profilePrimary}"${profileAlts.length ? ` (alternatives: ${profileAlts.join(', ')})` : ''}`,
+          context: {
+            domain: input.name,
+            lang,
+            action,
+            rendererWord,
+            profilePrimary,
+          },
+        });
+      }
+    }
+  }
+
+  // markers ↔ schema markerOverride values (loose check — any role in any
+  // schema for that lang must have this marker value somewhere)
+  const markerByLang = new Map<string, Set<string>>();
+  for (const schema of input.schemas) {
+    for (const role of schema.roles) {
+      if (!role.markerOverride) continue;
+      for (const [lang, word] of Object.entries(role.markerOverride)) {
+        const set = markerByLang.get(lang) ?? new Set<string>();
+        set.add(word);
+        markerByLang.set(lang, set);
+      }
+    }
+  }
+
+  for (const [markerName, langMap] of Object.entries(input.renderer.markers)) {
+    for (const [lang, rendererWord] of Object.entries(langMap)) {
+      const schemaMarkers = markerByLang.get(lang);
+      if (!schemaMarkers) continue; // lang has no markerOverride anywhere; skip
+      if (!schemaMarkers.has(rendererWord)) {
+        findings.push({
+          rule: RULE_ID,
+          severity: 'warning',
+          message: `renderer marker "${markerName}" in ${lang} is "${rendererWord}" but no schema role has that markerOverride value — likely drift`,
+          context: {
+            domain: input.name,
+            lang,
+            markerName,
+            rendererWord,
+          },
+        });
+      }
+    }
+  }
+
+  return findings;
+};

package/src/testing/gate/lint/rules/schema-rules.ts

@@ -0,0 +1,35 @@
+/**
+ * Schema-structure rules (R1, R2).
+ *
+ * Delegates to the validator the input brings (`DomainLintInput.validateSchema`): the domains pass
+ * `@lokascript/semantic`'s `validateCommandSchema`, whose checks are already solid. We only surface its
+ * error- and warning-level items; notes are dropped to keep linter output focused.
+ */
+
+import type { LintFinding, LintRule } from '../types';
+
+const RULE_ID = 'schema-structure';
+
+export const schemaStructureRule: LintRule = input => {
+  const findings: LintFinding[] = [];
+  if (!input.validateSchema) return findings;
+
+  for (const schema of input.schemas) {
+    const result = input.validateSchema(schema);
+    for (const item of result.items) {
+      if (item.severity === 'note') continue; // skip notes — not actionable at lint time
+      findings.push({
+        rule: `${RULE_ID}:${item.code}`,
+        severity: item.severity,
+        message: `[${schema.action}] ${item.message}`,
+        context: {
+          domain: input.name,
+          action: String(schema.action),
+          code: item.code,
+        },
+      });
+    }
+  }
+
+  return findings;
+};

package/src/testing/gate/lint/types.ts

@@ -0,0 +1,83 @@
+/**
+ * Core types for the domain linter.
+ */
+
+import type { CommandSchema } from '../../../schema';
+import type { LanguageTokenizer } from '../../../core/types';
+import type { PatternGenLanguageProfile } from '../../../generation/pattern-generator';
+
+export type Severity = 'error' | 'warning' | 'note';
+
+export interface LintFinding {
+  readonly rule: string;
+  readonly severity: Severity;
+  readonly message: string;
+  /** Optional structured context: domain, language code, command action, role name, etc. */
+  readonly context?: Record<string, string | number | boolean>;
+}
+
+export interface LintResult {
+  readonly domain: string;
+  readonly findings: readonly LintFinding[];
+  /** Count helpers — derived from findings. */
+  readonly errorCount: number;
+  readonly warningCount: number;
+}
+
+/**
+ * Optional renderer metadata for R10 (renderer-coherence check).
+ * Domains without a renderer or without standard table shape omit this field.
+ */
+export interface RendererTables {
+  /** Keyed by action name → lang code → keyword. */
+  readonly commandKeywords: Record<string, Record<string, string>>;
+  /** Keyed by marker name → lang code → marker word. */
+  readonly markers: Record<string, Record<string, string>>;
+}
+
+/**
+ * Matcher for an acknowledged-but-unfixed finding. Each entry is an object
+ * whose fields are compared against the finding's rule + context. A finding
+ * matches a waiver if every field in the waiver matches the corresponding
+ * field on the finding (or finding.context). Matched findings are dropped
+ * from the returned result entirely.
+ *
+ * Use sparingly — waivers are real debt that should have a plan to resolve.
+ */
+export interface LintWaiver {
+  readonly rule: string;
+  readonly reason: string; // human-readable; not matched against — for audit
+  readonly matches?: Record<string, string | number | boolean>;
+}
+
+export interface DomainLintInput {
+  readonly name: string;
+  readonly schemas: readonly CommandSchema[];
+  readonly profiles: readonly PatternGenLanguageProfile[];
+  readonly tokenizers: Readonly<Record<string, LanguageTokenizer>>;
+  readonly renderer?: RendererTables;
+  readonly waivers?: readonly LintWaiver[];
+  /**
+   * The schema validator R1/R2 (schema-structure) run. The domains pass `@lokascript/semantic`'s
+   * `validateCommandSchema`; framework cannot import semantic, which depends on it. Without one, the
+   * rule finds nothing.
+   */
+  readonly validateSchema?: SchemaValidator;
+}
+
+/** One finding of a schema validator. */
+export interface SchemaValidationFinding {
+  readonly code: string;
+  readonly severity: Severity;
+  readonly message: string;
+}
+
+/** A schema validator: `@lokascript/semantic`'s `validateCommandSchema` has this shape. */
+export type SchemaValidator = (schema: CommandSchema) => {
+  readonly items: readonly SchemaValidationFinding[];
+};
+
+/**
+ * A single rule is a pure function producing findings.
+ */
+export type LintRule = (input: DomainLintInput) => LintFinding[];

package/src/testing/gate/round-trip.test.ts

@@ -0,0 +1,208 @@
+/**
+ * The round-trip gate kit on framework's SQL fixture DSL: the commands it writes,
+ * the outcomes it reads (an unknown word read into a role among them), and the
+ * baseline and snapshot it compares with.
+ */
+import { describe, expect, it } from 'vitest';
+import { createSQLDSL, selectCommand, sqlDSLConfig } from '../../__test__/fixtures/sql-dsl';
+import { createMultilingualDSL } from '../../api/create-dsl';
+import {
+  commandsFor,
+  compare,
+  countsOf,
+  listingOf,
+  readsWord,
+  runRoundTrip,
+  snapshotChanges,
+  snapshotOf,
+  type GateBaseline,
+  type GateFixture,
+} from './round-trip';
+
+const fixture: GateFixture = {
+  oracle: 'compile',
+  values: { columns: ['name', 'email'], source: ['users'], condition: ['age'] },
+};
+
+const results = runRoundTrip('sql', createSQLDSL(), [selectCommand], fixture);
+
+function baselineOf(listing: ReturnType<typeof listingOf>): GateBaseline {
+  return {
+    upstream: {},
+    counts: { sql: countsOf(results) },
+    roundTrip: { sql: listing.roundTrip },
+    leftover: { sql: listing.leftover },
+  };
+}
+
+describe('runRoundTrip', () => {
+  it('writes each schema with its required roles, all its roles, and each further fixed word', () => {
+    expect(commandsFor([selectCommand], fixture)).toEqual([
+      '[select columns:name source:users]',
+      '[select columns:email source:users]',
+      '[select columns:name source:users condition:age]',
+      '[select columns:email source:users condition:age]',
+    ]);
+  });
+
+  it("writes a fixture's own commands after the generated ones, once each", () => {
+    const own = '[select columns:email source:users condition:age]';
+    expect(
+      commandsFor([selectCommand], { ...fixture, commands: [own, '[select columns:id source:t]'] })
+    ).toEqual([...commandsFor([selectCommand], fixture), '[select columns:id source:t]']);
+    expect(commandsFor([selectCommand], fixture)).toContain(own);
+  });
+
+  it('reads every render back, in every language, and tries each with an unknown word after it', () => {
+    expect(countsOf(results)).toEqual({
+      roundTrip: { cases: 8, pass: 8, refused: 0, silent: 0 },
+      // The `where` condition is greedy: it takes the unknown word as text, into the SQL (`pass`).
+      leftover: { cases: 8, pass: 4, refused: 4, silent: 0 },
+    });
+    expect(results.find(r => r.kind === 'roundTrip' && r.lang === 'es')).toMatchObject({
+      text: 'seleccionar name de users',
+      read: 'select columns:expression=name source:expression=users',
+    });
+  });
+});
+
+describe('compare', () => {
+  it('finds no drift against the listing of the same results', () => {
+    expect(compare('sql', results, baselineOf(listingOf(results)))).toEqual({
+      worse: [],
+      better: [],
+      stale: [],
+    });
+  });
+
+  it('reports a case worse than listed, one better, and a listed case that is gone', () => {
+    // Two leftover cases accepted that the baseline lists as refused.
+    const accepted = '[select columns:name source:users]';
+    const now = results.map(r =>
+      r.kind === 'leftover' && r.source === accepted ? { ...r, outcome: 'silent' as const } : r
+    );
+    const listing = listingOf(results);
+    const drift = compare('sql', now, {
+      ...baselineOf(listing),
+      roundTrip: {
+        sql: {
+          '[select columns:name source:users]': {
+            es: { outcome: 'refused' },
+          },
+          '[gone]': { en: { outcome: 'silent' } },
+        },
+      },
+    });
+    expect(drift.worse.map(d => [d.kind, d.source, d.lang, d.listed, d.now])).toEqual([
+      ['leftover', accepted, 'en', 'refused', 'silent'],
+      ['leftover', accepted, 'es', 'refused', 'silent'],
+    ]);
+    expect(drift.better).toEqual([
+      {
+        kind: 'roundTrip',
+        source: '[select columns:name source:users]',
+        lang: 'es',
+        listed: 'refused',
+        now: 'pass',
+      },
+    ]);
+    expect(drift.stale).toEqual([{ kind: 'roundTrip', source: '[gone]', lang: 'en' }]);
+  });
+});
+
+describe('an unknown word read into a role', () => {
+  const leftover = (rs: typeof results) =>
+    rs
+      .filter(r => r.kind === 'leftover' && r.source.includes('condition'))
+      .map(r => [r.lang, r.outcome, r.why]);
+
+  it('is read (`pass`) where it extends an open-text role and reaches the code', () => {
+    expect(leftover(results)).toEqual([
+      ['en', 'pass', undefined],
+      ['es', 'pass', undefined],
+      ['en', 'pass', undefined],
+      ['es', 'pass', undefined],
+    ]);
+    expect(results.find(r => r.kind === 'leftover' && r.source.includes('condition'))?.read).toBe(
+      'select columns:expression=name condition:expression="age zzqx" source:expression=users'
+    );
+  });
+
+  it('is accepted (`silent`) where it does not reach the code', () => {
+    const dropsCondition = createMultilingualDSL({
+      ...sqlDSLConfig(),
+      codeGenerator: { generate: () => 'SELECT name FROM users' },
+    });
+    const rs = runRoundTrip('sql', dropsCondition, [selectCommand], fixture);
+    expect(leftover(rs)[0]).toEqual([
+      'en',
+      'silent',
+      'accepted as select; the word does not reach the code',
+    ]);
+  });
+
+  it('is refused where the input stops compiling, unless the command never compiles on its own', () => {
+    const refusesTheWord = createMultilingualDSL({
+      ...sqlDSLConfig(),
+      codeGenerator: {
+        generate: n => {
+          const c = n.roles.get('condition') as { raw?: string } | undefined;
+          if (c?.raw?.includes('zzqx')) throw new Error('not a condition');
+          return 'SELECT';
+        },
+      },
+    });
+    const rs = runRoundTrip('sql', refusesTheWord, [selectCommand], fixture);
+    expect(leftover(rs)[0]).toEqual(['en', 'refused', 'does not compile']);
+    const alone = runRoundTrip('sql', refusesTheWord, [selectCommand], {
+      ...fixture,
+      englishDoesNotCompile: ['select'],
+    });
+    expect(leftover(alone)[0]).toEqual(['en', 'pass', undefined]);
+  });
+
+  const node = (action: string, roles: Record<string, string>) => ({
+    action,
+    roles: new Map(Object.entries(roles).map(([k, v]) => [k, { type: 'expression', raw: v }])),
+  });
+
+  it.each([
+    ['extends one role', { condition: 'age' }, { condition: 'age zzqx' }, true],
+    ['fills a role the text left empty', {}, { list: 'zzqx' }, true],
+    [
+      'moves a value to make room for it (`when clicks zzqx`)',
+      { action: 'clicks' },
+      { actor: 'clicks', action: 'zzqx' },
+      false,
+    ],
+    ['replaces a value', { quantity: '2' }, { quantity: 'zzqx' }, false],
+    ['is in two roles', {}, { a: 'zzqx', b: 'zzqx' }, false],
+    ['is not read at all', { a: 'x' }, { a: 'x' }, false],
+  ] as const)('a parse that %s is the text read with the word: %s', (_, was, now, want) => {
+    expect(readsWord(node('when', was), node('when', now), 'zzqx')).toBe(want);
+  });
+
+  it('a parse as another command is not', () => {
+    expect(readsWord(node('when', {}), node('given', { a: 'zzqx' }), 'zzqx')).toBe(false);
+  });
+});
+
+describe('the parse snapshot', () => {
+  it('shows a parse that moved', () => {
+    const parses = snapshotOf(results);
+    const source = '[select columns:name source:users]';
+    const moved = {
+      upstream: {},
+      parses: { sql: { ...parses, [source]: { ...parses[source], es: 'select' } } },
+    };
+    expect(snapshotChanges('sql', results, moved)).toEqual([
+      {
+        source,
+        lang: 'es',
+        was: 'select',
+        now: 'select columns:expression=name source:expression=users',
+      },
+    ]);
+    expect(snapshotChanges('sql', results, { upstream: {}, parses: { sql: parses } })).toEqual([]);
+  });
+});