pim-agent 0.0.1 → 0.10.0

package/packages/core/src/view/DiffExpand.ts

@@ -0,0 +1,214 @@
+import type { ToolDiffHunk, ToolDiffLine } from "../shared/DiffLines";
+import type { LineSpan } from "../shared/RepoDiff";
+
+/**
+ * A stretch of a file neither side changed and no hunk shows, numbered on the
+ * new side. `above` and `below` say which ends of it sit against a hunk, which
+ * is where a reader asking for more of it is given it.
+ */
+export type DiffGap = {
+  readonly start: number;
+  readonly end: number;
+  readonly count: number;
+  readonly above: boolean;
+  readonly below: boolean;
+};
+
+/** What a diff is painted from, top to bottom: hunks and the gaps between them. */
+export type DiffPart =
+  | { readonly hunk: ToolDiffHunk }
+  | { readonly gap: DiffGap };
+
+/** Lines one click reveals at each end of a gap. */
+const STEP = 25;
+
+/** A remainder this small is taken with the click rather than left as a row of its own. */
+const MIN_REMAINDER = 10;
+
+function newEnd(hunk: ToolDiffHunk): number {
+  return hunk.newStart + hunk.newLines - 1;
+}
+
+function oldEnd(hunk: ToolDiffHunk): number {
+  return hunk.oldStart + hunk.oldLines - 1;
+}
+
+function gapOf(
+  start: number,
+  end: number,
+  above: boolean,
+  below: boolean
+): readonly DiffGap[] {
+  return end < start
+    ? []
+    : [{ start, end, count: end - start + 1, above, below }];
+}
+
+/**
+ * Every gap in one file's hunks: before the first, between each pair, and
+ * after the last once `total` says where the file ends. A file with no new
+ * side to number has none of them.
+ */
+function gaps(
+  hunks: readonly ToolDiffHunk[],
+  total?: number
+): readonly DiffGap[] {
+  const first = hunks[0];
+  const last = hunks.at(-1);
+  if (first === undefined || last === undefined) {
+    return [];
+  }
+
+  return [
+    ...gapOf(1, first.newStart - 1, false, true),
+    ...hunks.flatMap((hunk, index) => {
+      const next = hunks[index + 1];
+      return next === undefined
+        ? []
+        : gapOf(newEnd(hunk) + 1, next.newStart - 1, true, true);
+    }),
+    ...(total === undefined ? [] : gapOf(newEnd(last) + 1, total, true, false)),
+  ];
+}
+
+/**
+ * What to ask the server for when a reader opens a gap: a step against each
+ * hunk it touches, or the whole gap when what would be left of it is a sliver.
+ */
+function spans(gap: DiffGap): readonly LineSpan[] {
+  const edges = (gap.above ? 1 : 0) + (gap.below ? 1 : 0);
+  if (gap.count <= edges * STEP + MIN_REMAINDER) {
+    return [{ start: gap.start, end: gap.end }];
+  }
+  return [
+    ...(gap.above ? [{ start: gap.start, end: gap.start + STEP - 1 }] : []),
+    ...(gap.below ? [{ start: gap.end - STEP + 1, end: gap.end }] : []),
+  ];
+}
+
+/** How many lines opening a gap would put on the page. */
+function revealed(gap: DiffGap): number {
+  return spans(gap).reduce(
+    (total, span) => total + span.end - span.start + 1,
+    0
+  );
+}
+
+/** The hunks with each gap in its place among them. */
+function parts(
+  hunks: readonly ToolDiffHunk[],
+  total?: number
+): readonly DiffPart[] {
+  const found = gaps(hunks, total);
+  const tail = found.find((gap) => !gap.below);
+  // Keyed by the line a gap ends on, which is the line before the hunk it
+  // leads into: one lookup per hunk rather than a scan of every gap.
+  const leading = new Map(found.map((gap) => [gap.end, gap]));
+  return [
+    ...hunks.flatMap((hunk) => {
+      const gap = leading.get(hunk.newStart - 1);
+      return gap === undefined ? [{ hunk }] : [{ gap }, { hunk }];
+    }),
+    ...(tail === undefined ? [] : [{ gap: tail }]),
+  ];
+}
+
+type Run = {
+  readonly oldStart: number;
+  readonly newStart: number;
+  readonly lines: ToolDiffLine[];
+  /** Lines of the run that stand on the new side, counted as they are added. */
+  newCount: number;
+};
+
+function context(line: number, offset: number, text: string): ToolDiffLine {
+  return { kind: "context", oldLine: line + offset, newLine: line, text };
+}
+
+function newLinesOf(lines: readonly ToolDiffLine[]): number {
+  return lines.filter((line) => line.kind !== "removed").length;
+}
+
+function hunkOf(run: Run): ToolDiffHunk {
+  return {
+    oldStart: run.oldStart,
+    newStart: run.newStart,
+    oldLines: run.lines.filter((line) => line.kind !== "added").length,
+    newLines: run.newCount,
+    lines: run.lines,
+  };
+}
+
+/**
+ * The hunks with every line a reader has since been given spliced back into
+ * the gaps around them, and hunks that now touch merged into one. Only lines
+ * running from a hunk's own edge are taken: an island in the middle of a gap
+ * is not a thing this ever asks for.
+ */
+function expand(
+  hunks: readonly ToolDiffHunk[],
+  known: ReadonlyMap<number, string>
+): readonly ToolDiffHunk[] {
+  if (known.size === 0) {
+    return hunks;
+  }
+
+  const runs: Run[] = [];
+
+  const reached = (): number => {
+    const last = runs.at(-1);
+    return last === undefined ? 0 : last.newStart + last.newCount - 1;
+  };
+
+  const add = (run: Run): void => {
+    const last = runs.at(-1);
+    if (last !== undefined && reached() + 1 === run.newStart) {
+      last.lines.push(...run.lines);
+      last.newCount += run.newCount;
+      return;
+    }
+    runs.push(run);
+  };
+
+  for (const [index, hunk] of hunks.entries()) {
+    const before: ToolDiffLine[] = [];
+    const floor = reached();
+    for (let line = hunk.newStart - 1; line > floor; line -= 1) {
+      const text = known.get(line);
+      if (text === undefined) {
+        break;
+      }
+      before.push(context(line, hunk.oldStart - hunk.newStart, text));
+    }
+    before.reverse();
+    const lines = [...before, ...hunk.lines];
+    add({
+      oldStart: hunk.oldStart - before.length,
+      newStart: hunk.newStart - before.length,
+      lines,
+      newCount: before.length + newLinesOf(hunk.lines),
+    });
+
+    const after: ToolDiffLine[] = [];
+    const ceiling = hunks[index + 1]?.newStart ?? Infinity;
+    for (let line = newEnd(hunk) + 1; line < ceiling; line += 1) {
+      const text = known.get(line);
+      if (text === undefined) {
+        break;
+      }
+      after.push(context(line, oldEnd(hunk) - newEnd(hunk), text));
+    }
+    if (after.length > 0) {
+      add({
+        oldStart: oldEnd(hunk) + 1,
+        newStart: newEnd(hunk) + 1,
+        lines: after,
+        newCount: after.length,
+      });
+    }
+  }
+
+  return runs.map(hunkOf);
+}
+
+export const DiffExpand = { gaps, parts, spans, revealed, expand };

