@xera-ai/core 0.3.0 → 0.4.1

package/src/graph/enrich.ts

@@ -0,0 +1,103 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { z } from 'zod';
+import { appendEvents, deriveSnapshot, loadAllEvents } from './store';
+import type { EdgeDiscoveredPayload, Event, TicketEnrichedPayload } from './types';
+import { SCHEMA_VERSION } from './types';
+import { ulid } from './ulid';
+
+const MAX_SIMILAR_EDGES = 10;
+const MIN_CONFIDENCE = 0.7;
+
+const SimilarEntrySchema = z.object({
+  ticketId: z.string().regex(/^[A-Z][A-Z0-9]*-\d+$/),
+  confidence: z.number(),
+  reason: z.string(),
+});
+
+const EnrichmentInputSchema = z.object({
+  similar: z.array(SimilarEntrySchema),
+});
+
+export interface EnrichOptions {
+  force?: boolean;
+}
+
+export interface EnrichResult {
+  ticketId: string;
+  similarCount: number;
+  enrichedAt: string;
+}
+
+const nowIso = () => new Date().toISOString();
+
+const mk = <T extends Event['type']>(
+  actor: string,
+  type: T,
+  payload: Extract<Event, { type: T }>['payload'],
+): Event =>
+  ({
+    event_id: ulid(),
+    schema_version: SCHEMA_VERSION,
+    ts: nowIso(),
+    actor,
+    type,
+    payload,
+  }) as Event;
+
+export async function enrichTicket(
+  repoRoot: string,
+  ticketId: string,
+  opts: EnrichOptions,
+): Promise<EnrichResult> {
+  const inputPath = join(repoRoot, '.xera', ticketId, 'enrichment-input.json');
+  if (!existsSync(inputPath)) {
+    throw new Error(`enrichment-input.json not found at ${inputPath}`);
+  }
+
+  const raw = JSON.parse(readFileSync(inputPath, 'utf8'));
+  const parsed = EnrichmentInputSchema.safeParse(raw);
+  if (!parsed.success) {
+    throw new Error(`invalid enrichment-input.json: ${parsed.error.message}`);
+  }
+
+  const snapshot = deriveSnapshot(loadAllEvents(repoRoot));
+  if (!snapshot.tickets[ticketId]) {
+    throw new Error(`ticket ${ticketId} not in graph; run /xera-fetch first`);
+  }
+
+  if (snapshot.tickets[ticketId]!.enrichedAt && !opts.force) {
+    return { ticketId, similarCount: 0, enrichedAt: snapshot.tickets[ticketId]!.enrichedAt! };
+  }
+
+  const validated = parsed.data.similar
+    .map((s) => ({ ...s, confidence: Math.max(0, Math.min(1, s.confidence)) }))
+    .filter((s) => s.confidence >= MIN_CONFIDENCE)
+    .filter((s) => snapshot.tickets[s.ticketId] !== undefined)
+    .filter((s) => s.ticketId !== ticketId)
+    .slice(0, MAX_SIMILAR_EDGES);
+
+  const events: Event[] = [];
+  for (const s of validated) {
+    const payload: EdgeDiscoveredPayload = {
+      kind: 'similar',
+      from: ticketId,
+      to: s.ticketId,
+      confidence: s.confidence,
+      source: `llm-similarity:${s.reason.slice(0, 80)}`,
+    };
+    events.push(mk('graph-enrich', 'edge.discovered', payload));
+  }
+
+  const enrichedAt = nowIso();
+  const enrichedPayload: TicketEnrichedPayload = {
+    ticketId,
+    enrichedAt,
+    similarCount: validated.length,
+  };
+  events.push(mk('graph-enrich', 'ticket.enriched', enrichedPayload));
+
+  appendEvents(repoRoot, events, { skill: 'graph-enrich', ticketId });
+
+  return { ticketId, similarCount: validated.length, enrichedAt };
+}

package/src/graph/index.ts

@@ -0,0 +1,30 @@
+export type {
+  CandidateEvidence,
+  ClassifyEvidence,
+  ClassifyInput,
+  ClassifyOutput,
+  DecideOutdated,
+  OutdatedDecision,
+} from './classify';
+export {
+  enhanceClassification,
+  findCandidateTickets,
+} from './classify';
+export type { CostSummary, LlmCallLog } from './cost';
+export { logLlmCall, summarizeCost } from './cost';
+export type { EnrichOptions, EnrichResult } from './enrich';
+export { enrichTicket } from './enrich';
+export { currentYyyyMm, graphPaths } from './paths';
+export { EventSchema, safeParseEvent } from './schema';
+export { buildSimilarityPrompt } from './similarity';
+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,142 @@
+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',
+  'TEST_OUTDATED',
+]);
+
+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/similarity.ts

@@ -0,0 +1,43 @@
+import type { TicketNode } from './types';
+
+const MAX_CANDIDATES = 50;
+
+export function buildSimilarityPrompt(target: TicketNode, candidates: TicketNode[]): string {
+  const window = candidates.slice(0, MAX_CANDIDATES);
+  const candidateBlock = window
+    .map((t, i) => {
+      const ac = t.ac.length > 0 ? `\n   AC: ${t.ac.slice(0, 3).join(' | ')}` : '';
+      return `${i + 1}. ${t.id} — ${t.summary}${ac}`;
+    })
+    .join('\n');
+
+  const targetAc =
+    target.ac.length > 0 ? `\nAC:\n${target.ac.map((a) => `  - ${a}`).join('\n')}` : '';
+
+  return `You are evaluating whether a NEW ticket is semantically related to any prior tickets in this project's knowledge graph.
+
+# NEW TICKET
+ID: ${target.id}
+Summary: ${target.summary}${targetAc}
+
+# PRIOR TICKETS (most recent ${window.length} of ${candidates.length})
+${candidateBlock || '(none yet)'}
+
+# Task
+Output a JSON object with shape:
+
+\`\`\`json
+{
+  "similar": [
+    { "ticketId": "<JIRA-KEY>", "confidence": 0.0-1.0, "reason": "<one sentence>" }
+  ]
+}
+\`\`\`
+
+# Rules
+1. Only include candidates with confidence ≥ 0.7. Below that, exclude.
+2. Confidence reflects semantic relatedness (same SUT area, same flow, complementary feature) — NOT just word overlap.
+3. Cap output at 10 entries even if more candidates pass the threshold; pick the highest-confidence ones.
+4. If NO candidates are related, return \`{ "similar": [] }\`. Do not invent relationships.
+5. Output JSON ONLY. No prose, no fences, no commentary.`;
+}

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;
+}