shoney.arickathil f6b5333d40 docs: iteration 15 closeout (Task 5)

- error catalog: WO-E106 (dependency fetch/shape failures, one code, message
  names dep + step) and WO-E107 (dep/local module-name collision) rows.
- README: a Dependencies subsection under the manifest docs — [deps] syntax,
  .wo-deps/wo.lock behavior, offline-when-locked, --update-deps, flat-only.
- board: iteration 15 row -> landed (deps-accept 8/0), pending row removed;
  story 15 header records the landing; 08-project-structure notes
  .wo-deps (gitignored) + wo.lock (committed); plan checkboxes all ticked.

(One self-inflicted casualty during this task, restored from git before
commit: a buggy doc-edit script truncated 08-project-structure.md; the file
was recovered intact and the intended one-liner applied by hand.)

Gates at closeout: deps-accept 8/0, woc-test 540/0, oop-e2e 87/0,
log-watcher 7/0, employee 8/0.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

2026-08-19 19:23:18 +02:00

2.9 KiB

Raw Blame History

Iteration 15 — dependencies: `wo.toml [deps]`, git fetch, `wo.lock`

Format: product/story-iteration-template. Part of Story — one language, one runtime, one database, one binary.

Inserted 2026-08-18. LANDED the same day (branch web-framework): all acceptance criteria met — just deps-accept 8/0 (cold fetch + lock, use and /sub, offline-when-locked with the remote deleted, lock-beats-moved-tag, --update-deps, drift/transitive/collision diagnostics WO-E106/E107, dep fn main never the entry, manifest shape). The enabler for code shared between writeonce repositories — the web framework (iteration 16) is the driving consumer.

Spec exists: 2026-08-18-web-framework-design.md section A is normative for this iteration. Plan: 2026-08-18-deps-package-manager.md (5 tasks: manifest inline-table + [deps]; resolver fetch/cache/lock; multi-root discovery + module mapping + entry restriction; the just deps-accept gate over file:// remotes; docs closeout).

Goals

A project declares exact-rev git dependencies in wo.toml [deps] (name = { git = "...", rev = "..." }); woc fetches them (via the git binary — no network code in the compiler) into .wo-deps/<name>/ and resolves use <name> / use <name>/sub into the dep's module tree.
wo.lock pins resolved SHAs: builds are reproducible, a moved tag is reported rather than silently followed, and a lock-satisfied build never touches the network.
Honest edges: transitive [deps] refused with a diagnostic (flat-only v1), dep/local module-name collisions diagnosed, a dep's fn main ignored, pub applies across the boundary exactly as across modules.

Acceptance Criteria

Given an app whose [deps] names a framework in a local file:// git repo, when woc <app> runs twice, then the first run fetches + writes wo.lock, the second builds offline from .wo-deps, and the built binary runs.
Given the dep's tag moved after wo.lock was written, when the app builds, then the lock wins and the drift is reported; woc --update-deps refreshes it.
Given a dep whose own wo.toml has [deps], or a dep name colliding with a local module, when the app builds, then each is a named diagnostic, never silent misresolution.

Out Of Scope

Registries, version ranges/semver solving, transitive dependencies (the successor's first fork), private-remote auth handling beyond what ambient git config provides, vendoring commands.

Proposed Solution

Manifest parsing extends compiler/bin/main.ml's existing wo.toml reader; fetch = Sys.command over the git binary; resolution plugs the dep root into the existing directory-as-module discovery. Fixtures under tests/ use local file:// remotes so the suite stays network-free.

2.9 KiB Raw Blame History

Iteration 15 — dependencies: wo.toml [deps], git fetch, wo.lock