@gordon.gan/specflow 1.0.0

package/dist/core/parsers/markdown-parser.js

@@ -0,0 +1,193 @@
+/**
+ * Markdown delta-spec parser.
+ *
+ * Parses a delta-spec markdown file into structured data with
+ * ADDED, MODIFIED, REMOVED, and RENAMED sections.
+ */
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+const SECTION_HEADER = /^##\s+(ADDED|MODIFIED|REMOVED|RENAMED)\s+Requirements\s*$/i;
+const REQUIREMENT_HEADER = /^###\s+Requirement:\s*(.+)\s*$/;
+const SCENARIO_HEADER = /^####\s+Scenario:\s*(.+)\s*$/;
+const WHEN_LINE = /^-\s+\*\*WHEN\*\*\s+(.+)$/;
+const THEN_LINE = /^-\s+\*\*THEN\*\*\s+(.+)$/;
+const REASON_LINE = /^\*\*Reason\*\*:\s*(.+)$/;
+const MIGRATION_LINE = /^\*\*Migration\*\*:\s*(.+)$/;
+const FROM_LINE = /^FROM:\s*(.+)$/;
+const TO_LINE = /^TO:\s*(.+)$/;
+function splitSections(content) {
+    const lines = content.replace(/\r\n?/g, '\n').split('\n');
+    const sections = [];
+    let current = null;
+    for (const line of lines) {
+        const match = SECTION_HEADER.exec(line);
+        if (match) {
+            if (current) {
+                sections.push({ kind: current.kind, lines: current.lines });
+            }
+            current = {
+                kind: match[1].toUpperCase(),
+                lines: [],
+            };
+            continue;
+        }
+        if (current) {
+            current.lines.push(line);
+        }
+    }
+    if (current) {
+        sections.push({ kind: current.kind, lines: current.lines });
+    }
+    return sections;
+}
+function parseScenarios(lines) {
+    const scenarios = [];
+    let current = null;
+    for (const line of lines) {
+        const scenarioMatch = SCENARIO_HEADER.exec(line);
+        if (scenarioMatch) {
+            if (current) {
+                scenarios.push({ ...current });
+            }
+            current = { name: scenarioMatch[1].trim(), when: [], then: [] };
+            continue;
+        }
+        if (!current)
+            continue;
+        const whenMatch = WHEN_LINE.exec(line);
+        if (whenMatch) {
+            current.when.push(whenMatch[1].trim());
+            continue;
+        }
+        const thenMatch = THEN_LINE.exec(line);
+        if (thenMatch) {
+            current.then.push(thenMatch[1].trim());
+        }
+    }
+    if (current) {
+        scenarios.push({ ...current });
+    }
+    return scenarios;
+}
+function parseRequirementBlocks(lines) {
+    const blocks = [];
+    let currentName = null;
+    let blockLines = [];
+    const flush = () => {
+        if (currentName !== null) {
+            const descriptionLines = [];
+            const scenarioLines = [];
+            let inScenario = false;
+            for (const l of blockLines) {
+                if (SCENARIO_HEADER.test(l)) {
+                    inScenario = true;
+                }
+                if (inScenario) {
+                    scenarioLines.push(l);
+                }
+                else {
+                    descriptionLines.push(l);
+                }
+            }
+            blocks.push({
+                name: currentName,
+                description: descriptionLines
+                    .join('\n')
+                    .trim(),
+                scenarios: parseScenarios(scenarioLines),
+            });
+        }
+    };
+    for (const line of lines) {
+        const reqMatch = REQUIREMENT_HEADER.exec(line);
+        if (reqMatch) {
+            flush();
+            currentName = reqMatch[1].trim();
+            blockLines = [];
+            continue;
+        }
+        blockLines.push(line);
+    }
+    flush();
+    return blocks;
+}
+function parseRemovedRequirements(lines) {
+    const removed = [];
+    let currentName = null;
+    let reason = '';
+    let migration = '';
+    const flush = () => {
+        if (currentName !== null) {
+            removed.push({ name: currentName, reason, migration });
+        }
+    };
+    for (const line of lines) {
+        const reqMatch = REQUIREMENT_HEADER.exec(line);
+        if (reqMatch) {
+            flush();
+            currentName = reqMatch[1].trim();
+            reason = '';
+            migration = '';
+            continue;
+        }
+        const reasonMatch = REASON_LINE.exec(line);
+        if (reasonMatch) {
+            reason = reasonMatch[1].trim();
+            continue;
+        }
+        const migrationMatch = MIGRATION_LINE.exec(line);
+        if (migrationMatch) {
+            migration = migrationMatch[1].trim();
+        }
+    }
+    flush();
+    return removed;
+}
+function parseRenamedRequirements(lines) {
+    const renamed = [];
+    let from = null;
+    for (const line of lines) {
+        const fromMatch = FROM_LINE.exec(line);
+        if (fromMatch) {
+            from = fromMatch[1].trim();
+            continue;
+        }
+        const toMatch = TO_LINE.exec(line);
+        if (toMatch && from !== null) {
+            renamed.push({ from, to: toMatch[1].trim() });
+            from = null;
+        }
+    }
+    return renamed;
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Parse a delta-spec markdown file into structured data.
+ */
+export function parseDeltaSpec(content) {
+    const sections = splitSections(content);
+    let added = [];
+    let modified = [];
+    let removed = [];
+    let renamed = [];
+    for (const section of sections) {
+        switch (section.kind) {
+            case 'ADDED':
+                added = parseRequirementBlocks(section.lines);
+                break;
+            case 'MODIFIED':
+                modified = parseRequirementBlocks(section.lines);
+                break;
+            case 'REMOVED':
+                removed = parseRemovedRequirements(section.lines);
+                break;
+            case 'RENAMED':
+                renamed = parseRenamedRequirements(section.lines);
+                break;
+        }
+    }
+    return { added, modified, removed, renamed };
+}

package/dist/core/parsers/requirement-blocks.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Requirement-blocks parser.
+ *
+ * Utilities for extracting individual requirement names and blocks
+ * from markdown content.
+ */
+/**
+ * Extract the requirement name from a `### Requirement: <name>` header line.
+ * Returns the trimmed name, or an empty string if the line is not a valid header.
+ */
+export declare function extractRequirementName(header: string): string;
+/**
+ * Extract the full block for a named requirement from markdown content.
+ *
+ * The block starts at `### Requirement: <name>` and extends through all
+ * content (including scenarios) until the next `### Requirement:` header,
+ * a `## ` section header, or end-of-content.
+ *
+ * Returns the block as a trimmed string, or an empty string if not found.
+ */
+export declare function extractRequirementBlock(content: string, name: string): string;

package/dist/core/parsers/requirement-blocks.js

@@ -0,0 +1,57 @@
+/**
+ * Requirement-blocks parser.
+ *
+ * Utilities for extracting individual requirement names and blocks
+ * from markdown content.
+ */
+const REQUIREMENT_HEADER = /^###\s+Requirement:\s*(.+)\s*$/;
+const SECTION_BOUNDARY = /^##\s+/;
+const NEXT_REQUIREMENT = /^###\s+Requirement:\s*/;
+/**
+ * Extract the requirement name from a `### Requirement: <name>` header line.
+ * Returns the trimmed name, or an empty string if the line is not a valid header.
+ */
+export function extractRequirementName(header) {
+    const match = REQUIREMENT_HEADER.exec(header.trim());
+    return match ? match[1].trim() : '';
+}
+/**
+ * Extract the full block for a named requirement from markdown content.
+ *
+ * The block starts at `### Requirement: <name>` and extends through all
+ * content (including scenarios) until the next `### Requirement:` header,
+ * a `## ` section header, or end-of-content.
+ *
+ * Returns the block as a trimmed string, or an empty string if not found.
+ */
+export function extractRequirementBlock(content, name) {
+    const normalized = content.replace(/\r\n?/g, '\n');
+    const lines = normalized.split('\n');
+    // Find the header line for this requirement
+    const targetPattern = new RegExp(`^###\\s+Requirement:\\s*${escapeRegExp(name)}\\s*$`);
+    let startIndex = -1;
+    for (let i = 0; i < lines.length; i++) {
+        if (targetPattern.test(lines[i])) {
+            startIndex = i;
+            break;
+        }
+    }
+    if (startIndex === -1) {
+        return '';
+    }
+    // Collect lines until a boundary
+    let endIndex = lines.length;
+    for (let i = startIndex + 1; i < lines.length; i++) {
+        if (NEXT_REQUIREMENT.test(lines[i]) || SECTION_BOUNDARY.test(lines[i])) {
+            endIndex = i;
+            break;
+        }
+    }
+    return lines.slice(startIndex, endIndex).join('\n').trimEnd();
+}
+/**
+ * Escape special regex characters in a string for use in a RegExp constructor.
+ */
+function escapeRegExp(str) {
+    return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

package/dist/core/parsers/spec-structure.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Spec structure parser.
+ *
+ * Parses a main spec markdown file into a structured ParsedSpec
+ * containing typed requirements and their scenarios.
+ */
+import type { Scenario } from './markdown-parser.js';
+export interface Requirement {
+    readonly name: string;
+    readonly description: string;
+    readonly scenarios: readonly Scenario[];
+}
+export interface ParsedSpec {
+    readonly requirements: readonly Requirement[];
+}
+/**
+ * Parse a main spec markdown file into a ParsedSpec.
+ *
+ * Extracts all requirements from the `## Requirements` section,
+ * including their descriptions and scenarios.
+ */
+export declare function parseMainSpec(content: string): ParsedSpec;

package/dist/core/parsers/spec-structure.js

@@ -0,0 +1,105 @@
+/**
+ * Spec structure parser.
+ *
+ * Parses a main spec markdown file into a structured ParsedSpec
+ * containing typed requirements and their scenarios.
+ */
+const REQUIREMENT_HEADER = /^###\s+Requirement:\s*(.+)\s*$/;
+const SCENARIO_HEADER = /^####\s+Scenario:\s*(.+)\s*$/;
+const SECTION_BOUNDARY = /^##\s+/;
+const WHEN_LINE = /^-\s+\*\*WHEN\*\*\s+(.+)$/;
+const THEN_LINE = /^-\s+\*\*THEN\*\*\s+(.+)$/;
+/**
+ * Parse a main spec markdown file into a ParsedSpec.
+ *
+ * Extracts all requirements from the `## Requirements` section,
+ * including their descriptions and scenarios.
+ */
+export function parseMainSpec(content) {
+    const normalized = content.replace(/\r\n?/g, '\n');
+    const lines = normalized.split('\n');
+    // Find the ## Requirements section
+    const reqSectionIndex = lines.findIndex((line) => /^##\s+Requirements\s*$/i.test(line));
+    if (reqSectionIndex === -1) {
+        return { requirements: [] };
+    }
+    // Find the end of the Requirements section
+    let endIndex = lines.length;
+    for (let i = reqSectionIndex + 1; i < lines.length; i++) {
+        if (SECTION_BOUNDARY.test(lines[i]) && !/^##\s+Requirements/i.test(lines[i])) {
+            endIndex = i;
+            break;
+        }
+    }
+    const sectionLines = lines.slice(reqSectionIndex + 1, endIndex);
+    return { requirements: parseRequirements(sectionLines) };
+}
+function parseRequirements(lines) {
+    const requirements = [];
+    let currentName = null;
+    let descriptionLines = [];
+    let scenarioLines = [];
+    let inScenario = false;
+    const flush = () => {
+        if (currentName !== null) {
+            requirements.push({
+                name: currentName,
+                description: descriptionLines.join('\n').trim(),
+                scenarios: parseScenarios(scenarioLines),
+            });
+        }
+    };
+    for (const line of lines) {
+        const reqMatch = REQUIREMENT_HEADER.exec(line);
+        if (reqMatch) {
+            flush();
+            currentName = reqMatch[1].trim();
+            descriptionLines = [];
+            scenarioLines = [];
+            inScenario = false;
+            continue;
+        }
+        if (currentName === null)
+            continue;
+        if (SCENARIO_HEADER.test(line)) {
+            inScenario = true;
+        }
+        if (inScenario) {
+            scenarioLines.push(line);
+        }
+        else {
+            descriptionLines.push(line);
+        }
+    }
+    flush();
+    return requirements;
+}
+function parseScenarios(lines) {
+    const scenarios = [];
+    let current = null;
+    for (const line of lines) {
+        const scenarioMatch = SCENARIO_HEADER.exec(line);
+        if (scenarioMatch) {
+            if (current) {
+                scenarios.push({ ...current });
+            }
+            current = { name: scenarioMatch[1].trim(), when: [], then: [] };
+            continue;
+        }
+        if (!current)
+            continue;
+        const whenMatch = WHEN_LINE.exec(line);
+        if (whenMatch) {
+            current.when.push(whenMatch[1].trim());
+            continue;
+        }
+        const thenMatch = THEN_LINE.exec(line);
+        if (thenMatch) {
+            current.then.push(thenMatch[1].trim());
+        }
+    }
+    if (current) {
+        scenarios.push({ ...current });
+    }
+    return scenarios;
+}

package/dist/core/specs-apply.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Specs apply.
+ *
+ * Applies a delta spec to a main spec, producing an updated main spec.
+ * Handles ADDED, MODIFIED, REMOVED, and RENAMED operations on
+ * requirement blocks identified by `### Requirement: <name>` headers.
+ */
+/**
+ * Apply a delta spec to a main spec.
+ *
+ * Operations are applied in this order:
+ * 1. RENAMED - rename requirement headers
+ * 2. REMOVED - delete requirement blocks
+ * 3. MODIFIED - replace requirement blocks
+ * 4. ADDED - append new requirement blocks
+ *
+ * @param mainSpecContent - The raw markdown of the main spec
+ * @param deltaContent - The raw markdown of the delta spec
+ * @returns The updated main spec markdown
+ * @throws When a MODIFIED target does not exist in the main spec
+ */
+export declare function applyDeltaSpec(mainSpecContent: string, deltaContent: string): string;

package/dist/core/specs-apply.js

@@ -0,0 +1,165 @@
+/**
+ * Specs apply.
+ *
+ * Applies a delta spec to a main spec, producing an updated main spec.
+ * Handles ADDED, MODIFIED, REMOVED, and RENAMED operations on
+ * requirement blocks identified by `### Requirement: <name>` headers.
+ */
+import { parseDeltaSpec } from './parsers/markdown-parser.js';
+const REQUIREMENT_HEADER = /^###\s+Requirement:\s*(.+)\s*$/;
+/**
+ * Find all requirement block spans in lines array.
+ * Each span covers from the `### Requirement:` line to just before
+ * the next requirement header or end-of-content.
+ */
+function findBlockSpans(lines) {
+    const spans = [];
+    let currentName = null;
+    let currentStart = -1;
+    for (let i = 0; i < lines.length; i++) {
+        const match = REQUIREMENT_HEADER.exec(lines[i]);
+        if (match) {
+            if (currentName !== null) {
+                spans.push({ name: currentName, startIndex: currentStart, endIndex: i });
+            }
+            currentName = match[1].trim();
+            currentStart = i;
+        }
+    }
+    if (currentName !== null) {
+        spans.push({ name: currentName, startIndex: currentStart, endIndex: lines.length });
+    }
+    return spans;
+}
+/**
+ * Rebuild a requirement block's markdown from a parsed RequirementBlock.
+ */
+function blockToMarkdown(block) {
+    const parts = [`### Requirement: ${block.name}`];
+    if (block.description.trim()) {
+        parts.push(block.description);
+    }
+    for (const scenario of block.scenarios) {
+        parts.push('');
+        parts.push(`#### Scenario: ${scenario.name}`);
+        for (const w of scenario.when) {
+            parts.push(`- **WHEN** ${w}`);
+        }
+        for (const t of scenario.then) {
+            parts.push(`- **THEN** ${t}`);
+        }
+    }
+    return parts.join('\n');
+}
+/**
+ * Remove a requirement block from the lines array by name.
+ * Returns a new array without the block, trimming excess blank lines.
+ */
+function removeBlock(lines, name) {
+    const spans = findBlockSpans(lines);
+    const target = spans.find((s) => s.name === name);
+    if (!target) {
+        return lines;
+    }
+    const before = lines.slice(0, target.startIndex);
+    const after = lines.slice(target.endIndex);
+    // Trim trailing blank lines from before and leading blank lines from after
+    const trimmedBefore = trimTrailingBlanks(before);
+    const trimmedAfter = trimLeadingBlanks(after);
+    if (trimmedBefore.length === 0) {
+        return trimmedAfter;
+    }
+    if (trimmedAfter.length === 0) {
+        return trimmedBefore;
+    }
+    return [...trimmedBefore, '', ...trimmedAfter];
+}
+/**
+ * Replace a requirement block's content in the lines array.
+ * Returns a new array with the block replaced.
+ */
+function replaceBlock(lines, name, newBlock) {
+    const spans = findBlockSpans(lines);
+    const target = spans.find((s) => s.name === name);
+    if (!target) {
+        throw new Error(`Requirement "${name}" not found in main spec`);
+    }
+    const before = lines.slice(0, target.startIndex);
+    const after = lines.slice(target.endIndex);
+    const replacement = blockToMarkdown(newBlock).split('\n');
+    return [...before, ...replacement, ...after];
+}
+/**
+ * Rename a requirement header in the lines array.
+ * Returns a new array with the header renamed.
+ */
+function renameBlock(lines, fromName, toName) {
+    return lines.map((line) => {
+        const match = REQUIREMENT_HEADER.exec(line);
+        if (match && match[1].trim() === fromName) {
+            return `### Requirement: ${toName}`;
+        }
+        return line;
+    });
+}
+/**
+ * Append a requirement block to the end of the lines array.
+ */
+function appendBlock(lines, block) {
+    const trimmed = trimTrailingBlanks([...lines]);
+    const markdown = blockToMarkdown(block);
+    return [...trimmed, '', ...markdown.split('\n')];
+}
+function trimTrailingBlanks(lines) {
+    const result = [...lines];
+    while (result.length > 0 && result[result.length - 1].trim() === '') {
+        result.pop();
+    }
+    return result;
+}
+function trimLeadingBlanks(lines) {
+    const result = [...lines];
+    while (result.length > 0 && result[0].trim() === '') {
+        result.shift();
+    }
+    return result;
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Apply a delta spec to a main spec.
+ *
+ * Operations are applied in this order:
+ * 1. RENAMED - rename requirement headers
+ * 2. REMOVED - delete requirement blocks
+ * 3. MODIFIED - replace requirement blocks
+ * 4. ADDED - append new requirement blocks
+ *
+ * @param mainSpecContent - The raw markdown of the main spec
+ * @param deltaContent - The raw markdown of the delta spec
+ * @returns The updated main spec markdown
+ * @throws When a MODIFIED target does not exist in the main spec
+ */
+export function applyDeltaSpec(mainSpecContent, deltaContent) {
+    const delta = parseDeltaSpec(deltaContent);
+    const normalized = mainSpecContent.replace(/\r\n?/g, '\n');
+    let lines = normalized.split('\n');
+    // 1. Apply RENAMED
+    for (const rename of delta.renamed) {
+        lines = renameBlock(lines, rename.from, rename.to);
+    }
+    // 2. Apply REMOVED
+    for (const removed of delta.removed) {
+        lines = removeBlock(lines, removed.name);
+    }
+    // 3. Apply MODIFIED
+    for (const modified of delta.modified) {
+        lines = replaceBlock(lines, modified.name, modified);
+    }
+    // 4. Apply ADDED
+    for (const added of delta.added) {
+        lines = appendBlock(lines, added);
+    }
+    return trimLeadingBlanks(trimTrailingBlanks([...lines])).join('\n') + '\n';
+}

package/dist/core/templates/index.d.ts

@@ -0,0 +1,31 @@
+import type { TemplateId } from './types.js';
+export type { TemplateId } from './types.js';
+/**
+ * Error thrown when a template cannot be found or loaded.
+ */
+export declare class TemplateNotFoundError extends Error {
+    readonly templateId: string;
+    readonly templatePath: string;
+    constructor(templateId: string, templatePath: string);
+}
+/**
+ * Returns the absolute path to a template file.
+ *
+ * @param id - The template identifier
+ * @returns Absolute path to the template markdown file
+ */
+export declare function getTemplatePath(id: TemplateId): string;
+/**
+ * Loads a template file and returns its contents as a string.
+ *
+ * @param id - The template identifier
+ * @returns The template content
+ * @throws TemplateNotFoundError if the template file does not exist
+ */
+export declare function loadTemplate(id: TemplateId): Promise<string>;
+/**
+ * Returns the list of all available template IDs.
+ *
+ * @returns Array of valid template identifiers
+ */
+export declare function listTemplates(): TemplateId[];

package/dist/core/templates/index.js

@@ -0,0 +1,80 @@
+import * as fs from 'node:fs/promises';
+import * as fsSync from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+/**
+ * All valid template IDs.
+ */
+const TEMPLATE_IDS = [
+    'proposal',
+    'spec',
+    'design',
+    'tasks',
+];
+/**
+ * Error thrown when a template cannot be found or loaded.
+ */
+export class TemplateNotFoundError extends Error {
+    templateId;
+    templatePath;
+    constructor(templateId, templatePath) {
+        super(`Template "${templateId}" not found at ${templatePath}`);
+        this.templateId = templateId;
+        this.templatePath = templatePath;
+        this.name = 'TemplateNotFoundError';
+    }
+}
+/**
+ * Resolves the package root by walking up from the current module until
+ * a directory containing package.json is found.
+ */
+function findPackageRoot() {
+    const currentFile = fileURLToPath(import.meta.url);
+    let dir = path.dirname(currentFile);
+    const root = path.parse(dir).root;
+    while (dir !== root) {
+        if (fsSync.existsSync(path.join(dir, 'package.json'))) {
+            return dir;
+        }
+        dir = path.dirname(dir);
+    }
+    throw new Error('Could not find package root (no package.json found in parent directories)');
+}
+/**
+ * Returns the absolute path to a template file.
+ *
+ * @param id - The template identifier
+ * @returns Absolute path to the template markdown file
+ */
+export function getTemplatePath(id) {
+    const packageRoot = findPackageRoot();
+    return path.join(packageRoot, 'templates', `${id}.md`);
+}
+/**
+ * Loads a template file and returns its contents as a string.
+ *
+ * @param id - The template identifier
+ * @returns The template content
+ * @throws TemplateNotFoundError if the template file does not exist
+ */
+export async function loadTemplate(id) {
+    const templatePath = getTemplatePath(id);
+    try {
+        return await fs.readFile(templatePath, 'utf-8');
+    }
+    catch (err) {
+        if (err instanceof Error && 'code' in err && err.code === 'ENOENT') {
+            throw new TemplateNotFoundError(id, templatePath);
+        }
+        const readError = err instanceof Error ? err : new Error(String(err));
+        throw new Error(`Failed to load template "${id}": ${readError.message}`);
+    }
+}
+/**
+ * Returns the list of all available template IDs.
+ *
+ * @returns Array of valid template identifiers
+ */
+export function listTemplates() {
+    return [...TEMPLATE_IDS];
+}