Luce packages
LuceLuce BaseLuciaOS

dymokomi/luce-base

Source of release 0.42.0

0.42.0 / src / sema / check / modules.lucb

#==============================================================================================
#
#   check/modules - Modules
#
#   DESCRIPTION:
#       Loading modules and their imports, and the names each module declares.
#
#==============================================================================================
extend Checker:
    # mark: Modules ============================================================================

    ## Parse `src` and add it as module `name`.
    pub func add_module(name: str, src: source.Source, is_prelude: bool) -> !:
        var p = try parser.Parser.over(src, self.scratch)
        p.allow_core_names = is_prelude
        let tree = try p.parse_module()
        try p.merge_extensions(tree)
        try self.add_parsed(name, src, tree, is_prelude)

    ## Add `tree`, parsed from `src`, as module `name`.
    func add_parsed(name: str, src: source.Source, tree: ast.Node*, is_prelude: bool) -> !:
        tree.text = name
        if is_prelude:
            var cursor = tree.body
            while let d = cursor:
                d.flags |= ast.flag_builtin
                var member = d.body
                while let m = member:
                    m.flags |= ast.flag_builtin
                    member = m.next
                cursor = d.next
        try self.modules.push(Module(name = name, tree = tree, src = src, is_prelude = is_prelude))

    ## Parse and add every standard module from its source (§16.6), where `standard`
    ## finds it. The target is settled by now: its word sizes the pointer-shaped types (§19.5).
    pub func add_prelude() -> !:
        try self.add_prelude_from(try standard.directory())

    ## Parse and add every standard module from its source under `directory`, in the order
    ## `directory/ORDER` lists, a module being `name.lucb` or the fragments of `name/`.
    pub func add_prelude_from(directory: str) -> !:
        self.ready_table()
        var order_bytes = try new u8[directory.length + 8] ---
        let order = try in_arena.read((c.str)try strings.format(order_bytes, f"{directory}/ORDER"))
        # every module read in order (each a build input), parsed in parallel, added in order
        var names = try list.List[str].create(32)
        var sources = try list.List[source.Source].create(32)
        var start: usize = 0
        var i: usize = 0
        while i <= order.length:
            let blank = i == order.length or order[i] == '\n' or order[i] == ' ' or order[i] == '\r' or order[i] == '\t'
            if blank and i > start:
                let name = (str)order[start..<i]
                try names.push(name)
                if name == "platform":
                    try sources.push(try self.platform_source())
                else:
                    var path_bytes = try new u8[directory.length + name.length + 8] ---
                    var path = try strings.format(path_bytes, f"{directory}/{name}.lucb")
                    if not file_exists((c.str)path):
                        path = try strings.format(path_bytes, f"{directory}/{name}")
                    var src = try load_source((c.str)path, false)
                    try src.rebase(directory, "std")
                    try sources.push(src)
            if blank:
                start = i + 1
            i += 1
        let trees = try parse_all(sources.span(), true)
        for k in 0..<names.count:
            if let tree = trees[k]:
                try self.add_parsed(names.get(k), sources.get(k), tree, true)
            else:
                # a module that does not parse is reported as the parser reports it
                try self.add_module(names.get(k), sources.get(k), true)

    ## Add every standard module from text the caller carries, as an embedded checker does
    ## (`standard_sources`): `modules` in binding order, `firsts` where each one's fragments
    ## begin in `sources` and `texts` (one entry more than `modules`), and each fragment's path
    ## as positions name it and its source.
    pub func add_prelude_texts(modules: const str[], firsts: const u32[], sources: const str[], texts: const str[]) -> !:
        self.ready_table()
        for i in 0..<modules.length:
            let name = modules[i]
            let first = (usize)firsts[i]
            let end = (usize)firsts[i + 1]
            # a module of one file, `std/core.lucb`, rather than a directory of fragments
            var file_bytes = try new u8[name.length + 16] ---
            let file = try strings.format(file_bytes, f"std/{name}.lucb")
            if name == "platform":
                try self.add_platform()
            elif end == first + 1 and sources[first] == file:
                try self.add_module(name, try source.Source.over(sources[first], texts[first].bytes), true)
            else:
                var names = try list.List[str].create(end - first)
                var parts = try list.List[str].create(end - first)
                for k in first..<end:
                    try names.push(sources[k])
                    try parts.push(texts[k])
                var path_bytes = try new u8[name.length + 8] ---
                let path = try strings.format(path_bytes, f"std/{name}")
                try self.add_module(name, try source.Source.assembled(path, names.span(), parts.span()), true)

    ## The table's word and C types follow the target, which is settled before the standard
    ## modules are added: its word sizes the pointer-shaped types (§19.5).
    func ready_table():
        self.table.word = (u64)self.build_target.pointer_bits // 8
        self.table.configure_c(self.build_target.os == targets.Os.windows)

    ## The `platform` module, which the checker writes for the target (§19.5).
    func add_platform() -> !:
        try self.add_module("platform", try self.platform_source(), true)

    ## The source of the `platform` module for the target.
    func platform_source() -> source.Source!:
        let buffer = try new u8[1024] ---
        let text = try self.build_target.module_text(buffer, self.program, self.program_version)
        return try source.Source.over("platform", text.bytes)

    ## Load `path` and, first, every module it imports from the same directory.
    pub func load(path: c.str) -> !:
        self.root = manifest.directory_of((str)path)
        # the package enclosing the entry is the one being built, whose modules keep their
        # bare names (§16.3), unless the caller named the build's package already
        if self.package_name == "app":
            let building = try module_paths.building_package(self.root)
            if building.length > 0:
                self.package_name = building
        if self.test_build:
            # a path that does not resolve is the entry's read's to report
            self.tested_package = module_paths.package_of((str)path, self.package_name) catch:
                recover ""
        try self.load_as(path, try module_paths.entry_name((str)path))
        self.entry_index = self.modules.count - 1
        if self.test_build and self.whole_package:
            try self.load_package_modules((str)path)

    ## Load module `name` from the directory `root` and, first, every module it imports, all
    ## from under `root` alone (`sealed`): no manifest is read and no package is searched.
    ## Positions name the files relative to `root`.
    pub func load_sealed(root: str, name: str) -> !:
        self.sealed = true
        let half = self.scratch.length // 2
        self.root = module_paths.canonical(root) catch failure:
            error(unknown_name, try strings.format(self.scratch[..<half], f"{root}: cannot read the directory: {failure.message}"))
        let found = module_paths.resolve_sealed(self.root, self.root, name) catch failure:
            error(unknown_name, try strings.format(self.scratch[..<half], f"{name}: {failure.message}"))
        try self.load_as((c.str)found.path, name)
        self.entry_index = self.modules.count - 1

    ## Every module of the entry's package that it does not import, in the order of their
    ## paths, each after the modules it imports; all are library code, as the entry is in
    ## a test (§16.5).
    func load_package_modules(entry: str) -> !:
        let standard_library = try module_paths.canonical(try standard.directory())
        for path in (try module_paths.package_modules(entry, standard_library)).span():
            let name = try module_paths.name_of(path)
            # spelled as the entry is, so their positions read as an import's do
            try self.load_as((c.str)try module_paths.spelled_like(path, entry), name)
            try note_library_module(name)

    ## Load `path` as module `name`; an imported module keeps its dotted path as its name.
    pub func load_as(path: c.str, name: str) -> !:
        for i in 0..<self.loading.count:
            if self.loading.get(i) == name:
                let half = self.scratch.length // 2
                let message = try strings.format(self.scratch[..<half], f"module import cycle involving {name}")
                error(unknown_name, message)
        try self.loading.push(name)
        defer self.finish_load()
        let text = (str)path
        # a module imported again is the one loaded, which is not read again; a path that
        # does not resolve is reported by the read below
        let known = module_paths.canonical(text) catch:
            recover ""
        if let loaded = self.by_canonical.find(known):
            try self.module_alias(name, self.modules.get(loaded).name)
            return
        # a module of another package, loaded where a library keeps such modules for the
        # checks after this one (`kept_in`, `embed.Library.check_file`), with its name and
        # path, which the importer's allocator holds
        if let kept = self.kept_in:
            let owner = module_paths.package_of(text, self.package_name) catch:
                recover self.package_name
            if owner != self.package_name:
                self.kept_open += 1
                with kept:
                    try self.read_module((c.str)try strings.copy(text), try strings.copy(name))
                self.kept_open -= 1
                return
        try self.read_module(path, name)

    ## Read, parse and add module `name` from `path`, which is not loaded yet, after every
    ## module it imports.
    func read_module(path: c.str, name: str) -> !:
        let text = (str)path
        var src = load_source(path, self.test_build and self.under_test(text)) catch failure:
            let half = self.scratch.length // 2
            # a located message (`path:line:column: ...`) stands as it is, copied into the
            # scratch that outlives the build's arena; only a file that cannot be opened is
            # reported by its name alone
            if failure.code == source.bad_encoding:
                let located = try strings.format(self.scratch[..<half], f"{failure.message}")
                error(unknown_name, located)
            let message = try strings.format(self.scratch[..<half], f"cannot read {text}: {failure.message}")
            error(unknown_name, message)
        if self.sealed:
            try src.rebase(self.root, "")
        let canonical = try module_paths.canonical(text)
        # parsed ahead, on another thread, when its text is the text read now (`prefetch`)
        var tree = self.parsed_ahead(text, &src) else try self.parse_loaded(&src)
        if not (self.test_build and self.under_test(text)):
            try self.loaded_paths.push(text)
        if is_standard_module(name):
            let half = self.scratch.length // 2
            let message = try strings.format(self.scratch[..<half], f"{text}:1:1: a module cannot take a standard module's name")
            error(unknown_name, message)
        if not is_identifier(module_name_of(text)):
            let half = self.scratch.length // 2
            let message = try strings.format(self.scratch[..<half], f"{text}:1:1: a module's file name is an identifier (§16.1)")
            error(unknown_name, message)
        if self.find_module(name) != none:
            error(unknown_name, "different source files use the same canonical module name")
        try packages_as_modules(tree, text, self.root if self.sealed else "")
        var cursor = tree.body
        while let d = cursor:
            if d.kind == ast.Kind.import_ or d.kind == ast.Kind.from_import:
                if is_standard_module(d.text) and try self.has_local_module(text, d.text):
                    # the standard module's name always names it: a package module of that
                    # name could never be imported, so it is an error where it is shadowed
                    let half = self.scratch.length // 2
                    let (file, line, column) = src.located(d.start)
                    let message = try strings.format(self.scratch[half..], f"{file}:{line}:{column}: this package has a module `{d.text}`, which the standard module of that name hides; rename it (§16.6)")
                    error(unknown_name, message)
                if not is_standard_module(d.text):
                    let resolution = self.resolve_import(text, d.text) catch failure:
                        let half = self.scratch.length // 2
                        let (file, line, column) = src.located(d.start)
                        let located = try strings.format(self.scratch[half..], f"{file}:{line}:{column}: cannot resolve module `{d.text}`: {failure.message}")
                        error(unknown_name, located)
                    # the imported module's own imports search from where it was found
                    let saved_root = self.root
                    self.root = resolution.root
                    # spelled as the importer is, so positions and `luce.file` read the same
                    # on every machine
                    let sibling = try module_paths.spelled_like(resolution.path, text)
                    # a module that cannot be read is reported at the import that named it;
                    # a message that already names a place stands as it is
                    self.load_as((c.str)sibling, resolution.name) catch failure:
                        if failure.code == unknown_name and not names_a_place(failure.message):
                            # the message sits in the scratch's lower half; the located one
                            # goes to the upper half
                            let half = self.scratch.length // 2
                            let (file, line, column) = src.located(d.start)
                            let located = try strings.format(self.scratch[half..], f"{file}:{line}:{column}: {failure.message}")
                            error(unknown_name, located)
                        error(failure.code, failure.message)
                    # the import names the module it loaded: the same text names different
                    # modules in different packages (`painter` in luce_ui and in the program)
                    let index = try self.module_at(sibling) else error(unknown_name, "an imported module was not loaded")
                    d.resolved = self.modules.get(index).tree
                    self.root = saved_root
            cursor = d.next
        tree.text = name
        let (owner, shown) = try self.owned_source(text, src)
        try self.modules.push(Module(name = name, tree = tree, src = shown, is_prelude = false, canonical = canonical, package_name = owner, tested = self.test_build and owner == self.tested_package))
        _ = try self.by_canonical.add(canonical, self.modules.count - 1)
        # Every imported module is library code, kept only where the program reaches it;
        # the entry file alone is the program and keeps all it declares.
        if self.loading.count > 1:
            try note_library_module(name)

    ## The package that owns the module at `path`, and its source `src` as positions name it:
    ## a dependency's positions name `<package>/<path in it>`, the same on every machine, as
    ## a standard module's name `std/...`. A sealed root is one package, the one checked.
    func owned_source(path: str, src: source.Source) -> (str, source.Source)!:
        if self.sealed:
            return (self.package_name, src)
        let owner = try module_paths.package_of(path, self.package_name)
        var shown = src
        if owner.length > 0 and owner != self.package_name:
            if let found = try module_paths.owner_root(path):
                let (package, root) = found
                if package == owner:
                    try shown.rebase(root, owner)
                else:
                    # a compiled workspace (luce's) holds every package's modules under one
                    # manifest, each package in its own directory: they name `<that>/...`
                    try shown.rebase(root, "")
        return (owner, shown)

    ## Where import `name` of the file `importer` leads: under the sealed root alone, or as
    ## every compiler resolves it (`module_paths.resolve`).
    func resolve_import(importer: str, name: str) -> module_paths.Resolution!:
        if self.sealed:
            return try module_paths.resolve_sealed(self.root, importer, name)
        return try module_paths.resolve(importer, self.root, name, true, self.package_name)

    ## Whether the importer's package, or the sealed root, has a module named `name`.
    func has_local_module(importer: str, name: str) -> bool!:
        if self.sealed:
            return try module_paths.sealed_has(self.root, importer, name)
        return try module_paths.has_local_module(importer, name)

    ## Whether the module at `path` is under test: one of the entry's package, never a
    ## dependency's (§16.5). A path that does not resolve is not, and the read that follows
    ## reports it.
    func under_test(path: str) -> bool:
        let owner = module_paths.package_of(path, self.package_name) catch:
            return false
        return owner == self.tested_package

    ## Parse the source of a module being loaded.
    func parse_loaded(src: source.Source*) -> ast.Node*!:
        var p = try parser.Parser.over(*src, self.scratch)
        let tree = try p.parse_module()
        try p.merge_extensions(tree)
        return tree

    ## Leave the active import path on success and on every loading error.
    func finish_load():
        self.loading.count -= 1

    ## Whether `m` is the standard `c` module, whose types the checker supplies (§5.2).
    func is_c_module(m: ast.Node*) -> bool:
        let index = self.find_module("c") else return false
        return self.modules.get(index).tree == m

    func module_alias(name: str, target: str) -> !:
        if name == target:
            return
        for alias in self.module_aliases.span():
            if alias.name == name:
                if alias.target != target:
                    error(unknown_name, "package exports disagree on the identity of a module")
                return
        try self.module_aliases.push(ModuleAlias(name, target))

    ## The index of the module named `name` (following aliases), or `none`.
    pub func find_module(name: str) -> usize?:
        var canonical = name
        for alias in self.module_aliases.span():
            if alias.name == name:
                canonical = alias.target
        var i: usize = 0
        while i < self.modules.count:
            if self.modules.get(i).name == canonical:
                return i
            i += 1
        return none

    ## The index of the module whose body declares `decl` at its top level, or `none`.
    ## Modules join the end of `modules` and are indexed as they are first asked about, so
    ## this is for a checked program, whose module bodies no longer change.
    pub func owner_of(decl: ast.Node*) -> usize?!:
        while self.owners_indexed < self.modules.count:
            let index = self.owners_indexed
            var cursor = self.modules.get(index).tree.body
            while let d = cursor:
                _ = try self.owners.add((usize)d, index)
                cursor = d.next
            self.owners_indexed += 1
        return self.owners.find((usize)decl)

    ## The top-level declaration named `name` in module tree `tree`, as `find_decl` finds
    ## it, from an index of the tree built the first time it is asked. A declaration the
    ## index has no entry for is looked for in the tree, so one added since is found too.
    func module_decl(tree: ast.Node*, name: str) -> ast.Node*?:
        self.index_decls(tree) catch:
            return find_decl(tree, name)
        let at = self.module_decls.find(DeclName(tree = (usize)tree, name = name)) else return find_decl(tree, name)
        return self.decl_nodes.get(at)

    func index_decls(tree: ast.Node*) -> !:
        if not try self.decls_indexed.add((usize)tree, 0):
            return
        var cursor = tree.body
        while let d = cursor:
            if d.kind != ast.Kind.import_ and d.kind != ast.Kind.from_import and d.kind != ast.Kind.test_:
                # the first of a name wins, as in `find_decl`
                if try self.module_decls.add(DeclName(tree = (usize)tree, name = d.text), self.decl_nodes.count):
                    try self.decl_nodes.push(d)
            cursor = d.next

    ## Check every module not checked yet, in order: the prelude, then each program module.
    ## A checker that checked the standard modules alone goes on to a program's this way
    ## (`copied`).
    pub func check_program() -> !:
        while self.checked < self.modules.count:
            self.current = self.checked
            try self.check_module(self.checked)
            self.checked += 1

    func check_module(index: usize) -> !:
        let m = self.modules.get(index)
        let tree = m.tree
        self.push_scope()
        self.module_depth = self.depth
        try bind_standard()
        try self.bind_imports(tree)
        try self.collect(tree)
        try self.resolve_signatures(tree)
        try self.infer_receiver_changes(tree)
        var decl = tree.body
        while let d = decl:
            if d.kind == ast.Kind.struct_ or d.kind == ast.Kind.union_ or d.kind == ast.Kind.enum_:
                try self.check_containment(d)
            if d.kind == ast.Kind.extern_type and d.right != none:
                try self.check_handle(d)
            decl = d.next
        if index + 1 == self.modules.count and not self.keeping:
            try self.check_entry(tree)
        # a declaration that fails is reported and the next is checked (§19.6): the scopes it
        # opened close and the function state resets first; the module's failures are one error
        let depth = self.depth
        let bindings = self.scope.count
        var cursor = tree.body
        while let d = cursor:
            self.check_declaration(d) catch failure:
                try self.keep_error(failure.message)
                while self.depth > depth:
                    self.pop_scope()
                self.truncate_scope(bindings)
                self.current_func = none
                self.fallible = false
                self.in_init = false
                self.in_catch = false
                self.in_defer = false
                self.loop_depth = 0
                self.label_count = 0
                self.checking_template = false
                self.at_top_level = false
                # the expression state a failure left mid-expression: a `try` it was under
                # would make every later `f() else x` read as handled
                self.expression_effect = false
                self.calling = false
                self.catch_result = types.none_id
                self.indexed_iterable = none
                self.folded_quietly = false
            cursor = d.next
        try self.settle_pending_changes()
        try self.settle_pending_instances()
        if self.errors.count > 0:
            error(type_error, try self.all_errors())
        var r = self.reporter()
        try prune.prune_unused_functions(tree, &r, m.is_prelude)
        try prune.prune_unused_imports(tree, &r)
        self.pop_scope()

    ## A `naked func` owns its frame: the body is asm blocks and nothing else (§9.8), and the
    ## blocks are what returns, so the every-path rule does not apply.
    func check_naked_body(body: ast.Node*) -> !:
        var cursor = body.body
        if cursor == none:
            try self.fail(body, "a naked function's body is one asm block per architecture")
        while let s = cursor:
            if s.kind != ast.Kind.asm_:
                try self.fail(s, "a naked function's body is asm blocks only")
            cursor = s.next

    ## `main` takes `str[]` or `c.str[]` and returns `i32` or `i32!` (§9.7).
    func check_entry(tree: ast.Node*) -> !:
        let d = find_decl(tree, "main") else return
        if d.kind != ast.Kind.func_:
            return
        let ft = self.table.get(d.type_id)
        var result = ft.elem
        if self.table.kind(result) == types.Kind.fallible:
            result = self.table.get(result).elem
        var good = ft.args.length == 1 and result == types.i32_id
        if good:
            let p = self.table.get(ft.args[0])
            good = p.kind == types.Kind.span and (p.elem == types.str_id or p.elem == types.cstr_id)
        if not good:
            try self.fail(d, "`main` takes `str[]` or `c.str[]` and returns `i32` or `i32!`")

    func bind_module(tree: ast.Node*, alias: str, at: ast.Node*) -> !:
        if self.lookup(alias) != none:
            return
        if tree.type_id == types.none_id:
            tree.type_id = try self.table.nominal(types.Kind.module, tree, try types.no_args())
        try self.bind(at, alias, tree.type_id, tree, false)
        self.set_origin(at)

    ## The module import `d` names: the one the loader resolved for it, or a standard one.
    func imported(d: ast.Node*) -> ast.Node*!:
        if let loaded = d.resolved:
            return loaded
        let index = self.find_module(d.text) else return try self.fail(d, "cannot find that module")
        return self.modules.get(index).tree

    ## The index of the loaded module whose source is at `path`.
    pub func module_at(path: str) -> usize?!:
        return self.by_canonical.find(try module_paths.canonical(path))

    func bind_imports(tree: ast.Node*) -> !:
        var cursor = tree.body
        while let d = cursor:
            if d.kind == ast.Kind.import_ or d.kind == ast.Kind.from_import:
                var earlier = tree.body
                while let e = earlier:
                    if e == d:
                        break
                    if e.kind == d.kind and e.text == d.text:
                        if d.kind == ast.Kind.import_:
                            return try self.fail_at(d, "this module is already imported (§16.3)", e, "the earlier import")
                        if let again = repeated_name(e.body, d.body):
                            return try self.fail_at(again, "this name is already imported (§16.3)", e, "the earlier import")
                    earlier = e.next
            if d.kind == ast.Kind.import_:
                let other = try self.imported(d)
                var alias = last_component(d.text)
                if let a = d.left:
                    alias = a.text
                d.resolved = other
                try self.bind_module(other, alias, d)
            elif d.kind == ast.Kind.from_import:
                let other = try self.imported(d)
                d.resolved = other
                # `from io import Writer` brings `Writer` alone; `io` itself needs `import io`
                var names = d.body
                while let n = names:
                    var bound = n.text
                    if let alias = n.left:
                        bound = alias.text
                    if intrinsic_of(self.standard_module_name(other), n.text).length > 0 and self.module_decl(other, n.text) == none:
                        # `from memory import size_of`: answered where it is called (§5.11)
                        n.resolved = other
                        try self.bind(n, bound, types.none_id, n, false)
                        self.set_origin(d)
                        names = n.next
                        continue
                    var text: u8[256]
                    let member = self.module_decl(other, n.text) else return try self.fail(n, try strings.format(text, f"`{d.text}` has no public `{n.text}`"))
                    if not member.has(ast.flag_pub):
                        var said1: u8[256]
                        try self.fail(n, said(said1, f"`{n.text}` is not public in `{d.text}`"))
                    n.resolved = member
                    try self.bind(n, bound, member.type_id, member, member.kind == ast.Kind.global or member.kind == ast.Kind.extern_var)
                    self.set_origin(d)
                    names = n.next
            cursor = d.next

