spec-gen-cli 1.0.0

package/dist/core/generator/prompts.js

@@ -0,0 +1,212 @@
+/**
+ * Prompt templates for each generation stage.
+ * These are used by the stage functions to construct LLM requests.
+ */
+export const PROMPTS = {
+    stage1_survey: `You are a senior software architect performing a codebase audit.
+Your task is to categorize this project based on the analysis data provided.
+
+Respond with a JSON object containing:
+- projectCategory: One of ["web-frontend", "web-backend", "api-service", "cli-tool", "library", "mobile-app", "desktop-app", "data-pipeline", "ml-service", "monorepo", "other"]
+- primaryLanguage: The main language
+- frameworks: Array of detected frameworks
+- architecturePattern: One of ["layered", "hexagonal", "microservices", "monolith", "serverless", "event-driven", "mvc", "other"]
+- domainSummary: One sentence describing what this system does
+- suggestedDomains: Array of domain names for OpenSpec specs (e.g., ["user", "order", "auth", "api"])
+- confidence: 0-1 score of how confident you are
+- schemaFiles: Array of file paths (from the provided file list) that define data models, types, entities, or interfaces — these will be used for entity extraction. Include files regardless of their name, based on their content role.
+- serviceFiles: Array of file paths containing business logic, services, processors, analyzers, pipelines, or domain operations — used for service analysis. Do not filter by name conventions; look at what the file does.
+- apiFiles: Array of file paths that expose public interfaces: HTTP routes, CLI command handlers, GraphQL resolvers, message consumers, or external-facing APIs.
+
+For schemaFiles/serviceFiles/apiFiles: use the exact file paths from the provided analysis. Return [] if none apply.
+
+Example output:
+{
+  "projectCategory": "api-service",
+  "primaryLanguage": "TypeScript",
+  "frameworks": ["Express", "Prisma"],
+  "architecturePattern": "layered",
+  "domainSummary": "REST API managing e-commerce orders and inventory.",
+  "suggestedDomains": ["order", "product", "auth"],
+  "confidence": 0.85,
+  "schemaFiles": ["src/models/order.ts", "src/types/product.ts"],
+  "serviceFiles": ["src/services/order-service.ts", "src/core/inventory.ts"],
+  "apiFiles": ["src/routes/orders.ts", "src/cli/commands/create.ts"]
+}
+
+Respond ONLY with valid JSON.`,
+    stage2_entities: (projectCategory, frameworks) => `You are analyzing the core data models of a ${projectCategory} built with ${frameworks.join(', ')}.
+
+For each entity you identify, extract in OpenSpec format:
+- name: The entity name (e.g., "User", "Order")
+- description: What this entity represents in the business domain
+- properties: Array of {name, type, description, required}
+- relationships: Array of {targetEntity, type, description}
+- validations: Array of validation rules as strings (these become Requirements)
+- scenarios: Array of {name, given, when, then, and?} - observable behaviors in Given/When/Then format
+
+Focus on BUSINESS entities, not framework internals.
+Be precise - only include what you can verify from the code.
+
+Example output:
+[{
+  "name": "Order",
+  "description": "Represents a customer purchase transaction.",
+  "properties": [
+    {"name": "id", "type": "string", "description": "Unique identifier", "required": true},
+    {"name": "status", "type": "OrderStatus", "description": "Current lifecycle state", "required": true}
+  ],
+  "relationships": [{"targetEntity": "User", "type": "belongs-to", "description": "Order belongs to a customer"}],
+  "validations": ["Total must be positive", "Status transitions: pending → confirmed → shipped"],
+  "scenarios": [{"name": "Place order", "given": "User with items in cart", "when": "submitOrder() is called", "then": "Order created with status 'pending' and inventory reserved"}],
+  "location": ""
+}]
+
+Respond with a JSON array of entities. Respond ONLY with valid JSON.`,
+    stage3_services: (projectCategory, entities, suggestedDomains) => `You are analyzing the logic and processing layer of a ${projectCategory}.
+
+Known entities: ${entities.join(', ')}
+Available domains: ${suggestedDomains.join(', ')}
+
+For each service/module, identify:
+- name: Service name
+- purpose: What capability or responsibility it encapsulates
+- operations: Array of {name, description, inputs, outputs, scenarios, functionName} - key operations/methods that become Requirements with Scenarios. Cover all meaningful operations that represent distinct business behaviors.
+  - operations[].functionName: The exact function or method name as written in the source code that implements this operation (e.g. "runStage2", "buildSpecMap"). Leave empty string if uncertain.
+- dependencies: Array of other services/repositories it uses
+- sideEffects: Array of external interactions (file I/O, network calls, database, queues, etc.)
+- domain: Which domain OWNS this service (where it lives in the codebase, not who uses it) — use ONLY one of the available domains listed above
+
+Focus on WHAT the service does, not HOW it's implemented.
+Express operations as requirements (SHALL/MUST/SHOULD) with testable scenarios.
+
+Example output:
+[{
+  "name": "OrderService",
+  "purpose": "Manages order lifecycle: placement, validation, and fulfillment.",
+  "operations": [
+    {
+      "name": "placeOrder",
+      "description": "Validates cart contents and creates a new order record.",
+      "inputs": ["userId: string", "items: CartItem[]"],
+      "outputs": ["orderId: string"],
+      "functionName": "placeOrder",
+      "scenarios": [{"name": "Valid order", "given": "In-stock items in cart", "when": "placeOrder is called", "then": "Order persisted and inventory reserved"}]
+    }
+  ],
+  "dependencies": ["InventoryService", "OrderRepository"],
+  "sideEffects": ["Writes to orders table", "Sends confirmation email via queue"],
+  "domain": "order"
+}]
+
+Respond with a JSON array of services. Respond ONLY with valid JSON.`,
+    stage4_api: `Extract the public API surface of this application.
+
+For each endpoint/interface, structure as:
+- method: HTTP method or interface type
+- path: Route path or interface signature
+- purpose: What it does (becomes requirement description)
+- authentication: Required auth (if detectable)
+- requestSchema: Expected input as JSON object
+- responseSchema: Expected output as JSON object
+- scenarios: Array of {name, given, when, then, and?} - example request/response flows
+- relatedEntity: Which domain entity it operates on
+
+Example output:
+[{
+  "method": "POST",
+  "path": "/api/orders",
+  "purpose": "Create a new order from the current cart.",
+  "authentication": "Bearer JWT",
+  "requestSchema": {"userId": "string", "items": "CartItem[]"},
+  "responseSchema": {"orderId": "string", "status": "pending"},
+  "scenarios": [{"name": "Create order", "given": "Authenticated user with valid cart", "when": "POST /api/orders is called", "then": "201 Created with orderId in response body"}],
+  "relatedEntity": "Order"
+}]
+
+Respond with a JSON array of endpoints. Respond ONLY with valid JSON.`,
+    stage5_architecture: (survey) => `Based on the analysis data, synthesize a complete architecture overview for OpenSpec.
+
+Project context: ${survey.domainSummary}
+Architecture pattern: ${survey.architecturePattern}
+Domains: ${survey.suggestedDomains.join(', ')}
+
+Include:
+- systemPurpose: 2-3 sentences on what this system does and why
+- architectureStyle: The overall architecture pattern with justification
+- layerMap: Array of {name, purpose, components} - how code is organized
+- dataFlow: How data moves through the system (entry to persistence) as a string
+- integrations: Array of external systems this interacts with
+- securityModel: Authentication/authorization approach as a string
+- keyDecisions: Array of observable architectural decisions as strings
+
+Express each key architectural aspect clearly.
+Base all conclusions on the code evidence provided.
+Where uncertain, say so explicitly.
+
+Example output:
+{
+  "systemPurpose": "A REST API for e-commerce order management. It allows customers to browse products, place orders, and track fulfillment.",
+  "architectureStyle": "Layered architecture: HTTP routes → service layer → repository pattern over PostgreSQL.",
+  "layerMap": [
+    {"name": "API", "purpose": "HTTP routing and input validation", "components": ["routes/orders.ts", "routes/products.ts"]},
+    {"name": "Service", "purpose": "Business logic and orchestration", "components": ["services/order-service.ts"]}
+  ],
+  "dataFlow": "HTTP request → route handler → service → repository → PostgreSQL; async email notifications via Redis queue",
+  "integrations": ["PostgreSQL", "Redis", "SendGrid"],
+  "securityModel": "JWT Bearer tokens issued at login; route middleware enforces authentication on all /api/* routes",
+  "keyDecisions": ["Use Prisma ORM for type-safe database access", "Redis queue for async email notifications to avoid request latency"]
+}
+
+Respond with a JSON object. Respond ONLY with valid JSON.`,
+    stage6_adr: (architecture) => `You are a senior software architect creating Architecture Decision Records (ADRs).
+
+For each key decision listed below, produce a complete ADR with:
+- id: Sequential like "ADR-001", "ADR-002", etc.
+- title: The decision as a clear statement (e.g., "Use TypeORM for database access")
+- status: "accepted" (these are observed decisions already implemented in the code)
+- context: 2-3 sentences on why this decision was needed
+- decision: 1-2 sentences clearly stating what was decided
+- consequences: Array of 2-4 consequences (include both positive and negative)
+- alternatives: Array of 1-3 alternatives that could have been chosen instead
+- relatedLayers: Array of architecture layer names affected (from: ${architecture.layerMap.map(l => l.name).join(', ')})
+- relatedDomains: Array of domain names affected
+
+Architecture context:
+- System purpose: ${architecture.systemPurpose}
+- Architecture style: ${architecture.architectureStyle}
+- Layers: ${architecture.layerMap.map(l => `${l.name} (${l.purpose})`).join(', ')}
+- Data flow: ${architecture.dataFlow}
+- Security model: ${architecture.securityModel}
+- External integrations: ${architecture.integrations.join(', ') || 'None'}
+
+Key decisions to expand into full ADRs:
+${architecture.keyDecisions.map((d, i) => `${i + 1}. ${d}`).join('\n')}
+
+Base all conclusions on the code evidence provided. Where uncertain, say so explicitly.
+Respond with a JSON array of ADR objects. Respond ONLY with valid JSON.`,
+    stage3_subspec_system: `You are generating sub-specifications for the logical blocks of an orchestrator function.
+
+For each sub-block provided, generate a focused specification:
+- name: short camelCase identifier (e.g. "entityExtraction", "schemaValidation")
+- callee: exact function/method name as written in source code
+- purpose: one sentence describing what this block does
+- operations: array of {name, description, inputs, outputs, scenarios, functionName}
+  - Express operations as requirements using SHALL/MUST/SHOULD keywords
+  - Include at least one testable scenario per operation
+
+Focus on WHAT each block does, not HOW it is implemented.
+Respond ONLY with a valid JSON array of sub-specification objects.`,
+    stage3_subspec: (orchestratorName, orchestratorPurpose, callees) => `Orchestrator function: ${orchestratorName}
+Purpose: ${orchestratorPurpose}
+
+Sub-blocks to specify:
+${callees.map((c, i) => `${i + 1}. ${c.name}` +
+        (c.signature ? `\n   Signature: ${c.signature}` : '') +
+        (c.docstring ? `\n   Doc: ${c.docstring}` : '') +
+        (c.subcallees.length > 0 ? `\n   Calls: ${c.subcallees.join(', ')}` : '')).join('\n')}
+
+Generate one sub-specification per sub-block listed above.
+Respond ONLY with a valid JSON array of {name, callee, purpose, operations} objects.`,
+};
+//# sourceMappingURL=prompts.js.map

