@abhinav2203/codeflow-core 0.1.0

package/dist/internal/phases.js

@@ -0,0 +1,124 @@
+import { generateNodeCode, isCodeBearingNode } from "./codegen";
+export const getCodeBearingNodes = (graph) => graph.nodes.filter(isCodeBearingNode);
+export const withSpecDrafts = (graph) => ({
+    ...graph,
+    nodes: graph.nodes.map((node) => isCodeBearingNode(node)
+        ? {
+            ...node,
+            status: node.status ?? "spec_only",
+            specDraft: node.specDraft ?? generateNodeCode(node, graph) ?? undefined
+        }
+        : {
+            ...node,
+            status: node.status ?? "spec_only"
+        })
+});
+export const canCompleteSpecPhase = (graph) => getCodeBearingNodes(graph).every((node) => Boolean(node.specDraft ?? generateNodeCode(node, graph)));
+export const canEnterImplementationPhase = (graph) => graph.phase === "spec" && canCompleteSpecPhase(graph);
+export const canEnterIntegrationPhase = (graph) => graph.phase === "implementation" &&
+    getCodeBearingNodes(graph).length > 0 &&
+    getCodeBearingNodes(graph).every((node) => node.status === "verified");
+export const setGraphPhase = (graph, phase) => ({
+    ...graph,
+    phase
+});
+export const updateNodeStatus = (graph, nodeId, updater) => ({
+    ...graph,
+    nodes: graph.nodes.map((node) => (node.id === nodeId ? updater(node) : node))
+});
+export const markNodeImplemented = (graph, nodeId, implementationDraft) => {
+    const nextPhase = graph.phase === "spec" ? "implementation" : graph.phase;
+    return {
+        ...graph,
+        phase: nextPhase,
+        nodes: graph.nodes.map((node) => node.id === nodeId
+            ? {
+                ...node,
+                specDraft: node.specDraft ?? generateNodeCode(node, graph) ?? undefined,
+                implementationDraft,
+                status: "implemented"
+            }
+            : node)
+    };
+};
+export const createNodeVerification = (result, verifiedAt = new Date().toISOString()) => ({
+    verifiedAt,
+    status: result.success ? "success" : "failure",
+    stdout: result.stdout,
+    stderr: result.stderr,
+    exitCode: result.exitCode ?? undefined
+});
+export const createNodeVerificationFromStep = (step, exitCode) => ({
+    verifiedAt: step.completedAt,
+    status: step.status === "passed" || step.status === "warning" ? "success" : "failure",
+    stdout: step.stdout,
+    stderr: step.stderr,
+    exitCode: exitCode ?? undefined
+});
+export const markNodeVerified = (graph, nodeId, result) => {
+    const verifiedGraph = {
+        ...graph,
+        nodes: graph.nodes.map((node) => node.id === nodeId
+            ? {
+                ...node,
+                status: result.success ? "verified" : node.status,
+                lastVerification: createNodeVerification(result)
+            }
+            : node)
+    };
+    return canEnterIntegrationPhase(verifiedGraph)
+        ? setGraphPhase(verifiedGraph, "integration")
+        : verifiedGraph;
+};
+export const getDefaultExecutionTarget = (graph) => {
+    const nodeMap = new Map(graph.nodes.map((node) => [node.id, node]));
+    const workflowTarget = graph.workflows
+        .flatMap((workflow) => workflow.steps)
+        .map((step) => graph.nodes.find((node) => node.name === step))
+        .find((node) => Boolean(node && isCodeBearingNode(node)));
+    if (workflowTarget) {
+        return workflowTarget;
+    }
+    const nodesWithIncomingEdges = new Set(graph.edges.map((edge) => edge.to));
+    const rootCandidate = graph.nodes.find((node) => isCodeBearingNode(node) && !nodesWithIncomingEdges.has(node.id));
+    if (rootCandidate) {
+        return rootCandidate;
+    }
+    return [...nodeMap.values()].find(isCodeBearingNode) ?? null;
+};
+export const markGraphConnected = (graph) => ({
+    ...graph,
+    phase: "integration",
+    nodes: graph.nodes.map((node) => isCodeBearingNode(node) && (node.status === "verified" || node.status === "connected")
+        ? {
+            ...node,
+            status: "connected"
+        }
+        : node)
+});
+export const applyExecutionResultToGraph = (graph, result, options) => {
+    const latestNodeSteps = new Map(result.steps
+        .filter((step) => step.kind === "node")
+        .map((step) => [step.nodeId, step]));
+    const nextGraph = {
+        ...graph,
+        phase: options.integrationRun ? "integration" : graph.phase,
+        nodes: graph.nodes.map((node) => {
+            const step = latestNodeSteps.get(node.id);
+            if (!step) {
+                return node;
+            }
+            const passed = step.status === "passed" || step.status === "warning";
+            const failed = step.status === "failed";
+            const verification = createNodeVerificationFromStep(step, node.id === result.entryNodeId ? result.exitCode : undefined);
+            return {
+                ...node,
+                status: passed
+                    ? (options.integrationRun ? "connected" : "verified")
+                    : node.status,
+                lastVerification: failed || passed ? verification : node.lastVerification
+            };
+        })
+    };
+    return options.integrationRun && result.success ? markGraphConnected(nextGraph) : nextGraph;
+};

