@gordon.gan/specflow 1.0.0

package/dist/core/artifact-graph/resolver.d.ts

@@ -0,0 +1,54 @@
+import type { SchemaYaml } from './types.js';
+/**
+ * Error thrown when loading a schema file fails.
+ */
+export declare class SchemaLoadError extends Error {
+    readonly schemaPath: string;
+    readonly cause?: Error | undefined;
+    constructor(message: string, schemaPath: string, cause?: Error | undefined);
+}
+/**
+ * Gets the package's built-in schemas directory path.
+ * Resolves from the compiled module location back to the package root.
+ */
+export declare function getPackageSchemasDir(): string;
+/**
+ * Gets the project-local schemas directory path.
+ *
+ * @param projectRoot - The project root directory
+ * @returns The path to the project's schemas directory
+ */
+export declare function getProjectSchemasDir(projectRoot: string): string;
+/**
+ * Resolves a schema name to its directory path.
+ *
+ * Resolution order:
+ * 1. Project-local: <projectRoot>/specflow/schemas/<name>/schema.yaml
+ * 2. Package built-in: <package>/schemas/<name>/schema.yaml
+ *
+ * @param name - Schema name (e.g., "specflow")
+ * @param projectRoot - Optional project root directory for project-local resolution
+ * @returns The path to the schema directory, or null if not found
+ */
+export declare function getSchemaDir(name: string, projectRoot?: string): string | null;
+/**
+ * Resolves a schema name to a validated SchemaYaml object.
+ *
+ * Resolution order:
+ * 1. Project-local: <projectRoot>/specflow/schemas/<name>/schema.yaml
+ * 2. Package built-in: <package>/schemas/<name>/schema.yaml
+ *
+ * @param name - Schema name (e.g., "specflow")
+ * @param projectRoot - Optional project root directory for project-local resolution
+ * @returns The resolved and validated schema object
+ * @throws Error if schema not found in any location
+ * @throws SchemaLoadError if schema file cannot be read or parsed
+ */
+export declare function resolveSchema(name: string, projectRoot?: string): SchemaYaml;
+/**
+ * Lists all available schema names.
+ *
+ * @param projectRoot - Optional project root directory for project-local resolution
+ * @returns Sorted array of schema names
+ */
+export declare function listSchemas(projectRoot?: string): string[];

package/dist/core/artifact-graph/resolver.js

