@mortice/mapwright 0.8.0

package/dist/catalogue/packages.js

@@ -0,0 +1,475 @@
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { toPosixPath } from "./moduleResolution.js";
+import { packageIdentityId } from "./identity.js";
+export function buildPackageModel(workspaceRoot, files, markdownPackages) {
+    const packageByPath = new Map();
+    const entrypointImportPathByFile = new Map();
+    for (const packageRecord of markdownPackages) {
+        packageByPath.set(normalizePackagePath(packageRecord.path), clonePackageRecord(packageRecord));
+    }
+    for (const file of files) {
+        const absolute = path.resolve(workspaceRoot, file.path);
+        const baseName = path.basename(file.path).toLowerCase();
+        if (baseName === "package.json") {
+            const packageRoot = normalizePackagePath(path.dirname(file.path));
+            const packageJson = readJsonIfExists(absolute);
+            const name = typeof packageJson?.name === "string" ? packageJson.name : undefined;
+            const entrypointInfos = collectPackageJsonEntrypoints(workspaceRoot, packageRoot, packageJson);
+            for (const entrypoint of entrypointInfos) {
+                if (entrypoint.importPath) {
+                    entrypointImportPathByFile.set(entrypoint.filePath, entrypoint.importPath);
+                }
+            }
+            upsertPackage(packageByPath, packageRoot, {
+                name,
+                ecosystem: "npm",
+                summary: undefined,
+                entrypoints: entrypointInfos.map((entrypoint) => entrypoint.filePath),
+                provenanceWarnings: isPrivateWorkspaceRootPackageJson(packageRoot, packageJson)
+                    ? ["private-workspace-root"]
+                    : []
+            });
+            continue;
+        }
+        if (baseName === "pyproject.toml") {
+            const packageRoot = normalizePackagePath(path.dirname(file.path));
+            const name = readPyprojectName(absolute);
+            const pythonMeta = readPyprojectMetadata(absolute);
+            const entrypointInfos = collectPythonEntrypointInfos(workspaceRoot, packageRoot, files, pythonMeta.importPackages);
+            for (const entrypoint of entrypointInfos) {
+                if (entrypoint.importPath) {
+                    entrypointImportPathByFile.set(entrypoint.filePath, entrypoint.importPath);
+                }
+            }
+            upsertPackage(packageByPath, packageRoot, {
+                name,
+                ecosystem: "python",
+                summary: undefined,
+                entrypoints: entrypointInfos.map((entrypoint) => entrypoint.filePath),
+                importPackages: pythonMeta.importPackages,
+                consoleScripts: pythonMeta.consoleScripts
+            });
+            continue;
+        }
+        if (/CATALOGUE\.md$/i.test(file.path)) {
+            const packageRoot = normalizePackagePath(path.dirname(file.path));
+            const existing = packageByPath.get(packageRoot);
+            if (!existing) {
+                const catalogueName = readCataloguePackageName(absolute);
+                upsertPackage(packageByPath, packageRoot, {
+                    name: catalogueName,
+                    summary: readCatalogueSummary(absolute)
+                });
+            }
+        }
+    }
+    hydrateRootPackageFromWorkspaceManifest(workspaceRoot, files, packageByPath, entrypointImportPathByFile);
+    if (packageByPath.size === 0) {
+        const fallbackName = path.basename(path.resolve(workspaceRoot)) || "workspace";
+        upsertPackage(packageByPath, ".", { name: fallbackName });
+    }
+    else if (!packageByPath.has(".")) {
+        const fallbackName = path.basename(path.resolve(workspaceRoot)) || "workspace";
+        upsertPackage(packageByPath, ".", { name: fallbackName });
+    }
+    const orderedPackages = [...packageByPath.values()].sort((a, b) => a.path.localeCompare(b.path));
+    const packageById = new Map();
+    for (const packageRecord of orderedPackages) {
+        packageById.set(packageRecord.id, packageRecord);
+    }
+    const sortedPackageRoots = orderedPackages
+        .map((packageRecord) => packageRecord.path)
+        .sort((a, b) => b.length - a.length || a.localeCompare(b));
+    const filePackageByPath = new Map();
+    for (const file of files) {
+        const packageRecord = findPackageForPath(sortedPackageRoots, packageByPath, file.path);
+        if (packageRecord) {
+            file.packageName = packageRecord.name;
+            filePackageByPath.set(file.path, packageRecord);
+            if (file.kind === "source" && !packageRecord.modules?.includes(file.path)) {
+                packageRecord.modules = [...new Set([...(packageRecord.modules ?? []), file.path])].sort();
+            }
+        }
+    }
+    for (const packageRecord of orderedPackages) {
+        packageRecord.modules = [...new Set(packageRecord.modules ?? [])].sort();
+        packageRecord.entrypoints = [...new Set(packageRecord.entrypoints ?? [])].sort();
+        packageRecord.capabilities = [...new Set(packageRecord.capabilities)].sort();
+        packageRecord.publicApis = [...new Set(packageRecord.publicApis)].sort();
+        packageRecord.tests = [...new Set(packageRecord.tests)].sort();
+    }
+    return {
+        packages: orderedPackages,
+        packageByPath,
+        packageById,
+        filePackageByPath,
+        entrypointImportPathByFile
+    };
+}
+export function findPackageForFile(model, filePath) {
+    return model.filePackageByPath.get(filePath);
+}
+export function computePublicApiImportPath(workspaceRoot, filePath, packageRecord, language, publicImportPath) {
+    const normalizedFilePath = toPosixPath(filePath);
+    const packagePath = packageRecord?.path ?? ".";
+    const packageName = packageRecord?.name;
+    if (language === "typescript" || language === "javascript") {
+        if (publicImportPath) {
+            return publicImportPath;
+        }
+        if (packageName && packageRecord?.entrypoints?.some((entrypoint) => matchesEntrypoint(filePath, entrypoint))) {
+            return packageName;
+        }
+        return stripExtension(normalizedFilePath);
+    }
+    if (language === "python") {
+        // Prefer a package-root import path attributed via explicit __init__ re-exports.
+        if (publicImportPath) {
+            return publicImportPath;
+        }
+        const packageRoot = packagePath === "." ? workspaceRoot : path.resolve(workspaceRoot, packagePath);
+        const relative = path.relative(packageRoot, path.resolve(workspaceRoot, filePath));
+        return stripPythonModulePath(toPosixPath(relative));
+    }
+    return normalizedFilePath;
+}
+export function buildPublicImportPathBySymbolId(packageModel, relationships) {
+    const exportRelationshipsByFile = new Map();
+    for (const relationship of relationships) {
+        if (relationship.type !== "exports" || relationship.from.kind !== "file") {
+            continue;
+        }
+        const current = exportRelationshipsByFile.get(relationship.from.id) ?? [];
+        current.push(relationship);
+        exportRelationshipsByFile.set(relationship.from.id, current);
+    }
+    const result = new Map();
+    for (const packageRecord of packageModel.packages) {
+        if (!packageRecord.name) {
+            continue;
+        }
+        for (const entrypoint of packageRecord.entrypoints ?? []) {
+            const publicImportPath = packageModel.entrypointImportPathByFile.get(entrypoint);
+            if (!publicImportPath) {
+                continue;
+            }
+            const queue = [entrypoint];
+            const visitedFiles = new Set();
+            while (queue.length > 0) {
+                const filePath = queue.shift();
+                if (visitedFiles.has(filePath)) {
+                    continue;
+                }
+                visitedFiles.add(filePath);
+                const exportRelationships = exportRelationshipsByFile.get(filePath) ?? [];
+                for (const relationship of exportRelationships) {
+                    if (relationship.to.kind === "symbol") {
+                        result.set(relationship.to.id, result.get(relationship.to.id) ?? publicImportPath);
+                    }
+                    else if (relationship.to.kind === "file") {
+                        queue.push(relationship.to.id);
+                    }
+                }
+            }
+        }
+    }
+    return result;
+}
+function upsertPackage(packageByPath, packagePath, seed) {
+    const existing = packageByPath.get(packagePath);
+    const pathValue = normalizePackagePath(packagePath);
+    const ecosystem = seed.ecosystem ?? existing?.ecosystem ?? "unknown";
+    if (existing) {
+        if (seed.name) {
+            existing.name = seed.name;
+        }
+        existing.ecosystem = ecosystem;
+        const identityName = existing.name && existing.name !== pathValue ? existing.name : seed.name ?? "unnamed";
+        if (!existing.name || existing.name === pathValue) {
+            existing.name = seed.name ?? "unnamed";
+        }
+        existing.id = packageIdentityId({ ecosystem, name: identityName === pathValue ? "unnamed" : identityName, root: pathValue });
+        existing.summary = existing.summary ?? seed.summary;
+        existing.entrypoints = [...new Set([...(existing.entrypoints ?? []), ...(seed.entrypoints ?? [])])];
+        if (seed.importPackages) {
+            existing.importPackages = [...new Set([...(existing.importPackages ?? []), ...seed.importPackages])].sort();
+        }
+        if (seed.consoleScripts) {
+            existing.consoleScripts = dedupeConsoleScripts([...(existing.consoleScripts ?? []), ...seed.consoleScripts]);
+        }
+        if ((seed.provenanceWarnings?.length ?? 0) > 0) {
+            existing.provenance.warnings = [...new Set([...(existing.provenance.warnings ?? []), ...seed.provenanceWarnings])].sort();
+        }
+        return;
+    }
+    const identityName = seed.name ?? "unnamed";
+    packageByPath.set(packagePath, {
+        id: packageIdentityId({ ecosystem, name: identityName, root: pathValue }),
+        name: identityName,
+        path: pathValue,
+        ecosystem,
+        importPackages: seed.importPackages ? [...seed.importPackages].sort() : undefined,
+        consoleScripts: seed.consoleScripts ? dedupeConsoleScripts(seed.consoleScripts) : undefined,
+        summary: seed.summary,
+        capabilities: [],
+        publicApis: [],
+        tests: [],
+        stability: "unknown",
+        entrypoints: [...new Set(seed.entrypoints ?? [])],
+        modules: [],
+        provenance: {
+            source: "package-model",
+            warnings: [...new Set(seed.provenanceWarnings ?? [])].sort()
+        }
+    });
+}
+function dedupeConsoleScripts(scripts) {
+    const seen = new Set();
+    const out = [];
+    for (const script of scripts) {
+        const key = `${script.name}\0${script.target}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push(script);
+    }
+    return out.sort((a, b) => a.name.localeCompare(b.name) || a.target.localeCompare(b.target));
+}
+function findPackageForPath(sortedPackageRoots, packageByPath, filePath) {
+    for (const packageRoot of sortedPackageRoots) {
+        if (packageRoot === ".") {
+            return packageByPath.get(packageRoot);
+        }
+        if (filePath === packageRoot || filePath.startsWith(`${packageRoot}/`)) {
+            return packageByPath.get(packageRoot);
+        }
+    }
+    return packageByPath.get(".");
+}
+function normalizePackagePath(packagePath) {
+    const normalized = packagePath.replaceAll("\\", "/");
+    return normalized === "" ? "." : normalized;
+}
+function clonePackageRecord(packageRecord) {
+    return {
+        ...packageRecord,
+        capabilities: [...packageRecord.capabilities],
+        publicApis: [...packageRecord.publicApis],
+        tests: [...packageRecord.tests],
+        entrypoints: [...(packageRecord.entrypoints ?? [])],
+        modules: [...(packageRecord.modules ?? [])],
+        internalPaths: [...(packageRecord.internalPaths ?? [])],
+        publicPaths: [...(packageRecord.publicPaths ?? [])],
+        dependencyPolicy: packageRecord.dependencyPolicy ? { ...packageRecord.dependencyPolicy } : undefined,
+        provenance: {
+            ...packageRecord.provenance,
+            extractors: [...(packageRecord.provenance.extractors ?? [])],
+            locations: [...(packageRecord.provenance.locations ?? [])],
+            warnings: [...(packageRecord.provenance.warnings ?? [])]
+        }
+    };
+}
+function readJsonIfExists(filePath) {
+    if (!existsSync(filePath)) {
+        return undefined;
+    }
+    try {
+        return JSON.parse(readFileSync(filePath, "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+}
+function readPyprojectName(filePath) {
+    if (!existsSync(filePath)) {
+        return undefined;
+    }
+    const text = readFileSync(filePath, "utf8");
+    const projectMatch = text.match(/(?:\[project\]|\[tool\.poetry\])([\s\S]*?)(?:\n\[|$)/);
+    const body = projectMatch?.[1] ?? text;
+    const nameMatch = body.match(/^\s*name\s*=\s*["']([^"']+)["']/m);
+    return nameMatch?.[1];
+}
+function readPyprojectMetadata(filePath) {
+    const importPackages = [];
+    const consoleScripts = [];
+    if (!existsSync(filePath)) {
+        return { importPackages, consoleScripts };
+    }
+    const text = readFileSync(filePath, "utf8");
+    const scriptsMatch = text.match(/\[project\.scripts\]([\s\S]*?)(?:\n\[|$)/);
+    if (scriptsMatch?.[1]) {
+        for (const line of scriptsMatch[1].split(/\r?\n/)) {
+            const m = line.match(/^\s*([A-Za-z0-9_.-]+)\s*=\s*["']([^"']+)["']/);
+            if (m) {
+                consoleScripts.push({ name: m[1], target: m[2] });
+            }
+        }
+    }
+    // Prefer packages listed under [tool.setuptools.packages] find where present; otherwise leave empty for layout inference later.
+    const packagesList = text.match(/packages\s*=\s*\[\s*((?:"[^"]+"\s*,?\s*)+)\s*\]/);
+    if (packagesList?.[1]) {
+        for (const m of packagesList[1].matchAll(/"([^"]+)"/g)) {
+            importPackages.push(m[1]);
+        }
+    }
+    return { importPackages: [...new Set(importPackages)].sort(), consoleScripts };
+}
+function readCataloguePackageName(filePath) {
+    const text = readFileSync(filePath, "utf8");
+    const match = text.match(/^Name:\s*(.+)$/m);
+    return match?.[1]?.replace(/`/g, "").trim();
+}
+function readCatalogueSummary(filePath) {
+    const text = readFileSync(filePath, "utf8");
+    const match = text.match(/^Purpose:\s*([\s\S]*?)(?:\n\n|$)/m);
+    return match?.[1]?.trim();
+}
+function collectPackageJsonEntrypoints(workspaceRoot, packageRoot, packageJson) {
+    const entrypoints = [];
+    if (!packageJson) {
+        return entrypoints;
+    }
+    const packageName = typeof packageJson.name === "string" ? packageJson.name : undefined;
+    const candidates = [
+        { value: packageJson.main, importPath: packageName },
+        { value: packageJson.module, importPath: packageName }
+    ];
+    if (typeof packageJson.exports === "string") {
+        candidates.push({ value: packageJson.exports, importPath: packageName });
+    }
+    if (packageJson.exports && typeof packageJson.exports === "object" && !Array.isArray(packageJson.exports)) {
+        const exportsMap = packageJson.exports;
+        const rootExport = exportsMap["."];
+        for (const value of collectExportTargetStrings(rootExport)) {
+            candidates.push({ value, importPath: packageName });
+        }
+        for (const [subpath, target] of Object.entries(exportsMap)) {
+            if (!subpath.startsWith("./") || subpath === ".") {
+                continue;
+            }
+            const normalizedSubpath = subpath.slice(2);
+            const importPath = packageName && normalizedSubpath ? `${packageName}/${normalizedSubpath}` : undefined;
+            for (const value of collectExportTargetStrings(target)) {
+                candidates.push({ value, importPath });
+            }
+        }
+    }
+    for (const candidate of candidates) {
+        if (typeof candidate.value !== "string") {
+            continue;
+        }
+        const normalized = toPosixPath(path.join(packageRoot, candidate.value));
+        entrypoints.push({ filePath: normalized, importPath: candidate.importPath });
+    }
+    for (const localCandidate of ["index.ts", "index.tsx", "index.js", "index.jsx", "index.py", path.join("src", "index.ts"), path.join("src", "index.tsx"), path.join("src", "index.js"), path.join("src", "index.jsx"), path.join("src", "__init__.py")]) {
+        const relativePath = toPosixPath(path.join(packageRoot, localCandidate));
+        if (existsSync(path.resolve(workspaceRoot, relativePath))) {
+            entrypoints.push({ filePath: relativePath, importPath: packageName });
+        }
+    }
+    const seen = new Set();
+    return entrypoints.filter((entrypoint) => {
+        const key = `${entrypoint.filePath}\0${entrypoint.importPath ?? ""}`;
+        if (seen.has(key)) {
+            return false;
+        }
+        seen.add(key);
+        return true;
+    });
+}
+function collectExportTargetStrings(target) {
+    if (typeof target === "string") {
+        return [target];
+    }
+    if (!target || typeof target !== "object" || Array.isArray(target)) {
+        return [];
+    }
+    const preferredKeys = ["types", "import", "require", "default"];
+    const record = target;
+    const values = preferredKeys.flatMap((key) => collectExportTargetStrings(record[key]));
+    return [...new Set(values)];
+}
+function isPrivateWorkspaceRootPackageJson(packageRoot, packageJson) {
+    if (packageRoot !== "." || !packageJson) {
+        return false;
+    }
+    const isPrivate = packageJson.private === true;
+    const hasWorkspaces = Array.isArray(packageJson.workspaces)
+        || (typeof packageJson.workspaces === "object" && packageJson.workspaces !== null);
+    return isPrivate && hasWorkspaces;
+}
+function hydrateRootPackageFromWorkspaceManifest(workspaceRoot, files, packageByPath, entrypointImportPathByFile) {
+    if (packageByPath.has(".")) {
+        return;
+    }
+    const rootPackageJsonPath = path.resolve(workspaceRoot, "package.json");
+    if (!existsSync(rootPackageJsonPath)) {
+        return;
+    }
+    const packageJson = readJsonIfExists(rootPackageJsonPath);
+    const name = typeof packageJson?.name === "string" ? packageJson.name : undefined;
+    const entrypoints = collectPackageJsonEntrypoints(workspaceRoot, ".", packageJson);
+    for (const entrypoint of entrypoints) {
+        if (entrypoint.importPath) {
+            entrypointImportPathByFile.set(entrypoint.filePath, entrypoint.importPath);
+        }
+    }
+    const hasRootPackageFile = files.some((file) => file.path === "package.json");
+    upsertPackage(packageByPath, ".", {
+        name,
+        ecosystem: "npm",
+        summary: undefined,
+        entrypoints: entrypoints.map((entrypoint) => entrypoint.filePath),
+        provenanceWarnings: isPrivateWorkspaceRootPackageJson(".", packageJson)
+            ? [hasRootPackageFile ? "private-workspace-root" : "private-workspace-root-manifest"]
+            : []
+    });
+}
+function collectPythonEntrypointInfos(workspaceRoot, packageRoot, files, importPackages) {
+    const infos = [];
+    // Legacy package/src root __init__.py (import path not statically known).
+    for (const file of files) {
+        if ((packageRoot === "." && (file.path === "__init__.py" || file.path === "src/__init__.py")) ||
+            file.path === `${packageRoot}/__init__.py` ||
+            file.path === `${packageRoot}/src/__init__.py`) {
+            infos.push({ filePath: file.path });
+        }
+    }
+    // Import packages declared in pyproject map their `__init__.py` to a dotted
+    // import path (distribution name may differ from the import package name).
+    for (const importPackage of importPackages) {
+        const relativeDir = importPackage.replaceAll(".", "/");
+        const candidates = packageRoot === "."
+            ? [`${relativeDir}/__init__.py`, `src/${relativeDir}/__init__.py`]
+            : [`${packageRoot}/${relativeDir}/__init__.py`, `${packageRoot}/src/${relativeDir}/__init__.py`];
+        for (const candidate of candidates) {
+            const normalized = toPosixPath(candidate);
+            if (existsSync(path.resolve(workspaceRoot, normalized))) {
+                infos.push({ filePath: normalized, importPath: importPackage });
+            }
+        }
+    }
+    const seen = new Set();
+    return infos.filter((info) => {
+        const key = `${info.filePath}\0${info.importPath ?? ""}`;
+        if (seen.has(key)) {
+            return false;
+        }
+        seen.add(key);
+        return true;
+    });
+}
+function matchesEntrypoint(filePath, entrypoint) {
+    const normalizedEntry = toPosixPath(entrypoint);
+    return filePath === normalizedEntry || filePath.endsWith(`/${path.basename(normalizedEntry)}`);
+}
+function stripExtension(filePath) {
+    return filePath.replace(/\.[^.\/]+$/, "");
+}
+function stripPythonModulePath(modulePath) {
+    const stripped = modulePath.replace(/\.py$/, "").replace(/\/__init__$/, "");
+    const dotted = stripped.replaceAll("/", ".");
+    return dotted === "." ? "" : dotted;
+}

