@planu/cli 4.6.0 → 4.7.0

package/CHANGELOG.md

@@ -1,3 +1,21 @@
+## [4.7.0] - 2026-06-12
+
+### Features
+- feat(SPEC-1085): add project knowledge graph
+
+### Bug Fixes
+- fix(security): override esbuild patched release
+
+### Chores
+- chore(deps): refresh push-gate dependencies
+
+
+## [4.6.1] - 2026-06-12
+
+### Bug Fixes
+- fix(SPEC-1086): handle Vitest 4 JSON paths in validate
+
+
 ## [4.6.0] - 2026-06-11
 
 ### Features

package/dist/config/project-knowledge-graph.json

@@ -0,0 +1,65 @@
+{
+  "version": 1,
+  "graphVersion": "1.0.0",
+  "enabled": true,
+  "artifactPaths": {
+    "directory": "project-graph",
+    "graph": "project-knowledge-graph.json",
+    "sourceHashes": "source-hashes.json"
+  },
+  "nodeTypes": [
+    "spec",
+    "criterion",
+    "file",
+    "test",
+    "release",
+    "decision",
+    "risk",
+    "tool",
+    "handoff",
+    "validation",
+    "commit"
+  ],
+  "edgeTypes": [
+    "contains",
+    "references",
+    "implements",
+    "tests",
+    "validated_by",
+    "released_in",
+    "decides",
+    "has_risk",
+    "uses_tool",
+    "mentions",
+    "neighbors"
+  ],
+  "classifications": ["extracted", "inferred", "ambiguous"],
+  "confidenceLabels": ["high", "medium", "low"],
+  "freshness": {
+    "staleAfterMinutes": 1440
+  },
+  "query": {
+    "maxNodes": 60,
+    "maxEdges": 120,
+    "maxListItems": 12
+  },
+  "redaction": {
+    "maxSnippetChars": 240,
+    "redactPatterns": [
+      "sk-[A-Za-z0-9_-]+",
+      "ghp_[A-Za-z0-9_]+",
+      "xox[baprs]-[A-Za-z0-9-]+",
+      "(api[_-]?key|token|secret|password)\\s*[:=]\\s*[^\\s,;]+"
+    ]
+  },
+  "toolNamePatterns": [
+    "package_handoff",
+    "validate",
+    "create_spec",
+    "planu_status",
+    "token_intelligence",
+    "check_readiness",
+    "update_status",
+    "session_checkpoint"
+  ]
+}

package/dist/engine/project-graph/builder.d.ts

@@ -0,0 +1,7 @@
+import type { ProjectGraphBuildResult, ProjectGraphPolicy } from '../../types/project-knowledge-graph.js';
+export declare function buildProjectKnowledgeGraph(args: {
+    projectId: string;
+    projectPath: string;
+    policy?: ProjectGraphPolicy;
+}): Promise<ProjectGraphBuildResult>;
+//# sourceMappingURL=builder.d.ts.map

package/dist/engine/project-graph/builder.js

