@xera-ai/core 0.4.0 → 0.4.2

package/src/graph/classify.ts

@@ -0,0 +1,126 @@
+import type { Classification, ScenarioNode, Snapshot, TicketNode } from './types';
+
+export interface ClassifyInput {
+  scenarioId: string;
+  traceClassification: Classification;
+}
+
+export interface CandidateEvidence {
+  ticketId: string;
+  summary: string;
+  modifiedArea: string;
+  relevantAcRef?: string;
+}
+
+export interface ClassifyEvidence {
+  candidateTickets?: CandidateEvidence[];
+  reasoning?: string;
+  expectedByTest?: string;
+  actualInApp?: string;
+  proposedAction?: 'regenerate-scenario' | 'review-and-decide';
+}
+
+export interface ClassifyOutput {
+  classification: Classification;
+  confidence: number;
+  evidence?: ClassifyEvidence;
+}
+
+export interface OutdatedDecision {
+  classification: 'TEST_OUTDATED' | 'BUG' | 'AMBIGUOUS';
+  confidence: number;
+  evidence: {
+    reasoning: string;
+    expectedByTest?: string;
+    actualInApp?: string;
+    relevantAcRef?: string;
+  };
+}
+
+export type DecideOutdated = (args: {
+  scenario: ScenarioNode;
+  candidates: TicketNode[];
+}) => Promise<OutdatedDecision>;
+
+const DEFAULT_THRESHOLD = 0.7;
+const SHORT_CIRCUIT: Classification[] = ['FLAKY', 'PASS'];
+
+export function findCandidateTickets(graph: Snapshot, scenario: ScenarioNode): TicketNode[] {
+  const poms = graph.edges
+    .filter((e) => e.kind === 'uses' && e.from === scenario.id)
+    .map((e) => e.to);
+  if (poms.length === 0) return [];
+
+  const areas = graph.edges
+    .filter((e) => e.kind === 'covers' && poms.includes(e.from))
+    .map((e) => e.to);
+  if (areas.length === 0) return [];
+
+  const ticketIds = graph.edges
+    .filter((e) => e.kind === 'modifies' && areas.includes(e.to))
+    .map((e) => e.from);
+
+  const seen = new Set<string>();
+  const out: TicketNode[] = [];
+  for (const id of ticketIds) {
+    if (seen.has(id)) continue;
+    seen.add(id);
+    if (id === scenario.ticketId) continue;
+    const t = graph.tickets[id];
+    if (!t) continue;
+    if (t.fetchedAt <= scenario.generatedAt) continue;
+    out.push(t);
+  }
+  return out;
+}
+
+export async function enhanceClassification(
+  input: ClassifyInput,
+  graph: Snapshot,
+  decideOutdated: DecideOutdated,
+  options: { threshold?: number } = {},
+): Promise<ClassifyOutput> {
+  const threshold = options.threshold ?? DEFAULT_THRESHOLD;
+  if (SHORT_CIRCUIT.includes(input.traceClassification)) {
+    return { classification: input.traceClassification, confidence: 1 };
+  }
+
+  const scenario = graph.scenarios[input.scenarioId];
+  if (!scenario) return { classification: input.traceClassification, confidence: 1 };
+
+  const candidates = findCandidateTickets(graph, scenario);
+  if (candidates.length === 0) {
+    return { classification: input.traceClassification, confidence: 1 };
+  }
+
+  const candidateEvidence: CandidateEvidence[] = candidates.map((t) => {
+    const area = graph.edges.find((e) => e.kind === 'modifies' && e.from === t.id)?.to ?? '';
+    const ev: CandidateEvidence = { ticketId: t.id, summary: t.summary, modifiedArea: area };
+    if (t.ac[0]) ev.relevantAcRef = t.ac[0];
+    return ev;
+  });
+
+  const decision = await decideOutdated({ scenario, candidates });
+
+  if (decision.classification === 'TEST_OUTDATED' && decision.confidence >= threshold) {
+    const evidence: ClassifyEvidence = {
+      candidateTickets: candidateEvidence,
+      reasoning: decision.evidence.reasoning,
+      proposedAction: 'regenerate-scenario',
+    };
+    if (decision.evidence.expectedByTest)
+      evidence.expectedByTest = decision.evidence.expectedByTest;
+    if (decision.evidence.actualInApp) evidence.actualInApp = decision.evidence.actualInApp;
+    return {
+      classification: 'TEST_OUTDATED',
+      confidence: decision.confidence,
+      evidence,
+    };
+  }
+
+  return {
+    classification: input.traceClassification,
+    confidence: 1,
+    evidence: { candidateTickets: candidateEvidence },
+  };
+}

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

