hadara 0.3.2 → 0.3.3

package/dist/context/context-pack.js

@@ -0,0 +1,457 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CONTEXT_PACK_DEFAULT_BUDGET = exports.CONTEXT_PACK_COMMAND = exports.CONTEXT_PACK_SCHEMA_ID = void 0;
+exports.buildContextPackReport = buildContextPackReport;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const context_graph_builder_1 = require("./context-graph-builder");
+const context_slice_boundary_1 = require("./context-slice-boundary");
+const extractor_contract_1 = require("./extractor-contract");
+exports.CONTEXT_PACK_SCHEMA_ID = 'hadara.contextPack.v1';
+exports.CONTEXT_PACK_COMMAND = 'context.pack';
+exports.CONTEXT_PACK_DEFAULT_BUDGET = {
+    maxReadFirstItems: 7,
+    mode: 'bounded'
+};
+function buildContextPackReport(input) {
+    const generatedAt = input.generatedAt ?? new Date().toISOString();
+    const budget = normalizeContextBudget(input.budget);
+    const graphReport = input.graphReport ?? (0, context_graph_builder_1.buildContextGraphReport)({
+        projectRoot: input.projectRoot,
+        generatedAt,
+        includeCode: input.includeCode,
+        ...(input.taskId ? { taskId: input.taskId, mode: 'task' } : { mode: 'full' })
+    });
+    const taskId = input.taskId ?? graphReport.taskId ?? graphReport.stateProjection.summary.activeTask;
+    const issues = [];
+    const taskNode = taskId ? findTaskNode(graphReport.nodes, taskId) : undefined;
+    if (!taskId || !taskNode) {
+        issues.push({
+            severity: 'error',
+            code: 'CONTEXT_PACK_TASK_NOT_FOUND',
+            message: taskId
+                ? `Context pack could not find task ${taskId} in the context graph.`
+                : 'Context pack requires a task id or active task from state projection.',
+            fixHint: 'Pass --task <task-id> once the public context pack command exists, or repair project active task state.'
+        });
+    }
+    if (!graphReport.stateProjection) {
+        issues.push({
+            severity: 'warning',
+            code: 'CONTEXT_PACK_STATE_PROJECTION_UNAVAILABLE',
+            message: 'Context graph did not include a state projection.',
+            fixHint: 'Rebuild the context graph with state projection extraction enabled.'
+        });
+    }
+    if (graphReport.summary.degraded) {
+        issues.push({
+            severity: 'warning',
+            code: 'CONTEXT_PACK_DEGRADED',
+            message: 'Context graph is degraded; context pack output may be partial.'
+        });
+    }
+    if (input.includeCode && !codeIndexAvailable(graphReport)) {
+        issues.push({
+            severity: 'warning',
+            code: 'CONTEXT_PACK_CODE_INDEX_UNAVAILABLE',
+            message: 'Code-aware context pack was requested, but code index output is unavailable.',
+            fixHint: 'Build the graph with includeCode enabled after C2 code index support is available.'
+        });
+    }
+    const connectedIds = taskId ? connectedNodeIds(graphReport.edges, (0, extractor_contract_1.createTaskNodeId)(taskId)) : new Set();
+    const rankedNodes = rankContextPackNodes(graphReport.nodes, graphReport.edges, connectedIds, taskNode);
+    const readFirstRanked = rankedNodes.filter((ranked) => isReadFirstAllowed(ranked.node));
+    const readFirst = readFirstRanked
+        .slice(0, budget.maxReadFirstItems)
+        .map((ranked) => itemFromRankedNode(ranked, true, input.projectRoot));
+    if (readFirstRanked.length > readFirst.length) {
+        issues.push({
+            severity: 'warning',
+            code: 'CONTEXT_PACK_BUDGET_TRUNCATED',
+            message: `Context pack readFirst items were truncated from ${readFirstRanked.length} to ${readFirst.length}.`
+        });
+    }
+    const selectedIds = new Set(readFirst.map((item) => item.id));
+    const maxReadIfNeeded = Math.max(0, (budget.maxItems ?? 30) - readFirst.length);
+    const readIfNeededRanked = rankedNodes
+        .filter((ranked) => !selectedIds.has(ranked.node.id))
+        .filter((ranked) => !isDoNotReadByDefault(ranked.node));
+    const readIfNeeded = readIfNeededRanked
+        .slice(0, maxReadIfNeeded)
+        .map((ranked) => itemFromRankedNode(ranked, false, input.projectRoot));
+    if (readIfNeededRanked.length > readIfNeeded.length) {
+        issues.push({
+            severity: 'warning',
+            code: 'CONTEXT_PACK_BUDGET_TRUNCATED',
+            message: `Context pack readIfNeeded items were truncated from ${readIfNeededRanked.length} to ${readIfNeeded.length}.`
+        });
+    }
+    const doNotReadByDefault = graphReport.nodes
+        .filter((node) => node.type === 'Document')
+        .filter(isDoNotReadByDefault)
+        .map((node) => itemFromRankedNode({
+        node,
+        reason: 'Historical, archived, superseded, or excluded document is not read by default.',
+        confidence: 'derived',
+        score: 0
+    }, false, input.projectRoot))
+        .sort(compareItems);
+    const knownProblems = graphReport.nodes
+        .filter((node) => node.type === 'KnownProblem')
+        .map((node) => itemFromRankedNode({
+        node,
+        reason: 'Current project handoff records this known problem.',
+        confidence: 'explicit',
+        score: 0
+    }, false, input.projectRoot))
+        .sort(compareItems);
+    const cache = input.cache ?? graphReport.cache ?? { used: false, hit: false };
+    return {
+        schemaVersion: exports.CONTEXT_PACK_SCHEMA_ID,
+        command: exports.CONTEXT_PACK_COMMAND,
+        ok: issues.every((issue) => issue.severity !== 'error'),
+        generatedAt,
+        ...(taskId ? { taskId } : {}),
+        projectRoot: input.projectRoot,
+        budget,
+        readFirst,
+        readIfNeeded,
+        doNotReadByDefault,
+        validateWith: validationSuggestionsForTask(taskId, graphReport),
+        writeBoundaries: writeBoundariesForItems([...readFirst, ...readIfNeeded], graphReport.nodes),
+        sliceCandidates: sliceCandidatesForItems([...readFirst, ...readIfNeeded], graphReport.nodes),
+        knownProblems,
+        stateProjection: {
+            ...graphReport.stateProjection.summary,
+            issues: graphReport.stateProjection.issues
+        },
+        sourceSummary: {
+            graphAvailable: true,
+            codeIndexAvailable: codeIndexAvailable(graphReport),
+            stateProjectionAvailable: true,
+            docsRegistryAvailable: graphReport.stateProjection.sources.some((source) => source.kind === 'docs-registry'),
+            commandRegistryAvailable: graphReport.nodes.some((node) => node.type === 'Command'),
+            degraded: graphReport.summary.degraded || issues.some((issue) => issue.severity !== 'info'),
+            graphSourceHash: graphReport.sourceHash,
+            sourcesRead: graphReport.summary.sourcesRead
+        },
+        cache,
+        issues
+    };
+}
+function normalizeContextBudget(input = {}) {
+    const maxReadFirstItems = positiveInteger(input.maxReadFirstItems) ?? exports.CONTEXT_PACK_DEFAULT_BUDGET.maxReadFirstItems;
+    return {
+        ...(input.targetTokens !== undefined ? { targetTokens: input.targetTokens } : {}),
+        ...(input.maxItems !== undefined ? { maxItems: input.maxItems } : {}),
+        maxReadFirstItems,
+        mode: input.mode ?? exports.CONTEXT_PACK_DEFAULT_BUDGET.mode
+    };
+}
+function positiveInteger(value) {
+    return typeof value === 'number' && Number.isInteger(value) && value > 0 ? value : undefined;
+}
+function rankContextPackNodes(nodes, edges, connectedIds, taskNode) {
+    const ranked = new Map();
+    if (taskNode) {
+        ranked.set(taskNode.id, {
+            node: taskNode,
+            reason: 'Active task capsule is the first read for task-scoped context routing.',
+            confidence: 'explicit',
+            score: 1000
+        });
+    }
+    const nodeById = new Map(nodes.map((node) => [node.id, node]));
+    for (const edge of edges) {
+        if (!connectedIds.has(edge.from) && !connectedIds.has(edge.to))
+            continue;
+        for (const nodeId of [edge.from, edge.to]) {
+            const node = nodeById.get(nodeId);
+            if (!node || node.type === 'Task')
+                continue;
+            upsertRankedNode(ranked, {
+                node,
+                reason: edge.reason,
+                confidence: edge.confidence,
+                score: nodeScore(node, edge.confidence, connectedIds.has(node.id))
+            });
+        }
+    }
+    for (const node of nodes) {
+        if (node.type !== 'Document' || ranked.has(node.id))
+            continue;
+        if (metadataBoolean(node, 'requiredReading')) {
+            upsertRankedNode(ranked, {
+                node,
+                reason: 'Document registry marks this document as required reading.',
+                confidence: 'explicit',
+                score: nodeScore(node, 'explicit', false) - 25
+            });
+        }
+    }
+    return Array.from(ranked.values()).sort(compareRankedNodes);
+}
+function upsertRankedNode(ranked, candidate) {
+    const existing = ranked.get(candidate.node.id);
+    if (!existing || compareRankedNodes(candidate, existing) < 0) {
+        ranked.set(candidate.node.id, candidate);
+    }
+}
+function nodeScore(node, confidence, connected) {
+    const confidenceScore = confidence === 'explicit' ? 80 : confidence === 'derived' ? 50 : 20;
+    const connectedScore = connected ? 25 : 0;
+    const typeScore = {
+        Task: 1000,
+        Document: 700,
+        ManagedSection: 680,
+        Command: 620,
+        KnownProblem: 600,
+        Evidence: 550,
+        ReleaseCheck: 520,
+        Decision: 500,
+        SourceFile: 480,
+        TestFile: 460,
+        Symbol: 440,
+        FixtureFile: 380,
+        ConfigFile: 360
+    };
+    return typeScore[node.type] + confidenceScore + connectedScore;
+}
+function isReadFirstAllowed(node) {
+    if (isDoNotReadByDefault(node))
+        return false;
+    return ['Task', 'Document', 'ManagedSection', 'Command', 'SourceFile', 'TestFile', 'Symbol', 'KnownProblem'].includes(node.type);
+}
+function isDoNotReadByDefault(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')
+        || readWhen.includes('never-default')
+        || (metadataBoolean(node, 'requiredReading') === false && kind.includes('archive'));
+}
+function itemFromRankedNode(ranked, required, projectRoot) {
+    const line = ranked.node.source.line;
+    const sourceHash = sourceHashForItem(projectRoot, ranked.node);
+    return {
+        id: ranked.node.id,
+        type: ranked.node.type,
+        ...(ranked.node.path ? { path: ranked.node.path } : {}),
+        ...(line ? { lineStart: line, lineEnd: line } : {}),
+        title: ranked.node.label,
+        reason: ranked.reason,
+        confidence: ranked.confidence,
+        ...(sourceHash ? { sourceHash } : {}),
+        ...(ranked.node.path ? { estimatedTokens: estimateTokens(ranked.node) } : {}),
+        required,
+        sourceAccess: sourceAccessForNode(ranked.node)
+    };
+}
+function sourceHashForItem(projectRoot, node) {
+    if (!node.path || !(0, context_slice_boundary_1.isContextSliceProjectRelativePath)(node.path))
+        return node.source.hash;
+    const normalized = (0, context_slice_boundary_1.normalizeContextSliceInputPath)(node.path);
+    const root = node_path_1.default.resolve(projectRoot);
+    const absolutePath = node_path_1.default.resolve(root, normalized);
+    if (absolutePath !== root && !absolutePath.startsWith(`${root}${node_path_1.default.sep}`))
+        return node.source.hash;
+    try {
+        const stat = node_fs_1.default.statSync(absolutePath);
+        if (!stat.isFile())
+            return node.source.hash;
+        return (0, extractor_contract_1.hashContextGraphText)(node_fs_1.default.readFileSync(absolutePath, 'utf8'));
+    }
+    catch {
+        return node.source.hash;
+    }
+}
+function sourceAccessForNode(node) {
+    if (!node.path) {
+        return {
+            rawSlice: 'not-applicable',
+            reason: 'This context item has no project file path for raw context slicing.'
+        };
+    }
+    if ((0, context_slice_boundary_1.isContextSliceProjectRelativePath)(node.path)) {
+        return {
+            rawSlice: 'sliceable',
+            reason: 'This item path is inside the raw context-slice read boundary.'
+        };
+    }
+    return {
+        rawSlice: 'not-sliceable',
+        reason: 'This item remains graph context, but its path is outside the raw context-slice read boundary.'
+    };
+}
+function estimateTokens(node) {
+    const labelCost = Math.ceil(node.label.length / 4);
+    const pathCost = node.path ? Math.ceil(node.path.length / 4) : 0;
+    return Math.max(24, labelCost + pathCost + 16);
+}
+function validationSuggestionsForTask(taskId, graphReport) {
+    const suggestions = new Map();
+    if (taskId) {
+        suggestions.set(`ready:${taskId}`, {
+            command: `node dist/cli/main.js task ready --task ${taskId} --level done --json`,
+            reason: 'Done-level readiness is required before closing this task.',
+            requiredForClose: true,
+            source: 'evidence-history'
+        });
+    }
+    for (const suggestion of graphReport.taskContext?.validationSuggestions ?? []) {
+        const source = suggestion.includes('npm run') || suggestion.includes('test')
+            ? 'task-tests'
+            : suggestion.includes('release')
+                ? 'release-readiness'
+                : 'heuristic';
+        suggestions.set(suggestion, {
+            command: suggestion,
+            reason: 'Task context report suggested this validation command.',
+            requiredForClose: false,
+            source
+        });
+    }
+    return Array.from(suggestions.values()).sort((a, b) => a.command.localeCompare(b.command));
+}
+function writeBoundariesForItems(items, nodes) {
+    const nodeById = new Map(nodes.map((node) => [node.id, node]));
+    const boundaries = new Map();
+    for (const item of items) {
+        if (!item.path)
+            continue;
+        const node = nodeById.get(item.id);
+        const boundary = boundaryForPath(item.path, node);
+        boundaries.set(item.path, {
+            path: item.path,
+            boundary,
+            reason: boundaryReason(item.path, boundary)
+        });
+    }
+    return Array.from(boundaries.values()).sort((a, b) => a.path.localeCompare(b.path));
+}
+function boundaryForPath(path, node) {
+    if (path.endsWith('evidence.jsonl'))
+        return 'append-only';
+    if (path === 'docs/TASK_BOARD.md' || path.endsWith('/TASK.md'))
+        return 'dry-run-first';
+    if (node?.type === 'ManagedSection')
+        return 'managed-section';
+    if (path.startsWith('docs/') || path.startsWith('tasks/'))
+        return 'agent-freeform';
+    return 'read-only';
+}
+function boundaryReason(path, boundary) {
+    if (boundary === 'append-only')
+        return 'Evidence files are append-only and must use the evidence writer.';
+    if (boundary === 'dry-run-first')
+        return `${path} has command-owned lifecycle fields; use dry-run-first lifecycle commands where applicable.`;
+    if (boundary === 'managed-section')
+        return 'Managed section edits must preserve HADARA markers.';
+    if (boundary === 'agent-freeform')
+        return 'Project documentation or task capsule prose can be edited by the agent within task scope.';
+    return 'Read for context only; do not mutate from context routing commands.';
+}
+function sliceCandidatesForItems(items, nodes) {
+    const nodeById = new Map(nodes.map((node) => [node.id, node]));
+    return items
+        .filter((item) => item.path)
+        .filter((item) => (0, context_slice_boundary_1.isContextSliceProjectRelativePath)(item.path))
+        .filter((item) => ['Document', 'ManagedSection', 'SourceFile', 'TestFile', 'Symbol'].includes(item.type))
+        .slice(0, 10)
+        .map((item, index) => {
+        const node = nodeById.get(item.id);
+        const strategy = sliceStrategyForNode(node);
+        const path = item.path;
+        const range = explicitRangeForCandidate(item, node);
+        const lineStart = range?.lineStart;
+        const lineEnd = range?.lineEnd;
+        const symbol = node?.type === 'Symbol' ? node.label : undefined;
+        const managedSection = node?.type === 'ManagedSection' ? node.label : undefined;
+        const suggestedCommandArgs = suggestedSliceCommandArgs(path, strategy, node, { lineStart, lineEnd, symbol, managedSection });
+        return {
+            id: `slice-candidate:${index + 1}:${item.id}`,
+            path,
+            strategy,
+            ...(lineStart ? { lineStart } : {}),
+            ...(lineEnd ? { lineEnd } : {}),
+            ...(symbol ? { symbol } : {}),
+            ...(managedSection ? { managedSection } : {}),
+            reason: `Candidate slice for ${item.id} selected by context pack ranking.`,
+            suggestedCommand: suggestedSliceCommand(suggestedCommandArgs),
+            suggestedCommandArgs
+        };
+    });
+}
+function explicitRangeForCandidate(item, node) {
+    const lineStart = item.lineStart ?? numberMetadata(node, 'startLine') ?? node?.source.line ?? 1;
+    const metadataEnd = numberMetadata(node, 'endLine');
+    if (metadataEnd !== undefined && metadataEnd > lineStart)
+        return { lineStart, lineEnd: metadataEnd };
+    if (item.lineEnd !== undefined && item.lineEnd > lineStart)
+        return { lineStart, lineEnd: item.lineEnd };
+    return { lineStart, lineEnd: Math.max(lineStart, lineStart + 80) };
+}
+function sliceStrategyForNode(node) {
+    if (node?.type === 'ManagedSection')
+        return 'managed-section';
+    if (node?.type === 'Symbol')
+        return 'symbol-neighborhood';
+    return 'explicit-range';
+}
+function suggestedSliceCommandArgs(path, strategy, node, hints = {}) {
+    const base = ['context', 'slice', '--path', path];
+    if (strategy === 'managed-section')
+        return [...base, '--managed-section', hints.managedSection ?? node?.label ?? '<section-id>', '--json'];
+    if (strategy === 'symbol-neighborhood')
+        return [...base, '--symbol', hints.symbol ?? node?.label ?? '<symbol>', '--json'];
+    const startLine = hints.lineStart ?? node?.source.line ?? 1;
+    const endLine = hints.lineEnd ?? Math.max(startLine, startLine + 80);
+    return [...base, '--from', String(startLine), '--to', String(endLine), '--json'];
+}
+function suggestedSliceCommand(args) {
+    return ['hadara', ...args].map(shellQuote).join(' ');
+}
+function shellQuote(value) {
+    if (/^[A-Za-z0-9_./:@+-]+$/.test(value))
+        return value;
+    return `'${value.replace(/'/g, "'\\''")}'`;
+}
+function numberMetadata(node, key) {
+    const value = node?.metadata?.[key];
+    return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+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 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 codeIndexAvailable(graphReport) {
+    return graphReport.stateProjection.sources.some((source) => source.kind === 'code-index')
+        || graphReport.nodes.some((node) => ['SourceFile', 'TestFile', 'Symbol'].includes(node.type));
+}
+function metadataBoolean(node, key) {
+    const value = node.metadata?.[key];
+    return typeof value === 'boolean' ? value : undefined;
+}
+function compareRankedNodes(a, b) {
+    return b.score - a.score || a.node.id.localeCompare(b.node.id);
+}
+function compareItems(a, b) {
+    return a.id.localeCompare(b.id);
+}

package/dist/context/context-slice-boundary.js

@@ -0,0 +1,37 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CONTEXT_SLICE_DENIED_PATHS = exports.CONTEXT_SLICE_HADARA_ALLOWLIST = void 0;
+exports.normalizeContextSliceInputPath = normalizeContextSliceInputPath;
+exports.isDeniedContextSlicePath = isDeniedContextSlicePath;
+exports.isContextSliceProjectRelativePath = isContextSliceProjectRelativePath;
+const node_path_1 = __importDefault(require("node:path"));
+const extractor_contract_1 = require("./extractor-contract");
+exports.CONTEXT_SLICE_HADARA_ALLOWLIST = new Set([
+    '.hadara/context/HADARA_CONTEXT.md',
+    '.hadara/docs-registry.json'
+]);
+exports.CONTEXT_SLICE_DENIED_PATHS = [
+    '.git',
+    'node_modules',
+    '.hadara/tmp',
+    '.hadara/run',
+    '.dashboard-visual'
+];
+function normalizeContextSliceInputPath(inputPath) {
+    return inputPath ? (0, extractor_contract_1.normalizeContextGraphPath)(inputPath.replace(/^\.?\//, '')) : '';
+}
+function isDeniedContextSlicePath(normalized) {
+    if (normalized.startsWith('.hadara/') && !exports.CONTEXT_SLICE_HADARA_ALLOWLIST.has(normalized))
+        return true;
+    return exports.CONTEXT_SLICE_DENIED_PATHS.some((denied) => normalized === denied || normalized.startsWith(`${denied}/`));
+}
+function isContextSliceProjectRelativePath(inputPath) {
+    const normalized = normalizeContextSliceInputPath(inputPath);
+    return Boolean(normalized)
+        && !node_path_1.default.isAbsolute(inputPath ?? '')
+        && !normalized.split('/').includes('..')
+        && !isDeniedContextSlicePath(normalized);
+}