package/dist/catalogue/pythonReExports.d.ts

@@ -0,0 +1,7 @@
+import type { FileRecord, RelationshipRecord, SymbolRecord } from "./schema.js";
+export interface PythonReExportInput {
+    workspaceRoot: string;
+    files: FileRecord[];
+    symbols: SymbolRecord[];
+}
+export declare function buildPythonInitReExports(input: PythonReExportInput): RelationshipRecord[];

package/dist/catalogue/pythonReExports.js

@@ -0,0 +1,113 @@
+/**
+ * Gate 3 Python public-surface: explicit `__init__.py` re-exports.
+ *
+ * A statement like `from .core import Greeter` inside a package `__init__.py`
+ * makes `Greeter` importable from the package itself. We model this with an
+ * `exports` relationship (file → symbol, discriminant `re-export`) so that the
+ * public import-path resolver can attribute the package root import path to the
+ * re-exported symbol. Only statically clear relative imports of concrete names
+ * are recognised; wildcard (`*`) and dynamic constructs are ignored.
+ */
+import path from "node:path";
+import { readFileSync } from "node:fs";
+import { relationshipIdentityId } from "./identity.js";
+import { truncateEvidenceText } from "./evidence.js";
+import { isGeneratedArtefactPath } from "./resolveRefs.js";
+import { resolvePythonRelativeModuleTarget } from "./moduleResolution.js";
+export function buildPythonInitReExports(input) {
+    const topLevelByFileName = new Map();
+    for (const symbol of input.symbols) {
+        if (symbol.language !== "python" || symbol.duplicateOf) {
+            continue;
+        }
+        if ((symbol.qualifiedContainerPath ?? "") !== "") {
+            continue;
+        }
+        const key = `${symbol.filePath}\0${symbol.name}`;
+        const current = topLevelByFileName.get(key) ?? [];
+        current.push(symbol.id);
+        topLevelByFileName.set(key, current);
+    }
+    const symbolById = new Map(input.symbols.map((symbol) => [symbol.id, symbol]));
+    const merged = new Map();
+    for (const file of input.files) {
+        if (file.language !== "python" || path.basename(file.path) !== "__init__.py") {
+            continue;
+        }
+        const absolute = path.resolve(input.workspaceRoot, file.path);
+        let lines;
+        try {
+            lines = readFileSync(absolute, "utf8").split(/\r?\n/);
+        }
+        catch {
+            continue;
+        }
+        for (let i = 0; i < lines.length; i += 1) {
+            const line = lines[i] ?? "";
+            const match = line.match(/^\s*from\s+(\.[.A-Za-z_0-9]*)\s+import\s+(.+)$/);
+            if (!match) {
+                continue;
+            }
+            const moduleSpecifier = match[1]?.trim() ?? "";
+            const targetFile = resolvePythonRelativeModuleTarget(input.workspaceRoot, file.path, moduleSpecifier);
+            if (!targetFile) {
+                continue;
+            }
+            const importList = (match[2] ?? "").replace(/[()\\]/g, " ");
+            for (const rawEntry of importList.split(",")) {
+                const entry = rawEntry.trim();
+                if (!entry || entry === "*") {
+                    continue;
+                }
+                const externalName = entry.split(/\s+as\s+/i)[0]?.trim();
+                if (!externalName || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(externalName)) {
+                    continue;
+                }
+                const candidates = topLevelByFileName.get(`${targetFile}\0${externalName}`) ?? [];
+                const symbolId = preferSourceId(candidates, symbolById);
+                if (!symbolId) {
+                    continue;
+                }
+                const id = relationshipIdentityId({
+                    type: "exports",
+                    fromKind: "file",
+                    fromId: file.path,
+                    toKind: "symbol",
+                    toId: symbolId,
+                    discriminant: "re-export"
+                });
+                if (merged.has(id)) {
+                    continue;
+                }
+                merged.set(id, {
+                    id,
+                    type: "exports",
+                    from: { kind: "file", id: file.path },
+                    to: { kind: "symbol", id: symbolId },
+                    localDiscriminant: "re-export",
+                    evidence: {
+                        filePath: file.path,
+                        startLine: i + 1,
+                        endLine: i + 1,
+                        text: truncateEvidenceText(line.trim())
+                    },
+                    confidence: 0.9,
+                    provenance: { source: "python-static", extractors: ["python-init"] }
+                });
+            }
+        }
+    }
+    return [...merged.values()].sort((a, b) => a.id.localeCompare(b.id));
+}
+function preferSourceId(ids, symbolById) {
+    if (ids.length === 0) {
+        return undefined;
+    }
+    const unique = [...new Set(ids)];
+    const authored = unique.filter((id) => {
+        const filePath = symbolById.get(id)?.filePath;
+        return filePath ? !isGeneratedArtefactPath(filePath) : true;
+    });
+    const pool = authored.length > 0 ? authored : unique;
+    return [...pool].sort()[0];
+}

