clearctx 3.0.0

package/src/lineage-graph.js

@@ -0,0 +1,402 @@
+/**
+ * lineage-graph.js
+ * Layer 3: Artifact Lineage Graph - Track data provenance and impact analysis
+ *
+ * This module provides methods to traverse the lineage graph embedded in artifact version files.
+ * The lineage graph is NOT a separate index - it's stored directly in each version file's
+ * lineage field (producedBy and derivedFrom).
+ *
+ * Key concepts:
+ * - Upstream: What artifacts was this derived from? (follow derivedFrom)
+ * - Downstream: What artifacts depend on this? (scan all artifacts for references)
+ * - Impact: What would be affected if this artifact changes?
+ * - Stale: Which artifacts reference outdated versions?
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// Import Layer 2 ArtifactStore
+const ArtifactStore = require('./artifact-store');
+
+/**
+ * LineageGraph provides methods to traverse artifact dependencies and analyze impact
+ *
+ * The lineage graph is stored in each artifact version file:
+ * {
+ *   lineage: {
+ *     producedBy: { contractId, session } | null,
+ *     derivedFrom: ["other-artifact@v1", ...]  // format: "artifactId@vN"
+ *   }
+ * }
+ */
+class LineageGraph {
+  /**
+   * Create a new LineageGraph instance
+   * @param {string} teamName - Name of the team (default: 'default')
+   */
+  constructor(teamName = 'default') {
+    // Create an ArtifactStore instance to access artifact data
+    this.artifacts = new ArtifactStore(teamName);
+
+    // Store team name for reference
+    this.teamName = teamName;
+
+    // Store the data directory path for scanning operations
+    this.dataDir = this.artifacts.dataDir;
+  }
+
+  /**
+   * Parse a lineage reference like "artifactId@vN" into components
+   * @param {string} ref - Reference string (format: "artifactId@vN" or just "artifactId")
+   * @returns {Object} { artifactId, version } where version is number or null for "latest"
+   * @private
+   */
+  _parseRef(ref) {
+    // Check if the reference includes a version suffix
+    const atIndex = ref.lastIndexOf('@v');
+
+    if (atIndex === -1) {
+      // No version specified - means "latest"
+      return { artifactId: ref, version: null };
+    }
+
+    // Split into artifact ID and version
+    const artifactId = ref.substring(0, atIndex);
+    const versionStr = ref.substring(atIndex + 2); // Skip "@v"
+    const version = parseInt(versionStr, 10);
+
+    return { artifactId, version };
+  }
+
+  /**
+   * Scan all artifact directories and collect latest version files
+   * @returns {Map<string, Object>} Map of artifactId -> latest version data
+   * @private
+   */
+  _scanAllVersionFiles() {
+    const results = new Map();
+
+    // Check if data directory exists
+    if (!fs.existsSync(this.dataDir)) {
+      return results; // Empty map
+    }
+
+    // Get all artifact directories
+    const artifactDirs = fs.readdirSync(this.dataDir);
+
+    // Process each artifact directory
+    for (const artifactId of artifactDirs) {
+      const artifactDir = path.join(this.dataDir, artifactId);
+
+      // Skip if not a directory
+      try {
+        if (!fs.statSync(artifactDir).isDirectory()) {
+          continue;
+        }
+      } catch (err) {
+        continue; // Skip if can't access
+      }
+
+      // Get the latest version from the artifact store
+      const latestVersion = this.artifacts.get(artifactId);
+
+      if (latestVersion) {
+        results.set(artifactId, latestVersion);
+      }
+    }
+
+    return results;
+  }
+
+  /**
+   * Get the upstream dependency tree for an artifact
+   * Shows what artifacts this one was derived from, recursively
+   * @param {string} artifactId - The artifact identifier
+   * @param {number|null} [version=null] - Version number (null = latest)
+   * @returns {Object|null} Tree: { artifactId, version, parents: [...] } or null if not found
+   */
+  getUpstream(artifactId, version = null) {
+    // Use a Set to track visited nodes and prevent cycles
+    const visited = new Set();
+
+    /**
+     * Recursive helper to build upstream tree
+     * @param {string} id - Artifact ID
+     * @param {number|null} ver - Version number
+     * @returns {Object|null} Tree node
+     */
+    const buildUpstreamTree = (id, ver) => {
+      // Get the artifact version
+      const versionData = this.artifacts.get(id, ver);
+
+      if (!versionData) {
+        return null; // Artifact not found
+      }
+
+      // Create a unique key for cycle detection
+      const nodeKey = `${id}@v${versionData.version}`;
+
+      // Check if we've already visited this node (cycle detection)
+      if (visited.has(nodeKey)) {
+        return { artifactId: id, version: versionData.version, parents: [], cycleDetected: true };
+      }
+
+      // Mark this node as visited
+      visited.add(nodeKey);
+
+      // Get the derivedFrom array from lineage
+      const derivedFrom = versionData.lineage?.derivedFrom || [];
+
+      // Build parent nodes recursively
+      const parents = [];
+      for (const ref of derivedFrom) {
+        const { artifactId: parentId, version: parentVer } = this._parseRef(ref);
+        const parentTree = buildUpstreamTree(parentId, parentVer);
+
+        if (parentTree) {
+          parents.push(parentTree);
+        }
+      }
+
+      // Return the tree node
+      return {
+        artifactId: id,
+        version: versionData.version,
+        parents
+      };
+    };
+
+    // Build and return the tree
+    return buildUpstreamTree(artifactId, version);
+  }
+
+  /**
+   * Get the downstream dependency tree for an artifact
+   * Shows what artifacts depend on this one, recursively
+   * @param {string} artifactId - The artifact identifier
+   * @param {number|null} [version=null] - Version number (null = latest)
+   * @returns {Object|null} Tree: { artifactId, version, dependents: [...] } or null if not found
+   */
+  getDownstream(artifactId, version = null) {
+    // Get the artifact version to find its actual version number
+    const versionData = this.artifacts.get(artifactId, version);
+
+    if (!versionData) {
+      return null; // Artifact not found
+    }
+
+    const targetVersion = versionData.version;
+
+    // Use a Set to track visited nodes and prevent cycles
+    const visited = new Set();
+
+    /**
+     * Recursive helper to build downstream tree
+     * @param {string} id - Artifact ID
+     * @param {number} ver - Version number
+     * @returns {Object} Tree node
+     */
+    const buildDownstreamTree = (id, ver) => {
+      // Create a unique key for cycle detection
+      const nodeKey = `${id}@v${ver}`;
+
+      // Check if we've already visited this node (cycle detection)
+      if (visited.has(nodeKey)) {
+        return { artifactId: id, version: ver, dependents: [], cycleDetected: true };
+      }
+
+      // Mark this node as visited
+      visited.add(nodeKey);
+
+      // Scan all artifacts to find which ones reference this artifact
+      const allArtifacts = this._scanAllVersionFiles();
+      const dependents = [];
+
+      for (const [depId, depData] of allArtifacts.entries()) {
+        // Get the derivedFrom array
+        const derivedFrom = depData.lineage?.derivedFrom || [];
+
+        // Check if this artifact is in the derivedFrom list
+        for (const ref of derivedFrom) {
+          const { artifactId: refId, version: refVer } = this._parseRef(ref);
+
+          // Check if this reference matches our target artifact
+          // Match if: same artifactId AND (version matches OR ref has no version specified)
+          if (refId === id && (refVer === ver || refVer === null)) {
+            // This artifact depends on our target
+            const depTree = buildDownstreamTree(depId, depData.version);
+            dependents.push(depTree);
+            break; // Don't check other refs in this artifact's derivedFrom
+          }
+        }
+      }
+
+      // Return the tree node
+      return {
+        artifactId: id,
+        version: ver,
+        dependents
+      };
+    };
+
+    // Build and return the tree
+    return buildDownstreamTree(artifactId, targetVersion);
+  }
+
+  /**
+   * Calculate the impact radius of an artifact
+   * Shows how many artifacts would be affected if this artifact changes
+   * @param {string} artifactId - The artifact identifier
+   * @returns {Object} { artifactId, impactRadius, affectedArtifacts, affectedContracts }
+   */
+  getImpact(artifactId) {
+    // Get the downstream tree
+    const downstreamTree = this.getDownstream(artifactId);
+
+    if (!downstreamTree) {
+      return {
+        artifactId,
+        impactRadius: 0,
+        affectedArtifacts: [],
+        affectedContracts: []
+      };
+    }
+
+    // Flatten the tree to get all affected artifact IDs
+    const affectedArtifacts = new Set();
+    let maxDepth = 0;
+
+    /**
+     * Recursive helper to traverse the tree
+     * @param {Object} node - Tree node
+     * @param {number} depth - Current depth
+     */
+    const traverseTree = (node, depth) => {
+      // Add this artifact to the affected set
+      if (node.artifactId !== artifactId) {
+        affectedArtifacts.add(node.artifactId);
+      }
+
+      // Update max depth
+      maxDepth = Math.max(maxDepth, depth);
+
+      // Traverse dependents
+      for (const dependent of node.dependents || []) {
+        // Skip cycles
+        if (!dependent.cycleDetected) {
+          traverseTree(dependent, depth + 1);
+        }
+      }
+    };
+
+    // Traverse the downstream tree
+    traverseTree(downstreamTree, 0);
+
+    // TODO: Check contracts for references to this artifact
+    // This requires the ContractStore to be implemented
+    // For now, return an empty array
+    const affectedContracts = [];
+
+    // Return the impact analysis
+    return {
+      artifactId,
+      impactRadius: maxDepth,
+      affectedArtifacts: Array.from(affectedArtifacts),
+      affectedContracts
+    };
+  }
+
+  /**
+   * Find artifacts that reference outdated versions of their dependencies
+   * @returns {Array} Array of { artifactId, version, staleReason, staleSourceId, referencedVersion, latestVersion }
+   */
+  findStale() {
+    const staleArtifacts = [];
+
+    // Scan all artifacts
+    const allArtifacts = this._scanAllVersionFiles();
+
+    for (const [artifactId, versionData] of allArtifacts.entries()) {
+      // Get the derivedFrom array
+      const derivedFrom = versionData.lineage?.derivedFrom || [];
+
+      // Check each dependency
+      for (const ref of derivedFrom) {
+        const { artifactId: sourceId, version: referencedVersion } = this._parseRef(ref);
+
+        // Get the source artifact's latest version
+        const sourceLatest = this.artifacts.get(sourceId);
+
+        if (!sourceLatest) {
+          // Source artifact doesn't exist anymore
+          staleArtifacts.push({
+            artifactId,
+            version: versionData.version,
+            staleReason: 'Source artifact not found',
+            staleSourceId: sourceId,
+            referencedVersion,
+            latestVersion: null
+          });
+          continue;
+        }
+
+        // If referencedVersion is null, it means "latest" - not stale
+        if (referencedVersion === null) {
+          continue;
+        }
+
+        // Check if the referenced version is outdated
+        if (sourceLatest.version > referencedVersion) {
+          staleArtifacts.push({
+            artifactId,
+            version: versionData.version,
+            staleReason: 'References outdated version',
+            staleSourceId: sourceId,
+            referencedVersion,
+            latestVersion: sourceLatest.version
+          });
+        }
+      }
+    }
+
+    return staleArtifacts;
+  }
+
+  /**
+   * Get the complete audit trail for an artifact
+   * Shows full provenance: who published it, what contract produced it, what inputs it used
+   * @param {string} artifactId - The artifact identifier
+   * @param {number|null} [version=null] - Version number (null = latest)
+   * @returns {Object|null} Audit trail with full provenance, or null if not found
+   */
+  getAuditTrail(artifactId, version = null) {
+    // Get the artifact version
+    const versionData = this.artifacts.get(artifactId, version);
+
+    if (!versionData) {
+      return null; // Artifact not found
+    }
+
+    // Get upstream chain
+    const upstreamChain = this.getUpstream(artifactId, versionData.version);
+
+    // Build the audit trail
+    const auditTrail = {
+      artifactId,
+      version: versionData.version,
+      type: versionData.type,
+      publisher: versionData.publisher,
+      publishedAt: versionData.publishedAt,
+      summary: versionData.summary,
+      contract: versionData.lineage?.producedBy || null,
+      inputs: versionData.lineage?.derivedFrom || [],
+      upstreamChain
+    };
+
+    return auditTrail;
+  }
+}
+
+// Export the LineageGraph class
+module.exports = LineageGraph;