boxwerk 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 45cabb7d61d5029a494703a95c1b974f1af7ee1286001d457ea7aaf8b870496c
-  data.tar.gz: fb14ec2556787d19618ee3599685a06a06a4d1ed40a3113c47f61420f84fb202
+  metadata.gz: 78eb85866eb8a42cb597f88faeace9f97fb81c8312748767669f776fbb09f504
+  data.tar.gz: 78b358fa881a3c0e440d52c67e479c70d29b4d6a4ae79a9eebaa0872e5e92605
 SHA512:
-  metadata.gz: 8e11bee2fd442bc29b537d4e7099e4380b19bed851f4f40bd42e119c35f139ee680866bd0f6189334e46652881c224559e10c6ab4dcf722c4d50c455fccdf16e
-  data.tar.gz: 0c69bf3a342d8fd502d6e64d085edfa9d1a2864b60d8f3f683addc680080f5762246f9901926c81667c40ddad82fdae7ead6e939ea3f297c0f907c983e21622f
+  metadata.gz: ae1b0a336dfbaa4f01fccb376a38b2c7020fccae033eeabcad328f20c2fdb312c8bbc14a37eea771b518c180125d6f8224cb3516e4d837e5484dc60a6eb307de
+  data.tar.gz: 1b31b4d1a59d2213617b522f3ab88f88a2a3c7ef686ce817fb7bb9e56a2680c47bfa597f7dae7385dbddc35c1a2594911c5a18aa067910604525b98df1a79c10

data/AGENTS.md

@@ -0,0 +1,24 @@
+# Agents
+
+Guidelines for AI agents working on this codebase.
+
+- Write tests for new behaviour; run existing tests before committing.
+- Only run tests relevant to your changes — not the full suite every time.
+- If you only changed an example, only run that example's tests.
+- Run targeted tests as you go for fast feedback; run the full suite once before committing.
+- Whenever adding new features/functionality, update complex example with support for it (if appropriate). Also add to or update E2E tests.
+- Update relevant documentation (README, USAGE, ARCHITECTURE, TODO, example READMEs, CHANGELOG).
+- Keep README concise — detailed usage belongs in USAGE.md.
+- Keep documentation minimal — don't be wordy.
+- Consistent style with existing code and docs.
+- Commit as you go with descriptive messages.
+- Don't over-engineer — keep it simple.
+- When multiple implementations or design choices exist, present a menu to the user with your recommendation.
+- Run `RUBY_BOX=1 bundle exec rake` to run all tests (unit, e2e, examples).
+- Run `RUBY_BOX=1 bundle exec rake test` for unit tests only.
+- Run `RUBY_BOX=1 bundle exec rake test e2e` for unit and e2e tests.
+- Run `RUBY_BOX=1 bundle exec rake example:minimal` for a specific example.
+- Run `bundle exec rake format` to format code after every change.
+- Fix any warnings.
+- Use sub-agents where appropriate.
+- Never bump version or publish gem.

data/ARCHITECTURE.md

