@tanishqkancharla/diffmap 0.3.0 → 0.4.0

package/README.md

@@ -75,16 +75,48 @@ import {
 | Fence info string                              | Viewer                                                                                            |
 | ---------------------------------------------- | ------------------------------------------------------------------------------------------------- |
 | `mermaid`                                      | Beautiful Mermaid                                                                                 |
+| `services`                                     | Animated service diagram you can play or step through                                             |
 | `callstack` or `diff` containing `└──` / `├──` | Interactive stack rows, no file header                                                            |
 | `diff` or `diff:path` with a file path         | Pierre patch with Pierre’s file header                                                            |
 | `diff` with no path                            | Pierre patch, no file header                                                                      |
 | `changes` with a commit, range, or empty body  | Files changed card with a Review button; empty means uncommitted changes                          |
 | `start:end:path`                               | Pierre file excerpt with Pierre’s file header                                                     |
 | `html`                                         | Trusted HTML from this file. diffmap does not sanitize it. Only use it for local files you wrote. |
-| other langs                                    | Maui `CodeBlock`                                                                                  |
+| other langs                                    | Highlighted code with optional [line highlights and notes](#highlight-lines-and-add-notes)        |
 
 Fences keep whitespace. Use them for mermaid, call stacks, and diffs.
 
+### Highlight lines and add notes
+
+In a code fence, `{2,4-6}` after the language highlights those lines. Comment
+lines at the bottom of the fence add notes that show on hover or keyboard focus:
+
+````md
+```ts {2-3}
+function requestHandler(record: RecordInput) {
+  const error = validateInput(record);
+  if (error) return error;
+  return existingService(record);
+}
+// [!note validateInput] Returns an error when `name` is blank, otherwise undefined.
+// [!note L3] Early return, so storage never sees an invalid record.
+```
+````
+
+- `[!note L3]` or `[!note L3-L5]` notes a line range. Any other target is a
+  symbol, and the note covers every whole-word occurrence in the fence.
+- Start note lines with `//`, `#`, or `--`. The viewer removes them, so line
+  numbers count only the code above. Backticks in a note render as code.
+- A symbol that does not appear, overlapping line notes, or a line number
+  outside the fence is a parse error. A note line above other code stays code.
+
+Call stacks take the same highlights and notes, counting rows from the first.
+Write their notes with `#`. A symbol note matches the row text you see, not
+hidden references. Inside a linked row, symbol notes show on hover only; the
+row itself keeps keyboard focus.
+
+Run `npx @tanishqkancharla/diffmap fixtures/code-notes.md` for an example.
+
 ## MDC
 
 md4x Comark components map to the same views:
@@ -154,9 +186,17 @@ A `changes` fence shows a commit's files as a card. Each row shows the file name
 and +N −M. **Review** opens the Diff panel on all files; a row focuses that file.
 An empty body (or `working`) means uncommitted changes.
 
+Lines after the rev list the files to review, in order. The card shows those
+first and folds the rest under a dimmed **N other files** row that expands and
+collapses. Review opens the Diff panel in the same order. `serve` and `share`
+fail if a listed file is not changed in that commit. With no list, the card
+shows every file.
+
 ````md
 ```changes
 a1b2c3d
+src/request.ts
+src/validate.ts
 ```
 ````
 
@@ -188,6 +228,62 @@ Resolution uses the workspace's TypeScript configuration and current files.
 Run `npx @tanishqkancharla/diffmap fixtures/annotations.md` for an example
 with commit references, multiple files, and unchanged context.
 
+## Animated service diagrams
+
+A `services` fence shows services, their state, and the events they send each
+other, then replays those events step by step. Readers press **Play**, step with
+the arrow buttons or ← and →, or click the progress bar to jump to a step.
+
+````md
+```services
+service Browser "login page"
+  state cookie = none
+service API "HTTP server" [[src/api.ts]]
+  > Receives every request and routes it to a service.
+  service Auth
+    state attempts = 0
+      > Failures since the last success. Five locks the account.
+
+step "The browser submits the form"
+  Browser -> API: POST /login
+step "The API asks Auth to verify"
+  API -> Auth: verify(alice) [[src/api.ts#login]]
+    > Sends the username and the password from the form.
+  Auth.attempts = 1
+    > Counted before the check, so a crash still counts as a failure.
+step "The API sets the session cookie"
+  API -> Browser: 200 Set-Cookie
+  Browser.cookie = sid=s_81f
+```
+````
+
+- `service <Name> "label"` declares a service. Indent a `service` line under
+  another to nest it. Names are unique within the diagram.
+- `state <key> = <value>` declares a value and its initial state. Indent it under
+  its service.
+- `step "caption"` starts a step at column 0. The caption is required: a
+  sentence that says what happens, shown under the controls. Indented lines
+  under it are `From -> To: label` events and `Service.key = value` updates.
+  Every event in a step travels at once, and the updates land when the events
+  arrive.
+- A `>` line adds text to the line above it. Indent it further than that line;
+  consecutive `>` lines join.
+  - Under a service or state, it is a description: the name gets a dotted
+    underline and the text shows in a tooltip on hover or focus.
+  - Under a step, it explains the step and shows under the caption.
+  - Under an event or update, it is a note for that step. Notes appear in a
+    column beside the diagram once the step's events land, each joined by a
+    line to its event label or state row.
+- `%%` starts a comment line.
+- Append `[[reference]]` to a `service` line or an event to link it to source.
+
+Services must be declared before the first step, and updates may only change
+declared state. [ELK](https://eclipse.dev/elk/) lays the services out left to
+right, or top to bottom when that fits the column better, and routes one
+connection between each pair of services that talk. A request and its reply
+share that connection. Indentation is significant, so `services` has no MDC form.
+See [the runnable examples](fixtures/services.md).
+
 ## Link Mermaid nodes and edges
 
 Inside a Mermaid fence, add `%% ref node:<id> [[reference]]` to link a node or

package/index.html

@@ -48,6 +48,12 @@
       })();
     </script>
     <title>diffmap</title>
+    <!-- A + over a −, like a diff. -->
+    <link
+      rel="icon"
+      type="image/svg+xml"
+      href="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 32 32'%3E%3Crect width='32' height='32' rx='7' fill='%2318181b'/%3E%3Crect x='14.25' y='5.5' width='3.5' height='11' rx='1.75' fill='%233fb950'/%3E%3Crect x='10.5' y='9.25' width='11' height='3.5' rx='1.75' fill='%233fb950'/%3E%3Crect x='10.5' y='21.25' width='11' height='3.5' rx='1.75' fill='%23f85149'/%3E%3C/svg%3E"
+    />
   </head>
   <body>
     <div id="root"></div>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanishqkancharla/diffmap",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Serve a spec or code walkthrough as a local page",
   "license": "MIT",
   "author": "Tanishq Kancharla",
@@ -44,9 +44,10 @@
     "@pierre/diffs": "1.6.1",
     "@vitejs/plugin-react": "^6.1.1",
     "beautiful-mermaid": "^1.1.3",
+    "elkjs": "^0.11.1",
     "errore": "^0.14.1",
     "incur": "^0.4.20",
-    "maui": "npm:@tanishqkancharla/maui@0.0.47",
+    "maui": "npm:@tanishqkancharla/maui@0.0.62",
     "md4x": "^0.0.29",
     "motion": "^13.4.0",
     "purse-styles": "^0.2.3",

package/src/changes.ts

@@ -156,6 +156,21 @@ export type Changes = {
   files: ChangedFile[];
 };
 
+/**
+ * Splits files into the ones to review, in `review` order, and the rest in
+ * their original order. An empty `review` means every file is to be reviewed.
+ */
+export function orderForReview(files: ChangedFile[], review: string[]) {
+  if (review.length === 0) return { reviewed: files, other: [] };
+  const reviewed = review.flatMap(
+    (path) => files.find((file) => file.path === path) ?? [],
+  );
+  return {
+    reviewed,
+    other: files.filter((file) => !reviewed.includes(file)),
+  };
+}
+
 /** Gist file holding the changes a shared spec references, keyed by rev. */
 export const GIST_CHANGES_FILE = "diffmap-changes.json";
 

package/src/codeNotes.ts

@@ -0,0 +1,123 @@
+export type CodeNote = {
+  target:
+    | { kind: "lines"; start: number; end: number }
+    | { kind: "symbol"; symbol: string };
+  text: string;
+};
+
+/** A symbol note's match on one line: `[start, end)` columns. */
+export type SymbolMatch = { start: number; end: number; note: CodeNote };
+
+const notePrefix = /^\s*(?:\/\/|#|--)\s*\[!note\b/;
+const notePattern = /^\s*(?:\/\/|#|--)\s*\[!note\s+([^\]]+?)\s*\]\s*(.*?)\s*$/;
+const linesPattern = /^L(\d+)(?:-L(\d+))?$/;
+const identifierChar = /[\w$]/;
+
+/**
+ * Splits trailing `// [!note target] text` lines off a code fence. Blank
+ * lines between notes are allowed; note-like lines above other code stay
+ * code, so fences that document this syntax render unchanged.
+ */
+export function parseCodeNotes(source: string) {
+  const lines = source.split("\n");
+  let end = lines.length;
+  while (
+    end > 0 &&
+    (lines[end - 1]!.trim() === "" || notePrefix.test(lines[end - 1]!))
+  )
+    end--;
+  const notes = lines.slice(end).flatMap((line) => {
+    if (line.trim() === "") return [];
+    const match = notePattern.exec(line);
+    if (match === null || match[2] === "")
+      return [{ target: { kind: "symbol", symbol: "" }, text: line } as const];
+    const lineRange = linesPattern.exec(match[1]!);
+    const target: CodeNote["target"] =
+      lineRange === null
+        ? { kind: "symbol", symbol: match[1]! }
+        : {
+            kind: "lines",
+            start: Number(lineRange[1]),
+            end: Number(lineRange[2] ?? lineRange[1]),
+          };
+    return [{ target, text: match[2]! }];
+  });
+  return { code: lines.slice(0, end).join("\n"), notes };
+}
+
+/** Why a fence's highlights or notes are invalid, or undefined. `lines` is the rendered text of each line or row. */
+export function notesProblem(fence: {
+  lines: string[];
+  highlights: number[];
+  notes: CodeNote[];
+}) {
+  const lines = fence.lines;
+  const highlight = fence.highlights.find((n) => n < 1 || n > lines.length);
+  if (highlight !== undefined)
+    return `Highlighted line ${highlight} is outside the ${lines.length}-line code fence`;
+  const covered = new Set<number>();
+  for (const note of fence.notes) {
+    const target = note.target;
+    if (target.kind === "symbol") {
+      if (target.symbol === "")
+        return `Invalid note "${note.text.trim()}". Use // [!note symbol] text or // [!note L3-L5] text`;
+      if (!lines.some((line) => symbolMatches(line, target.symbol).length > 0))
+        return `Note target "${target.symbol}" does not appear in its code fence`;
+      continue;
+    }
+    if (
+      target.start < 1 ||
+      target.end < target.start ||
+      target.end > lines.length
+    )
+      return `Note lines L${target.start}-L${target.end} are outside the ${lines.length}-line code fence`;
+    for (let n = target.start; n <= target.end; n++) {
+      if (covered.has(n)) return `Line notes overlap at line ${n}`;
+      covered.add(n);
+    }
+  }
+  return undefined;
+}
+
+/** Non-overlapping symbol note matches on one line, left to right. */
+export function lineSymbolMatches(line: string, notes: CodeNote[]) {
+  const matches = notes
+    .flatMap((note) =>
+      note.target.kind === "symbol"
+        ? symbolMatches(line, note.target.symbol).map((start) => ({
+            start,
+            end:
+              start +
+              (note.target.kind === "symbol" ? note.target.symbol.length : 0),
+            note,
+          }))
+        : [],
+    )
+    .toSorted((a, b) => a.start - b.start || b.end - a.end);
+  const kept: SymbolMatch[] = [];
+  for (const match of matches) {
+    const last = kept.at(-1);
+    if (last === undefined || match.start >= last.end) kept.push(match);
+  }
+  return kept;
+}
+
+/** Start columns of `symbol` in `line`, as a whole word where it starts or ends with an identifier character. */
+function symbolMatches(line: string, symbol: string) {
+  const starts: number[] = [];
+  for (
+    let at = line.indexOf(symbol);
+    at !== -1;
+    at = line.indexOf(symbol, at + 1)
+  ) {
+    const before = line[at - 1];
+    const after = line[at + symbol.length];
+    const wordStart = identifierChar.test(symbol[0]!);
+    const wordEnd = identifierChar.test(symbol.at(-1)!);
+    if (wordStart && before !== undefined && identifierChar.test(before))
+      continue;
+    if (wordEnd && after !== undefined && identifierChar.test(after)) continue;
+    starts.push(at);
+  }
+  return starts;
+}

package/src/errors.ts

@@ -20,6 +20,11 @@ export class DiffmapMermaidError extends errore.createTaggedError({
   message: "diffmap could not parse mermaid in $path ($where): $reason",
 }) {}
 
+export class DiffmapServicesError extends errore.createTaggedError({
+  name: "DiffmapServicesError",
+  message: "diffmap could not parse services in $path ($where): $reason",
+}) {}
+
 export class DiffmapParseError extends errore.createTaggedError({
   name: "DiffmapParseError",
   message: "diffmap could not parse markdown",

package/src/git.test.ts

@@ -249,7 +249,7 @@ test("readDocumentChanges rejects unchanged files and ranges past the end", asyn
     const sha = (await git("rev-parse", "HEAD")).slice(0, 7);
     const check = (reference: { path: string; start?: number; end?: number }) =>
       readDocumentChanges(root, {
-        changeRevs: [],
+        changeCards: [],
         references: [{ kind: "file", rev: sha, ...reference }],
       });
 
@@ -269,6 +269,18 @@ test("readDocumentChanges rejects unchanged files and ranges past the end", asyn
       unchanged instanceof Error ? unchanged.message : "",
       /gone\.ts is not changed/,
     );
+
+    const review = (paths: string[]) =>
+      readDocumentChanges(root, {
+        changeCards: [{ rev: sha, review: paths }],
+        references: [],
+      });
+    assert.equal((await review(["keep.ts"])) instanceof Error, false);
+    const missing = await review(["keep.ts", "gone.ts"]);
+    assert.match(
+      missing instanceof Error ? missing.message : "",
+      /lists gone\.ts to review, but it is not changed/,
+    );
   });
 });
 

package/src/git.ts

@@ -462,10 +462,13 @@ function totals(entries: NumstatEntry[]) {
  */
 export async function readDocumentChanges(
   root: string,
-  document: Pick<ViewerDocument, "references" | "changeRevs">,
+  document: Pick<ViewerDocument, "references" | "changeCards">,
 ): Promise<Map<Rev, Changes> | DiffmapGitError> {
   // Uncommitted revs are read live; only commits are checked and snapshotted.
-  const revs = new Set<Rev>(document.changeRevs.filter(isCommitRev));
+  const commitCards = document.changeCards.filter((card) =>
+    isCommitRev(card.rev),
+  );
+  const revs = new Set<Rev>(commitCards.map((card) => card.rev));
   for (const reference of document.references) {
     if (reference.kind === "changes" || reference.rev !== undefined)
       revs.add(reference.rev!);
@@ -476,6 +479,16 @@ export async function readDocumentChanges(
     if (changes instanceof Error) return changes;
     loaded.set(rev, changes);
   }
+  for (const card of commitCards) {
+    const files = loaded.get(card.rev)!.files;
+    const missing = card.review.find(
+      (reviewPath) => !files.some((file) => file.path === reviewPath),
+    );
+    if (missing !== undefined)
+      return new DiffmapGitError({
+        reason: `changes ${card.rev} lists ${missing} to review, but it is not changed in ${card.rev}.`,
+      });
+  }
   for (const reference of document.references) {
     if (reference.kind !== "file" || reference.rev === undefined) continue;
     const file = loaded

package/src/host/HostHome.tsx

@@ -12,10 +12,18 @@ import {
 } from "../viewer/changesSource.ts";
 import { HostFilesContext } from "./files.ts";
 import homeSource from "./home.md?raw";
-import cliSource from "../cli.ts?raw";
 import shareSource from "../share.ts?raw";
-import parseViewerSource from "../parseViewer.ts?raw";
-import githubRouteSource from "../github/route.ts?raw";
+import serveSource from "../serve.ts?raw";
+import gitSource from "../git.ts?raw";
+import fetchRepoSource from "../github/fetchRepo.ts?raw";
+import fenceSource from "../viewer/Fence.tsx?raw";
+import callStackSource from "../viewer/CallStackDiff.tsx?raw";
+import sourceNavigationSource from "../viewer/sourceNavigation.ts?raw";
+import sourceDiffPanelSource from "../viewer/SourceDiffPanel.tsx?raw";
+import viewerAppSource from "../viewer/ViewerApp.tsx?raw";
+import parseFenceSource from "../parseFence.ts?raw";
+import annotationsSource from "../annotations.ts?raw";
+import hostFilesSource from "./files.ts?raw";
 
 let parserReady: Promise<void> | undefined;
 
@@ -25,10 +33,18 @@ function readyHostParser() {
 }
 
 const hostFiles = {
-  "src/cli.ts": cliSource,
   "src/share.ts": shareSource,
-  "src/parseViewer.ts": parseViewerSource,
-  "src/github/route.ts": githubRouteSource,
+  "src/serve.ts": serveSource,
+  "src/git.ts": gitSource,
+  "src/github/fetchRepo.ts": fetchRepoSource,
+  "src/viewer/Fence.tsx": fenceSource,
+  "src/viewer/CallStackDiff.tsx": callStackSource,
+  "src/viewer/sourceNavigation.ts": sourceNavigationSource,
+  "src/viewer/SourceDiffPanel.tsx": sourceDiffPanelSource,
+  "src/viewer/ViewerApp.tsx": viewerAppSource,
+  "src/parseFence.ts": parseFenceSource,
+  "src/annotations.ts": annotationsSource,
+  "src/host/files.ts": hostFilesSource,
 };
 
 /** The homepage walks through diffmap's own commits, read from GitHub. */