Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
13.9 KB
Raw Blame
/** GST-2116, GST-2767: which named paths a commit-push left out, and why, in words an operator can act on. */
import { existsSync, lstatSync, readFileSync, readlinkSync, statSync } from 'node:fs';
import { dirname, join, relative, resolve } from 'node:path';
import { literalPathspecs } from '../git-env.ts';
import { canonicalFilesystemPath } from '../persistence/root-registry.ts';
import { opError } from '../ops/contract.ts';
import { git, gitOk } from './git-run.ts';

export interface SkippedPath { path: string; reason: 'assume_unchanged' | 'skip_worktree' | 'not_staged' | 'staged_for_removal'; why: string }

export const STAGED_FOR_REMOVAL_WHY = 'the index holds it as staged for removal from Git (as after git rm --cached) while the file stays on disk, and commit-push neither commits that removal nor adds the file back unasked';

/** The files under `rel` the index holds as staged for removal (HEAD has them, the index does not) whose bytes are still on disk. */
export function stagedRemovals(root: string, rel: string[]): string[] {
  if (!rel.length) return [];
  return gitOk(root, ['diff', '--cached', '--no-renames', '--name-only', '--diff-filter=D', '-z', '--', ...literalPathspecs(rel)], 'diff --cached')
    .split('\0').filter(path => { try { return !!path && !lstatSync(join(root, path)).isDirectory(); } catch { return false; } });
}

/** The flagged index entries in `listed` (`ls-files -v`: lower case for assume-unchanged, S for skip-worktree) whose bytes on disk HEAD lacks. A skip-worktree entry absent from disk is a sparse checkout, not a change. */
export function flaggedChanges(root: string, listed: string[]): SkippedPath[] {
  const changed: SkippedPath[] = [];
  const flagged = listed.filter(entry => /^[a-zS] /.test(entry));
  const gitlinks = new Set(flagged.length
    ? gitOk(root, ['ls-files', '-s', '-z', '--', ...literalPathspecs(flagged.map(line => line.slice(2)))], 'ls-files -s')
      .split('\0').filter(entry => entry.startsWith('160000 ')).map(entry => entry.slice(entry.indexOf('\t') + 1))
    : []);
  for (const line of flagged) {
    const path = line.slice(2);
    if (gitlinks.has(path)) continue;
    const abs = join(root, path);
    const reason = /^[sS]/.test(line) ? 'skip_worktree' as const : 'assume_unchanged' as const;
    const stat = (() => { try { return lstatSync(abs); } catch { return null; } })();
    if (!stat && reason === 'skip_worktree') continue;
    const hashed = !stat ? null : stat.isSymbolicLink()
      ? git(root, ['hash-object', '--stdin'], { input: readlinkSync(abs) })
      : git(root, ['hash-object', '--', path]);
    // An entry git cannot hash (a missing required filter, an unreadable file, a directory now) counts as changed, so it is reported, never dropped.
    const disk = hashed && (hashed.code === 0 ? hashed.stdout.trim() : undefined);
    const committed = git(root, ['rev-parse', '--verify', '--quiet', `HEAD:${path}`]).stdout.trim() || null;
    if (disk !== committed) changed.push({ path, reason, why: reason === 'skip_worktree'
      ? 'the index entry carries the skip-worktree flag, so git add does not see the edit on disk'
      : 'the index entry carries the assume-unchanged flag, so git add does not see the edit on disk' });
  }
  return changed;
}

/**
 * GST-2116: the named paths whose bytes on disk HEAD still lacks once the commit step is done. `git add -A` stages
 * nothing and exits 0 for a modified entry flagged assume-unchanged or skip-worktree (`ls-files -v`: lower case, or S;
 * `commit --only` may still pick one up beside another path, so the check reads HEAD) and for a file inside an untracked
 * nested repository. A skip-worktree entry absent from disk is a sparse checkout, not a change, and a flagged gitlink
 * is left out (its commit lives in the nested repository, which hash-object cannot read). Ignored files under a named
 * directory are left out as git leaves them; a named ignored file is refused by `git add` itself.
 */
