specweave 0.30.16 → 0.30.17

package/dist/src/utils/llm-json-extractor.js

@@ -0,0 +1,336 @@
+/**
+ * LLM JSON Extractor - Robust JSON parsing from LLM responses
+ *
+ * Handles common LLM output patterns:
+ * - "Based on the analysis, here is the JSON: {...}"
+ * - "```json\n{...}\n```"
+ * - "Here's what I found:\n{...}"
+ * - Pure JSON responses
+ *
+ * Features:
+ * - 4-level extraction strategy (pure -> code blocks -> regex -> array)
+ * - Input sanitization (BOM, trailing commas)
+ * - Schema-aware correction prompts
+ * - Required field validation
+ * - Retry-with-correction prompting
+ */
+import { consoleLogger } from './logger.js';
+/**
+ * Extract JSON from an LLM response that may contain prose
+ *
+ * Tries multiple extraction strategies in order:
+ * 1. Direct parse (pure JSON)
+ * 2. Remove markdown code blocks
+ * 3. Find JSON object via regex (handles prose around JSON)
+ * 4. Find JSON array via regex
+ */
+export function extractJson(response, options = {}) {
+    const logger = options.logger ?? consoleLogger;
+    const result = {
+        success: false,
+        data: null,
+        rawResponse: response,
+        extractedJson: null,
+        error: null,
+        extractionMethod: 'failed'
+    };
+    if (!response || typeof response !== 'string') {
+        result.error = 'Empty or invalid response';
+        return result;
+    }
+    // Sanitize input: strip BOM and normalize
+    const sanitized = sanitizeInput(response);
+    const trimmed = sanitized.trim();
+    // Strategy 1: Direct parse (pure JSON) - with trailing comma fallback
+    const directParsed = tryParseJson(trimmed);
+    if (directParsed !== null && validateParsedJson(directParsed, options.requiredFields)) {
+        result.success = true;
+        result.data = directParsed;
+        result.extractedJson = trimmed;
+        result.extractionMethod = 'pure';
+        return result;
+    }
+    // Strategy 2: Remove markdown code blocks
+    const codeBlockPatterns = [
+        /^```(?:json)?\s*\n?([\s\S]*?)\n?```$/m, // Full code block
+        /```(?:json)?\s*\n?([\s\S]*?)\n?```/, // Code block anywhere
+    ];
+    for (const pattern of codeBlockPatterns) {
+        const match = trimmed.match(pattern);
+        if (match?.[1]) {
+            const codeBlockContent = match[1].trim();
+            const parsed = tryParseJson(codeBlockContent);
+            if (parsed !== null && validateParsedJson(parsed, options.requiredFields)) {
+                result.success = true;
+                result.data = parsed;
+                result.extractedJson = codeBlockContent;
+                result.extractionMethod = 'code-block';
+                return result;
+            }
+        }
+    }
+    // Strategy 3: Find JSON object via regex (handles "Based on... here is: {...}")
+    // Find the outermost balanced braces
+    const jsonObject = findBalancedJson(trimmed, '{', '}');
+    if (jsonObject) {
+        const parsed = tryParseJson(jsonObject);
+        if (parsed !== null && validateParsedJson(parsed, options.requiredFields)) {
+            result.success = true;
+            result.data = parsed;
+            result.extractedJson = jsonObject;
+            result.extractionMethod = 'regex';
+            return result;
+        }
+    }
+    // Strategy 4: Find JSON array
+    const jsonArray = findBalancedJson(trimmed, '[', ']');
+    if (jsonArray) {
+        const parsed = tryParseJson(jsonArray);
+        if (parsed !== null && validateParsedJson(parsed, options.requiredFields)) {
+            result.success = true;
+            result.data = parsed;
+            result.extractedJson = jsonArray;
+            result.extractionMethod = 'regex';
+            return result;
+        }
+    }
+    // All strategies failed
+    result.error = generateErrorMessage(trimmed);
+    logger.debug?.(`JSON extraction failed: ${result.error}`);
+    return result;
+}
+/**
+ * Find balanced JSON by matching opening/closing brackets
+ * Handles nested structures and strings with escaped characters
+ */
+function findBalancedJson(text, openChar, closeChar) {
+    const startIdx = text.indexOf(openChar);
+    if (startIdx === -1)
+        return null;
+    let depth = 0;
+    let inString = false;
+    let escapeNext = false;
+    for (let i = startIdx; i < text.length; i++) {
+        const char = text[i];
+        if (escapeNext) {
+            escapeNext = false;
+            continue;
+        }
+        if (char === '\\' && inString) {
+            escapeNext = true;
+            continue;
+        }
+        if (char === '"') {
+            inString = !inString;
+            continue;
+        }
+        if (!inString) {
+            if (char === openChar) {
+                depth++;
+            }
+            else if (char === closeChar) {
+                depth--;
+                if (depth === 0) {
+                    return text.slice(startIdx, i + 1);
+                }
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Validate parsed JSON has required fields
+ */
+function validateParsedJson(parsed, requiredFields) {
+    if (!parsed || typeof parsed !== 'object') {
+        return false;
+    }
+    if (!requiredFields || requiredFields.length === 0) {
+        return true;
+    }
+    const obj = parsed;
+    return requiredFields.every(field => field in obj);
+}
+/**
+ * Sanitize LLM response input before JSON extraction
+ *
+ * Handles common issues:
+ * - UTF-8 BOM character
+ * - Trailing commas in arrays/objects (common LLM mistake)
+ */
+function sanitizeInput(input) {
+    // Strip UTF-8 BOM if present
+    let sanitized = input.replace(/^\uFEFF/, '');
+    return sanitized;
+}
+/**
+ * Clean trailing commas from JSON string
+ * Called after extraction but before parsing
+ */
+function cleanTrailingCommas(json) {
+    // Remove trailing commas before ] or }
+    // Be careful not to modify strings - only do this on extracted JSON
+    return json.replace(/,\s*([}\]])/g, '$1');
+}
+/**
+ * Try to parse JSON with trailing comma cleanup as fallback
+ */
+function tryParseJson(json) {
+    try {
+        return JSON.parse(json);
+    }
+    catch {
+        // Try with trailing comma cleanup
+        try {
+            const cleaned = cleanTrailingCommas(json);
+            return JSON.parse(cleaned);
+        }
+        catch {
+            return null;
+        }
+    }
+}
+/**
+ * Generate helpful error message for failed extraction
+ */
+function generateErrorMessage(response) {
+    const preview = response.slice(0, 100).replace(/\n/g, ' ');
+    if (response.toLowerCase().startsWith('based on')) {
+        return `Model returned prose instead of JSON. Response starts with: "${preview}..."`;
+    }
+    if (response.toLowerCase().includes('i apologize') || response.toLowerCase().includes('sorry')) {
+        return `Model returned an apology/error message instead of JSON. Response starts with: "${preview}..."`;
+    }
+    if (response.includes('{')) {
+        return `Found JSON-like content but parsing failed. Response starts with: "${preview}..."`;
+    }
+    return `No valid JSON found in response. Response starts with: "${preview}..."`;
+}
+/**
+ * Generate a correction prompt for retry after failed JSON extraction
+ *
+ * @param originalPrompt - The original prompt that was sent
+ * @param failedResponse - The failed response from the LLM
+ * @param schema - Optional schema to show expected structure (recommended)
+ */
+export function generateCorrectionPrompt(originalPrompt, failedResponse, schema) {
+    // Build schema example - either from provided schema or use default
+    let schemaExample;
+    if (schema && Object.keys(schema).length > 0) {
+        // Use provided schema
+        schemaExample = JSON.stringify(schema, null, 2);
+    }
+    else {
+        // Fallback to generic example (backward compatible)
+        schemaExample = `{
+  "purpose": "...",
+  "keyConcepts": [...],
+  "dependencies": [...],
+  "complexity": "low|medium|high",
+  "suggestedDocs": [...],
+  "architecturalNotes": "..."
+}`;
+    }
+    return `Your previous response was not valid JSON. I need ONLY a JSON object, with no explanations or prose.
+
+INCORRECT (what you sent):
+${failedResponse.slice(0, 200)}${failedResponse.length > 200 ? '...' : ''}
+
+CORRECT format - respond with ONLY this JSON structure, nothing else before or after:
+${schemaExample}
+
+Now provide ONLY the JSON for: ${originalPrompt.slice(0, 500)}`;
+}
+/**
+ * Extract required field names from a JSON schema object
+ *
+ * Handles common schema patterns:
+ * - Simple objects: extracts top-level keys
+ * - Objects with "type" descriptors: extracts keys
+ *
+ * @param schema - The schema object passed to analyzeStructured (any object type)
+ * @returns Array of required field names
+ */
+export function extractRequiredFieldsFromSchema(schema) {
+    if (!schema || typeof schema !== 'object') {
+        return [];
+    }
+    // For simple schemas like { purpose: "...", complexity: "..." }
+    // Return all top-level keys
+    return Object.keys(schema);
+}
+/**
+ * Build a prompt that strongly encourages JSON-only output
+ *
+ * Uses multiple techniques:
+ * 1. Leading instruction (most important position)
+ * 2. Schema definition
+ * 3. Trailing reminder
+ */
+export function buildJsonPrompt(context, schema, instruction) {
+    const schemaExample = JSON.stringify(Object.fromEntries(Object.entries(schema).map(([k, v]) => [k, v])), null, 2);
+    return `IMPORTANT: Respond with ONLY valid JSON. No explanations, no markdown, no text before or after.
+
+${instruction}
+
+${context}
+
+Required JSON schema:
+${schemaExample}
+
+Remember: Output ONLY the JSON object. Any text outside the JSON will cause errors.`;
+}
+/**
+ * Retry wrapper that attempts extraction with correction prompts
+ *
+ * Uses schema-aware correction prompts for better retry success.
+ */
+export async function extractJsonWithRetry(sendPrompt, originalPrompt, options = {}) {
+    const maxRetries = options.maxRetries ?? 2;
+    const logger = options.logger ?? consoleLogger;
+    let lastResult;
+    let currentPrompt = originalPrompt;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        if (attempt > 0) {
+            logger.debug?.(`JSON extraction retry ${attempt}/${maxRetries}`);
+        }
+        const response = await sendPrompt(currentPrompt);
+        lastResult = extractJson(response, options);
+        if (lastResult.success) {
+            if (attempt > 0) {
+                logger.debug?.(`JSON extraction succeeded on retry ${attempt}`);
+            }
+            return lastResult;
+        }
+        // Generate schema-aware correction prompt for next attempt
+        if (attempt < maxRetries) {
+            currentPrompt = generateCorrectionPrompt(originalPrompt, response, options.schema);
+        }
+    }
+    return lastResult;
+}
+/**
+ * Create a structured output analyzer with built-in retry
+ *
+ * This is the recommended way to get structured JSON from LLMs.
+ * Combines prompt building, extraction, validation, and retry.
+ *
+ * @param analyze - Function that sends prompt to LLM and returns response
+ * @param schema - Expected schema (used for prompt, validation, and correction)
+ * @param options - Configuration options
+ */
+export async function analyzeStructuredWithRetry(analyze, prompt, schema, options = {}) {
+    const requiredFields = extractRequiredFieldsFromSchema(schema);
+    const result = await extractJsonWithRetry(analyze, prompt, {
+        requiredFields,
+        schema,
+        maxRetries: options.maxRetries ?? 2,
+        logger: options.logger
+    });
+    return {
+        success: result.success,
+        data: result.data,
+        error: result.error
+    };
+}
+//# sourceMappingURL=llm-json-extractor.js.map

package/dist/src/utils/llm-json-extractor.js.map

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

package/dist/src/utils/structure-level-detector.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Structure Level Detector
+ *
+ * Detects whether the project uses 1-level or 2-level folder structure
+ * for living docs specs:
+ *
+ * - 1-Level: internal/specs/{project}/FS-XXX/
+ * - 2-Level: internal/specs/{project}/{board}/FS-XXX/
+ *
+ * 2-level is used when:
+ * - ADO area path mapping is configured (project → area paths)
+ * - JIRA board mapping is configured with multiple boards per project
+ * - Umbrella with team-based organization
+ *
+ * @module utils/structure-level-detector
+ */
+/**
+ * Structure level configuration
+ */
+export interface StructureLevelConfig {
+    /** Whether this is 1-level or 2-level structure */
+    level: 1 | 2;
+    /** Available projects (for 1-level) or top-level containers (for 2-level) */
+    projects: ProjectInfo[];
+    /** Available boards (only for 2-level) - organized by project */
+    boardsByProject?: Record<string, BoardInfo[]>;
+    /** Detection reason for debugging */
+    detectionReason: string;
+    /** Source of configuration */
+    source: 'ado-area-path' | 'jira-board' | 'umbrella-teams' | 'multi-project' | 'single-project' | 'existing-folders';
+}
+/**
+ * Project information
+ */
+export interface ProjectInfo {
+    id: string;
+    name: string;
+    /** For 2-level: this is the ADO project or JIRA project key */
+    externalId?: string;
+}
+/**
+ * Board information (for 2-level structures)
+ */
+export interface BoardInfo {
+    id: string;
+    name: string;
+    /** Parent project ID */
+    projectId: string;
+    /** Keywords for matching */
+    keywords?: string[];
+    /** ADO area path */
+    areaPath?: string;
+    /** JIRA board ID */
+    jiraBoardId?: string;
+}
+/**
+ * Validation result for spec.md project/board context
+ */
+export interface ProjectContextValidation {
+    isValid: boolean;
+    errors: string[];
+    warnings: string[];
+    /** Detected structure level */
+    structureLevel: 1 | 2;
+    /** Parsed project from spec */
+    project?: string;
+    /** Parsed board from spec (for 2-level) */
+    board?: string;
+    /** Expected path where this spec will sync to */
+    expectedPath?: string;
+}
+/**
+ * Detect structure level from configuration
+ *
+ * @param projectRoot - Path to project root
+ * @returns Structure level configuration
+ */
+export declare function detectStructureLevel(projectRoot?: string): StructureLevelConfig;
+/**
+ * Validate spec.md has required project/board context
+ *
+ * @param specContent - Content of spec.md file
+ * @param projectRoot - Path to project root
+ * @returns Validation result
+ */
+export declare function validateProjectContext(specContent: string, projectRoot?: string): ProjectContextValidation;
+/**
+ * Get required fields for spec.md based on structure level
+ *
+ * @param projectRoot - Path to project root
+ * @returns Object describing required fields
+ */
+export declare function getRequiredSpecFields(projectRoot?: string): {
+    level: 1 | 2;
+    requiredFields: string[];
+    optionalFields: string[];
+    projects: ProjectInfo[];
+    boardsByProject?: Record<string, BoardInfo[]>;
+};
+/**
+ * Normalize ID to kebab-case
+ */
+declare function normalizeId(name: string): string;
+export { normalizeId };
+//# sourceMappingURL=structure-level-detector.d.ts.map

package/dist/src/utils/structure-level-detector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"structure-level-detector.d.ts","sourceRoot":"","sources":["../../../src/utils/structure-level-detector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAKH;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,mDAAmD;IACnD,KAAK,EAAE,CAAC,GAAG,CAAC,CAAC;IAEb,6EAA6E;IAC7E,QAAQ,EAAE,WAAW,EAAE,CAAC;IAExB,iEAAiE;IACjE,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,EAAE,CAAC,CAAC;IAE9C,qCAAqC;IACrC,eAAe,EAAE,MAAM,CAAC;IAExB,8BAA8B;IAC9B,MAAM,EAAE,eAAe,GAAG,YAAY,GAAG,gBAAgB,GAAG,eAAe,GAAG,gBAAgB,GAAG,kBAAkB,CAAC;CACrH;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,+DAA+D;IAC/D,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,wBAAwB;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,4BAA4B;IAC5B,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,oBAAoB;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,oBAAoB;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,+BAA+B;IAC/B,cAAc,EAAE,CAAC,GAAG,CAAC,CAAC;IACtB,+BAA+B;IAC/B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,2CAA2C;IAC3C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iDAAiD;IACjD,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AA+CD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,WAAW,GAAE,MAAsB,GAAG,oBAAoB,CAoQ9F;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,WAAW,EAAE,MAAM,EACnB,WAAW,GAAE,MAAsB,GAClC,wBAAwB,CAgH1B;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,WAAW,GAAE,MAAsB,GAAG;IAC1E,KAAK,EAAE,CAAC,GAAG,CAAC,CAAC;IACb,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,QAAQ,EAAE,WAAW,EAAE,CAAC;IACxB,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,EAAE,CAAC,CAAC;CAC/C,CAmBA;AAED;;GAEG;AACH,iBAAS,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAOzC;AAED,OAAO,EAAE,WAAW,EAAE,CAAC"}