@xera-ai/core 0.9.8 → 0.11.0

package/dist/bin/templates/coverage-panel.html.fragment

@@ -0,0 +1,20 @@
+<section data-tab-panel="coverage" hidden>
+  <nav class="subtabs">
+    <button data-subtab="map" class="active">Map</button>
+    <button data-subtab="list">List</button>
+    <button data-subtab="trend">Trend</button>
+  </nav>
+  <div data-subpanel="map" class="active">
+    <p class="subpanel-hint">Area nodes are colored by status. Red = UNCOVERED, amber = STALE, green = COVERED. Other nodes neutral.</p>
+    <main id="coverage-map-canvas"></main>
+  </div>
+  <div data-subpanel="list" hidden>
+    <table id="coverage-list-table"><thead><tr><th>Status</th><th>Area</th><th>Risk</th><th>Recent tickets</th><th>Recent bugs</th></tr></thead><tbody></tbody></table>
+    <h3>AC Gaps</h3>
+    <table id="coverage-ac-table"><thead><tr><th>Ticket</th><th>Coverage</th><th>Gap</th><th>Unsatisfied</th></tr></thead><tbody></tbody></table>
+  </div>
+  <div data-subpanel="trend" hidden>
+    <p class="subpanel-hint">UNCOVERED + STALE area count over time (one point per day, latest snapshot wins).</p>
+    <div id="coverage-trend-svg"></div>
+  </div>
+</section>

package/dist/bin/templates/graph.css

@@ -340,3 +340,85 @@ body {
 #footer span {
   color: #374151;
 }
+
+/* ─── Coverage tab + subtabs ──────────────────────── */
+.toplevel-tabs {
+  display: flex;
+  gap: 4px;
+}
+.toplevel-tabs button {
+  padding: 6px 12px;
+  border: 0;
+  background: transparent;
+  cursor: pointer;
+  color: #9ca3af;
+}
+.toplevel-tabs button.active {
+  border-bottom: 2px solid #3b82f6;
+  font-weight: bold;
+  color: #e2e8f0;
+}
+[data-tab-panel] {
+  display: none;
+}
+[data-tab-panel].active {
+  display: block;
+}
+.subtabs {
+  display: flex;
+  gap: 4px;
+  padding: 8px;
+}
+.subtabs button {
+  padding: 4px 10px;
+  border: 1px solid #d1d5db;
+  background: white;
+  cursor: pointer;
+}
+.subtabs button.active {
+  background: #3b82f6;
+  color: white;
+}
+[data-subpanel] {
+  padding: 12px;
+}
+.subpanel-hint {
+  color: #6b7280;
+  font-size: 13px;
+  margin: 4px 0 12px;
+}
+#coverage-list-table,
+#coverage-ac-table {
+  border-collapse: collapse;
+  width: 100%;
+  font-size: 13px;
+}
+#coverage-list-table th,
+#coverage-list-table td,
+#coverage-ac-table th,
+#coverage-ac-table td {
+  border: 1px solid #e5e7eb;
+  padding: 6px 10px;
+  text-align: left;
+}
+#coverage-list-table th {
+  background: #f9fafb;
+  cursor: pointer;
+}
+.status-uncovered {
+  background: #fee2e2;
+}
+.status-stale {
+  background: #fef3c7;
+}
+.status-covered {
+  background: #d1fae5;
+}
+#coverage-map-canvas {
+  width: 100%;
+  height: 600px;
+}
+#coverage-trend-svg {
+  width: 100%;
+  min-height: 300px;
+}

package/dist/bin/templates/graph.html.template

@@ -11,6 +11,10 @@
       <div class="logo"></div>
       <span class="title">xera graph</span>
     </div>
+    <nav class="toplevel-tabs">
+      <button data-tab="knowledge" class="active">Knowledge</button>
+      {{COVERAGE_TAB_BUTTON}}
+    </nav>
     <div id="stats-bar" data-stats="{{STATS}}"></div>
     <div class="topbar-controls">
       <input type="text" id="search" placeholder="search nodes…" autocomplete="off" />