@@ -0,0 +1,92 @@
+import { collectProjectGraphSources, diffSourceHashes, hashText, loadProjectGraphPolicy, projectGraphCachePath, projectGraphPath, readProjectGraph, readProjectGraphSourceHashes, writeProjectGraph, writeProjectGraphSourceHashes, } from './cache.js';
+import { extractGitGraph, extractReleaseGraph } from './extractors/git-extractor.js';
+import { extractHandoffGraph } from './extractors/handoff-extractor.js';
+import { extractSpecGraph } from './extractors/spec-extractor.js';
+import { extractValidationGraph } from './extractors/validation-extractor.js';
+function uniqueNodes(nodes) {
+    return [...new Map(nodes.map((node) => [node.id, node])).values()];
+}
+function uniqueEdges(edges) {
+    return [...new Map(edges.map((edge) => [edge.id, edge])).values()];
+}
+function validateAgainstPolicy(result, policy) {
+    const nodes = result.nodes.filter((node) => policy.nodeTypes.includes(node.type));
+    const nodeIds = new Set(nodes.map((node) => node.id));
+    const edges = result.edges.filter((edge) => nodeIds.has(edge.from) &&
+        nodeIds.has(edge.to) &&
+        policy.edgeTypes.includes(edge.type) &&
+        policy.confidenceLabels.includes(edge.confidence) &&
+        policy.classifications.includes(edge.classification));
+    return { nodes, edges };
+}
+export async function buildProjectKnowledgeGraph(args) {
+    const policy = args.policy ?? (await loadProjectGraphPolicy());
+    const sources = await collectProjectGraphSources({
+        projectId: args.projectId,
+        projectPath: args.projectPath,
+        policy,
+    });
+    const previousHashes = await readProjectGraphSourceHashes(args.projectId, policy);
+    const diff = diffSourceHashes(sources, previousHashes);
+    const existingGraph = await readProjectGraph(args.projectId, policy);
+    if (existingGraph !== null && diff.changed.length === 0) {
+        return {
+            graph: existingGraph,
+            graphPath: projectGraphPath(args.projectId, policy),
+            cachePath: projectGraphCachePath(args.projectId, policy),
+            reprocessedSources: [],
+            skippedSources: diff.skipped,
+            usedCache: true,
+        };
+    }
+    const extracted = [];
+    for (const source of sources) {
+        if (source.kind === 'spec') {
+            extracted.push(extractSpecGraph(source, policy));
+        }
+        else if (source.kind === 'validation') {
+            extracted.push(extractValidationGraph(source, policy));
+        }
+        else if (source.kind === 'handoff') {
+            extracted.push(extractHandoffGraph(source, policy));
+        }
+        else if (source.kind === 'release-events') {
+            extracted.push(extractReleaseGraph(source, policy));
+        }
+    }
+    extracted.push(await extractGitGraph({ projectPath: args.projectPath, policy }));
+    const validated = extracted.map((result) => validateAgainstPolicy(result, policy));
+    const nodes = uniqueNodes(validated.flatMap((result) => result.nodes));
+    const edges = uniqueEdges(validated.flatMap((result) => result.edges));
+    const sourceHashes = diff.next;
+    const sourceHash = hashText(JSON.stringify(sourceHashes));
+    const graph = {
+        version: 1,
+        graphVersion: policy.graphVersion,
+        projectId: args.projectId,
+        projectPath: args.projectPath,
+        generatedAt: new Date().toISOString(),
+        sourceHash,
+        sourceHashes,
+        metadata: {
+            nodeCount: nodes.length,
+            edgeCount: edges.length,
+            sourceCount: sources.length,
+            reprocessedSourceCount: diff.changed.length,
+            skippedSourceCount: diff.skipped.length,
+        },
+        nodes,
+        edges,
+    };
+    await writeProjectGraph(args.projectId, policy, graph);
+    await writeProjectGraphSourceHashes(args.projectId, policy, sourceHashes);
+    return {
+        graph,
+        graphPath: projectGraphPath(args.projectId, policy),
+        cachePath: projectGraphCachePath(args.projectId, policy),
+        reprocessedSources: diff.changed,
+        skippedSources: diff.skipped,
+        usedCache: false,
+    };
+}
+//# sourceMappingURL=builder.js.map

package/dist/engine/project-graph/cache.d.ts

@@ -0,0 +1,26 @@
+import type { ProjectGraphFreshness, ProjectGraphPolicy, ProjectGraphSource, ProjectKnowledgeGraph } from '../../types/project-knowledge-graph.js';
+export declare function loadProjectGraphPolicy(): Promise<ProjectGraphPolicy>;
+export declare function hashText(text: string): string;
+export declare function projectGraphDir(projectId: string, policy: ProjectGraphPolicy): string;
+export declare function projectGraphPath(projectId: string, policy: ProjectGraphPolicy): string;
+export declare function projectGraphCachePath(projectId: string, policy: ProjectGraphPolicy): string;
+export declare function readProjectGraph(projectId: string, policy: ProjectGraphPolicy): Promise<ProjectKnowledgeGraph | null>;
+export declare function writeProjectGraph(projectId: string, policy: ProjectGraphPolicy, graph: ProjectKnowledgeGraph): Promise<void>;
+export declare function readProjectGraphSourceHashes(projectId: string, policy: ProjectGraphPolicy): Promise<Record<string, string>>;
+export declare function writeProjectGraphSourceHashes(projectId: string, policy: ProjectGraphPolicy, hashes: Record<string, string>): Promise<void>;
+export declare function diffSourceHashes(sources: ProjectGraphSource[], previous: Record<string, string>): {
+    changed: string[];
+    skipped: string[];
+    next: Record<string, string>;
+};
+export declare function collectProjectGraphSources(args: {
+    projectId: string;
+    projectPath: string;
+    policy: ProjectGraphPolicy;
+}): Promise<ProjectGraphSource[]>;
+export declare function getProjectGraphFreshness(args: {
+    projectId: string;
+    projectPath: string;
+    policy?: ProjectGraphPolicy;
+}): Promise<ProjectGraphFreshness>;
+//# sourceMappingURL=cache.d.ts.map

