@tanishqkancharla/diffmap 0.3.0 → 0.6.0

package/src/services.ts

@@ -0,0 +1,396 @@
+import { parseAnnotation, type SourceAnnotation } from "./annotations.js";
+
+/**
+ * A `services` fence: services that hold state, nest sub-services, and send
+ * each other events. Steps replay the events in order. Every event in a step
+ * is in flight at once; the step's state updates land when they arrive.
+ */
+export type ServiceDiagram = {
+  services: Service[];
+  /** From `start "caption"`: what the declared state shows, before step 1. */
+  start: { caption: string; description: string | undefined } | undefined;
+  steps: ServiceStep[];
+  /** From ```services diff: items carry `+` or `-` signs. */
+  diff: boolean;
+};
+
+/**
+ * In a `services diff`, `-` marks an item that exists only Today and `+` one
+ * that exists only in the Proposed version. Items inherit the sign of the
+ * service or step they sit in.
+ */
+export type Sign = "+" | "-" | " ";
+
+export type Side = "today" | "proposed";
+
+export type Service = {
+  name: string;
+  label: string | undefined;
+  description: string | undefined;
+  state: ServiceState[];
+  children: Service[];
+  annotation: SourceAnnotation | undefined;
+  sign: Sign;
+};
+
+export type ServiceState = {
+  key: string;
+  /** The Proposed initial value. */
+  value: string;
+  /** Set when a `-` and a `+` line declare the key with different values. */
+  todayValue: string | undefined;
+  description: string | undefined;
+  sign: Sign;
+};
+
+export type ServiceStep = {
+  /** What happens in this step, in a sentence. */
+  caption: string;
+  description: string | undefined;
+  events: ServiceEvent[];
+  updates: ServiceUpdate[];
+  sign: Sign;
+};
+
+export type ServiceEvent = {
+  from: string;
+  to: string;
+  label: string;
+  /** Shown beside the event's label while its step is current. */
+  note: string | undefined;
+  annotation: SourceAnnotation | undefined;
+  sign: Sign;
+};
+
+export type ServiceUpdate = {
+  service: string;
+  key: string;
+  value: string;
+  /** Shown beside the changed state while its step is current. */
+  note: string | undefined;
+  sign: Sign;
+};
+
+export type ServicesParse =
+  | { ok: true; diagram: ServiceDiagram }
+  | { ok: false; line: number; reason: string };
+
+const name = String.raw`[A-Za-z_]\w*`;
+const serviceLine = new RegExp(
+  String.raw`^service\s+(${name})(?:\s+"([^"]*)")?\s*$`,
+);
+const stateLine = new RegExp(String.raw`^state\s+(${name})\s*=\s*(.+)$`);
+const stepLine = /^step\b(?:\s+"([^"]*)")?\s*$/;
+const startLine = /^start\b(?:\s+"([^"]*)")?\s*$/;
+const eventLine = new RegExp(
+  String.raw`^(${name})\s*->\s*(${name})(?:\s*:\s*(.*))?$`,
+);
+const updateLine = new RegExp(String.raw`^(${name})\.(${name})\s*=\s*(.+)$`);
+
+/**
+ * ```services
+ * service API "HTTP server" [[src/api.ts]]
+ *   state requests = 0
+ *   service Auth
+ *     state attempts = 0
+ *
+ * step "Check the password"
+ *   API -> Auth: verify(alice) [[src/api.ts#login]]
+ *   Auth.attempts = 1
+ * ```
+ */
+export function parseServiceDiagram(
+  source: string,
+  diff = false,
+): ServicesParse {
+  const services: Service[] = [];
+  const byName = new Map<string, Service>();
+  const steps: ServiceStep[] = [];
+  let start: ServiceDiagram["start"];
+  // Open services, innermost last, with the indent of their `service` line.
+  const open: { indent: number; service: Service }[] = [];
+  // Where a `>` line's text goes: a description on a service, state, or
+  // step, or a note on an event or update.
+  let described: { indent: number; append: (text: string) => void } | undefined;
+  const describe = (indent: number, item: { description?: string }) => {
+    described = {
+      indent,
+      append: (more) => {
+        item.description =
+          item.description === undefined ? more : `${item.description} ${more}`;
+      },
+    };
+  };
+  const annotate = (indent: number, item: { note?: string }) => {
+    described = {
+      indent,
+      append: (more) => {
+        item.note = item.note === undefined ? more : `${item.note} ${more}`;
+      },
+    };
+  };
+  const lines = source.split("\n");
+  for (const [index, row] of lines.entries()) {
+    const line = index + 1;
+    const fail = (reason: string): ServicesParse => ({
+      ok: false,
+      line,
+      reason,
+    });
+    if (row.trim().length === 0 || row.trim().startsWith("%%")) continue;
+    // A diff's first column is its sign, so indentation counts from column 1.
+    if (diff && !/^[+ -]/.test(row))
+      return fail("Start every line of a services diff with +, -, or a space.");
+    // SAFETY: the test above limits a diff row's first character to a Sign.
+    const own: Sign = diff ? (row[0] as Sign) : " ";
+    const raw = diff ? row.slice(1) : row;
+    const text = raw.trim();
+    if (text.length === 0) continue;
+    const indent = raw.replace(/\t/g, "  ").search(/\S/);
+    // An item takes the sign of the service or step it sits in.
+    const signWithin = (
+      container: { sign: Sign } | undefined,
+      kind: string,
+    ) => {
+      const outer = container?.sign ?? " ";
+      if (outer === " " || own === " " || own === outer)
+        return outer === " " ? own : outer;
+      return fail(
+        `A ${own} line can't sit inside a ${outer === "-" ? "removed" : "added"} ${kind}.`,
+      );
+    };
+    if (text.startsWith(">")) {
+      if (described === undefined || indent <= described.indent)
+        return fail(
+          "Put a > line directly below the service, state, step, event, or update it describes, indented further.",
+        );
+      described.append(text.slice(1).trim());
+      continue;
+    }
+    const { text: body, references } = parseAnnotation(text);
+    const annotation =
+      references.length === 0 ? undefined : { text: body.trim(), references };
+    const step = steps.at(-1);
+
+    const serviceMatch = serviceLine.exec(body.trim());
+    if (serviceMatch !== null) {
+      if (step !== undefined)
+        return fail("Declare every service before the first step.");
+      const serviceName = serviceMatch[1]!;
+      if (byName.has(serviceName))
+        return fail(`Service ${serviceName} is declared twice.`);
+      while (open.length > 0 && open.at(-1)!.indent >= indent) open.pop();
+      const sign = signWithin(open.at(-1)?.service, "service");
+      if (typeof sign !== "string") return sign;
+      const service: Service = {
+        name: serviceName,
+        label: serviceMatch[2],
+        description: undefined,
+        state: [],
+        children: [],
+        annotation:
+          annotation === undefined
+            ? undefined
+            : { ...annotation, text: serviceName },
+        sign,
+      };
+      (open.at(-1)?.service.children ?? services).push(service);
+      byName.set(serviceName, service);
+      open.push({ indent, service });
+      describe(indent, service);
+      continue;
+    }
+
+    const stateMatch = stateLine.exec(text);
+    if (stateMatch !== null) {
+      if (step !== undefined)
+        return fail(
+          "Declare state under its service, before the first step. Change it in a step with Service.key = value.",
+        );
+      while (open.length > 0 && open.at(-1)!.indent >= indent) open.pop();
+      const owner = open.at(-1)?.service;
+      if (owner === undefined)
+        return fail("Indent state under the service that owns it.");
+      const key = stateMatch[1]!;
+      const value = stateMatch[2]!.trim();
+      const sign = signWithin(owner, "service");
+      if (typeof sign !== "string") return sign;
+      const declared = owner.state.find((entry) => entry.key === key);
+      if (declared !== undefined) {
+        // A `-` and a `+` declaration of one key change its initial value.
+        if (
+          declared.todayValue !== undefined ||
+          declared.sign === " " ||
+          sign === " " ||
+          declared.sign === sign
+        )
+          return fail(`${owner.name}.${key} is declared twice.`);
+        declared.todayValue = declared.sign === "-" ? declared.value : value;
+        declared.value = declared.sign === "+" ? declared.value : value;
+        declared.sign = " ";
+        describe(indent, declared);
+        continue;
+      }
+      const entry: ServiceState = {
+        key,
+        value,
+        todayValue: undefined,
+        description: undefined,
+        sign,
+      };
+      owner.state.push(entry);
+      describe(indent, entry);
+      continue;
+    }
+
+    const startMatch = startLine.exec(text);
+    if (startMatch !== null) {
+      if (indent !== 0) return fail("Start the start line at column 0.");
+      if (step !== undefined || start !== undefined)
+        return fail("Write one start line, before the first step.");
+      if (own !== " ")
+        return fail("The start line describes both versions; drop its sign.");
+      const caption = startMatch[1]?.trim();
+      if (caption === undefined || caption === "")
+        return fail(
+          'Give the start a caption that says what the initial state shows, like start "Alice is signed out".',
+        );
+      start = { caption, description: undefined };
+      describe(indent, start);
+      continue;
+    }
+
+    const stepMatch = stepLine.exec(text);
+    if (stepMatch !== null) {
+      if (indent !== 0) return fail("Start step lines at column 0.");
+      const caption = stepMatch[1]?.trim();
+      if (caption === undefined || caption === "")
+        return fail(
+          'Give the step a caption that says what happens, like step "Auth checks the password".',
+        );
+      const next: ServiceStep = {
+        caption,
+        description: undefined,
+        events: [],
+        updates: [],
+        sign: own,
+      };
+      steps.push(next);
+      describe(indent, next);
+      continue;
+    }
+
+    if (step !== undefined && indent > 0) {
+      const event = eventLine.exec(body.trim());
+      if (event !== null) {
+        for (const service of [event[1]!, event[2]!])
+          if (!byName.has(service)) return fail(`Unknown service ${service}.`);
+        const label = (event[3] ?? "").trim();
+        const sign = signWithin(step, "step");
+        if (typeof sign !== "string") return sign;
+        const entry: ServiceEvent = {
+          from: event[1]!,
+          to: event[2]!,
+          label,
+          note: undefined,
+          annotation:
+            annotation === undefined
+              ? undefined
+              : {
+                  ...annotation,
+                  text: `${event[1]} → ${event[2]}${label === "" ? "" : `: ${label}`}`,
+                },
+          sign,
+        };
+        step.events.push(entry);
+        annotate(indent, entry);
+        continue;
+      }
+      const update = updateLine.exec(text);
+      if (update !== null) {
+        const owner = byName.get(update[1]!);
+        if (owner === undefined) return fail(`Unknown service ${update[1]}.`);
+        if (!owner.state.some((entry) => entry.key === update[2]))
+          return fail(
+            `${owner.name} has no state ${update[2]}. Declare it with state ${update[2]} = <initial value>.`,
+          );
+        const sign = signWithin(step, "step");
+        if (typeof sign !== "string") return sign;
+        const entry: ServiceUpdate = {
+          service: owner.name,
+          key: update[2]!,
+          value: update[3]!.trim(),
+          note: undefined,
+          sign,
+        };
+        step.updates.push(entry);
+        annotate(indent, entry);
+        continue;
+      }
+      return fail(
+        `Expected an event (From -> To: label) or a state update (Service.key = value), got "${text}".`,
+      );
+    }
+
+    return fail(
+      `Expected service <Name>, state <key> = <value>, start "<caption>", or step "<caption>", got "${text}".`,
+    );
+  }
+  if (services.length === 0)
+    return { ok: false, line: 1, reason: "Declare at least one service." };
+  return { ok: true, diagram: { services, start, steps, diff } };
+}
+
+/** Every service in declaration order, with its parent. */
+export function flattenServices(
+  services: Service[],
+  parent?: Service,
+): { service: Service; parent: Service | undefined }[] {
+  return services.flatMap((service) => [
+    { service, parent },
+    ...flattenServices(service.children, service),
+  ]);
+}
+
+/**
+ * State after the first `step` steps; step 0 is the declared state. In a
+ * diff, Today skips `+` items and Proposed skips `-` items.
+ */
+export function serviceStateAt(
+  diagram: ServiceDiagram,
+  step: number,
+  side: Side = "proposed",
+) {
+  const skip: Sign = side === "today" ? "+" : "-";
+  const state = new Map(
+    flattenServices(diagram.services).map(({ service }) => [
+      service.name,
+      new Map(
+        service.state
+          .filter((entry) => entry.sign !== skip)
+          .map((entry) => [
+            entry.key,
+            side === "today" ? (entry.todayValue ?? entry.value) : entry.value,
+          ]),
+      ),
+    ]),
+  );
+  for (const { updates } of diagram.steps.slice(0, step))
+    for (const update of updates)
+      if (update.sign !== skip)
+        state.get(update.service)!.set(update.key, update.value);
+  return state;
+}
+
+export function serviceAnnotations(diagram: ServiceDiagram) {
+  return [
+    ...flattenServices(diagram.services).flatMap(({ service }) =>
+      service.annotation === undefined ? [] : [service.annotation],
+    ),
+    ...diagram.steps.flatMap((step) =>
+      step.events.flatMap((event) =>
+        event.annotation === undefined ? [] : [event.annotation],
+      ),
+    ),
+  ];
+}