@@ -23,21 +27,25 @@
     </div>
   </header>
   <div id="progress-wrap"><div id="progress-bar"></div></div>
-  <main id="canvas"></main>
-  <aside id="sidepanel" class="hidden">
-    <div class="sp-header">
-      <div id="sp-group" class="sp-group-badge"></div>
-      <p id="sp-title" class="sp-title"></p>
-    </div>
-    <div id="sp-desc" class="sp-desc"></div>
-    <div id="sp-actions" class="sp-actions"></div>
-  </aside>
+  <section data-tab-panel="knowledge" class="active">
+    <main id="canvas"></main>
+    <aside id="sidepanel" class="hidden">
+      <div class="sp-header">
+        <div id="sp-group" class="sp-group-badge"></div>
+        <p id="sp-title" class="sp-title"></p>
+      </div>
+      <div id="sp-desc" class="sp-desc"></div>
+      <div id="sp-actions" class="sp-actions"></div>
+    </aside>
+  </section>
+  {{COVERAGE_TAB_PANEL}}
   <footer id="footer">
     generated {{GENERATED_AT}}
     <span>· scroll to zoom · drag to pan · click to inspect</span>
   </footer>
   <script>{{VIS_NETWORK_JS}}</script>
   <script>window.__GRAPH__ = {{GRAPH_DATA}};</script>
+  <script>window.__COVERAGE__ = {{COVERAGE_DATA}};</script>
   <script>{{INTERACTION_JS}}</script>
 </body>
 </html>

package/dist/bin/templates/graph.js

@@ -316,3 +316,188 @@
     };
   });
 })();
