@nurix/nustack 0.23.20 → 0.23.22

package/dist/commands/context.js

@@ -0,0 +1,78 @@
+import { readFileSync } from "node:fs";
+import { printJsonSuccess } from "../lib/json_output.js";
+import { composePack, CONTEXT_EXIT_NO_REGISTER } from "../lib/context/compose.js";
+import { openGraphForCommand, readCheckoutHead } from "../lib/context/graph.js";
+import { docsRootOf, readRegister, REGISTER_SUBDIR } from "../lib/context/register.js";
+import { CONTEXT_PACK_MAX_TOKENS, SECTION_NAMES } from "../lib/context/render.js";
+import { resolveProjectRoot } from "../lib/graph/projectRoot.js";
+export function diffPaths(diff) {
+    const paths = [];
+    for (const match of diff.matchAll(/^\+\+\+ (?:b\/)?(.+)$/gm)) {
+        const file = (match[1] ?? "").trim();
+        if (file !== "/dev/null" && !paths.includes(file))
+            paths.push(file);
+    }
+    return paths;
+}
+function readDiff(source) {
+    return readFileSync(source === "-" ? 0 : source, "utf8");
+}
+function jsonData(pack) {
+    const sections = {};
+    for (const name of SECTION_NAMES)
+        sections[name] = pack.rendered.sections[name].map((line) => ({ label: line.label, text: line.text }));
+    return { exitCode: pack.exitCode, objects: pack.objects, sections, dropped: pack.rendered.dropped, tokens: pack.rendered.tokens };
+}
+export async function runContext(textParts, options, cwd = process.cwd()) {
+    if (options.hook === true) {
+        const { runContextHook } = await import("../lib/context/hook.js");
+        if ((await runContextHook()) === "deadline")
+            process.exit(0);
+        return;
+    }
+    const root = resolveProjectRoot(undefined, cwd);
+    const docsRoot = root === null ? "docs" : docsRootOf(root);
+    const register = root === null ? null : readRegister(root, docsRoot);
+    if (root === null || register === null) {
+        const where = `${docsRoot}/${REGISTER_SUBDIR.split("\\").join("/")}`;
+        const message = `no object register at ${where} — the context pack reads it; \`nustack graph\` answers structural questions without it`;
+        if (options.json === true) {
+            printJsonSuccess("context", { exitCode: CONTEXT_EXIT_NO_REGISTER, objects: [], sections: {}, dropped: [], tokens: 0, message });
+        }
+        else {
+            process.stderr.write(`${message}\n`);
+        }
+        process.exitCode = CONTEXT_EXIT_NO_REGISTER;
+        return;
+    }
+    const budget = options.budget === undefined ? CONTEXT_PACK_MAX_TOKENS : Number(options.budget);
+    if (!Number.isInteger(budget) || budget <= 0)
+        throw new Error(`--budget must be a positive integer, got "${options.budget}"`);
+    const paths = [...(options.path ?? []), ...(options.diff === undefined ? [] : diffPaths(readDiff(options.diff)))];
+    const graph = await openGraphForCommand(root, {
+        noRefresh: options.refresh === false,
+        onProgress: (line) => process.stderr.write(`${line}\n`),
+    });
+    try {
+        const pack = composePack({
+            root,
+            cwd,
+            register,
+            text: textParts.join(" "),
+            paths,
+            graph: graph.view,
+            graphReason: graph.reason,
+            docsRoot,
+            checkoutHead: readCheckoutHead(root),
+            budgetTokens: budget,
+        });
+        if (options.json === true)
+            printJsonSuccess("context", jsonData(pack));
+        else
+            process.stdout.write(`${pack.rendered.text}\n`);
+        process.exitCode = pack.exitCode;
+    }
+    finally {
+        graph.view?.close();
+    }
+}

package/dist/commands/gate.js

@@ -3,6 +3,8 @@ import path from "node:path";
 import { hasManagedHook, installManagedHook, removeManagedHook } from "../lib/agent/claudeHooks.js";
 import { readDesktopSettings } from "../lib/desktop_settings.js";
 import { loadOutlineLibrary } from "../lib/gate/outline.js";
+import { isRedirectOn } from "../lib/gate/redirect.js";
+import { resolveProjectRoot } from "../lib/graph/projectRoot.js";
 import { resolveThreshold } from "../lib/gate/settings.js";
 import { printJsonSuccess } from "../lib/json_output.js";
 import { readStoreVersion } from "../lib/local_store/database.js";
