gennady 0.8.3 → 0.8.4-draft.2

package/ai/inspector/web/__tests__/markdown.test.ts

@@ -0,0 +1,185 @@
+// @file: ai/inspector — renderMarkdown + clean: token highlight, code spans, and the SECTION-marker regression.
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { renderMarkdown, renderInline } from '../markdown.js';
+import { clean } from '../../core/scan.ts';
+
+test('renderInline: highlights tokens/code without wrapping in <p> (for notes)', () => {
+  const h = renderInline('run `sdd-state` then STEP_1_PLAN');
+  assert.doesNotMatch(h, /<p>|<ul>/);
+  assert.match(h, /<code><span class="tok-cmd">sdd-state<\/span><\/code>/);
+  assert.match(h, /class="tok-step">STEP_1_PLAN/);
+});
+
+test('renders a code span and keeps following text', () => {
+  const h = renderMarkdown('run `sdd-task` then done');
+  assert.match(h, /<code><span class="tok-cmd">sdd-task<\/span><\/code>/);
+  assert.match(h, /then done/);
+});
+
+test('classifies tokens by kind', () => {
+  const h = renderMarkdown(
+    'AX_AUDIT_HOOK STEP_1_PLAN H_NO_TASKS sdd-check ai/x/y.directive.xml FLOW_VERSION'
+  );
+  assert.match(h, /class="tok-axiom">AX_AUDIT_HOOK/);
+  assert.match(h, /class="tok-step">STEP_1_PLAN/);
+  assert.match(h, /class="tok-halt">H_NO_TASKS/);
+  assert.match(h, /class="tok-cmd">sdd-check/);
+  assert.match(h, /class="tok-path">ai\/x\/y\.directive\.xml/);
+  assert.match(h, /class="tok-kw">FLOW_VERSION/);
+});
+
+test('a code span that contains an HTML comment renders as ONE <code>, text intact', () => {
+  const h = renderMarkdown('wraps in `<!--SECTION:-->` markers; verify with `sdd-check` done');
+  assert.match(h, /<code>&lt;!--SECTION:--&gt;<\/code>/);
+  assert.match(h, /markers; verify with/);
+  assert.match(h, /<code><span class="tok-cmd">sdd-check<\/span><\/code>/);
+});
+
+test('a lone backtick does not swallow the rest of the line', () => {
+  const h = renderMarkdown('a ` b c');
+  assert.doesNotMatch(h, /<code>/);
+  assert.match(h, /b c/);
+});
+
+test('bullets and bold', () => {
+  assert.match(renderMarkdown('- one\n- two'), /<ul><li>one<\/li><li>two<\/li><\/ul>/);
+  assert.match(renderMarkdown('a **b** c'), /<strong>b<\/strong>/);
+});
+
+// --- regression: the STEP_2_ANCHORS bug (clean stripped the comment INSIDE the code span) ---
+test('clean keeps an HTML comment that is literal content inside a code span', () => {
+  const out = clean('wraps canonical sections in `<!--SECTION:-->` markers');
+  assert.match(out, /`<!--SECTION:-->`/);
+  assert.match(out, /markers/);
+});
+
+test('clean still strips a standalone authoring comment (outside code)', () => {
+  const out = clean('alpha <!-- author note --> beta');
+  assert.doesNotMatch(out, /author note/);
+  assert.match(out, /alpha/);
+  assert.match(out, /beta/);
+});
+
+// --- fuzz / property tests: highlighting must be tolerant of ANY input ---
+const stripTags = (h: string): string => h.replace(/<[^>]*>/g, '');
+const unescape = (h: string): string =>
+  h.replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&amp;/g, '&');
+const norm = (x: string): string => x.replace(/[`*]/g, ''); // markdown markers are consumed; ignore them
+const balanced = (h: string, tag: string): boolean =>
+  (h.match(new RegExp('<' + tag + '[ >]', 'g')) ?? []).length ===
+  (h.match(new RegExp('</' + tag + '>', 'g')) ?? []).length;
+
+const ATOMS = [
+  'a',
+  'B',
+  '7',
+  ' ',
+  '`',
+  '*',
+  '<',
+  '>',
+  '&',
+  '/',
+  '.',
+  '-',
+  '_',
+  ':',
+  '(',
+  ')',
+  '\n',
+  '→',
+  '->',
+  'AX_X',
+  'STEP_Y',
+  'H_Z',
+  'sdd-task',
+  'x.directive.xml',
+  'LOGIC_SWITCH',
+  '**',
+  '``',
+];
+function randInput(): string {
+  let s = '';
+  const n = Math.floor(Math.random() * 26);
+  for (let i = 0; i < n; i++) s += ATOMS[Math.floor(Math.random() * ATOMS.length)];
+  return s;
+}
+
+function assertInvariants(s: string): void {
+  let h = '';
+  assert.doesNotThrow(
+    () => {
+      h = renderInline(s);
+    },
+    `threw on ${JSON.stringify(s)}`
+  );
+  const noTags = stripTags(h);
+  assert.ok(!/[<>]/.test(noTags), `raw <> leaked for ${JSON.stringify(s)} -> ${h}`);
+  for (const tag of ['span', 'code', 'strong'])
+    assert.ok(balanced(h, tag), `unbalanced <${tag}> for ${JSON.stringify(s)} -> ${h}`);
+  assert.equal(
+    norm(unescape(noTags)),
+    norm(s),
+    `text changed for ${JSON.stringify(s)} -> ${JSON.stringify(unescape(noTags))}`
+  );
+}
+
+test('fuzz: renderInline holds invariants on 2000 random inputs', () => {
+  for (let i = 0; i < 2000; i++) assertInvariants(randInput());
+});
+
+test('fuzz: adversarial fixed cases', () => {
+  for (const s of [
+    '',
+    '`',
+    '``',
+    '```',
+    'a`b',
+    'a``b',
+    '`a``b`',
+    '**',
+    '*** x ***',
+    '<script>',
+    '<>&',
+    'AX_<b>',
+    '`<!--x-->`',
+    'sdd-task`',
+    'x.directive.xml.directive.xml',
+    '→->`*`<',
+    '`'.repeat(9),
+    '**`AX_X`**',
+  ]) {
+    assertInvariants(s);
+  }
+});
+
+test('fuzz: renderMarkdown (block) keeps word-chars + escapes + balances on 1500 random inputs', () => {
+  const words = (x: string): string => (x.match(/[A-Za-z0-9_]+/g) ?? []).join('');
+  for (let i = 0; i < 1500; i++) {
+    const s = randInput();
+    let h = '';
+    assert.doesNotThrow(
+      () => {
+        h = renderMarkdown(s);
+      },
+      `threw on ${JSON.stringify(s)}`
+    );
+    const noTags = stripTags(h);
+    assert.ok(!/[<>]/.test(noTags), `raw <> leaked for ${JSON.stringify(s)} -> ${h}`);
+    for (const tag of ['span', 'code', 'strong', 'p', 'ul', 'li'])
+      assert.ok(balanced(h, tag), `unbalanced <${tag}> for ${JSON.stringify(s)}`);
+    assert.equal(words(unescape(noTags)), words(s), `word-chars changed for ${JSON.stringify(s)}`);
+  }
+});
+
+test('clean → renderMarkdown: SECTION marker survives end-to-end (regression)', () => {
+  const src =
+    'Run `sdd-migrate anchors --all --write` (wraps sections in `<!--SECTION:-->` markers). Verify with `sdd-check`.';
+  const h = renderMarkdown(clean(src));
+  assert.match(h, /<code>&lt;!--SECTION:--&gt;<\/code>/);
+  assert.match(h, /Verify with/);
+  // sdd-check stays its own code span, not swallowed into a broken span
+  assert.match(h, /<code><span class="tok-cmd">sdd-check<\/span><\/code>/);
+});

package/ai/inspector/web/app.js

@@ -0,0 +1,324 @@
+// @file: ai/inspector — UI: skill list → (1) structure tree, (2) step-through debugger of the flow.
+
+import { renderMarkdown, renderInline } from './markdown.js';
+import {
+  base,
+  dirOf,
+  gather,
+  toolsOf,
+  runsOutsideSwitch,
+  stepMd,
+  unitsOf,
+  transOf,
+  mainDirective,
+  transitionsFor,
+  simulate,
+} from './debug.js';
+
+const KIND = {
+  skill: ['k-skill', 'skill'],
+  section: ['k-tag', 'tag'],
+  step: ['k-step', 'step'],
+  tool: ['k-tool', 'cmd'],
+  read: ['k-read', 'read'],
+  run: ['k-run', 'run'],
+  directive: ['k-run', 'directive'],
+  axiom: ['k-axiom', 'axiom'],
+  halt: ['k-halt', 'halt'],
+  switch: ['k-switch', 'switch'],
+  branch: ['k-switch', 'branch'],
+  text: ['k-tag', 'tag'],
+  unparsed: ['k-warn', 'unparsed'],
+};
+const LEGEND = ['step', 'tool', 'read', 'run', 'axiom', 'switch', 'halt', 'unparsed'];
+
+function el(tag, cls, txt) {
+  const e = document.createElement(tag);
+  if (cls) e.className = cls;
+  if (txt != null) e.textContent = txt;
+  return e;
+}
+
+// Open files via the editor's URL scheme (vscode://file/<abs>:<line>) — the OS launches the editor,
+// no server-side spawn (avoids EACCES). repoRoot comes from trace.json; editor scheme is user-picked.
+let REPO_ROOT = '';
+let EDITOR =
+  (typeof localStorage !== 'undefined' && localStorage.getItem('inspector.editor')) || 'vscode';
+const editorUrl = (loc) => EDITOR + '://file' + REPO_ROOT + '/' + loc.file + ':' + loc.line;
+
+/** A small "open in editor" link bound to a node's source loc (clicking does not toggle the row). */
+function openCtl(loc) {
+  const a = el('a', 'opensrc', '↗');
+  a.href = editorUrl(loc);
+  a.title = 'open ' + loc.file + ':' + loc.line + ' in ' + EDITOR;
+  a.addEventListener('click', (e) => e.stopPropagation());
+  return a;
+}
+
+/** Detail block: CLI help stays raw/aligned (<pre>-like); prompt prose renders as markdown-lite. */
+function detailEl(node) {
+  if (node.kind === 'tool') return el('div', 'detail', node.detail); // aligned help — keep raw
+  const d = el('div', 'md');
+  d.innerHTML = renderMarkdown(node.detail);
+  return d;
+}
+
+// ---------- structure tree ----------
+function renderNode(node, depth) {
+  const wrap = el('div', 'node');
+  const row = el('div', 'row');
+  row.dataset.kind = node.kind;
+  const hasStructural = !!(node.children && node.children.length);
+  const hasKids = hasStructural || node.detail;
+  const chev = el('span', 'chev' + (hasKids ? '' : ' leaf'), '▸');
+  row.appendChild(chev);
+  const meta = KIND[node.kind] || ['k-tag', '·'];
+  row.appendChild(el('span', 'k ' + meta[0], meta[1]));
+  const lab = el('div', 'lab');
+  lab.appendChild(el('span', 'tag', node.label));
+  if (node.note) {
+    lab.appendChild(document.createTextNode(' '));
+    const n = el('span', 'note');
+    n.innerHTML = '— ' + renderInline(node.note);
+    lab.appendChild(n);
+  }
+  row.appendChild(lab);
+  if (node.loc) row.appendChild(openCtl(node.loc));
+  wrap.appendChild(row);
+  if (hasKids) {
+    const kids = el('div', 'kids');
+    if (node.detail) kids.appendChild(detailEl(node));
+    (node.children || []).forEach((ch) => kids.appendChild(renderNode(ch, depth + 1)));
+    const open = depth < 2 && hasStructural;
+    if (open) chev.classList.add('open');
+    else kids.classList.add('collapsed');
+    wrap.appendChild(kids);
+    row.classList.add('clk');
+    row.addEventListener('click', () => {
+      kids.classList.toggle('collapsed');
+      chev.classList.toggle('open');
+    });
+  }
+  return wrap;
+}
+
+// ---------- debugger view ----------
+function renderDebug(container, skill) {
+  let moves = [];
+  function draw() {
+    const sim = simulate(skill, moves);
+    container.innerHTML = '';
+
+    const bc = el('div', 'dbg-stack');
+    bc.appendChild(document.createTextNode('стек: '));
+    sim.stack.forEach((f, i) => {
+      if (i) bc.appendChild(document.createTextNode('  ›  '));
+      bc.appendChild(el('b', null, f.node.label));
+    });
+    container.appendChild(bc);
+
+    sim.log.forEach((e) => {
+      const ind = (e.depth || 0) * 16; // indent by stack depth — the descent reads as a staircase
+      if (e.div) {
+        const d = el('div', 'dbg-div', e.div);
+        d.style.marginLeft = ind + 'px';
+        container.appendChild(d);
+        // entered a directive → drop it in collapsed, right under the divider, no extra frame.
+        // the divider text already says we loaded it; the row below is the affordance to read it.
+        if (e.dir) {
+          const r = renderNode(e.dir, 2);
+          r.style.marginLeft = ind + 'px';
+          container.appendChild(r);
+        }
+        return;
+      }
+      const row = el('div', 'dbg-ev');
+      row.style.marginLeft = ind + 'px';
+      row.appendChild(el('span', 'dbg-ic', '✓'));
+      const b = el('div');
+      b.appendChild(el('span', 'dbg-step', e.step.label));
+      const extra = [];
+      const tools = toolsOf(e.step)
+        .map((t) => t.label)
+        .join(', ');
+      if (tools) extra.push('тулы: ' + tools);
+      if (e.into) extra.push('вошли в ' + base(e.into));
+      if (e.branch) extra.push('ветка: ' + e.branch);
+      if (extra.length) b.appendChild(el('span', 'dbg-mut', ' — ' + extra.join(' · ')));
+      row.appendChild(b);
+      container.appendChild(row);
+    });
+
+    if (sim.done) {
+      container.appendChild(el('div', 'dbg-div', 'флоу завершён'));
+    } else if (sim.current) {
+      const { unit, transitions } = sim.current;
+      const card = el('div', 'dbg-card');
+      card.style.marginLeft = (sim.current.depth || 0) * 16 + 'px';
+      const hd = el('div', 'dbg-hd');
+      const meta = KIND[unit.kind] || ['k-step', 'step'];
+      hd.appendChild(el('span', 'k ' + meta[0], meta[1]));
+      hd.appendChild(el('span', 'dbg-cur', unit.label));
+      if (unit.loc) hd.appendChild(openCtl(unit.loc));
+      card.appendChild(hd);
+      if (unit.kind === 'switch') {
+        if (unit.note) {
+          const n = el('div', 'dbg-note');
+          n.innerHTML = renderInline(unit.note);
+          card.appendChild(n);
+        }
+      } else {
+        const md = stepMd(unit);
+        if (md) {
+          const d = el('div', 'md');
+          d.innerHTML = renderMarkdown(md);
+          card.appendChild(d);
+        }
+        const tools = toolsOf(unit);
+        if (tools.length)
+          card.appendChild(
+            el('div', 'dbg-mut', 'выполняет: ' + tools.map((t) => t.label).join(', '))
+          );
+        gather(unit, 'unparsed').forEach((u) =>
+          card.appendChild(el('div', 'dbg-mut', '⚠ ' + u.label + (u.note ? ' — ' + u.note : '')))
+        );
+        // READ_AND_USE: show WHAT this step loads directly (not switch branches), collapsed + inspectable
+        runsOutsideSwitch(unit).forEach((r) => {
+          const dir = dirOf(r);
+          if (!dir) return;
+          const box = el('div', 'dbg-loaded');
+          box.appendChild(el('div', 'dbg-mut', '↘ загружает (осмотреть): ' + base(r.ref)));
+          box.appendChild(renderNode(dir, 2)); // depth 2 → collapsed by default
+          card.appendChild(box);
+        });
+      }
+      // if the choices come from a structured switch, give it an explicit, labelled block
+      const govSwitch = unit.kind === 'switch' ? unit : gather(unit, 'switch')[0];
+      let host = card;
+      if (govSwitch && unit.kind !== 'switch') {
+        const box = el('div', 'dbg-switchbox');
+        const h = el('div', 'dbg-switch-hd');
+        h.appendChild(el('span', 'k k-switch', 'switch'));
+        h.appendChild(el('span', 'dbg-sw-tag', 'LOGIC_SWITCH'));
+        if (govSwitch.note) h.appendChild(el('span', 'dbg-mut', '· ' + govSwitch.note));
+        h.appendChild(el('span', 'dbg-mut', '— выбери ветку:'));
+        box.appendChild(h);
+        card.appendChild(box);
+        host = box;
+      }
+      const tr = el('div', 'dbg-branches');
+      transitions.forEach((t) => {
+        const btn = el('div', 'dbg-br');
+        if (t.type === 'branch') {
+          btn.classList.add('dbg-case');
+          const br = govSwitch && govSwitch.children ? govSwitch.children[t.i] : null;
+          const run = br && (br.children || []).find((c) => c.kind === 'run');
+          const txt = br && (br.children || []).find((c) => c.kind === 'text');
+          btn.appendChild(
+            el('span', 'cond', t.label === 'DEFAULT' ? 'DEFAULT — иначе' : 'когда ' + t.label)
+          );
+          btn.appendChild(
+            el('span', 'to', run ? '→ ' + base(run.ref) + ' ↘' : txt ? txt.label : '→ дальше')
+          );
+        } else if (t.type === 'into') {
+          btn.appendChild(el('span', 'cond', 'войти'));
+          btn.appendChild(el('span', 'to', '→ ' + base(t.label) + ' ↘'));
+        } else {
+          btn.appendChild(el('span', 'cond', 'следующий шаг'));
+          btn.appendChild(el('span', 'to', '→'));
+        }
+        btn.addEventListener('click', () => {
+          moves.push(t.type === 'next' ? { type: 'next' } : { type: t.type, i: t.i });
+          draw();
+        });
+        tr.appendChild(btn);
+      });
+      host.appendChild(tr);
+      container.appendChild(card);
+    }
+
+    const ctl = el('div', 'dbg-controls');
+    const back = el('span', 'dbg-ctl', '← шаг назад');
+    back.addEventListener('click', () => {
+      moves.pop();
+      draw();
+    });
+    const reset = el('span', 'dbg-ctl', '⟲ сброс');
+    reset.addEventListener('click', () => {
+      moves = [];
+      draw();
+    });
+    ctl.appendChild(back);
+    ctl.appendChild(reset);
+    container.appendChild(ctl);
+  }
+  draw();
+}
+
+// ---------- wiring ----------
+function renderLegend() {
+  const box = document.getElementById('legend');
+  LEGEND.forEach((k) => {
+    const meta = KIND[k];
+    const s = el('span');
+    s.appendChild(el('span', 'k ' + meta[0], meta[1]));
+    box.appendChild(s);
+  });
+}
+
+async function main() {
+  renderLegend();
+  const data = await (await fetch('./trace.json')).json();
+  REPO_ROOT = data.repoRoot || '';
+  const list = document.getElementById('skills');
+  const trace = document.getElementById('trace');
+  let cur = 0;
+  const select = (i) => {
+    cur = i;
+    [...list.children].forEach((c, j) => c.classList.toggle('active', j === i));
+    trace.innerHTML = '';
+    const skill = data.skills[i];
+    // skills that aren't XML/HTML-form are listed but not parsed — say so plainly, no tree/debugger.
+    if (skill.attrs?.unsupported) {
+      const box = el('div', 'unsupported-panel');
+      box.appendChild(el('div', 'unsupported-title', skill.label + ' — не поддерживается'));
+      box.appendChild(
+        el(
+          'div',
+          'unsupported-body',
+          'Инспектор разбирает только скилы в XML/HTML-форме (корневой элемент, например <SddSkill>). Этот SKILL.md — markdown/frontmatter, поэтому показать структуру и прогон нельзя.'
+        )
+      );
+      if (skill.detail) box.appendChild(el('div', 'dbg-mut', skill.detail));
+      trace.appendChild(box);
+      return;
+    }
+    const struct = el('div', 'structure');
+    struct.appendChild(el('div', 'section-head', 'Структура промпта'));
+    struct.appendChild(renderNode(skill, 0));
+    trace.appendChild(struct);
+    trace.appendChild(el('div', 'big-div', '▼ Прогон — пошаговый дебаг флоу'));
+    const dbg = el('div', 'dbg');
+    trace.appendChild(dbg);
+    renderDebug(dbg, skill);
+  };
+  data.skills.forEach((s, i) => {
+    const b = el('button', 'skill-btn', s.label);
+    if (s.attrs?.unsupported) b.classList.add('unsupported');
+    b.dataset.idx = i;
+    b.addEventListener('click', () => select(i));
+    list.appendChild(b);
+  });
+  const ed = document.getElementById('editor');
+  if (ed) {
+    ed.value = EDITOR;
+    ed.addEventListener('change', () => {
+      EDITOR = ed.value;
+      localStorage.setItem('inspector.editor', EDITOR);
+      select(cur);
+    });
+  }
+  if (data.skills.length) select(0);
+}
+
+main();