package/packages/core/src/view/DiffLayout.ts

@@ -0,0 +1,69 @@
+import type { ToolDiffHunk, ToolDiffLine } from "../shared/DiffLines";
+
+const TAB = "   ";
+
+function detab(text: string): string {
+  return text.replace(/\t/g, TAB);
+}
+
+// Highlight each side as one block, never line by line, or multi-line strings and comments mis-tokenise.
+function mapSides<T>(
+  lines: readonly ToolDiffLine[],
+  highlight: (block: string) => readonly T[]
+): readonly (T | undefined)[] {
+  const oldIndices: (number | undefined)[] = [];
+  const newIndices: (number | undefined)[] = [];
+  const oldBlock: string[] = [];
+  const newBlock: string[] = [];
+
+  for (const line of lines) {
+    // A context line must hold a slot in both blocks to keep tokeniser state aligned.
+    if (line.kind !== "added") {
+      oldIndices.push(oldBlock.length);
+      oldBlock.push(line.text);
+    } else {
+      oldIndices.push(undefined);
+    }
+
+    if (line.kind !== "removed") {
+      newIndices.push(newBlock.length);
+      newBlock.push(line.text);
+    } else {
+      newIndices.push(undefined);
+    }
+  }
+
+  const oldText = oldBlock.length === 0 ? [] : highlight(oldBlock.join("\n"));
+  const newText = newBlock.length === 0 ? [] : highlight(newBlock.join("\n"));
+
+  return lines.map((line, index) => {
+    const side = line.kind === "removed" ? oldText : newText;
+    const at = line.kind === "removed" ? oldIndices[index] : newIndices[index];
+    return at === undefined ? undefined : side[at];
+  });
+}
+
+function gutterWidth(hunks: readonly ToolDiffHunk[]): number {
+  let max = 0;
+
+  for (const hunk of hunks) {
+    max = Math.max(max, hunk.oldStart + hunk.oldLines - 1);
+    max = Math.max(max, hunk.newStart + hunk.newLines - 1);
+  }
+
+  return Math.max(1, String(max).length);
+}
+
+function lineNumber(line: ToolDiffHunk["lines"][number]): number | undefined {
+  if (line.kind === "added") {
+    return line.newLine;
+  }
+
+  if (line.kind === "removed") {
+    return line.oldLine;
+  }
+
+  return line.newLine ?? line.oldLine;
+}
+
+export const DiffLayout = { detab, mapSides, gutterWidth, lineNumber };

