@xera-ai/core 0.3.0 → 0.4.0

package/src/bin-internal/verify-prompts.ts

@@ -10,6 +10,7 @@ const IN_SCOPE_PROMPTS = [
   'feature-from-story.md',
   'script-from-feature.md',
   'heal-locator.md',
+  'extract-areas.md',
 ] as const;
 
 const REQUIRED_SECTION_HEADING = '## Handling untrusted input';

package/src/config/schema.ts

@@ -19,12 +19,12 @@ const WebSchema = z
       message: 'baseUrl must have at least one environment',
     }),
     defaultEnv: z.string(),
-    auth: AuthSchema.default({}),
+    auth: AuthSchema.prefault({}),
     testData: z
       .object({
         users: z.record(z.string(), z.object({ fromAuth: z.string() })).default({}),
       })
-      .default({ users: {} }),
+      .prefault({}),
   })
   .refine((w) => w.baseUrl[w.defaultEnv] !== undefined, {
     message: 'defaultEnv must exist in baseUrl map',
@@ -51,9 +51,9 @@ const AISchema = z
         lint: z.number().int().min(0).max(5).default(2),
         validateFeature: z.number().int().min(0).max(5).default(2),
       })
-      .default({}),
+      .prefault({}),
   })
-  .default({});
+  .prefault({});
 
 const ReportingSchema = z
   .object({
@@ -64,10 +64,10 @@ const ReportingSchema = z
         onPass: z.string().nullable().default(null),
         onFail: z.string().nullable().default(null),
       })
-      .default({}),
+      .prefault({}),
     artifactLinks: z.enum(['git', 'local']).default('git'),
   })
