@pithyjs/codex 0.1.0-beta.0

package/dist/extraction/type-extractor.js

@@ -0,0 +1,494 @@
+/**
+ * @codex
+ * {
+ *   "id": "pithy.codex.extraction.type-extractor",
+ *   "title": "TypeScript Type Extractor",
+ *   "category": "compiler"
+ * }
+ */
+import ts from 'typescript';
+/**
+ * @codexApi {"parent":"pithy.codex.extraction.type-extractor","name":"extractTypesFromFile","stability":"stable","signature":"(filePath: string, content: string) => ExtractedTypeDefinition[]"}
+ *
+ * Extracts type definitions from a TypeScript file using the TypeScript Compiler API
+ * @param filePath - Path to the TypeScript file
+ * @param content - Content of the file
+ * @returns Array of extracted type definitions
+ */
+export function extractTypesFromFile(filePath, content) {
+    const types = [];
+    // Create a source file
+    const sourceFile = ts.createSourceFile(filePath, content, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+    // Visit all nodes
+    function visit(node) {
+        if (ts.isInterfaceDeclaration(node)) {
+            types.push(extractInterface(node, sourceFile, filePath));
+        }
+        else if (ts.isTypeAliasDeclaration(node)) {
+            types.push(extractTypeAlias(node, sourceFile, filePath));
+        }
+        else if (ts.isEnumDeclaration(node)) {
+            types.push(extractEnum(node, sourceFile, filePath));
+        }
+        else if (ts.isClassDeclaration(node) && node.name) {
+            types.push(extractClass(node, sourceFile, filePath));
+        }
+        ts.forEachChild(node, visit);
+    }
+    visit(sourceFile);
+    return types;
+}
+/**
+ * Extracts an interface declaration
+ */
+function extractInterface(node, sourceFile, filePath) {
+    const name = node.name.text;
+    const exported = hasExportModifier(node);
+    const location = getSourceLocation(node, sourceFile, filePath);
+    // Extract generics
+    const generics = node.typeParameters?.map(tp => tp.getText(sourceFile));
+    // Extract extends
+    const extendsClause = node.heritageClauses?.find(hc => hc.token === ts.SyntaxKind.ExtendsKeyword);
+    const extendsTypes = extendsClause?.types.map(t => t.getText(sourceFile));
+    // Extract members
+    const members = node.members.map(member => extractMember(member, sourceFile));
+    // Extract JSDoc
+    const jsdoc = extractJSDocFromNode(node, sourceFile, filePath);
+    return {
+        name,
+        kind: 'interface',
+        exported,
+        generics,
+        extends: extendsTypes,
+        members,
+        jsdoc,
+        location,
+    };
+}
+/**
+ * Extracts a type alias declaration
+ */
+function extractTypeAlias(node, sourceFile, filePath) {
+    const name = node.name.text;
+    const exported = hasExportModifier(node);
+    const location = getSourceLocation(node, sourceFile, filePath);
+    // Extract generics
+    const generics = node.typeParameters?.map(tp => tp.getText(sourceFile));
+    // For type aliases, we represent the type as a single "member"
+    const members = [];
+    // If it's an object type literal, extract its properties
+    if (ts.isTypeLiteralNode(node.type)) {
+        for (const member of node.type.members) {
+            members.push(extractMember(member, sourceFile));
+        }
+    }
+    else {
+        // For other types (union, intersection, etc.), store the full type as a special member
+        members.push({
+            name: '__type',
+            type: node.type.getText(sourceFile),
+            optional: false,
+            readonly: false,
+        });
+    }
+    const jsdoc = extractJSDocFromNode(node, sourceFile, filePath);
+    return {
+        name,
+        kind: 'type',
+        exported,
+        generics,
+        members,
+        jsdoc,
+        location,
+    };
+}
+/**
+ * Extracts an enum declaration
+ */
+function extractEnum(node, sourceFile, filePath) {
+    const name = node.name.text;
+    const exported = hasExportModifier(node);
+    const location = getSourceLocation(node, sourceFile, filePath);
+    // Extract enum members
+    const members = node.members.map(member => {
+        const memberName = ts.isIdentifier(member.name)
+            ? member.name.text
+            : member.name.getText(sourceFile);
+        const value = member.initializer?.getText(sourceFile) || '';
+        return {
+            name: memberName,
+            type: value || 'auto',
+            optional: false,
+            readonly: true,
+        };
+    });
+    const jsdoc = extractJSDocFromNode(node, sourceFile, filePath);
+    return {
+        name,
+        kind: 'enum',
+        exported,
+        members,
+        jsdoc,
+        location,
+    };
+}
+/**
+ * Extracts a class declaration
+ */
+function extractClass(node, sourceFile, filePath) {
+    const name = node.name?.text || 'AnonymousClass';
+    const exported = hasExportModifier(node);
+    const location = getSourceLocation(node, sourceFile, filePath);
+    // Extract generics
+    const generics = node.typeParameters?.map(tp => tp.getText(sourceFile));
+    // Extract extends
+    const extendsClause = node.heritageClauses?.find(hc => hc.token === ts.SyntaxKind.ExtendsKeyword);
+    const extendsTypes = extendsClause?.types.map(t => t.getText(sourceFile));
+    // Extract implements
+    const implementsClause = node.heritageClauses?.find(hc => hc.token === ts.SyntaxKind.ImplementsKeyword);
+    const implementsTypes = implementsClause?.types.map(t => t.getText(sourceFile));
+    // Extract public members only (skip private, protected, and #private)
+    const members = [];
+    for (const member of node.members) {
+        if (hasPrivateModifier(member))
+            continue;
+        if (hasProtectedModifier(member))
+            continue;
+        // Skip ECMAScript #private fields/methods
+        if (member.name && ts.isPrivateIdentifier(member.name))
+            continue;
+        if (ts.isPropertyDeclaration(member) ||
+            ts.isMethodDeclaration(member) ||
+            ts.isGetAccessor(member) ||
+            ts.isSetAccessor(member)) {
+            members.push(extractClassMember(member, sourceFile));
+        }
+    }
+    const jsdoc = extractJSDocFromNode(node, sourceFile, filePath);
+    return {
+        name,
+        kind: 'class',
+        exported,
+        generics,
+        extends: extendsTypes,
+        implements: implementsTypes,
+        members,
+        jsdoc,
+        location,
+    };
+}
+/**
+ * Extracts a member from an interface/type literal
+ */
+function extractMember(member, sourceFile) {
+    if (ts.isPropertySignature(member)) {
+        const name = member.name.getText(sourceFile);
+        const type = member.type?.getText(sourceFile) || 'unknown';
+        const optional = !!member.questionToken;
+        const readonly = hasReadonlyModifier(member);
+        const description = getJSDocDescription(member, sourceFile);
+        return { name, type, optional, readonly, description };
+    }
+    if (ts.isMethodSignature(member)) {
+        const name = member.name.getText(sourceFile);
+        const signature = member.getText(sourceFile);
+        const optional = !!member.questionToken;
+        const description = getJSDocDescription(member, sourceFile);
+        return {
+            name,
+            type: 'method',
+            optional,
+            readonly: false,
+            signature,
+            description,
+        };
+    }
+    if (ts.isIndexSignatureDeclaration(member)) {
+        return {
+            name: '[index]',
+            type: member.type?.getText(sourceFile) || 'unknown',
+            optional: false,
+            readonly: hasReadonlyModifier(member),
+        };
+    }
+    // Fallback
+    return {
+        name: member.getText(sourceFile).slice(0, 50),
+        type: 'unknown',
+        optional: false,
+        readonly: false,
+    };
+}
+/**
+ * Builds a signature string for a class method/getter/setter without the body.
+ */
+function buildClassMemberSignature(member, sourceFile) {
+    const name = member.name.getText(sourceFile);
+    if (ts.isGetAccessor(member)) {
+        const returnType = member.type
+            ? `: ${member.type.getText(sourceFile)}`
+            : '';
+        return `get ${name}()${returnType}`;
+    }
+    if (ts.isSetAccessor(member)) {
+        const params = member.parameters.map(p => p.getText(sourceFile)).join(', ');
+        return `set ${name}(${params})`;
+    }
+    // Method declaration
+    const typeParams = member.typeParameters
+        ? `<${member.typeParameters.map(tp => tp.getText(sourceFile)).join(', ')}>`
+        : '';
+    const params = member.parameters.map(p => p.getText(sourceFile)).join(', ');
+    const returnType = member.type ? `: ${member.type.getText(sourceFile)}` : '';
+    return `${name}${typeParams}(${params})${returnType}`;
+}
+/**
+ * Extracts a class member
+ */
+function extractClassMember(member, sourceFile) {
+    const name = member.name.getText(sourceFile);
+    const optional = ts.isPropertyDeclaration(member) && !!member.questionToken;
+    const readonly = hasReadonlyModifier(member);
+    const description = getJSDocDescription(member, sourceFile);
+    if (ts.isMethodDeclaration(member) ||
+        ts.isGetAccessor(member) ||
+        ts.isSetAccessor(member)) {
+        const signature = buildClassMemberSignature(member, sourceFile);
+        return {
+            name,
+            type: ts.isGetAccessor(member)
+                ? 'getter'
+                : ts.isSetAccessor(member)
+                    ? 'setter'
+                    : 'method',
+            optional,
+            readonly,
+            signature,
+            description,
+        };
+    }
+    const type = member.type?.getText(sourceFile) || 'unknown';
+    return { name, type, optional, readonly, description };
+}
+/**
+ * Gets source location from a node
+ */
+function getSourceLocation(node, sourceFile, filePath) {
+    const { line, character } = sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile));
+    const endPos = sourceFile.getLineAndCharacterOfPosition(node.getEnd());
+    return {
+        file: filePath,
+        line: line + 1, // 1-indexed
+        column: character + 1,
+        endLine: endPos.line + 1,
+        endColumn: endPos.character + 1,
+    };
+}
+/**
+ * Checks if a node has the export modifier
+ */
+function hasExportModifier(node) {
+    const modifiers = ts.canHaveModifiers(node)
+        ? ts.getModifiers(node)
+        : undefined;
+    return modifiers?.some(m => m.kind === ts.SyntaxKind.ExportKeyword) || false;
+}
+/**
+ * Checks if a node has the private modifier
+ */
+function hasPrivateModifier(node) {
+    const modifiers = ts.canHaveModifiers(node)
+        ? ts.getModifiers(node)
+        : undefined;
+    return modifiers?.some(m => m.kind === ts.SyntaxKind.PrivateKeyword) || false;
+}
+/**
+ * Checks if a node has the protected modifier
+ */
+function hasProtectedModifier(node) {
+    const modifiers = ts.canHaveModifiers(node)
+        ? ts.getModifiers(node)
+        : undefined;
+    return (modifiers?.some(m => m.kind === ts.SyntaxKind.ProtectedKeyword) || false);
+}
+/**
+ * Checks if a node has the readonly modifier
+ */
+function hasReadonlyModifier(node) {
+    const modifiers = ts.canHaveModifiers(node)
+        ? ts.getModifiers(node)
+        : undefined;
+    return (modifiers?.some(m => m.kind === ts.SyntaxKind.ReadonlyKeyword) || false);
+}
+/**
+ * Gets the JSDoc description from a node
+ */
+function getJSDocDescription(node, sourceFile) {
+    const jsDocs = ts.getJSDocCommentsAndTags(node);
+    for (const doc of jsDocs) {
+        if (ts.isJSDoc(doc) && doc.comment) {
+            if (typeof doc.comment === 'string') {
+                return doc.comment;
+            }
+            return doc.comment.map(c => c.getText(sourceFile)).join('');
+        }
+    }
+    return undefined;
+}
+/**
+ * Extracts a comment string from a JSDoc comment node
+ */
+function extractCommentText(comment, sourceFile) {
+    if (!comment)
+        return '';
+    if (typeof comment === 'string')
+        return comment;
+    return comment.map(c => c.getText(sourceFile)).join('');
+}
+/**
+ * Extracts JSDoc from a node into our ParsedJSDoc format,
+ * including @param, @returns, @throws, @see, @since, @deprecated, and @example tags.
+ */
+function extractJSDocFromNode(node, sourceFile, filePath) {
+    const jsDocs = ts.getJSDocCommentsAndTags(node);
+    for (const doc of jsDocs) {
+        if (!ts.isJSDoc(doc))
+            continue;
+        const location = getSourceLocation(doc, sourceFile, filePath);
+        const description = extractCommentText(doc.comment, sourceFile);
+        const params = [];
+        const examples = [];
+        const tags = {};
+        let returns;
+        const throws = [];
+        const see = [];
+        let since;
+        let deprecated;
+        if (doc.tags) {
+            for (const tag of doc.tags) {
+                const tagName = tag.tagName.text;
+                const tagComment = extractCommentText(tag.comment, sourceFile);
+                switch (tagName) {
+                    case 'param': {
+                        if (ts.isJSDocParameterTag(tag)) {
+                            params.push({
+                                name: tag.name.getText(sourceFile),
+                                type: tag.typeExpression?.getText(sourceFile),
+                                description: tagComment,
+                                optional: tag.isBracketed,
+                            });
+                        }
+                        break;
+                    }
+                    case 'returns':
+                    case 'return':
+                        returns = {
+                            type: tag.typeExpression?.getText(sourceFile),
+                            description: tagComment,
+                        };
+                        break;
+                    case 'throws':
+                    case 'exception':
+                        throws.push(tagComment);
+                        break;
+                    case 'see':
+                        see.push(tagComment);
+                        break;
+                    case 'since':
+                        since = tagComment;
+                        break;
+                    case 'deprecated':
+                        deprecated = tagComment || true;
+                        break;
+                    case 'example':
+                        examples.push({
+                            code: tagComment,
+                            language: 'typescript',
+                            runnable: false,
+                            isDoctest: false,
+                            location: getSourceLocation(tag, sourceFile, filePath),
+                        });
+                        break;
+                    default:
+                        if (!tags[tagName])
+                            tags[tagName] = [];
+                        tags[tagName].push(tagComment);
+                        break;
+                }
+            }
+        }
+        return {
+            description,
+            params,
+            returns,
+            examples,
+            throws: throws.length > 0 ? throws : undefined,
+            see: see.length > 0 ? see : undefined,
+            since,
+            deprecated,
+            tags,
+            location,
+        };
+    }
+    return undefined;
+}
+/**
+ * @codexApi {"parent":"pithy.codex.extraction.type-extractor","name":"getTypeSignature","stability":"stable","signature":"(def: ExtractedTypeDefinition) => string"}
+ *
+ * Generates a human-readable signature for a type definition
+ * @param def - The extracted type definition
+ * @returns Formatted type signature
+ */
+export function getTypeSignature(def) {
+    const exportPrefix = def.exported ? 'export ' : '';
+    const genericsStr = def.generics?.length
+        ? `<${def.generics.join(', ')}>`
+        : '';
+    const extendsStr = def.extends?.length
+        ? ` extends ${def.extends.join(', ')}`
+        : '';
+    const implementsStr = def.implements?.length
+        ? ` implements ${def.implements.join(', ')}`
+        : '';
+    switch (def.kind) {
+        case 'interface':
+            return `${exportPrefix}interface ${def.name}${genericsStr}${extendsStr}`;
+        case 'type':
+            return `${exportPrefix}type ${def.name}${genericsStr}`;
+        case 'enum':
+            return `${exportPrefix}enum ${def.name}`;
+        case 'class':
+            return `${exportPrefix}class ${def.name}${genericsStr}${extendsStr}${implementsStr}`;
+        default:
+            return def.name;
+    }
+}
+/**
+ * @codexApi {"parent":"pithy.codex.extraction.type-extractor","name":"generateMethodTable","stability":"stable","signature":"(def: ExtractedTypeDefinition) => string"}
+ *
+ * Generates a markdown table of members for documentation
+ * @param def - The extracted type definition
+ * @returns Markdown table string
+ */
+export function generateMethodTable(def) {
+    if (def.members.length === 0)
+        return '';
+    const lines = [
+        '| Member | Type | Description |',
+        '|--------|------|-------------|',
+    ];
+    for (const member of def.members) {
+        let nameCol = member.name;
+        if (member.readonly) {
+            nameCol = `readonly ${nameCol}`;
+        }
+        if (member.optional) {
+            nameCol = `${nameCol}?`;
+        }
+        const typeCol = member.signature || member.type;
+        const rawDesc = member.description ?? '';
+        const descCol = rawDesc.replace(/\|/g, '\\|').replace(/\r?\n/g, '<br/>');
+        lines.push(`| \`${nameCol}\` | \`${typeCol}\` | ${descCol} |`);
+    }
+    return lines.join('\n');
+}