@xera-ai/core 0.4.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

@@ -1,7 +1,22 @@
+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,

package/src/graph/schema.ts

@@ -71,7 +71,14 @@ const runCompleted = z
   })
   .passthrough();
 
-const classification = z.enum(['REAL_BUG', 'TEST_BUG', 'SELECTOR_DRIFT', 'FLAKY', 'PASS']);
+const classification = z.enum([
+  'REAL_BUG',
+  'TEST_BUG',
+  'SELECTOR_DRIFT',
+  'FLAKY',
+  'PASS',
+  'TEST_OUTDATED',
+]);
 
 const runClassified = z
   .object({

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/types.ts

@@ -6,8 +6,13 @@ 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 type Classification =
+  | 'REAL_BUG'
+  | 'TEST_BUG'
+  | 'SELECTOR_DRIFT'
+  | 'FLAKY'
+  | 'PASS'
+  | 'TEST_OUTDATED';
 
 export interface TicketFetchedPayload {
   ticketId: string;