package/src/share.ts

@@ -45,7 +45,7 @@ export async function shareMarkdownFile(input: {
   const changes = await readDocumentChanges(input.workspaceRoot, parsed);
   if (changes instanceof Error) return changes;
   // An uncommitted changes card shows the tree as it is when you share.
-  for (const rev of parsed.changeRevs) {
+  for (const { rev } of parsed.changeCards) {
     if (changes.has(rev)) continue;
     const loaded = await readChanges(input.workspaceRoot, rev);
     if (loaded instanceof Error) return loaded;

package/src/viewer/CallStackDiff.tsx

@@ -1,33 +1,60 @@
-import {
-  backgroundColor,
-  colors,
-  focusRing,
-  LARGE_SCALE,
-  spacing,
-  text,
-} from "maui";
+import { colors, focusRing, LARGE_SCALE, text, Tooltip } from "maui";
 import { defineVars, style, useStyles } from "purse-styles";
 import { codeFontFamily } from "../codeFont.js";
-import type { SourceAnnotation, SourceNavigation } from "../annotations.js";
-import { pierreShell } from "./pierre.js";
+import {
+  callStackRow,
+  type SourceAnnotation,
+  type SourceNavigation,
+} from "../annotations.js";
+import { lineSymbolMatches, type CodeNote } from "../codeNotes.js";
+import { NoteText, NoteTokens } from "./notes.tsx";
+import { fenceTitle, pierreShell } from "./pierre.js";
 
 export function CallStackDiff(
-  props: { lines: SourceAnnotation[] } & SourceNavigation,
+  props: {
+    lines: SourceAnnotation[];
+    highlights: number[];
+    notes: CodeNote[];
+    title: string | undefined;
+  } & SourceNavigation,
 ) {
   const shell = useStyles(pierreShell, styles.shell);
-  const row = useStyles(styles.row);
+  const titleClassName = useStyles(fenceTitle);
+  const rowClassName = useStyles(styles.row);
   return (
-    <div className={shell} data-diffmap-kind="callstack">
+    <figure className={shell} data-diffmap-kind="callstack">
+      {props.title !== undefined && (
+        <figcaption className={titleClassName}>{props.title}</figcaption>
+      )}
       {props.lines.map((line, index) => {
-        const sign = line.text.startsWith("+")
-          ? "+"
-          : line.text.startsWith("-")
-            ? "-"
-            : " ";
-        const label = line.text.replace(/^[+ -]/, "");
-        const tree = /^[ \t│┃├└─]*/u.exec(label)![0];
-        const description = label.slice(tree.length);
+        const { sign, tree, description } = callStackRow(line.text);
         const comment = description.indexOf("#");
+        const linked = line.references.length > 0;
+        const row = index + 1;
+        const lineNote = props.notes.find(
+          (note) =>
+            note.target.kind === "lines" &&
+            note.target.start <= row &&
+            row <= note.target.end,
+        );
+        const matches = lineSymbolMatches(description, props.notes);
+        const rowProps = {
+          className: rowClassName,
+          "data-change": sign,
+          "data-highlighted": props.highlights.includes(row) || undefined,
+          "data-note":
+            lineNote === undefined
+              ? undefined
+              : lineNote.target.kind === "lines" &&
+                  lineNote.target.start === row
+                ? "start"
+                : "",
+          // A native title would show beside the note tooltip.
+          title:
+            lineNote === undefined && matches.length === 0
+              ? description
+              : undefined,
+        };
         const content = (
           <>
             <span className="diff-sign" aria-hidden="true">
@@ -40,12 +67,21 @@ export function CallStackDiff(
                 ))}
               </span>
               <span className="stack-label">
-                {comment === -1 ? description : description.slice(0, comment)}
-                {comment !== -1 && (
-                  <span className="stack-comment">
-                    {description.slice(comment)}
-                  </span>
-                )}
+                <NoteTokens
+                  tokens={
+                    comment === -1
+                      ? [{ content: description }]
+                      : [
+                          { content: description.slice(0, comment) },
+                          {
+                            content: description.slice(comment),
+                            className: "stack-comment",
+                          },
+                        ]
+                  }
+                  matches={matches}
+                  focusable={!linked}
+                />
               </span>
             </span>
             {line.references.length > 0 && (
@@ -55,55 +91,59 @@ export function CallStackDiff(
             )}
           </>
         );
-        if (line.references.length === 0) {
-          return (
-            <div
-              key={index}
-              className={row}
-              data-change={sign}
-              title={description}
-            >
-              {content}
-            </div>
-          );
-        }
-        return (
+        const element = linked ? (
           <button
             key={index}
             type="button"
-            className={row}
-            data-change={sign}
+            {...rowProps}
             aria-pressed={props.selectedAnnotation === line}
             aria-controls="source-diff-panel"
-            title={description}
             aria-label={description}
             onClick={() => props.onSelectAnnotation(line)}
           >
             {content}
           </button>
+        ) : (
+          <div
+            key={index}
+            {...rowProps}
+            tabIndex={lineNote === undefined ? undefined : 0}
+          >
+            {content}
+          </div>
+        );
+        if (lineNote === undefined) return element;
+        return (
+          <Tooltip key={index} content={<NoteText text={lineNote.text} />}>
+            {element}
+          </Tooltip>
         );
       })}
-    </div>
+    </figure>
   );
 }
 
 const rowSize = defineVars({
-  height: { default: "28px", [LARGE_SCALE]: "40px" },
+  height: { default: "22px", [LARGE_SCALE]: "32px" },
 });
 
 const styles = {
-  shell: style(
-    text({ size: "sm", fontWeight: 500, color: "highContrast" }),
-    spacing.padding({ y: 2 }),
-    {
-      backgroundColor: backgroundColor.app,
-      overflowX: "hidden",
-      maxWidth: "100%",
+  // Sized like Maui's code block, so stacks and code read as one family.
+  shell: style(text({ size: "xs", fontWeight: 400, color: "highContrast" }), {
+    fontFamily: codeFontFamily,
+    margin: 0,
+    paddingBlock: "8px",
+    overflowX: "hidden",
+    maxWidth: "100%",
+    // The shell's top padding goes below the title, between it and the rows.
+    "& > figcaption": {
+      marginTop: "-8px",
+      marginBottom: "8px",
     },
-  ),
+  }),
   row: style(
-    spacing.padding({ x: 3 }),
     {
+      paddingInline: "12px",
       display: "flex",
       alignItems: "center",
       gap: "12px",
@@ -120,6 +160,30 @@ const styles = {
       border: 0,
       "&[data-change='+']": { backgroundColor: colors.green[3] },
       "&[data-change='-']": { backgroundColor: colors.red[3] },
+      "&[data-highlighted]": {
+        backgroundColor: colors.blue[3],
+        boxShadow: `inset 3px 0 ${colors.blue[9]}`,
+      },
+      "&[data-change='+'][data-highlighted]": {
+        backgroundColor: colors.green[5],
+        boxShadow: `inset 3px 0 ${colors.green[9]}`,
+      },
+      "&[data-change='-'][data-highlighted]": {
+        backgroundColor: colors.red[5],
+        boxShadow: `inset 3px 0 ${colors.red[9]}`,
+      },
+      "&[data-note]": { cursor: "help" },
+      // The sign fills the row gutter, so the dot follows the label instead.
+      "&[data-note='start'] .stack-label::after": {
+        content: '""',
+        display: "inline-block",
+        width: "5px",
+        height: "5px",
+        marginLeft: "8px",
+        verticalAlign: "middle",
+        borderRadius: "50%",
+        backgroundColor: colors.blue[9],
+      },
       "&[aria-pressed]": { cursor: "pointer" },
       "&[aria-pressed]:hover": { backgroundColor: colors.blue[2] },
       "&[aria-pressed='true'], &[aria-pressed='true']:hover": {
@@ -138,7 +202,7 @@ const styles = {
         alignSelf: "center",
         flex: "1 1 auto",
         minWidth: 0,
-        paddingBlock: "3px",
+        paddingBlock: "1px",
         overflow: "hidden",
         textOverflow: "ellipsis",
         whiteSpace: "nowrap",