app/engine/ladderNotes.ts

// Ladder storage via git notes. A note is only worth writing for rungs
// anchored to a real git object (a file's blob, a directory's tree, the
// repo's root tree or root commit, or a release's own commit); a
// function/line/answer/nested-ask rung has no git object of its own, so
// it's embedded inline in its nearest anchor ancestor's note instead of
// getting one of its own. That keeps note count proportional to files plus
// top-level asks and releases, not to every function, line, and reply,
// while still letting you read "everything about this one file" or "this
// whole ask thread" in a single note.
import type { Rung, RungKind, RungSource } from "./ladder.js";
import { resolvePathSha, resolveRootCommit, writeNote, readNote, expandOid, isDirectoryAtHead } from "./gitNotes.js";
import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
import { dirname, join } from "node:path";

// repo/directory/file/release are anchors wherever they appear in the tree.
// ask/contributor/dependencies are repo-wide: no tree path, so they anchor
// to the repo's root commit with their own identity folded into the note
// ref instead. "ask" is further special: only a *top-level* ask (a new
// thread) is an anchor. Once you're inside a thread, nothing nested in it
// gets its own note, even an "ask"-kind reply that raises something new in
// that same thread -- it's still part of that one conversation, not a
// fresh top-level item. contributor/dependencies never thread, so they're
// always anchors wherever they appear.
const STRUCTURAL_ANCHOR_KINDS = new Set<RungKind>(["repo", "directory", "file", "release", "changeset"]);
const REPO_WIDE_ROOT_KINDS = new Set<RungKind>(["ask", "contributor", "dependencies"]);

// Git ref names forbid several characters a real-world path segment can
// easily contain (a bot login like "dependabot[bot]" has brackets). Applied
// consistently on both write and read (both go through this function with
// the same input path), so the mapping stays stable even though it's lossy.
// git's own ref-name rules reject more than just the characters the
// first replace already strips: no path component may start with "."
// (confirmed live: a real top-level ".zz" directory -- not unusual at
// all, plenty of real repos have dotfiles/dotdirs -- produced
// "refs/notes/zz/ladder/dir/.zz", which git refused outright) or
// contain "..". Applied per "/"-separated component, not to the whole
// string at once, since a leading "." is only invalid at the START of
// a component, not wherever it happens to appear overall.
function sanitizeRefSegment(segment: string): string {
  return segment
    .replace(/[^A-Za-z0-9._/-]/g, "-")
    .split("/")
    .map((part) => part.replace(/^\.+/, "_").replace(/\.\./g, "_"))
    .join("/");
}

function notesRef(kind: RungKind, path: string): string {
  if (REPO_WIDE_ROOT_KINDS.has(kind)) return `refs/notes/zz/ladder/${sanitizeRefSegment(path)}`;
  if (kind === "release") return "refs/notes/zz/ladder/release";
  if (kind === "changeset") return "refs/notes/zz/ladder/changeset";
  // Git notes hold exactly one note per (ref, oid) pair -- a directory
  // anchors to the repo's own root commit oid now (anchorSha's own
  // comment), the SAME oid "_repo" itself anchors to, so sharing the
  // generic "code" ref here would collide the two (and every directory
  // with every other) onto one slot, each write silently clobbering
  // whichever was there before. Confirmed live: every directory read
  // back as "_repo"'s own content once this collision existed. A
  // path-specific ref, same shape REPO_WIDE_ROOT_KINDS already uses
  // for exactly this reason, keeps each directory (and "_repo" itself,
  // on the unprefixed "code" ref) in its own slot despite sharing an
  // oid. No remote-side cost to this -- unlike cloudflareLadderBackend.ts's
  // own deliberate ref-sharing (one network fetch per distinct ref),
  // a local note lives in the already-cloned repo, so more local refs
  // cost nothing extra.
  //
  // The path's own "/" separators can't survive into the ref name,
  // though, the way REPO_WIDE_ROOT_KINDS's flat "asks/<n>"/
  // "contributors/<login>" paths safely do -- a directory path is
  // inherently hierarchical (app, app/agent, app/cli, ...), and git's
  // own loose-ref storage is a real filesystem tree where a ref name
  // can't be a path-prefix of another ref name. refs/notes/zz/ladder/
  // dir/app and refs/notes/zz/ladder/dir/app/agent can't coexist --
  // the first IS a file at the path the second needs to be a
  // directory. Confirmed live: "ENOTDIR: not a directory" the moment
  // a repo had any directory with a subdirectory of its own, which is
  // every real repo past one level deep. Flattening "/" to "__" first
  // makes every directory's ref a flat sibling under dir/, with no
  // ref ever a prefix of another.
  if (kind === "directory") return `refs/notes/zz/ladder/dir/${sanitizeRefSegment(path.replace(/\//g, "__"))}`;
  return "refs/notes/zz/ladder/code";
}