package/dist/core/generator/prompts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompts.js","sourceRoot":"","sources":["../../../src/core/generator/prompts.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,MAAM,CAAC,MAAM,OAAO,GAAG;IACrB,aAAa,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;8BA+Ba;IAE5B,eAAe,EAAE,CAAC,eAAuB,EAAE,UAAoB,EAAE,EAAE,CAAC,+CAA+C,eAAe,eAAe,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;qEA2BnG;IAEnE,eAAe,EAAE,CAAC,eAAuB,EAAE,QAAkB,EAAE,gBAA0B,EAAE,EAAE,CAAC,yDAAyD,eAAe;;kBAEtJ,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC;qBAChB,gBAAgB,CAAC,IAAI,CAAC,IAAI,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qEAiCqB;IAEnE,UAAU,EAAE;;;;;;;;;;;;;;;;;;;;;;;;sEAwBwD;IAEpE,mBAAmB,EAAE,CAAC,MAA0F,EAAE,EAAE,CAAC;;mBAEpG,MAAM,CAAC,aAAa;wBACf,MAAM,CAAC,mBAAmB;WACvC,MAAM,CAAC,gBAAgB,CAAC,IAAI,CAAC,IAAI,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;0DA6Ba;IAExD,UAAU,EAAE,CAAC,YAA0M,EAAE,EAAE,CAAC;;;;;;;;;;qEAUzJ,YAAY,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;;;;oBAIlG,YAAY,CAAC,aAAa;wBACtB,YAAY,CAAC,iBAAiB;YAC1C,YAAY,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,OAAO,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;eAClE,YAAY,CAAC,QAAQ;oBAChB,YAAY,CAAC,aAAa;2BACnB,YAAY,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,MAAM;;;EAGvE,YAAY,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;;;wEAGE;IAEtE,qBAAqB,EAAE;;;;;;;;;;;mEAW0C;IAEjE,cAAc,EAAE,CACd,gBAAwB,EACxB,mBAA2B,EAC3B,OAA8F,EAC9F,EAAE,CAAC,0BAA0B,gBAAgB;WACtC,mBAAmB;;;EAG5B,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CACrB,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE;QACrB,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,mBAAmB,CAAC,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACrD,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC/C,CAAC,CAAC,CAAC,UAAU,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAC1E,CAAC,IAAI,CAAC,IAAI,CAAC;;;qFAGyE;CACpF,CAAC"}

