Files
pplus-web/scripts/mojo/mojocorpus/processors/stdindex.py
T
2026-10-05 03:03:38 +00:00

150 lines
5.8 KiB
Python

"""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<group>.*?)\)|(?P<line>[^\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))