OpenAI's Codex Security CLI and TypeScript SDK for finding, validating, and fixing security vulnerabilities. npm: https://www.npmjs.com/package/@openai/codex-security
TypeScript ai-securityapplication-securityclicode-scanningcodexcodex-securitycybersecuritydevsecopsnodejsnpmopenaisdksecuritytypescriptvulnerability-scanning
import { isNonEmptyString } from "./value.js";
import { isUtf8 } from "node:buffer";
import { execFile as execFileCallback } from "node:child_process";
import { realpathSync, type Stats } from "node:fs";
import {
copyFile,
lstat,
mkdtemp,
readFile,
realpath,
rm,
stat,
} from "node:fs/promises";
import { homedir, tmpdir } from "node:os";
import {
basename,
dirname,
isAbsolute,
join,
relative,
resolve,
sep,
} from "node:path";
import { promisify } from "node:util";
import { InvalidTargetError, abortReason, errorMessage } from "./errors.js";
import {
resolveTrustedExecutable,
type TrustedExecutable,
} from "./trusted-executable.js";
import { windowsUnsafePathComponent } from "./windows-path.js";
import type { ScanMode } from "./scan-modes.js";
export type { ScanMode } from "./scan-modes.js";
const execFile = promisify(execFileCallback);
export const UNSUPPORTED_GIT_ENVIRONMENT: ReadonlySet<string> = new Set([
"GIT_DIR",
"GIT_WORK_TREE",
"GIT_INDEX_FILE",
"GIT_OBJECT_DIRECTORY",
"GIT_ALTERNATE_OBJECT_DIRECTORIES",
"GIT_COMMON_DIR",
"GIT_REPLACE_REF_BASE",
]);
const GIT_REPOSITORY_ENVIRONMENT = new Set([
...UNSUPPORTED_GIT_ENVIRONMENT,
"GIT_CEILING_DIRECTORIES",
"GIT_DISCOVERY_ACROSS_FILESYSTEM",
"GIT_GRAFT_FILE",
"GIT_IMPLICIT_WORK_TREE",
"GIT_NAMESPACE",
"GIT_NO_REPLACE_OBJECTS",
"GIT_PREFIX",
"GIT_SHALLOW_FILE",
]);
export type DiffTargetKind = "refs" | "working_tree";
export interface DiffTargetOptions {
kind: DiffTargetKind;
base: string;
head?: string;
}
export class DiffTarget {
readonly #brand = "DiffTarget";
public readonly kind: DiffTargetKind;
public readonly base: string;
public readonly head?: string;
public constructor(options: DiffTargetOptions) {
void this.#brand;
this.kind = options.kind;
this.base = options.base;
this.head = options.head;
requireValidDiffTarget(this);
Object.freeze(this);
}
public static refs({
base,
head = "HEAD",
}: {
base: string;
head?: string;
}): DiffTarget {
return new DiffTarget({ kind: "refs", base, head });
}
public static workingTree({
base = "HEAD",
}: { base?: string } = {}): DiffTarget {
return new DiffTarget({ kind: "working_tree", base });
}
}
function requireValidDiffTarget(target: DiffTargetOptions): void {
if (target.kind !== "refs" && target.kind !== "working_tree") {
throw new InvalidTargetError(
`Unsupported diff target kind: ${String(target.kind)}`,
);
}
if (typeof target.base !== "string" || target.base.length === 0) {
throw new InvalidTargetError("The diff base ref must be non-empty.");
}
if (
target.kind === "refs" &&
(typeof target.head !== "string" || target.head.length === 0)
) {
throw new InvalidTargetError(
"Git diff refs must include a non-empty head ref.",
);
}
if (target.kind === "working_tree" && target.head !== undefined) {
throw new InvalidTargetError(
"Working-tree targets cannot specify a head ref.",
);
}
}
export type ScanTarget = "repository" | DiffTarget | readonly string[];
export type NormalizedTargetKind =
"repository" | "paths" | "refs" | "working_tree";
export interface NormalizedTarget {
kind: NormalizedTargetKind;
paths: readonly string[];
base?: string;
head?: string;
baseRef?: string;
headRef?: string;
}
export async function normalizeRepository(
repository: string,
signal?: AbortSignal,
): Promise<string> {
const candidate = resolveRepositoryPath(repository);
requirePortableWindowsRepositoryPath(candidate);
let resolved: Buffer;
try {
resolved = await abortable(
() => realpath(candidate, { encoding: "buffer" }),
signal,
);
if (!(await abortable(() => lstat(resolved), signal)).isDirectory()) {
throw new Error("not a directory");
}
} catch (error) {
throwIfAborted(signal);
throw new InvalidTargetError(
`Repository is not a directory: ${candidate}`,
{
cause: error,
},
);
}
requireUtf8Path("Repository path", candidate, resolved);
const canonical = resolved.toString();
requirePortableWindowsRepositoryPath(canonical);
return canonical;
}
export function resolveRepositoryPath(
repository: string,
directory = process.cwd(),
): string {
requireUtf8Path("Repository path", repository);
return resolveTargetPath(expandHome(repository), directory);
}
/** Preserve filesystem resolution of symlink/.. paths on POSIX. */
export function resolveTargetPath(
value: string,
directory = process.cwd(),
): string {
if (sep === "\\") return resolve(directory, value);
const base = isAbsolute(directory)
? directory
: `${process.cwd()}/${directory}`;
const absolute = isAbsolute(value) ? value : `${base}/${value}`;
const parts = absolute
.split("/")
.filter((part) => part !== "" && part !== ".");
return `/${parts.join("/")}`;
}
function requireUtf8Path(
label: "Repository path" | "Path target",
value: string,
resolved?: Buffer,
): void {
if (resolved === undefined ? !value.isWellFormed() : !isUtf8(resolved)) {
throw new InvalidTargetError(
`${label} cannot be represented as UTF-8: ${value}`,
);
}
}
function requirePortableWindowsRepositoryPath(path: string): void {
if (process.platform !== "win32") return;
const ambiguous = windowsUnsafePathComponent(path);
if (ambiguous !== undefined) {
throw new InvalidTargetError(
`Repository paths must not contain Windows-ambiguous components: ${ambiguous}`,
);
}
}
type ReadWorktreeGit = (
repository: string,
args: readonly string[],
signal?: AbortSignal,
) => Promise<string>;
export async function enclosingGitWorktreeRoot(
repository: string,
signal?: AbortSignal,
options: { requireIfPresent?: boolean; readGit?: ReadWorktreeGit } = {},
): Promise<string | null> {
const strict = options.requireIfPresent === true;
const readGit = options.readGit ?? gitOutput;
const markerRoot = strict
? await gitMarkerRoot(repository, signal, "nearest")
: null;
let canonicalRoot: string;
try {
if (strict) {
if (
(await readGit(
repository,
["rev-parse", "--is-inside-git-dir"],
signal,
)) === "true"
) {
throw new InvalidTargetError(
"The selected path is inside Git metadata. Select a worktree directory instead.",
);
}
if (markerRoot === null) return null;
}
const root = await readGit(
repository,
["rev-parse", "--show-toplevel"],
signal,
);
canonicalRoot = await abortable(() => realpath(root), signal);
} catch (error) {
throwIfAborted(signal);
if (strict && error instanceof InvalidTargetError) throw error;
if (markerRoot !== null) {
throw new InvalidTargetError(
`Could not determine the Git worktree root. Check that Git is installed and the checkout is accessible. ${errorMessage(error)}`,
{ cause: error },
);
}
return null;
}
if (
markerRoot !== null &&
relative(
await abortable(() => realpath(markerRoot), signal),
canonicalRoot,
) !== ""
) {
throw new InvalidTargetError(
"Git's worktree root does not match the selected checkout's .git marker. Select the intended checkout explicitly or fix its Git configuration.",
);
}
if (markerRoot !== null)
await requireGitWorktreeBinding(canonicalRoot, signal, readGit);
return canonicalRoot;
}
export async function enclosingGitWorktreeRoots(
repository: string,
signal?: AbortSignal,
): Promise<string[]> {
const roots: string[] = [];
let directory = repository;
for (;;) {
const root = await enclosingGitWorktreeRoot(directory, signal, {
requireIfPresent: true,
});
if (root === null) return roots;
roots.push(root);
const parent = dirname(root);
if (parent === root) return roots;
directory = parent;
}
}
export async function isGitMetadataDirectory(
repository: string,
signal?: AbortSignal,
): Promise<boolean> {
const metadata = async (name: string, followLinks = false) =>
await (followLinks ? stat : lstat)(join(repository, name)).catch(
nullIfMissingPath,
);
const head = await metadata("HEAD");
if (head === null) {
// A common directory can outlive its main worktree's HEAD. Require both
// Git storage directories and its format declaration, not names alone.
if (!(await metadata("config", true))?.isFile()) return false;
const [objects, refs] = await Promise.all([
metadata("objects", true),
metadata("refs", true),
]);
if (!objects?.isDirectory() || !refs?.isDirectory()) return false;
try {
const version = await gitOutput(
repository,
[
"config",
"--no-includes",
"--file",
join(repository, "config"),
"--type=int",
"--get",
"core.repositoryformatversion",
],
signal,
{ LC_ALL: "C" },
);
return /^\d+$/u.test(version);
} catch (error) {
throwIfAborted(signal);
// Application folders can share these filenames without using Git's
// config format. Missing or invalid declarations do not identify metadata.
if (
error instanceof Error &&
"code" in error &&
(error.code === 1 ||
(error.code === 128 &&
"stderr" in error &&
typeof error.stderr === "string" &&
/fatal: bad (?:config line|numeric config value)/u.test(
error.stderr,
)))
)
return false;
throw error;
}
}
if (!head.isFile() && !head.isSymbolicLink()) return false;
try {
// Resolve from outside the candidate so Git does not load its configuration.
const directory = await gitOutput(
repository,
["rev-parse", "--resolve-git-dir", repository],
signal,
{ LC_ALL: "C" },
dirname(repository),
);
return (
relative(await realpath(directory), await realpath(repository)) === ""
);
} catch (error) {
throwIfAborted(signal);
if (
error instanceof Error &&
"code" in error &&
error.code === 128 &&
"stderr" in error &&
typeof error.stderr === "string" &&
error.stderr.trimEnd() === `fatal: not a gitdir '${repository}'`
)
return false;
throw error;
}
}
export async function gitMetadataDirectories(
repository: string,
signal?: AbortSignal,
options: { includeLocalObjects?: boolean; readGit?: ReadWorktreeGit } = {},
): Promise<[string, string, ...string[]]> {
const readGit = options.readGit ?? gitOutput;
const [directory, commonDirectory] = await Promise.all([
readGit(repository, ["rev-parse", "--absolute-git-dir"], signal),
readGit(repository, ["rev-parse", "--git-common-dir"], signal),
]);
const roots = await Promise.all([
abortable(() => realpath(resolve(repository, directory)), signal),
abortable(() => realpath(resolve(repository, commonDirectory)), signal),
]);
return [...roots, ...(await gitObjectDirectories(roots, signal, options))];
}
function gitAlternatePaths(contents: Buffer): string[] {
const text = contents.toString("latin1").split("\0", 1)[0]!;
const paths: string[] = [];
const utf8 = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
for (let offset = 0; offset < text.length;) {
const newline = text.indexOf("\n", offset);
let end = newline === -1 ? text.length : newline;
let path = text.slice(offset, end);
if (path.startsWith("#")) path = "";
const quoted = /^"(?:[^"\\]|\\[\s\S])*"/u.exec(text.slice(offset))?.[0];
if (quoted !== undefined) {
try {
// Git uses C-quoted bytes; JSON handles the shared escapes after conversion.
path = JSON.parse(
quoted.replace(
/\\(?:[0-3][0-7]{2}|[\s\S])|[\u0000-\u001f]/gu,
(escape) => {
if (/^\\[btnfr\\"]$/u.test(escape)) return escape;
const byte =
escape[0] !== "\\"
? escape.charCodeAt(0)
: escape === "\\a"
? 7
: escape === "\\v"
? 11
: /^\\[0-3][0-7]{2}$/u.test(escape)
? Number.parseInt(escape.slice(1), 8)
: undefined;
if (byte === undefined)
throw new SyntaxError("Invalid Git path escape.");
return `\\u${byte.toString(16).padStart(4, "0")}`;
},
),
) as string;
end = offset + quoted.length;
} catch (error) {
if (!(error instanceof SyntaxError)) throw error;
// Git treats malformed quoting as an unquoted pathname.
}
}
if (path !== "") {
try {
paths.push(utf8.decode(Buffer.from(path, "latin1")));
} catch (error) {
throw new InvalidTargetError("Git object-store paths must use UTF-8.", {
cause: error,
});
}
}
offset = end + 1;
}
return paths;
}
export async function gitObjectDirectories(
metadataDirectories: readonly string[],
signal?: AbortSignal,
options: { includeLocalObjects?: boolean } = {},
): Promise<string[]> {
const pending = metadataDirectories.map((path) => join(path, "objects"));
const visited = new Set<string>();
const canonical = (path: string): string | null => {
try {
return realpathSync.native(path);
} catch (error) {
if (
["ENOENT", "ENOTDIR"].includes(
(error as NodeJS.ErrnoException).code ?? "",
)
)
return null;
throw error;
}
};
while (pending.length > 0) {
throwIfAborted(signal);
const directory = canonical(pending.pop()!);
if (directory === null || visited.has(directory)) continue;
if (!(await stat(directory)).isDirectory()) continue;
visited.add(directory);
const contents = await readFile(join(directory, "info", "alternates"), {
signal,
}).catch(nullIfMissingPath);
if (contents === null) continue;
for (const path of gitAlternatePaths(contents)) {
throwIfAborted(signal);
pending.push(resolve(directory, path));
}
}
return [...visited].filter(
(path) =>
options.includeLocalObjects ||
metadataDirectories.every((root) =>
relativePathIsOutside(relative(root, path)),
),
);
}
async function requireGitWorktreeBinding(
repository: string,
signal: AbortSignal | undefined,
readGit: ReadWorktreeGit,
): Promise<void> {
let cause: unknown;
try {
const [directory, commonDirectory] = await gitMetadataDirectories(
repository,
signal,
{ readGit },
);
if (
[directory, commonDirectory].every(
(path) => !relativePathIsOutside(relative(repository, path)),
)
)
return;
if (relative(directory, commonDirectory) === "") {
// The toplevel check already verified the configured worktree path.
if (
await readGit(repository, ["config", "--get", "core.worktree"], signal)
)
return;
} else {
// A copied backlink is not registration in the common Git directory.
const worktreesDirectory = await abortable(
() => realpath(join(commonDirectory, "worktrees")),
signal,
);
if (relative(worktreesDirectory, dirname(directory)) === "") {
const contents = await abortable(
() => readFile(join(directory, "gitdir"), "utf8"),
signal,
);
const backlink = resolve(directory, contents.trimEnd());
if (
basename(backlink) === ".git" &&
relative(
repository,
await abortable(() => realpath(dirname(backlink)), signal),
) === ""
)
return;
}
}
} catch (error) {
throwIfAborted(signal);
cause = error;
}
throw new InvalidTargetError(
"Git metadata is not bound to the selected checkout. Select the intended checkout, repair a moved worktree with git worktree repair, or set core.worktree for a separate Git directory you own.",
{ cause },
);
}
export function relativePathIsOutside(path: string): boolean {
return path === ".." || path.startsWith(`..${sep}`) || isAbsolute(path);
}
export function validatedGitEnvironment(
environment: Readonly<Record<string, string | undefined>> = process.env,
): void {
const unsupported = Object.entries(environment).find(
([name, value]) =>
UNSUPPORTED_GIT_ENVIRONMENT.has(name.toUpperCase()) &&
value !== undefined &&
value.trim() !== "",
);
if (unsupported !== undefined) {
throw new InvalidTargetError(
`${unsupported[0]} is not supported for Codex Security scans.`,
);
}
}
export async function normalizeTarget(
repository: string,
target: ScanTarget,
signal?: AbortSignal,
): Promise<NormalizedTarget> {
const root = await normalizeRepository(repository, signal);
throwIfAborted(signal);
if (target === "repository") {
return { kind: "repository", paths: [] };
}
if (target instanceof DiffTarget) {
requireValidDiffTarget(target);
await requireGitRepository(root, signal);
const base = await resolveGitRef(root, target.base, signal);
const kind = target.kind === "refs" ? "refs" : "working_tree";
const head = kind === "refs" ? target.head : "HEAD";
if (!isNonEmptyString(head)) {
throw new InvalidTargetError(
"Git diff refs must include a non-empty head ref.",
);
}
return {
kind,
paths: [],
base,
head: await resolveGitRef(root, head, signal),
baseRef: target.base,
headRef: head,
};
}
if (!Array.isArray(target)) {
throw new InvalidTargetError(
"Scan target must be 'repository', a DiffTarget, or an array of paths.",
);
}
if (target.length === 0) {
throw new InvalidTargetError(
"A path scan target must contain at least one path.",
);
}
const paths = new Set<string>();
for (const value of target) {
throwIfAborted(signal);
if (typeof value !== "string") {
throw new InvalidTargetError(
"Path scan targets must contain only strings.",
);
}
if (value.length === 0) {
throw new InvalidTargetError(
"Path scan targets must not contain an empty path.",
);
}
requireUtf8Path("Path target", value);
const candidate = resolveTargetPath(expandHome(value), root);
let canonical: string;
try {
// Some runtimes cannot canonicalize special files to filesystem paths.
requireScanPathType(
value,
await abortable(() => stat(candidate), signal),
);
const resolved = await abortable(
() => realpath(candidate, { encoding: "buffer" }),
signal,
);
canonical = resolved.toString();
if (!isAbsolute(canonical)) {
throw new InvalidTargetError(`Could not resolve path target: ${value}`);
}
requireScanPathType(
value,
await abortable(() => lstat(resolved), signal),
);
requireUtf8Path("Path target", value, resolved);
} catch (error) {
throwIfAborted(signal);
if (error instanceof InvalidTargetError) throw error;
throw new InvalidTargetError(`Path target does not exist: ${value}`, {
cause: error,
});
}
const relativePath = relative(root, canonical);
if (relativePathIsOutside(relativePath)) {
throw new InvalidTargetError(
`Path target is outside the repository: ${value}`,
);
}
if (
process.platform === "win32" &&
relativePath.split(sep).some((part) => part.includes(":"))
) {
throw new InvalidTargetError(
`Path target contains an unsupported colon component: ${value}`,
);
}
const normalized = relativePath.split(sep).join("/") || ".";
paths.add(normalized);
}
return { kind: "paths", paths: [...paths] };
}
function requireScanPathType(value: string, metadata: Stats): void {
if (!metadata.isFile() && !metadata.isDirectory()) {
throw new InvalidTargetError(
`Path target is not a regular file or directory: ${value}`,
);
}
}
export async function validateCommittedDiffCheckout(
repository: string,
target: NormalizedTarget,
signal?: AbortSignal,
): Promise<void> {
if (target.kind !== "refs") return;
const checkoutHead = await resolveGitRef(repository, "HEAD", signal);
if (checkoutHead !== target.head) {
throw new InvalidTargetError(
`Committed-diff scans require the repository checkout to match the requested head revision. Checkout HEAD is ${checkoutHead}; requested head is ${target.head}. Check out the requested head and retry.`,
);
}
const status = await gitOutput(
repository,
["status", "--porcelain=v1", "--untracked-files=all"],
signal,
);
if (status.length !== 0) {
throw new InvalidTargetError(
"Committed-diff scans require a clean repository checkout. Commit, stash, or remove local changes and retry. Use `git stash --include-untracked` to stash untracked files.",
);
}
const tracked = (
await gitOutput(repository, ["ls-files", "-v", "-z"], signal)
).split("\0");
if (tracked.some((entry) => /^[Ss] /u.test(entry))) {
throw new InvalidTargetError(
"Committed-diff scans require a full repository checkout. Sparse checkouts are not supported; materialize skipped tracked files and retry.",
);
}
if (tracked.some((entry) => entry.startsWith("h "))) {
await verifyAssumedUnchangedFiles(repository, signal);
}
}
async function verifyAssumedUnchangedFiles(
repository: string,
signal?: AbortSignal,
): Promise<void> {
const index = await gitOutput(
repository,
["rev-parse", "--path-format=absolute", "--git-path", "index"],
signal,
);
// Git changes to the repository before resolving GIT_INDEX_FILE, even when TMPDIR is relative.
const directory = await mkdtemp(
join(await realpath(tmpdir()), "codex-security-git-index-"),
);
const copy = join(directory, "index");
try {
// Git refreshes stat data and flags. Keep that write and any hooks out of the checkout.
await copyFile(index, copy);
await gitOutput(
repository,
[
"-c",
`core.hooksPath=${directory}`,
"-c",
"core.splitIndex=false",
"update-index",
"--really-refresh",
],
signal,
{ GIT_INDEX_FILE: copy },
);
} catch (error) {
if (error instanceof Error && "code" in error && error.code === 1) {
throw new InvalidTargetError(
"Committed-diff scans require a clean repository checkout. A tracked file marked assume-unchanged has changed on disk.",
{ cause: error },
);
}
throw error;
} finally {
await rm(directory, { recursive: true, force: true });
}
}
export function validateMode(target: NormalizedTarget, mode: ScanMode): void {
if (mode !== "standard" && mode !== "deep") {
throw new InvalidTargetError(`Unsupported scan mode: ${String(mode)}`);
}
if (
mode === "deep" &&
(target.kind === "refs" || target.kind === "working_tree")
) {
throw new InvalidTargetError(
"Deep mode supports repository and path targets only.",
);
}
}
export async function repositoryRevision(
repository: string,
signal?: AbortSignal,
): Promise<string | null> {
try {
return await gitOutput(
repository,
["rev-parse", "--verify", "HEAD^{commit}"],
signal,
);
} catch {
throwIfAborted(signal);
return null;
}
}
async function requireGitRepository(
repository: string,
signal?: AbortSignal,
): Promise<void> {
let root: string;
try {
root = await gitOutput(
repository,
["rev-parse", "--show-toplevel"],
signal,
);
} catch (error) {
throwIfAborted(signal);
throw new InvalidTargetError(
`Diff targets require a Git repository: ${repository}. ${errorMessage(error)}`,
{
cause: error,
},
);
}
const canonicalRoot = await abortable(() => realpath(root), signal);
if (canonicalRoot !== repository) {
throw new InvalidTargetError(
`Diff target repository must be the Git worktree root: ${canonicalRoot}`,
);
}
}
async function resolveGitRef(
repository: string,
ref: string,
signal?: AbortSignal,
): Promise<string> {
try {
return await gitOutput(
repository,
["rev-parse", "--verify", "--end-of-options", `${ref}^{commit}`],
signal,
);
} catch (error) {
throwIfAborted(signal);
throw new InvalidTargetError(
`unknown Git ref: ${ref}. ${errorMessage(error)}`,
{ cause: error },
);
}
}
/** Read-only identity for matching saved history with an already selected host Git. */
export async function gitHistoryIdentity(
repository: string,
git: TrustedExecutable,
signal?: AbortSignal,
): Promise<{
commonDirectory: string | null;
origin: string | null;
relativePath: string | null;
}> {
const read = async (
args: readonly string[],
allowEmpty = false,
): Promise<string | null> => {
try {
const { stdout } = await execFile(
git.executable,
["-c", "core.fsmonitor=false", "-C", repository, ...args],
{
encoding: "utf8",
signal,
env: isolatedGitEnvironment(true, git.environment),
maxBuffer: Infinity,
},
);
const value = stdout.replace(
process.platform === "win32" ? /\r?\n$/u : /\n$/u,
"",
);
return value || (allowEmpty ? "" : null);
} catch {
throwIfAborted(signal);
return null;
}
};
const [commonDirectory, origin, relativePath] = await Promise.all([
read(["rev-parse", "--path-format=absolute", "--git-common-dir"]),
read(["remote", "get-url", "origin"]),
read(["rev-parse", "--show-prefix"], true),
]);
return { commonDirectory, origin, relativePath };
}
/** Resolve Git and its sanitized executable search path for a single selected checkout. */
export async function trustedGitCommand(
repository: string,
preserveConfiguration: boolean,
sourceEnvironment: NodeJS.ProcessEnv,
protectedRoots: string | readonly string[],
signal?: AbortSignal,
) {
const command = await resolveTrustedExecutable(
"git",
isolatedGitEnvironment(preserveConfiguration, sourceEnvironment),
[
(await gitMarkerRoot(repository, signal, "outermost")) ?? repository,
...(typeof protectedRoots === "string"
? [protectedRoots]
: protectedRoots),
],
);
if (!command) throw new Error("Git is not available on a trusted PATH.");
return command;
}
export function gitOutput(
repository: string,
args: readonly string[],
signal?: AbortSignal,
environment?: NodeJS.ProcessEnv,
workingDirectory?: string,
encoding?: "utf8",
protectedRoots?: string | readonly string[],
sourceEnvironment?: NodeJS.ProcessEnv,
): Promise<string>;
export function gitOutput(
repository: string,
args: readonly string[],
signal: AbortSignal | undefined,
environment: NodeJS.ProcessEnv | undefined,
workingDirectory: string | undefined,
encoding: "buffer",
protectedRoots?: string | readonly string[],
sourceEnvironment?: NodeJS.ProcessEnv,
): Promise<Buffer>;
export async function gitOutput(
repository: string,
args: readonly string[],
signal?: AbortSignal,
environment: NodeJS.ProcessEnv = {},
workingDirectory = repository,
encoding: "utf8" | "buffer" = "utf8",
protectedRoots: string | readonly string[] = [],
sourceEnvironment: NodeJS.ProcessEnv = process.env,
): Promise<string | Buffer> {
throwIfAborted(signal);
const command = await trustedGitCommand(
repository,
args[0] === "rev-parse" ||
(args[0] === "symbolic-ref" &&
args[1] === "--quiet" &&
args[2] === "HEAD" &&
args.length === 3) ||
(args[0] === "--exec-path" && args.length === 1) ||
args[0] === "config" ||
(args[0] === "fetch-pack" &&
args[1] === "--diag-url" &&
args.length === 3) ||
(args[0] === "ls-remote" &&
args[1] === "--get-url" &&
(args.length === 2 || (args[2] === "--" && args.length === 4))) ||
args[0] === "ls-files" ||
(args[0] === "remote" &&
(args.length === 1 ||
(args[1] === "get-url" &&
(args[2] === "--all" || args[2] === "--")))),
sourceEnvironment,
protectedRoots,
signal,
);
throwIfAborted(signal);
const { stdout } = await execFile(
command.executable,
["-c", "core.fsmonitor=false", "-C", workingDirectory, ...args],
{
encoding,
signal,
env: { ...command.environment, ...environment },
maxBuffer: Infinity,
},
);
if (typeof stdout !== "string") return stdout;
// Git writes remote URLs to binary stdout even on Windows. Only the final LF
// is a delimiter; a preceding CR belongs to the configured URL.
const remoteUrl = args[0] === "remote" && args[1] === "get-url";
return stdout.replace(
process.platform === "win32" && !remoteUrl ? /\r?\n$/u : /\n$/u,
"",
);
}
function unavailableGitMarkerPath(
error: unknown,
search: "nearest" | "outermost",
): boolean {
const { code } = error as NodeJS.ErrnoException;
return (
code === "ENOENT" ||
code === "ENOTDIR" ||
(search === "outermost" &&
["EACCES", "EPERM", "ELOOP", "ENAMETOOLONG"].includes(code ?? ""))
);
}
/** Bound repository-supplied document links to the selected checkout or directory. */
export async function documentSourceRoot(
repository: string,
signal?: AbortSignal,
): Promise<string> {
return (
(await gitMarkerRoot(repository, signal, "nearest")) ??
(await realpath(repository))
);
}
export async function gitMarkerRoot(
repository: string,
signal: AbortSignal | undefined,
search: "nearest" | "outermost",
): Promise<string | null> {
let candidate = resolveTargetPath(repository);
let current: string;
while (true) {
try {
const canonical = await abortable(() => realpath(candidate), signal);
current = (await lstat(canonical)).isDirectory()
? canonical
: dirname(canonical);
break;
} catch (error) {
// Stale or inaccessible descendants still belong to their accessible checkout ancestors.
throwIfAborted(signal);
if (search !== "outermost" || !unavailableGitMarkerPath(error, search))
throw error;
const parent = dirname(candidate);
if (parent === candidate) throw error;
candidate = parent;
}
}
return await walkGitMarkers(current, signal, search);
}
/** Protect both the stored path's checkout and its resolved destination. */
export async function gitProtectionRoots(
repository: string,
signal?: AbortSignal,
): Promise<string[]> {
const roots = await Promise.all([
gitMarkerRoot(repository, signal, "outermost"),
walkGitMarkers(resolve(repository), signal, "outermost"),
]);
return [...new Set(roots.filter((root): root is string => root !== null))];
}
async function walkGitMarkers(
current: string,
signal: AbortSignal | undefined,
search: "nearest" | "outermost",
): Promise<string | null> {
let root: string | null = null;
while (true) {
throwIfAborted(signal);
try {
await lstat(join(current, ".git"));
if (search === "nearest") return current;
root = current;
} catch (error) {
throwIfAborted(signal);
if (!unavailableGitMarkerPath(error, search)) throw error;
}
const parent = dirname(current);
if (parent === current) return root;
current = parent;
}
}
function isolatedGitEnvironment(
preserveGitConfiguration: boolean,
source: Readonly<Record<string, string | undefined>> = process.env,
): NodeJS.ProcessEnv {
const environment = { ...source };
for (const name of Object.keys(environment)) {
const normalized = name.toUpperCase();
if (
GIT_REPOSITORY_ENVIRONMENT.has(normalized) ||
normalized === "GIT_ALLOW_PROTOCOL" ||
(!preserveGitConfiguration && normalized.startsWith("GIT_"))
) {
delete environment[name];
}
}
environment["GIT_ALLOW_PROTOCOL"] = "";
return environment;
}
export async function abortable<T>(
operation: () => Promise<T>,
signal?: AbortSignal,
): Promise<T> {
if (signal === undefined) return await operation();
throwIfAborted(signal);
return await new Promise<T>((resolvePromise, reject) => {
const onAbort = (): void => reject(abortReason(signal));
signal.addEventListener("abort", onAbort, { once: true });
const finish =
<U>(settle: (value: U) => void) =>
(value: U): void => {
signal.removeEventListener("abort", onAbort);
settle(value);
};
void Promise.resolve()
.then(() => {
throwIfAborted(signal);
return operation();
})
.then(finish(resolvePromise), finish(reject));
});
}
function throwIfAborted(signal?: AbortSignal): void {
if (signal?.aborted === true) throw abortReason(signal);
}
function expandHome(value: string): string {
if (value === "~") {
return homedir();
}
if (value.startsWith("~/") || value.startsWith("~\\")) {
const separators =
sep === "/" && value.startsWith("~/") ? /^\/+/ : /^[/\\]+/;
const suffix = value.slice(2).replace(separators, "");
const home = homedir();
if (process.platform === "win32") return resolve(home, suffix);
return home === "" ? resolveTargetPath(suffix) : `${home}${sep}${suffix}`;
}
return value;
}
/** @internal */
export function nullIfMissingFile(error: NodeJS.ErrnoException): null {
if (error.code === "ENOENT") return null;
throw error;
}
/** @internal */
export function nullIfMissingPath(error: NodeJS.ErrnoException): null {
if (error.code === "ENOENT" || error.code === "ENOTDIR") return null;
throw error;
}