package/dist/core/generator/spec-pipeline.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Spec Generation Pipeline
+ *
+ * Orchestrates the multi-step LLM process to generate accurate specifications
+ * in OpenSpec format from code analysis.
+ */
+import type { LLMService } from '../services/llm-service.js';
+import type { RepoStructure, LLMContext } from '../analyzer/artifact-generator.js';
+import type { DependencyGraphResult } from '../analyzer/dependency-graph.js';
+import type { PipelineResult, StageResult, PipelineOptions, PipelineContext, ServiceSubSpec } from '../../types/pipeline.js';
+export type { ProjectCategory, ArchitecturePattern, ProjectSurveyResult, EntityProperty, EntityRelationship, Scenario, ExtractedEntity, ServiceOperation, ServiceSubSpec, ExtractedService, ExtractedEndpoint, ArchitectureLayer, ArchitectureSynthesis, EnrichedADR, PipelineResult, StageResult, PipelineOptions, PipelineContext, } from '../../types/pipeline.js';
+/**
+ * Spec Generation Pipeline
+ */
+export declare class SpecGenerationPipeline implements PipelineContext {
+    llm: LLMService;
+    options: Required<Omit<PipelineOptions, 'progress'>>;
+    private progress?;
+    /** Set at the start of run() and used by stage methods for graph-based prompts */
+    private currentLLMContext?;
+    constructor(llm: LLMService, options: PipelineOptions);
+    /**
+     * Run the complete pipeline
+     */
+    run(repoStructure: RepoStructure, llmContext: LLMContext, depGraph?: DependencyGraphResult): Promise<PipelineResult>;
+    /**
+     * Check if a stage should run
+     */
+    private shouldRunStage;
+    /**
+     * Split file content into chunks, breaking only on blank lines (function/class boundaries).
+     * A chunk is emitted when its size exceeds maxChars and a blank line is encountered.
+     * overlapLines trailing lines from the previous chunk are prepended to the next one,
+     * preserving context (e.g. class declaration visible when processing its methods).
+     */
+    chunkContent(content: string, maxChars: number, overlapLines?: number): string[];
+    /**
+     * For a large file, try to build a graph-based prompt section.
+     * Returns null when no call graph data is available or the file has no god functions
+     * (caller should fall back to raw source chunking).
+     *
+     * When file content is provided, appends a stripped skeleton when it achieves
+     * a meaningful size reduction (≥ 20%), giving the LLM both topology and
+     * internal control-flow structure.
+     */
+    graphPromptFor(filePath: string, content?: string): string | null;
+    /**
+     * Generate sub-specifications for the direct callees of god functions in a file.
+     * Makes a single batched LLM call covering all callees at once.
+     * Returns [] when no graph data or no god functions are found.
+     */
+    generateSubSpecs(filePath: string, parentName: string, parentPurpose: string): Promise<ServiceSubSpec[]>;
+    /**
+     * Get schema files from LLM context
+     */
+    private getSchemaFiles;
+    /**
+     * Get service files from LLM context
+     */
+    private getServiceFiles;
+    /**
+     * Get API files from LLM context
+     */
+    private getApiFiles;
+    /**
+     * Resolve file paths identified by Stage 1 LLM to actual file content.
+     * First looks in phase2_deep (already in memory); if not found and rootPath is set,
+     * reads the file from disk so that files outside the top-20 scored set can still
+     * be analyzed in later stages.
+     * Falls back to the provided heuristic list if no paths resolve.
+     */
+    private resolveFiles;
+    /**
+     * Get default survey when stage is skipped
+     */
+    private getDefaultSurvey;
+    /**
+     * Get default architecture when stage is skipped
+     */
+    private getDefaultArchitecture;
+    /**
+     * Save intermediate result
+     */
+    saveResult(name: string, data: unknown): Promise<void>;
+    /**
+     * Load previous stage result (for resume)
+     */
+    loadStageResult<T>(stage: string): Promise<StageResult<T> | null>;
+}
+/**
+ * Run the spec generation pipeline
+ */
+export declare function runSpecGenerationPipeline(llm: LLMService, repoStructure: RepoStructure, llmContext: LLMContext, options: PipelineOptions, depGraph?: DependencyGraphResult): Promise<PipelineResult>;
+//# sourceMappingURL=spec-pipeline.d.ts.map