package/dist/internal/plan.d.ts

@@ -0,0 +1,2 @@
+import type { BlueprintGraph, RunPlan } from "../schema/index";
+export declare const createRunPlan: (graph: BlueprintGraph) => RunPlan;

package/dist/internal/plan.js

@@ -0,0 +1,67 @@
+import { slugify } from "./utils";
+const taskOwnerPath = (node) => {
+    const extension = node.kind === "ui-screen" ? "tsx" : "ts";
+    return `stubs/${slugify(node.kind)}-${slugify(node.name)}.${extension}`;
+};
+export const createRunPlan = (graph) => {
+    const nodeMap = new Map(graph.nodes.map((node) => [node.id, node]));
+    const remaining = new Set(graph.nodes.map((node) => node.id));
+    const dependencyMap = new Map();
+    const warnings = [];
+    for (const node of graph.nodes) {
+        const dependencyIds = graph.edges
+            .filter((edge) => edge.from === node.id && nodeMap.has(edge.to))
+            .map((edge) => edge.to);
+        dependencyMap.set(node.id, new Set(dependencyIds));
+    }
+    const batches = [];
+    const batchIndexByNodeId = new Map();
+    while (remaining.size > 0) {
+        const ready = [...remaining]
+            .filter((nodeId) => [...(dependencyMap.get(nodeId) ?? new Set())].every((depId) => !remaining.has(depId)))
+            .sort((left, right) => {
+            const leftNode = nodeMap.get(left);
+            const rightNode = nodeMap.get(right);
+            return `${leftNode?.kind}:${leftNode?.name}`.localeCompare(`${rightNode?.kind}:${rightNode?.name}`);
+        });
+        const batchNodeIds = ready.length > 0
+            ? ready
+            : [...remaining]
+                .sort((left, right) => {
+                const leftNode = nodeMap.get(left);
+                const rightNode = nodeMap.get(right);
+                return `${leftNode?.kind}:${leftNode?.name}`.localeCompare(`${rightNode?.kind}:${rightNode?.name}`);
+            })
+                .slice(0, 1);
+        if (ready.length === 0) {
+            const node = nodeMap.get(batchNodeIds[0]);
+            warnings.push(`Cycle detected around ${node?.name ?? batchNodeIds[0]}; forced a serial execution break.`);
+        }
+        const batchIndex = batches.length;
+        for (const nodeId of batchNodeIds) {
+            batchIndexByNodeId.set(nodeId, batchIndex);
+            remaining.delete(nodeId);
+        }
+        batches.push({
+            index: batchIndex,
+            taskIds: batchNodeIds.map((nodeId) => `task:${nodeId}`)
+        });
+    }
+    const tasks = graph.nodes
+        .map((node) => ({
+        id: `task:${node.id}`,
+        nodeId: node.id,
+        title: `${node.kind}: ${node.name}`,
+        kind: node.kind,
+        dependsOn: [...(dependencyMap.get(node.id) ?? new Set())].map((dependencyId) => `task:${dependencyId}`),
+        ownerPath: node.path ?? taskOwnerPath(node),
+        batchIndex: batchIndexByNodeId.get(node.id) ?? 0
+    }))
+        .sort((left, right) => left.batchIndex - right.batchIndex || left.title.localeCompare(right.title));
+    return {
+        generatedAt: new Date().toISOString(),
+        tasks,
+        batches,
+        warnings
+    };
+};

package/dist/internal/prd.d.ts

@@ -0,0 +1,9 @@
+import type { BlueprintEdge, BlueprintNode, WorkflowPath } from "../schema/index";
+type PrdParseResult = {
+    nodes: BlueprintNode[];
+    edges: BlueprintEdge[];
+    workflows: WorkflowPath[];
+    warnings: string[];
+};
+export declare const parsePrd: (prdText: string) => PrdParseResult;
+export {};

