@prajwalghate/sourcetruth 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+## 0.1.0 — 2026-09-16
+
+First release.
+
+- **Daml and Solidity** source, detected automatically.
+- **The map** (`--html`): who can act, split into outside and inside the protocol; each action's
+  archives, creates and calls in code order, with **Play**; whose authority an action carries beyond
+  its caller; which contract ids the caller chooses; each contract's life; blind spots in amber.
+  One self-contained file, deterministic, with a guided tour and a Learn view drawn from your code.
+- **Solidity tracing**: every call site classified — typed variables, casts, libraries, `this.`, ETH
+  and low-level calls — with nothing dropped. Access checks followed through helpers, inheritance
+  and vendored modifiers, credited only when they run on every path. Inherited public functions from
+  vendored parents appear on the contracts that run them. Imports resolved through remappings,
+  node_modules and nested dependencies; missing ones reported.
+- **Daml tracing**: controllers, signatories, consuming effects, helper functions folded into the
+  choices that call them, test packages excluded.
+- `--surface`, `--holes`, `--graph`, `--json` (schemaVersion 1), `--min-resolution` for CI,
+  `--demo`, `-o`.
+- **GitHub Action** (`action.yml`): builds the map, uploads it, writes a run summary, and can fail
+  below a resolution floor.

package/GUIDE.md