@@ -0,0 +1,262 @@
+import type { EdgeKind, Priority, Snapshot, TicketNode } from './types';
+
+export interface ImpactEdge {
+  kind: EdgeKind;
+  from: string;
+  to: string;
+  confidence?: number;
+  source?: string;
+}
+
+export interface ImpactScenario {
+  scenarioId: string;
+  ticketId: string; // owner of the scenario (NOT the impact target)
+  name: string;
+  priority: Priority;
+  edgePath: ImpactEdge[];
+  riskScore: number;
+  lastPassedAt?: string;
+}
+
+export interface ImpactOpts {
+  depth: 1 | 2 | 3;
+  minPriority?: Priority;
+}
+
+export interface ImpactReport {
+  targetTicket: string;
+  modifiedAreas: string[];
+  scenarios: ImpactScenario[];
+  generatedAt: string;
+}
+
+const PRIORITY_WEIGHT: Record<Priority, number> = { p0: 3, p1: 2, p2: 1 };
+
+const EDGE_WEIGHT_FIXED: Partial<Record<EdgeKind, number>> = {
+  modifies: 5, // direct collision via SUT area
+  uses: 4, // shared POM
+  covers: 4, // shared POM (alt path)
+  // 'jira-linked' weight is dynamic — see jiraRelationWeight
+};
+
+function jiraRelationWeight(source?: string): number {
+  if (!source) return 0;
+  if (source.endsWith('blocks')) return 4;
+  if (source.endsWith('duplicates')) return 3;
+  if (source.endsWith('relates')) return 2;
+  if (source.endsWith('supersedes')) return 3;
+  return 1;
+}
+
+function edgeWeight(edge: ImpactEdge): number {
+  if (edge.kind === 'modifies') return EDGE_WEIGHT_FIXED.modifies ?? 0;
+  if (edge.kind === 'uses' || edge.kind === 'covers') return EDGE_WEIGHT_FIXED.uses ?? 0;
+  if (edge.kind === 'jira-linked') return jiraRelationWeight(edge.source);
+  if (edge.kind === 'similar') return 1 * (edge.confidence ?? 0);
+  return 0;
+}
+
+export function riskScore(scenario: ImpactScenario, daysSinceLastPass: number): number {
+  const pri = PRIORITY_WEIGHT[scenario.priority] * 3;
+  const firstEdge = scenario.edgePath[0];
+  const edgeW = firstEdge ? edgeWeight(firstEdge) : 0;
+  const confW = firstEdge?.confidence !== undefined ? firstEdge.confidence * 2 : 0;
+  const decay = daysSinceLastPass * 0.1;
+  return pri + edgeW + confW - decay;
+}
+
+const PRIORITY_RANK: Record<Priority, number> = { p0: 3, p1: 2, p2: 1 };
+
+function daysSince(ts: string | undefined): number {
+  if (!ts) return 0;
+  const ms = Date.now() - Date.parse(ts);
+  return ms < 0 ? 0 : ms / (86400 * 1000);
+}
+
+export function walkImpact(
+  graph: Snapshot,
+  target: TicketNode,
+  opts: ImpactOpts,
+): ImpactScenario[] {
+  const result: ImpactScenario[] = [];
+  const seen = new Set<string>();
+
+  // Areas the target modifies
+  const targetAreas = new Set(target.modifiesAreas);
+
+  // POMs covering any of those areas
+  const pomIds = graph.edges
+    .filter((e) => e.kind === 'covers' && targetAreas.has(e.to))
+    .map((e) => e.from);
+
+  // Scenarios using any of those POMs (depth 1 — direct collision)
+  const directScenarios = graph.edges
+    .filter((e) => e.kind === 'uses' && pomIds.includes(e.to))
+    .map((e) => e.from);
+
+  for (const scenarioId of directScenarios) {
+    if (seen.has(scenarioId)) continue;
+    const scenario = graph.scenarios[scenarioId];
+    if (!scenario) continue;
+    if (scenario.ticketId === target.id) continue; // exclude own scenarios
+
+    const usingPom = graph.edges.find((e) => e.kind === 'uses' && e.from === scenarioId);
+    const modifyEdge = graph.edges.find(
+      (e) => e.kind === 'modifies' && e.from === target.id && targetAreas.has(e.to),
+    );
+    const edgePath: ImpactEdge[] = [];
+    if (modifyEdge) edgePath.push({ kind: 'modifies', from: modifyEdge.from, to: modifyEdge.to });
+    if (usingPom) edgePath.push({ kind: 'uses', from: usingPom.from, to: usingPom.to });
+
+    seen.add(scenarioId);
+    const impact: ImpactScenario = {
+      scenarioId,
+      ticketId: scenario.ticketId,
+      name: scenario.name,
+      priority: scenario.priority,
+      edgePath,
+      riskScore: 0,
+    };
+    impact.riskScore = riskScore(impact, daysSince(graph.latest_failures[scenarioId]?.ts));
+    result.push(impact);
+  }
+
+  // Depth >= 2: jira-linked tickets contribute their scenarios
+  if (opts.depth >= 2) {
+    const linked = graph.edges
+      .filter((e) => e.kind === 'jira-linked' && e.from === target.id)
+      .map((e) => ({ to: e.to, source: e.source }));
+    for (const link of linked) {
+      const sceneIds = graph.edges
+        .filter((e) => e.kind === 'tests' && e.from === link.to)
+        .map((e) => e.to);
+      for (const scenarioId of sceneIds) {
+        if (seen.has(scenarioId)) continue;
+        const scenario = graph.scenarios[scenarioId];
+        if (!scenario || scenario.ticketId === target.id) continue;
+        seen.add(scenarioId);
+        const edge: ImpactEdge = { kind: 'jira-linked', from: target.id, to: link.to };
+        if (link.source !== undefined) edge.source = link.source;
+        const impact: ImpactScenario = {
+          scenarioId,
+          ticketId: scenario.ticketId,
+          name: scenario.name,
+          priority: scenario.priority,
+          edgePath: [edge],
+          riskScore: 0,
+        };
+        impact.riskScore = riskScore(impact, daysSince(graph.latest_failures[scenarioId]?.ts));
+        result.push(impact);
+      }
+    }
+  }
+
+  // Depth >= 3: similar tickets contribute their scenarios
+  if (opts.depth >= 3) {
+    const similar = graph.edges
+      .filter((e) => e.kind === 'similar' && e.from === target.id)
+      .map((e) => ({ to: e.to, confidence: e.confidence }));
+    for (const link of similar) {
+      const sceneIds = graph.edges
+        .filter((e) => e.kind === 'tests' && e.from === link.to)
+        .map((e) => e.to);
+      for (const scenarioId of sceneIds) {
+        if (seen.has(scenarioId)) continue;
+        const scenario = graph.scenarios[scenarioId];
+        if (!scenario || scenario.ticketId === target.id) continue;
+        seen.add(scenarioId);
+        const edge: ImpactEdge = { kind: 'similar', from: target.id, to: link.to };
+        if (link.confidence !== undefined) edge.confidence = link.confidence;
+        const impact: ImpactScenario = {
+          scenarioId,
+          ticketId: scenario.ticketId,
+          name: scenario.name,
+          priority: scenario.priority,
+          edgePath: [edge],
+          riskScore: 0,
+        };
+        impact.riskScore = riskScore(impact, daysSince(graph.latest_failures[scenarioId]?.ts));
+        result.push(impact);
+      }
+    }
+  }
+
+  // Filter by min-priority
+  let filtered = result;
+  if (opts.minPriority) {
+    const min = PRIORITY_RANK[opts.minPriority];
+    filtered = filtered.filter((s) => PRIORITY_RANK[s.priority] >= min);
+  }
+
+  // Sort by riskScore descending
+  filtered.sort((a, b) => b.riskScore - a.riskScore);
+  return filtered;
+}
+
+const HIGH_THRESHOLD = 7.0;
+const MEDIUM_THRESHOLD = 4.0;
+
+function bucket(score: number): 'high' | 'medium' | 'low' {
+  if (score >= HIGH_THRESHOLD) return 'high';
+  if (score >= MEDIUM_THRESHOLD) return 'medium';
+  return 'low';
+}
+
+function fmtEdgePath(path: ImpactEdge[]): string {
+  return path.map((e) => `${e.from} →[${e.kind}]→ ${e.to}`).join(' · ');
+}
+
+export function renderImpactMarkdown(report: ImpactReport): string {
+  const lines: string[] = [];
+  lines.push(`# Impact Analysis — ${report.targetTicket}`);
+  lines.push('');
+  lines.push(`**Modified areas:** ${report.modifiedAreas.join(', ') || '(none)'}`);
+  lines.push(`**Generated:** ${report.generatedAt}`);
+  lines.push('');
+
+  if (report.scenarios.length === 0) {
+    lines.push('No prior scenarios in the modified areas. This may be a new feature area.');
+    lines.push('');
+    return lines.join('\n');
+  }
+
+  const bySeverity = {
+    high: [] as ImpactScenario[],
+    medium: [] as ImpactScenario[],
+    low: [] as ImpactScenario[],
+  };
+  for (const s of report.scenarios) bySeverity[bucket(s.riskScore)].push(s);
+
+  lines.push(
+    `**Total impacted:** ${report.scenarios.length} scenarios (${bySeverity.high.length} high · ${bySeverity.medium.length} medium · ${bySeverity.low.length} low)`,
+  );
+  lines.push('');
+
+  for (const [name, scenarios] of [
+    ['High-risk', bySeverity.high],
+    ['Medium-risk', bySeverity.medium],
+    ['Low-risk', bySeverity.low],
+  ] as const) {
+    if (scenarios.length === 0) continue;
+    lines.push(`## ${name}`);
+    lines.push('');
+    for (const s of scenarios) {
+      lines.push(
+        `### ${s.ticketId} / "${s.name}" [${s.priority.toUpperCase()}]   score ${s.riskScore.toFixed(1)}`,
+      );
+      lines.push(`- Edge: ${fmtEdgePath(s.edgePath)}`);
+      if (s.lastPassedAt) lines.push(`- Last passed: ${s.lastPassedAt}`);
+      lines.push('');
+    }
+  }
+
+  lines.push('## Re-run commands');
+  lines.push(`- All:        \`bun run xera:exec --from-impact ${report.targetTicket}\``);
+  lines.push(
+    `- P0 only:    \`bun run xera:exec --from-impact ${report.targetTicket} --min-priority p0\``,
+  );
+  lines.push(`- Select:     \`bun run xera:exec --from-impact ${report.targetTicket} --select\``);
+  lines.push('');
+
+  return lines.join('\n');
+}

package/src/graph/index.ts

@@ -1,7 +1,33 @@
+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 type {
+  ImpactEdge,
+  ImpactOpts,
+  ImpactReport,
+  ImpactScenario,
+} from './impact';
+export {
+  renderImpactMarkdown,
+  riskScore,
+  walkImpact,
+} from './impact';
 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;