@rengler33/prov 0.1.1

package/dist/storage.d.ts

@@ -0,0 +1,267 @@
+/**
+ * Storage layer for prov.
+ *
+ * Handles persistence of the intent graph and trace mappings to disk.
+ * Uses file-based storage in .prov/ directory for git-friendliness.
+ *
+ * @see spec:storage:v1
+ */
+import { IntentGraph } from './graph.js';
+import type { EntityId, Hash, StepId, Timestamp, TraceId } from './types.js';
+/** Root directory name for prov metadata */
+export declare const PROV_DIR = ".prov";
+/** Intent graph file name */
+export declare const GRAPH_FILE = "graph.json";
+/** Mappings directory name */
+export declare const MAPPINGS_DIR = "mappings";
+/** Cache directory name */
+export declare const CACHE_DIR = "cache";
+/** Lock file name */
+export declare const LOCK_FILE = ".lock";
+/** Schema version for graph format */
+export declare const SCHEMA_VERSION = 1;
+/**
+ * Graph file schema for persistence.
+ */
+export interface GraphFile {
+    /** Schema version for migrations */
+    readonly schemaVersion: number;
+    /** ISO timestamp of last modification */
+    readonly updatedAt: Timestamp;
+    /** Graph nodes keyed by ID */
+    readonly nodes: Record<string, SerializedNode>;
+    /** Graph edges */
+    readonly edges: SerializedEdge[];
+}
+/**
+ * Serialized node format (JSON-friendly).
+ */
+export interface SerializedNode {
+    readonly id: EntityId;
+    readonly type: string;
+    readonly hash?: Hash | undefined;
+    readonly sourceFile?: string | undefined;
+    readonly data: unknown;
+}
+/**
+ * Serialized edge format (JSON-friendly).
+ */
+export interface SerializedEdge {
+    readonly from: EntityId;
+    readonly to: EntityId;
+    readonly type: string;
+}
+/**
+ * Line range mapping within a file.
+ */
+export interface LineMapping {
+    /** Starting line (1-indexed) */
+    readonly startLine: number;
+    /** Ending line (1-indexed, inclusive) */
+    readonly endLine: number;
+    /** Step ID this range implements */
+    readonly stepId: StepId;
+    /** Optional trace ID */
+    readonly traceId?: TraceId;
+}
+/**
+ * Trace mapping for a single source file.
+ */
+export interface FileMapping {
+    /** Source file path (relative to project root) */
+    readonly path: string;
+    /** Hash of the file at trace time */
+    readonly fileHash: Hash;
+    /** ISO timestamp of last update */
+    readonly updatedAt: Timestamp;
+    /** Line range mappings */
+    readonly mappings: readonly LineMapping[];
+}
+/**
+ * Options for storage operations.
+ */
+export interface StorageOptions {
+    /** Project root directory (default: cwd) */
+    readonly projectRoot?: string;
+}
+/**
+ * Result of storage operations.
+ */
+export interface StorageResult<T> {
+    readonly success: boolean;
+    readonly data?: T | undefined;
+    readonly error?: string | undefined;
+}
+/**
+ * Get the .prov directory path for a project.
+ */
+export declare function getProvDir(projectRoot?: string): string;
+/**
+ * Get the graph.json file path.
+ */
+export declare function getGraphPath(projectRoot?: string): string;
+/**
+ * Get the mappings directory path.
+ */
+export declare function getMappingsDir(projectRoot?: string): string;
+/**
+ * Get the cache directory path.
+ */
+export declare function getCacheDir(projectRoot?: string): string;
+/**
+ * Get the lock file path.
+ */
+export declare function getLockPath(projectRoot?: string): string;
+/**
+ * Get the mapping file path for a source file.
+ *
+ * @example
+ * getMappingPath('src/auth/login.ts') → '.prov/mappings/src/auth/login.ts.yaml'
+ */
+export declare function getMappingPath(sourcePath: string, projectRoot?: string): string;
+/**
+ * Check if prov is initialized in the project.
+ */
+export declare function isInitialized(projectRoot?: string): boolean;
+/**
+ * Initialize prov directory structure.
+ *
+ * Creates:
+ * - .prov/
+ * - .prov/mappings/
+ * - .prov/cache/
+ *
+ * @see req:storage:directory-structure
+ */
+export declare function initialize(projectRoot?: string): StorageResult<void>;
+/**
+ * Acquire a write lock.
+ *
+ * @see req:storage:atomic-writes
+ */
+export declare function acquireLock(projectRoot?: string): StorageResult<void>;
+/**
+ * Release the write lock.
+ */
+export declare function releaseLock(projectRoot?: string): StorageResult<void>;
+/**
+ * Execute a function with a lock held.
+ */
+export declare function withLock<T>(projectRoot: string, fn: () => Promise<T> | T): Promise<StorageResult<T>>;
+/**
+ * Write data atomically (write to temp, then rename).
+ *
+ * @see req:storage:atomic-writes
+ */
+export declare function atomicWrite(filePath: string, content: string): StorageResult<void>;
+/**
+ * Save the intent graph to disk.
+ *
+ * @see req:storage:graph-format
+ * @see req:storage:atomic-writes
+ */
+export declare function saveGraph(graph: IntentGraph, projectRoot?: string): StorageResult<void>;
+/**
+ * Load the intent graph from disk.
+ *
+ * @see req:storage:graph-format
+ */
+export declare function loadGraph(projectRoot?: string): StorageResult<IntentGraph>;
+/**
+ * Save a trace mapping for a source file.
+ *
+ * @see req:storage:mapping-format
+ */
+export declare function saveMapping(mapping: FileMapping, projectRoot?: string): StorageResult<void>;
+/**
+ * Load a trace mapping for a source file.
+ *
+ * @see req:storage:mapping-format
+ */
+export declare function loadMapping(sourcePath: string, projectRoot?: string): StorageResult<FileMapping | null>;
+/**
+ * Delete a trace mapping for a source file.
+ */
+export declare function deleteMapping(sourcePath: string, projectRoot?: string): StorageResult<void>;
+/**
+ * List all trace mappings.
+ */
+export declare function listMappings(projectRoot?: string): StorageResult<string[]>;
+/**
+ * Get cached hash for a file.
+ */
+export declare function getCachedHash(filePath: string, projectRoot?: string): Hash | null;
+/**
+ * Set cached hash for a file.
+ */
+export declare function setCachedHash(filePath: string, hash: Hash, projectRoot?: string): StorageResult<void>;
+/**
+ * Clear the hash cache.
+ */
+export declare function clearCache(projectRoot?: string): StorageResult<void>;
+/**
+ * Storage class providing a high-level interface for prov persistence.
+ */
+export declare class Storage {
+    private readonly projectRoot;
+    constructor(options?: StorageOptions);
+    /**
+     * Check if prov is initialized.
+     */
+    isInitialized(): boolean;
+    /**
+     * Initialize prov directory structure.
+     */
+    initialize(): StorageResult<void>;
+    /**
+     * Load the intent graph.
+     */
+    loadGraph(): StorageResult<IntentGraph>;
+    /**
+     * Save the intent graph.
+     */
+    saveGraph(graph: IntentGraph): StorageResult<void>;
+    /**
+     * Load a file mapping.
+     */
+    loadMapping(sourcePath: string): StorageResult<FileMapping | null>;
+    /**
+     * Save a file mapping.
+     */
+    saveMapping(mapping: FileMapping): StorageResult<void>;
+    /**
+     * Delete a file mapping.
+     */
+    deleteMapping(sourcePath: string): StorageResult<void>;
+    /**
+     * List all file mappings.
+     */
+    listMappings(): StorageResult<string[]>;
+    /**
+     * Get cached hash for a file.
+     */
+    getCachedHash(filePath: string): Hash | null;
+    /**
+     * Set cached hash for a file.
+     */
+    setCachedHash(filePath: string, hash: Hash): StorageResult<void>;
+    /**
+     * Clear the cache.
+     */
+    clearCache(): StorageResult<void>;
+    /**
+     * Execute a function with a write lock.
+     */
+    withLock<T>(fn: () => Promise<T> | T): Promise<StorageResult<T>>;
+    /**
+     * Get path utilities.
+     */
+    get paths(): {
+        provDir: string;
+        graphPath: string;
+        mappingsDir: string;
+        cacheDir: string;
+        getMappingPath: (sourcePath: string) => string;
+    };
+}
+//# sourceMappingURL=storage.d.ts.map

package/dist/storage.d.ts.map

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