hadara 0.3.2 → 0.3.3-rc.0

package/dist/context/context-graph-builder.js

@@ -0,0 +1,341 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.collectContextGraphExtractions = collectContextGraphExtractions;
+exports.collectContextGraphExtractionsWithCache = collectContextGraphExtractionsWithCache;
+exports.buildContextGraphReport = buildContextGraphReport;
+exports.createTaskContextReport = createTaskContextReport;
+const context_cache_store_1 = require("./context-cache-store");
+const extractor_contract_1 = require("./extractor-contract");
+const document_extractors_1 = require("./document-extractors");
+const evidence_extractors_1 = require("./evidence-extractors");
+const registry_extractors_1 = require("./registry-extractors");
+const release_extractors_1 = require("./release-extractors");
+const state_projection_1 = require("./state-projection");
+const task_extractors_1 = require("./task-extractors");
+const code_graph_extractor_1 = require("./code-graph-extractor");
+function collectContextGraphExtractions(projectRoot, options = {}) {
+    const results = [
+        (0, task_extractors_1.extractTaskCapsules)(projectRoot),
+        (0, task_extractors_1.extractTaskBoard)(projectRoot),
+        (0, registry_extractors_1.extractDocsRegistry)(projectRoot),
+        (0, registry_extractors_1.extractCommandRegistry)(projectRoot),
+        (0, document_extractors_1.extractManagedSections)(projectRoot),
+        (0, document_extractors_1.extractProjectState)(projectRoot),
+        (0, document_extractors_1.extractDecisions)(projectRoot),
+        (0, document_extractors_1.extractAgentHandoff)(projectRoot),
+        (0, evidence_extractors_1.extractEvidence)(projectRoot),
+        (0, release_extractors_1.extractReleaseReadiness)(projectRoot)
+    ];
+    if (options.includeCode)
+        results.push((0, code_graph_extractor_1.extractCodeIndexGraph)(projectRoot, options.generatedAt));
+    return results;
+}
+function collectContextGraphExtractionsWithCache(projectRoot, options = {}) {
+    if (options.cacheStrategy === 'disabled') {
+        return {
+            extractionResults: collectContextGraphExtractions(projectRoot, options),
+            cache: { used: false, hit: false }
+        };
+    }
+    const generatedAt = options.generatedAt ?? new Date().toISOString();
+    const analysis = (0, context_cache_store_1.createSourceManifestCacheAnalysis)({
+        projectRoot,
+        generatedAt,
+        generatedByCommand: 'context.graph'
+    });
+    const graphCore = (0, context_cache_store_1.readContextGraphCoreShard)({ projectRoot, manifest: analysis.currentManifest });
+    if (graphCore.hit && graphCore.result) {
+        const results = [graphCore.result];
+        const code = options.includeCode
+            ? collectCodeGraphExtractionWithCache(projectRoot, {
+                manifest: analysis.currentManifest,
+                generatedAt
+            })
+            : undefined;
+        if (code)
+            results.push(code.result);
+        return {
+            extractionResults: results,
+            cache: {
+                used: true,
+                hit: true,
+                mode: options.includeCode ? code?.cache.mode ?? 'graph-core+live-code' : 'graph-core',
+                manifestHash: analysis.currentManifest.manifestHash,
+                readShardCount: 1 + (code?.cache.readShardCount ?? 0),
+                hitShardCount: 1 + (code?.cache.hitShardCount ?? 0),
+                missShardCount: code?.cache.missShardCount ?? 0,
+                staleShardCount: code?.cache.staleShardCount ?? 0,
+                corruptShardCount: code?.cache.corruptShardCount ?? 0,
+                schemaMismatchShardCount: code?.cache.schemaMismatchShardCount ?? 0,
+                shardPaths: [graphCore.path, ...(code?.cache.shardPaths ?? [])].sort(),
+                staleExtractorKeys: code?.cache.staleExtractorKeys ?? [],
+                ...(graphCore.record ? { createdAt: graphCore.record.createdAt, cachePath: graphCore.path } : {}),
+                sourceManifestCacheFresh: analysis.cacheFresh,
+                sourceManifestFastPath: analysis.fastPath,
+                ...(analysis.fastPathReason ? { sourceManifestFastPathReason: analysis.fastPathReason } : {}),
+                ...(analysis.fastPathStrategy ? { sourceManifestFastPathStrategy: analysis.fastPathStrategy } : {})
+            }
+        };
+    }
+    const shards = (0, context_cache_store_1.collectContextGraphExtractorShards)({ projectRoot, manifest: analysis.currentManifest });
+    const results = [
+        (0, task_extractors_1.extractTaskCapsules)(projectRoot),
+        shards.results.extractTaskBoard ?? (0, task_extractors_1.extractTaskBoard)(projectRoot),
+        shards.results.extractDocsRegistry ?? (0, registry_extractors_1.extractDocsRegistry)(projectRoot),
+        shards.results.extractCommandRegistry ?? (0, registry_extractors_1.extractCommandRegistry)(projectRoot),
+        (0, document_extractors_1.extractManagedSections)(projectRoot),
+        (0, document_extractors_1.extractProjectState)(projectRoot),
+        (0, document_extractors_1.extractDecisions)(projectRoot),
+        (0, document_extractors_1.extractAgentHandoff)(projectRoot),
+        (0, evidence_extractors_1.extractEvidence)(projectRoot),
+        (0, release_extractors_1.extractReleaseReadiness)(projectRoot)
+    ];
+    const code = options.includeCode
+        ? collectCodeGraphExtractionWithCache(projectRoot, {
+            manifest: analysis.currentManifest,
+            generatedAt
+        })
+        : undefined;
+    if (code)
+        results.push(code.result);
+    return {
+        extractionResults: results,
+        cache: {
+            ...mergeCodeCacheMetadata(shards.cache, code?.cache),
+            sourceManifestCacheFresh: analysis.cacheFresh,
+            sourceManifestFastPath: analysis.fastPath,
+            ...(analysis.fastPathReason ? { sourceManifestFastPathReason: analysis.fastPathReason } : {}),
+            ...(analysis.fastPathStrategy ? { sourceManifestFastPathStrategy: analysis.fastPathStrategy } : {})
+        }
+    };
+}
+function collectCodeGraphExtractionWithCache(projectRoot, input) {
+    const read = (0, context_cache_store_1.readContextCodeIndexShard)({ projectRoot, manifest: input.manifest });
+    if (read.hit && read.result) {
+        return {
+            result: (0, code_graph_extractor_1.codeIndexReportToGraphExtraction)(read.result),
+            cache: {
+                used: true,
+                hit: true,
+                mode: 'graph-core+code-index',
+                manifestHash: input.manifest.manifestHash,
+                readShardCount: 1,
+                hitShardCount: 1,
+                missShardCount: 0,
+                staleShardCount: 0,
+                corruptShardCount: 0,
+                schemaMismatchShardCount: 0,
+                shardPaths: [read.path],
+                staleExtractorKeys: [],
+                ...(read.record ? { createdAt: read.record.createdAt, cachePath: read.path } : {})
+            }
+        };
+    }
+    return {
+        result: (0, code_graph_extractor_1.extractCodeIndexGraph)(projectRoot, input.generatedAt),
+        cache: {
+            used: false,
+            hit: false,
+            mode: 'graph-core+live-code',
+            manifestHash: input.manifest.manifestHash,
+            readShardCount: 1,
+            hitShardCount: 0,
+            missShardCount: read.status === 'missing' ? 1 : 0,
+            staleShardCount: read.status === 'stale' ? 1 : 0,
+            corruptShardCount: read.status === 'corrupt' ? 1 : 0,
+            schemaMismatchShardCount: read.status === 'schema-mismatch' ? 1 : 0,
+            shardPaths: [read.path],
+            staleExtractorKeys: read.status === 'stale' ? ['codeIndex'] : []
+        }
+    };
+}
+function mergeCodeCacheMetadata(base, code) {
+    if (!code)
+        return base;
+    return {
+        ...base,
+        used: base.used || code.used,
+        hit: base.hit || code.hit,
+        mode: code.hit ? 'extractor-shards+code-index' : 'extractor-shards+live-code',
+        readShardCount: (base.readShardCount ?? 0) + (code.readShardCount ?? 0),
+        hitShardCount: (base.hitShardCount ?? 0) + (code.hitShardCount ?? 0),
+        missShardCount: (base.missShardCount ?? 0) + (code.missShardCount ?? 0),
+        staleShardCount: (base.staleShardCount ?? 0) + (code.staleShardCount ?? 0),
+        corruptShardCount: (base.corruptShardCount ?? 0) + (code.corruptShardCount ?? 0),
+        schemaMismatchShardCount: (base.schemaMismatchShardCount ?? 0) + (code.schemaMismatchShardCount ?? 0),
+        shardPaths: [...(base.shardPaths ?? []), ...(code.shardPaths ?? [])].sort(),
+        staleExtractorKeys: [...(base.staleExtractorKeys ?? []), ...(code.staleExtractorKeys ?? [])].sort(),
+        ...(code.hit && code.cachePath ? { cachePath: code.cachePath } : {}),
+        ...(code.hit && code.createdAt ? { createdAt: code.createdAt } : {})
+    };
+}
+function buildContextGraphReport(input) {
+    const generatedAt = input.generatedAt ?? new Date().toISOString();
+    const collected = input.extractionResults ? undefined : collectContextGraphExtractionsWithCache(input.projectRoot, {
+        includeCode: input.includeCode,
+        generatedAt,
+        cacheStrategy: input.cacheStrategy
+    });
+    const extractionResults = input.extractionResults ?? collected?.extractionResults ?? [];
+    const merged = (0, extractor_contract_1.mergeGraphExtractionResults)(extractionResults);
+    const stateProjection = (0, state_projection_1.createContextStateProjectionReport)({ generatedAt, extractionResults });
+    const mode = input.mode ?? (input.taskId ? 'task' : 'full');
+    const taskContext = input.taskId
+        ? createTaskContextReport({
+            taskId: input.taskId,
+            nodes: merged.nodes,
+            edges: merged.edges,
+            stateProjection,
+            issues: merged.issues
+        })
+        : undefined;
+    return {
+        schemaVersion: 'hadara.contextGraph.v1',
+        command: 'context.graph',
+        ok: merged.issues.every((issue) => issue.severity !== 'error') && stateProjection.ok,
+        generatedAt,
+        projectRoot: input.projectRoot,
+        sourceHash: merged.source.sourceHash,
+        mode,
+        ...(input.taskId ? { taskId: input.taskId } : {}),
+        nodes: merged.nodes,
+        edges: merged.edges,
+        ...(taskContext ? { taskContext } : {}),
+        stateProjection,
+        summary: (0, extractor_contract_1.summarizeContextGraphExtraction)(merged.nodes, merged.edges, merged.issues),
+        cache: input.cache ?? collected?.cache ?? { used: false, hit: false },
+        issues: merged.issues
+    };
+}
+function createTaskContextReport(input) {
+    const task = findTaskNode(input.nodes, input.taskId);
+    const connectedNodes = connectedNodeIds(input.edges, (0, extractor_contract_1.createTaskNodeId)(input.taskId));
+    const readFirst = task ? [candidate(task, 'Active task capsule is the first read for task-scoped context routing.', 'explicit')] : [];
+    return {
+        schemaVersion: 'hadara.taskContext.v1',
+        taskId: input.taskId,
+        ...(task ? { task } : {}),
+        readFirst,
+        readIfNeeded: readIfNeededCandidates(input.nodes, input.edges, connectedNodes),
+        doNotReadByDefault: doNotReadByDefaultCandidates(input.nodes),
+        relatedEvidence: relatedEvidenceCandidates(input.nodes, input.edges, input.taskId),
+        relatedCommands: relatedCommandCandidates(input.nodes, input.edges, connectedNodes),
+        knownProblems: knownProblemCandidates(input.nodes),
+        validationSuggestions: validationSuggestions(input.taskId),
+        stateIssues: taskStateIssues(input.stateProjection.issues, input.taskId),
+        issues: input.issues
+    };
+}
+function findTaskNode(nodes, taskId) {
+    const nodeId = (0, extractor_contract_1.createTaskNodeId)(taskId);
+    const matches = nodes.filter((node) => node.id === nodeId && node.type === 'Task');
+    return matches.find((node) => node.kind === 'task-capsule') ?? matches[0];
+}
+function readIfNeededCandidates(nodes, edges, connectedIds) {
+    const candidates = new Map();
+    for (const node of nodes) {
+        if (node.type !== 'Document')
+            continue;
+        if (metadataBoolean(node, 'requiredReading')) {
+            candidates.set(node.id, candidate(node, 'Document registry marks this document as required reading.', 'explicit'));
+            continue;
+        }
+        if (connectedIds.has(node.id)) {
+            candidates.set(node.id, candidate(node, 'Document is directly connected to the task graph.', 'derived'));
+        }
+    }
+    for (const edge of edges) {
+        if (!connectedIds.has(edge.from) && !connectedIds.has(edge.to))
+            continue;
+        const from = nodes.find((node) => node.id === edge.from);
+        const to = nodes.find((node) => node.id === edge.to);
+        for (const node of [from, to]) {
+            if (node?.type !== 'Document' || candidates.has(node.id))
+                continue;
+            candidates.set(node.id, candidate(node, edge.reason, edge.confidence));
+        }
+    }
+    return sortCandidates(Array.from(candidates.values()));
+}
+function doNotReadByDefaultCandidates(nodes) {
+    return sortCandidates(nodes
+        .filter((node) => node.type === 'Document')
+        .filter((node) => {
+        const status = String(node.status ?? '').toLowerCase();
+        const kind = String(node.kind ?? '').toLowerCase();
+        const readWhen = Array.isArray(node.metadata?.readWhen) ? node.metadata.readWhen.map(String) : [];
+        return status === 'archived'
+            || status === 'superseded'
+            || kind.includes('historical')
+            || readWhen.includes('historical')
+            || metadataBoolean(node, 'requiredReading') === false && kind.includes('archive');
+    })
+        .map((node) => candidate(node, 'Historical, archived, or superseded document is excluded from default task routing.', 'derived')));
+}
+function relatedEvidenceCandidates(nodes, edges, taskId) {
+    const taskNodeId = (0, extractor_contract_1.createTaskNodeId)(taskId);
+    const evidenceIds = new Set(edges
+        .filter((edge) => edge.from === taskNodeId && (edge.type === 'HAS_EVIDENCE' || edge.type === 'CLOSES_WITH'))
+        .map((edge) => edge.to));
+    return sortCandidates(nodes
+        .filter((node) => node.type === 'Evidence' && evidenceIds.has(node.id))
+        .map((node) => candidate(node, 'Evidence is directly linked to this task.', 'explicit')));
+}
+function relatedCommandCandidates(nodes, edges, connectedIds) {
+    const commandIds = new Set();
+    for (const edge of edges) {
+        if (edge.type !== 'DESCRIBES_COMMAND' && edge.type !== 'CHECKS_COMMAND')
+            continue;
+        if (connectedIds.has(edge.from))
+            commandIds.add(edge.to);
+        if (connectedIds.has(edge.to))
+            commandIds.add(edge.from);
+    }
+    return sortCandidates(nodes
+        .filter((node) => node.type === 'Command' && commandIds.has(node.id))
+        .map((node) => candidate(node, 'Command is connected through task-relevant documentation or release checks.', 'derived')));
+}
+function knownProblemCandidates(nodes) {
+    return sortCandidates(nodes
+        .filter((node) => node.type === 'KnownProblem')
+        .map((node) => candidate(node, 'Current handoff records this known problem.', 'explicit')));
+}
+function taskStateIssues(issues, taskId) {
+    const relevant = issues.filter((issue) => issue.message.includes(taskId) || issue.paths.some((path) => path.includes(taskId)));
+    if (relevant.length > 0)
+        return relevant;
+    return issues.filter((issue) => issue.code === 'STATE_ACTIVE_TASK_MISMATCH' || issue.code === 'STATE_TASK_CAPSULE_MISSING');
+}
+function connectedNodeIds(edges, taskNodeId) {
+    const ids = new Set([taskNodeId]);
+    for (const edge of edges) {
+        if (edge.from === taskNodeId)
+            ids.add(edge.to);
+        if (edge.to === taskNodeId)
+            ids.add(edge.from);
+    }
+    return ids;
+}
+function candidate(node, reason, confidence) {
+    return {
+        id: node.id,
+        type: node.type,
+        ...(node.path ? { path: node.path } : {}),
+        reason,
+        confidence,
+        ...(node.source.hash ? { sourceHash: node.source.hash } : {})
+    };
+}
+function metadataBoolean(node, key) {
+    const value = node.metadata?.[key];
+    return typeof value === 'boolean' ? value : undefined;
+}
+function validationSuggestions(taskId) {
+    return [
+        'npm run test:focused -- tests/unit/context-graph-builder.test.ts',
+        `node dist/cli/main.js task ready --task ${taskId} --level done --json`
+    ];
+}
+function sortCandidates(candidates) {
+    return candidates.sort((a, b) => a.id.localeCompare(b.id));
+}