package/dist/internal/prd.js

@@ -0,0 +1,220 @@
+import { emptyContract } from "../schema/index";
+import { createNode, createNodeId, dedupeEdges, mergeContracts, mergeSourceRefs } from "./utils";
+const HEADING_PATTERN = /^#{1,6}\s+(.+)$/;
+const BULLET_PATTERN = /^[-*+]\s+(.*)$/;
+const WORKFLOW_PATTERN = /(.+?)\s*->\s*(.+)/;
+const API_PATTERN = /^(GET|POST|PUT|PATCH|DELETE)\s+([^\s]+)/i;
+const SIGNATURE_PATTERN = /^(?<name>[A-Za-z_$][\w$]*)\s*\((?<params>[^)]*)\)\s*(?::\s*(?<returnType>.+))?$/;
+const TAGGED_ITEM_PATTERN = /^(screen|page|ui|api|endpoint|module|service|class|function|method)\s*:\s*(.+)$/i;
+const titleToKind = (title) => {
+    const lower = title.toLowerCase();
+    if (/(screen|page|ui|frontend)/.test(lower)) {
+        return "ui-screen";
+    }
+    if (/(api|endpoint|route|backend)/.test(lower)) {
+        return "api";
+    }
+    if (/(class|service|controller|manager)/.test(lower)) {
+        return "class";
+    }
+    if (/(function|method)/.test(lower)) {
+        return "function";
+    }
+    if (/(module|component|domain)/.test(lower)) {
+        return "module";
+    }
+    return null;
+};
+const normalizeLine = (line) => line
+    .trim()
+    .replace(/^\d+\.\s+/, "")
+    .replace(BULLET_PATTERN, "$1")
+    .trim();
+const parseSections = (prdText) => {
+    const lines = prdText.split(/\r?\n/);
+    const sections = [];
+    let current = { title: "Overview", lines: [] };
+    for (const rawLine of lines) {
+        const headingMatch = rawLine.match(HEADING_PATTERN);
+        if (headingMatch) {
+            if (current.lines.length > 0 || sections.length === 0) {
+                sections.push(current);
+            }
+            current = { title: headingMatch[1].trim(), lines: [] };
+            continue;
+        }
+        const normalized = normalizeLine(rawLine);
+        if (normalized) {
+            current.lines.push(normalized);
+        }
+    }
+    if (current.lines.length > 0 || sections.length === 0) {
+        sections.push(current);
+    }
+    return sections;
+};
+const inferKindFromTaggedItem = (item) => {
+    const match = item.match(TAGGED_ITEM_PATTERN);
+    if (!match) {
+        return null;
+    }
+    return titleToKind(match[1]);
+};
+const extractName = (item, fallbackKind) => {
+    const tagMatch = item.match(TAGGED_ITEM_PATTERN);
+    if (tagMatch) {
+        return tagMatch[2].trim();
+    }
+    const apiMatch = item.match(API_PATTERN);
+    if (apiMatch) {
+        return `${apiMatch[1].toUpperCase()} ${apiMatch[2]}`;
+    }
+    if (fallbackKind === "ui-screen" && !/screen$/i.test(item)) {
+        return item.endsWith("Screen") ? item : `${item} Screen`;
+    }
+    return item;
+};
+const parseContractFromItem = (item) => {
+    const contract = emptyContract();
+    const signatureMatch = item.match(SIGNATURE_PATTERN);
+    contract.summary = item;
+    contract.responsibilities = [item];
+    if (signatureMatch?.groups) {
+        const params = signatureMatch.groups.params
+            .split(",")
+            .map((value) => value.trim())
+            .filter(Boolean);
+        contract.inputs = params.map((param) => {
+            const [name, type] = param.split(":").map((value) => value.trim());
+            return {
+                name,
+                type: type || "unknown"
+            };
+        });
+        contract.outputs = [
+            {
+                name: "result",
+                type: signatureMatch.groups.returnType?.trim() || "unknown"
+            }
+        ];
+        contract.methods = [
+            {
+                name: signatureMatch.groups.name.trim(),
+                signature: item,
+                summary: item,
+                inputs: contract.inputs,
+                outputs: contract.outputs,
+                sideEffects: [],
+                calls: []
+            }
+        ];
+    }
+    else {
+        const apiMatch = item.match(API_PATTERN);
+        if (apiMatch) {
+            contract.inputs = [
+                {
+                    name: "request",
+                    type: "Request"
+                }
+            ];
+            contract.outputs = [
+                {
+                    name: "response",
+                    type: "Response"
+                }
+            ];
+            contract.summary = `Handle ${apiMatch[1].toUpperCase()} ${apiMatch[2]}`;
+            contract.responsibilities = [contract.summary];
+        }
+    }
+    return contract;
+};
+export const parsePrd = (prdText) => {
+    const sections = parseSections(prdText);
+    const warnings = [];
+    const nodesById = new Map();
+    const edges = [];
+    const workflows = [];
+    const upsertNode = (kind, name, section, summary) => {
+        const id = createNodeId(kind, name);
+        const existing = nodesById.get(id);
+        const node = createNode({
+            id,
+            kind,
+            name,
+            summary,
+            contract: mergeContracts(parseContractFromItem(name), {
+                ...emptyContract(),
+                summary,
+                responsibilities: [summary]
+            }),
+            sourceRefs: [
+                {
+                    kind: "prd",
+                    section,
+                    detail: summary
+                }
+            ]
+        });
+        if (existing) {
+            nodesById.set(id, {
+                ...existing,
+                summary: existing.summary || summary,
+                contract: mergeContracts(existing.contract, node.contract),
+                sourceRefs: mergeSourceRefs(existing.sourceRefs, node.sourceRefs)
+            });
+            return id;
+        }
+        nodesById.set(id, node);
+        return id;
+    };
+    for (const section of sections) {
+        const sectionKind = titleToKind(section.title);
+        for (const item of section.lines) {
+            const workflowMatch = item.match(WORKFLOW_PATTERN);
+            if (workflowMatch && item.includes("->")) {
+                const steps = item
+                    .split("->")
+                    .map((value) => value.trim())
+                    .filter(Boolean);
+                if (steps.length >= 2) {
+                    workflows.push({
+                        name: `${section.title}: ${steps.join(" -> ")}`,
+                        steps
+                    });
+                    for (let index = 0; index < steps.length - 1; index += 1) {
+                        const fromName = steps[index];
+                        const toName = steps[index + 1];
+                        const fromId = [...nodesById.values()].find((node) => node.name === fromName)?.id ??
+                            upsertNode("module", fromName, section.title, fromName);
+                        const toId = [...nodesById.values()].find((node) => node.name === toName)?.id ??
+                            upsertNode("module", toName, section.title, toName);
+                        edges.push({
+                            from: fromId,
+                            to: toId,
+                            kind: "calls",
+                            label: section.title,
+                            required: true,
+                            confidence: 0.7
+                        });
+                    }
+                }
+                continue;
+            }
+            const inferredKind = inferKindFromTaggedItem(item) ?? sectionKind;
+            if (!inferredKind) {
+                warnings.push(`Skipped ambiguous PRD item "${item}" in section "${section.title}".`);
+                continue;
+            }
+            const name = extractName(item, inferredKind);
+            upsertNode(inferredKind, name, section.title, item);
+        }
+    }
+    return {
+        nodes: [...nodesById.values()],
+        edges: dedupeEdges(edges),
+        workflows,
+        warnings
+    };
+};