@@ -0,0 +1,139 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseSchema, SchemaValidationError } from './schema.js';
+/**
+ * Error thrown when loading a schema file fails.
+ */
+export class SchemaLoadError extends Error {
+    schemaPath;
+    cause;
+    constructor(message, schemaPath, cause) {
+        super(message);
+        this.schemaPath = schemaPath;
+        this.cause = cause;
+        this.name = 'SchemaLoadError';
+    }
+}
+/**
+ * Gets the package's built-in schemas directory path.
+ * Resolves from the compiled module location back to the package root.
+ */
+export function getPackageSchemasDir() {
+    const currentFile = fileURLToPath(import.meta.url);
+    // Navigate from src/core/artifact-graph/ (or dist/core/artifact-graph/) to package root
+    return path.join(path.dirname(currentFile), '..', '..', '..', 'schemas');
+}
+/**
+ * Gets the project-local schemas directory path.
+ *
+ * @param projectRoot - The project root directory
+ * @returns The path to the project's schemas directory
+ */
+export function getProjectSchemasDir(projectRoot) {
+    return path.join(projectRoot, 'specflow', 'schemas');
+}
+/**
+ * Resolves a schema name to its directory path.
+ *
+ * Resolution order:
+ * 1. Project-local: <projectRoot>/specflow/schemas/<name>/schema.yaml
+ * 2. Package built-in: <package>/schemas/<name>/schema.yaml
+ *
+ * @param name - Schema name (e.g., "specflow")
+ * @param projectRoot - Optional project root directory for project-local resolution
+ * @returns The path to the schema directory, or null if not found
+ */
+export function getSchemaDir(name, projectRoot) {
+    // 1. Check project-local directory
+    if (projectRoot) {
+        const projectDir = path.join(getProjectSchemasDir(projectRoot), name);
+        const projectSchemaPath = path.join(projectDir, 'schema.yaml');
+        if (fs.existsSync(projectSchemaPath)) {
+            return projectDir;
+        }
+    }
+    // 2. Check package built-in directory
+    const packageDir = path.join(getPackageSchemasDir(), name);
+    const packageSchemaPath = path.join(packageDir, 'schema.yaml');
+    if (fs.existsSync(packageSchemaPath)) {
+        return packageDir;
+    }
+    return null;
+}
+/**
+ * Resolves a schema name to a validated SchemaYaml object.
+ *
+ * Resolution order:
+ * 1. Project-local: <projectRoot>/specflow/schemas/<name>/schema.yaml
+ * 2. Package built-in: <package>/schemas/<name>/schema.yaml
+ *
+ * @param name - Schema name (e.g., "specflow")
+ * @param projectRoot - Optional project root directory for project-local resolution
+ * @returns The resolved and validated schema object
+ * @throws Error if schema not found in any location
+ * @throws SchemaLoadError if schema file cannot be read or parsed
+ */
+export function resolveSchema(name, projectRoot) {
+    const normalizedName = name.replace(/\.ya?ml$/, '');
+    const schemaDir = getSchemaDir(normalizedName, projectRoot);
+    if (!schemaDir) {
+        const available = listSchemas(projectRoot);
+        throw new Error(`Schema '${normalizedName}' not found. Available schemas: ${available.join(', ')}`);
+    }
+    const schemaPath = path.join(schemaDir, 'schema.yaml');
+    let content;
+    try {
+        content = fs.readFileSync(schemaPath, 'utf-8');
+    }
+    catch (err) {
+        const ioError = err instanceof Error ? err : new Error(String(err));
+        throw new SchemaLoadError(`Failed to read schema at '${schemaPath}': ${ioError.message}`, schemaPath, ioError);
+    }
+    try {
+        return parseSchema(content);
+    }
+    catch (err) {
+        if (err instanceof SchemaValidationError) {
+            throw new SchemaLoadError(`Invalid schema at '${schemaPath}': ${err.message}`, schemaPath, err);
+        }
+        const parseError = err instanceof Error ? err : new Error(String(err));
+        throw new SchemaLoadError(`Failed to parse schema at '${schemaPath}': ${parseError.message}`, schemaPath, parseError);
+    }
+}
+/**
+ * Lists all available schema names.
+ *
+ * @param projectRoot - Optional project root directory for project-local resolution
+ * @returns Sorted array of schema names
+ */
+export function listSchemas(projectRoot) {
+    const schemas = new Set();
+    // Package built-in schemas
+    const packageDir = getPackageSchemasDir();
+    if (fs.existsSync(packageDir)) {
+        for (const entry of fs.readdirSync(packageDir, { withFileTypes: true })) {
+            if (entry.isDirectory()) {
+                const schemaPath = path.join(packageDir, entry.name, 'schema.yaml');
+                if (fs.existsSync(schemaPath)) {
+                    schemas.add(entry.name);
+                }
+            }
+        }
+    }
+    // Project-local schemas
+    if (projectRoot) {
+        const projectDir = getProjectSchemasDir(projectRoot);
+        if (fs.existsSync(projectDir)) {
+            for (const entry of fs.readdirSync(projectDir, { withFileTypes: true })) {
+                if (entry.isDirectory()) {
+                    const schemaPath = path.join(projectDir, entry.name, 'schema.yaml');
+                    if (fs.existsSync(schemaPath)) {
+                        schemas.add(entry.name);
+                    }
+                }
+            }
+        }
+    }
+    return Array.from(schemas).sort();
+}

package/dist/core/artifact-graph/schema.d.ts

