Ship

Old Docs · Future Tooling
On this page · 5 sections

Future Tooling

Tooling not yet part of Ship's implemented application workflow stack.

Current Boundary

ship already owns parse/check/fmt, build/run/test/dev, read-only plans, database workflows, and managed resources. Build, run, test, and dev compile the same typed workflow graph their ship plan counterpart renders; external engines stay behind typed adapters.

Deferred Tools

Defer these until their contracts earn a stable surface:

ToolWhy later
ship lintNeeds a clear split between semantic errors, style, and deployment confidence
ship lspValuable, but expensive while the surface still moves; keep diagnostics structured so LSP stays easy
Contract-attached API docsLiterate //! chapters and numbered docs already build through apps/ship-site; public API extraction still needs a checked contract

Incremental Builds

Ship does not need a committed app interface-artifact format, deterministic JSON contract output, or separate-compilation cache design yet. DEV does retain an in-memory checked module graph with stable source paths, direct dependency edges, SCC membership, conservative opaque-body edges, and typed invalidation reasons. Exact Core dependency graphs are reused by toolchain identity. Application inference still checks the whole invalidated project generation; the graph is the foundation for later per-module checked IR reuse, not a second on-disk cache format.

Browser emission has an analogous process-local boundary. The exact Core toolchain and structural browser capabilities produce ship-core.js; app IR produces the self-accepting main.js. Core code is cached in memory and emitted as an unchanged file, while ordinary app edits rewrite only main.js. These generated modules are development/build outputs, not a public package ABI. The same checked IR derives a versioned, collision-free model-shape descriptor for HMR state preservation; runtime exceptions never decide compatibility.

The Core stdlib is a separate case: each toolchain build produces one external, versioned checked artifact (logical sources, checked interface/provider facts, runtime IR, and comptime IR) under its compiler library directory. Sections are independently hashed and decoded lazily, so ship check does not decode runtime IR. The filename and header carry a compiler/source identity; Cargo/Ship toolchain assembly regenerates it automatically. It is not a general package cache or a stable cross-version ABI. See 06-runtime-and-implementation.md.

Measured Artifact Evolution

Keep one aggregate compiler-local external Core artifact. Reject cross-compiler artifact compatibility as a goal.

Optimize only behind measured thresholds (record baselines beside the benchmark before changing layout):

  • The source/interface/runtime/comptime split is established. Prefer making the checked-interface section more compact before adding finer-grained lazy indexes, target partitions, mmap, compression, or reachability stripping.

  • Do not turn in-memory app invalidation metadata into package ABI stability, remote-cache authority, or Swift-style textual module interfaces in this track.

  • Keep Core artifact evolution distinct from any future app build cache.

Build Manifest

Convention-first layout is settled. Optional manifest name/shape remains open in ../questions/230-build-manifest-name-and-shape.md.

Extend the checked graph to per-module inference/IR reuse when measurements show mutable application checking—not stable Core graph work—on the critical path. Useful research context: