backnotprop__plannotator/packages/shared/generated-files.ts

/**
 * Generated-file detection for code review (#1317).
 *
 * Two layers, matching the GitHub linguist / GitLab semantics:
 *
 *  1. **Built-in name defaults** (`DEFAULT_GENERATED_PATTERNS`) — lockfiles,
 *     minified assets, and source maps are generated by their NAME alone, no
 *     git needed. Matched against the path's last segment only, so a
 *     directory named `bun.lock` never marks the files inside it.
 *  2. **Explicit `.gitattributes`** — wins in BOTH directions.
 *     `linguist-generated` / `linguist-generated=true` marks any file;
 *     `-linguist-generated` / `linguist-generated=false` UN-marks a file even
 *     when it is on the built-in list; `unspecified` falls through to the
 *     built-in defaults.
 *
 * Attribute resolution deliberately goes through git's own machinery
 * (`git check-attr`) instead of a hand-rolled `.gitattributes` parser, so
 * stacked and negated rules (per-directory files, `$GIT_DIR/info/attributes`)
 * behave exactly as git resolves them. One `--stdin -z` invocation covers
 * every path — never a per-file subprocess — and it is bounded by a timeout
 * because it sits on the blocking `/api/diff` path.
 *
 * Best-effort by design: any attribute-lookup failure (git missing, not a
 * work tree, non-zero exit, unparsable output, timeout) leaves the name-based
 * defaults standing — name matching needs no git. Attributes are read from
 * the working tree at the review cwd, git's default resolution.
 *
 * Runtime-agnostic like review-core (Pi consumes a build-time copy via
 * vendor.sh).
 */

import type { ReviewGitRuntime } from "./review-core";

export const GENERATED_ATTRIBUTE = "linguist-generated";

/** Same bound as review-core's stdin-driven git callers (`cat-file --batch-check`). */
const CHECK_ATTR_TIMEOUT_MS = 5000;

/**
 * Built-in name-based generated defaults — files GitHub's linguist collapses
 * without any `.gitattributes`. Exact entries match a path's last segment
 * verbatim; `*.`-prefixed entries match by extension suffix (at least one
 * character before the suffix, so a bare `.min.js` dotfile does not match).
 * Explicit `.gitattributes` always refines this list in both directions.
 */
export const DEFAULT_GENERATED_PATTERNS: readonly string[] = [
  // JavaScript ecosystems
  "package-lock.json",
  "npm-shrinkwrap.json",
  "yarn.lock",
  "pnpm-lock.yaml",
  "bun.lock",
  "bun.lockb",
  // Other language ecosystems
  "Cargo.lock",
  "Gemfile.lock",
  "composer.lock",
  "poetry.lock",
  "uv.lock",
  "Pipfile.lock",
  "go.sum",
  "flake.lock",
  "packages.lock.json",
  // Build artifacts
  "*.min.js",
  "*.min.css",
  "*.map",
];

const DEFAULT_EXACT_NAMES = new Set(
  DEFAULT_GENERATED_PATTERNS.filter((p) => !p.startsWith("*.")),
);
const DEFAULT_SUFFIXES = DEFAULT_GENERATED_PATTERNS.filter((p) =>
  p.startsWith("*."),
).map((p) => p.slice(1)); // "*.min.js" -> ".min.js"

/**
 * Does the path's LAST segment match a built-in generated default? Pure and
 * git-free, so it also serves the non-git degrade modes (piped patches,
 * workspace multi-repo folder-prefixed paths, PR worktrees, jj, GitButler,
 * P4) where attribute lookup is unavailable.
 */
export function isDefaultGeneratedPath(path: string): boolean {
  const name = path.slice(path.lastIndexOf("/") + 1);
  if (name.length === 0) return false;
  if (DEFAULT_EXACT_NAMES.has(name)) return true;
  return DEFAULT_SUFFIXES.some(
    (suffix) => name.length > suffix.length && name.endsWith(suffix),
  );
}

/**
 * Name-based detection alone — the built-in defaults with no attribute
 * refinement. Deduplicated, input order preserved.
 */
export function detectGeneratedFilesByName(paths: string[]): string[] {
  const unique = [...new Set(paths.filter((p) => p.length > 0))];
  return unique.filter(isDefaultGeneratedPath);
}

/**
 * `git check-attr -z` emits NUL-separated triples: path, attribute name,
 * value. A bare `linguist-generated` reports `set`, `=true` reports `true`;
 * both mark the file. `unset` (negated with `-`) and `false` explicitly
 * UN-mark it — overriding the built-in defaults. `unspecified` (or any other
 * value) expresses no opinion and falls through to the defaults.
 */
export function parseCheckAttrStates(
  stdout: string,
): Map<string, "set" | "unset" | "unspecified"> {
  const tokens = stdout.split("\0");
  const states = new Map<string, "set" | "unset" | "unspecified">();
  for (let i = 0; i + 2 < tokens.length; i += 3) {
    const [path, attribute, value] = [tokens[i], tokens[i + 1], tokens[i + 2]];
    if (attribute !== GENERATED_ATTRIBUTE) continue;
    if (value === "set" || value === "true") states.set(path, "set");
    else if (value === "unset" || value === "false") states.set(path, "unset");
    else states.set(path, "unspecified");
  }
  return states;
}

/**
 * Resolve which of `paths` count as generated: built-in name defaults first,
 * then one `git check-attr` subprocess whose explicit set/unset answers win
 * in both directions (`unspecified` keeps the default). Paths must be
 * repo-relative (the forward-slash paths a parsed unified diff yields).
 * Returns the generated subset in input order (deduplicated); an attribute
 * lookup failure leaves the name-based defaults standing.
 */
export async function detectGeneratedFiles(
  runtime: ReviewGitRuntime,
  cwd: string | undefined,
  paths: string[],
): Promise<string[]> {
  const unique = [...new Set(paths.filter((p) => p.length > 0))];
  if (unique.length === 0) return [];
  const marked = new Set(unique.filter(isDefaultGeneratedPath));
  try {
    const result = await runtime.runGit(
      ["check-attr", "--stdin", "-z", GENERATED_ATTRIBUTE],
      {
        cwd,
        // NUL-terminated input pairs with -z output; paths with spaces,
        // quotes, or newlines round-trip without any quoting layer.
        stdin: unique.join("\0") + "\0",
        timeoutMs: CHECK_ATTR_TIMEOUT_MS,
        interaction: "forbid",
      },
    );
    if (result.exitCode === 0 && !result.truncated) {
      for (const [path, state] of parseCheckAttrStates(result.stdout)) {
        if (state === "set") marked.add(path);
        else if (state === "unset") marked.delete(path);
        // unspecified: no opinion — the built-in default stands.
      }
    }
  } catch {
    // Attribute refinement unavailable — the name-based defaults stand.
  }
  // Report in input order so the sidecar is deterministic for a given diff.
  return unique.filter((p) => marked.has(p));
}