+
+// v0.8.1 — top-level tab switching
+(function setupTabs() {
+  const tabButtons = document.querySelectorAll('.toplevel-tabs button');
+  if (!tabButtons.length) return;
+  tabButtons.forEach((btn) => {
+    btn.addEventListener('click', () => {
+      tabButtons.forEach((b) => {
+        b.classList.remove('active');
+      });
+      btn.classList.add('active');
+      const tab = btn.getAttribute('data-tab');
+      document.querySelectorAll('[data-tab-panel]').forEach((panel) => {
+        if (panel.getAttribute('data-tab-panel') === tab) {
+          panel.classList.add('active');
+          panel.removeAttribute('hidden');
+        } else {
+          panel.classList.remove('active');
+        }
+      });
+      if (tab === 'coverage' && window.__COVERAGE__) {
+        renderCoverageOnce();
+      }
+    });
+  });
+})();
+
+// v0.8.1 — coverage subtab switching
+(function setupSubtabs() {
+  const subButtons = document.querySelectorAll('.subtabs button');
+  subButtons.forEach((btn) => {
+    btn.addEventListener('click', () => {
+      subButtons.forEach((b) => {
+        b.classList.remove('active');
+      });
+      btn.classList.add('active');
+      const sub = btn.getAttribute('data-subtab');
+      document.querySelectorAll('[data-subpanel]').forEach((panel) => {
+        if (panel.getAttribute('data-subpanel') === sub) {
+          panel.removeAttribute('hidden');
+          panel.classList.add('active');
+        } else {
+          panel.setAttribute('hidden', '');
+          panel.classList.remove('active');
+        }
+      });
+    });
+  });
+})();
+
+let _coverageRendered = false;
+function renderCoverageOnce() {
+  if (_coverageRendered) return;
+  _coverageRendered = true;
+  renderCoverageList();
+  renderCoverageTrend();
+  renderCoverageMap();
+}
+
+// Task 27 — coverage map: area color overlay
+function renderCoverageMap() {
+  const cov = window.__COVERAGE__;
+  if (!cov || !window.__GRAPH__) return;
+  const canvas = document.getElementById('coverage-map-canvas');
+  if (!canvas) return;
+
+  const STATUS_COLOR = {
+    UNCOVERED: { background: '#fca5a5', border: '#dc2626' },
+    STALE: { background: '#fcd34d', border: '#d97706' },
+    COVERED: { background: '#86efac', border: '#15803d' },
+  };
+  const NEUTRAL = { background: '#e5e7eb', border: '#9ca3af' };
+
+  const areaStatusById = {};
+  for (const a of cov.report.areas) {
+    areaStatusById[a.id] = a.status;
+  }
+
+  const mappedNodes = window.__GRAPH__.nodes.map((n) => {
+    if (n.group === 'SUTArea' && areaStatusById[n.id]) {
+      return Object.assign({}, n, { color: STATUS_COLOR[areaStatusById[n.id]] });
+    }
+    if (n.group !== 'SUTArea') return Object.assign({}, n, { color: NEUTRAL });
+    return n;
+  });
+
+  new vis.Network(
+    canvas,
+    { nodes: new vis.DataSet(mappedNodes), edges: new vis.DataSet(window.__GRAPH__.edges) },
+    {
+      physics: { enabled: true, stabilization: { iterations: 100 } },
+      nodes: { shape: 'dot', font: { size: 11 } },
+    },
+  );
+}
+
+// Task 28 — coverage list: sortable area + AC gap tables
+function renderCoverageList() {
+  const cov = window.__COVERAGE__;
+  if (!cov) return;
+  const listBody = document.querySelector('#coverage-list-table tbody');
+  if (listBody) {
+    listBody.innerHTML = '';
+    for (const a of cov.report.areas) {
+      const tr = document.createElement('tr');
+      tr.classList.add(`status-${a.status.toLowerCase()}`);
+      const cells = [
+        a.status,
+        a.id,
+        String(a.risk),
+        String(a.breakdown.recentTickets),
+        String(a.breakdown.recentBugs),
+      ];
+      for (const c of cells) {
+        const td = document.createElement('td');
+        td.textContent = c;
+        tr.appendChild(td);
+      }
+      listBody.appendChild(tr);
+    }
+  }
+
+  const acBody = document.querySelector('#coverage-ac-table tbody');
+  if (acBody) {
+    acBody.innerHTML = '';
+    for (const t of cov.report.tickets) {
+      const tr = document.createElement('tr');
+      const cells = [
+        t.id,
+        `${t.satisfiedCount}/${t.acCount}`,
+        String(t.gapScore),
+        t.unsatisfiedAcs.map((ac) => `AC-${ac.index}`).join(', '),
+      ];
+      for (const c of cells) {
+        const td = document.createElement('td');
+        td.textContent = c;
+        tr.appendChild(td);
+      }
+      acBody.appendChild(tr);
+    }
+  }
+}
+
+// Task 29 — coverage trend: inline SVG line chart
+function renderCoverageTrend() {
+  const cov = window.__COVERAGE__;
+  if (!cov) return;
+  const container = document.getElementById('coverage-trend-svg');
+  if (!container) return;
+
+  // Dedup by day (latest snapshot per day wins), sort asc.
+  const byDay = {};
+  for (const s of cov.snapshots) {
+    const day = s.ts.slice(0, 10);
+    byDay[day] = s;
+  }
+  const days = Object.keys(byDay).sort();
+  if (days.length === 0) {
+    container.innerHTML =
+      '<p class="subpanel-hint">No snapshots yet — run /xera-coverage on multiple days to build a trend.</p>';
+    return;
+  }
+
+  const points = days.map((d) => {
+    const snap = byDay[d];
+    const n = snap.areas.filter((a) => a.status === 'UNCOVERED' || a.status === 'STALE').length;
+    return { day: d, value: n };
+  });
+  const W = 800;
+  const H = 200;
+  const PAD = 30;
+  const maxValue = Math.max(...points.map((p) => p.value), 1);
+  const stepX = points.length > 1 ? (W - 2 * PAD) / (points.length - 1) : 0;
+  const path = points
+    .map((p, idx) => {
+      const x = PAD + idx * stepX;
+      const y = H - PAD - (p.value / maxValue) * (H - 2 * PAD);
+      return `${idx === 0 ? 'M' : 'L'}${x},${y}`;
+    })
+    .join(' ');
+
+  const labelFirst = points[0].day;
+  const labelLast = points[points.length - 1].day;
+  container.innerHTML = `<svg viewBox="0 0 ${W} ${H}" xmlns="http://www.w3.org/2000/svg"><path d="${path}" fill="none" stroke="#dc2626" stroke-width="2"/><text x="${PAD}" y="${H - 8}" font-size="11" fill="#6b7280">${labelFirst}</text><text x="${W - PAD - 60}" y="${H - 8}" font-size="11" fill="#6b7280">${labelLast}</text><text x="${PAD - 22}" y="${PAD - 4}" font-size="11" fill="#6b7280">${maxValue}</text></svg>`;
+}

