plan-assistant 1.0.0-alpha.1

package/dist/markdown-to-plan.js

@@ -0,0 +1,345 @@
+import { Lexer } from "marked";
+import { createHash } from "node:crypto";
+import { basename } from "node:path";
+import { generatePhaseFlowDiagram } from "./mermaid-gen.js";
+function splitIntoSections(tokens) {
+    const sections = [];
+    let current = null;
+    for (const token of tokens) {
+        if (token.type === "heading") {
+            const h = token;
+            current = { heading: h.text, level: h.depth, tokens: [] };
+            sections.push(current);
+        }
+        else if (current) {
+            current.tokens.push(token);
+        }
+    }
+    return sections;
+}
+function tokensToMarkdown(tokens) {
+    return tokens
+        .map((t) => t.raw)
+        .join("")
+        .trim();
+}
+function findSection(sections, pattern, level) {
+    return sections.find((s) => pattern.test(s.heading) && (level === undefined || s.level === level));
+}
+function collectSectionsUntilLevel(sections, startIdx, level) {
+    const result = [];
+    for (let i = startIdx + 1; i < sections.length; i++) {
+        if (sections[i].level <= level)
+            break;
+        result.push(sections[i]);
+    }
+    return result;
+}
+function parseKeyDiscoveries(tokens) {
+    const results = [];
+    for (const token of tokens) {
+        if (token.type === "list") {
+            const list = token;
+            for (const item of list.items) {
+                const text = item.text.trim();
+                const codeRefMatch = text.match(/\(?\`([^`]+:\d+[^`]*)\`\)?$/);
+                results.push({
+                    text: codeRefMatch ? text.replace(codeRefMatch[0], "").trim() : text,
+                    codeRef: codeRefMatch ? codeRefMatch[1] : undefined,
+                });
+            }
+        }
+    }
+    return results;
+}
+function parseScopeExclusions(tokens) {
+    const results = [];
+    for (const token of tokens) {
+        if (token.type === "list") {
+            const list = token;
+            for (const item of list.items) {
+                const text = item.text.trim();
+                const parts = text.split(/\s*--\s*|\s*[—–]\s*/);
+                if (parts.length >= 2) {
+                    results.push({
+                        title: parts[0].trim(),
+                        reason: parts.slice(1).join(" -- ").trim(),
+                    });
+                }
+                else {
+                    results.push({ title: text, reason: "" });
+                }
+            }
+        }
+    }
+    return results;
+}
+function parseChanges(sections) {
+    const changes = [];
+    for (const section of sections) {
+        if (section.level !== 4)
+            continue;
+        const nameMatch = section.heading.match(/^\d+\.\s*(.+)/);
+        if (!nameMatch)
+            continue;
+        const componentName = nameMatch[1]
+            .replace(/^(?:New\s+component:\s*|Update\s+)?/i, "")
+            .trim();
+        let filePath = "";
+        let description = "";
+        let codeSnippet;
+        let codeLanguage;
+        const lines = [];
+        for (const token of section.tokens) {
+            if (token.type === "paragraph") {
+                const para = token;
+                const fileMatch = para.raw.match(/\*\*File\*\*:\s*`([^`]+)`/);
+                if (fileMatch) {
+                    filePath = fileMatch[1];
+                    const rest = para.raw
+                        .replace(/\*\*File\*\*:\s*`[^`]+`\s*(\(new\))?\s*/i, "")
+                        .trim();
+                    if (rest)
+                        lines.push(rest);
+                }
+                else {
+                    const changesMatch = para.raw.match(/\*\*Changes?\*\*:\s*(.*)/s);
+                    if (changesMatch) {
+                        lines.push(changesMatch[1].trim());
+                    }
+                    else {
+                        lines.push(para.raw.trim());
+                    }
+                }
+            }
+            else if (token.type === "code") {
+                const codeToken = token;
+                codeSnippet = codeToken.text;
+                codeLanguage = codeToken.lang || undefined;
+            }
+            else if (token.type === "list") {
+                lines.push(tokensToMarkdown([token]));
+            }
+        }
+        description = lines.filter(Boolean).join("\n\n");
+        changes.push({
+            componentName,
+            filePath,
+            description,
+            codeSnippet,
+            codeLanguage,
+        });
+    }
+    return changes;
+}
+function parseCriteria(tokens, type) {
+    const criteria = [];
+    for (const token of tokens) {
+        if (token.type === "list") {
+            const list = token;
+            for (const item of list.items) {
+                const text = item.text.trim();
+                const commandMatch = text.match(/:\s*`([^`]+)`\s*$/);
+                const id = `${type}-${criteria.length + 1}`;
+                criteria.push({
+                    id,
+                    text: commandMatch
+                        ? text.replace(commandMatch[0], "").trim() + ":"
+                        : text,
+                    command: commandMatch ? commandMatch[1] : undefined,
+                });
+            }
+        }
+    }
+    return criteria;
+}
+function parsePhases(allSections) {
+    const phases = [];
+    for (let i = 0; i < allSections.length; i++) {
+        const section = allSections[i];
+        const phaseMatch = section.heading.match(/^Phase\s+(\d+):\s*(.+)/i);
+        if (!phaseMatch || section.level !== 2)
+            continue;
+        const number = parseInt(phaseMatch[1], 10);
+        const name = phaseMatch[2].trim();
+        const id = `phase-${number}`;
+        const subSections = collectSectionsUntilLevel(allSections, i, 2);
+        const overviewSection = subSections.find((s) => /^Overview$/i.test(s.heading));
+        const overview = overviewSection
+            ? tokensToMarkdown(overviewSection.tokens)
+            : "";
+        const changesSection = subSections.find((s) => /^Changes\s+Required/i.test(s.heading));
+        const changesIdx = changesSection
+            ? allSections.indexOf(changesSection)
+            : -1;
+        let changes = [];
+        if (changesIdx >= 0) {
+            const changeSubs = collectSectionsUntilLevel(allSections, changesIdx, 3);
+            changes = parseChanges(changeSubs);
+        }
+        const automatedSection = subSections.find((s) => /Automated\s+Verification/i.test(s.heading));
+        const manualSection = subSections.find((s) => /Manual\s+Verification/i.test(s.heading));
+        const automated = automatedSection
+            ? parseCriteria(automatedSection.tokens, "automated")
+            : [];
+        const manual = manualSection
+            ? parseCriteria(manualSection.tokens, "manual")
+            : [];
+        phases.push({
+            id,
+            number,
+            name,
+            overview,
+            changes,
+            successCriteria: { automated, manual },
+        });
+    }
+    return phases;
+}
+function parseTestingStrategy(section, subSections) {
+    const result = {
+        unit: [],
+        integration: [],
+        manual: [],
+    };
+    const unitSection = subSections.find((s) => /Unit\s+Tests?/i.test(s.heading));
+    const intSection = subSections.find((s) => /Integration\s+Tests?/i.test(s.heading) ||
+        /E2E\s+Tests?/i.test(s.heading));
+    const manualSection = subSections.find((s) => /Manual\s+Test/i.test(s.heading));
+    function extractList(sec) {
+        if (!sec)
+            return [];
+        const items = [];
+        for (const token of sec.tokens) {
+            if (token.type === "list") {
+                for (const item of token.items) {
+                    items.push(item.text.trim());
+                }
+            }
+        }
+        return items;
+    }
+    result.unit = extractList(unitSection);
+    result.integration = extractList(intSection);
+    result.manual = extractList(manualSection);
+    return result;
+}
+function parseReferences(tokens) {
+    const refs = [];
+    for (const token of tokens) {
+        if (token.type === "list") {
+            for (const item of token.items) {
+                refs.push(item.text.trim());
+            }
+        }
+        else if (token.type === "paragraph") {
+            const lines = token.text.split("\n");
+            for (const line of lines) {
+                const trimmed = line.replace(/^[-*]\s*/, "").trim();
+                if (trimmed)
+                    refs.push(trimmed);
+            }
+        }
+    }
+    return refs;
+}
+export function sessionIdFromPath(absolutePath) {
+    return createHash("sha256").update(absolutePath).digest("hex").slice(0, 8);
+}
+export function parseMarkdownToPlan(markdown, markdownPath, projectDir, version = 1) {
+    const tokens = Lexer.lex(markdown);
+    const sections = splitIntoSections(tokens);
+    // Title from first H1
+    const titleSection = sections.find((s) => s.level === 1);
+    const title = titleSection?.heading ?? basename(markdownPath, ".md");
+    // Date from filename or today
+    const dateMatch = basename(markdownPath).match(/^(\d{4}-\d{2}-\d{2})/);
+    const date = dateMatch ? dateMatch[1] : new Date().toISOString().slice(0, 10);
+    // Ticket ref from filename
+    const ticketMatch = basename(markdownPath).match(/(?:ENG|TASK)-(\d+)/i);
+    const ticketRef = ticketMatch ? ticketMatch[0].toUpperCase() : undefined;
+    // Overview
+    const overviewSection = findSection(sections, /^Overview$/i, 2);
+    const overview = overviewSection
+        ? tokensToMarkdown(overviewSection.tokens)
+        : "";
+    // Current State
+    const currentStateSection = findSection(sections, /^Current\s+State/i, 2);
+    const currentStateIdx = currentStateSection
+        ? sections.indexOf(currentStateSection)
+        : -1;
+    let currentState = "";
+    let keyDiscoveries = [];
+    if (currentStateSection) {
+        // Get tokens that are in the current state section but NOT in the key discoveries sub-section
+        const subSections = collectSectionsUntilLevel(sections, currentStateIdx, 2);
+        const kdSection = subSections.find((s) => /Key\s+Discover/i.test(s.heading));
+        if (kdSection) {
+            keyDiscoveries = parseKeyDiscoveries(kdSection.tokens);
+            // currentState is everything in the current state section before key discoveries
+            const kdIdx = sections.indexOf(kdSection);
+            const beforeKd = [];
+            for (let i = currentStateIdx + 1; i < kdIdx; i++) {
+                // include sub-section headings+tokens as raw markdown
+                beforeKd.push(...sections[i].tokens);
+            }
+            currentState = tokensToMarkdown([
+                ...currentStateSection.tokens,
+                ...beforeKd,
+            ]);
+        }
+        else {
+            currentState = tokensToMarkdown(currentStateSection.tokens);
+        }
+    }
+    // Scope exclusions
+    const scopeSection = findSection(sections, /What\s+We.*NOT\s+Doing/i, 2);
+    const scopeExclusions = scopeSection
+        ? parseScopeExclusions(scopeSection.tokens)
+        : [];
+    // Implementation approach
+    const approachSection = findSection(sections, /Implementation\s+Approach/i, 2);
+    const implementationApproach = approachSection
+        ? tokensToMarkdown(approachSection.tokens)
+        : "";
+    // Phases
+    const phases = parsePhases(sections);
+    // Diagrams
+    const diagrams = [];
+    if (phases.length > 0) {
+        diagrams.push(generatePhaseFlowDiagram(phases));
+    }
+    // Testing strategy
+    const testingSection = findSection(sections, /Testing\s+Strategy/i, 2);
+    const testingIdx = testingSection ? sections.indexOf(testingSection) : -1;
+    const testingSubs = testingIdx >= 0 ? collectSectionsUntilLevel(sections, testingIdx, 2) : [];
+    const testingStrategy = testingSection
+        ? parseTestingStrategy(testingSection, testingSubs)
+        : { unit: [], integration: [], manual: [] };
+    // References
+    const refsSection = findSection(sections, /^References$/i, 2);
+    const references = refsSection ? parseReferences(refsSection.tokens) : [];
+    const now = new Date().toISOString();
+    return {
+        schemaVersion: 1,
+        meta: {
+            title,
+            date,
+            ticketRef,
+            markdownPath,
+            projectDir,
+            version,
+            createdAt: now,
+            updatedAt: now,
+        },
+        overview,
+        currentState,
+        keyDiscoveries,
+        scopeExclusions,
+        implementationApproach,
+        phases,
+        diagrams,
+        testingStrategy,
+        references,
+    };
+}

package/dist/mermaid-gen.js

@@ -0,0 +1,17 @@
+export function generatePhaseFlowDiagram(phases) {
+    const lines = ["graph LR"];
+    for (const phase of phases) {
+        const nodeId = `P${phase.number}`;
+        const label = `Phase ${phase.number}: ${phase.name}`;
+        lines.push(`  ${nodeId}["${label}"]`);
+    }
+    for (let i = 0; i < phases.length - 1; i++) {
+        lines.push(`  P${phases[i].number} --> P${phases[i + 1].number}`);
+    }
+    return {
+        id: "phase-flow",
+        title: "Implementation Flow",
+        type: "flowchart",
+        mermaidCode: lines.join("\n"),
+    };
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "plan-assistant",
+  "version": "1.0.0-alpha.1",
+  "description": "Review implementation plans in the browser with live reload",
+  "homepage": "https://github.com/sanderdatema/plan_assistant#readme",
+  "bugs": {
+    "url": "https://github.com/sanderdatema/plan_assistant/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sanderdatema/plan_assistant.git"
+  },
+  "license": "MIT",
+  "author": "Sander Datema",
+  "type": "module",
+  "main": "svelte.config.js",
+  "bin": {
+    "plan-assistant": "bin/cli.js"
+  },
+  "files": [
+    "bin/",
+    "dist/",
+    "build/"
+  ],
+  "scripts": {
+    "dev": "vite dev --port 5199",
+    "build": "npm run build:cli && npm run build:server",
+    "build:cli": "tsc -p tsconfig.cli.json",
+    "build:server": "vite build",
+    "preview": "vite preview --port 5199",
+    "check": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "chokidar": "^4.0.3",
+    "marked": "^15.0.7"
+  },
+  "devDependencies": {
+    "@sveltejs/adapter-node": "^5.2.12",
+    "@sveltejs/kit": "^2.16.0",
+    "@sveltejs/vite-plugin-svelte": "^5.0.3",
+    "@tailwindcss/vite": "^4.1.4",
+    "@types/node": "^25.3.0",
+    "highlight.js": "^11.11.0",
+    "mermaid": "^11.6.0",
+    "svelte": "^5.20.0",
+    "svelte-check": "^4.1.0",
+    "tailwindcss": "^4.1.4",
+    "typescript": "^5.7.0",
+    "vite": "^6.2.0"
+  }
+}

package/svelte.config.js

@@ -0,0 +1,11 @@
+import adapter from '@sveltejs/adapter-node';
+import { vitePreprocess } from '@sveltejs/vite-plugin-svelte';
+
+const config = {
+	preprocess: vitePreprocess(),
+	kit: {
+		adapter: adapter()
+	}
+};
+
+export default config;