@neat.is/core 0.2.5

package/dist/index.d.cts

@@ -0,0 +1,408 @@
+import { MultiDirectedGraph } from 'graphology';
+import { GraphNode, GraphEdge, ErrorEvent, BlastRadiusResult, RootCauseResult, RegistryEntry, RegistryStatus, RegistryFile } from '@neat.is/types';
+import { FastifyInstance } from 'fastify';
+
+type NeatGraph = MultiDirectedGraph<GraphNode, GraphEdge>;
+declare function getGraph(project?: string): NeatGraph;
+declare function resetGraph(project?: string): void;
+
+interface ExtractResult {
+    nodesAdded: number;
+    edgesAdded: number;
+    frontiersPromoted: number;
+}
+interface ExtractOptions {
+    onPolicyTrigger?: (graph: NeatGraph) => Promise<void> | void;
+}
+declare function extractFromDirectory(graph: NeatGraph, scanPath: string, opts?: ExtractOptions): Promise<ExtractResult>;
+
+interface CompatibilityResult {
+    compatible: boolean;
+    reason?: string;
+    minDriverVersion?: string;
+}
+interface CompatPair {
+    kind?: 'driver-engine';
+    driver: string;
+    engine: string;
+    minDriverVersion: string;
+    minEngineVersion?: string;
+    reason: string;
+}
+declare function checkCompatibility(driver: string, driverVersion: string, engine: string, engineVersion: string): CompatibilityResult;
+declare function compatPairs(): readonly CompatPair[];
+
+declare function saveGraphToDisk(graph: NeatGraph, outPath: string): Promise<void>;
+declare function loadGraphFromDisk(graph: NeatGraph, outPath: string): Promise<void>;
+declare function startPersistLoop(graph: NeatGraph, outPath: string, intervalMs?: number): () => void;
+
+interface ScoredNode {
+    node: GraphNode;
+    score: number;
+}
+interface SearchResponse {
+    query: string;
+    provider: 'ollama' | 'transformers' | 'substring';
+    matches: ScoredNode[];
+}
+interface SearchIndex {
+    readonly provider: SearchResponse['provider'];
+    search(query: string, limit?: number): Promise<SearchResponse>;
+    refresh(graph: NeatGraph): Promise<void>;
+}
+
+interface ProjectPaths {
+    snapshotPath: string;
+    errorsPath: string;
+    staleEventsPath: string;
+    embeddingsCachePath: string;
+    policyViolationsPath: string;
+}
+interface ProjectContext {
+    name: string;
+    graph: NeatGraph;
+    scanPath?: string;
+    paths: ProjectPaths;
+    searchIndex?: SearchIndex;
+}
+declare class Projects {
+    private contexts;
+    upsert(ctx: ProjectContext): void;
+    set(name: string, init: Omit<ProjectContext, 'name' | 'graph'> & {
+        graph?: NeatGraph;
+    }): ProjectContext;
+    get(name: string): ProjectContext | undefined;
+    has(name: string): boolean;
+    list(): string[];
+    attachSearchIndex(name: string, index: SearchIndex | undefined): void;
+}
+
+interface BuildApiOptions {
+    projects?: Projects;
+    startedAt?: number;
+    graph?: NeatGraph;
+    scanPath?: string;
+    errorsPath?: string;
+    staleEventsPath?: string;
+    searchIndex?: SearchIndex;
+}
+declare function buildApi(opts: BuildApiOptions): Promise<FastifyInstance>;
+
+interface ParsedSpan {
+    service: string;
+    traceId: string;
+    spanId: string;
+    parentSpanId?: string;
+    name: string;
+    kind?: number;
+    startTimeUnixNano: string;
+    endTimeUnixNano: string;
+    startTimeIso?: string;
+    durationNanos: bigint;
+    attributes: Record<string, AttributeValue>;
+    dbSystem?: string;
+    dbName?: string;
+    statusCode?: number;
+    errorMessage?: string;
+    exception?: {
+        type?: string;
+        message?: string;
+        stacktrace?: string;
+    };
+}
+type AttributeValue = string | number | boolean | bigint | string[] | number[] | boolean[] | null;
+type SpanHandler = (span: ParsedSpan) => void | Promise<void>;
+interface BuildOtelReceiverOptions {
+    onSpan: SpanHandler;
+    onErrorSpanSync?: (span: ParsedSpan) => Promise<void>;
+    bodyLimit?: number;
+}
+interface OtlpKeyValue {
+    key: string;
+    value?: OtlpAnyValue;
+}
+interface OtlpAnyValue {
+    stringValue?: string;
+    intValue?: string | number;
+    doubleValue?: number;
+    boolValue?: boolean;
+    arrayValue?: {
+        values?: OtlpAnyValue[];
+    };
+}
+interface OtlpStatus {
+    code?: number;
+    message?: string;
+}
+interface OtlpEvent {
+    name?: string;
+    timeUnixNano?: string;
+    attributes?: OtlpKeyValue[];
+}
+interface OtlpSpan {
+    traceId?: string;
+    spanId?: string;
+    parentSpanId?: string;
+    name?: string;
+    kind?: number;
+    startTimeUnixNano?: string;
+    endTimeUnixNano?: string;
+    attributes?: OtlpKeyValue[];
+    events?: OtlpEvent[];
+    status?: OtlpStatus;
+}
+interface OtlpScopeSpans {
+    spans?: OtlpSpan[];
+}
+interface OtlpResourceSpans {
+    resource?: {
+        attributes?: OtlpKeyValue[];
+    };
+    scopeSpans?: OtlpScopeSpans[];
+}
+interface OtlpTracesRequest {
+    resourceSpans?: OtlpResourceSpans[];
+}
+declare function parseOtlpRequest(body: OtlpTracesRequest): ParsedSpan[];
+declare function buildOtelReceiver(opts: BuildOtelReceiverOptions): Promise<FastifyInstance & {
+    flushPending: () => Promise<void>;
+}>;
+declare function logSpanHandler(span: ParsedSpan): void;
+
+interface BuildOtelGrpcReceiverOptions {
+    onSpan: SpanHandler;
+}
+interface OtelGrpcReceiver {
+    address: string;
+    stop: () => Promise<void>;
+}
+declare function startOtelGrpcReceiver(opts: BuildOtelGrpcReceiverOptions & {
+    host?: string;
+    port?: number;
+}): Promise<OtelGrpcReceiver>;
+
+interface IngestContext {
+    graph: NeatGraph;
+    errorsPath: string;
+    now?: () => number;
+    writeErrorEventInline?: boolean;
+    onPolicyTrigger?: (graph: NeatGraph) => Promise<void> | void;
+}
+declare function thresholdForEdgeType(edgeType: string, overrides?: Record<string, number>): number;
+declare function stitchTrace(graph: NeatGraph, sourceServiceId: string, ts: string): void;
+declare function handleSpan(ctx: IngestContext, span: ParsedSpan): Promise<void>;
+
+declare function makeSpanHandler(ctx: IngestContext): (span: ParsedSpan) => Promise<void>;
+interface StaleEvent {
+    edgeId: string;
+    source: string;
+    target: string;
+    edgeType: string;
+    thresholdMs: number;
+    ageMs: number;
+    lastObserved: string;
+    transitionedAt: string;
+}
+interface MarkStaleOptions {
+    thresholds?: Record<string, number>;
+    now?: number;
+    staleEventsPath?: string;
+}
+declare function markStaleEdges(graph: NeatGraph, options?: MarkStaleOptions): Promise<{
+    count: number;
+    events: StaleEvent[];
+}>;
+declare function readStaleEvents(staleEventsPath: string): Promise<StaleEvent[]>;
+interface StalenessLoopOptions {
+    thresholds?: Record<string, number>;
+    intervalMs?: number;
+    staleEventsPath?: string;
+    onPolicyTrigger?: (graph: NeatGraph) => Promise<void> | void;
+}
+declare function startStalenessLoop(graph: NeatGraph, options?: StalenessLoopOptions): () => void;
+declare function readErrorEvents(errorsPath: string): Promise<ErrorEvent[]>;
+
+declare function confidenceForEdge(edge: GraphEdge, now?: number): number;
+declare function getRootCause(graph: NeatGraph, errorNodeId: string, errorEvent?: ErrorEvent): RootCauseResult | null;
+declare function getBlastRadius(graph: NeatGraph, nodeId: string, maxDepth?: number): BlastRadiusResult;
+
+interface PersistedNodeEntry {
+    key?: string;
+    attributes?: Record<string, unknown>;
+}
+interface PersistedEdgeEntry {
+    key?: string;
+    source?: string;
+    target?: string;
+    attributes?: Record<string, unknown>;
+}
+interface PersistedSnapshot {
+    schemaVersion?: number;
+    exportedAt?: string;
+    graph?: {
+        nodes?: PersistedNodeEntry[];
+        edges?: PersistedEdgeEntry[];
+    };
+}
+interface GraphDiff {
+    base: {
+        exportedAt?: string;
+    };
+    current: {
+        exportedAt: string;
+    };
+    added: {
+        nodes: GraphNode[];
+        edges: GraphEdge[];
+    };
+    removed: {
+        nodes: GraphNode[];
+        edges: GraphEdge[];
+    };
+    changed: {
+        nodes: {
+            id: string;
+            before: GraphNode;
+            after: GraphNode;
+        }[];
+        edges: {
+            id: string;
+            before: GraphEdge;
+            after: GraphEdge;
+        }[];
+    };
+}
+declare function loadSnapshotForDiff(target: string): Promise<PersistedSnapshot>;
+declare function computeGraphDiff(liveGraph: NeatGraph, baseSnapshot: PersistedSnapshot, currentExportedAt?: string): GraphDiff;
+
+/**
+ * Multi-project daemon (ADR-049).
+ *
+ * Single long-lived process watching every project in the machine-level registry.
+ * Per-project graph isolation: each registered project owns its own
+ * `MultiDirectedGraph` slot keyed by name (ADR-026), and a failure during
+ * one project's bootstrap is logged + marked `broken` without taking down
+ * the rest of the daemon.
+ *
+ * MVP scope (v0.2.5):
+ *  - Read registry; refuse to boot when it's missing.
+ *  - Write PID at `~/.neat/neatd.pid` for external supervisors.
+ *  - Per project: load any existing snapshot, run initial extraction,
+ *    start a per-project persist loop.
+ *  - SIGHUP triggers a reload — re-reads the registry, picks up new
+ *    projects, drops removed ones, leaves untouched ones in place.
+ *  - Provide `routeSpanToProject(serviceName, projects)` for OTel ingest
+ *    to dispatch by `service.name` across registered projects, falling
+ *    back to `default` for unknown services per ADR-033.
+ *
+ * Out of MVP scope (deferred):
+ *  - Live OTel listener wiring per project — daemon exposes the routing
+ *    primitive; the actual receiver attachment lands alongside v0.2.6.
+ *  - Policy reload on `policy.json` mtime — `startWatch` already does this
+ *    per-project; the daemon-level loop reuses that machinery in a follow-up.
+ *  - Auto-restart on crash. PID file is the supervisor handoff.
+ */
+
+interface DaemonOptions {
+    neatHome?: string;
+}
+interface ProjectSlot {
+    entry: RegistryEntry;
+    graph: NeatGraph;
+    outPath: string;
+    stopPersist: () => void;
+    status: 'active' | 'broken';
+    errorReason?: string;
+}
+interface DaemonHandle {
+    slots: Map<string, ProjectSlot>;
+    reload: () => Promise<void>;
+    stop: () => Promise<void>;
+    pidPath: string;
+}
+/**
+ * Resolve which project's graph an OTel span belongs to. Looks up the
+ * `service.name` against the registry and returns the matching project's
+ * name, or `DEFAULT_PROJECT` for unknown services so the FrontierNode
+ * auto-creation flow keeps working per ADR-033.
+ *
+ * Pure function. Daemon callers pass a snapshot of the registry to avoid
+ * per-span fs reads.
+ */
+declare function routeSpanToProject(serviceName: string | undefined, projects: ReadonlyArray<RegistryEntry>): string;
+declare function startDaemon(opts?: DaemonOptions): Promise<DaemonHandle>;
+
+/**
+ * Machine-level project registry (ADR-048).
+ *
+ * One file: `~/.neat/projects.json`. Per-user, machine-local. Not synced.
+ * `registry.ts` is the only module that opens it. Everything else — `init`,
+ * `daemon`, `cli` — calls into the helpers below.
+ *
+ * Two safety properties matter:
+ *  1. Atomic writes. We tmp + fsync + rename so the daemon never sees a torn
+ *     file when init races against it.
+ *  2. Cross-process exclusion. We hold an exclusive lock on
+ *     `~/.neat/projects.json.lock` for the read-modify-write window. Two
+ *     concurrent `neat init` runs cannot both win and overwrite each other.
+ *
+ * The lock is a file we exclusively-create (`O_EXCL`), hold while we mutate,
+ * and unlink on the way out. Crude but cross-platform; matches what
+ * `proper-lockfile` does internally without pulling the dep in.
+ */
+
+declare function registryPath(): string;
+declare function registryLockPath(): string;
+/**
+ * Path normalisation per ADR-048 #7. Two `init` calls from different relative
+ * paths to the same dir must collapse to one entry. `path.resolve` handles
+ * relative-to-cwd; we pass it through `fs.realpath` when the dir exists so
+ * symlinked paths land on the same canonical entry too.
+ */
+declare function normalizeProjectPath(input: string): Promise<string>;
+/**
+ * tmp + fsync + rename. The fsync on the data fd guarantees the bytes are on
+ * disk before rename swaps the inode; rename itself is atomic on POSIX.
+ *
+ * Exported so the init flow and test harnesses can use the same helper.
+ */
+declare function writeAtomically(target: string, contents: string): Promise<void>;
+/**
+ * Read the registry from disk. Returns an empty registry if the file does
+ * not exist yet — first run, never registered anything.
+ *
+ * Throws on parse / schema errors. The contract is single-source-of-truth;
+ * a corrupt file is louder than a silent reset.
+ */
+declare function readRegistry(): Promise<RegistryFile>;
+interface AddProjectOptions {
+    name: string;
+    path: string;
+    languages?: string[];
+    status?: RegistryStatus;
+}
+declare class ProjectNameCollisionError extends Error {
+    readonly projectName: string;
+    constructor(name: string);
+}
+/**
+ * Register a project, or update its `lastSeenAt` if the same path is already
+ * registered under the same name (idempotent re-init).
+ *
+ * Hard error on name collision against a different path — ADR-046 #7. The
+ * caller can recover by passing `--project <new-name>`.
+ */
+declare function addProject(opts: AddProjectOptions): Promise<RegistryEntry>;
+declare function getProject(name: string): Promise<RegistryEntry | undefined>;
+declare function listProjects(): Promise<RegistryEntry[]>;
+declare function setStatus(name: string, status: RegistryStatus): Promise<RegistryEntry>;
+declare function touchLastSeen(name: string, at?: string): Promise<void>;
+/**
+ * Remove the registry entry for `name`. Per ADR-048 #6: this only removes the
+ * registry row. It does **not** touch `neat-out/`, `policy.json`, or any user
+ * file in the project directory. SDK-install rollback is a separate flow
+ * (`neat-rollback.patch`) that the caller opts in to.
+ */
+declare function removeProject(name: string): Promise<RegistryEntry | undefined>;
+
+export { type BuildApiOptions, type BuildOtelGrpcReceiverOptions, type BuildOtelReceiverOptions, type CompatPair, type CompatibilityResult, type DaemonHandle, type DaemonOptions, type ExtractResult, type GraphDiff, type IngestContext, type MarkStaleOptions, type NeatGraph, type OtelGrpcReceiver, type OtlpTracesRequest, type ParsedSpan, type PersistedSnapshot, ProjectNameCollisionError, type ProjectSlot, type SpanHandler, type StaleEvent, type StalenessLoopOptions, addProject, buildApi, buildOtelReceiver, checkCompatibility, compatPairs, computeGraphDiff, confidenceForEdge, extractFromDirectory, getBlastRadius, getGraph, getProject, getRootCause, handleSpan, listProjects, loadGraphFromDisk, loadSnapshotForDiff, logSpanHandler, makeSpanHandler, markStaleEdges, normalizeProjectPath, parseOtlpRequest, readErrorEvents, readRegistry, readStaleEvents, registryLockPath, registryPath, removeProject, resetGraph, routeSpanToProject, saveGraphToDisk, setStatus, startDaemon, startOtelGrpcReceiver, startPersistLoop, startStalenessLoop, stitchTrace, thresholdForEdgeType, touchLastSeen, writeAtomically };