## The source at `path`: one file, or the fragments its `ORDER` lists when `path` is a
## directory, assembled in order as one module whose positions name the fragment files.
## `with_tests` adds, after them, the test fragments the package keeps for this module
## under `tests/` (§16.5).
func load_source(path: c.str, with_tests: bool, noting: bool = true) -> source.Source!:
    let text = (str)path
    var names = try list.List[str].create(8)
    var texts = try list.List[str].create(8)
    var order_bytes = try new u8[text.length + 8] ---
    let order_path = try strings.format(order_bytes, f"{text}/ORDER")
    # a lookup notes an absence for the build's key (`file_exists`), which only the thread
    # loading in order may do
    var ordered = false
    if noting:
        ordered = file_exists((c.str)order_path)
    else:
        ordered = files.exists((c.str)order_path)
    if ordered:
        try add_fragments(text, "ORDER", &names, &texts, noting)
    elif not noting:
        # read for parsing ahead (`prefetch`): the loading notes it
        return try source.Source.over(text, try in_arena.read(path))
    elif not with_tests:
        return try source.Source.load(path)
    else:
        try names.push(text)
        let bytes = try in_arena.read(path)
        cache.note_input(text, bytes)
        # the text is checked as UTF-8 once assembled (`Source.over`)
        try texts.push((str)bytes)
    if with_tests:
        if let tests = try module_paths.test_fragments_of(text):
            try add_fragments(tests, "TESTS", &names, &texts)
    if names.count == 1 and not ordered:
        return try source.Source.load(path)
    return try source.Source.assembled(text, names.span(), texts.span())