package/dist/catalogue/resolveRefs.d.ts

@@ -0,0 +1,40 @@
+import type { PackageRecord, PublicApiRecord, SymbolRecord } from "./schema.js";
+export type RefResolutionStatus = "resolved" | "ambiguous" | "unknown";
+export interface RefResolution {
+    status: RefResolutionStatus;
+    /** Canonical id when resolved; otherwise the original reference. */
+    value: string;
+}
+export interface SymbolRefIndex {
+    byId: Map<string, SymbolRecord>;
+    byQualifiedName: Map<string, string>;
+    byPathName: Map<string, string[]>;
+    byName: Map<string, string[]>;
+    byPackageName: Map<string, string[]>;
+}
+export interface PublicApiRefIndex {
+    byId: Map<string, PublicApiRecord>;
+    byPathName: Map<string, string[]>;
+    byName: Map<string, string[]>;
+    byPackageName: Map<string, string[]>;
+    symbolById: Map<string, SymbolRecord>;
+}
+export declare function isGeneratedArtefactPath(filePath: string): boolean;
+/** Prefer source symbols/APIs over generated dist/build artefacts when ranking matches. */
+export declare function preferSourceIds(ids: string[], filePathForId: (id: string) => string | undefined): string[];
+export declare function buildSymbolRefIndex(symbols: SymbolRecord[], packageByFilePath?: Map<string, PackageRecord>): SymbolRefIndex;
+export declare function buildPublicApiRefIndex(publicApis: PublicApiRecord[], symbols: SymbolRecord[], packageByFilePath?: Map<string, PackageRecord>): PublicApiRefIndex;
+export declare function resolveSymbolReference(reference: string, index: SymbolRefIndex): RefResolution;
+export declare function resolvePublicApiReference(reference: string, index: PublicApiRefIndex): RefResolution;
+/**
+ * Parse `symbol:path/to/file.ts:Name:12` or `symbol:path/to/file.ts:Name`.
+ * Relative catalogue paths are POSIX-style and do not contain colons.
+ */
+export declare function parseSymbolPathName(ref: string): {
+    filePath: string;
+    name: string;
+} | undefined;
+export declare function parsePublicApiPathName(ref: string): {
+    filePath: string;
+    name: string;
+} | undefined;