@skillstech/thunderlang 0.1.6

package/src/exporters.mjs

@@ -0,0 +1,245 @@
+// Export adapters (founder roadmap, IL-owned interop). The Intent Graph is the source of
+// truth; these render slices of it into industry-standard formats so intent can be checked
+// by existing tooling without leaving ThunderLang:
+//   - toDMN(ast)  , decisions -> DMN 1.3 decision tables (OMG DMN)
+//   - toBPMN(ast) , lifecycles -> BPMN 2.0 processes (OMG BPMN)
+//   - toSMV(ast)  , lifecycles + temporal -> NuSMV/nuXmv finite-state model + specs
+// All three are deterministic and pure (string in, string out). They export ONLY what is
+// declared; a mission with no decisions/lifecycles yields an empty-but-valid document.
+
+import { buildLifecycle } from './lifecycle.mjs';
+import { toJSONSchema, toOpenAPI } from './data-schema.mjs';
+import { toDesignTokens, toCss } from './style.mjs';
+import { buildIntentGraph } from './intent-graph.mjs';
+
+export { toDesignTokens, toCss };
+export const EXPORT_FORMATS = ['dmn', 'bpmn', 'smv', 'jsonschema', 'openapi', 'tokens', 'mermaid', 'css', 'playwright'];
+
+const esc = (s) => String(s ?? '').replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;').replace(/'/g, '&apos;');
+// A safe XML NCName / SMV identifier from arbitrary text (letters, digits, _; never leading digit).
+const xmlId = (s, fallback = 'id') => {
+  const v = String(s ?? '').trim().replace(/[^A-Za-z0-9_]+/g, '_').replace(/^_+|_+$/g, '');
+  return /^[A-Za-z_]/.test(v) ? v : `${fallback}_${v || '0'}`;
+};
+
+// ── DMN 1.3 ──────────────────────────────────────────────────────────────────
+/**
+ * Render declared decisions (Gap 4) as DMN 1.3 decision tables. Hit policy FIRST:
+ * rules are ordered, the first match wins, and the mission `default` becomes the final
+ * catch-all rule. The `when` expression lands in the first input column (the rest are
+ * "-" / any) so the full condition is preserved verbatim.
+ */
+export function toDMN(ast) {
+  const decisions = ast.decisions || [];
+  const defsId = xmlId(ast.mission, 'intent');
+  const body = decisions.map((dec) => {
+    const decId = xmlId(dec.name, 'decision');
+    const inputs = dec.inputs.length ? dec.inputs : ['condition'];
+    const inputCols = inputs.map((inp) => `        <input id="in_${decId}_${xmlId(inp)}" label="${esc(inp)}">
+          <inputExpression id="ie_${decId}_${xmlId(inp)}" typeRef="string"><text>${esc(inp)}</text></inputExpression>
+        </input>`).join('\n');
+    const ruleRow = (when, result, id) => {
+      const entries = inputs.map((_inp, i) => `          <inputEntry id="ien_${id}_${i}"><text>${esc(i === 0 ? (when ?? '-') : '-')}</text></inputEntry>`).join('\n');
+      return `        <rule id="rule_${id}">
+${entries}
+          <outputEntry id="oen_${id}"><text>${esc(result != null ? `"${result}"` : '-')}</text></outputEntry>
+        </rule>`;
+    };
+    const rules = dec.rules.map((r, i) => ruleRow(r.when, r.result, `${decId}_${i}`)).join('\n');
+    const defRule = dec.default != null ? '\n' + ruleRow(null, dec.default, `${decId}_default`) : '';
+    return `    <decision id="dec_${decId}" name="${esc(dec.name)}">
+      <decisionTable id="dt_${decId}" hitPolicy="FIRST">
+${inputCols}
+        <output id="out_${decId}" name="result" typeRef="string" />
+${rules}${defRule}
+      </decisionTable>
+    </decision>`;
+  }).join('\n');
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<definitions xmlns="https://www.omg.org/spec/DMN/20191111/MODEL/" id="defs_${defsId}" name="${esc(ast.mission || 'intent')}" namespace="https://skillstech.dev/intent/dmn">
+${body}
+</definitions>
+`;
+}
+
+// ── BPMN 2.0 ─────────────────────────────────────────────────────────────────
+/**
+ * Render declared lifecycles (Gap 2) as BPMN 2.0 processes. Each lifecycle state becomes a
+ * task, each transition a sequence flow (named after the transition), the initial state is
+ * entered from a start event, and terminal states flow to an end event.
+ */
+export function toBPMN(ast) {
+  const procs = (ast.lifecycles || []).map((lc) => {
+    const ir = buildLifecycle(lc);
+    const pid = xmlId(lc.name, 'process');
+    const sid = (s) => `t_${pid}_${xmlId(s)}`;
+    const tasks = ir.states.map((s) => `      <task id="${sid(s)}" name="${esc(s)}" />`).join('\n');
+    const flows = [];
+    if (ir.initial) flows.push(`      <startEvent id="start_${pid}" />`, `      <sequenceFlow id="f_start_${pid}" sourceRef="start_${pid}" targetRef="${sid(ir.initial)}" />`);
+    ir.transitions.forEach((t, i) => {
+      if (!t.from || !t.to) return;
+      flows.push(`      <sequenceFlow id="f_${pid}_${i}" name="${esc(t.name || '')}" sourceRef="${sid(t.from)}" targetRef="${sid(t.to)}" />`);
+    });
+    const terminals = ir.terminals.length ? ir.terminals : ir.states.filter((s) => (ir.out[s] || []).length === 0);
+    if (terminals.length) {
+      flows.push(`      <endEvent id="end_${pid}" />`);
+      terminals.forEach((s, i) => flows.push(`      <sequenceFlow id="f_end_${pid}_${i}" sourceRef="${sid(s)}" targetRef="end_${pid}" />`));
+    }
+    return `    <process id="proc_${pid}" name="${esc(lc.name)}" isExecutable="false">
+${tasks}
+${flows.join('\n')}
+    </process>`;
+  }).join('\n');
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<definitions xmlns="http://www.omg.org/spec/BPMN/20100524/MODEL" id="defs_${xmlId(ast.mission, 'intent')}" targetNamespace="https://skillstech.dev/intent/bpmn">
+${procs}
+</definitions>
+`;
+}
+
+// ── NuSMV / nuXmv model checking ─────────────────────────────────────────────
+/**
+ * Render declared lifecycles (Gap 2) as a NuSMV finite-state model, with the transition
+ * relation taken faithfully from the state machine. Emits derivable, checkable specs:
+ *   - EF(state = T) for each terminal T (the terminal is reachable), and
+ *   - a SPEC skeleton for each temporal declaration (always/eventually/until), with the
+ *     intent text as a comment and a bound-me boolean, ready for a human to bind the AP.
+ * One MODULE per lifecycle (the first is `main` so the file is runnable as-is).
+ */
+export function toSMV(ast) {
+  const lcs = ast.lifecycles || [];
+  if (!lcs.length) return '-- no lifecycle declared; nothing to model-check\n';
+
+  const txt = (s) => (typeof s === 'string' ? s : (s.statement || s.text || '')).trim();
+  const temporal = [
+    ...(ast.always || []).map((s) => ({ kind: 'AG', text: txt(s) })),
+    ...(ast.eventually || []).map((s) => ({ kind: 'AF', text: txt(s), within: s.within })),
+    ...(ast.until || []).map((s) => ({ kind: 'AU', text: txt(s) })),
+  ].filter((t) => t.text);
+
+  return lcs.map((lc, idx) => {
+    const ir = buildLifecycle(lc);
+    const name = idx === 0 ? 'main' : xmlId(lc.name, 'lifecycle');
+    const stateVals = ir.states.map((s) => xmlId(s, 's'));
+    const initial = ir.initial ? xmlId(ir.initial, 's') : (stateVals[0] || 's0');
+    const cases = ir.states.map((s) => {
+      const targets = (ir.out[s] || []).map((t) => xmlId(t, 's'));
+      const rhs = targets.length ? (targets.length === 1 ? targets[0] : `{${targets.join(', ')}}`) : xmlId(s, 's'); // self-loop if no outgoing (deadlock modeled)
+      return `      state = ${xmlId(s, 's')} : ${rhs};`;
+    }).join('\n');
+    const reachSpecs = (ir.terminals.length ? ir.terminals : []).map((t) => `-- terminal "${t}" is reachable\nSPEC EF (state = ${xmlId(t, 's')});`).join('\n');
+    const tempSpecs = idx === 0 ? temporal.map((t, i) => {
+      const op = t.kind === 'AF' ? 'AF' : t.kind === 'AU' ? 'A[ p_bind U q_bind ]' : 'AG';
+      const spec = t.kind === 'AU' ? `SPEC ${op};` : `SPEC ${op} (p_${i});`;
+      return `-- ${t.kind === 'AF' ? 'eventually' : t.kind === 'AU' ? 'until' : 'always'}: ${t.text}${t.within ? ` (within ${t.within})` : ''}\n-- bind p_${i}/q_bind to the atomic proposition, then check:\n-- ${spec}`;
+    }).join('\n') : '';
+    return `MODULE ${name}
+-- generated from lifecycle "${lc.name}" (intent-graph-v1)
+VAR
+  state : {${stateVals.join(', ')}};
+ASSIGN
+  init(state) := ${initial};
+  next(state) := case
+${cases}
+    esac;
+${reachSpecs ? '\n' + reachSpecs : ''}${tempSpecs ? '\n' + tempSpecs : ''}`;
+  }).join('\n\n') + '\n';
+}
+
+/** Dispatch by format name. Returns { format, ext, content } or null for unknown formats. */
+// ── Mermaid (full Intent Graph flowchart) ───────────────────────────────────
+/**
+ * Render the whole Intent Graph as a Mermaid `graph TD` , every canonical node with a
+ * shape by category and every typed relationship as a labeled edge. Unlike the mission
+ * summary emitted into the build's `.mmd` artifact, this is the complete graph, so it
+ * pastes into any Markdown/GitHub/Notion surface as a live diagram. Deterministic.
+ */
+export function toMermaid(ast) {
+  const graph = buildIntentGraph(ast);
+  const L = ['graph TD'];
+  const mid = (id) => `n_${String(id).replace(/[^A-Za-z0-9]+/g, '_')}`;
+  // Mermaid labels break on quotes/brackets/pipes/angles; normalize to plain text.
+  const lbl = (s) => String(s ?? '').replace(/"/g, "'").replace(/[[\]{}()<>|#]/g, ' ').replace(/\s+/g, ' ').trim();
+  // Node shape by category (rounded = states/lifecycle, hexagon = prohibitions/constraints,
+  // rhombus = decisions/rules, rectangle = everything else).
+  const shape = (type) => {
+    if (/State$/.test(type) || type === 'Lifecycle' || type === 'Journey') return ['(["', '"])'];
+    if (type === 'Never' || type === 'Constraint' || type === 'Guarantee') return ['{{"', '"}}'];
+    if (type === 'Decision' || type === 'Rule') return ['{"', '"}'];
+    return ['["', '"]'];
+  };
+  for (const n of graph.nodes) {
+    const [open, close] = shape(n.type);
+    L.push(`  ${mid(n.id)}${open}${lbl(`${n.type}: ${n.title || n.id}`)}${close}`);
+  }
+  for (const r of graph.relationships) {
+    L.push(`  ${mid(r.from)} -->|${lbl(r.type)}| ${mid(r.to)}`);
+  }
+  return `${L.join('\n')}\n`;
+}
+
+// ── Playwright (experience -> E2E test scaffold) ─────────────────────────────
+// A SKELETON, not a passing test: declared experiences/journeys/states become structured
+// Playwright stubs (describe/test/test.step) with TODOs for selectors + assertions. This is
+// the test-plan target for the experience profile , it turns "what the UI must do" into the
+// shape of the test that proves it, deterministically. Consistent with the compiler's scope
+// (test scaffolds, not production code).
+const jsStr = (s) => `'${String(s ?? '').replace(/\\/g, '\\\\').replace(/'/g, "\\'").replace(/\r?\n/g, ' ')}'`;
+
+export function toPlaywright(ast) {
+  const exps = ast.experiences || [];
+  const L = [];
+  L.push('// Playwright test scaffold generated from experience intent by @skillstech/thunderlang.');
+  L.push('// SKELETON: fill in selectors and assertions. It is not a passing test until you do.');
+  L.push("import { test, expect } from '@playwright/test';");
+  L.push('');
+  if (!exps.length) {
+    L.push('// No `experience` blocks declared, so there is nothing to scaffold.');
+    return `${L.join('\n')}\n`;
+  }
+  for (const exp of exps) {
+    L.push(`test.describe(${jsStr(exp.name || 'experience')}, () => {`);
+    if (exp.accessible && exp.accessible.target) {
+      L.push(`  // accessibility goal: ${exp.accessible.target} (proposed , verify with an a11y audit, do not assume met)`);
+    }
+    for (const j of exp.journeys || []) {
+      L.push(`  test(${jsStr(j.name || 'journey')}, async ({ page }) => {`);
+      if (!(j.steps || []).length) L.push('    // TODO: no steps declared for this journey');
+      for (const step of j.steps || []) {
+        L.push(`    await test.step(${jsStr(step)}, async () => {`);
+        L.push('      // TODO: implement this step');
+        L.push('    });');
+      }
+      L.push('  });');
+    }
+    for (const st of exp.states || []) {
+      if (st.hasRecovery) {
+        L.push(`  test(${jsStr(`failure state "${st.name}" offers a recovery path`)}, async ({ page }) => {`);
+        L.push(`    // TODO: drive the UI into "${st.name}", assert a recovery action is available`);
+        L.push('  });');
+      } else {
+        L.push(`  test(${jsStr(`reaches state: ${st.name}`)}, async ({ page }) => {`);
+        L.push(`    // TODO: drive the UI to "${st.name}" and assert it is shown`);
+        L.push('  });');
+      }
+    }
+    L.push('});');
+    L.push('');
+  }
+  return `${L.join('\n')}\n`;
+}
+
+export function exportIntent(ast, format) {
+  switch (format) {
+    case 'dmn': return { format, ext: 'dmn', content: toDMN(ast) };
+    case 'bpmn': return { format, ext: 'bpmn', content: toBPMN(ast) };
+    case 'smv': return { format, ext: 'smv', content: toSMV(ast) };
+    case 'jsonschema': return { format, ext: 'schema.json', content: JSON.stringify(toJSONSchema(ast, { which: 'both' }), null, 2) + '\n' };
+    case 'openapi': return { format, ext: 'openapi.json', content: JSON.stringify(toOpenAPI(ast), null, 2) + '\n' };
+    case 'tokens': return { format, ext: 'tokens.json', content: JSON.stringify(toDesignTokens(ast), null, 2) + '\n' };
+    case 'mermaid': return { format, ext: 'mmd', content: toMermaid(ast) };
+    case 'css': return { format, ext: 'css', content: toCss(ast) };
+    case 'playwright': return { format, ext: 'spec.ts', content: toPlaywright(ast) };
+    default: return null;
+  }
+}

package/src/expr.mjs

@@ -0,0 +1,245 @@
+// A tiny, safe, DETERMINISTIC expression evaluator for decision conditions. No eval, no
+// host access , it evaluates a `when` string against a plain inputs object and returns a
+// value. This is what makes ThunderLang decisions EXECUTABLE: the same condition + inputs
+// always yields the same result, with zero AI and zero code generation.
+//
+// Grammar (lowest -> highest precedence):
+//   or      := and (('or' | '||') and)*
+//   and     := not (('and' | '&&') not)*
+//   not     := ('not' | '!') not | comparison
+//   compare := add ( ('>='|'<='|'=='|'!='|'='|'>'|'<') add | 'in' '[' list ']' )?
+//   add     := mul (('+' | '-') mul)*
+//   mul     := unary (('*' | '/' | '%') unary)*
+//   unary   := '-' unary | primary
+//   primary := number | string | bool | ident(.ident)* | '(' or ')' | '[' list ']'
+
+export class ExprError extends Error {}
+
+const OPS = ['>=', '<=', '==', '!=', '&&', '||', '>', '<', '=', '+', '-', '*', '/', '%', '!', '(', ')', '[', ']', ','];
+
+export function tokenize(src) {
+  const toks = [];
+  const s = String(src ?? '');
+  let i = 0;
+  const isIdStart = (c) => /[A-Za-z_]/.test(c);
+  const isId = (c) => /[A-Za-z0-9_.]/.test(c);
+  while (i < s.length) {
+    const c = s[i];
+    if (/\s/.test(c)) { i++; continue; }
+    if (c === '"' || c === "'") {
+      let j = i + 1; let str = '';
+      while (j < s.length && s[j] !== c) { str += s[j]; j++; }
+      if (j >= s.length) throw new ExprError(`unterminated string in: ${src}`);
+      toks.push({ t: 'str', v: str }); i = j + 1; continue;
+    }
+    if (/[0-9]/.test(c) || (c === '.' && /[0-9]/.test(s[i + 1] || ''))) {
+      let j = i; let num = '';
+      while (j < s.length && /[0-9.]/.test(s[j])) { num += s[j]; j++; }
+      toks.push({ t: 'num', v: Number(num) }); i = j; continue;
+    }
+    if (isIdStart(c)) {
+      let j = i; let id = '';
+      while (j < s.length && isId(s[j])) { id += s[j]; j++; }
+      const lower = id.toLowerCase();
+      if (lower === 'and' || lower === 'or' || lower === 'not' || lower === 'in') toks.push({ t: 'kw', v: lower });
+      else if (lower === 'true' || lower === 'false') toks.push({ t: 'bool', v: lower === 'true' });
+      else toks.push({ t: 'id', v: id });
+      i = j; continue;
+    }
+    const two = s.slice(i, i + 2);
+    if (OPS.includes(two)) { toks.push({ t: 'op', v: two }); i += 2; continue; }
+    if (OPS.includes(c)) { toks.push({ t: 'op', v: c }); i += 1; continue; }
+    throw new ExprError(`unexpected character "${c}" in: ${src}`);
+  }
+  return toks;
+}
+
+function parse(toks) {
+  let pos = 0;
+  const peek = () => toks[pos];
+  const eat = (v) => { const t = toks[pos]; if (v && (!t || t.v !== v)) throw new ExprError(`expected "${v}"`); pos++; return t; };
+  const isKw = (v) => peek() && peek().t === 'kw' && peek().v === v;
+  const isOp = (v) => peek() && peek().t === 'op' && peek().v === v;
+
+  function orExpr() {
+    let node = andExpr();
+    while (isKw('or') || isOp('||')) { eat(); node = { k: 'or', a: node, b: andExpr() }; }
+    return node;
+  }
+  function andExpr() {
+    let node = notExpr();
+    while (isKw('and') || isOp('&&')) { eat(); node = { k: 'and', a: node, b: notExpr() }; }
+    return node;
+  }
+  function notExpr() {
+    if (isKw('not') || isOp('!')) { eat(); return { k: 'not', a: notExpr() }; }
+    return compare();
+  }
+  function compare() {
+    const left = add();
+    const t = peek();
+    if (t && t.t === 'op' && ['>=', '<=', '==', '!=', '=', '>', '<'].includes(t.v)) {
+      eat(); return { k: 'cmp', op: t.v === '=' ? '==' : t.v, a: left, b: add() };
+    }
+    if (isKw('in')) {
+      eat(); eat('['); const items = listExpr(); eat(']');
+      return { k: 'in', a: left, list: items };
+    }
+    return left;
+  }
+  function listExpr() {
+    const items = [];
+    if (isOp(']')) return items;
+    items.push(orExpr());
+    while (isOp(',')) { eat(); items.push(orExpr()); }
+    return items;
+  }
+  function add() {
+    let node = mul();
+    while (isOp('+') || isOp('-')) { const op = eat().v; node = { k: 'arith', op, a: node, b: mul() }; }
+    return node;
+  }
+  function mul() {
+    let node = unary();
+    while (isOp('*') || isOp('/') || isOp('%')) { const op = eat().v; node = { k: 'arith', op, a: node, b: unary() }; }
+    return node;
+  }
+  function unary() {
+    if (isOp('-')) { eat(); return { k: 'neg', a: unary() }; }
+    return primary();
+  }
+  function primary() {
+    const t = peek();
+    if (!t) throw new ExprError('unexpected end of expression');
+    if (t.t === 'num') { eat(); return { k: 'lit', v: t.v }; }
+    if (t.t === 'str') { eat(); return { k: 'lit', v: t.v }; }
+    if (t.t === 'bool') { eat(); return { k: 'lit', v: t.v }; }
+    if (t.t === 'id') { eat(); return { k: 'ref', path: t.v }; }
+    if (isOp('(')) { eat(); const n = orExpr(); eat(')'); return n; }
+    if (isOp('[')) { eat(); const items = listExpr(); eat(']'); return { k: 'list', items }; }
+    throw new ExprError(`unexpected token "${t.v}"`);
+  }
+
+  const tree = orExpr();
+  if (pos !== toks.length) throw new ExprError('trailing tokens in expression');
+  return tree;
+}
+
+// Resolve a dotted path (a.b.c) against the inputs object. Bare identifiers that are not
+// present resolve to a Symbol so that `status == active` treats `active` as the literal
+// string "active" (decision tables commonly use bare enum tokens on the right-hand side).
+const UNRESOLVED = Symbol('unresolved');
+function resolve(path, inputs) {
+  let cur = inputs;
+  for (const part of path.split('.')) {
+    if (cur != null && typeof cur === 'object' && part in cur) cur = cur[part];
+    else return UNRESOLVED;
+  }
+  return cur;
+}
+
+// Numeric coercion for comparisons: if both sides look numeric, compare as numbers.
+const asNum = (v) => (typeof v === 'number' ? v : (typeof v === 'string' && v.trim() !== '' && !isNaN(Number(v)) ? Number(v) : null));
+
+function evalNode(n, inputs) {
+  switch (n.k) {
+    case 'lit': return n.v;
+    case 'list': return n.items.map((x) => evalNode(x, inputs));
+    case 'ref': {
+      const v = resolve(n.path, inputs);
+      return v === UNRESOLVED ? n.path : v; // bare token -> its own name (enum literal)
+    }
+    case 'or': return !!(evalNode(n.a, inputs) || evalNode(n.b, inputs));
+    case 'and': return !!(evalNode(n.a, inputs) && evalNode(n.b, inputs));
+    case 'not': return !evalNode(n.a, inputs);
+    case 'neg': { const r = -Number(evalNode(n.a, inputs)); return Number.isFinite(r) ? r : null; }
+    case 'arith': {
+      const a = Number(evalNode(n.a, inputs)); const b = Number(evalNode(n.b, inputs));
+      const r = n.op === '+' ? a + b : n.op === '-' ? a - b : n.op === '*' ? a * b : n.op === '/' ? a / b : a % b;
+      // Non-finite results (divide/modulo by zero, NaN from non-numeric operands) are
+      // neutralized to null so they can never leak a surprising truthy comparison (e.g.
+      // Infinity > 1). A deterministic decision must not silently match on 10 / 0.
+      return Number.isFinite(r) ? r : null;
+    }
+    case 'in': {
+      const a = evalNode(n.a, inputs);
+      return n.list.map((x) => evalNode(x, inputs)).some((v) => eq(a, v));
+    }
+    case 'cmp': {
+      const a = evalNode(n.a, inputs); const b = evalNode(n.b, inputs);
+      if (n.op === '==') return eq(a, b);
+      if (n.op === '!=') return !eq(a, b);
+      // An unknown / neutralized operand (null: a missing value or a divide-by-zero) cannot be
+      // ordered; every ordering comparison against it is false, never JS's null->0 coercion.
+      if (a === null || b === null) return false;
+      const na = asNum(a); const nb = asNum(b);
+      const [x, y] = (na != null && nb != null) ? [na, nb] : [a, b];
+      if (n.op === '>=') return x >= y;
+      if (n.op === '<=') return x <= y;
+      if (n.op === '>') return x > y;
+      if (n.op === '<') return x < y;
+      throw new ExprError(`unknown operator ${n.op}`);
+    }
+    default: throw new ExprError(`unknown node ${n.k}`);
+  }
+}
+
+function eq(a, b) {
+  const na = asNum(a); const nb = asNum(b);
+  if (na != null && nb != null) return na === nb;
+  return String(a) === String(b);
+}
+
+/** Compile a `when` string into a reusable predicate (throws ExprError on bad syntax). */
+export function compileExpr(src) {
+  const tree = parse(tokenize(src));
+  return (inputs = {}) => evalNode(tree, inputs);
+}
+
+/** Evaluate a `when` string against inputs. Returns the value (booleans for conditions). */
+export function evalExpr(src, inputs = {}) {
+  return compileExpr(src)(inputs);
+}
+
+// Per-language rendering of the `when` grammar. `eq`/`neq` build an equality expression (JS uses
+// ===, C# ==, Java Objects.equals for correct string value equality); `inList` builds membership.
+const DIALECTS = {
+  js: { eq: (a, b) => `${a} === ${b}`, neq: (a, b) => `${a} !== ${b}`, inList: (list, x) => `[${list.join(', ')}].includes(${x})`, nil: 'undefined' },
+  csharp: { eq: (a, b) => `${a} == ${b}`, neq: (a, b) => `${a} != ${b}`, inList: (list, x) => `new[]{${list.join(', ')}}.Contains(${x})`, nil: 'null' },
+  java: { eq: (a, b) => `java.util.Objects.equals(${a}, ${b})`, neq: (a, b) => `!java.util.Objects.equals(${a}, ${b})`, inList: (list, x) => `java.util.List.of(${list.join(', ')}).contains(${x})`, nil: 'null' },
+};
+
+function renderExpr(src, inputs, D) {
+  const known = new Set(inputs);
+  const r = (n) => {
+    switch (n.k) {
+      case 'or': return `(${r(n.a)} || ${r(n.b)})`;
+      case 'and': return `(${r(n.a)} && ${r(n.b)})`;
+      case 'not': return `!${r(n.a)}`;
+      case 'neg': return `-${r(n.a)}`;
+      case 'arith': return `(${r(n.a)} ${n.op} ${r(n.b)})`;
+      case 'cmp':
+        if (n.op === '==') return `(${D.eq(r(n.a), r(n.b))})`;
+        if (n.op === '!=') return `(${D.neq(r(n.a), r(n.b))})`;
+        return `(${r(n.a)} ${n.op} ${r(n.b)})`;
+      case 'in': return D.inList(n.list.map(r), r(n.a));
+      case 'list': return `[${n.items.map(r).join(', ')}]`;
+      case 'lit': return typeof n.v === 'string' ? JSON.stringify(n.v) : String(n.v);
+      case 'ref': return (known.has(n.path) || known.has(n.path.split('.')[0])) ? n.path : JSON.stringify(n.path);
+      default: return D.nil;
+    }
+  };
+  return r(parse(tokenize(src)));
+}
+
+/**
+ * Render a `when` condition as an equivalent expression in a target language, for code generation.
+ * Input names render as identifiers; any other bare token is an enum literal (a string). Reuses
+ * the parser, so precedence is exact. `dialect` is js (default) | csharp | java.
+ */
+export function exprToCode(src, { inputs = [], dialect = 'js' } = {}) {
+  return renderExpr(src, inputs, DIALECTS[dialect] || DIALECTS.js);
+}
+export const exprToJs = (src, opts = {}) => exprToCode(src, { ...opts, dialect: 'js' });
+export const exprToCSharp = (src, opts = {}) => exprToCode(src, { ...opts, dialect: 'csharp' });
+export const exprToJava = (src, opts = {}) => exprToCode(src, { ...opts, dialect: 'java' });

package/src/fable.mjs

@@ -0,0 +1,110 @@
+// Fable (intent-fable-v1) , the versioned, explainable rule authority the Intent Scanner runs.
+// Anti-fork: Fable is NOT a new rule engine. It is a rule-metadata layer OVER ThunderLang's shipped
+// DIAGNOSTIC_RULES catalog (which already carries id/severity/blocks/area), adding what a Scanner
+// finding needs: a risk category, detection strategy, remediation, required evidence, suggested
+// ThunderLang, and suppression/risk-acceptance policy. Every finding is explainable , never
+// "AI detected a possible issue." Pure ESM, browser-safe.
+
+import { ALL_DIAGNOSTICS } from './intent-schema.mjs';
+
+export const FABLE_SCHEMA = 'intent-fable-v1';
+
+// The Scanner's risk taxonomy (directive Part 3). Every finding rolls up to exactly one.
+export const RISK_CATEGORIES = [
+  'Intent risk', 'Implementation risk', 'Architecture risk', 'Product risk', 'UX risk',
+  'Security risk', 'Privacy risk', 'Reliability risk', 'Operational risk', 'Data risk',
+  'Dependency risk', 'Knowledge risk', 'Verification risk', 'AI-generated-code risk',
+  'Organizational-policy risk',
+];
+
+// Diagnostic area -> risk category. Deterministic; every catalog area is mapped.
+const AREA_RISK = {
+  product: 'Product risk', evidence: 'Intent risk', graph: 'Intent risk', experience: 'UX risk',
+  conflict: 'Intent risk', governance: 'Organizational-policy risk', privacy: 'Privacy risk',
+  outcome: 'Product risk', decision: 'Implementation risk', distributed: 'Reliability risk',
+  lifecycle: 'Reliability risk', temporal: 'Verification risk', style: 'UX risk',
+  security: 'Security risk', type: 'Implementation risk', core: 'Intent risk',
+  architecture: 'Architecture risk', ai: 'AI-generated-code risk', note: 'Knowledge risk',
+};
+
+// Remediation + suggested-verification guidance per area (a finding says how to fix it).
+const AREA_REMEDIATION = {
+  security: 'Remove the secret from the surface, or gate it behind an auth requirement; add a never-rule and a scan test.',
+  privacy: 'State the purpose, retention, and lawful basis for the data; restrict exposure.',
+  core: 'Make the intent complete: state the goal, and attach a `verify` to each guarantee/never-rule.',
+  outcome: 'Give the outcome a metric, a target better than baseline, and a measurement window.',
+  decision: 'Add a default and resolve overlapping/contradictory rules.',
+  distributed: 'Add an idempotency key, a timeout, duplicate handling, or a compensation as required.',
+  lifecycle: 'Fix the transition/state so every state is reachable and can terminate.',
+  conflict: 'Resolve the contradiction or record a governed decision.',
+  style: 'Bind tokens to the canonical address space; declare the accessibility target as a proposed claim.',
+  type: 'Use a known semantic type or a PascalCase entity name.',
+};
+
+/**
+ * The Fable rule for a diagnostic code , the shipped catalog entry augmented with Scanner
+ * metadata. Returns a synthetic rule for unknown codes so a finding is always explainable.
+ */
+export function fableRuleFor(code) {
+  const base = ALL_DIAGNOSTICS.find((r) => r.ruleId === code);
+  const area = base?.area || 'core';
+  return {
+    ruleId: code,
+    ruleVersion: '1',
+    title: base?.summary || code,
+    category: AREA_RISK[area] || 'Intent risk',
+    area,
+    detection: 'deterministic', // every catalog check is deterministic, no AI
+    severity: base?.severity || 'warning',
+    defaultConfidence: 'Observed',
+    blocks: base?.blocks || [],
+    requiredEvidence: 'the source location(s) where the check fired',
+    remediation: AREA_REMEDIATION[area] || (base?.summary ? `Address: ${base.summary}` : 'Review and resolve.'),
+    suggestedVerification: area === 'core' || area === 'outcome' ? 'Add a test that proves the property, then re-scan.' : 'Add a check that would catch a regression.',
+    suppressible: base?.severity !== 'blocker',
+    riskAcceptable: true,
+    deprecated: false,
+  };
+}
+
+/** The universal Fable rule pack , every check-surface catalog rule as a Fable rule. */
+export function universalPack() {
+  return {
+    schema: FABLE_SCHEMA,
+    pack: 'universal',
+    version: '1',
+    rules: ALL_DIAGNOSTICS.map((r) => fableRuleFor(r.ruleId)),
+  };
+}
+
+// Map an intent-graph classification/provenance-free deterministic diagnostic to a confidence.
+const confidenceFor = (rule) => (rule.detection === 'deterministic' ? 'Observed' : 'Inferred');
+
+/**
+ * Turn a compiler diagnostic (from semanticDiagnostics) into a rich Fable Finding , the directive's
+ * finding model: what/why/evidence/affected/severity/confidence/detection/remediation/... Every
+ * field is present so a finding is never unexplained.
+ */
+export function toFinding(diag, { file = null, index = 0, affectedNodes = [] } = {}) {
+  const rule = fableRuleFor(diag.code);
+  const isBlocker = diag.severity === 'blocker';
+  return {
+    findingId: `${(diag.code || 'FINDING').toLowerCase()}-${file ? file.replace(/[^a-z0-9]+/gi, '-') : 'x'}-${index}`,
+    ruleId: rule.ruleId,
+    ruleVersion: rule.ruleVersion,
+    category: rule.category,
+    detected: diag.message,
+    why: diag.why || rule.title,
+    evidence: [{ file, line: diag.line ?? null, kind: 'diagnostic', detail: diag.message }],
+    affectedNodes,
+    severity: isBlocker ? 'blocker' : (diag.level || 'warning'),
+    confidence: confidenceFor(rule),
+    detectionType: rule.detection,
+    potentialImpact: isBlocker ? 'Blocks a phase (e.g. release) until resolved.' : 'Weakens the intent; not blocking.',
+    remediation: rule.remediation,
+    suggestedVerification: rule.suggestedVerification,
+    humanReviewRequired: rule.detection !== 'deterministic',
+    suppressed: false,
+    riskAccepted: false,
+  };
+}