gswd 1.0.1 → 1.1.0

package/dist/lib/compile.d.ts

@@ -0,0 +1,239 @@
+/**
+ * GSWD Compile Module — Deterministic contract doc generation
+ *
+ * Reads spec artifacts (IMAGINE.md, DECISIONS.md, SPEC.md, NFR.md, JOURNEYS.md, INTEGRATIONS.md),
+ * parses into a SpecBundle, and generates 4 GSD contract docs deterministically.
+ * Zero LLM calls, no randomness, no ordering variance.
+ *
+ * Schema: GSWD_SPEC.md Section 8.5, 9.2, 11.3
+ */
+export interface ParsedFR {
+    id: string;
+    description: string;
+    scope: 'v1' | 'v2' | 'out';
+    priority: 'P0' | 'P1' | 'P2';
+    sourceJourneys: string[];
+    acceptanceCriteria: string[];
+}
+export interface ParsedNFR {
+    id: string;
+    description: string;
+    category: string;
+    threshold: string;
+}
+export interface ParsedJourney {
+    id: string;
+    name: string;
+    type: string;
+    linkedFRs: string[];
+    linkedIntegrations: string[];
+}
+export interface ParsedIntegration {
+    id: string;
+    name: string;
+    status: string;
+    fallback: string;
+}
+export interface SpecBundle {
+    vision: string;
+    targetUser: string;
+    productDirection: string;
+    wedge: string;
+    frozenDecisions: string[];
+    successMetrics: string[];
+    outOfScope: string[];
+    risks: string[];
+    openQuestions: string[];
+    approvals: Record<string, string>;
+    frs: ParsedFR[];
+    roles: string;
+    nfrs: ParsedNFR[];
+    journeys: ParsedJourney[];
+    integrations: ParsedIntegration[];
+    projectSlug: string;
+    architectureSummary: string;
+    icpHighlights: string;
+    competitionLandscape: string;
+    gtmPositioning: string;
+    journeyInsights: string;
+}
+export declare const SCOPE_ORDER: Record<string, number>;
+export declare const PRIORITY_ORDER: Record<string, number>;
+export declare const NFR_CATEGORY_ORDER: string[];
+export declare const JOURNEY_TYPE_TO_PHASE: Record<string, number>;
+export declare const PHASE_NAMES: Record<number, string>;
+/**
+ * Sort FRs by scope (v1 first), then priority (P0 first), then numeric ID ascending.
+ */
+export declare function sortFRs(frs: ParsedFR[]): ParsedFR[];
+/**
+ * Parse FR entries from SPEC.md content.
+ * Uses ### FR-NNN heading pattern, extracts description, scope, and priority.
+ * Accepts a frToJourneys map to populate sourceJourneys.
+ */
+export declare function parseFRsFromSpec(specContent: string, frToJourneys: Map<string, Set<string>>): ParsedFR[];
+/**
+ * Parse NFR entries from NFR.md content.
+ * Extracts id, description, category (from **Category:** field), threshold (from **Threshold:** field).
+ * Sorts by NFR_CATEGORY_ORDER then numeric ID.
+ */
+export declare function parseNFRsFromContent(nfrContent: string): ParsedNFR[];
+/**
+ * Parse journey entries from JOURNEYS.md content.
+ * Extracts id, name, type, linkedFRs, linkedIntegrations.
+ * Sorts by numeric ID.
+ */
+export declare function parseJourneysFromContent(journeysContent: string): ParsedJourney[];
+/**
+ * Parse integration entries from INTEGRATIONS.md content.
+ * Extracts id, name, status, fallback.
+ * Sorts by numeric ID.
+ */
+export declare function parseIntegrationsFromContent(intContent: string): ParsedIntegration[];
+/**
+ * Build SpecBundle from file contents.
+ *
+ * Uses extractHeadingContent() for IMAGINE.md and DECISIONS.md sections.
+ * Populates frToJourneys mapping from journey parsing.
+ * If statePath provided, reads STATE.json for approvals and projectSlug.
+ * If no statePath provided, projectSlug defaults to '' and approvals defaults to {}.
+ */
+export declare function parseSpecBundle(files: {
+    imagine: string;
+    decisions: string;
+    spec: string;
+    nfr: string;
+    journeys: string;
+    integrations: string;
+    architecture?: string;
+    icp?: string;
+    competition?: string;
+    gtm?: string;
+    researchSummary?: string;
+    features?: string;
+}, statePath?: string): SpecBundle;
+/**
+ * Generate PROJECT.md content from SpecBundle.
+ *
+ * Headings: # projectSlug, ## What This Is, ## Target User, ## Problem Statement,
+ * ## Wedge / MVP Boundary, ## Success Metrics (bulleted), ## Out of Scope (bulleted).
+ * CRITICAL: No Date, Date.now(), or any time-dependent call.
+ * CRITICAL: Ends with exactly one trailing newline.
+ */
+export declare function generateProjectDoc(bundle: SpecBundle): string;
+/**
+ * Generate REQUIREMENTS.md content from SpecBundle.
+ *
+ * Structure:
+ * - # Requirements
+ * - ## Functional Requirements
+ *   - ### v1 (In Scope) — FRs sorted by priority then ID
+ *   - ### v2 (Future) — FRs sorted by priority then ID
+ * - ## Non-Functional Requirements — grouped by NFR_CATEGORY_ORDER
+ * - ## Traceability — FR to journey mapping table (v1 FRs only)
+ *
+ * CRITICAL: No Date, Date.now(), or any time-dependent call.
+ * CRITICAL: Ends with exactly one trailing newline.
+ */
+export declare function generateRequirementsDoc(bundle: SpecBundle): string;
+/**
+ * Generate ROADMAP.md content from SpecBundle.
+ *
+ * Structure:
+ * - # Roadmap
+ * - ## Overview
+ * - ## Phases
+ *   - ### Phase 1-3: journeys grouped by JOURNEY_TYPE_TO_PHASE, sorted by ID
+ *   - ### Phase 4: observability+security NFRs sorted by ID
+ *
+ * CRITICAL: Always emit all 4 phases.
+ * CRITICAL: No Date, Date.now(), or any time-dependent call.
+ * CRITICAL: Ends with exactly one trailing newline.
+ */
+export declare function generateRoadmapDoc(bundle: SpecBundle): string;
+/**
+ * Generate a GSD-format research SUMMARY.md from SpecBundle.
+ *
+ * Maps GSWD spec content to GSD research template headings.
+ * Pure function — no Date calls, no I/O.
+ * Versioned with <!-- gswd-schema-version: 1 --> header.
+ */
+export declare function generateResearchSummary(bundle: SpecBundle): string;
+export interface ValidatorFinding {
+    check: 'v1_coverage' | 'orphan_requirement' | 'integration_sanity' | 'required_headings';
+    id: string;
+    issue: string;
+}
+export interface ValidatorResult {
+    passed: boolean;
+    findings: ValidatorFinding[];
+}
+/**
+ * Validate generated contract docs against the spec bundle.
+ *
+ * 4 checks:
+ * 1. v1_coverage: Every v1 FR ID appears in the generated roadmap content
+ * 2. orphan_requirement: Every v1 FR has at least 1 source journey (sourceJourneys.length > 0)
+ * 3. integration_sanity: Every integration referenced by any journey is approved or deferred-with-fallback
+ * 4. required_headings: All 4 generated docs contain their REQUIRED_HEADINGS entries
+ */
+export declare function validateContracts(generatedDocs: {
+    project: string;
+    requirements: string;
+    roadmap: string;
+    state: string;
+}, bundle: SpecBundle): ValidatorResult;
+/**
+ * Generate STATE.md content from SpecBundle.
+ *
+ * Structure:
+ * - # Project State
+ * - ## Frozen Decisions (numbered list)
+ * - ## Approvals (key-value list from bundle.approvals)
+ * - ## Open Questions (bulleted)
+ * - ## Risks (bulleted)
+ *
+ * CRITICAL: No Date, Date.now(), or any time-dependent call.
+ * CRITICAL: Ends with exactly one trailing newline.
+ */
+export declare function generateStateDoc(bundle: SpecBundle): string;
+/**
+ * Read all 6 spec artifact files from a planning directory.
+ * Also reads research files from .planning/research/ directory.
+ * Returns a content map keyed by artifact type.
+ * Missing files return empty string (does not throw).
+ */
+export declare function readSpecArtifacts(planningDir: string): Record<string, string>;
+export interface CompileWorkflowResult {
+    passed: boolean;
+    error?: string;
+    validatorResult?: ValidatorResult;
+    filesWritten: string[];
+    generated?: {
+        project: string;
+        requirements: string;
+        roadmap: string;
+        state: string;
+        researchSummary: string;
+    };
+}
+/**
+ * Full compile workflow orchestrator.
+ *
+ * Steps:
+ *   1. Check audit gate via checkAuditGate(). If false, return early with error.
+ *   2. Update stage status: compile -> in_progress.
+ *   3. Read spec artifacts from planningDir.
+ *   4. Parse into SpecBundle.
+ *   5. Generate all 4 contract docs (pure functions, no I/O).
+ *   6. Run validator: validateContracts().
+ *   7. If validator FAIL: update state -> fail. Return without writing files.
+ *   8. Write all 4 docs atomically via safeWriteFile().
+ *   9. Update state: stage_status.compile = 'done', stage = 'compile'.
+ *  10. Write checkpoint.
+ *  11. Return result with passed=true and filesWritten list.
+ */
+export declare function runCompileWorkflow(options: {
+    planningDir: string;
+    statePath: string;
+}): CompileWorkflowResult;