export function unstagedPaths(root: string, rel: string[], listed: string[], dirtyBefore: Map<string, string>, sha: string | null): SkippedPath[] {
  const skipped = new Map(flaggedChanges(root, listed).map(s => [s.path, s]));
  const notStaged = (path: string, why: string) => { if (!skipped.has(path)) skipped.set(path, { path, reason: 'not_staged', why }); };
  const removed = new Set(stagedRemovals(root, rel));
  for (const path of unindexedFiles(root, rel, listed)) {
    if (removed.has(path)) { skipped.set(path, { path, reason: 'staged_for_removal', why: STAGED_FOR_REMOVAL_WHY }); continue; }
    const nested = nestedRepositoryOf(root, path);
    notStaged(path, nested ? `it sits inside the nested Git repository ${nested}, so git add stages nothing for it` : 'git add left it out of the index');
  }
  // Only a named directory can hide an unstaged change from the two checks above (a nested repository inside it).
  const dirs = rel.filter(path => { try { return lstatSync(join(root, path)).isDirectory(); } catch { return false; } });
  // Status lists nothing under a directory that sits inside an untracked nested repository.
  for (const path of dirs) {
    const nested = nestedRepositoryOf(root, path);
    if (nested) notStaged(path, `it sits inside the nested Git repository ${nested}, so git add stages nothing under it`);
  }
  // GST-2128: an entry that was clean before the add, or a tracked one this commit carried, is another writer's later change, not a skip.
  const status = directoryStatus(root, dirs);
  const carried = sha && status.size ? committedModes(root, sha) : new Map<string, string>();
  for (const [path, xy] of status) {
    if (xy[1] === ' ' || skipped.has(path) || !dirtyBefore.has(path)) continue;
    if (xy !== '??' && carried.has(path) && carried.get(path) !== '160000') continue;
    notStaged(path, xy === '??' ? 'it is still untracked after the commit' : `it still differs from the last commit after the commit (git status ${xy.trim()})`);
  }
  return [...skipped.values()].sort((a, b) => a.path.localeCompare(b.path));
}

/**
 * GST-2767: the directory above `path` (repository-relative) that Git treats as a nested repository, or null. A `.git`
 * entry alone is not one: an empty or broken `.git` left under a source path is ignored by git, which stages and commits
 * the files beneath it, so only a directory that is its own work-tree top level counts.
 */
export function nestedRepositoryOf(root: string, path: string): string | null {
  const parts = path.split('/');
  const own = validGitDir(join(root, '.git'));
  for (let i = 1; i < parts.length; i++) {
    const dir = parts.slice(0, i).join('/');
    const gitDir = validGitDir(join(root, dir, '.git'));
    if (gitDir && gitDir !== own) return dir;
  }
  return null;
}

/**
 * The git directory a `.git` entry names (a directory, a link to one, or a `gitdir:` file), canonical, when git's own
 * discovery would take it as a repository: HEAD names a ref or an object, and objects/ and refs/ exist. Ownership is never
 * read, as `git add` in the outer repository does not read it, so a nested repository git refuses to open still counts.
 */
