Render Code Shape

Render Code Shape

Code has a waterline. Above it sits the shape: modules and their boundaries, the types and values that cross those boundaries, the signatures, and the order calls actually happen in. Below it sits syntax and the statements inside a body.

Render the shape and collapse everything below the waterline to a single line of intent. Only bodies are pseudo — every name, type, and path is read from the source and cited by file and line, or marked [NEW]. This is why the render is trustworthy in a way a remembered summary is not.

Read-only. The render is the deliverable, not the edit. Producing a render never authorizes changing production code, tests, or configuration. Implement only if the request separately authorizes it, and then under the governing workflow — tdd for behavior change, refactoring or reduce-system-complexity for behavior-preserving work.

A render is not a verdict. It states what is visible in the render. Deciding whether a boundary is well-drawn belongs to codebase-design; deciding where files should live belongs to structure-codebase; ranking architecture investments belongs to improve-codebase-architecture.

Load alongside: planning (a [NEW] render is an input to a slice plan, never a substitute for one), codebase-design and structure-codebase (judgments about the shape once it is visible), finding-seams (when the render exposes an untestable dependency), characterisation-tests (when the existing path has no behavior evidence), diagrams (when relationships are materially clearer drawn than listed), technical-writing (when the render becomes a durable document).

1. Frame the render

Name the entry points to trace from and the frame edge — the packages, services, and libraries that count as outside. Name each wiring to render: production, plus any composition root that substitutes a dependency, such as tests, local dev, or a feature flag.

Classify each entry point existing or [NEW]. For a [NEW] render, resolve the requirement it must satisfy and the existing code it attaches to.

Prefer the narrowest frame that answers the question asked. A render that expands to the whole repository answers nothing.

Complete when: the entry points, the frame edge, every wiring, and the existing/[NEW] split are each explicit.

2. Read the parts

Follow every call from each entry point, opening each file on the path. For every function reached, record its file and line, its signature as written, the effects it causes, and the calls it makes.

Expand a path until it reaches a boundary crossing, a pure leaf, the frame edge, or a function already recorded. A path ends nowhere else.

For a [NEW] render, read the surrounding modules the change attaches to with the same rigour; parts that do not exist yet are derived from the requirement and marked.

Read the source. A signature recalled from training data, inferred from a name, or carried over from an older revision is a fabrication even when it happens to be right — and the citation is what makes the difference checkable.

Complete when: every path terminates on one of those four conditions, and every name that will appear in the render is either recorded with a file and line or marked [NEW].

3. Render the shape

Write in the project's own language and naming — the glossary term, not a synonym (see ubiquitous-language). Three parts:

Types — every type, interface, or schema that crosses a boundary, declared with its fields. A type from outside the frame is named and marked external.

Boundaries — one row per module: what it owns, what it exposes, what it depends on, and what it hides behind that surface.

Signatures — grouped under their module, each carrying parameter names, parameter types, return type, and error type as written in the source. Each body collapses to a single line naming its intent.

Where the cut is not obvious, place it here:

Complete when: every type named in a signature is declared here or marked external, every module row states what it hides, and every signature matches its source or carries [NEW].

4. Render the call graph

One graph per wiring, as an indented tree. Each edge reads → Receiver.method(arg: Type, arg: Type) : Return, then its annotations, then its file and line. Order siblings by execution order.

submitCheckout(req: HttpRequest) : HttpResponse                          src/http/checkout.ts:14
  → Checkout.submit(cart: Cart, actor: UserId) : Receipt                 src/checkout/service.ts:31
      → Pricing.quote(cart: Cart) : Quote                                src/pricing/quote.ts:8
          → TaxRates.lookup(region: Region) : TaxTable  [boundary: network]   src/pricing/tax.ts:22
      → Payments.charge(quote: Quote, card: CardRef) : Receipt  [boundary: network]   src/payments/stripe.ts:40
      → Orders.insert(order: Order) : OrderId  [boundary: database]      src/orders/store.ts:17
      → Email.receipt(to: EmailAddress, receipt: Receipt) : void  [async]   src/mail/queue.ts:9
      → Checkout.release(cart: Cart) : void  [error: charge declined]    src/checkout/service.ts:58

Annotate every edge that is not a plain unconditional in-process call with at least one:

A function already drawn appears as → Name (above) in place of a second expansion.

Complete when: every edge names the values crossing it, every non-plain edge carries an annotation, every branch terminates on a step 2 condition, and each wiring that differs from production is drawn beside it.