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

package/dist/extractor/shape-extractor.js

@@ -1,966 +0,0 @@
-/**
- * @architect
- * @architect-pattern ShapeExtractor
- * @architect-status completed
- * @architect-phase 26
- * @architect-implements ShapeExtraction
- * @architect-uses typescript-estree
- *
- * ## Shape Extractor - TypeScript Type Extraction
- *
- * Extracts TypeScript type definitions (interfaces, type aliases, enums,
- * function signatures) from source files for documentation generation.
- *
- * ### When to Use
- *
- * - When processing @architect-extract-shapes tags during extraction
- * - When generating documentation that needs actual type definitions
- * - When eliminating duplication between JSDoc examples and code
- *
- * ### Key Concepts
- *
- * - **AST-based extraction**: Uses typescript-estree for accurate parsing
- * - **Preserves formatting**: Extracts exact source text, not regenerated
- * - **Includes JSDoc**: Type-level JSDoc comments are preserved
- * - **Order from tag**: Shapes appear in tag-specified order, not source order
- */
-import { parse } from '@typescript-eslint/typescript-estree';
-import { Result } from '../types/result.js';
-// =============================================================================
-// Constants
-// =============================================================================
-/**
- * Maximum line gap between JSDoc comment end and declaration start.
- * Allows 1 blank line between JSDoc and declaration (comment end line + 1 blank + decl line = 3 gap)
- */
-const MAX_JSDOC_LINE_DISTANCE = 3;
-/**
- * Strict adjacency required for property-level JSDoc.
- * Property JSDoc must end on the line immediately before the property (no gap allowed).
- * This prevents interface-level JSDoc from being misattributed to the first property.
- */
-const PROPERTY_JSDOC_MAX_GAP = 1;
-/**
- * Maximum source code size in bytes (5MB).
- * Prevents memory exhaustion from oversized input during AST parsing.
- */
-const MAX_SOURCE_SIZE_BYTES = 5 * 1024 * 1024;
-// =============================================================================
-// Parse Helper
-// =============================================================================
-/**
- * Parse TypeScript source with the correct JSX mode.
- * JSX must only be enabled for .tsx files — enabling it for .ts files causes
- * generic arrow functions like `<T>(v: T)` to be mis-parsed as JSX elements.
- */
-function parseSource(sourceCode, jsx) {
-    return parse(sourceCode, { loc: true, range: true, comment: true, jsx });
-}
-// =============================================================================
-// Main Extraction Function
-// =============================================================================
-/**
- * Extract named shapes from TypeScript source code.
- *
- * @param sourceCode - The TypeScript source code to parse
- * @param shapeNames - Names of shapes to extract (in desired output order)
- * @param options - Extraction options
- * @returns Result containing extraction result with shapes, warnings, and not-found list
- */
-export function extractShapes(sourceCode, shapeNames, options = {}) {
-    // Validate input size to prevent memory exhaustion
-    if (sourceCode.length > MAX_SOURCE_SIZE_BYTES) {
-        return Result.err(new Error(`Source code size (${sourceCode.length} bytes) exceeds maximum allowed (${MAX_SOURCE_SIZE_BYTES} bytes)`));
-    }
-    const { includeJsDoc = true, preserveFormatting = true } = options;
-    const shapes = [];
-    const notFound = [];
-    const imported = [];
-    const reExported = [];
-    const warnings = [];
-    // Parse the source code
-    let ast;
-    try {
-        ast = parseSource(sourceCode, options.jsx ?? false);
-    }
-    catch (error) {
-        return Result.err(error instanceof Error ? error : new Error(`Failed to parse source code: ${String(error)}`));
-    }
-    // Build maps of declarations and imports/re-exports
-    const declarations = findDeclarations(ast);
-    const importsAndReExports = findImportsAndReExports(ast);
-    // Process each requested shape name
-    for (const shapeName of shapeNames) {
-        // Check if it's a local declaration
-        const declarationList = declarations.get(shapeName);
-        if (declarationList !== undefined) {
-            const declaration = pickBestDeclaration(declarationList);
-            const shape = extractShape(sourceCode, declaration, ast.comments ?? [], {
-                includeJsDoc,
-                preserveFormatting,
-            });
-            shapes.push(shape);
-            continue;
-        }
-        // Check if it's an import or re-export
-        const importInfo = importsAndReExports.get(shapeName);
-        if (importInfo) {
-            if (importInfo.isReExport) {
-                reExported.push({
-                    name: shapeName,
-                    sourceModule: importInfo.sourceModule,
-                    typeOnly: importInfo.typeOnly,
-                });
-            }
-            else {
-                imported.push(shapeName);
-            }
-            continue;
-        }
-        // Not found at all
-        notFound.push(shapeName);
-    }
-    return Result.ok({ shapes, notFound, imported, reExported, warnings });
-}
-// =============================================================================
-// AST Traversal Functions
-// =============================================================================
-/**
- * Find all declarations that could be extracted as shapes.
- */
-function findDeclarations(ast) {
-    const declarations = new Map();
-    function pushDeclaration(decl) {
-        const existing = declarations.get(decl.name);
-        if (existing !== undefined) {
-            existing.push(decl);
-        }
-        else {
-            declarations.set(decl.name, [decl]);
-        }
-    }
-    for (const node of ast.body) {
-        // Handle export declarations
-        if (node.type === 'ExportNamedDeclaration') {
-            if (node.declaration) {
-                const found = processDeclaration(node.declaration, true);
-                for (const decl of found) {
-                    pushDeclaration(decl);
-                }
-            }
-            // Handle export { Foo } without a source (local re-export)
-            if (!node.source) {
-                for (const spec of node.specifiers) {
-                    const localName = spec.local.name;
-                    // This might reference a local declaration - mark all as exported
-                    const existing = declarations.get(localName);
-                    if (existing !== undefined) {
-                        for (const decl of existing) {
-                            decl.exported = true;
-                        }
-                    }
-                }
-            }
-        }
-        // Handle non-exported declarations
-        else {
-            const found = processDeclaration(node, false);
-            for (const decl of found) {
-                const existing = declarations.get(decl.name);
-                // Only add if no exported version of same kind already exists
-                if (existing !== undefined) {
-                    const hasExportedSameKind = existing.some((e) => e.exported && e.kind === decl.kind);
-                    if (!hasExportedSameKind) {
-                        existing.push(decl);
-                    }
-                }
-                else {
-                    declarations.set(decl.name, [decl]);
-                }
-            }
-        }
-    }
-    return declarations;
-}
-/** Priority ranking for declaration kinds — type-level preferred for documentation */
-const KIND_PRIORITY = {
-    interface: 0,
-    type: 1,
-    enum: 2,
-    function: 3,
-    const: 4,
-};
-/**
- * Pick the best declaration from an array of same-name declarations.
- * Prefers type-level constructs (interface, type, enum) over value-level (function, const).
- */
-function pickBestDeclaration(declarations) {
-    if (declarations.length === 1) {
-        const only = declarations[0];
-        if (only === undefined)
-            throw new Error('Empty declarations array');
-        return only;
-    }
-    const sorted = [...declarations].sort((a, b) => KIND_PRIORITY[a.kind] - KIND_PRIORITY[b.kind]);
-    const best = sorted[0];
-    if (best === undefined)
-        throw new Error('Empty declarations array after sort');
-    return best;
-}
-/**
- * Process a declaration node and extract shape info.
- */
-function processDeclaration(node, exported) {
-    const results = [];
-    switch (node.type) {
-        case 'TSInterfaceDeclaration':
-            results.push({
-                node,
-                kind: 'interface',
-                name: node.id.name,
-                exported,
-            });
-            break;
-        case 'TSTypeAliasDeclaration':
-            results.push({
-                node,
-                kind: 'type',
-                name: node.id.name,
-                exported,
-            });
-            break;
-        case 'TSEnumDeclaration':
-            results.push({
-                node,
-                kind: 'enum',
-                name: node.id.name,
-                exported,
-            });
-            break;
-        case 'FunctionDeclaration':
-            if (node.id) {
-                results.push({
-                    node,
-                    kind: 'function',
-                    name: node.id.name,
-                    exported,
-                });
-            }
-            break;
-        case 'VariableDeclaration':
-            // Handle const declarations
-            if (node.kind === 'const') {
-                for (const declarator of node.declarations) {
-                    if (declarator.id.type === 'Identifier') {
-                        results.push({
-                            node: declarator,
-                            kind: 'const',
-                            name: declarator.id.name,
-                            exported,
-                        });
-                    }
-                }
-            }
-            break;
-    }
-    return results;
-}
-/**
- * Find all imports and re-exports.
- */
-function findImportsAndReExports(ast) {
-    const result = new Map();
-    for (const node of ast.body) {
-        // Import declarations
-        if (node.type === 'ImportDeclaration') {
-            const sourceModule = node.source.value;
-            const typeOnly = node.importKind === 'type';
-            for (const spec of node.specifiers) {
-                if (spec.type === 'ImportSpecifier') {
-                    result.set(spec.local.name, {
-                        name: spec.local.name,
-                        sourceModule,
-                        isReExport: false,
-                        typeOnly: typeOnly || spec.importKind === 'type',
-                    });
-                }
-                else if (spec.type === 'ImportDefaultSpecifier') {
-                    result.set(spec.local.name, {
-                        name: spec.local.name,
-                        sourceModule,
-                        isReExport: false,
-                        typeOnly,
-                    });
-                }
-            }
-        }
-        // Export declarations with source (re-exports)
-        if (node.type === 'ExportNamedDeclaration' && node.source) {
-            const sourceModule = node.source.value;
-            const typeOnly = node.exportKind === 'type';
-            for (const spec of node.specifiers) {
-                const exportedName = spec.exported.type === 'Identifier' ? spec.exported.name : spec.exported.value;
-                result.set(exportedName, {
-                    name: exportedName,
-                    sourceModule,
-                    isReExport: true,
-                    typeOnly,
-                });
-            }
-        }
-        // Export all (export * from './module')
-        if (node.type === 'ExportAllDeclaration') {
-            // We can't know specific names from export *, just note it
-            // This is handled by the "not found" case
-        }
-    }
-    return result;
-}
-// =============================================================================
-// Shape Extraction
-// =============================================================================
-/**
- * Extract a single shape from its declaration.
- */
-function extractShape(sourceCode, declaration, comments, options) {
-    const { node, kind, name, exported } = declaration;
-    // Get the node's range for source extraction (guaranteed by parse options: range: true)
-    let sourceText = sourceCode.slice(node.range[0], node.range[1]);
-    // For functions, convert to signature only (remove body)
-    // Uses AST body range for precise location — avoids brace-matching that
-    // fails on object parameter types like { timeout: number }
-    if (kind === 'function' && node.type === 'FunctionDeclaration') {
-        const funcNode = node;
-        const bodyStart = funcNode.body.range[0];
-        const declStart = node.range[0];
-        sourceText = sourceCode.slice(declStart, bodyStart).trim();
-        if (sourceText.startsWith('export ')) {
-            sourceText = sourceText.slice('export '.length);
-        }
-        sourceText = sourceText.trim() + ';';
-    }
-    // For const, extract just the type annotation if present
-    if (kind === 'const' && node.type === 'VariableDeclarator') {
-        const declNode = node;
-        if (declNode.id.typeAnnotation) {
-            // Extract const with type annotation (ranges guaranteed by parse options)
-            const idRange = declNode.id.range;
-            const typeRange = declNode.id.typeAnnotation.range;
-            sourceText = `const ${sourceCode.slice(idRange[0], typeRange[1])};`;
-        }
-    }
-    // Get JSDoc if requested, stripping @architect-* annotation lines
-    let jsDoc;
-    if (options.includeJsDoc) {
-        const rawJsDoc = extractPrecedingJsDoc(sourceCode, node, comments);
-        jsDoc = rawJsDoc !== undefined ? stripArchitectTags(rawJsDoc) : undefined;
-    }
-    // DD-3: Parse @param/@returns/@throws from JSDoc for function shapes
-    let parsedTags;
-    if (options.includeJsDoc && kind === 'function' && jsDoc) {
-        parsedTags = parseJsDocTags(jsDoc);
-    }
-    // Get line number (guaranteed by parse options: loc: true)
-    const lineNumber = node.loc.start.line;
-    // Extract type parameters for interfaces and types
-    let typeParameters;
-    if (node.type === 'TSInterfaceDeclaration' || node.type === 'TSTypeAliasDeclaration') {
-        const params = node.typeParameters;
-        if (params?.params) {
-            typeParameters = params.params.map((p) => sourceCode.slice(p.range[0], p.range[1]));
-        }
-    }
-    // Extract extends for interfaces
-    let extendsArr;
-    if (node.type === 'TSInterfaceDeclaration' && node.extends.length > 0) {
-        extendsArr = node.extends.map((ext) => sourceCode.slice(ext.range[0], ext.range[1]));
-    }
-    // Extract property-level JSDoc for interfaces
-    // Uses strict adjacency to prevent interface-level JSDoc from being misattributed to first property
-    // Performance optimization: pre-sort comments once O(c log c), then O(log c) per property lookup
-    let propertyDocs;
-    if (options.includeJsDoc && node.type === 'TSInterfaceDeclaration') {
-        const docs = [];
-        // Get the line where the interface body starts (the `{` line)
-        // loc is guaranteed by parse options: { range: true, loc: true }
-        const interfaceBodyStartLine = node.body.loc.start.line;
-        // Pre-process comments once for O(log c) binary search per property
-        // This converts O(m × c) to O(c log c + m log c) where m=properties, c=comments
-        const sortedComments = prepareJsDocComments(comments);
-        for (const member of node.body.body) {
-            if (member.type === 'TSPropertySignature' && member.key.type === 'Identifier') {
-                const propName = member.key.name;
-                // Use strict adjacency - comment must be inside interface body and immediately before property
-                const propJsDoc = findStrictlyAdjacentPropertyJsDoc(sourceCode, member, sortedComments, interfaceBodyStartLine);
-                if (propJsDoc) {
-                    // Extract just the text content from JSDoc, removing delimiters
-                    const cleanedJsDoc = extractJsDocText(propJsDoc);
-                    if (cleanedJsDoc) {
-                        docs.push({ name: propName, jsDoc: cleanedJsDoc });
-                    }
-                }
-            }
-        }
-        if (docs.length > 0) {
-            propertyDocs = docs;
-        }
-    }
-    return {
-        name,
-        kind,
-        sourceText,
-        jsDoc,
-        lineNumber,
-        typeParameters,
-        extends: extendsArr,
-        exported,
-        propertyDocs,
-        // DD-3: Include parsed JSDoc tags for function shapes
-        params: parsedTags !== undefined && parsedTags.params.length > 0 ? parsedTags.params : undefined,
-        returns: parsedTags?.returns,
-        throws: parsedTags !== undefined && parsedTags.throws.length > 0 ? parsedTags.throws : undefined,
-    };
-}
-/**
- * Strip @architect-* annotation lines from a JSDoc comment.
- *
- * Preserves standard JSDoc tags (@param, @returns, @example, etc.) and
- * all non-annotation content. Returns undefined if all content lines were
- * annotation tags (empty JSDoc after stripping).
- */
-function extractJsDocLineContent(line) {
-    return line
-        .trim()
-        .replace(/^\/\*\*\s*/, '') // strip leading /**
-        .replace(/\*\/\s*$/, '') // strip trailing */
-        .replace(/^\*\s?/, '') // strip leading * (JSDoc continuation)
-        .trim();
-}
-function stripArchitectTags(jsDoc) {
-    const lines = jsDoc.split('\n');
-    const filtered = lines.filter((line) => !extractJsDocLineContent(line).startsWith('@architect'));
-    // Check if anything meaningful remains (not just /** and */)
-    const hasContent = filtered.some((line) => extractJsDocLineContent(line).length > 0);
-    if (!hasContent)
-        return undefined;
-    // Clean up consecutive empty JSDoc lines left by tag removal
-    const result = [];
-    let prevWasEmptyJsDocLine = false;
-    for (const line of filtered) {
-        const trimmed = line.trim();
-        const isEmptyJsDocLine = trimmed === '*' || trimmed === '';
-        if (isEmptyJsDocLine && prevWasEmptyJsDocLine)
-            continue;
-        result.push(line);
-        prevWasEmptyJsDocLine = isEmptyJsDocLine;
-    }
-    return result.join('\n');
-}
-/**
- * Extract JSDoc comment preceding a node.
- */
-function extractPrecedingJsDoc(sourceCode, node, comments) {
-    // Range and loc are guaranteed by parse options: { range: true, loc: true }
-    const nodeStart = node.range[0];
-    const nodeLine = node.loc.start.line;
-    // Find the closest block comment that ends before this node
-    // and is a JSDoc comment (starts with /**)
-    let closestJsDoc;
-    for (const comment of comments) {
-        if (comment.type !== 'Block')
-            continue;
-        if (!comment.value.startsWith('*'))
-            continue; // JSDoc starts with /**
-        const commentEnd = comment.range[1];
-        const commentEndLine = comment.loc.end.line;
-        // Comment must end before node starts
-        if (commentEnd > nodeStart)
-            continue;
-        // Comment must be close to the node
-        if (nodeLine - commentEndLine > MAX_JSDOC_LINE_DISTANCE)
-            continue;
-        // This is a candidate - pick the one closest to the node
-        if (!closestJsDoc || comment.range[1] > closestJsDoc.range[1]) {
-            closestJsDoc = comment;
-        }
-    }
-    if (!closestJsDoc)
-        return undefined;
-    // Return the full JSDoc including delimiters
-    return sourceCode.slice(closestJsDoc.range[0], closestJsDoc.range[1]);
-}
-/**
- * Pre-process comments for efficient property JSDoc lookup.
- *
- * Filters to only JSDoc block comments and sorts by end line for binary search.
- * This is O(c log c) but done once per file, enabling O(log c) lookups per property.
- *
- * @param comments - All comments from the AST
- * @returns Sorted array of JSDoc comments with pre-extracted line info
- */
-function prepareJsDocComments(comments) {
-    const jsDocComments = [];
-    for (const comment of comments) {
-        // Filter: Must be a block comment with JSDoc format (starts with *)
-        if (comment.type !== 'Block' || !comment.value.startsWith('*')) {
-            continue;
-        }
-        // Pre-extract line info (loc guaranteed by parse options: { loc: true })
-        jsDocComments.push({
-            comment,
-            endLine: comment.loc.end.line,
-            startLine: comment.loc.start.line,
-            endPosition: comment.range[1],
-        });
-    }
-    // Sort by end line for binary search
-    jsDocComments.sort((a, b) => a.endLine - b.endLine);
-    return jsDocComments;
-}
-/**
- * Binary search to find a JSDoc comment that ends at or near a target line.
- *
- * Returns the index of the comment with the largest endLine <= targetLine,
- * or -1 if no such comment exists.
- *
- * @param sortedComments - Comments sorted by endLine
- * @param targetLine - The line to search for
- * @returns Index of matching comment, or -1 if not found
- */
-function findCommentEndingAtLine(sortedComments, targetLine) {
-    if (sortedComments.length === 0)
-        return -1;
-    let left = 0;
-    let right = sortedComments.length - 1;
-    let result = -1;
-    while (left <= right) {
-        const mid = Math.floor((left + right) / 2);
-        const comment = sortedComments[mid];
-        if (!comment)
-            break;
-        const endLine = comment.endLine;
-        if (endLine === targetLine) {
-            // Exact match - could be multiple, find the rightmost one
-            result = mid;
-            left = mid + 1;
-        }
-        else if (endLine < targetLine) {
-            left = mid + 1;
-        }
-        else {
-            right = mid - 1;
-        }
-    }
-    return result;
-}
-/**
- * Find JSDoc comment strictly adjacent to an interface property member.
- *
- * Unlike extractPrecedingJsDoc which allows a 3-line gap, this function requires:
- * 1. Comment must be INSIDE the interface body (start line > minLine)
- * 2. Comment must end exactly at member.startLine - 1 (strictly adjacent)
- *
- * This prevents interface-level JSDoc from being misattributed to the first property
- * when the interface is tightly formatted.
- *
- * Performance: O(log c) per property when using pre-sorted comments, vs O(c) previously.
- *
- * @param sourceCode - Full source code text
- * @param member - The property member node
- * @param sortedComments - Pre-sorted JSDoc comments (call prepareJsDocComments once per file)
- * @param interfaceBodyStartLine - Line where interface body starts (the `{` line)
- * @returns JSDoc string if found, undefined otherwise
- */
-function findStrictlyAdjacentPropertyJsDoc(sourceCode, member, sortedComments, interfaceBodyStartLine) {
-    // Range and loc are guaranteed by parse options: { range: true, loc: true }
-    const memberStartLine = member.loc.start.line;
-    const memberStart = member.range[0];
-    // Property JSDoc must end exactly on the line before the property
-    const expectedCommentEndLine = memberStartLine - PROPERTY_JSDOC_MAX_GAP;
-    // Binary search for comment ending at expected line
-    const index = findCommentEndingAtLine(sortedComments, expectedCommentEndLine);
-    if (index === -1)
-        return undefined;
-    // Check all comments ending at that line (there could be multiple)
-    // Start from the found index and check backwards/forwards for exact matches
-    for (let i = index; i >= 0; i--) {
-        const entry = sortedComments[i];
-        if (entry?.endLine !== expectedCommentEndLine)
-            break;
-        // Comment must end before the member starts (character position)
-        if (entry.endPosition > memberStart)
-            continue;
-        // Comment must be INSIDE the interface body (after the opening brace line)
-        if (entry.startLine <= interfaceBodyStartLine)
-            continue;
-        // Found a valid property-level JSDoc
-        return sourceCode.slice(entry.comment.range[0], entry.comment.range[1]);
-    }
-    return undefined;
-}
-/**
- * Parse @param, @returns, and @throws tags from raw JSDoc text.
- *
- * DD-3: Handles both TypeScript-style (`@param name - desc`) and
- * JSDoc-style (`@param {Type} name desc`) formats. Multi-line tag
- * descriptions are supported — lines not starting with `@` are
- * continuations of the previous tag.
- *
- * @param rawJsDoc - Raw JSDoc text with delimiters (/** ... *\/)
- * @returns Structured param/returns/throws data
- */
-function parseJsDocTags(rawJsDoc) {
-    // Strip JSDoc delimiters and leading asterisks
-    let text = rawJsDoc.trim();
-    if (text.startsWith('/**')) {
-        text = text.slice(3);
-    }
-    if (text.endsWith('*/')) {
-        text = text.slice(0, -2);
-    }
-    const lines = text.split('\n').map((line) => {
-        let cleaned = line.trim();
-        if (cleaned.startsWith('*')) {
-            cleaned = cleaned.slice(1).trim();
-        }
-        return cleaned;
-    });
-    const params = [];
-    let returns;
-    const throws = [];
-    // Regex for @param with optional {Type}: @param {Type} name - description
-    const paramRegex = /^@param\s+(?:\{([^}]+)\}\s+)?([\w.]+)\s*(?:-\s*)?(.*)$/;
-    // Regex for @returns/@return with optional {Type}
-    const returnsRegex = /^@returns?\s+(?:\{([^}]+)\}\s+)?(.*)$/;
-    // Regex for @throws/@throw with optional {Type}
-    const throwsRegex = /^@throws?\s+(?:\{([^}]+)\}\s+)?(.*)$/;
-    let currentTag;
-    for (const line of lines) {
-        if (line.length === 0) {
-            currentTag = undefined;
-            continue;
-        }
-        // Try @param
-        const paramMatch = paramRegex.exec(line);
-        if (paramMatch) {
-            const paramName = paramMatch[2] ?? '';
-            const paramType = paramMatch[1];
-            const paramDesc = paramMatch[3] ?? '';
-            params.push({
-                name: paramName,
-                type: paramType ?? undefined,
-                description: paramDesc.trim(),
-            });
-            currentTag = { target: 'param', index: params.length - 1 };
-            continue;
-        }
-        // Try @returns
-        const returnsMatch = returnsRegex.exec(line);
-        if (returnsMatch) {
-            const retType = returnsMatch[1];
-            const retDesc = returnsMatch[2] ?? '';
-            returns = {
-                type: retType ?? undefined,
-                description: retDesc.trim(),
-            };
-            currentTag = { target: 'returns', index: 0 };
-            continue;
-        }
-        // Try @throws
-        const throwsMatch = throwsRegex.exec(line);
-        if (throwsMatch) {
-            const throwType = throwsMatch[1];
-            const throwDesc = throwsMatch[2] ?? '';
-            throws.push({
-                type: throwType ?? undefined,
-                description: throwDesc.trim(),
-            });
-            currentTag = { target: 'throws', index: throws.length - 1 };
-            continue;
-        }
-        // Any other @tag breaks the current continuation
-        if (line.startsWith('@')) {
-            currentTag = undefined;
-            continue;
-        }
-        // Continuation line for current tag
-        if (currentTag) {
-            const continuation = line.trim();
-            if (continuation.length === 0)
-                continue;
-            const paramEntry = currentTag.target === 'param' ? params[currentTag.index] : undefined;
-            const throwEntry = currentTag.target === 'throws' ? throws[currentTag.index] : undefined;
-            if (currentTag.target === 'param' && paramEntry !== undefined) {
-                params[currentTag.index] = {
-                    ...paramEntry,
-                    description: paramEntry.description.length > 0
-                        ? `${paramEntry.description} ${continuation}`
-                        : continuation,
-                };
-            }
-            else if (currentTag.target === 'returns' && returns !== undefined) {
-                returns = {
-                    ...returns,
-                    description: returns.description.length > 0
-                        ? `${returns.description} ${continuation}`
-                        : continuation,
-                };
-            }
-            else if (currentTag.target === 'throws' && throwEntry !== undefined) {
-                throws[currentTag.index] = {
-                    ...throwEntry,
-                    description: throwEntry.description.length > 0
-                        ? `${throwEntry.description} ${continuation}`
-                        : continuation,
-                };
-            }
-        }
-    }
-    return { params, returns, throws };
-}
-/**
- * Extract clean text content from a JSDoc comment.
- *
- * Removes the JSDoc delimiters (/** and *\/) and leading asterisks from each line.
- * Returns the first meaningful line as the description.
- */
-function extractJsDocText(jsDoc) {
-    // Remove /** prefix and */ suffix
-    let text = jsDoc.trim();
-    if (text.startsWith('/**')) {
-        text = text.slice(3);
-    }
-    if (text.endsWith('*/')) {
-        text = text.slice(0, -2);
-    }
-    // Split into lines and clean each line
-    const lines = text
-        .split('\n')
-        .map((line) => {
-        // Remove leading whitespace and asterisk
-        let cleaned = line.trim();
-        if (cleaned.startsWith('*')) {
-            cleaned = cleaned.slice(1).trim();
-        }
-        return cleaned;
-    })
-        .filter((line) => line.length > 0 && !line.startsWith('@')); // Skip empty and tag lines
-    // DD-2: Return all non-empty, non-tag lines joined with space (not just first line)
-    // Space-join because property JSDoc renders in table cells where newlines break formatting
-    return lines.length > 0 ? lines.join(' ') : undefined;
-}
-/**
- * DD-4: Extract all exported declarations from a file as shapes.
- *
- * Auto-discovery mode: when `@architect-extract-shapes *` is used,
- * all exported types/interfaces/enums/functions/consts are extracted
- * without requiring explicit names.
- *
- * @param sourceCode - File content
- * @returns Result with all exported shapes
- */
-function extractAllExportedShapes(sourceCode, jsx = false) {
-    // Validate input size
-    if (sourceCode.length > MAX_SOURCE_SIZE_BYTES) {
-        return Result.err(new Error(`Source code size (${sourceCode.length} bytes) exceeds maximum allowed (${MAX_SOURCE_SIZE_BYTES} bytes)`));
-    }
-    let ast;
-    try {
-        ast = parseSource(sourceCode, jsx);
-    }
-    catch (error) {
-        return Result.err(error instanceof Error ? error : new Error(`Failed to parse source code: ${String(error)}`));
-    }
-    const declarations = findDeclarations(ast);
-    const shapes = [];
-    const warnings = [];
-    // Extract best exported declaration per name (one shape per name)
-    for (const [, declarationList] of declarations) {
-        const exportedDecls = declarationList.filter((d) => d.exported);
-        if (exportedDecls.length === 0)
-            continue;
-        const best = pickBestDeclaration(exportedDecls);
-        const shape = extractShape(sourceCode, best, ast.comments ?? [], {
-            includeJsDoc: true,
-            preserveFormatting: true,
-        });
-        shapes.push(shape);
-    }
-    if (shapes.length > 50) {
-        warnings.push(`[extract-shapes] Auto-discovery extracted ${shapes.length} shapes. ` +
-            `This may indicate the file has too many exports for effective documentation.`);
-    }
-    return Result.ok({ shapes, notFound: [], imported: [], reExported: [], warnings });
-}
-/**
- * Process extract-shapes tag and return shapes for ExtractedPattern.
- *
- * Called by the document extractor when processing TypeScript files
- * with @architect-extract-shapes tags.
- *
- * DD-4: Supports wildcard `*` for auto-discovery mode.
- *
- * @param sourceCode - File content
- * @param extractShapesTag - Comma-separated shape names from tag, or `*` for auto-discovery
- * @returns Result with extracted shapes and any warnings
- */
-export function processExtractShapesTag(sourceCode, extractShapesTag, options) {
-    const jsx = options?.jsx ?? false;
-    // DD-4: Auto-shape discovery via wildcard
-    const shapeNames = extractShapesTag
-        .split(',')
-        .map((s) => s.trim())
-        .filter(Boolean);
-    const hasWildcard = shapeNames.includes('*');
-    if (hasWildcard) {
-        // Wildcard must be sole value — reject mixed case
-        if (shapeNames.length > 1) {
-            const namedShapes = shapeNames.filter((n) => n !== '*');
-            return {
-                shapes: [],
-                warnings: [
-                    `[extract-shapes] Wildcard '*' must be the sole extract-shapes value. ` +
-                        `Ignoring named shapes: ${namedShapes.join(', ')}. Use '*' alone or list specific names.`,
-                ],
-            };
-        }
-        const result = extractAllExportedShapes(sourceCode, jsx);
-        if (!result.ok) {
-            return {
-                shapes: [],
-                warnings: [`[extract-shapes] ${result.error.message}`],
-            };
-        }
-        return { shapes: [...result.value.shapes], warnings: [...result.value.warnings] };
-    }
-    const extractionResult = extractShapes(sourceCode, shapeNames, { jsx });
-    // If extraction failed (parse error), return empty shapes with error as warning
-    if (!extractionResult.ok) {
-        return {
-            shapes: [],
-            warnings: [`[extract-shapes] ${extractionResult.error.message}`],
-        };
-    }
-    const result = extractionResult.value;
-    const warnings = [...result.warnings];
-    // Collect warnings for not-found shapes
-    for (const name of result.notFound) {
-        warnings.push(`[extract-shapes] Shape '${name}' not found in file`);
-    }
-    // Collect warnings for imported shapes
-    for (const name of result.imported) {
-        warnings.push(`[extract-shapes] Shape '${name}' is imported, not defined in this file. ` +
-            `Add @architect-extract-shapes to the source file instead.`);
-    }
-    // Collect warnings for re-exported shapes with source module info
-    for (const reExport of result.reExported) {
-        const typeOnlyNote = reExport.typeOnly ? ' (type-only)' : '';
-        warnings.push(`[extract-shapes] Shape '${reExport.name}' is re-exported${typeOnlyNote} from '${reExport.sourceModule}'. ` +
-            `Add @architect-extract-shapes to ${reExport.sourceModule} instead.`);
-    }
-    return { shapes: [...result.shapes], warnings };
-}
-// =============================================================================
-// Declaration-Level Shape Discovery (DD-1, DD-2, DD-4, DD-7)
-// =============================================================================
-/**
- * Extract the @architect-shape tag from JSDoc text.
- *
- * Returns `{ tagged: true, group }` if the tag is present,
- * where `group` is `undefined` for bare tags and a string for valued tags.
- *
- * @param jsDocText - Raw JSDoc text including delimiters
- */
-function extractShapeTag(jsDocText) {
-    // Match tag with optional group name, excluding JSDoc delimiters (* and /).
-    // Negative lookahead (?!-) prevents matching hypothetical architect-shape-* tags.
-    const match = /architect-shape(?!-)(?:\s+([^\s*/]+))?/.exec(jsDocText);
-    if (!match)
-        return { tagged: false };
-    const group = match[1];
-    if (group !== undefined) {
-        return { tagged: true, group };
-    }
-    return { tagged: true };
-}
-/**
- * Extract the @architect-include tag from JSDoc text.
- *
- * Returns an array of include values if the tag is present (CSV format),
- * or `undefined` if the tag is absent. Values are trimmed and filtered for empties.
- *
- * @param jsDocText - Raw JSDoc text including delimiters
- */
-function extractIncludeTag(jsDocText) {
-    const match = /architect-include(?!-)(?:\s+([^\n@*]+))?/.exec(jsDocText);
-    if (!match)
-        return undefined;
-    const raw = match[1];
-    if (raw === undefined)
-        return undefined;
-    const values = raw
-        .split(',')
-        .map((v) => v.trim())
-        .filter((v) => v.length > 0);
-    return values.length > 0 ? values : undefined;
-}
-/**
- * Discover declarations tagged with @architect-shape in source code.
- *
- * Scans all top-level declarations (exported and non-exported per DD-7)
- * for @architect-shape tags in their preceding JSDoc. Tagged declarations
- * are extracted as shapes with an optional group from the tag value (DD-5).
- *
- * Reuses existing infrastructure: findDeclarations(), extractPrecedingJsDoc(),
- * and extractShape() — no parser changes needed (DD-2).
- *
- * @param sourceCode - TypeScript source code to scan
- * @param options - Parse options (jsx should match file extension)
- * @returns Result containing discovered shapes and warnings
- */
-export function discoverTaggedShapes(sourceCode, options) {
-    // Validate input size
-    if (sourceCode.length > MAX_SOURCE_SIZE_BYTES) {
-        return Result.err(new Error(`Source code size (${sourceCode.length} bytes) exceeds maximum allowed (${MAX_SOURCE_SIZE_BYTES} bytes)`));
-    }
-    // Parse with correct JSX mode (DD-2: stay on estree parser)
-    let ast;
-    try {
-        ast = parseSource(sourceCode, options?.jsx ?? false);
-    }
-    catch (error) {
-        return Result.err(error instanceof Error ? error : new Error(`Failed to parse source code: ${String(error)}`));
-    }
-    // DD-7: Get ALL declarations (exported + non-exported)
-    const declarations = findDeclarations(ast);
-    const comments = ast.comments ?? [];
-    const shapes = [];
-    const warnings = [];
-    for (const [, declarationList] of declarations) {
-        for (const declaration of declarationList) {
-            // Get JSDoc for this declaration (respects MAX_JSDOC_LINE_DISTANCE)
-            const jsDoc = extractPrecedingJsDoc(sourceCode, declaration.node, comments);
-            if (jsDoc === undefined)
-                continue;
-            // Check for @architect-shape tag
-            const tagResult = extractShapeTag(jsDoc);
-            if (!tagResult.tagged)
-                continue;
-            // Extract the shape using existing infrastructure
-            const shape = extractShape(sourceCode, declaration, comments, {
-                includeJsDoc: true,
-                preserveFormatting: true,
-            });
-            // DD-5: Add group field from tag value
-            // DD-3 (CrossCuttingDocumentInclusion): Add includes from @architect-include
-            const includeValues = extractIncludeTag(jsDoc);
-            shapes.push({
-                ...shape,
-                group: tagResult.group,
-                ...(includeValues !== undefined && { includes: includeValues }),
-            });
-        }
-    }
-    return Result.ok({ shapes, warnings });
-}
-//# sourceMappingURL=shape-extractor.js.map