package/packages/core/src/view/DiffPairs.ts

@@ -0,0 +1,47 @@
+import type { ToolDiffHunk, ToolDiffLine } from "../shared/DiffLines";
+
+/** One row of a split view: the old side, the new side, or both. */
+export type DiffPair = {
+  readonly left?: ToolDiffLine;
+  readonly right?: ToolDiffLine;
+};
+
+function pair(hunk: ToolDiffHunk): readonly DiffPair[] {
+  const pairs: DiffPair[] = [];
+  let removed: ToolDiffLine[] = [];
+  let added: ToolDiffLine[] = [];
+
+  const zip = (): void => {
+    const rows = Math.max(removed.length, added.length);
+    for (let index = 0; index < rows; index += 1) {
+      pairs.push({ left: removed[index], right: added[index] });
+    }
+    removed = [];
+    added = [];
+  };
+
+  for (const line of hunk.lines) {
+    if (line.kind === "context") {
+      zip();
+      pairs.push({ left: line, right: line });
+      continue;
+    }
+
+    if (line.kind === "added") {
+      added.push(line);
+      continue;
+    }
+
+    // A removal after an addition starts a new replacement rather than joining the last.
+    if (added.length > 0) {
+      zip();
+    }
+    removed.push(line);
+  }
+
+  zip();
+
+  return pairs;
+}
+
+export const DiffPairs = { pair };

package/packages/core/src/view/MarkdownPainter.ts

