@xera-ai/core 0.1.7 → 0.4.0

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

package/src/graph/ulid.ts

@@ -0,0 +1,58 @@
+// Crockford base32, monotonic-per-process. Spec-compliant 26-char output.
+const CROCKFORD = '0123456789ABCDEFGHJKMNPQRSTVWXYZ';
+let lastMs = 0;
+let lastRand = new Uint8Array(10);
+
+// Encodes 48-bit timestamp as 10 Crockford base32 chars (10 × 5 bits = 50 bits;
+// the two leading bits are always zero for any ms ≤ 2^48-1, covering ~year 10000).
+function timestampPart(ms: number): string {
+  let out = '';
+  for (let i = 9; i >= 0; i--) {
+    const shift = i * 5;
+    // Use bigint to safely shift 48-bit values without sign-extension issues
+    const part = Number((BigInt(ms) >> BigInt(shift)) & 0x1fn);
+    out += CROCKFORD[part];
+  }
+  return out;
+}
+
+// Encodes 10 random bytes (80 bits) as 16 Crockford base32 chars (16 × 5 = 80 bits exactly).
+function encodeRandom(buf: Uint8Array): string {
+  let out = '';
+  let bitBuf = 0;
+  let bits = 0;
+  for (const b of buf) {
+    bitBuf = (bitBuf << 8) | b;
+    bits += 8;
+    while (bits >= 5) {
+      bits -= 5;
+      out += CROCKFORD[(bitBuf >> bits) & 0x1f];
+    }
+  }
+  return out;
+}
+
+function bumpRandom(prev: Uint8Array): Uint8Array {
+  const next = new Uint8Array(prev);
+  for (let i = next.length - 1; i >= 0; i--) {
+    if (next[i]! === 0xff) {
+      next[i] = 0;
+      continue;
+    }
+    next[i] = next[i]! + 1;
+    break;
+  }
+  return next;
+}
+
+export function ulid(now: number = Date.now()): string {
+  let rand: Uint8Array;
+  if (now === lastMs) {
+    rand = bumpRandom(lastRand);
+  } else {
+    rand = new Uint8Array(crypto.getRandomValues(new Uint8Array(10)));
+    lastMs = now;
+  }
+  lastRand = new Uint8Array(rand);
+  return timestampPart(now) + encodeRandom(rand);
+}

package/src/index.ts

@@ -1,19 +1,19 @@
 export const VERSION = '0.1.0';
 export type * from './adapter/types';
-export * from './config/schema';
-export * from './config/define';
-export * from './config/load';
-export * from './artifact/paths';
 export * from './artifact/hash';
 export * from './artifact/meta';
+export * from './artifact/paths';
 export * from './artifact/status';
-export * from './logging/ndjson-logger';
-export * from './lock/file-lock';
-export * from './jira/types';
-export * from './jira/client';
-export * from './jira/fields';
-export * from './jira/retry';
 export * from './auth/encrypt';
 export * from './auth/key';
-export * from './auth/state';
 export * from './auth/refresh';
+export * from './auth/state';
+export * from './config/define';
+export * from './config/load';
+export * from './config/schema';
+export * from './jira/client';
+export * from './jira/fields';
+export * from './jira/retry';
+export * from './jira/types';
+export * from './lock/file-lock';
+export * from './logging/ndjson-logger';

package/src/jira/client.ts

@@ -1,6 +1,6 @@
-import type { JiraClient } from './types';
 import { createMcpBackend } from './mcp-backend';
 import { createRestBackend } from './rest-backend';
+import type { JiraClient } from './types';
 
 export interface CreateJiraClientOptions {
   baseUrl: string;
@@ -14,7 +14,9 @@ export async function createJiraClient(opts: CreateJiraClientOptions): Promise<J
     if (mcp) return mcp;
   }
   if (!opts.rest) {
-    throw new Error('Atlassian MCP not connected and no REST credentials provided (JIRA_EMAIL + JIRA_API_TOKEN).');
+    throw new Error(
+      'Atlassian MCP not connected and no REST credentials provided (JIRA_EMAIL + JIRA_API_TOKEN).',
+    );
   }
   return createRestBackend(opts.baseUrl, opts.rest);
 }

package/src/jira/fields.ts

@@ -8,8 +8,10 @@ export interface JiraFieldInfo {
 
 export function rankStoryCandidates(fields: JiraFieldInfo[]): JiraFieldInfo[] {
   return fields
-    .filter(f => f.hasContent)
-    .filter(f => !['attachment', 'comment', 'created', 'updated', 'reporter', 'creator'].includes(f.id))
+    .filter((f) => f.hasContent)
+    .filter(
+      (f) => !['attachment', 'comment', 'created', 'updated', 'reporter', 'creator'].includes(f.id),
+    )
     .sort((a, b) => {
       const ai = PREFERRED_STORY_IDS.indexOf(a.id);
       const bi = PREFERRED_STORY_IDS.indexOf(b.id);

package/src/jira/mcp-backend.ts

@@ -1,4 +1,4 @@
-import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import type { JiraClient, JiraTicket } from './types';