package/dist/internal/utils.d.ts

@@ -0,0 +1,13 @@
+import type { BlueprintEdge, BlueprintNode, BlueprintNodeKind, CodeContract, ContractField, DesignCall, MethodSpec, SourceRef } from "../schema/index";
+export declare const slugify: (value: string) => string;
+export declare const toPosixPath: (value: string) => string;
+export declare const createNodeId: (kind: BlueprintNodeKind, name: string, pathHint?: string) => string;
+export declare const mergeStringLists: (...collections: string[][]) => string[];
+export declare const mergeFields: (...collections: ContractField[][]) => ContractField[];
+export declare const mergeSourceRefs: (...collections: SourceRef[][]) => SourceRef[];
+export declare const mergeDesignCalls: (...collections: DesignCall[][]) => DesignCall[];
+export declare const mergeMethodSpecs: (...collections: MethodSpec[][]) => MethodSpec[];
+export declare const mergeContracts: (...contracts: CodeContract[]) => CodeContract;
+export declare const createNode: (input: Omit<BlueprintNode, "generatedRefs" | "traceRefs" | "traceState" | "status" | "specDraft" | "implementationDraft" | "lastVerification"> & Partial<Pick<BlueprintNode, "generatedRefs" | "traceRefs" | "traceState" | "status" | "specDraft" | "implementationDraft" | "lastVerification">>) => BlueprintNode;
+export declare const createContract: (partial: Partial<CodeContract>) => CodeContract;
+export declare const dedupeEdges: (edges: BlueprintEdge[]) => BlueprintEdge[];