@@ -0,0 +1,255 @@
+# How to use sourcetruth
+
+The same guide, with a live demo, is at **https://prajwalghate.github.io/sourcetruth/**.
+
+sourcetruth reads Daml or Solidity source and draws what it does: who can act, what each action
+changes, and what could not be traced. You do the judging. This guide gets you from install to a
+first audit, then covers every option.
+
+- [1. Install](#1-install)
+- [2. First look: the demo](#2-first-look-the-demo)
+- [3. A first audit, step by step](#3-a-first-audit-step-by-step)
+- [4. Reading the map](#4-reading-the-map)
+- [5. Pointing it at your code](#5-pointing-it-at-your-code)
+- [6. Command-line reference](#6-command-line-reference)
+- [7. In CI](#7-in-ci)
+- [8. What it cannot tell you](#8-what-it-cannot-tell-you)
+- [9. Troubleshooting](#9-troubleshooting)
+
+---
+
+## 1. Install
+
+Node 22 or newer. Nothing else.
+
+```bash
+npm install -g @prajwalghate/sourcetruth
+sourcetruth --version
+```
+
+Or without installing, from a clone:
+
+```bash
+git clone git@github.com:prajwalghate/sourcetruth.git
+node sourcetruth/bin/sourcetruth.mjs --help
+```
+
+---
+
+## 2. First look: the demo
+
+```bash
+sourcetruth --demo -o demo.html          # a small Solidity vault
+sourcetruth --demo daml -o demo-daml.html # a small Daml lending protocol
+open demo.html
+```
+
+The first time the map opens, a short tour clicks through it for you. The two demos are written to
+show everything the map can draw — an open function, a guard hidden in a helper, borrowed authority,
+a caller-chosen contract id, and a blind spot — so they are the fastest way to learn to read it.
+
+---
+
+## 3. A first audit, step by step
+
+This walks the Solidity demo. Every step is one click.
+
+1. **Look at the top bar.** `94% traced · 1 blind spot`. Nearly everything the code does could be
+   followed. Click **1 blind spot**: `Vault.execute` does a `delegatecall` to an address the caller
+   passes in. That is a line to read by hand.
+
+2. **Look at who can act.** On the left: `anyone` is *outside*; `onlyOwner`, `vault` and
+   `keepers[msg.sender]` are *inside*. Anything under `anyone` is callable with no access check.
+
+3. **Start where outsiders get in.** The panel on the right lists the actions an outsider can take,
+   riskiest first. `takeFee` is there — no check, and it moves tokens.
+
+4. **Open it and press Play.** The map shows `takeFee` writing the vault's storage and calling
+   `IERC20` — a transfer to the owner, of an amount the caller chooses.
+
+5. **Check a guarded one.** Click `harvest`. It is guarded by `keepers[msg.sender]`, and the panel
+   shows where that check lives: `_onlyKeeper() → require(keepers[msg.sender])`. The guard is a
+   helper call, not a modifier — sourcetruth follows those.
+
+6. **Follow the flow.** In `harvest`, press Play: `IStrategy.harvest`, then the fee transfer, then
+   `_invest` sending funds back to the strategy. Click `IStrategy` to see the strategy's side.
+
+7. **Read the code.** Every action has a **Code** button that opens its source, comments intact for
+   reading — though nothing on the map was derived from them.
+
+The Daml demo reads the same way. There, open `Position.Liquidate`: the liquidator **names
+themselves**, passes in the `priceCid` it is checked against, and the action runs with the
+authority of `operator` **and** `owner` — the signers of the position, not just the caller.
+
+---
+
+## 4. Reading the map
+
+| On screen | What it shows | What to do with it |
+|---|---|---|
+| **Outside / Inside** (left, or across the top on a small screen) | Every party the code lets act. *Outside* can act without the protocol's own parties. | Click one: the map lights up every contract they can reach. |
+| **The map** | Contracts as cards. Solid arrows *create*, dashed arrows *call*. Dashed cards are defined outside the code you pointed at. | Drag to pan, pinch or ⌘-scroll to zoom, **Fit** to see everything. |
+| **Where can someone outside get in?** | Actions an outsider can take alone, riskiest first. | Start at the top. |
+| **An action** | Who fires it; what it does to its own contract; **whose authority it also carries**; which contract ids the caller picks; every archive, create and call in code order. | Press **Play** (or `P`). |
+| **A contract** | Its life: made by → replaced by → ended by, and who reads it. | Look for *Nothing in this code ends it* on anything that holds value. |
+| **Blind spots** (amber) | Calls whose target can't be named from source. | Read them before trusting the rest. |
+| **Learn** | Each idea of the language, drawn with contracts from your code. | Read once if the language is new to you. |
+| **Code** | The plain listing: every contract, action, authority, link and source body. | Look things up. It is also the whole page with JavaScript off. |
+
+**Colours.** Green made · red archived or ended · blue called or selected · violet authority that is
+not the caller's own (a signer's, or no access check at all) · amber could not trace.
+
+**Typefaces.** Monospace is copied from the source. Sans-serif is the tool talking.
+
+`Esc` goes back a step. Links open the map at a place, on load or while it is open: `#e-Vault-takeFee` an action, `#u-Vault` a contract, `#a-anyone` a party, `#learn` the Learn view, `#map` the start — so a runbook or a ticket can point straight at what it means.
+
+### How "outside" is decided
+
+From the code, never from names.
+
+- **Daml:** the parties who sign the contracts nothing in the code creates are *inside*, and so are
+  the signers of any contract only ever created with an inside party's consent. A party who can act
+  without any of them is *outside*.
+- **Solidity:** a function with no access check is callable by *anyone*. A named check is a
+  privilege, and whoever holds it is *inside*.
+
+### How Solidity access checks are found
+
+A check counts when it runs on every path: in a modifier that checks the caller, or as a top-level
+`require` / `if (...) revert` on `msg.sender` — in the function itself or in a helper it calls,
+through inheritance and into vendored libraries. A check inside an `if` does **not** count: claiming a
+guard that might not run would hide an open function. `a || b` means either may call.
+
+---
+
+## 5. Pointing it at your code
+
+Point it at a repository root, or at the folder that holds the source. The language is detected.
+
+**Daml.** `.daml` files are read recursively. Skipped: `.daml/` build output, and test packages —
+any package whose `daml.yaml` name ends in `-test` or `-tests`, and directories named `test`/`tests`.
+
+**Solidity.** `.sol` files are read recursively. Skipped by default:
+
+- your dependencies in `lib/` (Foundry) and `node_modules/` — still **read**, to follow inheritance
+  and access checks, but not drawn as your code (`--include-libs` draws them);
+- tests and scripts: `test/`, `tests/`, `script/`, `scripts/`, `TestContracts/`, `mocks/`, `*.t.sol`,
+  `*.s.sol` (`--include-tests` brings them back).
+
+Imports are followed the way the compiler would: relative paths, `remappings.txt` and `foundry.toml`
+remappings, `node_modules`, and nested dependencies. Public functions a contract inherits from a
+vendored parent — `deposit()` from an ERC4626 base, say — appear on that contract, running the
+contract's own overrides.
+
+**If dependencies are missing** — typically a git submodule that was never initialised — the map
+says so at the top, and every function whose access might depend on the missing code is marked. Run
+`forge install` or `git submodule update --init` and generate the map again.
+
+---
+
+## 6. Command-line reference
+
+```
+sourcetruth <dir> [mode] [options]
+```
+
+| Mode | Output |
+|---|---|
+| *(none)* | Summary and blind spots in the terminal |
+| `--html` | The interactive map, one self-contained file |
+| `--surface` | State-changing actions at most one party can take alone |
+| `--holes` | Only the calls that could not be traced |
+| `--graph` | Contract-to-contract creates and calls |
+| `--json` | The full model (see below) |
+
+| Option | |
+|---|---|
+| `-o, --out <file>` | Write to a file instead of stdout |
+| `--title <text>` | Name the map (default: the directory name) |
+| `--lang daml\|evm` | Force the language |
+| `--min-resolution N` | Exit 1 if less than N% of links could be traced |
+| `--include-tests` | Include test packages and test contracts |
+| `--include-libs` | Draw vendored dependencies as if they were your code |
+| `--dated` | Stamp today's date on the map (off by default, so maps from the same commit are identical) |
+| `--demo [daml\|solidity]` | Render a bundled example |
+| `-v, --version` · `-h, --help` | |
+
+**Exit codes.** `0` success · `1` nothing found, or below `--min-resolution` · `2` bad usage.
+Blind spots alone never fail a run.
+
+**JSON.** `--json` prints `{ "schemaVersion": 1, "tool": {...}, "units": [...], "entries": [...], ... }`.
+`schemaVersion` changes only when a field changes meaning or is removed.
+
+```bash
+# every state-changing function with no access check
+sourcetruth ./src --json | jq -r '.entries[] | select(.authority == [] and .effect != "none" and (.declared|not)) | "\(.unit).\(.name)"'
+```
+
+---
+
+## 7. In CI
+
+### GitHub Actions
+
+```yaml
+name: sourcetruth
+on: [pull_request]
+jobs:
+  map:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: recursive        # so inherited code and access checks can be read
+      - uses: prajwalghate/sourcetruth@v0
+        with:
+          path: ./contracts
+          min-resolution: 90
+```
+
+Inputs: `path`, `title`, `min-resolution` (0 = off), `output` (default `sourcetruth-map.html`),
+`include-tests`, `upload`. Outputs: `resolution`, `blind-spots`. Each run uploads the map as the
+`sourcetruth-map` artifact and writes a summary table.
+
+### Anywhere else
+
+```bash
+npx @prajwalghate/sourcetruth ./contracts --min-resolution 90
+```
+
+Pick the floor from today's number, not from 100: if you are at 94%, set 90. When a change makes the
+number drop, a construct the tool can't follow has arrived — worth knowing on the pull request.
+
+---
+
+## 8. What it cannot tell you
+
+- **Whether anything is a bug.** It draws; you judge.
+- **Runtime facts.** Which contract id a caller will actually pass, who holds a role, what a proxy
+  currently points at, what value a price has.
+- **Branches.** It cannot tell which path runs. An action that archives a contract and creates one
+  is shown as possibly replacing it *and* possibly ending it.
+- **Arithmetic.** Overflow, rounding, decimals — none of it.
+- **Inside a blind spot.** A `delegatecall` to a caller's address, an assembly `call`, a receiver
+  whose type can't be worked out: shown, never followed.
+- **Code that isn't on disk.** Missing imports are reported, not guessed.
+
+---
+
+## 9. Troubleshooting
+
+**"0 contracts found."** You pointed at build output or an empty folder. Point at the repository
+root or the source folder.
+
+**A function you know is guarded shows as `anyone`.** Check the top of the map for a *not on disk*
+note — the guard may live in a dependency that isn't installed. If everything resolved, the check
+may be inside an `if`, which is deliberately not credited. The **Code** button shows the source.
+
+**A contract is missing.** It may be in a skipped folder (`test/`, `mocks/`, `TestContracts/`,
+`lib/`). Use `--include-tests` or `--include-libs`.
+
+**Resolution is lower than you expected.** Run `sourcetruth <dir> --holes` and look at the lines:
+they share a pattern, and that pattern is what the tool couldn't follow.
+
+**The map looks empty.** Click **Fit** (bottom right). On very large codebases the opening view
+zooms in on the riskiest action so the cards are readable.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Prajwal Ghate
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,79 @@
+# sourcetruth
+
+[![npm](https://img.shields.io/npm/v/@prajwalghate/sourcetruth)](https://www.npmjs.com/package/@prajwalghate/sourcetruth)
+[![test](https://github.com/prajwalghate/sourcetruth/actions/workflows/test.yml/badge.svg)](https://github.com/prajwalghate/sourcetruth/actions/workflows/test.yml)
+[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+**[Documentation](https://prajwalghate.github.io/sourcetruth/)** · **[Live demo](https://prajwalghate.github.io/sourcetruth/demo)** · [Guide](GUIDE.md)
+
+See what smart-contract code **does** — who can act, and what each action changes — straight from
+the source. And see, just as plainly, what it **could not trace**.
+
+Works on **Daml** (Canton) and **Solidity**. One command, one self-contained HTML file, no server.
+
+```bash
+sourcetruth --demo -o demo.html          # a first look, on a bundled example
+sourcetruth ./contracts --html -o map.html
+```
+
+## What you get
+
+A map of the protocol you can click through:
+
+- **Who can act** — every party the code lets take an action, split into those *outside* the
+  protocol and those running it. Worked out from the code, not from what things are called.
+- **What an action does** — pick one and press **Play**: what it archives, what it creates, what it
+  calls, in the order the code does them, and whose authority it carries beyond the caller's own.
+- **Each contract's life** — what makes it, what replaces it, what ends it.
+- **Blind spots** — every call whose target can't be named from source is shown in amber. The tool
+  never guesses one and never drops one.
+
+Comments are stripped before anything is read. If a comment says a function is admin-only and the
+code says otherwise, the map shows the code.
+
+## Install
+
+Node 22 or newer. No dependencies.
+
+```bash
+npm install -g @prajwalghate/sourcetruth
+sourcetruth --version
+```
+
+## Use it
+
+```bash
+sourcetruth <dir>                      # summary + blind spots in the terminal
+sourcetruth <dir> --html -o map.html   # the interactive map
+sourcetruth <dir> --surface            # actions one party can take alone
+sourcetruth <dir> --json               # the full model, for your own tooling
+sourcetruth <dir> --min-resolution 90  # for CI: fail if too little can be traced
+```
+
+**[GUIDE.md](GUIDE.md)** walks through a first audit, reading the map, every option, CI, and what
+the tool cannot tell you.
+
+## In CI
+
+```yaml
+- uses: prajwalghate/sourcetruth@v0
+  with:
+    path: ./contracts
+    min-resolution: 90
+```
+
+The map is uploaded as a workflow artifact and a summary is written to the run.
+
+## Contributing
+
+Bug reports with a small piece of code that shows the problem are the most useful thing you can send
+— unfamiliar code is how most of this tool's bugs have been found. See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## What it is not
+
+Not a bug finder. It has no vulnerability patterns and makes no judgement about whether code is
+wrong. It draws what the code does so a person can decide — and it stores no findings.
+
+## License
+
+[MIT](LICENSE)

package/bin/sourcetruth.mjs

@@ -0,0 +1,188 @@
+#!/usr/bin/env node
+// sourcetruth — read what contract code does, from source, and say what could not be determined.
+//
+// Exit codes: 0 parsed, 1 nothing found or below --min-resolution, 2 bad usage. Holes are NOT a
+// failure — an honest 80% is the output, not an error.
+//
+// WHY THIS IS A FUNCTION WITH RETURNS, and never calls process.exit():
+// stdout to a pipe is ASYNCHRONOUS. `process.exit()` tears the process down before the buffer
+// drains, and `--json` on a real codebase was truncating at exactly 65282 bytes — a 64 KB pipe
+// buffer — emitting JSON that ended mid-string. It looked perfect in a terminal, where stdout is
+// synchronous, and broke the instant anyone piped it to jq. Set `process.exitCode` and return;
+// Node then exits on its own once the buffer has flushed.
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import daml from "../src/adapters/daml.mjs";
+import evm from "../src/adapters/evm.mjs";
+import { graph, attackSurface } from "../src/model.mjs";
+import { render as renderHtml } from "../src/report.mjs";
+
+const PKG = JSON.parse(fs.readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+const ADAPTERS = { daml, evm, solidity: evm };
+
+/** The JSON shape's version. Bump it when a field changes meaning or goes away — tools key off it. */
+const SCHEMA_VERSION = 1;
+
+const USAGE = `sourcetruth ${PKG.version} — see what contract code does, from source
+
+Usage
+  sourcetruth <dir> [mode] [options]
+
+Modes (pick one; the default prints a summary and the blind spots)
+  --html               the interactive map, as one self-contained HTML file
+  --surface            state-changing actions that at most one party can take alone
+  --holes              only what could not be traced
+  --graph              contract-to-contract calls and creates
+  --json               the full model, for your own tooling
+
+Options
+  -o, --out <file>     write the output to a file instead of stdout
+  --title <text>       name the map (default: the directory name)
+  --lang daml|evm      force the language (default: detected)
+  --min-resolution N   exit 1 if less than N% of links could be traced (for CI)
+  --include-tests      include test packages, TestContracts/, mocks/, *.t.sol
+  --include-libs       report vendored dependencies (lib/) as if they were this code
+  --dated              stamp today's date on the map (off by default, so maps diff cleanly)
+  --demo [daml|solidity]  render a bundled example instead of <dir> (default: solidity)
+  -v, --version        print the version
+  -h, --help           print this
+
+Examples
+  sourcetruth --demo -o demo.html
+  sourcetruth ./contracts --html -o map.html
+  sourcetruth ./daml --surface
+  sourcetruth . --json | jq '.entries[] | select(.authority == []) | .name'
+  sourcetruth ./src --min-resolution 90`;
+
+/** Pick an adapter by what the tree contains. Ties go to whichever has more files. */
+function detectLanguage(root) {
+  try {
+    const nDaml = daml.findSources(root).length;
+    const nSol = evm.findSources(root).length;
+    if (nSol > nDaml) return "evm";
+    if (nDaml > 0) return "daml";
+    return nSol > 0 ? "evm" : "daml";
+  } catch { return "daml"; }
+}
+
+function main(input) {
+  let argv = [...input];
+  const flag = (...names) => names.some((n) => argv.includes(n));
+  const opt = (names, d = null) => {
+    for (const n of [].concat(names)) { const i = argv.indexOf(n); if (i >= 0) return argv[i + 1] ?? d; }
+    return d;
+  };
+  // A bare word that is not the value of an option that takes one.
+  const VALUED = new Set(["--min-resolution", "--lang", "--title", "-o", "--out", "--demo"]);
+  let target = argv.find((a, i) => !a.startsWith("-") && !VALUED.has(argv[i - 1]));
+
+  if (flag("--help", "-h")) { console.log(USAGE); return 0; }
+  if (flag("--version", "-v")) { console.log(PKG.version); return 0; }
+  // A first look before pointing it at real code: render one of the bundled examples.
+  if (flag("--demo")) {
+    const which = String(opt("--demo", "solidity"));
+    const dir = /^(daml)$/i.test(which) ? "daml-lending" : "solidity-vault";
+    target = fileURLToPath(new URL(`../examples/${dir}`, import.meta.url));
+    if (!flag("--html", "--json", "--surface", "--holes", "--graph")) argv = [...argv, "--html"];
+    if (!argv.includes("--title")) argv = [...argv, "--title", `sourcetruth demo — ${dir}`];
+  }
+  if (!target) { console.error(USAGE); return 2; }
+  if (!fs.existsSync(target)) { console.error(`sourcetruth: no such file or directory: ${target}`); return 2; }
+
+  const lang = opt("--lang") ?? detectLanguage(path.resolve(target));
+  const adapter = ADAPTERS[lang];
+  if (!adapter) {
+    console.error(`no adapter for "${lang}" (have: ${Object.keys(ADAPTERS).join(", ")})`);
+    return 2;
+  }
+
+  let m;
+  try { m = adapter.parse(path.resolve(target), { includeLibs: flag("--include-libs"), includeTests: flag("--include-tests") }); }
+  catch (e) { console.error(`parse failed: ${e.message}`); return 1; }
+
+  // Output goes to stdout, or to --out. Either way it is written once, whole.
+  const outFile = opt(["-o", "--out"]);
+  const lines = [];
+  const say = (s = "") => lines.push(s);
+  const flush = () => {
+    const text = `${lines.join("\n")}\n`;
+    if (outFile) {
+      fs.writeFileSync(outFile, text);
+      console.error(`wrote ${outFile} (${Math.max(1, Math.round(Buffer.byteLength(text) / 1024))} KB)`);
+    } else process.stdout.write(text);
+  };
+
+  if (flag("--json")) {
+    say(JSON.stringify({ schemaVersion: SCHEMA_VERSION, tool: { name: "sourcetruth", version: PKG.version }, ...m }, null, 2));
+    flush();
+    return 0;
+  }
+
+  if (flag("--html")) {
+    // No timestamp unless asked: a report that differs every run cannot be diffed between commits,
+    // and "what changed since last week" is the question this format is for.
+    say(renderHtml(m, {
+      title: opt("--title", `sourcetruth — ${path.basename(path.resolve(target))}`),
+      generatedAt: flag("--dated") ? new Date().toISOString().slice(0, 10) : null,
+    }));
+    flush();
+    return 0;
+  }
+
+  if (flag("--holes")) {
+    for (const h of m.holes) say(`${h.path}  ${h.owner}  ${h.kind}  ${h.raw}`);
+    flush();
+    return 0;
+  }
+  if (flag("--graph")) {
+    for (const e of graph(m).edges) {
+      say(`${e.from} --${e.kind}--> ${e.to}${e.external ? " [external]" : ""}  (${e.via.join(", ")})`);
+    }
+    flush();
+    return 0;
+  }
+  if (flag("--surface")) {
+    for (const e of attackSurface(m)) {
+      say(`${String(e.unguarded ? "ANYONE" : e.authority).padEnd(18)} ${`${e.unit}.${e.name}`.padEnd(38)} ${e.effect.padEnd(11)} moves:${e.moves} holes:${e.holes}  ${e.path}:${e.line}`);
+    }
+    flush();
+    return 0;
+  }
+
+  // Default: the summary an auditor wants first.
+  const s = m.stats;
+  say(`\n  ${m.language}  ${m.root}`);
+  say(`  ${s.modules} module(s)  ${s.units} unit(s)  ${s.entries} entr(ies)  ${s.edges} edge(s)`);
+  if (s.resolution !== null) {
+    say(`\n  resolution   ${s.resolution}%   (${s.holes} edge(s) could not be resolved from source)`);
+  }
+  say(`  solo-authority entries: ${s.soloAuthority}    terminal entries: ${s.terminal}`);
+  for (const n of m.notes) say(`  note: ${n}`);
+
+  if (m.holes.length) {
+    say(`\n  HOLES — what this tool could not determine. Not guessed, not omitted:`);
+    const byOwner = new Map();
+    for (const h of m.holes) {
+      if (!byOwner.has(h.owner)) byOwner.set(h.owner, []);
+      byOwner.get(h.owner).push(h);
+    }
+    for (const [owner, hs] of [...byOwner].slice(0, 20)) {
+      say(`    ${owner}`);
+      for (const h of hs.slice(0, 4)) say(`      ${h.kind.padEnd(8)} ${h.raw.slice(0, 84)}`);
+      if (hs.length > 4) say(`      … ${hs.length - 4} more`);
+    }
+    if (byOwner.size > 20) say(`    … ${byOwner.size - 20} more entr(ies) with holes`);
+  }
+  flush();
+
+  const floor = opt("--min-resolution");
+  if (floor !== null && s.resolution !== null && s.resolution < Number(floor)) {
+    console.error(`  resolution ${s.resolution}% is below the required ${floor}%`);
+    return 1;
+  }
+  return s.units === 0 ? 1 : 0;
+}
+
+process.exitCode = main(process.argv.slice(2));

package/examples/daml-lending/daml.yaml

@@ -0,0 +1,7 @@
+sdk-version: 3.3.0
+name: example-lending
+version: 0.1.0
+source: src
+dependencies:
+  - daml-prim
+  - daml-stdlib

package/examples/daml-lending/src/Lending.daml

@@ -0,0 +1,92 @@
+-- A small lending protocol, written to show what sourcetruth draws. Not production code.
+module Lending where
+
+template Pool
+  with
+    operator : Party
+    rateBps : Int
+  where
+    signatory operator
+
+    nonconsuming choice OpenPosition : ContractId Position
+      with
+        owner : Party
+        collateral : Decimal
+      controller owner
+      do
+        assertMsg "collateral must be positive" (collateral > 0.0)
+        create Position with operator; owner; collateral; debt = 0.0
+
+    choice SetRate : ContractId Pool
+      with
+        newRate : Int
+      controller operator
+      do
+        create this with rateBps = newRate
+
+template Position
+  with
+    operator : Party
+    owner : Party
+    collateral : Decimal
+    debt : Decimal
+  where
+    signatory operator, owner
+
+    choice Borrow : ContractId Position
+      with
+        amount : Decimal
+        priceCid : ContractId Price
+      controller owner
+      do
+        price <- fetch priceCid
+        assertMsg "undercollateralised" (collateral * price.value >= (debt + amount) * 1.5)
+        create this with debt = debt + amount
+
+    choice Repay : ContractId Position
+      with
+        amount : Decimal
+      controller owner
+      do
+        create this with debt = debt - amount
+
+    choice Close : ()
+      controller owner
+      do
+        assertMsg "debt outstanding" (debt == 0.0)
+        pure ()
+
+    choice Liquidate : ContractId Receipt
+      with
+        liquidator : Party
+        priceCid : ContractId Price
+        evidence : [ContractId Price]
+      controller liquidator
+      do
+        price <- fetch priceCid
+        let (primary, backup) = (priceCid, head evidence)
+        second <- fetch backup
+        assertMsg "position is healthy" (collateral * price.value < debt * 1.1 && price.value == second.value)
+        create Receipt with operator; liquidator; seized = collateral
+
+template Receipt
+  with
+    operator : Party
+    liquidator : Party
+    seized : Decimal
+  where
+    signatory operator
+
+template Price
+  with
+    oracle : Party
+    value : Decimal
+  where
+    signatory oracle
+
+    choice Update : ContractId Price
+      with
+        newValue : Decimal
+      controller oracle
+      do
+        create this with value = newValue

package/examples/solidity-vault/foundry.toml

@@ -0,0 +1,2 @@
+[profile.default]
+src = "src"