@wutangbanger/horus-contracts 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,147 @@
+/**
+ * @horus/contracts
+ *
+ * Pure interface definitions shared between production services and test infrastructure.
+ * No implementations here — just contracts. Production code depends on this;
+ * test-utils implements these interfaces.
+ *
+ * This separation ensures production services never depend on test code.
+ */
+export interface EventPayload {
+    topic: string;
+    data: unknown;
+    timestamp: number;
+    correlationId: string;
+}
+export interface IEventBus {
+    publish(topic: string, data: unknown, correlationId?: string): Promise<void>;
+    subscribe(topic: string, handler: (payload: EventPayload) => void | Promise<void>): void;
+    unsubscribeAll(): void;
+}
+/**
+ * Categories map to the five AI agents:
+ *   failure    → Felix  (triage latest test failures)
+ *   diff       → Percy  (review recent test-file diffs)
+ *   dashboard  → Iris   (enrich dashboard with insights)
+ *   flakiness  → Greta  (analyze flakiness report)
+ *   coverage   → Saxon  (analyze coverage summary)
+ */
+export type AgentInsightCategory = 'failure' | 'diff' | 'dashboard' | 'flakiness' | 'coverage';
+export type AgentInsightSeverity = 'info' | 'warning' | 'critical';
+export interface AgentInsight {
+    /** Unique ID for this insight record */
+    id: string;
+    /** Which agent produced this insight (e.g. "felix", "saxon") */
+    agentId: string;
+    /** ISO 8601 timestamp of when the agent ran */
+    runAt: string;
+    category: AgentInsightCategory;
+    severity: AgentInsightSeverity;
+    /** One-line human-readable summary shown in the dashboard */
+    summary: string;
+    /** Full structured output from the agent — shape varies by agent */
+    details: unknown;
+}
+export interface IAgentInsightStore {
+    append(insight: AgentInsight): Promise<void>;
+    readAll(): Promise<AgentInsight[]>;
+    readSince(isoTimestamp: string): Promise<AgentInsight[]>;
+    readByAgent(agentId: string): Promise<AgentInsight[]>;
+}
+/**
+ * One record per individual test per CI run.
+ * Accumulated over time to compute flakiness scores.
+ */
+export interface TestRunRecord {
+    /** Unique ID for this record */
+    id: string;
+    /** Full test name, e.g. "OrderService > createOrder > given valid request..." */
+    testName: string;
+    /** Layer: unit | integration | e2e */
+    layer: 'unit' | 'integration' | 'e2e';
+    /** ISO 8601 timestamp of the run */
+    runAt: string;
+    /** Whether this test passed in this run */
+    passed: boolean;
+    /** Execution time in milliseconds */
+    durationMs: number;
+    /** Number of retries before this result (0 = first attempt) */
+    retries: number;
+    /** Git commit SHA or 'local' */
+    commitSha: string;
+}
+/**
+ * Computed flakiness summary for a single test.
+ * Derived from a window of TestRunRecords.
+ */
+export interface FlakeScore {
+    testName: string;
+    layer: TestRunRecord['layer'];
+    /** Total runs in the analysis window */
+    totalRuns: number;
+    passCount: number;
+    failCount: number;
+    /** 0.0 = always passes, 1.0 = always fails */
+    flakeRate: number;
+    /** Whether the test is considered flaky (0 < flakeRate < 1) */
+    isFlaky: boolean;
+    /** Whether the test consistently fails (flakeRate === 1) */
+    isAlwaysFailing: boolean;
+    /** Average duration in ms */
+    avgDurationMs: number;
+}
+export interface ITestRunStore {
+    append(record: TestRunRecord): Promise<void>;
+    readAll(): Promise<TestRunRecord[]>;
+    readSince(isoTimestamp: string): Promise<TestRunRecord[]>;
+    readByTest(testName: string): Promise<TestRunRecord[]>;
+}
+/**
+ * One snapshot per test:coverage run. Accumulated over time to detect drift.
+ */
+export interface CoverageSnapshot {
+    id: string;
+    capturedAt: string;
+    commitSha: string;
+    /** Percentage values 0–100 */
+    lines: number;
+    functions: number;
+    branches: number;
+    statements: number;
+}
+/**
+ * Delta between two consecutive CoverageSnapshots.
+ * Negative values mean coverage degraded.
+ */
+export interface CoverageDelta {
+    lines: number;
+    functions: number;
+    branches: number;
+    statements: number;
+    /** True if any metric dropped below its configured threshold */
+    belowThreshold: boolean;
+}
+export interface HorusConfig {
+    /** Directory where all JSONL report files are written. Default: './reports' */
+    reportsDir: string;
+    /** Git SHA for test run records. Default: process.env.GITHUB_SHA ?? 'local' */
+    commitSha?: string;
+    /** Coverage thresholds for delta/belowThreshold calculation */
+    coverage?: {
+        lines: number;
+        functions: number;
+        branches: number;
+        statements: number;
+    };
+}
+export interface IRepository<T extends {
+    id: string;
+}> {
+    findById(id: string): Promise<T | null>;
+    findAll(): Promise<T[]>;
+    findWhere(predicate: (item: T) => boolean): Promise<T[]>;
+    save(entity: T): Promise<T>;
+    update(id: string, patch: Partial<T>): Promise<T | null>;
+    delete(id: string): Promise<boolean>;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -0,0 +1,11 @@
+/**
+ * @horus/contracts
+ *
+ * Pure interface definitions shared between production services and test infrastructure.
+ * No implementations here — just contracts. Production code depends on this;
+ * test-utils implements these interfaces.
+ *
+ * This separation ensures production services never depend on test code.
+ */
+export {};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@wutangbanger/horus-contracts",
+  "version": "1.0.0",
+  "description": "Shared interface contracts for Horus services",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "clean": "rm -rf dist"
+  }
+}