@yannelli/paseo-linear-plugin 1.0.1 → 1.1.0-beta.1

package/shared/links.ts

@@ -0,0 +1,252 @@
+// Links between repository files, for the Linear Live graph: code imports in common languages,
+// links in Markdown, HTML, and CSS, entry points in package files, and repo paths named in
+// config and scripts. Pure: the daemon reads the files and checks which candidates exist.
+
+export type LinkKind = "import" | "link" | "mention";
+
+export interface FileLink {
+  from: string;
+  to: string;
+  kind: LinkKind;
+}
+
+/** A reference found in a file, with the repo paths it may point to, best first. */
+export interface Reference {
+  kind: LinkKind;
+  candidates: string[];
+}
+
+export interface LinkContext {
+  /** Path aliases from tsconfig or jsconfig, such as "@/" to "src/". */
+  aliases: readonly { prefix: string; targets: readonly string[] }[];
+  /** Workspace packages by name, with their folder and entry file. */
+  packages: ReadonlyMap<string, { dir: string; entry: string | null }>;
+  /** The module path from go.mod. */
+  goModule: string | null;
+}
+
+export const EMPTY_CONTEXT: LinkContext = { aliases: [], packages: new Map(), goModule: null };
+
+const SCRIPT_EXTENSIONS = [".ts", ".tsx", ".d.ts", ".js", ".jsx", ".mjs", ".cjs", ".mts", ".cts", ".json", ".vue", ".svelte"];
+/** A Go import names a package folder; this suffix asks the daemon for the folder's Go files. */
+export const GO_PACKAGE = "/*.go";
+
+function extension(file: string): string {
+  const name = file.split("/").pop() ?? file;
+  const dot = name.lastIndexOf(".");
+  return dot > 0 ? name.slice(dot).toLowerCase() : "";
+}
+
+function dirname(file: string): string {
+  const index = file.lastIndexOf("/");
+  return index < 0 ? "" : file.slice(0, index);
+}
+
+/** Joins and normalizes a repo path; null when it leaves the repository. */
+export function joinPath(base: string, target: string): string | null {
+  const parts: string[] = [];
+  for (const part of `${base}/${target}`.split("/")) {
+    if (part === "" || part === ".") continue;
+    if (part === "..") {
+      if (parts.length === 0) return null;
+      parts.pop();
+    } else parts.push(part);
+  }
+  return parts.length ? parts.join("/") : null;
+}
+
+function all(pattern: RegExp, text: string, group = 1): string[] {
+  return [...text.matchAll(pattern)].map((match) => match[group] ?? "").filter(Boolean);
+}
+
+// A script specifier may leave out the extension, name a folder with an index file, or name
+// the .js file that a .ts file compiles to.
+function scriptCandidates(base: string): string[] {
+  const list = [base, ...SCRIPT_EXTENSIONS.map((ext) => base + ext), ...SCRIPT_EXTENSIONS.map((ext) => `${base}/index${ext}`)];
+  const compiled = /\.(m|c)?jsx?$/.exec(base);
+  if (compiled) {
+    const stem = base.slice(0, -compiled[0].length);
+    list.unshift(`${stem}.ts`, `${stem}.tsx`, `${stem}.${compiled[1] ?? ""}ts`);
+  }
+  return list;
+}
+
+function scriptSpecifier(from: string, spec: string, context: LinkContext): string[] {
+  if (spec.startsWith(".")) {
+    const base = joinPath(dirname(from), spec);
+    return base ? scriptCandidates(base) : [];
+  }
+  for (const alias of context.aliases) {
+    if (!spec.startsWith(alias.prefix)) continue;
+    return alias.targets.flatMap((target) => {
+      const base = joinPath(target, spec.slice(alias.prefix.length));
+      return base ? scriptCandidates(base) : [];
+    });
+  }
+  for (const [name, pkg] of context.packages) {
+    if (spec === name && pkg.entry) return scriptCandidates(pkg.entry);
+    if (spec.startsWith(`${name}/`)) {
+      const base = joinPath(pkg.dir, spec.slice(name.length + 1));
+      return base ? [...scriptCandidates(base), ...scriptCandidates(joinPath(pkg.dir, `src/${spec.slice(name.length + 1)}`) ?? base)] : [];
+    }
+  }
+  return [];
+}
+
+function scriptImports(text: string): string[] {
+  return [
+    ...all(/\b(?:import|export)\s+(?:type\s+)?[^'"`;]*?\bfrom\s*["']([^"']+)["']/g, text),
+    ...all(/\bimport\s*["']([^"']+)["']/g, text),
+    ...all(/\b(?:require|import)\s*\(\s*["']([^"']+)["']\s*\)/g, text),
+  ];
+}
+
+function pythonImports(from: string, text: string): string[][] {
+  const results: string[][] = [];
+  const module = (base: string, name: string) => {
+    const stem = joinPath(base, name.replace(/\./g, "/"));
+    return stem ? [`${stem}.py`, `${stem}.pyi`, `${stem}/__init__.py`] : [];
+  };
+  for (const match of text.matchAll(/^\s*from\s+(\.*)([\w.]*)\s+import\s+([\w*, ()]+)/gm)) {
+    const [, dots = "", name = "", names = ""] = match;
+    if (dots) {
+      let base = dirname(from);
+      for (let level = 1; level < dots.length; level += 1) base = dirname(base);
+      if (name) results.push(module(base, name));
+      else for (const item of names.replace(/[()]/g, "").split(",")) results.push(module(base, item.trim()));
+    } else results.push([...module("", name), ...module("src", name)]);
+  }
+  for (const match of text.matchAll(/^\s*import\s+([\w.]+(?:\s*,\s*[\w.]+)*)/gm)) {
+    for (const name of (match[1] ?? "").split(",")) results.push([...module("", name.trim()), ...module("src", name.trim())]);
+  }
+  return results;
+}
+
+function goImports(text: string, context: LinkContext): string[][] {
+  if (!context.goModule) return [];
+  const prefix = `${context.goModule}/`;
+  const specs = [...all(/^\s*import\s+(?:\w+\s+)?"([^"]+)"/gm, text)];
+  for (const block of all(/^\s*import\s*\(([\s\S]*?)\)/gm, text)) specs.push(...all(/"([^"]+)"/g, block));
+  return specs.filter((spec) => spec.startsWith(prefix)).map((spec) => [`${spec.slice(prefix.length)}${GO_PACKAGE}`]);
+}
+
+function rustImports(from: string, text: string): string[][] {
+  const name = from.split("/").pop() ?? "";
+  const own = /^(mod|lib|main)\.rs$/.test(name) ? dirname(from) : joinPath(dirname(from), name.replace(/\.rs$/, ""));
+  const results = all(/^\s*(?:pub\s+)?mod\s+(\w+)\s*;/gm, text).map((mod) => [`${own ?? ""}/${mod}.rs`, `${own ?? ""}/${mod}/mod.rs`].map((file) => file.replace(/^\//, "")));
+  for (const spec of all(/^\s*(?:pub\s+)?use\s+crate::([\w:]+)/gm, text)) {
+    const parts = spec.split("::");
+    for (let size = parts.length; size > 0; size -= 1) {
+      const stem = `src/${parts.slice(0, size).join("/")}`;
+      results.push([`${stem}.rs`, `${stem}/mod.rs`]);
+    }
+  }
+  return results;
+}
+
+// Repo paths named in config, scripts, and prose: a word with a slash and an extension, or a
+// relative path. Each is tried from the file's folder and from the repository root.
+function mentions(from: string, text: string): string[][] {
+  const words = all(/(?:^|[\s"'`(=:,[])((?:\.{1,2}\/)?[\w@.-]+(?:\/[\w@.-]+)+\.[A-Za-z][\w]{0,7})(?=$|[\s"'`),:;\]#?])/gm, text);
+  return [...new Set(words)].map((word) => {
+    const local = joinPath(dirname(from), word);
+    const rooted = word.startsWith(".") ? null : joinPath("", word);
+    return [local, rooted].filter((candidate): candidate is string => candidate !== null);
+  });
+}
+
+function markdownLinks(from: string, text: string): string[][] {
+  return all(/\]\(\s*<?([^)\s>]+)>?(?:\s+"[^"]*")?\s*\)/g, text)
+    .map((target) => target.split("#")[0] ?? "")
+    .filter((target) => target && !/^[a-z][\w+.-]*:/i.test(target))
+    .map((target) => {
+      const resolved = target.startsWith("/") ? joinPath("", target) : joinPath(dirname(from), decodeURI(target));
+      return resolved ? [resolved, `${resolved}/README.md`] : [];
+    });
+}
+
+function packageEntries(from: string, text: string): string[][] {
+  let pkg: Record<string, unknown>;
+  try {
+    pkg = JSON.parse(text) as Record<string, unknown>;
+  } catch {
+    return [];
+  }
+  const strings: string[] = [];
+  const collect = (value: unknown) => {
+    if (typeof value === "string") strings.push(value);
+    else if (value && typeof value === "object") for (const inner of Object.values(value)) collect(inner);
+  };
+  for (const key of ["main", "module", "types", "typings", "bin", "exports", "browser"]) collect(pkg[key]);
+  const dir = dirname(from);
+  const entries = strings.filter((value) => /^\.?\.?\/?[\w@.-]/.test(value) && !value.includes("*"));
+  const scripts = mentions(from, Object.values((pkg.scripts as Record<string, string>) ?? {}).join("\n"));
+  return [...entries.map((value) => [joinPath(dir, value)].filter((entry): entry is string => entry !== null)), ...scripts];
+}
+
+/** The references in one file, with candidate paths for each. */
+export function fileReferences(from: string, text: string, context: LinkContext = EMPTY_CONTEXT): Reference[] {
+  const ext = extension(from);
+  const name = from.split("/").pop() ?? "";
+  const refs: Reference[] = [];
+  const add = (kind: LinkKind, lists: string[][]) => {
+    for (const candidates of lists) if (candidates.length) refs.push({ kind, candidates });
+  };
+  if ([".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".mts", ".cts", ".vue", ".svelte", ".astro"].includes(ext)) {
+    add("import", scriptImports(text).map((spec) => scriptSpecifier(from, spec, context)));
+  } else if (ext === ".py" || ext === ".pyi") add("import", pythonImports(from, text));
+  else if (ext === ".go") add("import", goImports(text, context));
+  else if (ext === ".rs") add("import", rustImports(from, text));
+  else if (ext === ".rb") {
+    add("import", all(/\brequire_relative\s*\(?\s*["']([^"']+)["']/g, text).map((spec) => {
+      const base = joinPath(dirname(from), spec);
+      return base ? [base.endsWith(".rb") ? base : `${base}.rb`] : [];
+    }));
+  } else if ([".css", ".scss", ".sass", ".less"].includes(ext)) {
+    add("link", all(/@(?:import|use|forward)\s+(?:url\()?["']([^"']+)["']/g, text).map((spec) => {
+      const base = joinPath(dirname(from), spec);
+      if (!base) return [];
+      const partial = `${dirname(base)}/_${base.split("/").pop()}`.replace(/^\//, "");
+      return [base, `${base}.css`, `${base}.scss`, `${partial}.scss`, `${base}.less`];
+    }));
+  } else if (ext === ".md" || ext === ".mdx") add("link", markdownLinks(from, text));
+  else if (ext === ".html" || ext === ".htm") {
+    add("link", all(/\b(?:src|href)\s*=\s*["']([^"'#?]+)["']/g, text)
+      .filter((target) => !/^[a-z][\w+.-]*:|^\/\//i.test(target))
+      .map((target) => [joinPath(target.startsWith("/") ? "" : dirname(from), target)].filter((value): value is string => value !== null)));
+  } else if (name === "package.json") add("link", packageEntries(from, text));
+  else if (/^[tj]sconfig(\..+)?\.json$/.test(name)) {
+    add("link", all(/"extends"\s*:\s*"(\.[^"]+)"/g, text).map((spec) => {
+      const base = joinPath(dirname(from), spec);
+      return base ? [base, `${base}.json`] : [];
+    }));
+  }
+  // Every text file can name repo paths, as a workflow names the script it runs.
+  add("mention", mentions(from, text));
+  return refs;
+}
+
+/** Reads tsconfig paths, such as {"@/*": ["./src/*"]}, as prefix aliases. */
+export function aliasesFrom(config: unknown, configDir = ""): LinkContext["aliases"] {
+  const options = (config as { compilerOptions?: { baseUrl?: string; paths?: Record<string, string[]> } })?.compilerOptions;
+  const base = joinPath(configDir, options?.baseUrl ?? ".") ?? "";
+  return Object.entries(options?.paths ?? {}).flatMap(([pattern, targets]) => {
+    if (!pattern.endsWith("*") || !Array.isArray(targets)) return [];
+    const resolved = targets
+      .filter((target) => typeof target === "string" && target.endsWith("*"))
+      .map((target) => joinPath(base, target.slice(0, -1)) ?? "");
+    return [{ prefix: pattern.slice(0, -1), targets: resolved }];
+  });
+}
+
+/** Strips comments and trailing commas, which tsconfig files allow. */
+export function parseLooseJson(text: string): unknown {
+  const clean = text
+    .replace(/("(?:[^"\\]|\\.)*")|\/\/[^\n]*|\/\*[\s\S]*?\*\//g, (match, string: string | undefined) => string ?? "")
+    .replace(/,(\s*[}\]])/g, "$1");
+  try {
+    return JSON.parse(clean);
+  } catch {
+    return null;
+  }
+}

package/shared/live.ts

@@ -0,0 +1,243 @@
+import { defineRpc } from "@getpaseo/plugin";
+import { z } from "zod";
+import { McpHttpServerSchema, ToolPolicySchema } from "./agent-tools";
+import { IssueCardSchema, WorkflowStateSchema } from "./linear";
+
+// Contracts for Linear Live, todo sync, and project setup. Agents the plugin starts for itself
+// carry their own labels so they get no pill, no sync, and no place in the linked agent list.
+
+export const MapFileSchema = z.object({
+  path: z.string().min(1),
+  /** Issue key the file belongs to: the parent or one of its sub-issues. */
+  issue: z.string().min(1),
+});
+export type MapFile = z.infer<typeof MapFileSchema>;
+
+export const IssueMapSchema = z.object({
+  identifier: z.string(),
+  source: z.enum(["semantic", "explore"]),
+  files: z.array(MapFileSchema),
+  createdAt: z.string(),
+});
+export type IssueMap = z.infer<typeof IssueMapSchema>;
+
+export const JobSchema = z.object({
+  id: z.string(),
+  status: z.enum(["running", "done", "failed"]),
+  agentId: z.string().nullable(),
+  error: z.string().nullable(),
+  startedAt: z.string(),
+});
+export type Job = z.infer<typeof JobSchema>;
+
+/** What the explore agent must return. */
+export const ExploreResultSchema = z.object({
+  files: z.array(z.object({ path: z.string().min(1), issue: z.string().min(1) })).max(200),
+});
+
+export const InitProposalSchema = z.object({
+  instructions: z.string().default(""),
+  steps: z.array(z.string()).default([]),
+  implement: z.string().default(""),
+  review: z.string().default(""),
+});
+export type InitProposal = z.infer<typeof InitProposalSchema>;
+
+/** Files an explore run may list; the map and the graph show this many and more. */
+export const MAX_EXPLORE_FILES = 150;
+export const MAX_LIST_DIRS = 40;
+export const MAX_DIR_ENTRIES = 60;
+
+export const listFilesRpc = defineRpc({
+  name: "linear.live.files",
+  input: z.object({ agentId: z.string().min(1), dirs: z.array(z.string()).max(MAX_LIST_DIRS) }),
+  output: z.object({
+    dirs: z.array(z.object({ dir: z.string(), files: z.array(z.string()), truncated: z.boolean() })),
+  }),
+});
+
+export const MAX_LINK_FILES = 200;
+
+/** Imports and other links between the files on the graph. */
+export const linksRpc = defineRpc({
+  name: "linear.live.links",
+  input: z.object({ agentId: z.string().min(1), files: z.array(z.string().min(1)).max(MAX_LINK_FILES) }),
+  output: z.object({
+    links: z.array(z.object({ from: z.string(), to: z.string(), kind: z.enum(["import", "link", "mention"]) })),
+  }),
+});
+
+const SubagentLogSchema = z.object({
+  id: z.string(),
+  type: z.string(),
+  description: z.string(),
+  /** The parent's call that started it, when Claude recorded one. */
+  toolUseId: z.string().nullable(),
+  updatedAt: z.number(),
+  /** Its last reply ended the run. */
+  finished: z.boolean(),
+  items: z.array(
+    z.object({
+      type: z.literal("tool_call"),
+      callId: z.string(),
+      name: z.string(),
+      status: z.enum(["running", "completed", "failed"]),
+      detail: z.record(z.string(), z.unknown()),
+    }),
+  ),
+});
+export type SubagentLog = z.infer<typeof SubagentLogSchema>;
+
+/** Tool calls of the subagents an agent started inside its provider. */
+export const subagentLogsRpc = defineRpc({
+  name: "linear.live.subagents",
+  input: z.object({ agentId: z.string().min(1) }),
+  output: z.object({ runs: z.array(SubagentLogSchema) }),
+});
+
+/** Forgets the saved explore map of the agent's issue, so the map falls back to ticket text. */
+export const clearMapRpc = defineRpc({
+  name: "linear.live.map.clear",
+  input: z.object({ agentId: z.string().min(1) }),
+  output: z.object({ cleared: z.boolean() }),
+});
+
+export const liveMapRpc = defineRpc({
+  name: "linear.live.map",
+  input: z.object({ identifier: z.string().min(1) }),
+  output: z.object({ map: IssueMapSchema.nullable(), job: JobSchema.nullable() }),
+});
+
+export const exploreRpc = defineRpc({
+  name: "linear.live.explore",
+  input: z.object({ agentId: z.string().min(1), force: z.boolean().default(false) }),
+  output: z.object({ job: JobSchema }),
+});
+
+export const LaunchConfigSchema = z.object({
+  provider: z.string().min(1),
+  thinkingOptionId: z.string().optional(),
+  modeId: z.string().optional(),
+  /** Only the folder of the issue's Claude Code hooks; see agent-hooks.ts. */
+  providerOptions: z.object({ extraArgs: z.object({ "plugin-dir": z.string().min(1) }) }).optional(),
+  /** Only the plugin's own MCP server; see agent-tools.ts. */
+  mcpServers: z.object({ linear: McpHttpServerSchema }).optional(),
+  toolPolicy: ToolPolicySchema.optional(),
+});
+
+// The daemon maps the files first and then starts the agent, so closing the app mid-way
+// still starts it. With a saved map, or when exploring cannot start, the agent starts now.
+export const LaunchInputSchema = z.object({
+  workspaceId: z.string().min(1),
+  identifier: z.string().min(1),
+  keyScope: z.string().nullable(),
+  agent: z.object({
+    config: LaunchConfigSchema,
+    title: z.string(),
+    prompt: z.string(),
+    labels: z.record(z.string(), z.string()),
+  }),
+  card: IssueCardSchema,
+});
+export type LaunchInput = z.infer<typeof LaunchInputSchema>;
+
+export const launchAfterExploreRpc = defineRpc({
+  name: "linear.live.launch",
+  input: LaunchInputSchema,
+  output: z.object({ agentId: z.string().nullable(), job: JobSchema }),
+});
+
+export const SyncMoveSchema = z.object({
+  identifier: z.string(),
+  from: WorkflowStateSchema,
+  to: WorkflowStateSchema,
+});
+
+export const syncNowRpc = defineRpc({
+  name: "linear.sync.now",
+  input: z.object({ agentId: z.string().min(1) }),
+  output: z.object({ moves: z.array(SyncMoveSchema), skipped: z.string().nullable() }),
+});
+
+export const initStartRpc = defineRpc({
+  name: "linear.init.start",
+  input: z.object({ projectId: z.string().min(1), rootPath: z.string().min(1) }),
+  output: z.object({ job: JobSchema }),
+});
+
+export const initStatusRpc = defineRpc({
+  name: "linear.init.status",
+  input: z.object({ jobId: z.string().min(1) }),
+  output: z.object({ job: JobSchema.nullable(), proposal: InitProposalSchema.nullable() }),
+});
+
+const EXTENSIONS =
+  "ts|tsx|js|jsx|mjs|cjs|py|go|rs|rb|java|kt|swift|c|cc|cpp|h|hpp|cs|php|vue|svelte|css|scss|html|md|mdx|json|ya?ml|toml|sql|sh|prisma|graphql";
+const PATH = new RegExp(
+  `(?:^|[\\s\`'"(\\[])((?:[\\w@.-]+/)*[\\w@.-]+\\.(?:${EXTENSIONS}))(?=$|[\\s\`'")\\],.:;!?])`,
+  "g",
+);
+const DIRECTORY = /`((?:[\w@.-]+\/)+)`/g;
+const ISSUE_KEY = /\b[A-Z][A-Z0-9]*-\d+\b/g;
+
+export function pathsIn(text: string): string[] {
+  const found = new Set<string>();
+  for (const match of text.matchAll(PATH)) if (match[1]) found.add(match[1].replace(/^\.\//, ""));
+  for (const match of text.matchAll(DIRECTORY)) if (match[1]) found.add(match[1]);
+  return [...found].filter((path) => !/^https?:/.test(path) && !path.includes("//"));
+}
+
+export interface SemanticIssue {
+  identifier: string;
+  title: string;
+  description: string | null;
+  children: readonly { identifier: string; title: string }[];
+}
+
+// Linear sends sub-issue titles but not their descriptions, so a path in the parent's text
+// belongs to the sub-issue its line names and otherwise to the parent.
+export function semanticMap(issue: SemanticIssue, now = new Date()): IssueMap {
+  const owners = new Map<string, string>();
+  const childKeys = new Set(issue.children.map((child) => child.identifier.toUpperCase()));
+  for (const child of issue.children) {
+    for (const path of pathsIn(child.title)) owners.set(path, child.identifier);
+  }
+  const lines = `${issue.title}\n${issue.description ?? ""}`.split("\n");
+  for (const line of lines) {
+    const named = (line.match(ISSUE_KEY) ?? []).find((key) => childKeys.has(key));
+    for (const path of pathsIn(line)) {
+      if (!owners.has(path)) owners.set(path, named ?? issue.identifier);
+    }
+  }
+  return {
+    identifier: issue.identifier,
+    source: "semantic",
+    files: [...owners].map(([path, owner]) => ({ path, issue: owner })),
+    createdAt: now.toISOString(),
+  };
+}
+
+/** Parses the last JSON object in an agent reply: a fenced block, the whole text, or braces. */
+export function lastJsonObject(reply: string): unknown {
+  const fences = [...reply.matchAll(/```(?:json)?\s*\n([\s\S]*?)```/g)].reverse();
+  const candidates = [...fences.map((match) => match[1] ?? ""), reply.trim()];
+  const start = reply.indexOf("{");
+  const end = reply.lastIndexOf("}");
+  if (start >= 0 && end > start) candidates.push(reply.slice(start, end + 1));
+  for (const candidate of candidates) {
+    try {
+      const value: unknown = JSON.parse(candidate);
+      if (value && typeof value === "object" && !Array.isArray(value)) return value;
+    } catch {
+      // Not JSON; try the next candidate.
+    }
+  }
+  return null;
+}
+
+/** Directory of a repo path, with a trailing slash, or "" for the root. */
+export function dirOf(path: string): string {
+  if (path.endsWith("/")) return path;
+  const index = path.lastIndexOf("/");
+  return index < 0 ? "" : path.slice(0, index + 1);
+}

package/shared/map-model.ts

@@ -0,0 +1,192 @@
+import type { DirTouch, FileTouch } from "./activity";
+import { dirOf, type MapFile } from "./live";
+
+// The Linear Live map: predicted files and touched files grouped into folder zones, and the
+// column layout for those zones. Pure, so it runs in tests without React Native.
+
+const MAX_GHOSTS = 4;
+/** Listing chips are hidden once a zone has this many real tiles. */
+const GHOSTS_UNTIL = 6;
+
+export interface MapTile {
+  path: string;
+  name: string;
+  owner: string | null;
+  ghost: boolean;
+  onMap: boolean;
+  touch: "none" | "read" | "edited" | "created";
+  added: number;
+  removed: number;
+}
+
+export type ZoneExplored = "none" | "listed" | "searched";
+
+export interface MapZone {
+  dir: string;
+  tiles: MapTile[];
+  /** Files in the zone that are on the map. */
+  predicted: number;
+  /** Files in the zone the agent read or changed. */
+  touched: number;
+  /** Touched files that are on the map. */
+  hits: number;
+  explored: ZoneExplored;
+}
+
+export interface MapModel {
+  zones: MapZone[];
+  touched: number;
+  hits: number;
+}
+
+// Search hits alone do not count: one broad search would flood the map with off-map tiles.
+function isTouched(file: FileTouch): boolean {
+  return file.reads + file.edits > 0;
+}
+
+function touchState(file: FileTouch | undefined): MapTile["touch"] {
+  if (!file) return "none";
+  if (file.created) return "created";
+  return file.edits > 0 ? "edited" : "read";
+}
+
+interface Predictions {
+  files: ReadonlyMap<string, string>;
+  dirs: ReadonlyMap<string, string>;
+}
+
+// A map entry ending in "/" names a directory: it seeds a zone and owns the files inside.
+function predictions(files: readonly MapFile[]): Predictions {
+  const paths = new Map<string, string>();
+  const dirs = new Map<string, string>();
+  for (const file of files) {
+    const target = file.path.endsWith("/") ? dirs : paths;
+    if (!target.has(file.path)) target.set(file.path, file.issue.toUpperCase());
+  }
+  return { files: paths, dirs };
+}
+
+function ownerOf(path: string, predicted: Predictions): string | null {
+  const direct = predicted.files.get(path);
+  if (direct) return direct;
+  for (const [dir, owner] of predicted.dirs) if (path.startsWith(dir)) return owner;
+  return null;
+}
+
+/** Zone directories: predicted ones in map order, then touched ones by name. */
+export function zoneDirs(files: readonly MapFile[], touches: readonly FileTouch[]): string[] {
+  const dirs = new Set(files.map((file) => dirOf(file.path)));
+  const extra = touches.filter(isTouched).map((file) => dirOf(file.path));
+  for (const dir of [...new Set(extra)].sort()) dirs.add(dir);
+  return [...dirs];
+}
+
+// A listed folder counts for itself; a recursive search counts for every folder under it,
+// except a search of the whole repository, which would mark every zone.
+function exploredState(dir: string, dirs: readonly DirTouch[]): ZoneExplored {
+  let state: ZoneExplored = "none";
+  for (const touch of dirs) {
+    const covers = touch.path === dir || (touch.deep && touch.path !== "" && dir.startsWith(touch.path));
+    if (covers && touch.deep) return "searched";
+    if (covers) state = "listed";
+  }
+  return state;
+}
+
+export function buildMapModel(
+  files: readonly MapFile[],
+  touches: readonly FileTouch[],
+  listing: ReadonlyMap<string, readonly string[]>,
+  dirs: readonly DirTouch[] = [],
+): MapModel {
+  const predicted = predictions(files);
+  const touched = new Map(touches.filter(isTouched).map((file) => [file.path, file]));
+  const zones = zoneDirs(files, touches).map((dir): MapZone => {
+    const inZone = (path: string) => dirOf(path) === dir;
+    const real = new Set([...predicted.files.keys(), ...touched.keys()].filter(inZone));
+    const tiles = [...real].sort().map((path): MapTile => {
+      const touch = touched.get(path);
+      const owner = ownerOf(path, predicted);
+      return {
+        path,
+        name: path.slice(dir.length),
+        owner,
+        ghost: false,
+        onMap: owner !== null,
+        touch: touchState(touch),
+        added: touch?.added ?? 0,
+        removed: touch?.removed ?? 0,
+      };
+    });
+    const ghosts = (tiles.length >= GHOSTS_UNTIL ? [] : (listing.get(dir) ?? []))
+      .filter((name) => !real.has(`${dir}${name}`))
+      .slice(0, MAX_GHOSTS)
+      .map((name): MapTile => {
+        const path = `${dir}${name}`;
+        const owner = ownerOf(path, predicted);
+        const onMap = owner !== null;
+        return { path, name, owner, ghost: true, onMap, touch: "none", added: 0, removed: 0 };
+      });
+    return {
+      dir,
+      tiles: [...tiles, ...ghosts],
+      predicted: tiles.filter((tile) => tile.onMap).length,
+      touched: tiles.filter((tile) => tile.touch !== "none").length,
+      hits: tiles.filter((tile) => tile.touch !== "none" && tile.onMap).length,
+      explored: exploredState(dir, dirs),
+    };
+  });
+  let hits = 0;
+  for (const path of touched.keys()) if (ownerOf(path, predicted)) hits += 1;
+  return { zones, touched: touched.size, hits };
+}
+
+export function hitRateLine(model: MapModel): string {
+  if (model.touched === 0) return "No files touched yet";
+  const noun = model.touched === 1 ? "file" : "files";
+  return `${model.touched} ${noun} touched, ${model.hits} on the map`;
+}
+
+export const ZONE_GAP = 10;
+
+// Rough zone height from its tiles, so zones can go to the shortest column. Tiles wrap, so
+// count how many fit per row by name length.
+function zoneHeight(zone: MapZone, width: number): number {
+  const inner = Math.max(120, width - 26);
+  let rows = 1;
+  let used = 0;
+  for (const tile of zone.tiles) {
+    const tileWidth = Math.min(inner, 32 + tile.name.length * 7);
+    if (used > 0 && used + tileWidth > inner) {
+      rows += 1;
+      used = 0;
+    }
+    used += tileWidth + 6;
+  }
+  return 46 + rows * 32;
+}
+
+/**
+ * Splits zones into columns in map order. A zone in `placed` keeps its column; a new zone
+ * goes to the shortest column and is added to `placed`.
+ */
+export function masonry(
+  zones: readonly MapZone[],
+  columns: number,
+  width: number,
+  placed: Map<string, number>,
+): MapZone[][] {
+  const result: MapZone[][] = Array.from({ length: columns }, () => []);
+  const heights: number[] = Array.from({ length: columns }, () => 0);
+  const columnWidth = (width - ZONE_GAP * (columns - 1)) / columns;
+  for (const zone of zones) {
+    let column = placed.get(zone.dir);
+    if (column === undefined || column >= columns) {
+      column = heights.indexOf(Math.min(...heights));
+      placed.set(zone.dir, column);
+    }
+    result[column]?.push(zone);
+    heights[column] = (heights[column] ?? 0) + zoneHeight(zone, columnWidth) + ZONE_GAP;
+  }
+  return result;
+}