export interface EmbeddedRef {
  ref: string;
}

export interface EmbeddedRung {
  path: string;
  kind: RungKind;
  summary: string;
  sources: RungSource[];
  touches?: string[];
  children: (EmbeddedRung | EmbeddedRef)[];
}

function isRef(x: EmbeddedRung | EmbeddedRef): x is EmbeddedRef {
  return "ref" in x;
}

/** insideThread: true once `rung` itself is inside a thread (is, or descends from, an ask). Its children are then always embedded too, regardless of their own kind -- being a child of any ask means you're part of that one thread, not a fresh top-level item. */
function embed(rung: Rung, insideThread: boolean): EmbeddedRung {
  const childrenInsideThread = insideThread || rung.kind === "ask";
  return {
    path: rung.path,
    kind: rung.kind,
    summary: rung.summary,
    sources: rung.sources,
    touches: rung.touches,
    children: rung.children.map((c) => {
      const isTopLevelRepoWide = !childrenInsideThread && REPO_WIDE_ROOT_KINDS.has(c.kind);
      const isAnchorChild = !childrenInsideThread && STRUCTURAL_ANCHOR_KINDS.has(c.kind);
      if (isTopLevelRepoWide || isAnchorChild) return { ref: c.path };
      return embed(c, childrenInsideThread);
    }),
  };
}

// Small index, only for releases now: there's no tree path for a release
// and (unlike asks) it keeps anchoring to its own real commit rather than
// the repo-wide root, so something has to record which commit that was.
// Proportional to how many releases we track, not to codebase size -- the
// same reasoning data-format.md gives for keeping Lanes and Roles as plain
// files rather than notes.
function indexPath(stateDir: string): string {
  return join(stateDir, ".zz", "ladder-index.json");
}

function readIndex(stateDir: string): Record<string, string> {
  const path = indexPath(stateDir);
  if (!existsSync(path)) return {};
  return JSON.parse(readFileSync(path, "utf8"));
}

function writeIndexEntry(stateDir: string, rungPath: string, sha: string): void {
  const path = indexPath(stateDir);
  const index = readIndex(stateDir);
  index[rungPath] = sha;
  mkdirSync(dirname(path), { recursive: true });
  writeFileSync(path, JSON.stringify(index, null, 2) + "\n");
}

function firstCommitRef(rung: Rung): string {
  const commit = rung.sources.find((s) => s.kind === "commit");
  if (!commit) throw new Error(`${rung.path}: no commit source to anchor a note to`);
  return commit.ref;
}

// resolveRootCommit walks the repo's full history; cache it per repo rather
// than re-walking for every top-level ask.
const rootCommitCache = new Map<string, Promise<string>>();
function cachedRootCommit(repoDir: string): Promise<string> {
  let cached = rootCommitCache.get(repoDir);
  if (!cached) {
    cached = resolveRootCommit(repoDir);
    rootCommitCache.set(repoDir, cached);
  }
  return cached;
}

async function anchorSha(repoDir: string, stateDir: string, rung: Rung): Promise<string> {
  // The repo's own root commit, not the current/HEAD tree: the tree sha
  // changes on every commit, which would silently orphan _repo's note
  // (and everything registered under it) on the very next commit in any
  // repo under live development, not just a one-time onboarding pass.
  // "directory" has the exact same problem -- its own tree sha changes
  // whenever ANY file inside it changes, anywhere in its subtree, not
  // just a direct child -- and used to anchor there anyway (confirmed
  // live: ladder-sync.ts's own first real incremental run silently
  // orphaned every directory note that had a changed file under it,
  // making the whole subtree unreadable). A directory's own summary
  // ("N entries: ...") isn't tied to any one file's content either, so
  // there's nothing lost anchoring it the same stable way "repo" (and
  // every REPO_WIDE_ROOT_KINDS entry) already does.
  if (rung.kind === "repo" || rung.kind === "directory") return cachedRootCommit(repoDir);
  if (rung.kind === "file") {
    const sha = await resolvePathSha(repoDir, rung.path);
    if (!sha) throw new Error(`${rung.path}: not found in the repo at HEAD`);
    return sha;
  }
  if (REPO_WIDE_ROOT_KINDS.has(rung.kind)) return cachedRootCommit(repoDir);
  // release: anchor to its own real commit, already in its sources. Our
  // sources store short SHAs for readability; notes need the full one.
  const sha = await expandOid(repoDir, firstCommitRef(rung));
  writeIndexEntry(stateDir, rung.path, sha);
  return sha;
}