package/dist/context/context-graph.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CONTEXT_CONFIDENCE_LEVELS = exports.CONTEXT_GRAPH_EDGE_TYPES = exports.CONTEXT_GRAPH_NODE_TYPES = exports.TASK_CONTEXT_SCHEMA_ID = exports.CONTEXT_GRAPH_SCHEMA_ID = void 0;
+exports.CONTEXT_GRAPH_SCHEMA_ID = 'hadara.contextGraph.v1';
+exports.TASK_CONTEXT_SCHEMA_ID = 'hadara.taskContext.v1';
+exports.CONTEXT_GRAPH_NODE_TYPES = [
+    'Task',
+    'Document',
+    'ManagedSection',
+    'Evidence',
+    'Command',
+    'ReleaseCheck',
+    'Decision',
+    'KnownProblem',
+    'SourceFile',
+    'TestFile',
+    'FixtureFile',
+    'ConfigFile',
+    'Symbol'
+];
+exports.CONTEXT_GRAPH_EDGE_TYPES = [
+    'HAS_EVIDENCE',
+    'CLOSES_WITH',
+    'REFERENCES_DOC',
+    'REQUIRED_FOR',
+    'SUPERSEDES',
+    'DESCRIBES_COMMAND',
+    'BELONGS_TO_DOCUMENT',
+    'CHECKS_COMMAND',
+    'AFFECTS_SURFACE',
+    'DEPENDS_ON_EVIDENCE',
+    'HAS_DECISION',
+    'HAS_KNOWN_PROBLEM',
+    'IMPORTS',
+    'EXPORTS',
+    'DEFINES_SYMBOL',
+    'TESTS_FILE',
+    'IMPLEMENTS_COMMAND',
+    'REFERENCED_BY_DOC',
+    'VALIDATED_BY_EVIDENCE'
+];
+exports.CONTEXT_CONFIDENCE_LEVELS = ['explicit', 'derived', 'heuristic'];