export function validGitDir(dotGit: string): string | null {
  try {
    let dir = dotGit;
    if (statSync(dotGit).isFile()) {
      const named = /^gitdir: (.+)$/m.exec(readSmallFile(dotGit));
      if (!named) return null;
      dir = resolve(dirname(dotGit), named[1]!.trim());
    }
    const head = readSmallFile(join(dir, 'HEAD')).trim();
    if (!/^ref: refs\//.test(head) && !/^[0-9a-f]{40}([0-9a-f]{24})?$/.test(head)) return null;
    const common = existsSync(join(dir, 'commondir')) ? resolve(dir, readSmallFile(join(dir, 'commondir')).trim()) : dir;
    return existsSync(join(common, 'objects')) && existsSync(join(common, 'refs')) ? canonicalFilesystemPath(dir) : null;
  } catch {
    return null;
  }
}

/** A git metadata file's text, refusing anything but a small regular file: a FIFO or device there would block the read under the commit lock. */
function readSmallFile(path: string): string {
  const stat = statSync(path);
  if (!stat.isFile() || stat.size > 4096) throw new Error(path + ' is not a small regular file');
  return readFileSync(path, 'utf8');
}

/** The `git status` entries under the named paths that are directories, as path (a nested repository keeps its trailing /) to XY code. */
export function directoryStatus(root: string, rel: string[]): Map<string, string> {
  const dirs = rel.filter(path => { try { return lstatSync(join(root, path)).isDirectory(); } catch { return false; } });
  const status = dirs.length ? gitOk(root, ['--no-optional-locks', 'status', '--porcelain=v1', '-z', '--untracked-files=all', '--no-renames', '--', ...literalPathspecs(dirs)], 'status') : '';
  return new Map(status.split('\0').filter(Boolean).map(entry => [entry.slice(3), entry.slice(0, 2)]));
}

/** The paths commit `sha` changed, each with its new mode (160000 for a gitlink, 000000 for a removal). */
export function committedModes(root: string, sha: string): Map<string, string> {
  const fields = gitOk(root, ['diff-tree', '--root', '-r', '--no-renames', '--no-commit-id', '-z', sha], 'diff-tree').split('\0');
  const modes = new Map<string, string>();
  for (let i = 0; i + 1 < fields.length; i += 2) if (fields[i]!.startsWith(':')) modes.set(fields[i + 1]!, fields[i]!.split(' ')[1]!);
  return modes;
}

/** Named paths that are files on disk yet absent from the index (`listed`: `ls-files -v` after `git add -A`), as a file inside a nested repository is. */
export function unindexedFiles(root: string, rel: string[], listed: string[]): string[] {
  const indexed = new Set(listed.map(line => line.slice(2)));
  return rel.filter(path => {
    if (indexed.has(path)) return false;
    try { return !lstatSync(join(root, path)).isDirectory(); } catch { return false; }
  });
}

/**
 * GST-2767: the checkout above `dir` when git refuses `dir` only because a `.git` file in it or above it points at no
 * repository (a leftover from a moved submodule or worktree), and that checkout already tracks files under `dir`; else
 * null. Git itself stages such a folder from the checkout above, so the folder is committed there instead of refused.
 */
export function checkoutBehindStrayGitfile(dir: string): string | null {
  for (let at = canonicalFilesystemPath(dir); dirname(at) !== at; at = dirname(at)) {
    try { if (!lstatSync(join(at, '.git')).isFile()) continue; } catch { continue; }
    const top = git(dirname(at), ['rev-parse', '--show-toplevel']);
    if (top.code !== 0) continue;
    const root = top.stdout.trim();
    const rel = relative(canonicalFilesystemPath(root), canonicalFilesystemPath(dir));
    return git(root, ['ls-files', '--', ...literalPathspecs([rel])]).stdout.trim() ? root : null;
  }
  return null;
}

/**
 * GST-2767: the folder whose own `.git` is the repository `top` reached through a linked `.git` (repo-a/brain/.git ->
 * ../.git). Git then reports the linked folder as the top level and would commit its files at the wrong place in the
 * tree, so the real work tree is the folder that holds that git directory; any other `top` is returned unchanged.
 */
export function worktreeOfGitdir(top: string): string {
  const gitDir = git(top, ['rev-parse', '--absolute-git-dir']);
  if (gitDir.code !== 0) return top;
  const real = canonicalFilesystemPath(gitDir.stdout.trim());
  for (let at = dirname(canonicalFilesystemPath(top)); dirname(at) !== at; at = dirname(at)) {
    if (existsSync(join(at, '.git')) && canonicalFilesystemPath(join(at, '.git')) === real) return at;
  }
  return top;
}

/** The named paths with unresolved merge conflicts in the index; a failed listing throws git_unavailable, never reads as none. */
export function unmergedPaths(root: string, rel: string[]): string[] {
  return [...new Set(gitOk(root, ['ls-files', '-u', '-z', '--', ...literalPathspecs(rel)], 'ls-files -u').split('\0').filter(Boolean).map(l => l.slice(l.indexOf('\t') + 1)))];
}

/**
 * The named paths without those an unresolved merge conflict holds, so a pending-ledger sweep still commits the rest. Asks git in
 * batches of 500 paths; a listing that fails leaves the list whole, so the commit's own check refuses it and the caller's fallback runs.
 */
export function withoutUnmergedPaths(root: string, rel: string[]): string[] {
  const unmerged = new Set<string>();
  try { for (let i = 0; i < rel.length; i += 500) for (const p of unmergedPaths(root, rel.slice(i, i + 500))) unmerged.add(p); } catch { return rel; }
  return rel.filter(p => !unmerged.has(p));
}

/** Refuses, before anything is staged, named paths with unresolved merge conflicts in the index: staging one would commit its markers as resolved. */
export function assertNoUnmergedPaths(root: string, rel: string[]): void {
  const unmerged = unmergedPaths(root, rel);
  if (unmerged.length) {
    const list = `${unmerged.slice(0, 10).join(', ')}${unmerged.length > 10 ? ', ...' : ''}`;
    throw opError('commit_paths_unmerged', `${unmerged.length} named file(s) still have unresolved merge conflicts in the index: ${list}.`,
      `Nothing was staged or committed. Resolve each file first with the user: edit out the conflict markers, keeping the changes from both sides that belong in the file (one side may be a write gbrain made), and mark it resolved with git add -- <file>. Then rerun the commit. git ls-files -u -- <file> prints nothing once it is resolved.`,
      { detail: JSON.stringify({ paths: unmerged }), fix: { ask_user: true, consent: [], actor: 'user', requires_exclusive: false,
        argv: ['git', '-C', root, 'diff', '--', ...literalPathspecs(unmerged)],
        why: 'Shows the conflict in each file; committing now would publish the conflict markers as the file content.',
        user_message: `These files still have unresolved merge conflicts (${list}), for example after a merge, rebase or stash pop that stopped on a conflict. Resolve each one keeping the changes from both sides that belong in the file (one side may be a write gbrain made), mark it resolved with git add, then commit again?`,
        verify: { argv: ['git', '-C', root, 'ls-files', '-u', '--', ...literalPathspecs(unmerged)] },
        docs: 'docs/guides/shared-checkout-git.md#outcomes' } });
  }
}