package/dist/src/index.js

@@ -396,6 +396,11 @@ var RunSchema = z4.object({
     threshold: z4.number().nonnegative().default(8)
   }).prefault({})
 }).prefault({});
+var CoverageSchema = z4.object({
+  staleAfterDays: z4.number().int().positive().default(30),
+  criticalAreas: z4.array(z4.string().regex(/^[a-z0-9-]+$/)).default([]),
+  autoSnapshotOnCoverage: z4.boolean().default(true)
+}).prefault({});
 var XeraConfigSchema = z4.object({
   jira: JiraSchema,
   web: WebSchema.optional(),
@@ -403,6 +408,7 @@ var XeraConfigSchema = z4.object({
   ai: AISchema,
   reporting: ReportingSchema,
   run: RunSchema.prefault({}),
+  coverage: CoverageSchema,
   adapters: z4.array(z4.enum(["web", "http"])).min(1).default(["web"])
 }).refine((c) => c.web !== undefined || c.http !== undefined, {
   message: "At least one of `web` or `http` must be configured"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xera-ai/core",
-  "version": "0.9.8",
+  "version": "0.11.0",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -31,8 +31,8 @@
   },
   "dependencies": {
     "zod": "4.4.3",
-    "@xera-ai/web": "^0.9.8",
-    "@xera-ai/http": "^0.9.8",
+    "@xera-ai/web": "^0.11.0",
+    "@xera-ai/http": "^0.11.0",
     "@playwright/test": "1.60.0",
     "dotenv": "^16.0.0",
     "fflate": "0.8.3",

package/src/bin-internal/ac-coverage-backfill-finalize.ts

@@ -0,0 +1,90 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { z } from 'zod';
+import { appendEvents } from '../graph/store';
+import type { Event } from '../graph/types';
+import { SCHEMA_VERSION } from '../graph/types';
+import { ulid } from '../graph/ulid';
+
+const DecisionsSchema = z.object({
+  mappings: z.array(
+    z.object({
+      scenarioId: z.string().min(1),
+      satisfiesAcs: z.array(z.number().int().nonnegative()),
+      confidence: z.number().min(0).max(1),
+    }),
+  ),
+});
+
+interface ParsedArgs {
+  inputFile?: string;
+  snapshotTs?: string;
+}
+
+function parseArgs(argv: string[]): ParsedArgs {
+  const args: ParsedArgs = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--input') {
+      const v = argv[++i];
+      if (v !== undefined) args.inputFile = v;
+    } else if (a === '--snapshot-ts') {
+      const v = argv[++i];
+      if (v !== undefined) args.snapshotTs = v;
+    } else if (a === '--help-stub') {
+      /* no-op */
+    } else {
+      console.error(`[ac-coverage-backfill-finalize] unknown flag: ${a}`);
+      return args;
+    }
+  }
+  return args;
+}
+
+export async function acCoverageBackfillFinalizeCmd(argv: string[]): Promise<number> {
+  const args = parseArgs(argv);
+  const cwd = process.cwd();
+  const inputPath = args.inputFile ?? join(cwd, '.xera/coverage/ac-backfill-decisions.json');
+
+  if (!existsSync(inputPath)) {
+    console.error(`[ac-coverage-backfill-finalize] decisions file not found: ${inputPath}`);
+    return 2;
+  }
+
+  let parsed: z.infer<typeof DecisionsSchema>;
+  try {
+    const raw = JSON.parse(readFileSync(inputPath, 'utf8'));
+    parsed = DecisionsSchema.parse(raw);
+  } catch (e) {
+    console.error(`[ac-coverage-backfill-finalize] invalid decisions: ${(e as Error).message}`);
+    return 2;
+  }
+
+  if (parsed.mappings.length === 0) return 0;
+
+  // Group mappings by ticketId (extracted from scenarioId prefix)
+  const byTicket: Record<string, z.infer<typeof DecisionsSchema>['mappings']> = {};
+  for (const m of parsed.mappings) {
+    const ticketId = m.scenarioId.split('#')[0];
+    if (!ticketId) continue;
+    if (!byTicket[ticketId]) byTicket[ticketId] = [];
+    byTicket[ticketId].push(m);
+  }
+
+  const ts = args.snapshotTs ?? new Date().toISOString();
+  const now = new Date(ts);
+
+  for (const [ticketId, mappings] of Object.entries(byTicket)) {
+    const event: Event = {
+      event_id: ulid(),
+      schema_version: SCHEMA_VERSION,
+      ts,
+      actor: 'xera-coverage',
+      type: 'ac-coverage.backfilled',
+      payload: { ts, ticketId, mappings },
+    };
+    appendEvents(cwd, [event], { skill: 'ac-coverage', ticketId, now });
+  }
+
+  return 0;
+}

package/src/bin-internal/ac-coverage-backfill-prepare.ts

@@ -0,0 +1,72 @@
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { deriveSnapshot, loadAllEvents } from '../graph/store';
+import type { Snapshot } from '../graph/types';
+
+interface BackfillInput {
+  tickets: Array<{
+    id: string;
+    summary: string;
+    acs: string[];
+    scenarios: Array<{ id: string; name: string; gherkin: string }>;
+  }>;
+}
+
+function findUnmapped(snap: Snapshot): BackfillInput {
+  const out: BackfillInput['tickets'] = [];
+  for (const ticket of Object.values(snap.tickets)) {
+    if (ticket.ac.length === 0) continue;
+    const ticketScenarios = Object.values(snap.scenarios).filter((s) => s.ticketId === ticket.id);
+    if (ticketScenarios.length === 0) continue;
+    const acsForTicket = Object.values(snap.acNodes).filter((ac) => ac.ticketId === ticket.id);
+    const hasAnyEdge = snap.edges.some(
+      (e) => e.kind === 'satisfies' && acsForTicket.some((ac) => ac.id === e.to),
+    );
+    if (hasAnyEdge) continue;
+    out.push({
+      id: ticket.id,
+      summary: ticket.summary,
+      acs: ticket.ac,
+      scenarios: ticketScenarios.map((s) => ({
+        id: s.id,
+        name: s.name,
+        gherkin: s.gherkin,
+      })),
+    });
+  }
+  return { tickets: out };
+}
+
+interface ParsedArgs {
+  outputFile?: string;
+}
+
+function parseArgs(argv: string[]): ParsedArgs {
+  const args: ParsedArgs = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--output') {
+      const v = argv[++i];
+      if (v !== undefined) args.outputFile = v;
+    } else if (a === '--help-stub') {
+      /* no-op */
+    } else {
+      console.error(`[ac-coverage-backfill-prepare] unknown flag: ${a}`);
+      return args;
+    }
+  }
+  return args;
+}
+
+export async function acCoverageBackfillPrepareCmd(argv: string[]): Promise<number> {
+  const args = parseArgs(argv);
+  const cwd = process.cwd();
+  const snap = deriveSnapshot(loadAllEvents(cwd));
+  const input = findUnmapped(snap);
+
+  const outDir = join(cwd, '.xera/coverage');
+  mkdirSync(outDir, { recursive: true });
+  const outPath = args.outputFile ?? join(outDir, 'ac-backfill-input.json');
+  writeFileSync(outPath, JSON.stringify(input, null, 2));
+  return 0;
+}