package/dist/engine/project-graph/cache.js

@@ -0,0 +1,160 @@
+// @crash-shield-ignore-file — graph artifacts are Planu-owned JSON written by this subsystem.
+import { createHash } from 'node:crypto';
+import { readdir, readFile, stat } from 'node:fs/promises';
+import { dirname, join, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { projectDataDir, readJson, writeJson } from '../../storage/base-store.js';
+const POLICY_PATH = join(dirname(fileURLToPath(import.meta.url)), '../../config/project-knowledge-graph.json');
+export async function loadProjectGraphPolicy() {
+    const raw = await readFile(POLICY_PATH, 'utf-8');
+    return JSON.parse(raw);
+}
+export function hashText(text) {
+    return createHash('sha256').update(text, 'utf8').digest('hex');
+}
+export function projectGraphDir(projectId, policy) {
+    return join(projectDataDir(projectId), policy.artifactPaths.directory);
+}
+export function projectGraphPath(projectId, policy) {
+    return join(projectGraphDir(projectId, policy), policy.artifactPaths.graph);
+}
+export function projectGraphCachePath(projectId, policy) {
+    return join(projectGraphDir(projectId, policy), policy.artifactPaths.sourceHashes);
+}
+export async function readProjectGraph(projectId, policy) {
+    return readJson(projectGraphPath(projectId, policy), null);
+}
+export async function writeProjectGraph(projectId, policy, graph) {
+    await writeJson(projectGraphPath(projectId, policy), graph);
+}
+export async function readProjectGraphSourceHashes(projectId, policy) {
+    return readJson(projectGraphCachePath(projectId, policy), {});
+}
+export async function writeProjectGraphSourceHashes(projectId, policy, hashes) {
+    await writeJson(projectGraphCachePath(projectId, policy), hashes);
+}
+export function diffSourceHashes(sources, previous) {
+    const next = Object.fromEntries(sources.map((source) => [source.id, source.hash]));
+    const changed = sources
+        .filter((source) => previous[source.id] !== source.hash)
+        .map((source) => source.id);
+    const skipped = sources
+        .filter((source) => previous[source.id] === source.hash)
+        .map((source) => source.id);
+    return { changed, skipped, next };
+}
+async function fileExists(path) {
+    try {
+        const info = await stat(path);
+        return info.isFile();
+    }
+    catch {
+        return false;
+    }
+}
+async function collectFiles(dir, predicate) {
+    try {
+        const entries = await readdir(dir, { withFileTypes: true });
+        const nested = await Promise.all(entries.map(async (entry) => {
+            const path = join(dir, entry.name);
+            if (entry.isDirectory()) {
+                return collectFiles(path, predicate);
+            }
+            return entry.isFile() && predicate(path) ? [path] : [];
+        }));
+        return nested.flat();
+    }
+    catch {
+        return [];
+    }
+}
+async function sourceFromFile(args) {
+    try {
+        const content = await readFile(args.path, 'utf-8');
+        return { ...args, content, hash: hashText(content) };
+    }
+    catch {
+        return null;
+    }
+}
+export async function collectProjectGraphSources(args) {
+    const projectRoot = resolve(args.projectPath);
+    const dataRoot = projectDataDir(args.projectId);
+    const specFiles = await collectFiles(join(projectRoot, 'planu', 'specs'), (path) => path.endsWith('/spec.md'));
+    const handoffFiles = await collectFiles(join(dataRoot, 'handoffs'), (path) => /\.(json|md)$/.test(path));
+    const validationFiles = handoffFiles.filter((path) => path.includes('validation'));
+    const transitionLog = join(dataRoot, 'transition-log.jsonl');
+    const releaseEvents = join(dataRoot, '..', '..', 'release-events.jsonl');
+    const raw = [
+        ...specFiles.map((path) => ({
+            id: `spec:${relative(projectRoot, path)}`,
+            kind: 'spec',
+            path,
+        })),
+        ...handoffFiles.map((path) => ({
+            id: `handoff:${relative(dataRoot, path)}`,
+            kind: validationFiles.includes(path) ? 'validation' : 'handoff',
+            path,
+        })),
+        ...((await fileExists(transitionLog))
+            ? [{ id: 'transition-log', kind: 'transition-log', path: transitionLog }]
+            : []),
+        ...((await fileExists(releaseEvents))
+            ? [{ id: 'release-events', kind: 'release-events', path: releaseEvents }]
+            : []),
+    ];
+    const sources = await Promise.all(raw.map((source) => sourceFromFile(source)));
+    return sources.filter((source) => source !== null);
+}
+export async function getProjectGraphFreshness(args) {
+    const policy = args.policy ?? (await loadProjectGraphPolicy());
+    const graphPath = projectGraphPath(args.projectId, policy);
+    const graph = await readProjectGraph(args.projectId, policy);
+    if (graph === null) {
+        return { exists: false, stale: true, reason: 'missing', graphPath, changedSources: [] };
+    }
+    if (!Array.isArray(graph.nodes) || !Array.isArray(graph.edges)) {
+        return { exists: true, stale: true, reason: 'corrupt', graphPath, changedSources: [] };
+    }
+    const generatedAtMs = Date.parse(graph.generatedAt);
+    if (Number.isFinite(generatedAtMs)) {
+        const ageMinutes = (Date.now() - generatedAtMs) / 60_000;
+        if (ageMinutes > policy.freshness.staleAfterMinutes) {
+            return {
+                exists: true,
+                stale: true,
+                reason: 'expired',
+                graphPath,
+                generatedAt: graph.generatedAt,
+                changedSources: [],
+            };
+        }
+    }
+    const sources = await collectProjectGraphSources({
+        projectId: args.projectId,
+        projectPath: args.projectPath,
+        policy,
+    });
+    const changedSources = sources
+        .filter((source) => graph.sourceHashes[source.id] !== source.hash)
+        .map((source) => source.id);
+    if (changedSources.length > 0) {
+        return {
+            exists: true,
+            stale: true,
+            reason: 'source_changed',
+            graphPath,
+            generatedAt: graph.generatedAt,
+            changedSources,
+        };
+    }
+    return {
+        exists: true,
+        stale: false,
+        reason: 'fresh',
+        graphPath,
+        generatedAt: graph.generatedAt,
+        changedSources: [],
+    };
+}
+//# sourceMappingURL=cache.js.map

package/dist/engine/project-graph/extractors/git-extractor.d.ts

@@ -0,0 +1,7 @@
+import type { ProjectGraphExtractionResult, ProjectGraphPolicy, ProjectGraphSource } from '../../../types/project-knowledge-graph.js';
+export declare function extractGitGraph(args: {
+    projectPath: string;
+    policy: ProjectGraphPolicy;
+}): Promise<ProjectGraphExtractionResult>;
+export declare function extractReleaseGraph(source: ProjectGraphSource, policy: ProjectGraphPolicy): ProjectGraphExtractionResult;
+//# sourceMappingURL=git-extractor.d.ts.map

package/dist/engine/project-graph/extractors/git-extractor.js

@@ -0,0 +1,89 @@
+import { promisify } from 'node:util';
+import { hashText } from '../cache.js';
+import { redactGraphText } from '../query.js';
+export async function extractGitGraph(args) {
+    try {
+        const childProcess = await import('node:child_process');
+        if (typeof childProcess.execFile !== 'function') {
+            return { nodes: [], edges: [] };
+        }
+        const execFileAsync = promisify(childProcess.execFile);
+        const { stdout } = await execFileAsync('git', ['log', '--max-count=20', '--pretty=format:%H%x09%s'], { cwd: args.projectPath });
+        const nodes = [];
+        const edges = [];
+        for (const line of stdout.split('\n').filter(Boolean)) {
+            const [sha, ...messageParts] = line.split('\t');
+            if (sha === undefined) {
+                continue;
+            }
+            const message = messageParts.join('\t');
+            const commitId = `commit:${sha.slice(0, 12)}`;
+            nodes.push({
+                id: commitId,
+                type: 'commit',
+                label: redactGraphText(message, args.policy),
+                source: 'git-extractor',
+                evidence: [{ path: '.git/log', selector: sha }],
+                updatedAt: new Date().toISOString(),
+            });
+            const specId = /SPEC-\d+/i.exec(message)?.[0]?.toUpperCase();
+            if (specId !== undefined) {
+                edges.push({
+                    id: `edge:${hashText(`${commitId}:references:${specId}`)}`,
+                    from: commitId,
+                    to: `spec:${specId}`,
+                    type: 'references',
+                    source: 'git-extractor',
+                    confidence: 'medium',
+                    classification: 'inferred',
+                    evidence: { path: '.git/log', selector: sha },
+                    updatedAt: new Date().toISOString(),
+                });
+            }
+        }
+        return { nodes, edges };
+    }
+    catch {
+        return { nodes: [], edges: [] };
+    }
+}
+export function extractReleaseGraph(source, policy) {
+    const nodes = [];
+    const edges = [];
+    for (const line of source.content.split('\n').filter(Boolean).slice(-20)) {
+        try {
+            const item = JSON.parse(line);
+            if (typeof item.version !== 'string') {
+                continue;
+            }
+            const releaseId = `release:${item.version}`;
+            nodes.push({
+                id: releaseId,
+                type: 'release',
+                label: redactGraphText(item.version, policy),
+                source: 'git-extractor',
+                evidence: [{ path: source.path, hash: source.hash }],
+                metadata: { commitSha: item.commitSha ?? null, timestamp: item.timestamp ?? null },
+                updatedAt: new Date().toISOString(),
+            });
+            if (typeof item.commitSha === 'string') {
+                edges.push({
+                    id: `edge:${hashText(`${releaseId}:released_in:${item.commitSha}`)}`,
+                    from: `commit:${item.commitSha.slice(0, 12)}`,
+                    to: releaseId,
+                    type: 'released_in',
+                    source: 'git-extractor',
+                    confidence: 'medium',
+                    classification: 'extracted',
+                    evidence: { path: source.path, hash: source.hash },
+                    updatedAt: new Date().toISOString(),
+                });
+            }
+        }
+        catch {
+            continue;
+        }
+    }
+    return { nodes, edges };
+}
+//# sourceMappingURL=git-extractor.js.map

package/dist/engine/project-graph/extractors/handoff-extractor.d.ts

@@ -0,0 +1,3 @@
+import type { ProjectGraphExtractionResult, ProjectGraphPolicy, ProjectGraphSource } from '../../../types/project-knowledge-graph.js';
+export declare function extractHandoffGraph(source: ProjectGraphSource, policy: ProjectGraphPolicy): ProjectGraphExtractionResult;
+//# sourceMappingURL=handoff-extractor.d.ts.map

package/dist/engine/project-graph/extractors/handoff-extractor.js

@@ -0,0 +1,55 @@
+import { hashText } from '../cache.js';
+import { redactGraphText } from '../query.js';
+function specIdFromPath(path) {
+    return path.split('/').find((part) => /^SPEC-\d+$/i.test(part));
+}
+function basename(path) {
+    return path.split('/').slice(-1)[0] ?? path;
+}
+function node(args) {
+    return {
+        id: args.id,
+        type: args.type,
+        label: redactGraphText(args.label, args.policy),
+        source: 'handoff-extractor',
+        evidence: [{ path: args.source.path, hash: args.source.hash }],
+        updatedAt: new Date().toISOString(),
+    };
+}
+function edge(from, to, type, source) {
+    return {
+        id: `edge:${hashText(`${from}:${type}:${to}:${source.id}`)}`,
+        from,
+        to,
+        type,
+        source: 'handoff-extractor',
+        confidence: 'medium',
+        classification: 'extracted',
+        evidence: { path: source.path, hash: source.hash },
+        updatedAt: new Date().toISOString(),
+    };
+}
+export function extractHandoffGraph(source, policy) {
+    const specId = specIdFromPath(source.path);
+    if (specId === undefined) {
+        return { nodes: [], edges: [] };
+    }
+    const specNodeId = `spec:${specId}`;
+    const handoffId = `handoff:${specId}:${hashText(source.path).slice(0, 10)}`;
+    const nodes = [
+        node({ id: handoffId, type: 'handoff', label: basename(source.path), source, policy }),
+    ];
+    const edges = [edge(specNodeId, handoffId, 'references', source)];
+    for (const match of source.content.matchAll(/`((?:src|tests|planu)\/[^`]+)`/g)) {
+        const path = (match[1] ?? '').trim();
+        if (path.length === 0) {
+            continue;
+        }
+        const type = path.startsWith('tests/') ? 'test' : 'file';
+        const id = `${type}:${path}`;
+        nodes.push(node({ id, type, label: path, source, policy }));
+        edges.push(edge(handoffId, id, type === 'test' ? 'tests' : 'references', source));
+    }
+    return { nodes, edges };
+}
+//# sourceMappingURL=handoff-extractor.js.map

package/dist/engine/project-graph/extractors/spec-extractor.d.ts

@@ -0,0 +1,3 @@
+import type { ProjectGraphExtractionResult, ProjectGraphPolicy, ProjectGraphSource } from '../../../types/project-knowledge-graph.js';
+export declare function extractSpecGraph(source: ProjectGraphSource, policy: ProjectGraphPolicy): ProjectGraphExtractionResult;
+//# sourceMappingURL=spec-extractor.d.ts.map