ucn 4.2.3 → 5.0.2

package/core/index-ir.js

@@ -0,0 +1,138 @@
+'use strict';
+
+/**
+ * Convert normalized language IR into the persisted ProjectIndex shape.
+ *
+ * This is the only translation boundary used by sequential and worker builds.
+ * Keeping it data-only prevents the two build paths from silently dropping
+ * parser fields or changing symbol/binding behavior.
+ */
+
+function createImportBindings(imports) {
+    return imports.flatMap(item => (item.names || [])
+        .filter(name => name && name !== '*' && name !== '_' && name !== '.')
+        .map(name => {
+            const rename = (item.renames || []).find(candidate => candidate.original === name);
+            return {
+                name,
+                module: item.module,
+                ...(item.line != null && { line: item.line }),
+                ...(rename && { alias: rename.local }),
+                ...(item.defaultLike && { defaultLike: true }),
+            };
+        }));
+}
+
+function createFileEntryFromIR({
+    ir,
+    filePath,
+    relativePath,
+    hash,
+    mtime,
+    size,
+    lineCount,
+    isBundled = false,
+    isGenerated = false,
+}) {
+    const imports = ir.imports || [];
+    const exports = ir.exports || [];
+    return {
+        path: filePath,
+        relativePath,
+        language: ir.language,
+        lines: lineCount,
+        hash,
+        mtime,
+        size,
+        imports: imports.map(item => item.module),
+        globalImports: imports.filter(item => item.global).map(item => item.module),
+        importNames: imports.flatMap(item => item.names || []),
+        importBindings: createImportBindings(imports),
+        exports: exports.map(item => item.name),
+        exportDetails: exports,
+        symbols: [],
+        bindings: [],
+        dynamicImports: ir.dynamicImports || 0,
+        ...(ir.diagnostics?.parseRecovery && { parseRecovery: true }),
+        ...(ir.importAliases && { importAliases: ir.importAliases }),
+        ...(ir.moduleAssignedNames?.length > 0 && {
+            moduleAssignedNames: ir.moduleAssignedNames,
+        }),
+        ...(isBundled && { isBundled: true }),
+        ...(isGenerated && { isGenerated: true }),
+    };
+}
+
+const OPTIONAL_SYMBOL_FIELDS = Object.freeze([
+    'returnedFunctionResult', 'isFunctionVariable', 'paramTypes', 'isAsync',
+    'isGenerator', 'generics', 'extends', 'implements', 'indent', 'isNested',
+    'enclosingType', 'isMethod', 'receiver', 'memberType', 'fieldType',
+    'aliasOf', 'derefTarget', 'decorators', 'decoratorsWithArgs',
+    'annotationsWithArgs', 'attributesWithArgs', 'nameLine', 'traitImpl',
+    'traitName', 'isSignature', 'memberAssigned', 'bodyScopedName',
+    'registryMember', 'registryContainer', 'namespace',
+    'isExtensionMethod', 'extensionReceiver', 'explicitInterface',
+    'lexicalScopeStartLine', 'lexicalScopeEndLine',
+    'returnTypeQualifier', 'macroNeverReturns', 'callbackParamTypes', 'iteratorItemType',
+    'returnedConcreteType', 'returnedConstructors', 'templateDependent',
+    'linkage', 'functionLike',
+]);
+
+function materializeSymbol(fileEntry, item) {
+    const symbol = {
+        name: item.name,
+        type: item.kind,
+        file: fileEntry.path,
+        relativePath: fileEntry.relativePath,
+        startLine: item.startLine,
+        endLine: item.endLine,
+        params: item.params,
+        paramsStructured: item.paramsStructured,
+        returnType: item.returnType,
+        modifiers: item.modifiers,
+        docstring: item.docstring,
+        bindingId: `${fileEntry.relativePath}:${item.kind}:${item.startLine}`,
+        ...(item.owner && { className: item.owner }),
+    };
+    for (const field of OPTIONAL_SYMBOL_FIELDS) {
+        if (item[field] === undefined || item[field] === null) continue;
+        if (Array.isArray(item[field]) && item[field].length === 0) continue;
+        // Most false feature flags are omitted for compactness, but
+        // functionLike=false is the semantic distinction between an
+        // object-like macro and a callable macro (UCN5-170).
+        if (item[field] === false && field !== 'functionLike') continue;
+        symbol[field] = item[field];
+    }
+    return symbol;
+}
+
+function addIRSymbol(fileEntry, item, symbolTable = null) {
+    const symbol = materializeSymbol(fileEntry, item);
+    fileEntry.symbols.push(symbol);
+    if (!item.memberAssigned && !item.bodyScopedName) {
+        fileEntry.bindings.push({
+            id: symbol.bindingId,
+            name: symbol.name,
+            type: symbol.type,
+            startLine: symbol.startLine,
+        });
+    }
+    if (symbolTable) {
+        if (!symbolTable.has(symbol.name)) symbolTable.set(symbol.name, []);
+        symbolTable.get(symbol.name).push(symbol);
+    }
+    return symbol;
+}
+
+function populateFileEntryFromIR(fileEntry, ir, symbolTable = null) {
+    for (const symbol of ir.symbols) addIRSymbol(fileEntry, symbol, symbolTable);
+    return fileEntry;
+}
+
+module.exports = {
+    createImportBindings,
+    createFileEntryFromIR,
+    materializeSymbol,
+    addIRSymbol,
+    populateFileEntryFromIR,
+};