package/src/bin-internal/coverage-prepare.ts

@@ -0,0 +1,123 @@
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { loadConfig } from '../config/load';
+import type { XeraConfig } from '../config/schema';
+import {
+  buildCoverageReport,
+  buildWhyArea,
+  buildWhyTicket,
+  type RenderOptions,
+  renderMarkdown,
+} from '../coverage';
+import { appendEvents, deriveSnapshot, loadAllEvents } from '../graph/store';
+import type { Event, Snapshot } from '../graph/types';
+import { ulid } from '../graph/ulid';
+
+interface ParsedArgs {
+  snapshotTs?: string;
+  emitEvent: boolean;
+  why?: string;
+  json: boolean;
+  all: boolean;
+  snapshotFile?: string;
+}
+
+function parseArgs(argv: string[]): ParsedArgs {
+  const args: ParsedArgs = { emitEvent: true, json: false, all: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--snapshot-ts') {
+      const v = argv[++i];
+      if (v !== undefined) args.snapshotTs = v;
+    } else if (a === '--no-emit-event') args.emitEvent = false;
+    else if (a === '--why') {
+      const v = argv[++i];
+      if (v !== undefined) args.why = v;
+    } else if (a === '--json') args.json = true;
+    else if (a === '--all') args.all = true;
+    else if (a === '--snapshot-file') {
+      const v = argv[++i];
+      if (v !== undefined) args.snapshotFile = v;
+    } else if (a === '--help-stub') {
+      /* no-op for test scaffold */
+    } else {
+      console.error(`[coverage-prepare] unknown flag: ${a}`);
+      return { ...args, emitEvent: false };
+    }
+  }
+  return args;
+}
+
+const TICKET_RE = /^[A-Z][A-Z0-9]*-\d+$/;
+
+export async function coveragePrepareCmd(argv: string[]): Promise<number> {
+  const args = parseArgs(argv);
+
+  const cwd = process.cwd();
+  let config: XeraConfig;
+  try {
+    config = await loadConfig(cwd);
+  } catch (e) {
+    console.error(`[coverage-prepare] ${(e as Error).message}`);
+    return 2;
+  }
+
+  let snap: Snapshot;
+  if (args.snapshotFile) {
+    snap = JSON.parse(readFileSync(args.snapshotFile, 'utf8')) as Snapshot;
+  } else {
+    snap = deriveSnapshot(loadAllEvents(cwd));
+  }
+
+  const now = args.snapshotTs ? new Date(args.snapshotTs) : new Date();
+
+  if (args.why) {
+    const out = TICKET_RE.test(args.why)
+      ? buildWhyTicket(args.why, snap, config.coverage, now)
+      : buildWhyArea(args.why, snap, config.coverage, now);
+    process.stdout.write(out);
+    return 0;
+  }
+
+  const report = buildCoverageReport(snap, config.coverage, now);
+
+  if (args.json) {
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+    return 0;
+  }
+
+  const outDir = join(cwd, '.xera/coverage');
+  mkdirSync(outDir, { recursive: true });
+  writeFileSync(join(outDir, 'report.json'), JSON.stringify(report, null, 2));
+  const renderOpts: RenderOptions = { includeCovered: args.all };
+  writeFileSync(join(outDir, 'report.md'), renderMarkdown(report, renderOpts));
+
+  if (args.emitEvent && config.coverage.autoSnapshotOnCoverage) {
+    const event: Event = {
+      event_id: ulid(),
+      schema_version: 1,
+      ts: now.toISOString(),
+      actor: 'xera-coverage',
+      type: 'coverage.snapshot',
+      payload: {
+        ts: now.toISOString(),
+        windowDays: config.coverage.staleAfterDays,
+        areas: report.areas.map((a) => ({
+          id: a.id,
+          status: a.status,
+          risk: a.risk,
+          breakdown: a.breakdown,
+        })),
+        tickets: report.tickets.map((t) => ({
+          id: t.id,
+          acCount: t.acCount,
+          satisfiedCount: t.satisfiedCount,
+          gapScore: t.gapScore,
+        })),
+      },
+    };
+    appendEvents(cwd, [event], { skill: 'coverage', ticketId: 'session', now });
+  }
+
+  return 0;
+}