@tanishqkancharla/diffmap 0.3.0 → 0.6.0

package/README.md

@@ -75,16 +75,56 @@ import {
 | Fence info string                              | Viewer                                                                                            |
 | ---------------------------------------------- | ------------------------------------------------------------------------------------------------- |
 | `mermaid`                                      | Beautiful Mermaid                                                                                 |
+| `services`                                     | Animated service diagram you can play or step through                                             |
+| `mermaid diff` or `services diff`              | The same diagram with [added and removed parts marked](#diagram-diffs)                            |
 | `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 [titles, 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.
+
+Add `[Title]` after the language to show a title above the code, as in
+` ```ts [src/request.ts] {2-3} `. Call stacks and `mermaid` fences take a
+title the same way, as in ` ```mermaid diff [Request flow] `, or
+`::callstack{title="Request flow"}` and `::mermaid{title="Request flow"}` in
+MDC. A `services` fence uses its [start caption](#animated-service-diagrams)
+instead.
+
+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:
@@ -114,8 +154,13 @@ startServer
 ::html
 <aside>Note.</aside>
 ::
+
+::details{summary="How it works"}
+Folded content: prose, lists, and any fence above.
+::
 ```
 
+`::details` folds its content under the `summary` label until the reader opens it.
 `.md` and `.mdx` are both markdown. Curly braces in prose are plain text.
 
 ## Link call stacks to source changes
@@ -154,9 +199,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 +241,123 @@ 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.
+
+start "Alice logs in"
+  > She is signed out.
+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.
+- `start "caption"` at column 0, before the first step, captions the whole
+  diagram, such as `start "Alice logs in"`. It shows above the diagram until
+  the reader steps, and each step's caption replaces it. A `>` line under it
+  can say what the initial state shows. A `services` fence takes no `[Title]`;
+  the start caption is its title.
+- `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 `start` or a step, it explains the caption and shows under it.
+  - 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).
+
+## Diagram diffs
+
+Add `diff` after `mermaid` or `services` to show a change in one diagram.
+Start every line with `-` for Today only, `+` for Proposed only, or a space
+for both, as in a call stack diff. Indentation starts after that column.
+
+````md
+```mermaid diff
+ flowchart LR
+   Client --> Handler
+-  Handler --> Service
++  Handler --> Validate
++  Validate --> Service
+```
+````
+
+diffmap draws every line once, so both versions share one layout. Nodes,
+edges, sequence participants, and messages that only Today has are red and
+dashed; those only Proposed has are green. A node whose label differs between
+the versions is amber and shows its Proposed label. Each version must also be
+a valid diagram on its own. To relabel a node, declare it on its own line
+(`-  B[Old]`, `+  B[New]`) so its edges are not drawn twice. In a diff,
+`%% ref edge:<index>` counts edges as drawn: within each run of changed lines,
+`+` lines come before `-` lines.
+
+````md
+```services diff
+ service API
+-  service SessionCache
+-    state active = 0
++  service Sessions
+ service Postgres
+-  state sessions = not used
++  state sessions = 0 rows
+
+ start "Sessions move to Postgres"
+-step "API caches the session"
+   API -> SessionCache: create(alice)
+   SessionCache.active = 1
++step "Sessions writes the session"
+   API -> Sessions: create(alice)
+   Sessions -> Postgres: INSERT
+   Postgres.sessions = 1 row
+```
+````
+
+In a `services diff`, lines inside a `-` or `+` service or step take its
+sign. Today replays the unmarked and `-` lines and Proposed the unmarked and
+`+` lines, so each state row shows Today's value struck through beside
+Proposed's when they differ. A `-` and a `+` declaration of the same state key
+give each version its own starting value. Added and removed steps color their
+segment of the progress bar, and their caption starts with **Added** or
+**Removed**. See [the runnable examples](fixtures/diagram-diffs.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.6.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/annotations.ts

@@ -26,10 +26,26 @@ export type SourceReference = FileReference | ChangesReference;
 export type SourceAnnotation = {
   text: string;
   references: SourceReference[];
+  /** Source panel title while selected, such as a call stack row without its tree. */
+  title?: string;
 };
 
 export function parseCallStack(source: string): SourceAnnotation[] {
-  return source.split("\n").map(parseAnnotation);
+  return source.split("\n").map((line) => {
+    const annotation = parseAnnotation(line);
+    return {
+      ...annotation,
+      title: callStackRow(annotation.text).description.trim(),
+    };
+  });
+}
+
+/** A call stack row's change mark, tree prefix, and the call it describes. */
+export function callStackRow(text: string) {
+  const sign = text.startsWith("+") ? "+" : text.startsWith("-") ? "-" : " ";
+  const label = text.replace(/^[+ -]/, "");
+  const tree = /^[ \t│┃├└─]*/u.exec(label)![0];
+  return { sign, tree, description: label.slice(tree.length) };
 }
 
 export function parseAnnotation(line: string): SourceAnnotation {

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/extractDocument.ts

@@ -12,9 +12,17 @@ export function extractTitle(source: string) {
 export function extractFences(source: string) {
   const fences: Fence[] = [];
   for (const match of source.matchAll(fencePattern)) {
-    const lang = match[1] ?? "";
+    const lang = (match[1] ?? "").trim();
     const body = match[2] ?? "";
-    fences.push(parseFence(lang.trim(), body));
+    // A diagram's info string can add `diff`, and Mermaid a [Title].
+    const diagram = /^(mermaid|services)\b\s*(diff)?\s*(?:\[([^\]]*)\])?$/.exec(
+      lang,
+    );
+    fences.push(
+      diagram === null
+        ? parseFence(lang, body)
+        : parseFence(diagram[1]!, body, [], diagram[3], diagram[2]),
+    );
   }
   return fences;
 }

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. */