"""Which standard-library package exports each public name. The compiler's "use of unknown declaration 'sqrt'; did you mean to import it from 'std.math'?" needs to know where a name lives. A package says what it exports in its __init__.mojo (`from .math import (sqrt, ...)`, and its own top-level definitions); a module file's public top-level definitions are exported by that module. A name a package exports is attributed to the package; otherwise to its module. A name exported from more than one place is ambiguous and gets no hint, rather than a guess. The prelude package is not an import hint (its names are visible everywhere), but its functions are read for whether they raise: `input` and `atol` raise, so calling them from a function that does not is the compiler's "cannot call function that may raise". A prelude function counts as raising only if every overload says `raises` in its signature. Writes stdindex/stdindex.json: {name: module}, the ambiguous names, and the raising prelude functions. """ from __future__ import annotations import re from ..common import write_json from . import Context, fresh_dir NAME = "stdindex" SOURCE = "modular" INPUTS = ["stdlib/std"] IMPORT = re.compile(r"(?ms)^from\s+([\w.]+)\s+import\s+(\((?P.*?)\)|(?P[^\n]+))") TOPLEVEL = re.compile(r"(?m)^(?:def|struct|trait)\s+([A-Za-z]\w*)|^comptime\s+([A-Za-z]\w*)\s*(?:[:=\[])") def _names(body: str) -> list[str]: body = re.sub(r"#[^\n]*", "", body) out = [] for part in body.split(","): part = part.strip() if part: name = part.split(" as ")[-1].strip() if re.fullmatch(r"[A-Za-z]\w*", name): out.append(name) return out def defined(text: str) -> set[str]: return {m.group(1) or m.group(2) for m in TOPLEVEL.finditer(text)} - {None} def run(ctx: Context) -> dict: out = fresh_dir(NAME) std = ctx.root / "stdlib" / "std" places: dict[str, set[str]] = {} def add(name: str, module: str) -> None: if not name.startswith("_"): places.setdefault(name, set()).add(module) package_exports: dict[str, set[str]] = {} for init in sorted(std.rglob("__init__.mojo")): rel = init.parent.relative_to(std.parent) if any(p.startswith("_") for p in rel.parts) or rel.parts[1:2] == ("prelude",): continue module = ".".join(rel.parts) text = init.read_text(encoding="utf-8") names = defined(text) for m in IMPORT.finditer(text): names.update(_names(m.group("group") or m.group("line") or "")) package_exports[module] = names for n in names: add(n, module) exported_anywhere = set().union(*package_exports.values()) if package_exports else set() for f in sorted(std.rglob("*.mojo")): if f.name == "__init__.mojo": continue rel = f.relative_to(std.parent).with_suffix("") if any(p.startswith("_") for p in rel.parts) or rel.parts[1:2] == ("prelude",): continue for n in defined(f.read_text(encoding="utf-8")): if n not in exported_anywhere: add(n, ".".join(rel.parts)) unique = {n: next(iter(ms)) for n, ms in sorted(places.items()) if len(ms) == 1} raising = raising_prelude(std) ambiguous = sorted(n for n, ms in places.items() if len(ms) > 1) write_json(out / "stdindex.json", {"processor": NAME, "provenance": ctx.prov("stdlib/std"), "exports": unique, "ambiguous": ambiguous, "raisingPrelude": raising}) return {"names": len(unique), "ambiguous": len(ambiguous), "packages": len(package_exports), "raisingPrelude": len(raising)} def signatures(text: str, name: str) -> list[str]: """Every top-level `def name...:` signature, up to the colon that opens its body.""" out = [] for m in re.finditer(rf"(?m)^def\s+{re.escape(name)}\b", text): depth, j = 0, m.end() while j < len(text): c = text[j] if c in "([{": depth += 1 elif c in ")]}": depth -= 1 elif c == ":" and depth == 0: break j += 1 out.append(text[m.start():j]) return out def module_file(std, mod: str): base = std.parent.joinpath(*mod.split(".")) if base.with_suffix(".mojo").exists(): return base.with_suffix(".mojo") return base / "__init__.mojo" if (base / "__init__.mojo").exists() else None def signatures_of(std, mod: str, name: str, depth: int = 0) -> list[str]: """`name`'s signatures where it is defined, following re-exports (`from .string import atol`).""" src = module_file(std, mod) if src is None or depth > 4: return [] text = src.read_text(encoding="utf-8") sigs = signatures(text, name) if sigs: return sigs package = mod if src.name == "__init__.mojo" else mod.rsplit(".", 1)[0] for m in IMPORT.finditer(text): if name in _names(m.group("group") or m.group("line") or ""): target = m.group(1) if target.startswith("."): target = package + "." + target.lstrip(".") if target.strip(".") else package return signatures_of(std, target, name, depth + 1) return [] def raising_prelude(std) -> list[str]: init = std / "prelude" / "__init__.mojo" if not init.exists(): return [] text = init.read_text(encoding="utf-8") found = [] for m in IMPORT.finditer(text): mod = m.group(1) if not mod.startswith("std."): continue for name in _names(m.group("group") or m.group("line") or ""): sigs = signatures_of(std, mod, name) if sigs and all(re.search(r"\)\s*(?:raises\b|[^\n]*\braises\b)", sig.split("(", 1)[1] if "(" in sig else sig) for sig in sigs): found.append(name) return sorted(set(found))