feat(lang): module NAME uses A, B - a module reaches only the modules it names

A reference from a module that declares uses into a module it does not
name is refused, exported or not, naming the use and the fix. A module
with no uses clause keeps the old rule; a package's module is always
usable; a friend is not held to it; a cycle in the declared graph is
refused; LUDIC_VIS_REPORT=1 lists the violations as uses: lines. Reseed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

selfhost/backend/emit_vis.ludic

@@ -1,10 +1,13 @@
 # emit_vis.ludic — L3: module scope. A file belongs to the module its own `module NAME` line or
 # its importer's names (frontend/parse.ludic, module_of); a file in no module is public. A
 # reference from one module to another module's function, global, record or event needs that
-# declaration `export`ed, unless the referring module is a `friend module` (a test harness).
-# LUDIC_VIS_REPORT=1 prints every violation as `vis: <file>: <module>.<name>` and goes on, so a
-# tool can add the exports a codebase needs before the rule is switched on for it.
+# declaration `export`ed, and - when the referring module says `uses` - that module named there
+# (frontend/modules.ludic), unless the referring module is a friend of it (a test harness).
+# LUDIC_VIS_REPORT=1 prints every violation as `vis: <file>: <module>.<name>` (a private name) or
+# `uses: <file>: ...` (a module not in the uses list) and goes on, so a tool can add the exports
+# and the uses a codebase needs before the rule is switched on for it.
 var g_vis_report: int = -1