@@ -0,0 +1,264 @@
+# Architecture
+
+This document describes how Boxwerk works internally.
+
+## Overview
+
+Boxwerk enforces package boundaries at runtime using Ruby::Box isolation. Each package gets its own `Ruby::Box` instance. Constants are resolved lazily on first access and cached. Only direct dependencies are accessible; transitive dependencies are blocked.
+
+```
+┌─────────────────────────────────────────────────────┐
+│                    Root Box                         │
+│  (Bundler + global gems loaded here)                │
+│                                                     │
+│  ┌──────────┐  ┌──────────┐  ┌──────────┐           │
+│  │ root pkg │  │ finance  │  │   util   │  ...      │
+│  │  (box)   │  │  (box)   │  │  (box)   │           │
+│  └──────────┘  └──────────┘  └──────────┘           │
+│       │              │              │               │
+│       │  const_missing             autoload         │
+│       │  searches deps             resolves files   │
+└─────────────────────────────────────────────────────┘
+```
+
+## Ruby::Box Primer
+
+[`Ruby::Box`](https://docs.ruby-lang.org/en/4.0/Ruby/Box.html) provides in-process isolation of classes, modules, and constants. Boxwerk relies on these specific behaviours:
+
+### Box Types
+
+- **Root box** — A single box per Ruby process. Created during bootstrap. All builtin classes/modules live here. The source for copy-on-write when creating user boxes.
+- **Main box** — A user box automatically created at bootstrap, copied from the root box. The user's main program runs here.
+- **User boxes** — Created with `Ruby::Box.new`, copied from the root box. All user boxes are flat (no nesting). This is what Boxwerk creates for each package.
+
+### Key Behaviours
+
+- **File scope.** One `.rb` file runs in a single box. Methods and procs defined in that file always execute in that file's box, even when called from another box.
+- **Top-level constants.** Constants defined at the top level are constants of `Object` within that box. From outside, `box::Foo` accesses them.
+- **Monkey patch isolation.** Reopened built-in classes are visible only within the box that defined them.
+- **Global variable isolation.** `$LOAD_PATH`, `$LOADED_FEATURES`, and other globals are isolated per box. `$LOAD_PATH` and `$LOADED_FEATURES` use the *loading box* (not current box) for `require` resolution.
+- **Copy-on-write.** `Ruby::Box.new` copies the root box's class extensions. Anything loaded into the root box *before* creating a user box is inherited. Anything loaded *after* is not.
+- **`box.eval(code)`** — Evaluates Ruby code in the box's context, like loading a file.
+- **`box.require(path)`** — Requires a file in the box's context. Subsequent requires from that file also run in the same box.
+
+### Important Implications
+
+1. **Order matters.** Gems loaded into the root box via `Bundler.require` before `Ruby::Box.new` are inherited by all user boxes. This is how Boxwerk provides "global gems".
+2. **No cross-box method inheritance.** A `const_missing` hook defined on `Module` in one box does not fire in another box. Boxwerk must install resolvers per-box.
+3. **`$LOAD_PATH` per box.** Each box has its own `$LOAD_PATH`, which enables per-package gem version isolation.
+
+## Boot Sequence
+
+The `boxwerk` executable (`exe/boxwerk`) orchestrates the boot:
+
+```
+1. exe/boxwerk starts in the main box
+2. If Bundler is loaded (bundle exec or binstub), re-exec into a clean
+   Ruby process using Bundler.with_unbundled_env (prevents double gem loading)
+3. For install/info/help/version: load boxwerk directly (no Ruby::Box needed)
+4. For exec/run/console: check Ruby::Box availability and enabled status
+5. Switch to root box via Ruby::Box.root.eval(...)
+6. Load boxwerk gem into root box ($LOAD_PATH.unshift)
+7. Discover project Gemfile (gems.rb preferred, then Gemfile)
+8. Run Bundler.setup + Bundler.require in root box
+   → All global gems now available in root box
+9. Call Boxwerk::CLI.run(ARGV)
+   → CLI delegates to Setup.run for package boot
+   → Discovers boxwerk.yml for configuration (package_paths)
+   → Runs global boot (global/ require + global/boot.rb)
+   → Eager-loads Zeitwerk constants for child box inheritance
+```
+
+### Setup.run
+
+```
+1. Find root package.yml or boxwerk.yml (walk up from current directory)
+2. Run global boot (if global/ exists):
+   a. Require global/ files in root box (eager, not autoload)
+   b. Require global/boot.rb in root box
+3. Eager-load all Zeitwerk-managed constants in root box
+4. Create PackageResolver — discovers all package.yml files
+   → Respects package_paths from boxwerk.yml
+   → Creates implicit root package if no root package.yml exists
+5. Create BoxManager — manages Ruby::Box instances
+6. Boot all packages in topological order (dependencies first)
+   → Root package boot.rb runs in root package box (not root box)
+```
+
+### BoxManager.boot (per package)
+
+For each package, in dependency order:
+
+```
+1. Create Ruby::Box.new (copied from root box, inherits global gems)
+2. Setup per-package gem load paths (if Gemfile exists)
+   → Prepend gem load paths to the box's $LOAD_PATH
+3. Auto-require gems from Gemfile (non-root packages only)
+   → Respects require: false and require: 'custom/path'
+4. Scan directories with Zeitwerk (file discovery + inflection)
+   → Uses Zeitwerk::Loader::FileSystem for scanning
+   → Uses Zeitwerk::Inflector for snake_case → CamelCase conversion
+5. Register autoload entries in the box via box.eval
+   → Implicit namespaces: create Module.new
+   → Explicit namespaces: autoload + eager trigger
+   → Files: autoload :Invoice, "/path/to/public/invoice.rb"
+6. Run per-package boot.rb (if it exists)
+   → Executes after the package's own constants are scanned
+   → Used for configuring additional autoload dirs and collapse dirs
+7. Wire dependency constants via const_missing
+   → Install a resolver that searches direct dependency boxes
+   → When enforce_dependencies is false, searches ALL packages:
+     explicit deps first (in declared order), then remaining packages
+```
+
+## Constant Resolution
+
+Constants are resolved through two mechanisms:
+
+### Intra-Package: autoload
+
+Each package's own constants are registered as `autoload` entries in its box. When code inside the box references `Calculator`, Ruby's built-in `autoload` loads the file and defines the constant — standard Ruby behaviour.
+
+### Cross-Package: const_missing
+
+When a constant is not found in the current box (no autoload entry), `Object.const_missing` fires. Boxwerk installs a custom handler per-box that:
+
+1. Iterates through the package's declared direct dependencies
+2. For each dependency, checks if it has the constant (via file index or `const_get`)
+3. Enforces privacy rules (public path, private_constants list)
+4. Returns the constant value from the dependency's box
+5. Raises `NameError` if no dependency has the constant
+
+```ruby
+# Simplified const_missing flow:
+class Object
+  def self.const_missing(const_name)
+    deps.each do |dep|
+      next unless dep.has_constant?(const_name)
+      check_privacy!(const_name, dep)
+      return dep.box.const_get(const_name)
+    end
+    raise NameError, "uninitialized constant #{const_name}"
+  end
+end
+```
+
+Constants are **not** wrapped in namespaces. `Invoice` is accessible as `Invoice`, not `Finance::Invoice`. This matches how constants work within a single Ruby application.
+
+### Root Box Resolver (for exec/run)
+
+When running commands via `boxwerk exec` or `boxwerk run`, some tools (like Rake) load files via the root box rather than the package box. Boxwerk installs a composite resolver on `Ruby::Box.root` that:
+
+1. Tries the target package's own box first (for internal constants)
+2. Falls through to the target box's dependency resolver
+3. This ensures package constants are accessible even when code is loaded by tools running in the root box
+
+## Package Resolution
+
+`PackageResolver` discovers packages by scanning for `package.yml` files:
+
+1. Start from the project root
+2. Glob for `package.yml` files using `package_paths` from `boxwerk.yml` (default: `**/`)
+3. Parse each YAML file into a `Package` object
+4. If no root `package.yml` exists, create an implicit root package with `enforce_dependencies: false`, `enforce_privacy: false`, and automatic dependencies on all discovered packages
+5. Resolve dependency order via DFS — circular dependencies are allowed (back-edges are skipped)
+6. Provide topological ordering for boot (dependencies before dependents)
+
+### package.yml Format
+
+```yaml
+enforce_dependencies: true
+dependencies:
+  - packs/util
+  - packs/billing
+enforce_privacy: true
+public_path: public/          # default
+private_constants:
+  - "::InternalHelper"
+```
+
+This is the standard [Packwerk](https://github.com/Shopify/packwerk) format.
+
+## Privacy Enforcement
+
+`PrivacyChecker` enforces which constants a package exposes:
+
+- **public_path** (default: `public/`) — Files in this directory define the package's public API. Only these constants are accessible to dependents.
+- **private_constants** — Explicitly private constants, blocked even if in the public path.
+- **pack_public sigil** — Files outside the public path can be marked public with `# pack_public: true` in the first 5 lines.
+
+Privacy is checked at constant resolution time in the `const_missing` handler. A `NameError` with a descriptive message is raised for violations.
+
+## Per-Package Gem Isolation
+
+`GemResolver` enables different packages to use different versions of the same gem:
+
+1. Check if the package has a `gems.rb` or `Gemfile` (and corresponding lockfile)
+2. Parse the lockfile with `Bundler::LockfileParser` to get gem specs
+3. Parse the Gemfile with `GemfileRequireParser` to extract autorequire directives
+4. Find the actual gem installation paths by searching all `Gem.path` directories
+5. Collect full require paths for each gem and its runtime dependencies
+6. Prepend these paths to the box's `$LOAD_PATH`
+7. Auto-require gems declared in the Gemfile (non-root packages only):
+   - Default (`gem 'faker'`) → `require 'faker'`
+   - Custom (`gem 'foo', require: 'foo/bar'`) → `require 'foo/bar'`
+   - Disabled (`gem 'dotenv', require: false`) → skip
+
+Since each box has its own `$LOAD_PATH`, `require 'faker'` in two different boxes can load different versions.
+
+## File-to-Constant Mapping
+
+Boxwerk uses Zeitwerk's inflector for file-to-constant name mapping:
+
+```
+lib/calculator.rb      → Calculator
+lib/tax_calculator.rb  → TaxCalculator
+public/invoice.rb      → Invoice
+lib/api/v2/client.rb   → Api::V2::Client
+```
+
+Zeitwerk cannot register autoloads directly inside `Ruby::Box` because autoload calls execute in the box where the code was defined (root box for Zeitwerk). Boxwerk works around this by using Zeitwerk only for file scanning and inflection, then registering autoloads via `box.eval`. For nested constants, implicit namespaces are created as `Module.new` instances, and explicit namespaces (with a matching `.rb` file) are eagerly loaded before child autoloads are registered.
+
+## CLI Commands
+
+The CLI (`Boxwerk::CLI`) provides:
+
+| Command | Description |
+|---------|-------------|
+| `exec`  | Run a command (gem binstub) in the boxed environment |
+| `run`   | Run a Ruby script in a package box |
+| `console` | Start an IRB console in a package box |
+| `info`  | Show package structure and dependencies |
+| `install` | Bundle install for all packages |
+
+### console Implementation
+
+Console always runs IRB in `Ruby::Box.root` rather than the target package box. The composite resolver installed on root provides the same constant access. This avoids a Ruby 4.0.1 GC bug where running IRB in child boxes with `const_missing` overrides triggers a double-free crash during process exit.
+
+### exec Implementation
+
+`exec` resolves the command to a gem binstub path, then evaluates the binstub's content in the target box using `box.eval(content)`. File content is evaluated directly (not via `load`) because `load` creates a new file scope where inherited DSL methods (e.g. Rake's `task`) may not be visible inside a `Ruby::Box`.
+
+### --all Flag
+
+The `--all` flag runs `exec` for each package in a separate subprocess. This is necessary because test frameworks like Minitest register tests globally via `at_exit`, which would conflict across packages in a single process.
+
+### --global Flag
+
+The `--global` / `-g` flag runs commands directly in `Ruby::Box.root`, bypassing package resolution entirely. No package constants are accessible — only global gems. Useful for debugging.
+
+## Module Structure
+
+```
+Boxwerk
+├── CLI              # Command-line interface
+├── Setup            # Boot orchestration (find root, create resolver + manager)
+├── PackageResolver  # Discover packages, validate deps, topological sort
+├── Package          # Data class for a single package
+├── BoxManager       # Create boxes, scan with Zeitwerk, wire constants
+├── ConstantResolver # Install const_missing handlers per-box
+├── PrivacyChecker   # Check public/private constant access
+├── GemResolver      # Resolve per-package gem load paths and autorequire
+├── GemfileRequireParser # Lightweight Gemfile parser for require directives
+└── ZeitwerkScanner  # Zeitwerk-based file scanning and autoload registration
+```

data/CHANGELOG.md

@@ -1,8 +1,79 @@
 # Changelog
 
-## [0.1.0] - 2026-01-05
+## [v0.3.0] — 2026-03-02
+
+Complete architecture rewrite. Each package now runs in its own `Ruby::Box`
+with constants resolved lazily at runtime via `const_missing`. Reads standard
+Packwerk `package.yml` files without requiring Packwerk.
+
+### Added
+
+- **Package isolation** — each package runs in its own `Ruby::Box`; constants
+  from undeclared dependencies and private constants raise `NameError` at
+  runtime.
+- **Per-package gems** — packages can declare their own `gems.rb`/`Gemfile`
+  with independent gem versions; auto-require mirrors Bundler's default
+  behaviour (respects `require: false`, `require: 'path'`).
+- **Zeitwerk autoloading** — constants discovered via Zeitwerk conventions;
+  default autoload roots: `lib/` and `public/`.
+- **Privacy enforcement** — `enforce_privacy`, `public_path`,
+  `private_constants`, and `# pack_public: true` file sigil.
+- **`Boxwerk.package`** — returns a `PackageContext` in per-package `boot.rb`
+  with `name`, `root?`, `config`, `root_path`, and `autoloader`.
+- **`Boxwerk.global`** — returns a `GlobalContext` from any box context.
+- **Autoloader API** — `push_dir`, `collapse`, `ignore`, `setup` on both
+  `PackageContext::Autoloader` and `GlobalContext::Autoloader`; shared via
+  `AutoloaderMixin`. `push_dir` and `collapse` auto-call `setup` so constants
+  are available immediately in boot scripts.
+- **`global/boot.rb`** — runs in the root box before package boxes; shared
+  constants defined here are inherited by all packages.
+- **`eager_load_global`** / **`eager_load_packages`** boxwerk.yml options.
+- **Package name normalization** — leading `./` and trailing `/` stripped;
+  `packs/foo`, `./packs/foo`, and `packs/foo/` are equivalent.
+- **CLI commands** — `exec`, `run`, `console`, `install`, `info`.
+- **`boxwerk install`** — installs gems for all packages; works on a fresh
+  clone without pre-installed gems.
+- **`boxwerk info`** — shows config, global context, and per-package
+  autoload/collapse/ignore dirs (with eager-load status), enforcements,
+  dependencies, gems, and boot script presence. Boots the application
+  (`RUBY_BOX=1` required).
+- **NameError hints** — improved error messages like
+  `(defined in 'packs/baz', not a dependency of '.')` in child package
+  contexts.
+- **Circular dependency detection** in `boxwerk info` tree output.
+- **`collapse` / `ignore` in boot.rb** — collapses intermediate namespaces
+  (e.g. `Analytics::Formatters` → `Analytics::*`); ignores dirs from
+  autoloading.
+- **Missing lockfile warning** — graceful message directing to
+  `boxwerk install` when a Gemfile exists but no lockfile is found.
+- **Monkey patch isolation** — patches defined in one package box are not
+  visible in other packages or the root context.
+- **`examples/complex`** and **`examples/minimal`** demonstrating all features.
+- **E2E test suite** (74 tests) alongside unit tests (120 tests).
+- **GitHub Pages API documentation** published from `lib/` via RDoc.
+
+### Removed
+
+- Custom file-to-constant mapping (`Boxwerk.camelize`), replaced by Zeitwerk.
+- Namespace wrapping.
+
+## [v0.2.0] - 2026-01-06
+
+### Changed
+- Simplified implementation (~370 lines removed)
+- Consolidated cycle detection in Graph (removed redundant methods)
+- Added class-level documentation to all modules
+- Simplified example application
+
+### Removed
+- Removed `Gemfile.lock` from git (library best practice)
+- Removed `sig/boxwerk.rbs`
+
+## [v0.1.0] - 2026-01-05
 
 Initial release.
 
-[unreleased]: https://github.com/dtcristo/boxwerk/compare/v0.1.0...HEAD
-[0.1.0]: https://github.com/dtcristo/boxwerk/releases/tag/v0.1.0
+[Unreleased]: https://github.com/dtcristo/boxwerk/compare/v0.3.0...HEAD
+[v0.3.0]: https://github.com/dtcristo/boxwerk/releases/tag/v0.3.0
+[v0.2.0]: https://github.com/dtcristo/boxwerk/releases/tag/v0.2.0
+[v0.1.0]: https://github.com/dtcristo/boxwerk/releases/tag/v0.1.0