@@ -0,0 +1,314 @@
+import { basename } from "node:path";
+import { Painting, type PainterMap } from "./Painting";
+import type {
+  BlockOf,
+  DiffHunk,
+  NoticeSeverity,
+  Span,
+  Tone,
+  ToolIcon,
+  ToolView,
+  ViewBlock,
+} from "./ViewBlock";
+
+type Mode = "inline" | "block";
+
+/** How a block sits in a body; `embed` payloads must never be re-wrapped. */
+export type MarkdownFrame = "flow" | "embed" | "heading";
+
+export type MarkdownGroup = {
+  readonly frame: MarkdownFrame;
+  readonly lines: readonly string[];
+};
+
+export type PaintedTool = {
+  readonly icon: string;
+  readonly lines: readonly string[];
+};
+
+const INLINE_LIMIT = 180;
+
+const ENTITIES: Readonly<Record<string, string>> = {
+  "&": "&amp;",
+  "<": "&lt;",
+  ">": "&gt;",
+  '"': "&quot;",
+};
+
+function escape(text: string): string {
+  return text.replace(/[&<>"]/g, (char) => ENTITIES[char] ?? char);
+}
+
+function paint(blocks: readonly ViewBlock[]): string[] {
+  return blocks.flatMap((block) => paintBlock(block, "block"));
+}
+
+function paintInline(blocks: readonly ViewBlock[]): string {
+  return blocks
+    .flatMap((block) => paintBlock(block, "inline"))
+    .filter((line) => line !== "")
+    .join(" ");
+}
+
+function paintBody(blocks: readonly ViewBlock[]): MarkdownGroup[] {
+  return Painting.groupByFrame(blocks, Painting.FRAMES).map((group) => ({
+    frame: group.frame,
+    lines: group.blocks.flatMap((block) => paintBlock(block, "block")),
+  }));
+}
+
+function icon(toolIcon: ToolIcon | undefined): string {
+  return toolIcon === undefined ? DEFAULT_ICON : ICONS[toolIcon];
+}
+
+function paintTool(view: ToolView): PaintedTool {
+  const head = [view.title, view.summary ?? []]
+    .map((blocks) => paintInline(blocks))
+    .filter((text) => text !== "")
+    .join(" ");
+  const outline = outlined(view.body ?? []).flatMap((block) =>
+    paintBlock(block, "block")
+  );
+
+  return {
+    icon: icon(view.icon),
+    lines: [head, ...outline].filter((line) => line !== ""),
+  };
+}
+
+/** A chat row carries a body's headings and any payload that fits a line; an embedded one needs a screen. */
+function outlined(blocks: readonly ViewBlock[]): readonly ViewBlock[] {
+  return blocks.filter((block) => {
+    const frame = Painting.FRAMES[block.kind];
+    return (
+      frame === "heading" ||
+      (frame === "flow" && Painting.WEIGHT[block.kind] === "payload")
+    );
+  });
+}
+
+const ICONS = {
+  file: "📄",
+  edit: "✏️",
+  trash: "🗑️",
+  terminal: "⚡️",
+  search: "🔎",
+  checklist: "📋",
+  globe: "🌐",
+  upload: "📤",
+  clock: "⏰",
+  robot: "🤖",
+} as const satisfies Record<ToolIcon, string>;
+
+const DEFAULT_ICON = "⚙️";
+
+const TONE_WRAPPERS = {
+  default: identity,
+  muted: identity,
+  dim: identity,
+  error: bold,
+  warning: identity,
+  accent: identity,
+  added: identity,
+  removed: identity,
+  title: identity,
+} as const satisfies Record<Tone, (text: string) => string>;
+
+const NOTICE_PREFIXES = {
+  info: "",
+  warn: "⚠️ ",
+  error: "❌ ",
+} as const satisfies Record<NoticeSeverity, string>;
+
+function identity(text: string): string {
+  return text;
+}
+
+function bold(text: string): string {
+  return `<b>${text}</b>`;
+}
+
+function paintBlock(block: ViewBlock, mode: Mode): readonly string[] {
+  return Painting.dispatch(PAINTERS, block, mode);
+}
+
+function oneLine(text: string): string {
+  const index = text.indexOf("\n");
+  const first = index < 0 ? text : `${text.slice(0, index).trimEnd()} …`;
+  return first.length <= INLINE_LIMIT
+    ? first
+    : `${first.slice(0, INLINE_LIMIT - 1)}…`;
+}
+
+function escapeIn(text: string, mode: Mode): string {
+  return escape(mode === "inline" ? oneLine(text) : text);
+}
+
+function lines(text: string, mode: Mode): readonly string[] {
+  return mode === "inline"
+    ? [escapeIn(text, mode)]
+    : text.split("\n").map((line) => escape(line));
+}
+
+function paintText(block: BlockOf<"text">, mode: Mode): readonly string[] {
+  const wrap = TONE_WRAPPERS[block.tone ?? "default"];
+  return lines(block.text, mode).map(wrap);
+}
+
+function paintSpans(block: BlockOf<"spans">, mode: Mode): readonly string[] {
+  return [spansText(block.spans, mode)];
+}
+
+function spansText(spans: readonly Span[], mode: Mode): string {
+  return spans
+    .filter((span) => span.text !== "")
+    .map((span) => {
+      let text = escapeIn(span.text, mode);
+      if (span.code === true) {
+        text = `<code>${text}</code>`;
+      }
+      if (span.strike === true) {
+        text = `<s>${text}</s>`;
+      }
+      if (span.strong === true) {
+        text = bold(text);
+      }
+      return TONE_WRAPPERS[span.tone ?? "default"](text);
+    })
+    .join("");
+}
+
+function paintSection(block: BlockOf<"section">): readonly string[] {
+  const lead =
+    block.icon === undefined ? bold(escape(block.label)) : icon(block.icon);
+  const content = paintInline(block.content);
+  return [content === "" ? lead : `${lead} ${content}`];
+}
+
+function paintCode(block: BlockOf<"code">, mode: Mode): readonly string[] {
+  if (mode === "inline") {
+    return [`<code>${escapeIn(block.text, mode)}</code>`];
+  }
+  const start = block.startLine;
+  const body = numbered(block.text.split("\n"), start)
+    .map((line) => escape(line))
+    .join("\n");
+  return [preformatted(body, block.lang)];
+}
+
+function numbered(
+  source: readonly string[],
+  start: number | undefined
+): readonly string[] {
+  if (start === undefined) {
+    return source;
+  }
+  const width = Painting.lineNumberWidth(start, source.length);
+  return source.map(
+    (line, index) => `${String(start + index).padStart(width)} ${line}`
+  );
+}
+
+function preformatted(body: string, lang?: string): string {
+  return lang === undefined || lang === ""
+    ? `<pre>${body}</pre>`
+    : `<pre><code class="language-${escape(lang)}">${body}</code></pre>`;
+}
+
+function paintDiff(block: BlockOf<"diff">, mode: Mode): readonly string[] {
+  const body = block.hunks.flatMap((hunk) => diffLines(hunk));
+  if (body.length === 0) {
+    return [];
+  }
+  if (mode === "inline") {
+    return [`<code>${escapeIn(body[0] ?? "", mode)}</code>`];
+  }
+  return [preformatted(body.map((line) => escape(line)).join("\n"), "diff")];
+}
+
+function diffLines(hunk: DiffHunk): readonly string[] {
+  const header = `@@ -${hunk.oldStart},${hunk.oldLines} +${hunk.newStart},${hunk.newLines} @@`;
+  return [
+    header,
+    ...hunk.lines.map((line) => `${DIFF_MARKERS[line.kind]}${line.text}`),
+  ];
+}
+
+const DIFF_MARKERS = {
+  context: " ",
+  added: "+",
+  removed: "-",
+} as const;
+
+function paintFile(block: BlockOf<"file">, mode: Mode): readonly string[] {
+  const path = mode === "inline" ? basename(block.path) : block.path;
+  const { range, truncated } = Painting.fileSuffix(block);
+  return [`<code>${escape(oneLine(path) + range)}</code>${truncated}`];
+}
+
+function paintList(block: BlockOf<"list">, mode: Mode): readonly string[] {
+  return Painting.hangingList(block.items, block.ordered === true, (item) =>
+    paintBlock(item, mode)
+  );
+}
+
+function paintKv(block: BlockOf<"kv">, mode: Mode): readonly string[] {
+  return block.pairs.map(
+    ([key, value]) =>
+      `${bold(`${escapeIn(key, mode)}:`)} ${escapeIn(value, mode)}`
+  );
+}
+
+function paintLink(block: BlockOf<"link">, mode: Mode): readonly string[] {
+  const label = Painting.linkLabel(block);
+  return [`<a href="${escape(block.href)}">${escapeIn(label, mode)}</a>`];
+}
+
+function paintAttachment(
+  block: BlockOf<"attachment">,
+  mode: Mode
+): readonly string[] {
+  return [escapeIn(block.name, mode)];
+}
+
+function paintImage(block: BlockOf<"image">, mode: Mode): readonly string[] {
+  return [escapeIn(Painting.imageSummary(block), mode)];
+}
+
+function paintMarkdown(
+  block: BlockOf<"markdown">,
+  mode: Mode
+): readonly string[] {
+  return lines(block.text, mode);
+}
+
+function paintNotice(block: BlockOf<"notice">, mode: Mode): readonly string[] {
+  const prefix = NOTICE_PREFIXES[block.severity];
+  return lines(block.text, mode).map((line) => `${prefix}${line}`);
+}
+
+const PAINTERS: PainterMap<readonly string[], [Mode]> = {
+  text: paintText,
+  markdown: paintMarkdown,
+  spans: paintSpans,
+  section: paintSection,
+  code: paintCode,
+  diff: paintDiff,
+  file: paintFile,
+  list: paintList,
+  kv: paintKv,
+  link: paintLink,
+  attachment: paintAttachment,
+  image: paintImage,
+  notice: paintNotice,
+};
+
+/** Paints a `ViewBlock` tree to Telegram-flavoured HTML; the caller joins lines. */
+export const MarkdownPainter = {
+  escape,
+  paint,
+  paintInline,
+  paintBody,
+  icon,
+  paintTool,
+};

package/packages/core/src/view/MovePath.ts

@@ -0,0 +1,70 @@
+/**
+ * A file that moved, read as one path rather than two. Everything the old and
+ * new paths agree on is said once, and only the segments that actually changed
+ * are named on both sides — `packages/{web ➝ tui}/src/App.tsx` rather than two
+ * near-identical paths a reader has to diff by eye.
+ */
+export type MoveParts = {
+  /** The leading directories both paths share, with its trailing `/`. */
+  readonly prefix: string;
+  /** What those segments used to be. */
+  readonly from: string;
+  /** What they are now. */
+  readonly to: string;
+  /** The trailing segments both paths share, with its leading `/`. */
+  readonly suffix: string;
+};
+
+/** The arrow every surface draws a move with. */
+const ARROW = "➝";
+
+/**
+ * The shared head and tail of a move, or `undefined` when there is nothing
+ * worth folding: two paths that share no segment read better whole, since a
+ * brace around the entire path only adds punctuation. Two bare filenames are
+ * the exception — `{old.ts ➝ new.ts}` shares no segment but is still one name.
+ */
+function fold(oldPath: string, newPath: string): MoveParts | undefined {
+  const oldParts = oldPath.split("/");
+  const newParts = newPath.split("/");
+
+  let head = 0;
+  while (
+    head < oldParts.length &&
+    head < newParts.length &&
+    oldParts[head] === newParts[head]
+  ) {
+    head += 1;
+  }
+
+  let tail = 0;
+  while (
+    tail < oldParts.length - head &&
+    tail < newParts.length - head &&
+    oldParts[oldParts.length - tail - 1] ===
+      newParts[newParts.length - tail - 1]
+  ) {
+    tail += 1;
+  }
+
+  const from = oldParts.slice(head, oldParts.length - tail);
+  const to = newParts.slice(head, newParts.length - tail);
+  const bareNames = oldParts.length === 1 && newParts.length === 1;
+
+  if (
+    from.length === 0 ||
+    to.length === 0 ||
+    (head === 0 && tail === 0 && !bareNames)
+  ) {
+    return undefined;
+  }
+
+  return {
+    prefix: head > 0 ? `${oldParts.slice(0, head).join("/")}/` : "",
+    from: from.join("/"),
+    to: to.join("/"),
+    suffix: tail > 0 ? `/${oldParts.slice(-tail).join("/")}` : "",
+  };
+}
+
+export const MovePath = { ARROW, fold };