package/dist/internal/utils.js

@@ -0,0 +1,103 @@
+import path from "node:path";
+import { emptyContract } from "../schema/index";
+export const slugify = (value) => value
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/(^-|-$)/g, "")
+    .slice(0, 80) || "node";
+export const toPosixPath = (value) => value.split(path.sep).join("/");
+export const createNodeId = (kind, name, pathHint) => `${kind}:${slugify(pathHint ?? name)}`;
+export const mergeStringLists = (...collections) => [...new Set(collections.flat().filter(Boolean))];
+export const mergeFields = (...collections) => {
+    const map = new Map();
+    for (const field of collections.flat()) {
+        const key = `${field.name}:${field.type}:${field.description ?? ""}`;
+        if (!map.has(key)) {
+            map.set(key, field);
+        }
+    }
+    return [...map.values()];
+};
+export const mergeSourceRefs = (...collections) => {
+    const map = new Map();
+    for (const ref of collections.flat()) {
+        const key = `${ref.kind}:${ref.path ?? ""}:${ref.symbol ?? ""}:${ref.section ?? ""}:${ref.detail ?? ""}`;
+        if (!map.has(key)) {
+            map.set(key, ref);
+        }
+    }
+    return [...map.values()];
+};
+export const mergeDesignCalls = (...collections) => {
+    const map = new Map();
+    for (const call of collections.flat()) {
+        const key = `${call.target}:${call.kind ?? ""}:${call.description ?? ""}`;
+        if (!map.has(key)) {
+            map.set(key, call);
+        }
+    }
+    return [...map.values()];
+};
+export const mergeMethodSpecs = (...collections) => {
+    const map = new Map();
+    for (const method of collections.flat()) {
+        const key = `${method.name}:${method.signature ?? ""}`;
+        const existing = map.get(key);
+        if (!existing) {
+            map.set(key, method);
+            continue;
+        }
+        map.set(key, {
+            ...existing,
+            summary: existing.summary || method.summary,
+            inputs: mergeFields(existing.inputs, method.inputs),
+            outputs: mergeFields(existing.outputs, method.outputs),
+            sideEffects: mergeStringLists(existing.sideEffects, method.sideEffects),
+            calls: mergeDesignCalls(existing.calls, method.calls)
+        });
+    }
+    return [...map.values()];
+};
+export const mergeContracts = (...contracts) => ({
+    summary: contracts.map((item) => item.summary).find(Boolean) ?? "",
+    responsibilities: mergeStringLists(...contracts.map((item) => item.responsibilities)),
+    inputs: mergeFields(...contracts.map((item) => item.inputs)),
+    outputs: mergeFields(...contracts.map((item) => item.outputs)),
+    attributes: mergeFields(...contracts.map((item) => item.attributes)),
+    methods: mergeMethodSpecs(...contracts.map((item) => item.methods)),
+    sideEffects: mergeStringLists(...contracts.map((item) => item.sideEffects)),
+    errors: mergeStringLists(...contracts.map((item) => item.errors)),
+    dependencies: mergeStringLists(...contracts.map((item) => item.dependencies)),
+    calls: mergeDesignCalls(...contracts.map((item) => item.calls)),
+    uiAccess: mergeStringLists(...contracts.map((item) => item.uiAccess)),
+    backendAccess: mergeStringLists(...contracts.map((item) => item.backendAccess)),
+    notes: mergeStringLists(...contracts.map((item) => item.notes))
+});
+export const createNode = (input) => ({
+    ...input,
+    generatedRefs: input.generatedRefs ?? [],
+    traceRefs: input.traceRefs ?? [],
+    traceState: input.traceState,
+    status: input.status ?? "spec_only",
+    specDraft: input.specDraft,
+    implementationDraft: input.implementationDraft,
+    lastVerification: input.lastVerification
+});
+export const createContract = (partial) => mergeContracts(emptyContract(), partial);
+export const dedupeEdges = (edges) => {
+    const map = new Map();
+    for (const edge of edges) {
+        const key = `${edge.kind}:${edge.from}:${edge.to}:${edge.label ?? ""}`;
+        const existing = map.get(key);
+        if (!existing) {
+            map.set(key, edge);
+            continue;
+        }
+        map.set(key, {
+            ...existing,
+            required: existing.required || edge.required,
+            confidence: Math.max(existing.confidence, edge.confidence)
+        });
+    }
+    return [...map.values()];
+};