+var g_vis_off: bool = false          # a port's binding: checked where it is written (ports.ludic)
 function vis_reporting() -> bool {
   if g_vis_report < 0 {
     g_vis_report = 0
@@ -12,14 +15,6 @@ function vis_reporting() -> bool {
   }
   return g_vis_report == 1
 }
-function vis_allowed(d: Node, from: pointer) -> bool {
-  if d.vis == 1 { return true }
-  if d.file == null { return true }
-  let to = module_of(d.file)
-  if to == "" { return true }
-  if from == to { return true }
-  return module_is_friend(from)
-}
 # `what` is the name as written at the reference
 # a generic function's instance is named for its type arguments (grow$int); a message names grow
 function vis_plain(what: pointer) -> pointer {
@@ -30,17 +25,30 @@ function vis_plain(what: pointer) -> pointer {
   }
   return what
 }
+function vis_say(m: pointer) -> void {
+  file_write(file_stderr(), m, len(m))
+}
 function vis_check(d: Node, what0: pointer) -> void {
   if d == null { return }
+  if g_vis_off { return }
+  if d.file == null { return }
   let what = vis_plain(what0)
   var here = g_err_file
   if here == null { return }
   let from = module_of(here)
-  if vis_allowed(d, from) { return }
   let to = module_of(d.file)
+  if (to == "") or (from == to) { return }
+  if module_friend_of(from, to) { return }
+  if not module_may_use(from, to) {
+    if vis_reporting() {
+      vis_say(`uses: {d.file}:{itoa(d.line)}: {to}.{what} used from {here} (module {from})\n`)
+    } else {
+      perr(`{from} uses {to}.{what} ({d.file}:{itoa(d.line)}): add 'uses {to}' to {from}'s module line, or take it through a port`)
+    }
+  }
+  if d.vis == 1 { return }
   if vis_reporting() {
-    let m = `vis: {d.file}:{itoa(d.line)}: {to}.{what} used from {here}\n`
-    file_write(file_stderr(), m, len(m))
+    vis_say(`vis: {d.file}:{itoa(d.line)}: {to}.{what} used from {here}\n`)
     return
   }
   perr(`{what} is private to module {to}; mark it 'export' where it is declared ({d.file})`)

selfhost/frontend/modules.ludic

@@ -0,0 +1,146 @@
+# modules.ludic — L3 the module graph. `module fishing uses base, data` says which other modules
+# fishing may reach at all: a reference from fishing into a module it does not name is refused
+# (backend/emit_vis.ludic), exported or not, unless fishing is a friend of that module. A module
+# that says no `uses` keeps the old rule (anything exported), so the rule comes in one module at a
+# time. A package's module (found through ludic_modules or the toolchain) is always usable, and
+# the declared graph may not have a cycle.
+#
+# `friend module lab` sees every module's private names; `friend module lab of fishing, data`
+# sees only those modules'.
+var g_mu_mod: []pointer = new []pointer      # a module that said `uses`
+var g_mu_list: []pointer = new []pointer     # ",a,b," - what it may use (union of its lines)
+var g_mu_file: []pointer = new []pointer     # where it said so first
+var g_mu_line: []int = new []int
+var g_fr_scope: []pointer = new []pointer    # per g_mod_friends entry: "" for all, else ",a,b,"
+var g_pkg_files: []pointer = new []pointer   # files that belong to a package, not the project
+var g_pkg_mods: []pointer = new []pointer    # modules declared in a package's files
+
+function mod_list_has(list: pointer, name: pointer) -> bool {
+  return has_sub(list, `,{name},`)
+}
+function mod_find_uses(m: pointer) -> int {
+  var i = 0
+  while i < len(g_mu_mod) {
+    if (g_mu_mod[i] == m) { return i }
+    i += 1
+  }
+  return -1
+}
+# `A, B, C` after `uses` / `of`, as ",A,B,C,"
+function mod_parse_names() -> pointer {
+  var out = ","
+  out = out + eat_id() + ","
+  while is_op(",") {
+    pi += 1
+    out = out + eat_id() + ","
+  }
+  return out
+}
+# `module NAME [uses A, B]`
+function mod_parse_line() -> void {
+  pi += 1
+  let name = eat_id()
+  module_set(g_parse_file, name)
+  if is_pkg_file(g_parse_file) and not mod_is_pkg(name) { push(g_pkg_mods, name) }
+  if not is_id("uses") { return }
+  let ln = toks[pi].line
+  pi += 1
+  let list = mod_parse_names()
+  let k = mod_find_uses(name)
+  if k >= 0 {
+    g_mu_list[k] = g_mu_list[k] + list
+    return
+  }
+  push(g_mu_mod, name)
+  push(g_mu_list, list)
+  push(g_mu_file, g_parse_file)
+  push(g_mu_line, ln)
+}
+# `friend module NAME [of A, B]`
+function mod_parse_friend() -> void {
+  pi += 2
+  let fm = eat_id()
+  module_set(g_parse_file, fm)
+  let scope = ""
+  push(g_mod_friends, fm)
+  push(g_fr_scope, scope)
+}
+# may `from` see `to`'s private names?
+function module_friend_of(from: pointer, to: pointer) -> bool {
+  var i = 0
+  while i < len(g_mod_friends) {
+    if (g_mod_friends[i] == from) {
+      if (g_fr_scope[i] == "") or mod_list_has(g_fr_scope[i], to) { return true }
+    }
+    i += 1
+  }
+  return false
+}
+function is_pkg_file(f: pointer) -> bool {
+  var i = 0
+  while i < len(g_pkg_files) {
+    if (g_pkg_files[i] == f) { return true }
+    i += 1
+  }
+  return false
+}
+function mod_is_pkg(m: pointer) -> bool {
+  var i = 0
+  while i < len(g_pkg_mods) {
+    if (g_pkg_mods[i] == m) { return true }
+    i += 1
+  }
+  return false
+}
+# may module `from` reach into module `to` at all? (L3 uses; the export rule is separate)
+function module_may_use(from: pointer, to: pointer) -> bool {
+  if (from == "") or (to == "") or (from == to) { return true }
+  if mod_is_pkg(to) { return true }
+  let k = mod_find_uses(from)
+  if k < 0 { return true }
+  return mod_list_has(g_mu_list[k], to)
+}
+# the names in ",a,b," as a slice
+function mod_names(list: pointer) -> []pointer {
+  let out = new []pointer
+  var a = 1
+  var j = 1
+  while j < len(list) {
+    if list[j] == ',' {
+      if j > a { push(out, list[a .. j]) }
+      a = j + 1
+    }
+    j += 1
+  }
+  return out
+}
+# the declared uses graph has no cycle: a depth-first walk that carries its path, "a -> b -> "
+var g_mu_done: pointer = ","          # modules whose every path is known to end
+function mod_walk(m: pointer, path: pointer, first: pointer) -> void {
+  if has_sub(`-> {path}`, `-> {m} -> `) {
+    let k0 = mod_find_uses(first)
+    g_err_file = g_mu_file[k0]
+    g_err_line = g_mu_line[k0]
+    perr(`the modules' uses go round in a circle: {path}{m}; one of them has to take the other through a port`)
+  }
+  if has_sub(g_mu_done, `,{m},`) { return }
+  let k = mod_find_uses(m)
+  if k < 0 { return }
+  let next = mod_names(g_mu_list[k])
+  var n = 0
+  while n < len(next) {
+    mod_walk(next[n], `{path}{m} -> `, first)
+    n += 1
+  }
+  g_mu_done = g_mu_done + m + ","
+}
+function modules_finish() -> void {
+  let saved = g_parsing
+  g_parsing = false
+  var i = 0
+  while i < len(g_mu_mod) {
+    mod_walk(g_mu_mod[i], "", g_mu_mod[i])
+    i += 1
+  }
+  g_parsing = saved
+}

selfhost/frontend/parse.ludic

@@ -47,14 +47,6 @@ function module_set(f: pointer, name: pointer) -> void {
   push(g_mod_file, f)
   push(g_mod_name, name)
 }
-function module_is_friend(name: pointer) -> bool {
-  var i = 0
-  while i < len(g_mod_friends) {
-    if (g_mod_friends[i] == name) { return true }
-    i += 1
-  }
-  return false
-}
 function is_float_file(f: pointer) -> bool {
   if (f == null) { return false }
   var i = 0
@@ -921,15 +913,11 @@ function parse_one_decl() -> void {
     skipnl()
   }
   if is_id("friend") and (toks[pi + 1].text == "module") {
-    pi += 2
-    let fm = eat_id()
-    module_set(g_parse_file, fm)
-    push(g_mod_friends, fm)
+    mod_parse_friend()                            # frontend/modules.ludic
     return
   }
   if is_id("module") and toks[pi + 1].kind == TK_ID {
-    pi += 1
-    module_set(g_parse_file, eat_id())
+    mod_parse_line()                              # module NAME [uses A, B]
     return
   }
   # `export function f`, `export var v`, ...: visible from other modules (L3)
@@ -1158,6 +1146,7 @@ function do_import(rel: pointer) -> void {
   # ludic_modules is not beside its importer and keeps its own module (or none)
   let beside = full == join_path(cur_dir, rel)
   if is_runtime_path(rel) or not beside or (beside and unsafe_trusted(g_parse_file)) { push(g_trusted_files, full) }
+  if (not beside and not is_runtime_path(rel)) or (beside and is_pkg_file(g_parse_file)) { push(g_pkg_files, full) }
   if beside and not is_runtime_path(rel) and not (module_of(g_parse_file) == "") { module_set(full, module_of(g_parse_file)) }
   if (src == null) { perr(`cannot open import {full}`) }
   # the audio runtime can arrive through atlas.ludic's own import or the Assets
@@ -1513,6 +1502,7 @@ function parse_program() -> void {
     if is_op("}") { break }
     parse_one_decl()
   }
+  modules_finish()                                 # L3: the declared uses have no cycle
   registries_finish()                              # L8: each registry gets its defs
   views_finish()                                   # L11: each view gets its model and call
   components_finish()                              # L11: each component gets its class