@libar-dev/architect 1.0.0-pre.3 → 1.0.0-pre.4

package/dist/scanner/ast-parser.js

@@ -1,835 +0,0 @@
-/**
- * @architect
- * @architect-core @architect-scanner
- * @architect-pattern TypeScript AST Parser
- * @architect-status completed
- * @architect-arch-role infrastructure
- * @architect-arch-context scanner
- * @architect-arch-layer infrastructure
- * @architect-uses TagRegistry, DocDirectiveSchema, typescript-estree
- * @architect-used-by Pattern Scanner, Doc Extractor
- * @architect-usecase "When parsing JSDoc comments for @architect-* directives"
- * @architect-usecase "When extracting code blocks following documentation comments"
- *
- * ## TypeScript AST Parser - JSDoc Directive Extraction
- *
- * Parses TypeScript source files using @typescript-eslint/typescript-estree
- * to extract @architect-* directives with their associated code blocks.
- * First stage of the three-stage pipeline: Scanner → Extractor → Generator.
- *
- * ### When to Use
- *
- * - Scanning TypeScript files for documentation directives
- * - Extracting code snippets following JSDoc comments
- * - Building pattern metadata from JSDoc tags
- *
- * ### Key Concepts
- *
- * - **Data-Driven Extraction**: Tag formats defined in registry, not hardcoded
- * - **Schema-First Validation**: All directives validated against Zod schemas
- * - **Result Monad**: Returns Result<T, E> for explicit error handling
- */
-import { Result } from '../types/index.js';
-import { parse } from '@typescript-eslint/typescript-estree';
-import { asDirectiveTag, createDirectiveValidationError, createFileParseError, } from '../types/index.js';
-import { DocDirectiveSchema, createDefaultTagRegistry, } from '../validation-schemas/index.js';
-import { createRegexBuilders } from '../config/regex-builders.js';
-/**
- * Module-level regex cache for performance optimization.
- *
- * Regex compilation is expensive (~50μs per pattern). In hot paths where
- * the same patterns are used repeatedly (e.g., extracting metadata tags),
- * caching provides ~80x fewer RegExp instantiations.
- *
- * @internal
- */
-const REGEX_CACHE = new Map();
-/**
- * Get or create a cached RegExp instance.
- *
- * @param pattern - Regex pattern string
- * @param flags - Optional regex flags (g, i, m, etc.)
- * @returns Cached or newly created RegExp
- *
- * @internal
- */
-function getCachedRegex(pattern, flags) {
-    const key = flags ? `${pattern}|${flags}` : pattern;
-    let regex = REGEX_CACHE.get(key);
-    if (!regex) {
-        regex = new RegExp(pattern, flags);
-        REGEX_CACHE.set(key, regex);
-    }
-    // Reset lastIndex for stateful regexes (those with 'g' flag)
-    if (regex.global) {
-        regex.lastIndex = 0;
-    }
-    return regex;
-}
-/**
- * Extract single value from comment text for format="value"
- *
- * @example
- * ```
- * @architect-pattern MyPattern
- * ```
- */
-function extractSingleValue(commentText, fullTag) {
-    const regex = getCachedRegex(`(?:^|\\n)\\s*\\*?\\s*${escapeRegex(fullTag)}\\s+(.+?)(?:\\n|\\*|$)`);
-    const match = regex.exec(commentText);
-    return match?.[1]?.trim();
-}
-/**
- * Extract enum value from comment text for format="enum"
- *
- * @example
- * ```
- * @architect-status completed
- * ```
- */
-function extractEnumValue(commentText, fullTag, validValues) {
-    const valuesPattern = validValues.join('|');
-    const regex = getCachedRegex(`${escapeRegex(fullTag)}\\s+(${valuesPattern})`);
-    const match = regex.exec(commentText);
-    return match?.[1];
-}
-/**
- * Extract quoted value from comment text for format="quoted-value"
- *
- * @example
- * ```
- * @architect-usecase "When implementing a new command"
- * ```
- */
-function extractQuotedValue(commentText, fullTag) {
-    const regex = getCachedRegex(`${escapeRegex(fullTag)}\\s+(?:"([^"]+)"|([^\\n*]+?)(?:\\n|\\*|$))`, 'g');
-    const values = [];
-    let match;
-    while ((match = regex.exec(commentText)) !== null) {
-        const value = (match[1] ?? match[2])?.trim();
-        if (value) {
-            values.push(value);
-        }
-    }
-    return values;
-}
-/**
- * Extract comma-separated values from comment text for format="csv"
- *
- * @example
- * ```
- * @architect-uses PatternA, PatternB, PatternC
- * ```
- */
-function extractCsvValue(commentText, fullTag) {
-    const regex = getCachedRegex(`${escapeRegex(fullTag)}\\s+([^\\n@*]+)`);
-    const match = regex.exec(commentText);
-    if (!match?.[1])
-        return undefined;
-    return match[1]
-        .split(',')
-        .map((s) => s.trim())
-        .filter(Boolean);
-}
-/**
- * Extract number value from comment text for format="number"
- *
- * @example
- * ```
- * @architect-phase 14
- * ```
- */
-function extractNumberValue(commentText, fullTag) {
-    const regex = getCachedRegex(`${escapeRegex(fullTag)}\\s+(\\d+)`);
-    const match = regex.exec(commentText);
-    return match?.[1] ? parseInt(match[1], 10) : undefined;
-}
-/**
- * Check if flag is present in comment text for format="flag"
- *
- * @example
- * ```
- * @architect-core
- * ```
- */
-function checkFlagPresent(commentText, fullTag) {
-    const regex = getCachedRegex(`${escapeRegex(fullTag)}(?:\\s|$|\\*)`);
-    return regex.test(commentText);
-}
-/**
- * Escape special regex characters
- */
-function escapeRegex(str) {
-    return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-}
-/**
- * Build regex patterns for directive parsing from registry configuration.
- *
- * @param registry - Tag registry with prefix and opt-in tag configuration
- * @returns Object with compiled regex patterns for directive parsing
- *
- * @internal
- */
-function buildDirectivePatterns(registry) {
-    // Extract prefix without @ for pattern construction
-    const prefixWithoutAt = registry.tagPrefix.startsWith('@')
-        ? registry.tagPrefix.substring(1)
-        : registry.tagPrefix;
-    const escapedPrefixWithoutAt = escapeRegex(prefixWithoutAt);
-    // Extract opt-in tag without @ for pattern construction
-    const optInWithoutAt = registry.fileOptInTag.startsWith('@')
-        ? registry.fileOptInTag.substring(1)
-        : registry.fileOptInTag;
-    const escapedOptInWithoutAt = escapeRegex(optInWithoutAt);
-    return {
-        // Match directive tags: @prefix-pattern, @prefix-core, etc. (prefix includes trailing -)
-        tagRegex: new RegExp(`@${escapedPrefixWithoutAt}[\\w-]+`, 'g'),
-        // Check if line starts with opt-in or directive
-        // e.g., ^@architect or ^@architect-pattern
-        startsWithOptInOrDirective: new RegExp(`^@${escapedOptInWithoutAt}(?:-[\\w-]+)?`),
-        // Match opt-in tag for removal (not followed by -)
-        // e.g., @architect followed by whitespace or end
-        optInTagPattern: new RegExp(`@${escapedOptInWithoutAt}(?!-)(\\s|$)?`, 'g'),
-        // Match any @ tag that is NOT our prefix
-        // e.g., @param, @returns, @example (not @architect)
-        nonOptInAtTagPattern: new RegExp(`^@(?!${escapedOptInWithoutAt})`),
-    };
-}
-/**
- * Build regex pattern for value-taking tags from registry.
- *
- * Value-taking tags are all metadata tags except those with format="flag".
- * This pattern detects when a line contains a metadata directive whose
- * value should NOT be captured as inline description text.
- *
- * @param registry - Tag registry to extract metadata tags from
- * @returns RegExp pattern string (without surrounding slashes)
- *
- * @internal
- */
-function buildValueTakingTagsPattern(registry) {
-    const valueTakingTags = registry.metadataTags
-        .filter((tag) => tag.format !== 'flag')
-        .map((tag) => escapeRegex(tag.tag));
-    const tagPrefix = escapeRegex(registry.tagPrefix);
-    return `${tagPrefix}(?:${valueTakingTags.join('|')})\\s`;
-}
-/**
- * Pre-compiled regex for detecting value-taking metadata directives.
- *
- * Built at module load time from the default registry to:
- * 1. Avoid regex compilation on every parse call
- * 2. Eliminate hardcoded tag lists that fall out of sync with registry
- *
- * Matches lines containing tags like @architect-pattern, @architect-status, etc.
- * Does NOT match flag-only tags like @architect-core.
- *
- * @internal
- */
-const _VALUE_TAKING_TAGS_REGEX = (() => {
-    const defaultRegistry = createDefaultTagRegistry();
-    return new RegExp(buildValueTakingTagsPattern(defaultRegistry));
-})();
-/**
- * Extract metadata tag value based on format type
- *
- * Dispatches to the appropriate extraction function based on the tag's format.
- * This enables data-driven metadata extraction without hardcoded patterns.
- *
- * @param commentText - Full JSDoc comment text
- * @param tagDef - Metadata tag definition from registry
- * @param prefix - Tag prefix (e.g., "@architect-")
- * @returns Extracted value in appropriate format, or undefined if not found
- */
-function extractMetadataTag(commentText, tagDef, prefix) {
-    const fullTag = `${prefix}${tagDef.tag}`;
-    switch (tagDef.format) {
-        case 'value':
-            return extractSingleValue(commentText, fullTag);
-        case 'enum':
-            return extractEnumValue(commentText, fullTag, tagDef.values ?? []);
-        case 'quoted-value':
-            // For repeatable tags, return array; otherwise return single value
-            if (tagDef.repeatable) {
-                const values = extractQuotedValue(commentText, fullTag);
-                return values.length > 0 ? values : undefined;
-            }
-            else {
-                const values = extractQuotedValue(commentText, fullTag);
-                return values[0];
-            }
-        case 'csv':
-            return extractCsvValue(commentText, fullTag);
-        case 'number':
-            return extractNumberValue(commentText, fullTag);
-        case 'flag':
-            return checkFlagPresent(commentText, fullTag);
-        default:
-            return undefined;
-    }
-}
-/**
- * Parses TypeScript content and extracts all @architect-* directives
- * with their associated code blocks and exports.
- *
- * **Error Handling**: Returns Result type to surface parse errors:
- * - Ok: Contains successfully parsed directives and any skipped directive errors
- * - Err: Contains FileParseError when the entire file fails to parse
- *
- * @param content - TypeScript file content
- * @param filePath - Path to TypeScript file (for error messages)
- * @param registry - Tag registry for metadata extraction (optional, defaults to generic registry)
- * @returns Result with parsed directives or parse error
- *
- * @example
- * ```typescript
- * const content = await fs.readFile(filePath, "utf-8");
- * const result = parseFileDirectives(content, filePath, registry);
- *
- * if (Result.isOk(result)) {
- *   const { directives, skippedDirectives } = result.value;
- *   console.log(`Parsed ${directives.length} directives`);
- *   console.log(`Skipped ${skippedDirectives.length} invalid directives`);
- * } else {
- *   console.error(`Parse error: ${result.error.message}`);
- * }
- * ```
- */
-export function parseFileDirectives(content, filePath, registry) {
-    const effectiveRegistry = registry ?? createDefaultTagRegistry();
-    let ast;
-    try {
-        ast = parse(content, {
-            loc: true,
-            range: true,
-            comment: true,
-            tokens: false,
-        });
-    }
-    catch (error) {
-        // Surface parse errors instead of silently returning empty
-        const tsError = error;
-        const location = 'lineNumber' in tsError && 'column' in tsError
-            ? { line: tsError.lineNumber, column: tsError.column }
-            : undefined;
-        return Result.err(createFileParseError(filePath, tsError.message || 'Unknown parse error', location, error));
-    }
-    const results = [];
-    const skippedDirectives = [];
-    const comments = ast.comments ?? [];
-    // Create regex builders for directive detection using registry configuration
-    const builders = createRegexBuilders(effectiveRegistry.tagPrefix, effectiveRegistry.fileOptInTag);
-    for (const comment of comments) {
-        if (comment.type !== 'Block')
-            continue;
-        const commentText = comment.value;
-        if (!builders.hasDocDirectives(commentText))
-            continue;
-        // Extract directive information (with schema validation)
-        if (!comment.loc)
-            continue; // Skip if no location info
-        const directiveResult = parseDirective(commentText, comment.loc, filePath, effectiveRegistry);
-        if (Result.isErr(directiveResult)) {
-            // Collect directive validation errors instead of silently skipping
-            skippedDirectives.push(directiveResult.error);
-            continue;
-        }
-        const directive = directiveResult.value;
-        if (directive.tags.length === 0)
-            continue;
-        // Find the code block following this comment
-        const codeBlock = extractCodeBlockAfterComment(content, ast, comment);
-        if (!codeBlock)
-            continue;
-        // Extract exports from the code block (DD-1: thread content for signature slicing)
-        const exports = extractExportsFromBlock(ast, codeBlock, content);
-        results.push({
-            directive,
-            code: codeBlock.code,
-            exports,
-        });
-    }
-    return Result.ok({ directives: results, skippedDirectives });
-}
-/**
- * Parse JSDoc comment to extract directive information
- *
- * **Schema-First Enforcement**: Validates constructed directive against schema
- * to ensure data integrity at the boundary.
- *
- * **Directive-Level Tag Extraction**: Only extracts `@architect-*` tags from
- * the directive section (first lines before description content). Tags mentioned
- * in descriptions, examples, or other sections are NOT extracted.
- *
- * JSDoc structure:
- * ```
- * /**
- *  * @architect-core @architect-api   <- Directive tags (extracted)
- *  *
- *  * Description mentioning @architect-x <- NOT extracted
- *  * @example
- *  * hasTag('@architect-y');            <- NOT extracted
- *  *\/
- * ```
- */
-function parseDirective(commentText, loc, filePath, registry) {
-    const lines = commentText.split('\n').map((l) => l.trim().replace(/^\*\s?/, ''));
-    // Build registry-based regex patterns for directive parsing
-    const patterns = buildDirectivePatterns(registry);
-    const valueTakingTagsRegex = new RegExp(buildValueTakingTagsPattern(registry));
-    // Extract directive tags ONLY from directive section
-    // Directive section = lines where tags appear at the START (not mentioned in text)
-    // A directive tag line: "@architect-core @architect-api Some brief description"
-    // A description line: "This works with @architect-api patterns" (tag not at start)
-    const tags = [];
-    let inlineDescription = ''; // Capture description on same line as tags
-    for (const line of lines) {
-        const trimmedLine = line.trim();
-        // Skip empty lines at the start (before we've found any tags)
-        if (trimmedLine === '' && tags.length === 0)
-            continue;
-        // Stop at empty lines after we've found tags (description section started)
-        if (trimmedLine === '' && tags.length > 0)
-            break;
-        // Check if line starts with a standard JSDoc tag (@param, @returns, @example, etc.)
-        // but NOT our doc directives
-        if (patterns.nonOptInAtTagPattern.exec(trimmedLine)) {
-            break; // Stop at other @ tags
-        }
-        // Check if line STARTS with opt-in or directive tag
-        // e.g., @architect (no suffix) = file opt-in tag
-        // e.g., @architect-* (with suffix) = section tag to extract
-        const startsWithDocTag = patterns.startsWithOptInOrDirective.exec(trimmedLine);
-        if (startsWithDocTag) {
-            // This is a directive line - extract only directive tags (with suffix)
-            // Skip opt-in tag (no suffix) which is just the opt-in marker
-            // e.g., "@architect @architect-core Brief description" extracts only @architect-core
-            let match;
-            let lastTagEnd = 0;
-            patterns.tagRegex.lastIndex = 0;
-            while ((match = patterns.tagRegex.exec(trimmedLine)) !== null) {
-                // Only extract tags that are at the start (consecutive, separated by whitespace or opt-in)
-                const textBefore = trimmedLine.slice(lastTagEnd, match.index).trim();
-                // Allow opt-in tag and whitespace between directive tags
-                const cleanedBefore = textBefore.replace(patterns.optInTagPattern, '').trim();
-                if (lastTagEnd > 0 && cleanedBefore !== '') {
-                    // There's non-whitespace content between tags - this tag is in description
-                    break;
-                }
-                tags.push(match[0]);
-                lastTagEnd = match.index + match[0].length;
-            }
-            // Capture any description text after the tags on the same line
-            // e.g., "@architect-core Brief description on same line" -> "Brief description on same line"
-            // But skip lines with metadata directives that take values (all non-flag tags)
-            // to prevent their values from leaking into the description
-            // (e.g., "@architect-phase 01" would incorrectly capture "01")
-            const hasMetadataDirective = valueTakingTagsRegex.test(trimmedLine);
-            if (!hasMetadataDirective) {
-                const textAfterTags = trimmedLine
-                    .slice(lastTagEnd)
-                    .replace(patterns.optInTagPattern, '') // Remove any opt-in markers
-                    .trim();
-                if (textAfterTags) {
-                    inlineDescription = textAfterTags;
-                }
-            }
-            // Continue to next line - there might be more directive tags
-        }
-        else {
-            // Line doesn't start with doc tag - it's description content
-            break;
-        }
-    }
-    // Data-driven metadata extraction using registry
-    // Build map of metadata tag results: tagName -> extracted value
-    const metadataResults = new Map();
-    for (const tagDef of registry.metadataTags) {
-        const result = extractMetadataTag(commentText, tagDef, registry.tagPrefix);
-        if (result !== undefined) {
-            metadataResults.set(tagDef.tag, result);
-        }
-    }
-    // Map extracted metadata to directive fields
-    // This mapping translates registry tag names to DocDirective field names
-    const patternName = metadataResults.get('pattern');
-    const status = metadataResults.get('status');
-    const isCore = metadataResults.get('core');
-    const useCases = metadataResults.get('usecase');
-    const uses = metadataResults.get('uses');
-    const usedBy = metadataResults.get('used-by');
-    const phase = metadataResults.get('phase');
-    const brief = metadataResults.get('brief');
-    const dependsOn = metadataResults.get('depends-on');
-    const enables = metadataResults.get('enables');
-    // UML-inspired relationship tags (PatternRelationshipModel)
-    const implementsPatterns = metadataResults.get('implements');
-    const extendsPattern = metadataResults.get('extends');
-    // Cross-reference and API navigation tags (PatternRelationshipModel enhancement)
-    const seeAlso = metadataResults.get('see-also');
-    const apiRef = metadataResults.get('api-ref');
-    // Architecture diagram generation tags
-    const archRole = metadataResults.get('arch-role');
-    const archContext = metadataResults.get('arch-context');
-    const archLayer = metadataResults.get('arch-layer');
-    const includeRaw = metadataResults.get('include');
-    const include = Array.isArray(includeRaw) ? includeRaw : undefined;
-    // Design session stub metadata tags
-    const target = metadataResults.get('target');
-    const since = metadataResults.get('since');
-    // Shape extraction tags
-    const extractShapes = metadataResults.get('extract-shapes');
-    // PRD metadata tags (product area, user role, business value)
-    const productArea = metadataResults.get('product-area');
-    // Convention tags for reference document generation
-    const convention = metadataResults.get('convention');
-    // Claude module generation tags
-    const claudeModule = metadataResults.get('claude-module');
-    const claudeSection = metadataResults.get('claude-section');
-    const claudeTags = metadataResults.get('claude-tags');
-    // Extract "### When to Use" section or "**When to use:**" inline format
-    // Returns array of bullet points, stopping at section boundaries
-    // This is a special format that extracts from description, not a metadata tag
-    const whenToUse = extractWhenToUse(commentText, registry.fileOptInTag);
-    // Extract description and examples
-    const descriptionLines = [];
-    const examples = [];
-    let inExample = false;
-    let exampleBuffer = [];
-    for (const line of lines) {
-        if (line.startsWith('@example')) {
-            inExample = true;
-            if (exampleBuffer.length > 0) {
-                examples.push(exampleBuffer.join('\n'));
-                exampleBuffer = [];
-            }
-            continue;
-        }
-        if (line.startsWith('@param') || line.startsWith('@returns') || line.startsWith('@')) {
-            if (inExample && exampleBuffer.length > 0) {
-                examples.push(exampleBuffer.join('\n'));
-                exampleBuffer = [];
-            }
-            inExample = false;
-            continue;
-        }
-        if (inExample) {
-            // Remove code fence markers
-            if (!line.startsWith('```')) {
-                exampleBuffer.push(line);
-            }
-        }
-        else if (!line.startsWith('@')) {
-            descriptionLines.push(line);
-        }
-    }
-    if (exampleBuffer.length > 0) {
-        examples.push(exampleBuffer.join('\n'));
-    }
-    // Build directive object
-    // Combine inline description (from same line as tags) with multi-line description
-    const fullDescription = inlineDescription
-        ? [inlineDescription, ...descriptionLines].join('\n').trim()
-        : descriptionLines.join('\n').trim();
-    const directive = {
-        tags: tags.map((tag) => asDirectiveTag(tag)),
-        description: fullDescription,
-        examples,
-        position: {
-            startLine: loc.start.line,
-            endLine: loc.end.line,
-        },
-        // Include optional fields only if present
-        ...(patternName && { patternName }),
-        ...(status && { status }),
-        ...(isCore && { isCore }),
-        ...(useCases && useCases.length > 0 && { useCases }),
-        ...(whenToUse && { whenToUse }),
-        ...(uses && uses.length > 0 && { uses }),
-        ...(usedBy && usedBy.length > 0 && { usedBy }),
-        ...(phase !== undefined && { phase }),
-        ...(brief && { brief }),
-        ...(dependsOn && dependsOn.length > 0 && { dependsOn }),
-        ...(enables && enables.length > 0 && { enables }),
-        // UML-inspired relationship fields (PatternRelationshipModel)
-        ...(implementsPatterns && implementsPatterns.length > 0 && { implements: implementsPatterns }),
-        ...(extendsPattern && { extends: extendsPattern }),
-        // Cross-reference and API navigation fields (PatternRelationshipModel enhancement)
-        ...(seeAlso && seeAlso.length > 0 && { seeAlso }),
-        ...(apiRef && apiRef.length > 0 && { apiRef }),
-        // Design session stub metadata fields
-        ...(target && { target }),
-        ...(since && { since }),
-        // Architecture diagram generation fields
-        ...(archRole && { archRole }),
-        ...(archContext && { archContext }),
-        ...(archLayer && { archLayer }),
-        ...(include && include.length > 0 && { include }),
-        ...(claudeModule && { claudeModule }),
-        ...(claudeSection && { claudeSection }),
-        ...(claudeTags && claudeTags.length > 0 && { claudeTags }),
-        // Shape extraction fields
-        ...(extractShapes && extractShapes.length > 0 && { extractShapes }),
-        // PRD metadata fields
-        ...(productArea && { productArea }),
-        // Convention tags for reference document generation
-        ...(convention && convention.length > 0 && { convention }),
-    };
-    // Validate against schema (schema-first enforcement)
-    const validation = DocDirectiveSchema.safeParse(directive);
-    if (!validation.success) {
-        const error = createDirectiveValidationError(filePath, loc.start.line, 'Invalid directive structure', commentText.substring(0, 100));
-        return Result.err(error);
-    }
-    return Result.ok(validation.data);
-}
-/**
- * Extract code block immediately following a comment
- */
-function extractCodeBlockAfterComment(content, ast, comment) {
-    if (!comment.range)
-        return null;
-    const commentEnd = comment.range[1];
-    // Find the first meaningful AST node after this comment
-    const nextNode = findNextNodeAfterPosition(ast, commentEnd);
-    if (!nextNode?.range || !nextNode.loc)
-        return null;
-    const lines = content.split('\n');
-    const startLine = nextNode.loc.start.line;
-    const endLine = nextNode.loc.end.line;
-    // Extract the code block
-    const codeLines = lines.slice(startLine - 1, endLine);
-    return {
-        code: codeLines.join('\n'),
-        startLine,
-        endLine,
-    };
-}
-/**
- * Find the first AST node after a given position
- */
-function findNextNodeAfterPosition(ast, position) {
-    for (const node of ast.body) {
-        if (node.range && node.range[0] > position) {
-            return node;
-        }
-    }
-    return null;
-}
-/**
- * Extract export information from a code block
- */
-function extractExportsFromBlock(ast, block, sourceCode) {
-    const exports = [];
-    for (const node of ast.body) {
-        if (!node.loc)
-            continue;
-        if (node.loc.start.line < block.startLine || node.loc.end.line > block.endLine)
-            continue;
-        if (node.type === 'ExportNamedDeclaration') {
-            if (node.declaration) {
-                exports.push(...extractFromDeclaration(node.declaration, sourceCode));
-            }
-            // Handle re-exports like: export { foo, bar } from './module'
-            // or type exports: export type { Foo } from './module'
-            if (node.specifiers) {
-                // Check if parent ExportNamedDeclaration is type-only
-                const isTypeExport = node.exportKind === 'type';
-                for (const spec of node.specifiers) {
-                    if (spec.type === 'ExportSpecifier') {
-                        // TypeScript 5.9.0+: exported can be Identifier or Literal (StringLiteral)
-                        // Handles cases like: export { "foo-bar" as baz } from './module'
-                        // Type union exhaustion: only Identifier and Literal are valid types here
-                        const exportedName = spec.exported.type === 'Identifier'
-                            ? spec.exported.name
-                            : spec.exported.value; // Literal type - extract value
-                        exports.push({
-                            name: exportedName,
-                            type: isTypeExport ? 'type' : 'const',
-                        });
-                    }
-                }
-            }
-        }
-        else if (node.type === 'ExportDefaultDeclaration') {
-            exports.push({
-                name: 'default',
-                type: getExportType(node.declaration),
-            });
-        }
-    }
-    return exports;
-}
-/**
- * Build a clean function signature from AST node and source code.
- *
- * DD-1: Uses AST body range to precisely locate the function body start,
- * then slices everything before it as the signature. This avoids flawed
- * brace-matching that fails on object parameter types like `{ timeout: number }`.
- * Strips `export ` prefix but keeps `async` (semantically meaningful).
- */
-function buildFunctionSignature(declaration, sourceCode) {
-    // Use AST body range for precise body location (no brace-matching needed)
-    if (declaration.body) {
-        const bodyStart = declaration.body.range[0];
-        const declStart = declaration.range[0];
-        const beforeBody = sourceCode.slice(declStart, bodyStart);
-        // Strip 'export ' prefix for clean display
-        const withoutExport = beforeBody.startsWith('export ')
-            ? beforeBody.slice('export '.length)
-            : beforeBody;
-        return withoutExport.trim() + ';';
-    }
-    // Fallback for declarations without body (ambient/abstract)
-    const fullText = sourceCode.slice(declaration.range[0], declaration.range[1]);
-    return fullText.startsWith('export ') ? fullText.slice('export '.length).trim() : fullText.trim();
-}
-/**
- * Extract exports from a declaration node
- */
-function extractFromDeclaration(declaration, sourceCode) {
-    const exports = [];
-    switch (declaration.type) {
-        case 'FunctionDeclaration':
-            if (declaration.id) {
-                exports.push({
-                    name: declaration.id.name,
-                    type: 'function',
-                    signature: buildFunctionSignature(declaration, sourceCode),
-                });
-            }
-            break;
-        case 'VariableDeclaration':
-            for (const declarator of declaration.declarations) {
-                if (declarator.id.type === 'Identifier') {
-                    exports.push({
-                        name: declarator.id.name,
-                        type: 'const',
-                    });
-                }
-            }
-            break;
-        case 'TSTypeAliasDeclaration':
-            exports.push({
-                name: declaration.id.name,
-                type: 'type',
-            });
-            break;
-        case 'TSInterfaceDeclaration':
-            exports.push({
-                name: declaration.id.name,
-                type: 'interface',
-            });
-            break;
-        case 'ClassDeclaration':
-            if (declaration.id) {
-                exports.push({
-                    name: declaration.id.name,
-                    type: 'class',
-                });
-            }
-            break;
-        case 'TSEnumDeclaration':
-            if (declaration.id) {
-                exports.push({
-                    name: declaration.id.name,
-                    type: 'enum',
-                });
-            }
-            break;
-    }
-    return exports;
-}
-/**
- * Get export type from declaration
- */
-function getExportType(declaration) {
-    switch (declaration.type) {
-        case 'FunctionDeclaration':
-            return 'function';
-        case 'ClassDeclaration':
-            return 'class';
-        case 'TSInterfaceDeclaration':
-            return 'interface';
-        case 'TSTypeAliasDeclaration':
-            return 'type';
-        default:
-            return 'const';
-    }
-}
-/**
- * Extract "When to Use" bullet points from JSDoc comment
- *
- * Handles two formats:
- * - Heading format: `### When to Use\n- bullet 1\n- bullet 2`
- * - Inline format: `**When to use:** Single line description`
- *
- * Key improvements over naive regex:
- * - Strips JSDoc `* ` markers before matching
- * - Only captures actual bullet points (lines starting with `- ` or `* `)
- * - Stops at section boundaries (empty lines, headings, tables, JSDoc tags)
- *
- * **Limitation:** Multi-line bullets (continuation lines) are not supported.
- * Each bullet must be a single line. For example:
- * ```
- * ### When to Use
- * - This works (single line)
- * - This is broken because it
- *   continues on the next line  // <-- Not captured
- * ```
- * Recommendation: Keep all bullet points as single lines.
- *
- * @param commentText - Raw JSDoc comment content
- * @param fileOptInTag - The file opt-in tag (e.g., "@docs" or "@architect")
- * @returns Array of bullet point strings, or undefined if no "When to Use" section
- */
-function extractWhenToUse(commentText, fileOptInTag) {
-    // Strip JSDoc markers and normalize lines
-    const cleanedLines = commentText.split('\n').map((line) => line
-        .trim()
-        .replace(/^\*\s?/, '')
-        .trim());
-    const cleanedText = cleanedLines.join('\n');
-    // Try heading format first: ### When to Use
-    const headingMatch = /###\s*When to Use\s*\n/i.exec(cleanedText);
-    if (headingMatch) {
-        const startIndex = headingMatch.index + headingMatch[0].length;
-        const afterHeading = cleanedText.slice(startIndex);
-        const lines = afterHeading.split('\n');
-        const bullets = [];
-        for (const line of lines) {
-            const trimmed = line.trim();
-            // Stop conditions: empty line, new heading, table, JSDoc tag (but not doc directives)
-            if (trimmed === '')
-                break;
-            if (trimmed.startsWith('#'))
-                break;
-            if (trimmed.startsWith('|'))
-                break;
-            if (trimmed.startsWith('@') && !trimmed.startsWith(fileOptInTag))
-                break;
-            // Extract bullet point content (must start with - or * followed by space)
-            const bulletMatch = /^[-*]\s+(.+)$/.exec(trimmed);
-            if (bulletMatch?.[1]) {
-                bullets.push(bulletMatch[1].trim());
-            }
-            else {
-                // Line doesn't start with bullet - stop extraction
-                break;
-            }
-        }
-        if (bullets.length > 0) {
-            return bullets;
-        }
-    }
-    // Try inline format: **When to use:** description
-    const inlineMatch = /\*\*When to use:\*\*\s*([^\n]+)/i.exec(cleanedText);
-    if (inlineMatch?.[1]) {
-        const description = inlineMatch[1].trim();
-        if (description) {
-            return [description];
-        }
-    }
-    return undefined;
-}
-//# sourceMappingURL=ast-parser.js.map