checkpointer 0.2.0 → 0.3.0

package/README.md

@@ -1,6 +1,6 @@
 # checkpointer
 
-> Git-isolated checkpoints that humans and AI agents share — save working states, revert anytime, ship a range as one clean commit.
+> Git-isolated checkpoints that humans and AI agents share — save working states, revert anytime, ship a range as one clean commit, and map your TypeScript/JavaScript or Java call graph in the browser.
 
 When you (or an AI agent) work through a long task, you want save points: a way to
 mark "this works", roll back when something breaks, and at the end turn all that
@@ -11,6 +11,7 @@ repo kept outside your project — so your real `git log` stays clean until you
 - **Isolated from your repo** — checkpoints live in `~/.checkpointer`, never in your project's `.git`. Nothing shows up in `git log` until you `ship`.
 - **Captures everything** — unlike editor undo, it snapshots the whole working tree, including files changed by scripts, formatters, and codemods.
 - **Ships to one commit** — bundle a range of checkpoints into a single commit on your branch, then push when you're ready.
+- **Maps your code** — `checkpointer graph` opens an interactive, searchable function call-graph of your TypeScript/JavaScript or Java project in the browser, so you can see how functions reach each other before you change them. Polyglot repos render as one combined graph. Fully offline.
 
 ## Install
 
@@ -21,6 +22,43 @@ npx checkpointer <command>       # or run without installing
 
 Requires Node 18+ and git. Also available as `ckpt`.
 
+### Without npm (git clone)
+
+If you can't access the npm registry, clone the repo — `dist/cli.js` is committed and is a single self-contained bundle with no runtime dependencies:
+
+```bash
+git clone https://git.soma.salesforce.com/v-akshay/checkpointer.git
+cd checkpointer
+node dist/cli.js --help
+```
+
+To use it like a regular command (`ckpt`) without typing `node dist/cli.js` every time:
+
+```bash
+# macOS / Linux — copy to somewhere on your PATH
+sudo cp dist/cli.js /usr/local/bin/ckpt
+sudo chmod +x /usr/local/bin/ckpt
+ckpt --help
+
+# or add the dist folder to your PATH in ~/.zshrc / ~/.bashrc
+export PATH="$PATH:/path/to/checkpointer/dist"
+alias ckpt="node /path/to/checkpointer/dist/cli.js"
+```
+
+Then `cd` into any git project and start checkpointing:
+
+```bash
+cd ~/my-project
+node /path/to/checkpointer/dist/cli.js init   # or just: ckpt init
+```
+
+To rebuild from source (only needed if you edit the TypeScript):
+
+```bash
+npm install   # installs tsup + typescript — dev tooling only
+npm run build
+```
+
 ## Quick start
 
 ```bash
@@ -134,9 +172,9 @@ checkpointer ship --force -m "..."                     # include broken checkpoi
 ## Visualizing your code (`graph`)
 
 Debugging an unfamiliar codebase is easier when you can *see* how functions call
-each other. `checkpointer graph` parses your TypeScript/JavaScript project with the
-TypeScript compiler (so calls resolve accurately — methods, `this.`, and imports,
-not just name matches) and opens an interactive map in your browser:
+each other. `checkpointer graph` parses your TypeScript/JavaScript or Java project
+(so calls resolve accurately — methods, `this.`, inheritance, and imports, not just
+name matches) and opens an interactive map in your browser:
 
 ```bash
 checkpointer graph                  # analyze + serve on localhost + open the browser
@@ -154,17 +192,26 @@ In the viewer you can:
 - **Search** any function by name or file; jump straight to it.
 - **Focus a function** to see its **ancestors** (everyone who reaches it, up to the
   entrypoints) beside its **descendants** (everything it calls) — both expandable.
-- See each function's **JSDoc/comment description**, kind (function/method/constructor),
-  async flag, parameters, and `file:line`, with recursion and cycles flagged inline.
+- See each function's **full signature** with type-checker-resolved parameter and
+  return types — so you learn what it takes and returns even when there's no comment —
+  alongside its description, a **per-parameter table** (name, type, optional, JSDoc
+  `@param` prose when present), kind (function/method/constructor), async flag, and
+  `file:line`, with recursion and cycles flagged inline.
+- Hit **"view code"** on any function to read its source inline, embedded in the page —
+  nothing is fetched.
 
 The page is fully self-contained and offline — no CDN, no telemetry, the graph data is
 embedded inline. `--out` produces a single file you can commit or share. Analysis is
 read-only and never creates a checkpoint.
 
-Today `graph` analyzes **TypeScript/JavaScript** (`.ts`/`.tsx`/`.js`/`.jsx`/`.mjs`/`.cjs`),
-since the accurate call resolution comes from the TypeScript compiler; support for more
-languages is planned. In a project with no TS/JS sources it says so cleanly — the other
-commands (`save`/`restore`/`ship`) work in any repository regardless of language.
+`graph` analyzes **TypeScript/JavaScript** (`.ts`/`.tsx`/`.js`/`.jsx`/`.mjs`/`.cjs`) and
+**Java** (`.java`). TS/JS calls resolve through the TypeScript compiler; Java is parsed
+with [`java-parser`](https://www.npmjs.com/package/java-parser) and resolved through a
+symbol table (fields, locals, parameters, and the superclass chain) so `this.m()`,
+`obj.m()`, `Type.staticM()`, inherited methods, and `new X()` all map to the right
+declaration. A repo with both languages renders as **one combined graph**; support for
+more languages is planned. In a project with no analyzable sources it says so cleanly —
+the other commands (`save`/`restore`/`ship`) work in any repository regardless of language.
 
 ## Using it with AI agents