/** Writes one note per top-level anchor in the tree, recursively. Everything inside a thread, or nested under a file, is embedded, not written separately. */
export async function writeLadder(repoDir: string, stateDir: string, root: Rung): Promise<void> {
  const visit = async (rung: Rung, insideThread: boolean): Promise<void> => {
    const isAnchor = !insideThread && (REPO_WIDE_ROOT_KINDS.has(rung.kind) || STRUCTURAL_ANCHOR_KINDS.has(rung.kind));
    if (!isAnchor) return; // shouldn't be called on a non-anchor, but guard anyway
    const sha = await anchorSha(repoDir, stateDir, rung);
    await writeNote(repoDir, notesRef(rung.kind, rung.path), sha, embed(rung, false));
    const childrenInsideThread = insideThread || rung.kind === "ask";
    for (const child of rung.children) {
      if (!childrenInsideThread) await visit(child, false);
    }
  };
  await visit(root, false);
}

/**
 * Adds references to the repo root's own note without touching any
 * existing child, written or not. writeLadder always recurses into every
 * anchor child it's given, which is right when building a tree from
 * scratch but would re-derive and overwrite already-correct content for
 * anything passed in as a bare stub just to get it into the children
 * list. This only ever rewrites the repo root's one note.
 */
export async function appendRepoChildren(repoDir: string, stateDir: string, newChildren: { path: string; kind: RungKind }[]): Promise<void> {
  const current = await readAnchor(repoDir, stateDir, "_repo");
  if (!current) throw new Error("repo root has no note yet; run the main build first");
  const existingRefs = new Set(current.children.filter(isRef).map((c) => c.ref));
  const toAdd = newChildren.filter((c) => !existingRefs.has(c.path));
  current.children.push(...toAdd.map((c) => ({ ref: c.path })));
  const sha = await cachedRootCommit(repoDir);
  await writeNote(repoDir, notesRef("repo", "_repo"), sha, current);
}

/** Reads one anchor's note (its own fields plus everything embedded under it, inline). */
export async function readAnchor(repoDir: string, stateDir: string, path: string): Promise<EmbeddedRung | null> {
  if (path === "_repo") {
    const sha = await cachedRootCommit(repoDir);
    return readNote<EmbeddedRung>(repoDir, notesRef("repo", path), sha);
  }
  if (path.startsWith("asks/")) {
    const sha = await cachedRootCommit(repoDir);
    return readNote<EmbeddedRung>(repoDir, notesRef("ask", path), sha);
  }
  if (path.startsWith("contributors/")) {
    const sha = await cachedRootCommit(repoDir);
    return readNote<EmbeddedRung>(repoDir, notesRef("contributor", path), sha);
  }
  if (path === "dependencies" || path.startsWith("dependencies/") || path === "dependents") {
    const sha = await cachedRootCommit(repoDir);
    return readNote<EmbeddedRung>(repoDir, notesRef("dependencies", path), sha);
  }
  if (path.startsWith("changesets/")) {
    const sha = readIndex(stateDir)[path];
    if (!sha) return null;
    return readNote<EmbeddedRung>(repoDir, notesRef("changeset", path), sha);
  }
  // A directory anchors to the repo's root commit now (anchorSha's own
  // reasoning: its tree sha changes whenever any file anywhere under
  // it changes, which would orphan the note on the very next unrelated
  // commit) -- checked before the file case below, since a directory
  // path would otherwise fall through to resolvePathSha's own
  // blob-then-tree fallback and get misread as a file-kind note that
  // was never written at that sha.
  if (await isDirectoryAtHead(repoDir, path)) {
    const sha = await cachedRootCommit(repoDir);
    return readNote<EmbeddedRung>(repoDir, notesRef("directory", path), sha);
  }
  const fileSha = await resolvePathSha(repoDir, path);
  if (fileSha) return readNote<EmbeddedRung>(repoDir, notesRef("file", path), fileSha);
  // Not a tree path: must be a release, looked up in the small index.
  const releaseSha = readIndex(stateDir)[path];
  if (!releaseSha) return null;
  return readNote<EmbeddedRung>(repoDir, notesRef("release", path), releaseSha);
}

/** Finds a rung (anchor or embedded) by exact path, starting from an already-read anchor subtree. */
export function findEmbedded(root: EmbeddedRung, path: string): EmbeddedRung | null {
  if (root.path === path) return root;
  for (const child of root.children) {
    if (isRef(child)) continue;
    const found = findEmbedded(child, path);
    if (found) return found;
  }
  return null;
}

export { isRef };