@specferret/core 0.1.3 → 0.2.0

package/dist/extractor/typescript.js

@@ -1,153 +1,374 @@
-class TypeParser {
-    input;
-    i = 0;
-    constructor(input) {
-        this.input = input;
-    }
-    parseObject() {
-        const diagnostics = [];
-        const object = this.parseObjectType(diagnostics);
-        return { shape: object, diagnostics };
-    }
-    parseObjectType(diagnostics) {
-        this.skipWs();
-        if (this.peek() !== "{") {
-            diagnostics.push("Expected object type starting with '{'.");
-            return { type: "object", properties: {}, required: [] };
-        }
-        this.i++; // '{'
-        const properties = {};
-        const required = [];
-        while (this.i < this.input.length) {
-            this.skipWs();
-            if (this.peek() === "}") {
-                this.i++; // '}'
-                break;
-            }
-            const name = this.readIdentifier();
-            if (!name) {
-                diagnostics.push("Unable to parse property name in object type.");
-                this.advanceToDelimiter();
-                continue;
-            }
-            this.skipWs();
-            let optional = false;
-            if (this.peek() === "?") {
-                optional = true;
-                this.i++;
-            }
-            this.skipWs();
-            if (this.peek() !== ":") {
-                diagnostics.push(`Expected ':' after property '${name}'.`);
-                this.advanceToDelimiter();
-                continue;
-            }
-            this.i++; // ':'
-            this.skipWs();
-            const schema = this.parseTypeExpr(diagnostics);
-            properties[name] = schema;
-            if (!optional) {
-                required.push(name);
-            }
-            this.skipWs();
-            if (this.peek() === ";" || this.peek() === ",") {
-                this.i++;
-            }
+import Parser from 'tree-sitter';
+import tsLanguage from 'tree-sitter-typescript';
+import { CONTRACT_TYPES } from './contract-types.js';
+const parser = new Parser();
+parser.setLanguage(tsLanguage.typescript);
+function normalizeIdSegment(value) {
+    return value
+        .toLowerCase()
+        .replace(/[^a-z0-9/._-]+/g, '-')
+        .replace(/-+/g, '-')
+        .replace(/(^[-./_]+)|([-./_]+$)/g, '');
+}
+function normalizeFilePathForId(filePath) {
+    const normalized = filePath.replace(/\\/g, '/').replace(/\.[cm]?tsx?$/i, '');
+    // Prefer repository-relative paths for deterministic ids. When absolute
+    // paths are passed, keep from the first src/ segment when available.
+    if (/^[a-z]:\//i.test(normalized) || normalized.startsWith('/')) {
+        const segments = normalized.split('/').filter(Boolean);
+        const srcIndex = segments.findIndex((segment) => segment.toLowerCase() === 'src');
+        if (srcIndex >= 0) {
+            return segments.slice(srcIndex).join('/');
+        }
+        // Fallback to the last 3 path segments to reduce machine-specific prefixes.
+        return segments.slice(-3).join('/');
+    }
+    return normalized;
+}
+function inferContractType() {
+    // Inferred extraction currently emits the strict six-core-type set and
+    // defaults to `type` unless an annotation override supplies another type.
+    return 'type';
+}
+function inferContractId(filePath, symbol) {
+    const normalizedPath = normalizeFilePathForId(filePath);
+    const pathPart = normalizeIdSegment(normalizedPath) || 'source';
+    const symbolPart = normalizeIdSegment(symbol) || 'contract';
+    return `type.${pathPart}/${symbolPart}`;
+}
+function allocateDeterministicInferredId(baseId, seenCounts, allocatedIds, diagnostics, filePath, symbol) {
+    let count = (seenCounts.get(baseId) ?? 0) + 1;
+    let allocatedId = count === 1 ? baseId : `${baseId}-${count}`;
+    while (allocatedIds.has(allocatedId)) {
+        count += 1;
+        allocatedId = `${baseId}-${count}`;
+    }
+    seenCounts.set(baseId, count);
+    if (allocatedId !== baseId) {
+        diagnostics.push(`${filePath} (${symbol}): Inferred id collision for '${baseId}'. Assigned deterministic suffix '${allocatedId}'.`);
+    }
+    allocatedIds.set(allocatedId, symbol);
+    return allocatedId;
+}
+function toSchemaType(text) {
+    switch (text) {
+        case 'string':
+            return { type: 'string' };
+        case 'number':
+        case 'bigint':
+            return { type: 'number' };
+        case 'boolean':
+            return { type: 'boolean' };
+        case 'null':
+            return { type: 'null' };
+        case 'Date':
+            return { type: 'string', format: 'date-time' };
+        case 'unknown':
+        case 'any':
+            return { type: 'object' };
+        default:
+            return { type: 'object' };
+    }
+}
+function getIdentifierText(node) {
+    if (!node)
+        return null;
+    if (node.type === 'identifier' || node.type === 'property_identifier' || node.type === 'type_identifier') {
+        return node.text;
+    }
+    const idNode = node.namedChildren.find((child) => child.type === 'identifier' || child.type === 'property_identifier' || child.type === 'type_identifier');
+    return idNode ? idNode.text : null;
+}
+function extractAnnotationOverrides(filePath, content) {
+    const annotations = parseAnnotations(content);
+    const overrides = new Map();
+    const errors = [];
+    for (const annotation of annotations) {
+        const declaration = extractDeclaration(content, annotation.index);
+        if (declaration.error) {
+            errors.push(`${filePath}: ${declaration.error}`);
+            continue;
+        }
+        overrides.set(declaration.symbol, annotation);
+    }
+    return { overrides, errors };
+}
+function collectExportedDeclarations(root) {
+    const declarations = [];
+    for (const node of root.namedChildren) {
+        if (node.type !== 'export_statement') {
+            continue;
+        }
+        const declaration = node.namedChildren.find((child) => ['interface_declaration', 'type_alias_declaration', 'enum_declaration', 'function_declaration'].includes(child.type));
+        if (!declaration) {
+            continue;
+        }
+        const symbolNode = declaration.childForFieldName('name');
+        const symbol = getIdentifierText(symbolNode);
+        if (!symbol) {
+            continue;
+        }
+        if (declaration.type === 'interface_declaration') {
+            declarations.push({ kind: 'interface', symbol, node: declaration });
+            continue;
+        }
+        if (declaration.type === 'type_alias_declaration') {
+            declarations.push({ kind: 'type', symbol, node: declaration });
+            continue;
+        }
+        if (declaration.type === 'enum_declaration') {
+            declarations.push({ kind: 'enum', symbol, node: declaration });
+            continue;
+        }
+        declarations.push({ kind: 'function', symbol, node: declaration });
+    }
+    return declarations;
+}
+function findChildByType(node, types) {
+    return node.namedChildren.find((child) => types.includes(child.type)) ?? null;
+}
+function parseTypeNode(filePath, symbol, node, diagnostics) {
+    if (node.type === 'type_annotation') {
+        const inner = node.namedChildren[0];
+        if (!inner) {
+            return { type: 'object' };
+        }
+        return parseTypeNode(filePath, symbol, inner, diagnostics);
+    }
+    if (node.type === 'predefined_type') {
+        return toSchemaType(node.text);
+    }
+    if (node.type === 'type_identifier') {
+        if (node.text === 'Date') {
+            return { type: 'string', format: 'date-time' };
+        }
+        diagnostics.push(`${filePath} (${symbol}): Unsupported referenced type '${node.text}'. Falling back to object.`);
+        return { type: 'object' };
+    }
+    if (node.type === 'array_type') {
+        const element = node.namedChildren[0];
+        if (!element) {
+            diagnostics.push(`${filePath} (${symbol}): Unable to parse array element type. Falling back to object items.`);
+            return { type: 'array', items: { type: 'object' } };
         }
         return {
-            type: "object",
-            properties,
-            required,
+            type: 'array',
+            items: parseTypeNode(filePath, symbol, element, diagnostics),
         };
     }
-    parseTypeExpr(diagnostics) {
-        this.skipWs();
-        if (this.peek() === "{") {
-            return this.parseObjectType(diagnostics);
-        }
-        const ident = this.readIdentifier();
-        if (!ident) {
-            diagnostics.push("Unable to parse type expression.");
-            return { type: "object" };
-        }
-        let base;
-        switch (ident) {
-            case "string":
-                base = { type: "string" };
-                break;
-            case "number":
-                base = { type: "number" };
-                break;
-            case "boolean":
-                base = { type: "boolean" };
-                break;
-            case "Date":
-                base = { type: "string", format: "date-time" };
-                break;
-            default:
-                diagnostics.push(`Unsupported referenced type '${ident}'. Falling back to object.`);
-                base = { type: "object" };
-                break;
-        }
-        while (true) {
-            this.skipWs();
-            if (this.peek() === "[" && this.peek(1) === "]") {
-                this.i += 2;
-                base = { type: "array", items: base };
-                continue;
+    if (node.type === 'union_type') {
+        diagnostics.push(`${filePath} (${symbol}): Union types are not supported in extraction. Falling back to object.`);
+        return { type: 'object' };
+    }
+    if (node.type === 'intersection_type') {
+        diagnostics.push(`${filePath} (${symbol}): Intersection types are not supported in extraction. Falling back to object.`);
+        return { type: 'object' };
+    }
+    if (node.type === 'literal_type') {
+        const valueNode = node.namedChildren[0];
+        if (!valueNode) {
+            return { type: 'object' };
+        }
+        if (valueNode.type === 'string') {
+            return { type: 'string', enum: [valueNode.text.slice(1, -1)] };
+        }
+        if (valueNode.type === 'number') {
+            return { type: 'number', enum: [Number(valueNode.text)] };
+        }
+        if (valueNode.type === 'true' || valueNode.type === 'false') {
+            return { type: 'boolean', enum: [valueNode.type === 'true'] };
+        }
+        return { type: 'object' };
+    }
+    if (node.type === 'parenthesized_type') {
+        const inner = node.namedChildren[0];
+        if (!inner) {
+            return { type: 'object' };
+        }
+        return parseTypeNode(filePath, symbol, inner, diagnostics);
+    }
+    if (node.type === 'object_type' || node.type === 'interface_body') {
+        return parseObjectShape(filePath, symbol, node, diagnostics);
+    }
+    if (node.type === 'function_type') {
+        const parameters = node.childForFieldName('parameters');
+        const returnType = node.childForFieldName('return_type');
+        return {
+            type: 'object',
+            properties: {
+                params: parseParametersShape(filePath, symbol, parameters, diagnostics),
+                returns: returnType ? parseTypeNode(filePath, symbol, returnType, diagnostics) : { type: 'object' },
+            },
+            required: ['params', 'returns'],
+        };
+    }
+    diagnostics.push(`${filePath} (${symbol}): Unsupported node type '${node.type}'. Falling back to object.`);
+    return { type: 'object' };
+}
+function parseObjectShape(filePath, symbol, node, diagnostics) {
+    const properties = {};
+    const required = [];
+    const members = node.namedChildren;
+    for (const member of members) {
+        if (!['property_signature', 'method_signature'].includes(member.type)) {
+            diagnostics.push(`${filePath} (${symbol}): Unsupported object member type '${member.type}'. Falling back by skipping this member.`);
+            continue;
+        }
+        const nameNode = member.childForFieldName('name') ?? findChildByType(member, ['property_identifier', 'identifier', 'string']);
+        const propertyName = getIdentifierText(nameNode) ?? nameNode?.text?.replace(/^['"]|['"]$/g, '');
+        if (!propertyName) {
+            diagnostics.push(`${filePath} (${symbol}): Unable to parse property name in object type.`);
+            continue;
+        }
+        // Check for a '?' token that is a direct (unnamed) child of the member node.
+        // This correctly distinguishes optional properties (bar?: string) from required
+        // methods that happen to have optional parameters (fn(x?: string): void).
+        const optional = member.children.some((child) => !child.isNamed && child.text === '?');
+        let schema;
+        if (member.type === 'method_signature') {
+            const parameters = member.childForFieldName('parameters');
+            const returnType = member.childForFieldName('return_type');
+            schema = {
+                type: 'object',
+                properties: {
+                    params: parseParametersShape(filePath, symbol, parameters, diagnostics),
+                    returns: returnType ? parseTypeNode(filePath, symbol, returnType, diagnostics) : { type: 'object' },
+                },
+                required: ['params', 'returns'],
+            };
+        }
+        else {
+            const typeNode = member.childForFieldName('type') ??
+                member.childForFieldName('value') ??
+                findChildByType(member, [
+                    'type_annotation',
+                    'predefined_type',
+                    'type_identifier',
+                    'array_type',
+                    'union_type',
+                    'intersection_type',
+                    'object_type',
+                    'literal_type',
+                    'parenthesized_type',
+                    'function_type',
+                ]);
+            if (!typeNode) {
+                diagnostics.push(`${filePath} (${symbol}): Unable to parse type expression for property '${propertyName}'.`);
+                schema = { type: 'object' };
             }
-            break;
-        }
-        this.skipWs();
-        if (this.peek() === "|") {
-            diagnostics.push("Union types are not supported in Sprint 3 extraction.");
-            while (this.i < this.input.length) {
-                const ch = this.peek();
-                if (ch === ";" || ch === "," || ch === "}" || ch === "\n") {
-                    break;
-                }
-                this.i++;
+            else {
+                schema = parseTypeNode(filePath, symbol, typeNode, diagnostics);
             }
         }
-        return base;
+        properties[propertyName] = schema;
+        if (!optional) {
+            required.push(propertyName);
+        }
     }
-    readIdentifier() {
-        this.skipWs();
-        const start = this.i;
-        while (this.i < this.input.length) {
-            const ch = this.input[this.i];
-            const ok = /[A-Za-z0-9_]/.test(ch);
-            if (!ok) {
-                break;
-            }
-            this.i++;
+    return {
+        type: 'object',
+        properties,
+        required,
+    };
+}
+function parseParametersShape(filePath, symbol, parametersNode, diagnostics) {
+    if (!parametersNode) {
+        return { type: 'object', properties: {}, required: [] };
+    }
+    const properties = {};
+    const required = [];
+    for (const parameter of parametersNode.namedChildren) {
+        if (!['required_parameter', 'optional_parameter', 'rest_parameter'].includes(parameter.type)) {
+            continue;
+        }
+        const nameNode = parameter.childForFieldName('pattern') ??
+            parameter.childForFieldName('name') ??
+            // rest_parameter exposes its identifier as a direct named child with no field name
+            parameter.namedChildren.find((c) => c.type === 'identifier') ??
+            null;
+        const parameterName = getIdentifierText(nameNode) ?? 'arg';
+        const typeNode = parameter.childForFieldName('type') ??
+            findChildByType(parameter, [
+                'type_annotation',
+                'predefined_type',
+                'type_identifier',
+                'array_type',
+                'union_type',
+                'intersection_type',
+                'object_type',
+            ]);
+        properties[parameterName] = typeNode ? parseTypeNode(filePath, symbol, typeNode, diagnostics) : { type: 'object' };
+        // A rest parameter is represented as required_parameter with a rest_pattern child.
+        // It can be called with zero arguments, so it must not appear in required[].
+        const isRestParameter = parameter.namedChildren.some((c) => c.type === 'rest_pattern');
+        if (parameter.type !== 'optional_parameter' && parameter.type !== 'rest_parameter' && !isRestParameter) {
+            required.push(parameterName);
         }
-        return this.input.slice(start, this.i);
     }
-    skipWs() {
-        while (this.i < this.input.length) {
-            const ch = this.input[this.i];
-            if (!/\s/.test(ch)) {
-                break;
-            }
-            this.i++;
+    return {
+        type: 'object',
+        properties,
+        required,
+    };
+}
+function parseEnumShape(node) {
+    const body = node.childForFieldName('body') ?? findChildByType(node, ['enum_body']);
+    if (!body) {
+        return { type: 'string', enum: [] };
+    }
+    const values = body.namedChildren
+        .map((child) => {
+        // Bare member: Admin
+        if (child.type === 'property_identifier' || child.type === 'identifier') {
+            return child.text;
         }
+        // Valued member: Admin = "admin" or Admin = 1
+        if (child.type === 'enum_assignment') {
+            const nameChild = child.namedChildren.find((c) => c.type === 'property_identifier' || c.type === 'identifier');
+            return nameChild?.text ?? null;
+        }
+        return null;
+    })
+        .filter((v) => v !== null);
+    return {
+        type: 'string',
+        enum: values,
+    };
+}
+function parseDeclarationShape(filePath, declaration, diagnostics) {
+    if (declaration.kind === 'interface') {
+        const body = declaration.node.childForFieldName('body') ?? findChildByType(declaration.node, ['interface_body']);
+        if (!body) {
+            diagnostics.push(`${filePath} (${declaration.symbol}): Interface body was not found. Falling back to object.`);
+            return { type: 'object', properties: {}, required: [] };
+        }
+        return parseObjectShape(filePath, declaration.symbol, body, diagnostics);
     }
-    advanceToDelimiter() {
-        while (this.i < this.input.length) {
-            const ch = this.input[this.i];
-            if (ch === ";" || ch === "\n" || ch === "}") {
-                return;
-            }
-            this.i++;
+    if (declaration.kind === 'type') {
+        const valueNode = declaration.node.childForFieldName('value') ?? declaration.node.namedChildren.at(-1);
+        if (!valueNode) {
+            diagnostics.push(`${filePath} (${declaration.symbol}): Type alias value was not found. Falling back to object.`);
+            return { type: 'object' };
         }
+        return parseTypeNode(filePath, declaration.symbol, valueNode, diagnostics);
     }
-    peek(offset = 0) {
-        return this.input[this.i + offset] ?? "";
+    if (declaration.kind === 'enum') {
+        return parseEnumShape(declaration.node);
     }
+    const parameters = declaration.node.childForFieldName('parameters');
+    const returnType = declaration.node.childForFieldName('return_type');
+    return {
+        type: 'object',
+        properties: {
+            params: parseParametersShape(filePath, declaration.symbol, parameters, diagnostics),
+            returns: returnType ? parseTypeNode(filePath, declaration.symbol, returnType, diagnostics) : { type: 'object' },
+        },
+        required: ['params', 'returns'],
+    };
 }
 function parseAnnotations(content) {
-    const pattern = /^\s*\/\/\s*@ferret-contract:\s*([^\s]+)\s+(api|table|type|event|flow|config)\s*$/gm;
+    const contractTypePattern = CONTRACT_TYPES.join('|');
+    const pattern = new RegExp(`^\\s*//\\s*@ferret-contract:\\s*([^\\s]+)\\s+(${contractTypePattern})\\s*$`, 'gm');
     const out = [];
     let match;
     while ((match = pattern.exec(content)) !== null) {
@@ -161,72 +382,69 @@ function parseAnnotations(content) {
 }
 function extractDeclaration(content, start) {
     const tail = content.slice(start);
-    const decl = /(?:export\s+)?(interface|type)\s+([A-Za-z0-9_]+)\s*(?:=)?\s*/m.exec(tail);
-    if (!decl || decl.index === undefined) {
-        return {
-            symbol: "unknown",
-            objectBody: "",
-            error: "No interface/type declaration found after annotation.",
-        };
-    }
-    const symbol = decl[2];
-    const offset = start + decl.index + decl[0].length;
-    const bodyStart = content.indexOf("{", offset);
-    if (bodyStart === -1) {
-        return {
-            symbol,
-            objectBody: "",
-            error: `Declaration '${symbol}' is not an object-like type.`,
-        };
-    }
-    let depth = 0;
-    let end = -1;
-    for (let i = bodyStart; i < content.length; i++) {
-        const ch = content[i];
-        if (ch === "{")
-            depth++;
-        if (ch === "}") {
-            depth--;
-            if (depth === 0) {
-                end = i;
-                break;
-            }
-        }
-    }
-    if (end === -1) {
+    const decl = /(?:export\s+)?(interface|type)\s+([A-Za-z0-9_]+)/m.exec(tail);
+    if (!decl) {
         return {
-            symbol,
-            objectBody: "",
-            error: `Unclosed object type for declaration '${symbol}'.`,
+            symbol: 'unknown',
+            error: 'No interface/type declaration found after annotation.',
         };
     }
-    const objectBody = content.slice(bodyStart, end + 1);
-    return { symbol, objectBody };
+    return { symbol: decl[2] };
 }
 export function extractContractsFromTypeScript(filePath, content) {
-    const annotations = parseAnnotations(content);
+    const annotationResult = extractAnnotationOverrides(filePath, content);
+    const annotationOverrides = annotationResult.overrides;
     const contracts = [];
+    const inferredIdCounts = new Map();
+    const allocatedIds = new Map();
+    const errors = [...annotationResult.errors];
     const diagnostics = [];
-    for (const annotation of annotations) {
-        const declaration = extractDeclaration(content, annotation.index);
-        if (declaration.error) {
-            diagnostics.push(`${filePath}: ${declaration.error}`);
-            continue;
+    let tree;
+    try {
+        tree = parser.parse(content);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : 'Unknown parse error.';
+        errors.push(`${filePath}: Tree-sitter parse failed: ${message}`);
+        return { contracts, errors, diagnostics };
+    }
+    if (tree.rootNode.hasError) {
+        diagnostics.push(`${filePath}: Tree-sitter detected syntax errors; extraction may be partial.`);
+    }
+    const declarations = collectExportedDeclarations(tree.rootNode);
+    for (const declaration of declarations) {
+        const shape = parseDeclarationShape(filePath, declaration, diagnostics);
+        const override = annotationOverrides.get(declaration.symbol);
+        let allocatedId;
+        if (override?.id) {
+            const existingOwner = allocatedIds.get(override.id);
+            if (existingOwner && existingOwner !== declaration.symbol) {
+                errors.push(`${filePath} (${declaration.symbol}): Annotation id '${override.id}' duplicates id already used by '${existingOwner}'.`);
+                continue;
+            }
+            allocatedId = override.id;
+            allocatedIds.set(allocatedId, declaration.symbol);
         }
-        const parser = new TypeParser(declaration.objectBody);
-        const { shape, diagnostics: parserDiagnostics } = parser.parseObject();
-        for (const d of parserDiagnostics) {
-            diagnostics.push(`${filePath} (${declaration.symbol}): ${d}`);
+        else {
+            const inferredId = inferContractId(filePath, declaration.symbol);
+            allocatedId = allocateDeterministicInferredId(inferredId, inferredIdCounts, allocatedIds, diagnostics, filePath, declaration.symbol);
         }
         contracts.push({
-            id: annotation.id,
-            type: annotation.type,
+            id: allocatedId,
+            type: override?.type ?? inferContractType(),
             shape,
             sourceSymbol: declaration.symbol,
             filePath,
+            idSource: override?.id ? 'annotated' : 'inferred',
         });
     }
-    contracts.sort((a, b) => a.id.localeCompare(b.id));
-    return { contracts, diagnostics };
+    for (const [symbol, annotation] of annotationOverrides.entries()) {
+        if (contracts.some((contract) => contract.sourceSymbol === symbol)) {
+            continue;
+        }
+        errors.push(`${filePath}: Annotation for '${annotation.id}' did not match an exported declaration.`);
+    }
+    contracts.sort((a, b) => (a.id === b.id ? a.sourceSymbol.localeCompare(b.sourceSymbol) : a.id.localeCompare(b.id)));
+    return { contracts, errors, diagnostics };
 }
 //# sourceMappingURL=typescript.js.map