package/dist/core/generator/spec-pipeline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spec-pipeline.d.ts","sourceRoot":"","sources":["../../../src/core/generator/spec-pipeline.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAC7D,OAAO,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,mCAAmC,CAAC;AAGnF,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,iCAAiC,CAAC;AAS7E,OAAO,KAAK,EAQV,cAAc,EACd,WAAW,EACX,eAAe,EACf,eAAe,EACf,cAAc,EACf,MAAM,yBAAyB,CAAC;AAGjC,YAAY,EACV,eAAe,EACf,mBAAmB,EACnB,mBAAmB,EACnB,cAAc,EACd,kBAAkB,EAClB,QAAQ,EACR,eAAe,EACf,gBAAgB,EAChB,cAAc,EACd,gBAAgB,EAChB,iBAAiB,EACjB,iBAAiB,EACjB,qBAAqB,EACrB,WAAW,EACX,cAAc,EACd,WAAW,EACX,eAAe,EACf,eAAe,GAChB,MAAM,yBAAyB,CAAC;AAMjC;;GAEG;AACH,qBAAa,sBAAuB,YAAW,eAAe;IAC5D,GAAG,EAAE,UAAU,CAAC;IAChB,OAAO,EAAE,QAAQ,CAAC,IAAI,CAAC,eAAe,EAAE,UAAU,CAAC,CAAC,CAAC;IACrD,OAAO,CAAC,QAAQ,CAAC,CAAoB;IACrC,kFAAkF;IAClF,OAAO,CAAC,iBAAiB,CAAC,CAAa;gBAE3B,GAAG,EAAE,UAAU,EAAE,OAAO,EAAE,eAAe;IAcrD;;OAEG;IACG,GAAG,CACP,aAAa,EAAE,aAAa,EAC5B,UAAU,EAAE,UAAU,EACtB,QAAQ,CAAC,EAAE,qBAAqB,GAC/B,OAAO,CAAC,cAAc,CAAC;IAyL1B;;OAEG;IACH,OAAO,CAAC,cAAc;IAetB;;;;;OAKG;IACH,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,YAAY,SAAK,GAAG,MAAM,EAAE;IA6B5E;;;;;;;;OAQG;IACH,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAuBjE;;;;OAIG;IACG,gBAAgB,CACpB,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,EAClB,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,cAAc,EAAE,CAAC;IAwE5B;;OAEG;IACH,OAAO,CAAC,cAAc;IAgBtB;;OAEG;IACH,OAAO,CAAC,eAAe;IAiBvB;;OAEG;IACH,OAAO,CAAC,WAAW;IAgBnB;;;;;;OAMG;YACW,YAAY;IAuC1B;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAexB;;OAEG;IACH,OAAO,CAAC,sBAAsB;IAY9B;;OAEG;IACG,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAM5D;;OAEG;IACG,eAAe,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;CASxE;AAMD;;GAEG;AACH,wBAAsB,yBAAyB,CAC7C,GAAG,EAAE,UAAU,EACf,aAAa,EAAE,aAAa,EAC5B,UAAU,EAAE,UAAU,EACtB,OAAO,EAAE,eAAe,EACxB,QAAQ,CAAC,EAAE,qBAAqB,GAC/B,OAAO,CAAC,cAAc,CAAC,CAGzB"}