@@ -56,6 +58,7 @@ export async function readGateStatus() {
         thresholdSource,
         outline: library !== null && typeof library.outlineSource === "function" ? "tree-sitter" : "fallback",
         storeVersion: await readStoreVersion(),
+        redirect: isRedirectOn(resolveProjectRoot(process.env.CLAUDE_PROJECT_DIR, process.cwd())),
     };
 }
 export async function runGateStatus(options) {
@@ -71,5 +74,6 @@ export async function runGateStatus(options) {
         `Threshold: ${status.thresholdTokens} tokens (from ${status.thresholdSource})`,
         `Outline: ${status.outline}`,
         `Local store version: ${status.storeVersion ?? "no store"}`,
+        `Large-read redirect: ${status.redirect.isOn ? "on" : "off"} (from ${status.redirect.source})`,
     ].join("\n"));
 }

package/dist/index.js

@@ -5,6 +5,11 @@ if (command === "gate" && subcommand !== undefined && HOOK_SUBCOMMANDS.includes(
     const { runGateHook } = await import("./lib/gate/hook.js");
     await runGateHook(subcommand);
 }
+else if (command === "context" && process.argv.includes("--hook")) {
+    const { runContextHook } = await import("./lib/context/hook.js");
+    if ((await runContextHook()) === "deadline")
+        process.exit(0);
+}
 else if (command === "check" && process.argv.includes("--hook")) {
     const { runHookMode } = await import("./lib/harness/hookEntry.js");
     await runHookMode(process.argv[process.argv.indexOf("--hook") + 1] ?? "", process.argv.includes("--protection"));

package/dist/lib/context/compose.js

@@ -0,0 +1,269 @@
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { GRAPH_UNAVAILABLE_REASON } from "./graph.js";
+import { renderPack, emptySections } from "./render.js";
+import { extractTerms, isRegisterTerm, resolveObjects, resolvePaths } from "./resolve.js";
+import { findWriteSites, scanWriteSites, tableSymbols } from "./writers.js";
+export const CONTEXT_EXIT_OK = 0;
+export const CONTEXT_EXIT_NOTHING_RESOLVED = 3;
+export const CONTEXT_EXIT_NO_REGISTER = 4;
+export const CONTEXT_MAX_HOLES = 8;
+export const CARD_MAX_WRITERS = 8;
+const IMPACT_ROWS = 5;
+const TESTS_ROWS = 3;
+const WRITER_ANCHOR_PATHS = 2;
+const HEADER_LINES = 5;
+export const OBLIGATIONS_LINE = "none raised — the rules judge is not installed (program ruling R18)";
+export const JUDGE_LINE = "judge: not installed — exact matches only";
+export const REFUSALS_LINE = "refusals: not extracted — no refusal extractor is installed";
+function line(label, text, extra = {}) {
+    return { label, text, ...extra };
+}
+function grepDirOf(root) {
+    return existsSync(path.join(root, "packages")) ? "packages" : ".";
+}
+function labelOf(confidence) {
+    if (confidence === "certain")
+        return "CERTAIN";
+    if (confidence === "unresolved")
+        return "UNRESOLVED";
+    return "INFERRED";
+}
+function cardHeader(object) {
+    const scope = object.scope.length === 0 ? "unscoped" : object.scope.join(", ");
+    return `object ${object.name}  (${object.plane ?? "no plane"} · scope ${scope})`;
+}
+export function cardLines(object, writers, graphReason) {
+    const group = object.name;
+    const lines = [line("AUTHORED", cardHeader(object), { group })];
+    if (object.aliases.length > 0)
+        lines.push(line("AUTHORED", `aliases: ${object.aliases.join(", ")}`, { group }));
+    if (object.tables.length > 0)
+        lines.push(line("AUTHORED", `tables: ${object.tables.join(", ")}`, { group }));
+    if (object.oneLine !== null)
+        lines.push(line("AUTHORED", object.oneLine, { group }));
+    if (writers === null) {
+        lines.push(line("NOT KNOWN", graphReason ?? GRAPH_UNAVAILABLE_REASON, { group, role: "writer" }));
+    }
+    else if (object.tables.length > 0) {
+        if (writers.length === 0)
+            lines.push(line("INFERRED", `writers: no name-matched write site of ${object.tables.join(", ")}`, { group }));
+        for (const site of writers.slice(0, CARD_MAX_WRITERS)) {
+            lines.push(line("INFERRED", `writer ${site.path}:${site.line} ${site.verb} ${site.table}`, { group, role: "writer", paths: [site.path] }));
+        }
+    }
+    lines.push(line("UNRESOLVED", REFUSALS_LINE, { group }));
+    for (const claim of object.claims) {
+        const text = claim.type === "predicate" ? `claim ${claim.text} (not evaluated)` : `claim? ${claim.text}`;
+        lines.push(line("AUTHORED", text, { group, role: "claim" }));
+    }
+    return lines;
+}
+export function cardHoles(object, writers, dir) {
+    const group = object.name;
+    const holes = object.tables.map((table) => line("NOT KNOWN", `grep -rnE "(INTO|UPDATE|FROM) ${table}\\b" ${dir}`, { group }));
+    const writerFile = writers?.[0]?.path;
+    holes.push(line("NOT KNOWN", `grep -rnE "fail\\(c, [0-9]{3}" ${writerFile ?? dir}`, { group }));
+    return holes;
+}
+export function objectWriters(root, object, graph, scrutinised = []) {
+    const sites = [];
+    for (const table of object.tables) {
+        for (const site of findWriteSites(root, table, graph, scrutinised)) {
+            if (!sites.some((existing) => existing.path === site.path && existing.line === site.line))
+                sites.push(site);
+        }
+    }
+    return sites;
+}
+function answerRows(answer, fn, target, limit, skip) {
+    if (answer === null)
+        return [];
+    const lines = [];
+    for (const section of answer.sections) {
+        const label = labelOf(section.confidence);
+        if (section.rows.length === 0) {
+            lines.push(line(label, `${fn} ${target} — ${section.label}: none (${section.emptyMeans ?? "no rows"})`));
+            continue;
+        }
+        for (const row of section.rows) {
+            if (row.at !== undefined && skip.has(row.at))
+                continue;
+            const file = (row.at ?? row.text).replace(/:\d+$/, "");
+            const text = `${fn} ${target} — ${section.label}: ${row.text}${row.at !== undefined && row.at !== row.text ? ` ${row.at}` : ""}${row.note !== undefined ? ` (${row.note})` : ""}`;
+            lines.push(line(label, text, { paths: [file] }));
+        }
+    }
+    return lines.slice(0, limit);
+}
+function frontmatterStatus(root, doc) {
+    try {
+        const head = readFileSync(path.join(root, doc), "utf8").slice(0, 4_000);
+        const match = /^---\n([\s\S]*?)\n---/.exec(head);
+        const status = match === null ? null : /^status:\s*(.+)$/m.exec(match[1] ?? "");
+        return status === null ? "no status" : (status[1] ?? "").trim();
+    }
+    catch {
+        return "unreadable";
+    }
+}
+function documentsByObjects(root, docsRoot, names) {
+    if (names.length === 0)
+        return [];
+    let listing;
+    try {
+        listing = execFileSync("git", ["grep", "-l", "-E", "^objects:", "--", `${docsRoot}/**/*.md`, `${docsRoot}/*.md`], {
+            cwd: root,
+            stdio: ["ignore", "pipe", "ignore"],
+            encoding: "utf8",
+        });
+    }
+    catch {
+        return [];
+    }
+    const found = [];
+    for (const doc of listing.split("\n").filter((entry) => entry !== "")) {
+        let objectsLine = "";
+        try {
+            objectsLine = /^objects:(.*)$/m.exec(readFileSync(path.join(root, doc), "utf8").slice(0, 4_000))?.[1] ?? "";
+        }
+        catch {
+            continue;
+        }
+        for (const name of names) {
+            if (new RegExp(`(^|[^A-Za-z0-9_-])${name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}($|[^A-Za-z0-9_-])`).test(objectsLine)) {
+                found.push({ doc, object: name });
+            }
+        }
+    }
+    return found;
+}
+function headerPointers(root, docsRoot, file) {
+    try {
+        const head = readFileSync(path.join(root, file), "utf8").split("\n").slice(0, HEADER_LINES).join("\n");
+        const pattern = new RegExp(`${docsRoot.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}/[A-Za-z0-9_./-]+\\.md`, "g");
+        return [...new Set(head.match(pattern) ?? [])].filter((doc) => existsSync(path.join(root, doc)));
+    }
+    catch {
+        return [];
+    }
+}
+export function composePack(input) {
+    const { root, register, graph } = input;
+    const sections = emptySections();
+    const empty = {};
+    const dir = grepDirOf(root);
+    const terms = extractTerms(input.text);
+    const { resolved, missing } = resolvePaths(root, input.cwd, [...input.paths, ...terms.paths]);
+    const files = resolved.filter((entry) => entry.isFile).map((entry) => entry.path);
+    const pathSites = [];
+    for (const object of register.objects) {
+        for (const table of object.tables)
+            pathSites.push(...scanWriteSites(root, files, table, tableSymbols(table, graph)));
+    }
+    const resolutions = resolveObjects(register.objects, input.text, terms.identifiers, pathSites);
+    for (const entry of resolved)
+        sections.RESOLVED.push(line("CERTAIN", `path ${entry.path}`, { paths: entry.isFile ? [entry.path] : [] }));
+    for (const resolution of resolutions)
+        sections.RESOLVED.push(line("AUTHORED", `${resolution.object.name} via ${resolution.via.join(", ")}`));
+    sections.RESOLVED.push(line("CERTAIN", JUDGE_LINE));
+    if (graph !== null && graph.indexedHead !== null && input.checkoutHead !== null && graph.indexedHead !== input.checkoutHead) {
+        sections.RESOLVED.push(line("CERTAIN", `index at ${graph.indexedHead.slice(0, 7)}, checkout at ${input.checkoutHead.slice(0, 7)}`));
+    }
+    const cardHoleLines = [];
+    const writerSites = new Set();
+    const writerFiles = [];
+    for (const { object } of resolutions) {
+        const writers = graph === null ? null : objectWriters(root, object, graph, files);
+        for (const site of writers ?? []) {
+            writerSites.add(`${site.path}:${site.line}`);
+            if (!writerFiles.includes(site.path))
+                writerFiles.push(site.path);
+        }
+        sections.CARDS.push(...cardLines(object, writers, input.graphReason));
+        cardHoleLines.push(...cardHoles(object, writers, dir));
+    }
+    const resolvedNames = new Set(resolutions.map((resolution) => resolution.object.name));
+    for (const { object } of resolutions) {
+        if (object.projects !== null)
+            sections.RELATIONS.push(line("AUTHORED", `${object.name} projects ${object.projects}`));
+    }
+    const coWritten = new Set();
+    for (const file of writerFiles) {
+        for (const other of register.objects) {
+            if (other.tables.length === 0)
+                continue;
+            const isWritten = other.tables.some((table) => scanWriteSites(root, [file], table, tableSymbols(table, graph)).length > 0);
+            const key = `${other.name}@${file}`;
+            if (!isWritten || coWritten.has(key))
+                continue;
+            if (resolvedNames.has(other.name))
+                continue;
+            coWritten.add(key);
+            sections.RELATIONS.push(line("INFERRED", `${other.name} co-written in ${file}`, { paths: [file] }));
+        }
+    }
+    if (graph === null) {
+        empty.ANCHORS = input.graphReason ?? GRAPH_UNAVAILABLE_REASON;
+    }
+    else {
+        const anchorPaths = files.length > 0 ? files : writerFiles.slice(0, WRITER_ANCHOR_PATHS);
+        for (const target of anchorPaths) {
+            const rows = [
+                ...answerRows(graph.ask("impact", { target, limit: IMPACT_ROWS }), "impact", target, IMPACT_ROWS, writerSites),
+                ...answerRows(graph.ask("tests-covering", { path: target, limit: TESTS_ROWS }), "tests-covering", target, TESTS_ROWS, writerSites),
+            ];
+            rows.forEach((row, rank) => sections.ANCHORS.push({ ...row, group: target, rank }));
+        }
+        if (anchorPaths.length === 0)
+            empty.ANCHORS = "no path resolved and no writer found";
+    }
+    const seenDocs = new Set();
+    for (const { doc, object } of documentsByObjects(root, input.docsRoot, [...resolvedNames])) {
+        if (seenDocs.has(doc))
+            continue;
+        seenDocs.add(doc);
+        sections.DOCS.push(line("AUTHORED", `${doc} (status ${frontmatterStatus(root, doc)}) — designs ${object}`, { paths: [doc] }));
+    }
+    for (const source of [...files, ...writerFiles]) {
+        for (const doc of headerPointers(root, input.docsRoot, source)) {
+            if (seenDocs.has(doc))
+                continue;
+            seenDocs.add(doc);
+            sections.DOCS.push(line("AUTHORED", `${doc} (status ${frontmatterStatus(root, doc)}) — named by the header of ${source}`, { paths: [doc] }));
+        }
+    }
+    sections.OBLIGATIONS.push(line("CERTAIN", OBLIGATIONS_LINE));
+    const holes = [];
+    for (const term of terms.identifiers) {
+        if (isRegisterTerm(register.objects, term))
+            continue;
+        if (graph !== null && graph.isDefined(term))
+            continue;
+        holes.push(line("NOT KNOWN", `grep -rn "${term}" ${dir}`));
+    }
+    for (const term of missing)
+        holes.push(line("NOT KNOWN", `grep -rn "${path.basename(term)}" ${dir}`));
+    for (const refusal of register.refusals) {
+        holes.push(line("NOT KNOWN", `grep -n "${refusal.name ?? ""}" ${refusal.file} (refused at line ${refusal.line}: ${refusal.reason})`));
+    }
+    holes.push(...cardHoleLines);
+    sections.HOLES = holes.slice(0, CONTEXT_MAX_HOLES);
+    const rendered = renderPack(sections, empty, input.budgetTokens);
+    const offered = new Set();
+    for (const name of ["RESOLVED", "CARDS", "RELATIONS", "ANCHORS", "DOCS"]) {
+        for (const kept of rendered.sections[name]) {
+            for (const file of kept.paths ?? [])
+                if (existsSync(path.join(root, file)))
+                    offered.add(file);
+        }
+    }
+    return {
+        exitCode: resolutions.length === 0 && resolved.length === 0 ? CONTEXT_EXIT_NOTHING_RESOLVED : CONTEXT_EXIT_OK,
+        objects: resolutions.map((resolution) => resolution.object.name),
+        resolvedPaths: resolved.map((entry) => entry.path),
+        rendered,
+        offeredPaths: [...offered],
+    };
+}

package/dist/lib/context/editCard.js

@@ -0,0 +1,31 @@
+import { CARD_MAX_WRITERS } from "./compose.js";
+import { renderCard } from "./render.js";
+import { camelCaseOf, findWriteSites, scanWriteSites } from "./writers.js";
+export function objectsWrittenIn(root, register, relPath) {
+    return register.objects.filter((object) => object.tables.some((table) => scanWriteSites(root, [relPath], table, [camelCaseOf(table)]).length > 0));
+}
+export function buildEditCard(root, object, relPath, graph, graphReason) {
+    const group = object.name;
+    const scope = object.scope.length === 0 ? "unscoped" : object.scope.join(", ");
+    const lines = [{ label: "AUTHORED", text: `object ${object.name}  (${object.plane ?? "no plane"} · scope ${scope})`, group }];
+    if (object.oneLine !== null)
+        lines.push({ label: "AUTHORED", text: object.oneLine, group });
+    const writers = [];
+    for (const table of object.tables) {
+        const sites = graph === null ? scanWriteSites(root, [relPath], table, [camelCaseOf(table)]) : findWriteSites(root, table, graph, [relPath]);
+        for (const site of sites)
+            if (!writers.some((existing) => existing.path === site.path && existing.line === site.line))
+                writers.push(site);
+    }
+    if (graph === null)
+        lines.push({ label: "NOT KNOWN", text: graphReason ?? "code graph not available — `nustack graph index`", group });
+    for (const site of writers.slice(0, CARD_MAX_WRITERS)) {
+        lines.push({ label: "INFERRED", text: `writer ${site.path}:${site.line} ${site.verb} ${site.table}`, group, role: "writer" });
+    }
+    lines.push({ label: "NOT KNOWN", text: `grep -rnE "fail\\(c, [0-9]{3}" ${relPath}`, group });
+    for (const claim of object.claims) {
+        const text = claim.type === "predicate" ? `claim ${claim.text} (not evaluated)` : `claim? ${claim.text}`;
+        lines.push({ label: "AUTHORED", text, group, role: "claim" });
+    }
+    return renderCard(`EDIT CARD — ${relPath} writes ${object.name}`, lines);
+}

package/dist/lib/context/graph.js

@@ -0,0 +1,107 @@
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { loadCodegraph } from "../graph/library.js";
+import { refreshIfStale } from "../graph/freshness.js";
+export const GRAPH_UNAVAILABLE_REASON = "code graph not available — `nustack graph index`";
+function viewOver(library, root, db, indexedHead) {
+    const ask = (fn, args) => {
+        try {
+            const answer = library.dispatch({ root, db, budget: 0 }, { fn, args });
+            return answer.unavailable === undefined ? answer : null;
+        }
+        catch {
+            return null;
+        }
+    };
+    const defined = new Map();
+    return {
+        indexedHead,
+        ask,
+        isDefined(symbol) {
+            const known = defined.get(symbol);
+            if (known !== undefined)
+                return known;
+            const answer = ask("where-defined", { symbol, limit: 1 });
+            const isDefined = (answer?.sections[0]?.rows.length ?? 0) > 0;
+            defined.set(symbol, isDefined);
+            return isDefined;
+        },
+        importers(symbol, limit) {
+            const answer = ask("refs", { name: symbol, limit });
+            const section = answer?.sections.find((candidate) => candidate.label === "imported at");
+            const files = (section?.rows ?? []).map((row) => (row.at ?? "").replace(/:\d+$/, "")).filter((file) => file !== "");
+            return [...new Set(files)].slice(0, limit);
+        },
+        close() {
+            try {
+                db.close();
+            }
+            catch {
+            }
+        },
+    };
+}
+export async function openGraphForHook(root, load = loadCodegraph) {
+    let library;
+    try {
+        library = await load();
+    }
+    catch {
+        return { view: null, reason: GRAPH_UNAVAILABLE_REASON };
+    }
+    if (typeof library.openReadOnly !== "function")
+        return { view: null, reason: GRAPH_UNAVAILABLE_REASON };
+    const db = library.openReadOnly(root);
+    if (db === null)
+        return { view: null, reason: GRAPH_UNAVAILABLE_REASON };
+    const record = library.findProject(root);
+    return { view: viewOver(library, root, db, record?.lastHead ?? null), reason: null };
+}
+export async function openGraphForCommand(root, options) {
+    let library;
+    try {
+        library = await loadCodegraph();
+    }
+    catch {
+        return { view: null, reason: GRAPH_UNAVAILABLE_REASON };
+    }
+    try {
+        await refreshIfStale(library, root, { noRefresh: options.noRefresh, onProgress: options.onProgress });
+        const record = library.findProject(root);
+        const db = library.open(root);
+        return { view: viewOver(library, root, db, record?.lastHead ?? null), reason: null };
+    }
+    catch {
+        return { view: null, reason: GRAPH_UNAVAILABLE_REASON };
+    }
+}
+export function readCheckoutHead(root) {
+    try {
+        let gitDir = path.join(root, ".git");
+        if (!existsSync(path.join(gitDir, "HEAD"))) {
+            const pointer = /^gitdir:\s*(.+)$/m.exec(readFileSync(gitDir, "utf8"));
+            if (pointer === null)
+                return null;
+            gitDir = path.resolve(root, (pointer[1] ?? "").trim());
+        }
+        const head = readFileSync(path.join(gitDir, "HEAD"), "utf8").trim();
+        const ref = /^ref:\s*(.+)$/.exec(head);
+        if (ref === null)
+            return /^[0-9a-f]{40}$/.test(head) ? head : null;
+        const name = (ref[1] ?? "").trim();
+        const commonDir = existsSync(path.join(gitDir, "commondir"))
+            ? path.resolve(gitDir, readFileSync(path.join(gitDir, "commondir"), "utf8").trim())
+            : gitDir;
+        for (const dir of [gitDir, commonDir]) {
+            const loose = path.join(dir, name);
+            if (existsSync(loose))
+                return readFileSync(loose, "utf8").trim();
+        }
+        const packed = readFileSync(path.join(commonDir, "packed-refs"), "utf8");
+        const line = packed.split("\n").find((entry) => entry.endsWith(` ${name}`));
+        return line === undefined ? null : (line.split(" ")[0] ?? null);
+    }
+    catch {
+        return null;
+    }
+}