## Nothing is visible without an import (§16.3): a standard module is `import io`,
## one of its declarations `from io import Writer`, in the prelude as anywhere else.
func bind_standard() -> !:
    return

## The fragments that the list file `listing` in `directory` names (`ORDER` for a module,
## `TESTS` for its test fragments), whitespace apart, added in order to `names` and their
## text to `texts`, unchecked until assembled; each is a build input, so an edit rebuilds.
func add_fragments(directory: str, listing: str, names: list.List[str]*, texts: list.List[str]*, noting: bool = true) -> !:
    var order_bytes = try new u8[directory.length + listing.length + 2] ---
    let order_path = try strings.format(order_bytes, f"{directory}/{listing}")
    let listed = try files.read((c.str)order_path)
    defer listed.release()
    let order = listed.value
    if noting:
        cache.note_input(directory, order, order_path)
    let before = names.count
    var start: usize = 0
    var i: usize = 0
    while i <= order.length:
        let blank = i == order.length or order[i] == '\n' or order[i] == ' ' or order[i] == '\r' or order[i] == '\t'
        if blank and i > start:
            let part = (str)order[start..<i]
            var fragment_bytes = try new u8[directory.length + part.length + 2] ---
            let fragment = try strings.format(fragment_bytes, f"{directory}/{part}")
            try names.push(fragment)
            let bytes = try in_arena.read((c.str)fragment)
            if noting:
                cache.note_input(fragment, bytes)
            try texts.push((str)bytes)
        if blank:
            start = i + 1
        i += 1
    if names.count == before:
        error(unknown_name, try strings.format(try new u8[listing.length + 40] ---, f"a `{listing}` names at least one fragment"))