-  .default({});
+  .prefault({});
 
 export const XeraConfigSchema = z.object({
   jira: JiraSchema,

package/src/graph/cost.ts

@@ -0,0 +1,59 @@
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { graphPaths } from './paths';
+
+export interface LlmCallLog {
+  ts?: string;
+  skill: string;
+  prompt: string;
+  tokensIn: number;
+  tokensOut: number;
+  model: string;
+  costUsd: number;
+}
+
+export function logLlmCall(repoRoot: string, call: LlmCallLog): void {
+  const paths = graphPaths(repoRoot);
+  mkdirSync(dirname(paths.costLog), { recursive: true });
+  const record = {
+    ts: call.ts ?? new Date().toISOString(),
+    skill: call.skill,
+    prompt: call.prompt,
+    tokens_in: call.tokensIn,
+    tokens_out: call.tokensOut,
+    model: call.model,
+    cost_estimate_usd: call.costUsd,
+  };
+  appendFileSync(paths.costLog, `${JSON.stringify(record)}\n`);
+}
+
+export interface CostSummary {
+  totalCalls: number;
+  totalUsd: number;
+  bySkill: Record<string, { calls: number; usd: number }>;
+  windowDays: number;
+}
+
+export function summarizeCost(repoRoot: string, daysBack: number): CostSummary {
+  const paths = graphPaths(repoRoot);
+  const result: CostSummary = { totalCalls: 0, totalUsd: 0, bySkill: {}, windowDays: daysBack };
+  if (!existsSync(paths.costLog)) return result;
+  const cutoff = Date.now() - daysBack * 86400 * 1000;
+  for (const line of readFileSync(paths.costLog, 'utf8').split('\n')) {
+    if (!line.trim()) continue;
+    let row: { ts: string; skill: string; cost_estimate_usd: number };
+    try {
+      row = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    if (Date.parse(row.ts) < cutoff) continue;
+    result.totalCalls++;
+    result.totalUsd += row.cost_estimate_usd;
+    if (!result.bySkill[row.skill]) result.bySkill[row.skill] = { calls: 0, usd: 0 };
+    const s = result.bySkill[row.skill]!;
+    s.calls++;
+    s.usd += row.cost_estimate_usd;
+  }
+  return result;
+}

package/src/graph/index.ts

@@ -0,0 +1,15 @@
+export type { CostSummary, LlmCallLog } from './cost';
+export { logLlmCall, summarizeCost } from './cost';
+export { currentYyyyMm, graphPaths } from './paths';
+export { EventSchema, safeParseEvent } from './schema';
+export {
+  appendEvents,
+  computeEventsHash,
+  deriveSnapshot,
+  isSnapshotStale,
+  loadAllEvents,
+  loadSnapshot,
+  writeSnapshot,
+} from './store';
+export * from './types';
+export { ulid } from './ulid';

package/src/graph/paths.ts

@@ -0,0 +1,27 @@
+import { join } from 'node:path';
+
+export interface GraphPaths {
+  eventsDir: string;
+  snapshotFile: string;
+  costLog: string;
+  eventsMonthDir(yyyyMm: string): string;
+  eventFile(ulid: string, skill: string, ticketId: string, yyyyMm: string): string;
+}
+
+export function graphPaths(repoRoot: string): GraphPaths {
+  const eventsDir = join(repoRoot, '.xera/graph/events');
+  return {
+    eventsDir,
+    snapshotFile: join(repoRoot, '.xera/graph/snapshot.json'),
+    costLog: join(repoRoot, '.xera/cost-log.jsonl'),
+    eventsMonthDir: (yyyyMm) => join(eventsDir, yyyyMm),
+    eventFile: (ulid, skill, ticketId, yyyyMm) =>
+      join(eventsDir, yyyyMm, `${ulid}-${skill}-${ticketId}.jsonl`),
+  };
+}
+
+export function currentYyyyMm(now: Date = new Date()): string {
+  const y = now.getUTCFullYear();
+  const m = String(now.getUTCMonth() + 1).padStart(2, '0');
+  return `${y}-${m}`;
+}

package/src/graph/schema.ts

@@ -0,0 +1,135 @@
+import { z } from 'zod';
+import type { Event } from './types';
+import { SCHEMA_VERSION } from './types';
+
+const schemaV = z.literal(SCHEMA_VERSION);
+const iso = z.string().datetime({ offset: false });
+
+const ticketFetched = z
+  .object({
+    ticketId: z.string().regex(/^[A-Z][A-Z0-9]*-\d+$/),
+    summary: z.string(),
+    ac: z.array(z.string()),
+    jiraLinks: z.array(
+      z.object({
+        ticketId: z.string().regex(/^[A-Z][A-Z0-9]*-\d+$/),
+        relation: z.enum(['blocks', 'duplicates', 'relates', 'supersedes']),
+      }),
+    ),
+    storyHash: z.string(),
+    modifiesAreas: z.array(z.string().regex(/^[a-z0-9-]+$/)),
+  })
+  .passthrough();
+
+const ticketEnriched = z
+  .object({
+    ticketId: z.string(),
+    enrichedAt: iso,
+    similarCount: z.number().int().nonnegative(),
+  })
+  .passthrough();
+
+const scenarioGenerated = z
+  .object({
+    scenarioId: z.string(),
+    ticketId: z.string(),
+    name: z.string(),
+    gherkin: z.string(),
+    priority: z.enum(['p0', 'p1', 'p2']),
+    featureHash: z.string(),
+    generatedAt: iso,
+  })
+  .passthrough();
+
+const pomGenerated = z
+  .object({
+    pomId: z.string(),
+    ticketId: z.string(),
+    filePath: z.string(),
+    route: z.string(),
+    locators: z.array(z.string()),
+    scope: z.enum(['local', 'shared']),
+  })
+  .passthrough();
+
+const pomPromoted = z
+  .object({
+    pomId: z.string(),
+    fromPath: z.string(),
+    toPath: z.string(),
+  })
+  .passthrough();
+
+const runCompleted = z
+  .object({
+    scenarioId: z.string(),
+    ticketId: z.string(),
+    runId: z.string(),
+    status: z.enum(['pass', 'fail']),
+    traceId: z.string().optional(),
+    runtime: z.number().nonnegative(),
+  })
+  .passthrough();
+
+const classification = z.enum(['REAL_BUG', 'TEST_BUG', 'SELECTOR_DRIFT', 'FLAKY', 'PASS']);
+
+const runClassified = z
+  .object({
+    scenarioId: z.string(),
+    runId: z.string(),
+    classification,
+    confidence: z.enum(['low', 'medium', 'high']),
+  })
+  .passthrough();
+
+const classificationDisputed = z
+  .object({
+    runId: z.string(),
+    scenarioId: z.string(),
+    originalClassification: classification,
+    disputedTo: classification,
+    qaActor: z.string(),
+    qaReason: z.string().optional(),
+  })
+  .passthrough();
+
+const edgeDiscovered = z
+  .object({
+    kind: z.enum(['tests', 'uses', 'covers', 'modifies', 'jira-linked', 'similar', 'ran']),
+    from: z.string(),
+    to: z.string(),
+    confidence: z.number().min(0).max(1).optional(),
+    source: z.string(),
+  })
+  .passthrough();
+
+const base = {
+  event_id: z.string().min(20),
+  schema_version: schemaV,
+  ts: iso,
+  actor: z.string(),
+};
+
+export const EventSchema = z.discriminatedUnion('type', [
+  z.object({ ...base, type: z.literal('ticket.fetched'), payload: ticketFetched }),
+  z.object({ ...base, type: z.literal('ticket.enriched'), payload: ticketEnriched }),
+  z.object({ ...base, type: z.literal('scenario.generated'), payload: scenarioGenerated }),
+  z.object({ ...base, type: z.literal('pom.generated'), payload: pomGenerated }),
+  z.object({ ...base, type: z.literal('pom.promoted'), payload: pomPromoted }),
+  z.object({ ...base, type: z.literal('run.completed'), payload: runCompleted }),
+  z.object({ ...base, type: z.literal('run.classified'), payload: runClassified }),
+  z.object({
+    ...base,
+    type: z.literal('classification.disputed'),
+    payload: classificationDisputed,
+  }),
+  z.object({ ...base, type: z.literal('edge.discovered'), payload: edgeDiscovered }),
+]);
+
+export function safeParseEvent(
+  value: unknown,
+): { success: true; data: Event } | { success: false; error: z.ZodError } {
+  const r = EventSchema.safeParse(value);
+  if (r.success) return { success: true, data: r.data as Event };
+  return { success: false, error: r.error };
+}

package/src/graph/store.ts

@@ -0,0 +1,231 @@
+import { createHash } from 'node:crypto';
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  renameSync,
+  writeFileSync,
+} from 'node:fs';
+import { dirname } from 'node:path';
+import { currentYyyyMm, graphPaths } from './paths';
+import { safeParseEvent } from './schema';
+import type {
+  EdgeRecord,
+  Event,
+  FailureNode,
+  PomNode,
+  ScenarioNode,
+  Snapshot,
+  TicketNode,
+} from './types';
+import { SCHEMA_VERSION } from './types';
+
+export interface AppendOptions {
+  skill: string;
+  ticketId: string;
+  now?: Date;
+}
+
+export function appendEvents(repoRoot: string, events: Event[], opts: AppendOptions): string {
+  if (events.length === 0) return '';
+  const paths = graphPaths(repoRoot);
+  const yyyyMm = currentYyyyMm(opts.now);
+  const monthDir = paths.eventsMonthDir(yyyyMm);
+  mkdirSync(monthDir, { recursive: true });
+  const ulid = events[0]!.event_id;
+  const finalPath = paths.eventFile(ulid, opts.skill, opts.ticketId, yyyyMm);
+  const tmpPath = `${finalPath}.tmp`;
+  const body = `${events.map((e) => JSON.stringify(e)).join('\n')}\n`;
+  writeFileSync(tmpPath, body);
+  renameSync(tmpPath, finalPath);
+  return finalPath;
+}
+
+export function loadAllEvents(repoRoot: string): Event[] {
+  const paths = graphPaths(repoRoot);
+  if (!existsSync(paths.eventsDir)) return [];
+  const files: string[] = [];
+  for (const monthDir of readdirSync(paths.eventsDir, { withFileTypes: true })) {
+    if (!monthDir.isDirectory()) continue;
+    const monthPath = paths.eventsMonthDir(monthDir.name);
+    for (const f of readdirSync(monthPath)) {
+      if (f.endsWith('.jsonl')) files.push(`${monthPath}/${f}`);
+    }
+  }
+  files.sort((a, b) => {
+    const ua = a.split('/').pop()!.split('-')[0]!;
+    const ub = b.split('/').pop()!.split('-')[0]!;
+    return ua < ub ? -1 : ua > ub ? 1 : 0;
+  });
+  const events: Event[] = [];
+  for (const file of files) {
+    try {
+      const lines = readFileSync(file, 'utf8').split('\n').filter(Boolean);
+      for (const line of lines) {
+        let parsed: unknown;
+        try {
+          parsed = JSON.parse(line);
+        } catch {
+          console.warn(`[graph.store] skip-line bad-json ${file}`);
+          continue;
+        }
+        const r = safeParseEvent(parsed);
+        if (!r.success) {
+          console.warn(`[graph.store] skip-line invalid ${file}`);
+          continue;
+        }
+        events.push(r.data);
+      }
+    } catch (e) {
+      console.warn(`[graph.store] skip-file ${file} ${(e as Error).message}`);
+    }
+  }
+  events.sort((a, b) => (a.event_id < b.event_id ? -1 : a.event_id > b.event_id ? 1 : 0));
+  return events;
+}
+
+export function computeEventsHash(events: Event[]): string {
+  const h = createHash('sha256');
+  for (const e of events) h.update(e.event_id);
+  return `sha256:${h.digest('hex')}`;
+}
+
+export function deriveSnapshot(events: Event[]): Snapshot {
+  const tickets: Record<string, TicketNode> = {};
+  const scenarios: Record<string, ScenarioNode> = {};
+  const poms: Record<string, PomNode> = {};
+  const areas: Record<string, { id: string }> = {};
+  const edges: EdgeRecord[] = [];
+  const latestFailures: Record<string, FailureNode> = {};
+
+  for (const e of events) {
+    switch (e.type) {
+      case 'ticket.fetched':
+        tickets[e.payload.ticketId] = {
+          id: e.payload.ticketId,
+          summary: e.payload.summary,
+          ac: e.payload.ac,
+          storyHash: e.payload.storyHash,
+          modifiesAreas: e.payload.modifiesAreas,
+          fetchedAt: e.ts,
+        };
+        for (const a of e.payload.modifiesAreas) areas[a] = { id: a };
+        for (const link of e.payload.jiraLinks) {
+          edges.push({
+            kind: 'jira-linked',
+            from: e.payload.ticketId,
+            to: link.ticketId,
+            source: `jira:${link.relation}`,
+            discoveredAt: e.ts,
+          });
+        }
+        break;
+      case 'ticket.enriched':
+        if (tickets[e.payload.ticketId])
+          tickets[e.payload.ticketId]!.enrichedAt = e.payload.enrichedAt;
+        break;
+      case 'scenario.generated':
+        scenarios[e.payload.scenarioId] = {
+          id: e.payload.scenarioId,
+          ticketId: e.payload.ticketId,
+          name: e.payload.name,
+          gherkin: e.payload.gherkin,
+          priority: e.payload.priority,
+          featureHash: e.payload.featureHash,
+          generatedAt: e.payload.generatedAt,
+        };
+        edges.push({
+          kind: 'tests',
+          from: e.payload.ticketId,
+          to: e.payload.scenarioId,
+          source: 'xera-script',
+          discoveredAt: e.ts,
+        });
+        break;
+      case 'pom.generated':
+        poms[e.payload.pomId] = {
+          id: e.payload.pomId,
+          ticketId: e.payload.ticketId,
+          filePath: e.payload.filePath,
+          route: e.payload.route,
+          locators: e.payload.locators,
+          scope: e.payload.scope,
+        };
+        break;
+      case 'pom.promoted':
+        if (poms[e.payload.pomId]) {
+          poms[e.payload.pomId]!.filePath = e.payload.toPath;
+          poms[e.payload.pomId]!.scope = 'shared';
+        }
+        break;
+      case 'run.completed':
+        if (e.payload.status === 'fail') {
+          const fail: FailureNode = {
+            id: `${e.payload.runId}:${e.payload.scenarioId}`,
+            scenarioId: e.payload.scenarioId,
+            runId: e.payload.runId,
+            ts: e.ts,
+          };
+          if (e.payload.traceId) fail.traceId = e.payload.traceId;
+          latestFailures[e.payload.scenarioId] = fail;
+        } else {
+          delete latestFailures[e.payload.scenarioId];
+        }
+        break;
+      case 'edge.discovered': {
+        const ed: EdgeRecord = {
+          kind: e.payload.kind,
+          from: e.payload.from,
+          to: e.payload.to,
+          source: e.payload.source,
+          discoveredAt: e.ts,
+        };
+        if (e.payload.confidence !== undefined) ed.confidence = e.payload.confidence;
+        edges.push(ed);
+        break;
+      }
+      // run.classified and classification.disputed: not materialized in v0.6.0 snapshot
+      default:
+        break;
+    }
+  }
+
+  return {
+    schema_version: SCHEMA_VERSION,
+    generated_at: new Date().toISOString(),
+    event_count: events.length,
+    events_hash: computeEventsHash(events),
+    tickets,
+    scenarios,
+    poms,
+    areas,
+    edges,
+    latest_failures: latestFailures,
+  };
+}
+
+export function writeSnapshot(repoRoot: string, snap: Snapshot): void {
+  const paths = graphPaths(repoRoot);
+  mkdirSync(dirname(paths.snapshotFile), { recursive: true });
+  const tmp = `${paths.snapshotFile}.tmp`;
+  writeFileSync(tmp, JSON.stringify(snap, null, 2));
+  renameSync(tmp, paths.snapshotFile);
+}
+
+export function loadSnapshot(repoRoot: string): Snapshot | null {
+  const paths = graphPaths(repoRoot);
+  if (!existsSync(paths.snapshotFile)) return null;
+  try {
+    return JSON.parse(readFileSync(paths.snapshotFile, 'utf8')) as Snapshot;
+  } catch {
+    return null;
+  }
+}
+
+export function isSnapshotStale(repoRoot: string): boolean {
+  const snap = loadSnapshot(repoRoot);
+  if (!snap) return true;
+  const liveHash = computeEventsHash(loadAllEvents(repoRoot));
+  return snap.events_hash !== liveHash;
+}

package/src/graph/types.ts

@@ -0,0 +1,174 @@
+// Schema v1 — see docs/superpowers/specs/2026-05-16-xera-v06-project-knowledge-graph-design.md §3
+
+export const SCHEMA_VERSION = 1 as const;
+
+export type Priority = 'p0' | 'p1' | 'p2';
+export type ScenarioStatus = 'pass' | 'fail';
+export type EdgeKind = 'tests' | 'uses' | 'covers' | 'modifies' | 'jira-linked' | 'similar' | 'ran';
+
+export type Classification = 'REAL_BUG' | 'TEST_BUG' | 'SELECTOR_DRIFT' | 'FLAKY' | 'PASS';
+// Note: TEST_OUTDATED is added in v0.6.1.
+
+export interface TicketFetchedPayload {
+  ticketId: string;
+  summary: string;
+  ac: string[];
+  jiraLinks: Array<{
+    ticketId: string;
+    relation: 'blocks' | 'duplicates' | 'relates' | 'supersedes';
+  }>;
+  storyHash: string;
+  modifiesAreas: string[];
+}
+
+export interface TicketEnrichedPayload {
+  ticketId: string;
+  enrichedAt: string;
+  similarCount: number;
+}
+
+export interface ScenarioGeneratedPayload {
+  scenarioId: string;
+  ticketId: string;
+  name: string;
+  gherkin: string;
+  priority: Priority;
+  featureHash: string;
+  generatedAt: string;
+}
+
+export interface PomGeneratedPayload {
+  pomId: string;
+  ticketId: string;
+  filePath: string;
+  route: string;
+  locators: string[];
+  scope: 'local' | 'shared';
+}
+
+export interface PomPromotedPayload {
+  pomId: string;
+  fromPath: string;
+  toPath: string;
+}
+
+export interface RunCompletedPayload {
+  scenarioId: string;
+  ticketId: string;
+  runId: string;
+  status: ScenarioStatus;
+  traceId?: string;
+  runtime: number;
+}
+
+export interface RunClassifiedPayload {
+  scenarioId: string;
+  runId: string;
+  classification: Classification;
+  confidence: 'low' | 'medium' | 'high';
+}
+
+export interface ClassificationDisputedPayload {
+  runId: string;
+  scenarioId: string;
+  originalClassification: Classification;
+  disputedTo: Classification;
+  qaActor: string;
+  qaReason?: string;
+}
+
+export interface EdgeDiscoveredPayload {
+  kind: EdgeKind;
+  from: string;
+  to: string;
+  confidence?: number;
+  source: string;
+}
+
+export type EventPayloadMap = {
+  'ticket.fetched': TicketFetchedPayload;
+  'ticket.enriched': TicketEnrichedPayload;
+  'scenario.generated': ScenarioGeneratedPayload;
+  'pom.generated': PomGeneratedPayload;
+  'pom.promoted': PomPromotedPayload;
+  'run.completed': RunCompletedPayload;
+  'run.classified': RunClassifiedPayload;
+  'classification.disputed': ClassificationDisputedPayload;
+  'edge.discovered': EdgeDiscoveredPayload;
+};
+
+export type EventType = keyof EventPayloadMap;
+
+export type Event = {
+  [K in EventType]: {
+    event_id: string;
+    schema_version: typeof SCHEMA_VERSION;
+    ts: string;
+    actor: string;
+    type: K;
+    payload: EventPayloadMap[K];
+  };
+}[EventType];
+
+export interface TicketNode {
+  id: string;
+  summary: string;
+  ac: string[];
+  storyHash: string;
+  modifiesAreas: string[];
+  fetchedAt: string;
+  enrichedAt?: string;
+}
+
+export interface ScenarioNode {
+  id: string;
+  ticketId: string;
+  name: string;
+  gherkin: string;
+  priority: Priority;
+  featureHash: string;
+  generatedAt: string;
+}
+
+export interface PomNode {
+  id: string;
+  ticketId: string;
+  filePath: string;
+  route: string;
+  locators: string[];
+  scope: 'local' | 'shared';
+}
+
+export interface AreaNode {
+  id: string;
+}
+
+export interface FailureNode {
+  id: string;
+  scenarioId: string;
+  runId: string;
+  traceId?: string;
+  ts: string;
+}
+
+export interface EdgeRecord {
+  kind: EdgeKind;
+  from: string;
+  to: string;
+  confidence?: number;
+  source: string;
+  discoveredAt: string;
+}
+
+export interface Snapshot {
+  schema_version: typeof SCHEMA_VERSION;
+  generated_at: string;
+  event_count: number;
+  events_hash: string;
+  tickets: Record<string, TicketNode>;
+  scenarios: Record<string, ScenarioNode>;
+  poms: Record<string, PomNode>;
+  areas: Record<string, AreaNode>;
+  edges: EdgeRecord[];
+  latest_failures: Record<string, FailureNode>;
+}