@hstm-labs/forge-verifier 0.1.11

package/dist/verify-stage.js

@@ -0,0 +1,155 @@
+/**
+ * VerifyStage — pipeline stage that verifies compliance of generated
+ * artifacts against specification requirements.
+ *
+ * This stage does NOT require an LLM. It runs after the review stage
+ * and produces a {@link ComplianceReport} with requirement coverage,
+ * gap analysis, and review finding incorporation.
+ */
+import { join, dirname } from 'node:path';
+import { writeFileSync, mkdirSync } from 'node:fs';
+import { ForgeError, ErrorCodes, hashContent } from '@hstm-labs/forge-common';
+import { loadProfile } from '@hstm-labs/forge-profiles';
+import { getOpinionatedStacks } from './tech-stack-resolver.js';
+import { resolveTechStack } from './tech-stack-resolver.js';
+import { mapRequirementsToArtifacts } from './requirement-mapper.js';
+import { calculateCoverage } from './coverage-calculator.js';
+import { detectGaps } from './gap-detector.js';
+import { incorporateReviewFindings } from './review-incorporator.js';
+import { buildComplianceReport } from './compliance-builder.js';
+// ---------------------------------------------------------------------------
+// Stage
+// ---------------------------------------------------------------------------
+/**
+ * Pipeline stage that verifies spec-to-artifact compliance.
+ *
+ * Produces a {@link ComplianceReport} with requirement mapping, coverage
+ * scoring, gap analysis, and review finding incorporation. The report is
+ * written as `compliance-report.json` and stored in `data.compliance`.
+ *
+ * @example
+ * ```ts
+ * const stage = new VerifyStage();
+ * const output = await stage.execute(input, context);
+ * const report = output.data?.compliance as ComplianceReport;
+ * ```
+ */
+export class VerifyStage {
+    name = 'verify';
+    dependsOn = ['review'];
+    requiresLLM = false;
+    /**
+     * Execute the compliance verification stage.
+     *
+     * @param input - Input from prior stages (keyed by stage name)
+     * @param context - Pipeline context with config, workspace, and runId
+     * @returns Stage output with compliance report artifact and ComplianceReport in data
+     * @throws {ForgeError} FORGE-PIPE-001 if validate stage output is missing
+     */
+    async execute(input, context) {
+        // 1. Get parsed spec from validate stage
+        const validateOutput = input['validate'];
+        if (validateOutput === undefined) {
+            throw new ForgeError(ErrorCodes.PIPE.STAGE_FAILURE, "Verify stage requires 'validate' stage output, but it was not found. " +
+                'Ensure the validate stage runs before the verify stage.');
+        }
+        const parsedSpec = validateOutput.data?.['parsedSpec'];
+        if (parsedSpec === undefined) {
+            throw new ForgeError(ErrorCodes.PIPE.STAGE_FAILURE, 'Validate stage did not produce a parsed specification in its output data.');
+        }
+        // 2. Collect all generation stage outputs
+        const generationOutputs = this.collectGenerationOutputs(input);
+        // 3. Get review report (optional — may be undefined if review was skipped)
+        const reviewReport = input['review']?.data?.['review'];
+        // 4. Map requirements to artifacts
+        const coverageResults = mapRequirementsToArtifacts(parsedSpec.requirements, parsedSpec.entities, generationOutputs);
+        // 5. Calculate coverage score
+        const { score, coveredCount, totalCount } = calculateCoverage(coverageResults);
+        // 6. Detect gaps
+        const gaps = detectGaps(coverageResults, parsedSpec.requirements);
+        // 7. Incorporate review findings
+        const reviewFindings = incorporateReviewFindings(reviewReport);
+        // 8. Resolve API type and tech stack (when spec does not define them)
+        const profile = loadProfile(context.config.profileName, context.workspace.rootDir);
+        const techResolution = resolveTechStack(parsedSpec, context.config, profile);
+        const stacksList = getOpinionatedStacks().map((s) => ({
+            id: s.id,
+            label: s.label,
+            apiType: s.apiType,
+            description: s.description,
+        }));
+        // 9. Build compliance report
+        const report = buildComplianceReport({
+            runId: context.runId,
+            coverage: coverageResults,
+            gaps,
+            reviewFindings,
+            totalRequirements: totalCount,
+            coveredRequirements: coveredCount,
+            score,
+        });
+        // 10. Write compliance-report.json and tech-stack-resolution.json to output directory
+        const outputDir = join(context.workspace.forgeDir, 'runs', context.runId, 'stages', 'verify', 'artifacts');
+        const reportJson = JSON.stringify(report, null, 2);
+        const reportPath = 'compliance-report.json';
+        const fullPath = join(outputDir, reportPath);
+        mkdirSync(dirname(fullPath), { recursive: true });
+        writeFileSync(fullPath, reportJson, 'utf-8');
+        const techResolutionPayload = {
+            resolvedApiType: techResolution.resolvedApiType,
+            resolvedTechStack: techResolution.resolvedTechStack,
+            clarificationSuggested: techResolution.clarificationSuggested,
+            suggestedConfigSnippet: techResolution.suggestedConfigSnippet,
+            opinionatedStacks: stacksList,
+        };
+        const techResolutionJson = JSON.stringify(techResolutionPayload, null, 2);
+        const techResolutionPath = 'tech-stack-resolution.json';
+        writeFileSync(join(outputDir, techResolutionPath), techResolutionJson, 'utf-8');
+        const artifacts = [
+            {
+                filePath: reportPath,
+                content: reportJson,
+                contentHash: hashContent(reportJson),
+                sizeBytes: Buffer.byteLength(reportJson, 'utf-8'),
+            },
+            {
+                filePath: techResolutionPath,
+                content: techResolutionJson,
+                contentHash: hashContent(techResolutionJson),
+                sizeBytes: Buffer.byteLength(techResolutionJson, 'utf-8'),
+            },
+        ];
+        // 11. Return stage output
+        return {
+            artifacts,
+            data: {
+                compliance: report,
+                resolvedApiType: techResolution.resolvedApiType,
+                resolvedTechStack: techResolution.resolvedTechStack,
+                clarificationSuggested: techResolution.clarificationSuggested,
+            },
+        };
+    }
+    // -------------------------------------------------------------------------
+    // Private helpers
+    // -------------------------------------------------------------------------
+    /**
+     * Collect generation stage outputs from pipeline input.
+     *
+     * Gracefully handles missing stages — each output is optional.
+     *
+     * @param input - Pipeline stage input map
+     * @returns Collected generation stage outputs
+     */
+    collectGenerationOutputs(input) {
+        return {
+            architecture: input['architect']?.data?.['architecture'],
+            api: input['services-generate']?.data?.['api'],
+            ui: input['apps-generate']?.data?.['ui'],
+            infra: input['infra-generate']?.data?.['infra'],
+            security: input['security-generate']?.data?.['security'],
+            seedData: input['seed-data']?.data?.['seedData'],
+        };
+    }
+}
+//# sourceMappingURL=verify-stage.js.map

package/dist/verify-stage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify-stage.js","sourceRoot":"","sources":["../src/verify-stage.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@hstm-labs/forge-verifier",
+  "version": "0.1.11",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@hstm-labs/forge-common": "0.1.11",
+    "@hstm-labs/forge-core": "0.1.11",
+    "@hstm-labs/forge-architect": "0.1.11",
+    "@hstm-labs/forge-services-generator": "0.1.11",
+    "@hstm-labs/forge-apps-generator": "0.1.11",
+    "@hstm-labs/forge-infra-generator": "0.1.11",
+    "@hstm-labs/forge-security-generator": "0.1.11",
+    "@hstm-labs/forge-seed-data": "0.1.11",
+    "@hstm-labs/forge-reviewer": "0.1.11",
+    "@hstm-labs/forge-spec-parser": "0.1.11",
+    "@hstm-labs/forge-profiles": "0.1.11",
+    "@hstm-labs/forge-templates": "0.1.11"
+  }
+}