## `from pkg import a, b` where `pkg` is a package, the importer's own or a dependency, imports
## its modules (§16.3): each becomes `import pkg.a as a`, in place, before anything resolves.
## Under a sealed root, `sealed` names it, and `pkg` is a directory of modules there.
func packages_as_modules(tree: ast.Node*, importer: str, sealed: str) -> !:
    var previous: ast.Node*? = none
    var cursor = tree.body
    while let d = cursor:
        cursor = d.next
        if d.kind != ast.Kind.from_import or not try names_modules(importer, d.text, sealed):
            previous = d
            continue
        var first: ast.Node*? = none
        var last: ast.Node*? = none
        var names = d.body
        while let n = names:
            names = n.next
            let module = try strings.join([d.text, ".", n.text], "")
            let one = try ast.Node.make(ast.Kind.import_, module, n.start, n.line)
            one.left = n.left
            if one.left == none:
                one.left = try ast.Node.make(ast.Kind.name, n.text, n.start, n.line)
            ast.append(&first, &last, one)
        let end = last else return
        end.next = d.next
        if let p = previous:
            p.next = first
        else:
            tree.body = first
        previous = end

## Whether `from name import ...` in `importer` brings modules, under the sealed root
## `sealed` when there is one.
func names_modules(importer: str, name: str, sealed: str) -> bool!:
    if sealed.length > 0:
        return try module_paths.sealed_names_modules(sealed, importer, name)
    return try module_paths.names_modules(importer, name)