From 3173c7176f2886659fd9f810f88b5122684e7e61e93db27f08add84e05bd5e7e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Linus=20Bj=C3=B6rnstam?= <linus.internet@fastmail.se>
Date: Thu, 22 Oct 2026 15:36:57 +0200
Subject: [PATCH] Modules only the package may use
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A directory whose name starts with _ keeps its modules to the directory it
is in, and to the project's tests/ and benches/.

🤖 Generated with [ECA](https://eca.dev)

Co-Authored-By: eca-agent <git@eca.dev>
---
 _02_.Writing-programs.sz | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/_02_.Writing-programs.sz b/_02_.Writing-programs.sz
index 10ed9a8..8f1b896 100644
--- a/_02_.Writing-programs.sz
+++ b/_02_.Writing-programs.sz
@@ -313,6 +313,20 @@ Because @code{bjo} automatically detects the project root by walking upward unti
 
 In @code{bjo run . one two}, the dot specifies the project itself. Any arguments following the target are forwarded directly to the program's @code{main} function, binding @code{args} to @code{[one two]}. You can also point @code{bjo run} at a specific test file, such as @code{bjo run tests/deck-test.bjo}; the file will be compiled and linked against the project's declared packages.
 
+@subsubsection{Modules only the package may use}
+
+An export list says what a module offers, but once a module is exported, any module can import it. As a package grows you want helpers that the package's own modules share without them becoming part of what the package offers to others. Put them in a directory whose name starts with an underscore:
+
+@codeblock[#:lang "text"]|{
+cards/
+  src/
+    _lib/shuffle.bjo     (cards _lib shuffle)
+    deck.bjo             may import (cards _lib shuffle)
+  tests/shuffle-test.bjo may import it too
+}|
+
+A module under @code{src/_lib/} may be imported by the modules under @code{src/}, and by the project's own @code{tests/} and @code{benches/}. Any other package that tries is told the module is internal to @code{(cards)}, and should use a module outside @code{_lib/} instead. The rule works for any directory starting with @code{_}, at any depth: a module in @code{src/game/_rules/} is for the modules under @code{src/game/}. The REPL may import anything.
+
 @subsubsection{Libraries}
 
 A package that lacks an executable entry point (@code{src/main.bjo}) is treated as a library. Running @code{bjo init --lib} initializes a library project, and running @code{bjo build} inside it compiles all modules found under @code{src/}.