@@ -0,0 +1,23 @@
+import { type SchemaYaml } from './types.js';
+/**
+ * Error thrown when schema validation fails.
+ */
+export declare class SchemaValidationError extends Error {
+    constructor(message: string);
+}
+/**
+ * Loads and validates an artifact schema from a YAML file path.
+ *
+ * @param filePath - Absolute path to the schema.yaml file
+ * @returns The validated schema object
+ * @throws SchemaValidationError if the YAML is invalid
+ */
+export declare function loadSchema(filePath: string): SchemaYaml;
+/**
+ * Parses and validates an artifact schema from YAML content string.
+ *
+ * @param yamlContent - Raw YAML string
+ * @returns The validated schema object
+ * @throws SchemaValidationError if validation fails
+ */
+export declare function parseSchema(yamlContent: string): SchemaYaml;

package/dist/core/artifact-graph/schema.js

@@ -0,0 +1,115 @@
+import * as fs from 'node:fs';
+import yaml from 'js-yaml';
+import { SchemaYamlSchema } from './types.js';
+/**
+ * Error thrown when schema validation fails.
+ */
+export class SchemaValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'SchemaValidationError';
+    }
+}
+/**
+ * Loads and validates an artifact schema from a YAML file path.
+ *
+ * @param filePath - Absolute path to the schema.yaml file
+ * @returns The validated schema object
+ * @throws SchemaValidationError if the YAML is invalid
+ */
+export function loadSchema(filePath) {
+    const content = fs.readFileSync(filePath, 'utf-8');
+    return parseSchema(content);
+}
+/**
+ * Parses and validates an artifact schema from YAML content string.
+ *
+ * @param yamlContent - Raw YAML string
+ * @returns The validated schema object
+ * @throws SchemaValidationError if validation fails
+ */
+export function parseSchema(yamlContent) {
+    const parsed = yaml.load(yamlContent);
+    const result = SchemaYamlSchema.safeParse(parsed);
+    if (!result.success) {
+        const errors = result.error.issues
+            .map(e => `${e.path.join('.')}: ${e.message}`)
+            .join(', ');
+        throw new SchemaValidationError(`Invalid schema: ${errors}`);
+    }
+    const schema = result.data;
+    validateNoDuplicateIds(schema.artifacts);
+    validateRequiresReferences(schema.artifacts);
+    validateNoCycles(schema.artifacts);
+    return schema;
+}
+/**
+ * Validates that there are no duplicate artifact IDs.
+ */
+function validateNoDuplicateIds(artifacts) {
+    const seen = new Set();
+    for (const artifact of artifacts) {
+        if (seen.has(artifact.id)) {
+            throw new SchemaValidationError(`Duplicate artifact ID: ${artifact.id}`);
+        }
+        seen.add(artifact.id);
+    }
+}
+/**
+ * Validates that all `requires` references point to valid artifact IDs.
+ */
+function validateRequiresReferences(artifacts) {
+    const validIds = new Set(artifacts.map(a => a.id));
+    for (const artifact of artifacts) {
+        for (const req of artifact.requires) {
+            if (!validIds.has(req)) {
+                throw new SchemaValidationError(`Invalid dependency reference in artifact '${artifact.id}': '${req}' does not exist`);
+            }
+        }
+    }
+}
+/**
+ * Validates that there are no cyclic dependencies.
+ * Uses DFS with path reconstruction for clear error messages.
+ */
+function validateNoCycles(artifacts) {
+    const artifactMap = new Map(artifacts.map(a => [a.id, a]));
+    const visited = new Set();
+    const inStack = new Set();
+    const parent = new Map();
+    function dfs(id) {
+        visited.add(id);
+        inStack.add(id);
+        const artifact = artifactMap.get(id);
+        if (!artifact)
+            return null;
+        for (const dep of artifact.requires) {
+            if (!visited.has(dep)) {
+                parent.set(dep, id);
+                const cycle = dfs(dep);
+                if (cycle)
+                    return cycle;
+            }
+            else if (inStack.has(dep)) {
+                const cyclePath = [dep];
+                let current = id;
+                while (current !== dep) {
+                    cyclePath.unshift(current);
+                    current = parent.get(current);
+                }
+                cyclePath.unshift(dep);
+                return cyclePath.join(' -> ');
+            }
+        }
+        inStack.delete(id);
+        return null;
+    }
+    for (const artifact of artifacts) {
+        if (!visited.has(artifact.id)) {
+            const cycle = dfs(artifact.id);
+            if (cycle) {
+                throw new SchemaValidationError(`Cyclic dependency detected: ${cycle}`);
+            }
+        }
+    }
+}