package/core/ir.js

@@ -0,0 +1,195 @@
+'use strict';
+
+/**
+ * Normalized language-analysis boundary for v5.
+ *
+ * ProjectIndex and build workers consume this shape directly. Language
+ * adapters must not leak tree-sitter nodes or raw parser-module objects across
+ * this boundary. The shape is deliberately data-only and versioned.
+ */
+
+const IR_SCHEMA_VERSION = 1;
+const EVIDENCE_TIERS = Object.freeze(['confirmed', 'unverified', 'excluded']);
+
+function normalizeSymbol(symbol, family, language, kind, owner = null) {
+    let normalizedOwner = owner || symbol.className || null;
+    if (!normalizedOwner && symbol.receiver && family === 'callable') {
+        // Go and some Rust parser records expose methods as top-level
+        // functions with a receiver. Normalize their owning type here so
+        // every index consumer sees the same method identity.
+        normalizedOwner = String(symbol.receiver)
+            .replace(/^[*&]\s*/, '')
+            .replace(/^mut\s+/, '')
+            .replace(/<.*$/, '')
+            .trim();
+        if (normalizedOwner === 'self' || normalizedOwner === 'Self') {
+            normalizedOwner = null;
+        }
+    }
+    const normalized = {
+        id: symbol.bindingId || null,
+        name: symbol.name,
+        kind,
+        family,
+        language,
+        startLine: symbol.startLine,
+        endLine: symbol.endLine,
+        ...(normalizedOwner && { owner: normalizedOwner }),
+        ...(symbol.receiver && { receiver: symbol.receiver }),
+        ...(symbol.params !== undefined && { params: symbol.params }),
+        ...(symbol.paramsStructured && { paramsStructured: symbol.paramsStructured }),
+        ...(symbol.returnType && { returnType: symbol.returnType }),
+        modifiers: [...(symbol.modifiers || [])],
+    };
+    const passthrough = [
+        'docstring', 'returnedFunctionResult', 'isFunctionVariable', 'paramTypes',
+        'isAsync', 'isGenerator', 'generics', 'extends', 'implements', 'indent',
+        'isNested', 'enclosingType', 'isMethod', 'memberType', 'fieldType',
+        'aliasOf', 'derefTarget', 'decorators', 'decoratorsWithArgs',
+        'annotationsWithArgs', 'attributesWithArgs', 'nameLine', 'traitImpl',
+        'traitName', 'isSignature', 'memberAssigned', 'bodyScopedName',
+        'registryMember', 'registryContainer', 'isConstructor',
+        'isExtensionMethod', 'extensionReceiver', 'explicitInterface',
+        'namespace', 'lexicalScopeStartLine', 'lexicalScopeEndLine',
+        'returnTypeQualifier', 'macroNeverReturns', 'callbackParamTypes', 'iteratorItemType',
+        'returnedConcreteType', 'returnedConstructors', 'templateDependent',
+        'linkage', 'functionLike',
+    ];
+    for (const field of passthrough) {
+        if (symbol[field] !== undefined && symbol[field] !== null) {
+            normalized[field] = Array.isArray(symbol[field])
+                ? [...symbol[field]]
+                : symbol[field];
+        }
+    }
+    return normalized;
+}
+
+function createFileIR({
+    language,
+    file = null,
+    parsed = {},
+    calls = [],
+    capabilities = {},
+} = {}) {
+    const functions = parsed.functions || [];
+    const classes = parsed.classes || [];
+    const stateObjects = parsed.stateObjects || [];
+    const macros = parsed.macros || [];
+    const normalizedSymbols = [];
+    const seen = new Set();
+    const append = (symbol, family, kind, owner = null) => {
+        const key = `${owner || symbol.className || ''}\0${symbol.name}\0${kind}\0` +
+            `${symbol.startLine}\0${symbol.endLine}`;
+        if (seen.has(key)) return;
+        seen.add(key);
+        normalizedSymbols.push(normalizeSymbol(symbol, family, language, kind, owner));
+    };
+    for (const symbol of functions) {
+        append(symbol, 'callable',
+            symbol.type || (symbol.isConstructor ? 'constructor' : 'function'));
+    }
+    for (const type of classes) {
+        append(type, 'type', type.type || 'class');
+        for (const member of type.members || []) {
+            const inherited = {
+                ...member,
+                ...(type.namespace && member.namespace == null && {
+                    namespace: type.namespace,
+                }),
+                ...(type.enclosingType && member.enclosingType == null && {
+                    enclosingType: type.enclosingType,
+                }),
+                ...(type.traitName && {
+                    traitImpl: true,
+                    traitName: type.traitName,
+                }),
+            };
+            append(inherited,
+                inherited.memberType === 'field' ? 'state' : 'callable',
+                inherited.memberType || (inherited.isConstructor ? 'constructor' : 'method'),
+                type.name);
+        }
+    }
+    for (const symbol of stateObjects) append(symbol, 'state', 'state');
+    for (const symbol of macros) append(symbol,
+        symbol.functionLike ? 'callable' : 'state', 'macro');
+    const imports = [...(parsed.imports || [])];
+    return {
+        schemaVersion: IR_SCHEMA_VERSION,
+        language,
+        file,
+        totalLines: parsed.totalLines || 0,
+        symbols: normalizedSymbols,
+        calls: [...calls],
+        imports,
+        exports: [...(parsed.exports || [])],
+        dynamicImports: imports.filter(item => item.dynamic).length,
+        importAliases: parsed.imports?.aliases || null,
+        moduleAssignedNames: [...(parsed.moduleAssignedNames || [])],
+        diagnostics: {
+            parseRecovery: !!parsed.parseRecovery,
+        },
+        capabilities: { ...capabilities },
+    };
+}
+
+function validateFileIR(ir) {
+    const failures = [];
+    if (!ir || typeof ir !== 'object') return ['IR must be an object'];
+    if (ir.schemaVersion !== IR_SCHEMA_VERSION) {
+        failures.push(`schemaVersion must be ${IR_SCHEMA_VERSION}`);
+    }
+    if (typeof ir.language !== 'string' || !ir.language) failures.push('language is required');
+    for (const field of ['symbols', 'calls', 'imports', 'exports']) {
+        if (!Array.isArray(ir[field])) failures.push(`${field} must be an array`);
+    }
+    if (!Number.isInteger(ir.totalLines) || ir.totalLines < 0) {
+        failures.push('totalLines must be a non-negative integer');
+    }
+    for (const [index, symbol] of (ir.symbols || []).entries()) {
+        if (!symbol?.name) failures.push(`symbols[${index}].name is required`);
+        if (!symbol?.kind) failures.push(`symbols[${index}].kind is required`);
+        if (!symbol?.family) failures.push(`symbols[${index}].family is required`);
+        if (!Number.isInteger(symbol?.startLine) || symbol.startLine < 1) {
+            failures.push(`symbols[${index}].startLine must be a positive integer`);
+        }
+        if (!Number.isInteger(symbol?.endLine) || symbol.endLine < symbol.startLine) {
+            failures.push(`symbols[${index}].endLine must be >= startLine`);
+        }
+    }
+    return failures;
+}
+
+function createEvidenceEdge({
+    from = null,
+    to = null,
+    site,
+    tier,
+    resolution,
+    reason = null,
+    evidence = {},
+} = {}) {
+    if (!EVIDENCE_TIERS.includes(tier)) {
+        throw new Error(`Unknown evidence tier: ${tier}`);
+    }
+    if (!resolution) throw new Error('Evidence resolution is required');
+    return {
+        schemaVersion: IR_SCHEMA_VERSION,
+        from,
+        to,
+        site,
+        tier,
+        resolution,
+        ...(reason && { reason }),
+        evidence: { ...evidence },
+    };
+}
+
+module.exports = {
+    IR_SCHEMA_VERSION,
+    EVIDENCE_TIERS,
+    createFileIR,
+    validateFileIR,
+    createEvidenceEdge,
+};