@hstm-labs/forge-spec-parser 0.1.2 → 0.1.3

package/dist/index.d.ts

@@ -2,7 +2,9 @@ export type { SpecFormat, ParsedSpecification, SpecMetadata, SpecSection, SpecRe
 export type { SpecParserPlugin } from './parser-plugin.js';
 export { ParserRegistry } from './registry.js';
 export { detectFormat } from './detect.js';
-export { loadSpecFile, parseSpec } from './loader.js';
+export { loadSpecFile, parseSpec, parseSpecPath } from './loader.js';
+export { resolveSpecFiles } from './resolve.js';
+export { mergeSpecs } from './merge.js';
 export { MarkdownParserPlugin } from './parsers/markdown-parser.js';
 export { YamlParserPlugin } from './parsers/yaml-parser.js';
 export { JsonParserPlugin } from './parsers/json-parser.js';
@@ -14,5 +16,6 @@ export { checkCompleteness } from './validators/completeness-checker.js';
 export type { CompletenessResult } from './validators/completeness-checker.js';
 export { validateCrossReferences } from './validators/cross-reference-validator.js';
 export { validateSpec } from './validators/spec-validator.js';
-export { executeValidateStage } from './validate-stage.js';
+export { executeValidateStage, executeValidateStageWithSpec } from './validate-stage.js';
+export type { ValidateStageResult } from './validate-stage.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,YAAY,EACV,UAAU,EACV,mBAAmB,EACnB,YAAY,EACZ,WAAW,EACX,eAAe,EACf,UAAU,EACV,WAAW,EACX,kBAAkB,EAClB,YAAY,EACZ,YAAY,GACb,MAAM,YAAY,CAAC;AAGpB,YAAY,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAG3D,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAG/C,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAG3C,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAGtD,OAAO,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAC;AACpE,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAG5D,OAAO,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AAGnE,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAG9D,YAAY,EACV,kBAAkB,EAClB,kBAAkB,EAClB,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,uBAAuB,CAAC;AAG/B,OAAO,EAAE,cAAc,EAAE,MAAM,kCAAkC,CAAC;AAClE,OAAO,EAAE,iBAAiB,EAAE,MAAM,sCAAsC,CAAC;AACzE,YAAY,EAAE,kBAAkB,EAAE,MAAM,sCAAsC,CAAC;AAC/E,OAAO,EAAE,uBAAuB,EAAE,MAAM,2CAA2C,CAAC;AACpF,OAAO,EAAE,YAAY,EAAE,MAAM,gCAAgC,CAAC;AAG9D,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,YAAY,EACV,UAAU,EACV,mBAAmB,EACnB,YAAY,EACZ,WAAW,EACX,eAAe,EACf,UAAU,EACV,WAAW,EACX,kBAAkB,EAClB,YAAY,EACZ,YAAY,GACb,MAAM,YAAY,CAAC;AAGpB,YAAY,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAG3D,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAG/C,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAG3C,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAGrE,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAGhD,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAGxC,OAAO,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAC;AACpE,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAG5D,OAAO,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AAGnE,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAG9D,YAAY,EACV,kBAAkB,EAClB,kBAAkB,EAClB,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,uBAAuB,CAAC;AAG/B,OAAO,EAAE,cAAc,EAAE,MAAM,kCAAkC,CAAC;AAClE,OAAO,EAAE,iBAAiB,EAAE,MAAM,sCAAsC,CAAC;AACzE,YAAY,EAAE,kBAAkB,EAAE,MAAM,sCAAsC,CAAC;AAC/E,OAAO,EAAE,uBAAuB,EAAE,MAAM,2CAA2C,CAAC;AACpF,OAAO,EAAE,YAAY,EAAE,MAAM,gCAAgC,CAAC;AAG9D,OAAO,EAAE,oBAAoB,EAAE,4BAA4B,EAAE,MAAM,qBAAqB,CAAC;AACzF,YAAY,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/index.js

@@ -4,7 +4,11 @@ export { ParserRegistry } from './registry.js';
 // Format detection
 export { detectFormat } from './detect.js';
 // File loading and parse entry point
-export { loadSpecFile, parseSpec } from './loader.js';
+export { loadSpecFile, parseSpec, parseSpecPath } from './loader.js';
+// Spec path resolution (file or directory)
+export { resolveSpecFiles } from './resolve.js';
+// Multi-file merge
+export { mergeSpecs } from './merge.js';
 // Parser plugins
 export { MarkdownParserPlugin } from './parsers/markdown-parser.js';
 export { YamlParserPlugin } from './parsers/yaml-parser.js';
@@ -19,5 +23,5 @@ export { checkCompleteness } from './validators/completeness-checker.js';
 export { validateCrossReferences } from './validators/cross-reference-validator.js';
 export { validateSpec } from './validators/spec-validator.js';
 // Validate stage integration
-export { executeValidateStage } from './validate-stage.js';
+export { executeValidateStage, executeValidateStageWithSpec } from './validate-stage.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,0CAA0C;AAmB1C,kBAAkB;AAClB,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAE/C,mBAAmB;AACnB,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,qCAAqC;AACrC,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAEtD,iBAAiB;AACjB,OAAO,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAC;AACpE,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAE5D,2BAA2B;AAC3B,OAAO,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AAEnE,2BAA2B;AAC3B,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAU9D,aAAa;AACb,OAAO,EAAE,cAAc,EAAE,MAAM,kCAAkC,CAAC;AAClE,OAAO,EAAE,iBAAiB,EAAE,MAAM,sCAAsC,CAAC;AAEzE,OAAO,EAAE,uBAAuB,EAAE,MAAM,2CAA2C,CAAC;AACpF,OAAO,EAAE,YAAY,EAAE,MAAM,gCAAgC,CAAC;AAE9D,6BAA6B;AAC7B,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,0CAA0C;AAmB1C,kBAAkB;AAClB,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAE/C,mBAAmB;AACnB,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,qCAAqC;AACrC,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAErE,2CAA2C;AAC3C,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAEhD,mBAAmB;AACnB,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAExC,iBAAiB;AACjB,OAAO,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAC;AACpE,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAE5D,2BAA2B;AAC3B,OAAO,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AAEnE,2BAA2B;AAC3B,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAU9D,aAAa;AACb,OAAO,EAAE,cAAc,EAAE,MAAM,kCAAkC,CAAC;AAClE,OAAO,EAAE,iBAAiB,EAAE,MAAM,sCAAsC,CAAC;AAEzE,OAAO,EAAE,uBAAuB,EAAE,MAAM,2CAA2C,CAAC;AACpF,OAAO,EAAE,YAAY,EAAE,MAAM,gCAAgC,CAAC;AAE9D,6BAA6B;AAC7B,OAAO,EAAE,oBAAoB,EAAE,4BAA4B,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/loader.d.ts

@@ -1,9 +1,10 @@
 /**
  * Specification file loader and primary parse entry point.
  *
- * Provides {@link loadSpecFile} for reading raw file content and
- * {@link parseSpec} as the main public API for parsing a specification
- * file into the canonical {@link ParsedSpecification} model.
+ * Provides {@link loadSpecFile} for reading raw file content,
+ * {@link parseSpec} for parsing a single file, and
+ * {@link parseSpecPath} as the high-level API that handles both
+ * file and directory `specPath` values.
  */
 import type { ParsedSpecification } from './types.js';
 import type { ParserRegistry } from './registry.js';
@@ -28,4 +29,18 @@ export declare function loadSpecFile(filePath: string): string;
  * @throws {@link ForgeError} with code `FORGE-SPEC-001` if format detection, file reading, or parsing fails
  */
 export declare function parseSpec(filePath: string, registry: ParserRegistry): ParsedSpecification;
+/**
+ * Parse a specification path that may be a single file or a directory.
+ *
+ * When `specPath` is a directory, all supported spec files within it
+ * (recursively) are parsed and merged into a single
+ * {@link ParsedSpecification}.
+ *
+ * @param specPath - Path to a spec file or directory containing spec files
+ * @param registry - Parser registry with registered format plugins
+ * @returns Parsed (and possibly merged) specification
+ * @throws {@link ForgeError} `FORGE-SPEC-003` if path does not exist or directory is empty
+ * @throws {@link ForgeError} `FORGE-SPEC-001` if any file cannot be parsed
+ */
+export declare function parseSpecPath(specPath: string, registry: ParserRegistry): ParsedSpecification;
 //# sourceMappingURL=loader.d.ts.map

package/dist/loader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../src/loader.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAEtD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAEpD;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAWrD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,CACvB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,cAAc,GACvB,mBAAmB,CAKrB"}
+{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../src/loader.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAEtD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAIpD;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAWrD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,CACvB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,cAAc,GACvB,mBAAmB,CAKrB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,cAAc,GACvB,mBAAmB,CASrB"}

package/dist/loader.js

@@ -1,13 +1,16 @@
 /**
  * Specification file loader and primary parse entry point.
  *
- * Provides {@link loadSpecFile} for reading raw file content and
- * {@link parseSpec} as the main public API for parsing a specification
- * file into the canonical {@link ParsedSpecification} model.
+ * Provides {@link loadSpecFile} for reading raw file content,
+ * {@link parseSpec} for parsing a single file, and
+ * {@link parseSpecPath} as the high-level API that handles both
+ * file and directory `specPath` values.
  */
 import fs from 'node:fs';
 import { ForgeError, ErrorCodes } from '@hstm-labs/forge-common';
 import { detectFormat } from './detect.js';
+import { resolveSpecFiles } from './resolve.js';
+import { mergeSpecs } from './merge.js';
 /**
  * Read the content of a specification file from disk.
  *
@@ -42,4 +45,25 @@ export function parseSpec(filePath, registry) {
     const content = loadSpecFile(filePath);
     return plugin.parse(content, filePath);
 }
+/**
+ * Parse a specification path that may be a single file or a directory.
+ *
+ * When `specPath` is a directory, all supported spec files within it
+ * (recursively) are parsed and merged into a single
+ * {@link ParsedSpecification}.
+ *
+ * @param specPath - Path to a spec file or directory containing spec files
+ * @param registry - Parser registry with registered format plugins
+ * @returns Parsed (and possibly merged) specification
+ * @throws {@link ForgeError} `FORGE-SPEC-003` if path does not exist or directory is empty
+ * @throws {@link ForgeError} `FORGE-SPEC-001` if any file cannot be parsed
+ */
+export function parseSpecPath(specPath, registry) {
+    const files = resolveSpecFiles(specPath);
+    if (files.length === 1) {
+        return parseSpec(files[0], registry);
+    }
+    const specs = files.map((f) => parseSpec(f, registry));
+    return mergeSpecs(specs, specPath);
+}
 //# sourceMappingURL=loader.js.map

package/dist/loader.js.map

@@ -1 +1 @@
-{"version":3,"file":"loader.js","sourceRoot":"","sources":["../src/loader.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAEjE,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAG3C;;;;;;GAMG;AACH,MAAM,UAAU,YAAY,CAAC,QAAgB;IAC3C,IAAI,CAAC;QACH,OAAO,EAAE,CAAC,YAAY,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IAC5C,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,UAAU,CAClB,UAAU,CAAC,IAAI,CAAC,aAAa,EAC7B,sCAAsC,QAAQ,KAAK;YACjD,qDAAqD,EACvD,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAC/C,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,SAAS,CACvB,QAAgB,EAChB,QAAwB;IAExB,MAAM,MAAM,GAAG,YAAY,CAAC,QAAQ,CAAC,CAAC;IACtC,MAAM,MAAM,GAAG,QAAQ,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;IAC1C,MAAM,OAAO,GAAG,YAAY,CAAC,QAAQ,CAAC,CAAC;IACvC,OAAO,MAAM,CAAC,KAAK,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;AACzC,CAAC"}
+{"version":3,"file":"loader.js","sourceRoot":"","sources":["../src/loader.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAEjE,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAExC;;;;;;GAMG;AACH,MAAM,UAAU,YAAY,CAAC,QAAgB;IAC3C,IAAI,CAAC;QACH,OAAO,EAAE,CAAC,YAAY,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IAC5C,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,UAAU,CAClB,UAAU,CAAC,IAAI,CAAC,aAAa,EAC7B,sCAAsC,QAAQ,KAAK;YACjD,qDAAqD,EACvD,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAC/C,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,SAAS,CACvB,QAAgB,EAChB,QAAwB;IAExB,MAAM,MAAM,GAAG,YAAY,CAAC,QAAQ,CAAC,CAAC;IACtC,MAAM,MAAM,GAAG,QAAQ,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;IAC1C,MAAM,OAAO,GAAG,YAAY,CAAC,QAAQ,CAAC,CAAC;IACvC,OAAO,MAAM,CAAC,KAAK,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;AACzC,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,aAAa,CAC3B,QAAgB,EAChB,QAAwB;IAExB,MAAM,KAAK,GAAG,gBAAgB,CAAC,QAAQ,CAAC,CAAC;IAEzC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvB,OAAO,SAAS,CAAC,KAAK,CAAC,CAAC,CAAE,EAAE,QAAQ,CAAC,CAAC;IACxC,CAAC;IAED,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,SAAS,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC,CAAC;IACvD,OAAO,UAAU,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;AACrC,CAAC"}

package/dist/merge.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Multi-file specification merger.
+ *
+ * Combines multiple {@link ParsedSpecification} objects into a single
+ * unified specification. Used when `specPath` points to a directory
+ * containing multiple spec files.
+ */
+import type { ParsedSpecification } from './types.js';
+/**
+ * Merge multiple parsed specifications into one.
+ *
+ * - Metadata: titles are joined; `sourcePath` reflects the directory.
+ * - Sections, requirements, workflows: concatenated in order.
+ * - Entities: deduplicated by name (first occurrence wins).
+ * - API style: first non-undefined value wins.
+ *
+ * @param specs - Array of parsed specifications (must have at least one)
+ * @param sourcePath - Path to attribute as the merged spec's source
+ * @returns A single merged specification
+ * @throws {Error} if `specs` is empty
+ */
+export declare function mergeSpecs(specs: ParsedSpecification[], sourcePath: string): ParsedSpecification;
+//# sourceMappingURL=merge.d.ts.map

package/dist/merge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"merge.d.ts","sourceRoot":"","sources":["../src/merge.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAgB,MAAM,YAAY,CAAC;AAEpE;;;;;;;;;;;;GAYG;AACH,wBAAgB,UAAU,CACxB,KAAK,EAAE,mBAAmB,EAAE,EAC5B,UAAU,EAAE,MAAM,GACjB,mBAAmB,CAyCrB"}

package/dist/merge.js

@@ -0,0 +1,56 @@
+/**
+ * Multi-file specification merger.
+ *
+ * Combines multiple {@link ParsedSpecification} objects into a single
+ * unified specification. Used when `specPath` points to a directory
+ * containing multiple spec files.
+ */
+/**
+ * Merge multiple parsed specifications into one.
+ *
+ * - Metadata: titles are joined; `sourcePath` reflects the directory.
+ * - Sections, requirements, workflows: concatenated in order.
+ * - Entities: deduplicated by name (first occurrence wins).
+ * - API style: first non-undefined value wins.
+ *
+ * @param specs - Array of parsed specifications (must have at least one)
+ * @param sourcePath - Path to attribute as the merged spec's source
+ * @returns A single merged specification
+ * @throws {Error} if `specs` is empty
+ */
+export function mergeSpecs(specs, sourcePath) {
+    if (specs.length === 0) {
+        throw new Error('Cannot merge zero specifications.');
+    }
+    const first = specs[0];
+    if (specs.length === 1) {
+        return first;
+    }
+    const metadata = {
+        title: specs.map((s) => s.metadata.title).join(' + '),
+        sourcePath,
+        format: first.metadata.format,
+        description: specs
+            .map((s) => s.metadata.description)
+            .filter(Boolean)
+            .join('; ') || undefined,
+    };
+    const seenEntities = new Set();
+    const entities = specs.flatMap((s) => s.entities).filter((e) => {
+        if (seenEntities.has(e.name)) {
+            return false;
+        }
+        seenEntities.add(e.name);
+        return true;
+    });
+    const apiStyle = specs.find((s) => s.apiStyle !== undefined)?.apiStyle;
+    return {
+        metadata,
+        sections: specs.flatMap((s) => s.sections),
+        requirements: specs.flatMap((s) => s.requirements),
+        entities,
+        workflows: specs.flatMap((s) => s.workflows),
+        ...(apiStyle !== undefined ? { apiStyle } : {}),
+    };
+}
+//# sourceMappingURL=merge.js.map

package/dist/merge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"merge.js","sourceRoot":"","sources":["../src/merge.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,UAAU,CACxB,KAA4B,EAC5B,UAAkB;IAElB,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvB,MAAM,IAAI,KAAK,CAAC,mCAAmC,CAAC,CAAC;IACvD,CAAC;IAED,MAAM,KAAK,GAAG,KAAK,CAAC,CAAC,CAAE,CAAC;IAExB,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvB,OAAO,KAAK,CAAC;IACf,CAAC;IAED,MAAM,QAAQ,GAAiB;QAC7B,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC;QACrD,UAAU;QACV,MAAM,EAAE,KAAK,CAAC,QAAQ,CAAC,MAAM;QAC7B,WAAW,EACT,KAAK;aACF,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC;aAClC,MAAM,CAAC,OAAO,CAAC;aACf,IAAI,CAAC,IAAI,CAAC,IAAI,SAAS;KAC7B,CAAC;IAEF,MAAM,YAAY,GAAG,IAAI,GAAG,EAAU,CAAC;IACvC,MAAM,QAAQ,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE;QAC7D,IAAI,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC;YAC7B,OAAO,KAAK,CAAC;QACf,CAAC;QACD,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QACzB,OAAO,IAAI,CAAC;IACd,CAAC,CAAC,CAAC;IAEH,MAAM,QAAQ,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,SAAS,CAAC,EAAE,QAAQ,CAAC;IAEvE,OAAO;QACL,QAAQ;QACR,QAAQ,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC;QAC1C,YAAY,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,YAAY,CAAC;QAClD,QAAQ;QACR,SAAS,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;QAC5C,GAAG,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAChD,CAAC;AACJ,CAAC"}

package/dist/resolve.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Spec path resolution — handles both file and directory `specPath` values.
+ *
+ * When `specPath` is a directory, recursively scans for files with supported
+ * extensions (`.md`, `.yaml`, `.yml`, `.json`) and returns them in sorted
+ * order for deterministic processing.
+ */
+/**
+ * Resolve a `specPath` to one or more specification file paths.
+ *
+ * - If `specPath` is a file, returns it as a single-element array.
+ * - If `specPath` is a directory, recursively scans for files with
+ *   supported extensions and returns them sorted alphabetically.
+ *
+ * @param specPath - Absolute or relative path to a spec file or directory
+ * @returns Sorted array of resolved spec file paths
+ * @throws {@link ForgeError} `FORGE-SPEC-003` if the path does not exist or
+ *   the directory contains no supported spec files
+ */
+export declare function resolveSpecFiles(specPath: string): string[];
+//# sourceMappingURL=resolve.d.ts.map

package/dist/resolve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.d.ts","sourceRoot":"","sources":["../src/resolve.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAcH;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,CAgC3D"}

package/dist/resolve.js

@@ -0,0 +1,70 @@
+/**
+ * Spec path resolution — handles both file and directory `specPath` values.
+ *
+ * When `specPath` is a directory, recursively scans for files with supported
+ * extensions (`.md`, `.yaml`, `.yml`, `.json`) and returns them in sorted
+ * order for deterministic processing.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { ForgeError, ErrorCodes } from '@hstm-labs/forge-common';
+/** File extensions accepted as specification files. */
+const SUPPORTED_EXTENSIONS = new Set([
+    '.md',
+    '.yaml',
+    '.yml',
+    '.json',
+]);
+/**
+ * Resolve a `specPath` to one or more specification file paths.
+ *
+ * - If `specPath` is a file, returns it as a single-element array.
+ * - If `specPath` is a directory, recursively scans for files with
+ *   supported extensions and returns them sorted alphabetically.
+ *
+ * @param specPath - Absolute or relative path to a spec file or directory
+ * @returns Sorted array of resolved spec file paths
+ * @throws {@link ForgeError} `FORGE-SPEC-003` if the path does not exist or
+ *   the directory contains no supported spec files
+ */
+export function resolveSpecFiles(specPath) {
+    const stat = fs.statSync(specPath, { throwIfNoEntry: false });
+    if (!stat) {
+        throw new ForgeError(ErrorCodes.SPEC.NOT_FOUND, `Specification path '${specPath}' does not exist. ` +
+            `Verify the specPath in forge.config.json and retry.`);
+    }
+    if (stat.isFile()) {
+        return [specPath];
+    }
+    if (stat.isDirectory()) {
+        const files = scanDirectory(specPath);
+        if (files.length === 0) {
+            throw new ForgeError(ErrorCodes.SPEC.NOT_FOUND, `No specification files found in directory '${specPath}'. ` +
+                `Add .md, .yaml, .yml, or .json files to the directory and retry.`);
+        }
+        return files.sort();
+    }
+    throw new ForgeError(ErrorCodes.SPEC.NOT_FOUND, `Specification path '${specPath}' is not a file or directory. ` +
+        `Verify the specPath in forge.config.json and retry.`);
+}
+/**
+ * Recursively scan a directory for files with supported spec extensions.
+ */
+function scanDirectory(dirPath) {
+    const results = [];
+    const entries = fs.readdirSync(dirPath, { withFileTypes: true });
+    for (const entry of entries) {
+        const fullPath = path.join(dirPath, entry.name);
+        if (entry.isDirectory()) {
+            results.push(...scanDirectory(fullPath));
+        }
+        else if (entry.isFile()) {
+            const ext = path.extname(entry.name).toLowerCase();
+            if (SUPPORTED_EXTENSIONS.has(ext)) {
+                results.push(fullPath);
+            }
+        }
+    }
+    return results;
+}
+//# sourceMappingURL=resolve.js.map

package/dist/resolve.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.js","sourceRoot":"","sources":["../src/resolve.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAEjE,uDAAuD;AACvD,MAAM,oBAAoB,GAAwB,IAAI,GAAG,CAAC;IACxD,KAAK;IACL,OAAO;IACP,MAAM;IACN,OAAO;CACR,CAAC,CAAC;AAEH;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,gBAAgB,CAAC,QAAgB;IAC/C,MAAM,IAAI,GAAG,EAAE,CAAC,QAAQ,CAAC,QAAQ,EAAE,EAAE,cAAc,EAAE,KAAK,EAAE,CAAC,CAAC;IAE9D,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,MAAM,IAAI,UAAU,CAClB,UAAU,CAAC,IAAI,CAAC,SAAS,EACzB,uBAAuB,QAAQ,oBAAoB;YACjD,qDAAqD,CACxD,CAAC;IACJ,CAAC;IAED,IAAI,IAAI,CAAC,MAAM,EAAE,EAAE,CAAC;QAClB,OAAO,CAAC,QAAQ,CAAC,CAAC;IACpB,CAAC;IAED,IAAI,IAAI,CAAC,WAAW,EAAE,EAAE,CAAC;QACvB,MAAM,KAAK,GAAG,aAAa,CAAC,QAAQ,CAAC,CAAC;QACtC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACvB,MAAM,IAAI,UAAU,CAClB,UAAU,CAAC,IAAI,CAAC,SAAS,EACzB,8CAA8C,QAAQ,KAAK;gBACzD,kEAAkE,CACrE,CAAC;QACJ,CAAC;QACD,OAAO,KAAK,CAAC,IAAI,EAAE,CAAC;IACtB,CAAC;IAED,MAAM,IAAI,UAAU,CAClB,UAAU,CAAC,IAAI,CAAC,SAAS,EACzB,uBAAuB,QAAQ,gCAAgC;QAC7D,qDAAqD,CACxD,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,SAAS,aAAa,CAAC,OAAe;IACpC,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,MAAM,OAAO,GAAG,EAAE,CAAC,WAAW,CAAC,OAAO,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;IAEjE,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;QAChD,IAAI,KAAK,CAAC,WAAW,EAAE,EAAE,CAAC;YACxB,OAAO,CAAC,IAAI,CAAC,GAAG,aAAa,CAAC,QAAQ,CAAC,CAAC,CAAC;QAC3C,CAAC;aAAM,IAAI,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC;YAC1B,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,WAAW,EAAE,CAAC;YACnD,IAAI,oBAAoB,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;gBAClC,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YACzB,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/validate-stage.d.ts

@@ -5,14 +5,34 @@
  * This function will be called by the pipeline runner when executing the
  * `validate` stage of a generation run.
  */
+import type { ParsedSpecification } from './types.js';
 import type { ValidationReport } from './validation-types.js';
+/** Result of the validate stage containing both the report and parsed spec. */
+export interface ValidateStageResult {
+    /** Validation report with findings and completeness score. */
+    report: ValidationReport;
+    /** The parsed (and possibly merged) specification. */
+    parsedSpec: ParsedSpecification;
+}
 /**
- * Execute the validate pipeline stage: parse a specification file and
- * validate the result.
+ * Execute the validate pipeline stage: parse a specification path
+ * (file or directory) and validate the result.
  *
- * @param specPath - Path to the specification file
+ * @param specPath - Path to a specification file or directory
  * @returns Validation report for the parsed specification
- * @throws {@link ForgeError} if the file cannot be read or parsed
+ * @throws {@link ForgeError} if the path cannot be resolved, read, or parsed
  */
 export declare function executeValidateStage(specPath: string): ValidationReport;
+/**
+ * Execute the validate pipeline stage and return both the validation
+ * report and parsed specification.
+ *
+ * Avoids double-parsing when the caller also needs the parsed spec
+ * (e.g. the core pipeline `ValidateStage`).
+ *
+ * @param specPath - Path to a specification file or directory
+ * @returns Validation report and parsed specification
+ * @throws {@link ForgeError} if the path cannot be resolved, read, or parsed
+ */
+export declare function executeValidateStageWithSpec(specPath: string): ValidateStageResult;
 //# sourceMappingURL=validate-stage.d.ts.map

package/dist/validate-stage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validate-stage.d.ts","sourceRoot":"","sources":["../src/validate-stage.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAK9D;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,MAAM,GACf,gBAAgB,CAIlB"}
+{"version":3,"file":"validate-stage.d.ts","sourceRoot":"","sources":["../src/validate-stage.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AACtD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAK9D,+EAA+E;AAC/E,MAAM,WAAW,mBAAmB;IAClC,8DAA8D;IAC9D,MAAM,EAAE,gBAAgB,CAAC;IACzB,sDAAsD;IACtD,UAAU,EAAE,mBAAmB,CAAC;CACjC;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,MAAM,GACf,gBAAgB,CAGlB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,4BAA4B,CAC1C,QAAQ,EAAE,MAAM,GACf,mBAAmB,CAKrB"}

package/dist/validate-stage.js

@@ -6,19 +6,35 @@
  * `validate` stage of a generation run.
  */
 import { createDefaultRegistry } from './default-registry.js';
-import { parseSpec } from './loader.js';
+import { parseSpecPath } from './loader.js';
 import { validateSpec } from './validators/spec-validator.js';
 /**
- * Execute the validate pipeline stage: parse a specification file and
- * validate the result.
+ * Execute the validate pipeline stage: parse a specification path
+ * (file or directory) and validate the result.
  *
- * @param specPath - Path to the specification file
+ * @param specPath - Path to a specification file or directory
  * @returns Validation report for the parsed specification
- * @throws {@link ForgeError} if the file cannot be read or parsed
+ * @throws {@link ForgeError} if the path cannot be resolved, read, or parsed
  */
 export function executeValidateStage(specPath) {
+    const { report } = executeValidateStageWithSpec(specPath);
+    return report;
+}
+/**
+ * Execute the validate pipeline stage and return both the validation
+ * report and parsed specification.
+ *
+ * Avoids double-parsing when the caller also needs the parsed spec
+ * (e.g. the core pipeline `ValidateStage`).
+ *
+ * @param specPath - Path to a specification file or directory
+ * @returns Validation report and parsed specification
+ * @throws {@link ForgeError} if the path cannot be resolved, read, or parsed
+ */
+export function executeValidateStageWithSpec(specPath) {
     const registry = createDefaultRegistry();
-    const spec = parseSpec(specPath, registry);
-    return validateSpec(spec);
+    const parsedSpec = parseSpecPath(specPath, registry);
+    const report = validateSpec(parsedSpec);
+    return { report, parsedSpec };
 }
 //# sourceMappingURL=validate-stage.js.map

package/dist/validate-stage.js.map

@@ -1 +1 @@
-{"version":3,"file":"validate-stage.js","sourceRoot":"","sources":["../src/validate-stage.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,YAAY,EAAE,MAAM,gCAAgC,CAAC;AAE9D;;;;;;;GAOG;AACH,MAAM,UAAU,oBAAoB,CAClC,QAAgB;IAEhB,MAAM,QAAQ,GAAG,qBAAqB,EAAE,CAAC;IACzC,MAAM,IAAI,GAAG,SAAS,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;IAC3C,OAAO,YAAY,CAAC,IAAI,CAAC,CAAC;AAC5B,CAAC"}
+{"version":3,"file":"validate-stage.js","sourceRoot":"","sources":["../src/validate-stage.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,YAAY,EAAE,MAAM,gCAAgC,CAAC;AAU9D;;;;;;;GAOG;AACH,MAAM,UAAU,oBAAoB,CAClC,QAAgB;IAEhB,MAAM,EAAE,MAAM,EAAE,GAAG,4BAA4B,CAAC,QAAQ,CAAC,CAAC;IAC1D,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,4BAA4B,CAC1C,QAAgB;IAEhB,MAAM,QAAQ,GAAG,qBAAqB,EAAE,CAAC;IACzC,MAAM,UAAU,GAAG,aAAa,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;IACrD,MAAM,MAAM,GAAG,YAAY,CAAC,UAAU,CAAC,CAAC;IACxC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC;AAChC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hstm-labs/forge-spec-parser",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -16,7 +16,7 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@hstm-labs/forge-common": "0.1.2",
+    "@hstm-labs/forge-common": "0.1.3",
     "remark-frontmatter": "^5.0.0",
     "remark-gfm": "^4.0.1",
     "remark-parse": "^11.0.0",