package/dist/core/artifact-graph/state.d.ts

@@ -0,0 +1,9 @@
+import type { SchemaYaml } from './types.js';
+/**
+ * Detects which artifacts are completed by checking file existence in the change directory.
+ *
+ * @param changeDir - The change directory to scan
+ * @param schema - The workflow schema with artifact definitions
+ * @returns Array of completed artifact IDs
+ */
+export declare function getCompletedArtifacts(changeDir: string, schema: SchemaYaml): string[];

package/dist/core/artifact-graph/state.js

@@ -0,0 +1,93 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+/**
+ * Checks if an artifact's generated file(s) exist in the change directory.
+ * Supports simple file paths and basic glob patterns with "**".
+ */
+function artifactFileExists(changeDir, generates) {
+    if (!isGlobPattern(generates)) {
+        const fullPath = path.join(changeDir, generates);
+        try {
+            return fs.statSync(fullPath).isFile();
+        }
+        catch {
+            return false;
+        }
+    }
+    // For glob patterns, check if any matching files exist
+    return globHasMatch(changeDir, generates);
+}
+/**
+ * Checks if a path pattern contains glob characters.
+ */
+function isGlobPattern(pattern) {
+    return pattern.includes('*') || pattern.includes('?') || pattern.includes('[');
+}
+/**
+ * Simple glob matching: checks if any files match a glob-style pattern.
+ * Avoids external dependencies by walking the directory tree.
+ */
+function globHasMatch(baseDir, pattern) {
+    // Extract the extension pattern (e.g., "*.md" from "specs/**/*.md")
+    const parts = pattern.split('/');
+    const filePattern = parts[parts.length - 1];
+    const extension = filePattern.startsWith('*') ? filePattern.slice(1) : '';
+    // Get the starting directory path (before any glob segment)
+    const dirParts = [];
+    for (const part of parts) {
+        if (part.includes('*') || part.includes('?'))
+            break;
+        dirParts.push(part);
+    }
+    const startDir = dirParts.length > 0
+        ? path.join(baseDir, ...dirParts)
+        : baseDir;
+    if (!fs.existsSync(startDir)) {
+        return false;
+    }
+    return walkForMatch(startDir, extension);
+}
+/**
+ * Recursively walks a directory looking for files matching the extension.
+ */
+function walkForMatch(dir, extension) {
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return false;
+    }
+    for (const entry of entries) {
+        const fullPath = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            if (walkForMatch(fullPath, extension))
+                return true;
+        }
+        else if (entry.isFile()) {
+            if (extension === '' || entry.name.endsWith(extension)) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+/**
+ * Detects which artifacts are completed by checking file existence in the change directory.
+ *
+ * @param changeDir - The change directory to scan
+ * @param schema - The workflow schema with artifact definitions
+ * @returns Array of completed artifact IDs
+ */
+export function getCompletedArtifacts(changeDir, schema) {
+    if (!fs.existsSync(changeDir)) {
+        return [];
+    }
+    const completed = [];
+    for (const artifact of schema.artifacts) {
+        if (artifactFileExists(changeDir, artifact.generates)) {
+            completed.push(artifact.id);
+        }
+    }
+    return completed;
+}

package/dist/core/artifact-graph/types.d.ts

@@ -0,0 +1,123 @@
+import { z } from 'zod';
+/**
+ * Zod schema for a single artifact definition in a workflow schema.
+ */
+export declare const ArtifactSchema: z.ZodObject<{
+    id: z.ZodString;
+    generates: z.ZodString;
+    description: z.ZodString;
+    instruction: z.ZodOptional<z.ZodString>;
+    requires: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    generates: string;
+    description: string;
+    requires: string[];
+    instruction?: string | undefined;
+}, {
+    id: string;
+    generates: string;
+    description: string;
+    instruction?: string | undefined;
+    requires?: string[] | undefined;
+}>;
+/**
+ * Zod schema for the apply phase configuration.
+ */
+export declare const ApplyPhaseSchema: z.ZodObject<{
+    requires: z.ZodArray<z.ZodString, "many">;
+    tracks: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    instruction: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    requires: string[];
+    instruction?: string | undefined;
+    tracks?: string | null | undefined;
+}, {
+    requires: string[];
+    instruction?: string | undefined;
+    tracks?: string | null | undefined;
+}>;
+/**
+ * Zod schema for the full schema YAML structure.
+ */
+export declare const SchemaYamlSchema: z.ZodObject<{
+    name: z.ZodString;
+    version: z.ZodNumber;
+    description: z.ZodOptional<z.ZodString>;
+    artifacts: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        generates: z.ZodString;
+        description: z.ZodString;
+        instruction: z.ZodOptional<z.ZodString>;
+        requires: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        generates: string;
+        description: string;
+        requires: string[];
+        instruction?: string | undefined;
+    }, {
+        id: string;
+        generates: string;
+        description: string;
+        instruction?: string | undefined;
+        requires?: string[] | undefined;
+    }>, "many">;
+    apply: z.ZodOptional<z.ZodObject<{
+        requires: z.ZodArray<z.ZodString, "many">;
+        tracks: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        instruction: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        requires: string[];
+        instruction?: string | undefined;
+        tracks?: string | null | undefined;
+    }, {
+        requires: string[];
+        instruction?: string | undefined;
+        tracks?: string | null | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    version: number;
+    artifacts: {
+        id: string;
+        generates: string;
+        description: string;
+        requires: string[];
+        instruction?: string | undefined;
+    }[];
+    description?: string | undefined;
+    apply?: {
+        requires: string[];
+        instruction?: string | undefined;
+        tracks?: string | null | undefined;
+    } | undefined;
+}, {
+    name: string;
+    version: number;
+    artifacts: {
+        id: string;
+        generates: string;
+        description: string;
+        instruction?: string | undefined;
+        requires?: string[] | undefined;
+    }[];
+    description?: string | undefined;
+    apply?: {
+        requires: string[];
+        instruction?: string | undefined;
+        tracks?: string | null | undefined;
+    } | undefined;
+}>;
+/** A single artifact definition. */
+export type Artifact = z.infer<typeof ArtifactSchema>;
+/** Apply phase configuration. */
+export type ApplyPhase = z.infer<typeof ApplyPhaseSchema>;
+/** Full schema YAML structure. */
+export type SchemaYaml = z.infer<typeof SchemaYamlSchema>;
+/** Set of completed artifact IDs. */
+export type CompletedSet = Set<string>;
+/** Blocked artifacts mapped to their missing dependency IDs. */
+export interface BlockedArtifacts {
+    readonly [artifactId: string]: readonly string[];
+}

package/dist/core/artifact-graph/types.js

@@ -0,0 +1,29 @@
+import { z } from 'zod';
+/**
+ * Zod schema for a single artifact definition in a workflow schema.
+ */
+export const ArtifactSchema = z.object({
+    id: z.string().min(1, { message: 'Artifact ID is required' }),
+    generates: z.string().min(1, { message: 'generates field is required' }),
+    description: z.string(),
+    instruction: z.string().optional(),
+    requires: z.array(z.string()).default([]),
+});
+/**
+ * Zod schema for the apply phase configuration.
+ */
+export const ApplyPhaseSchema = z.object({
+    requires: z.array(z.string()).min(1, { message: 'At least one required artifact' }),
+    tracks: z.string().nullable().optional(),
+    instruction: z.string().optional(),
+});
+/**
+ * Zod schema for the full schema YAML structure.
+ */
+export const SchemaYamlSchema = z.object({
+    name: z.string().min(1, { message: 'Schema name is required' }),
+    version: z.number().int().positive({ message: 'Version must be a positive integer' }),
+    description: z.string().optional(),
+    artifacts: z.array(ArtifactSchema).min(1, { message: 'At least one artifact required' }),
+    apply: ApplyPhaseSchema.optional(),
+});

package/dist/core/parsers/change-parser.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Change parser.
+ *
+ * Higher-level API that delegates to the markdown delta-spec parser.
+ * Produces a DeltaPlan from a delta-spec file's content.
+ */
+import type { RequirementBlock, RemovedRequirement, RenamedRequirement } from './markdown-parser.js';
+export interface DeltaPlan {
+    readonly added: readonly RequirementBlock[];
+    readonly modified: readonly RequirementBlock[];
+    readonly removed: readonly RemovedRequirement[];
+    readonly renamed: readonly RenamedRequirement[];
+}
+/**
+ * Parse a delta-spec markdown file into a DeltaPlan.
+ *
+ * This is a thin wrapper around `parseDeltaSpec` that produces
+ * the `DeltaPlan` type used by the rest of the system.
+ */
+export declare function parseDeltaSpecFile(content: string): DeltaPlan;

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

@@ -0,0 +1,22 @@
+/**
+ * Change parser.
+ *
+ * Higher-level API that delegates to the markdown delta-spec parser.
+ * Produces a DeltaPlan from a delta-spec file's content.
+ */
+import { parseDeltaSpec } from './markdown-parser.js';
+/**
+ * Parse a delta-spec markdown file into a DeltaPlan.
+ *
+ * This is a thin wrapper around `parseDeltaSpec` that produces
+ * the `DeltaPlan` type used by the rest of the system.
+ */
+export function parseDeltaSpecFile(content) {
+    const spec = parseDeltaSpec(content);
+    return {
+        added: spec.added,
+        modified: spec.modified,
+        removed: spec.removed,
+        renamed: spec.renamed,
+    };
+}

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

@@ -0,0 +1,7 @@
+export { parseDeltaSpec } from './markdown-parser.js';
+export type { DeltaSpec, RequirementBlock, Scenario, RemovedRequirement, RenamedRequirement, } from './markdown-parser.js';
+export { extractRequirementName, extractRequirementBlock, } from './requirement-blocks.js';
+export { parseDeltaSpecFile } from './change-parser.js';
+export type { DeltaPlan } from './change-parser.js';
+export { parseMainSpec } from './spec-structure.js';
+export type { Requirement, ParsedSpec } from './spec-structure.js';

package/dist/core/parsers/index.js

@@ -0,0 +1,4 @@
+export { parseDeltaSpec } from './markdown-parser.js';
+export { extractRequirementName, extractRequirementBlock, } from './requirement-blocks.js';
+export { parseDeltaSpecFile } from './change-parser.js';
+export { parseMainSpec } from './spec-structure.js';

package/dist/core/parsers/markdown-parser.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Markdown delta-spec parser.
+ *
+ * Parses a delta-spec markdown file into structured data with
+ * ADDED, MODIFIED, REMOVED, and RENAMED sections.
+ */
+export interface Scenario {
+    readonly name: string;
+    readonly when: readonly string[];
+    readonly then: readonly string[];
+}
+export interface RequirementBlock {
+    readonly name: string;
+    readonly description: string;
+    readonly scenarios: readonly Scenario[];
+}
+export interface RemovedRequirement {
+    readonly name: string;
+    readonly reason: string;
+    readonly migration: string;
+}
+export interface RenamedRequirement {
+    readonly from: string;
+    readonly to: string;
+}
+export interface DeltaSpec {
+    readonly added: readonly RequirementBlock[];
+    readonly modified: readonly RequirementBlock[];
+    readonly removed: readonly RemovedRequirement[];
+    readonly renamed: readonly RenamedRequirement[];
+}
+/**
+ * Parse a delta-spec markdown file into structured data.
+ */
+export declare function parseDeltaSpec(content: string): DeltaSpec;