dsh-gitnexus-plus 0.0.0-stage → 0.1.1

package/lib/gitnexus/scan.js

@@ -0,0 +1,247 @@
+/**
+ * Reproduce GitNexus's scan decision and expose what it discards.
+ *
+ * `walkRepositoryPaths` (gitnexus/dist/core/ingestion/filesystem-walker.js)
+ * makes three cuts and only returns the survivors:
+ *
+ *   1. `glob(recursive, { nodir: true, dot: false, ignore: createIgnoreFilter(repo) })`
+ *      — drops dotfiles (`dot: false`) and anything the ignore rules match.
+ *   2. `stat.size > maxFileSizeBytes` — the large-file cut. **Counted and logged
+ *      but never returned**, so an external tool cannot see it.
+ *   3. `.d.ts` / `.d.mts` / `.d.cts` whose same-stem implementation was also
+ *      scanned — suppressed as redundant.
+ *
+ * This module applies cuts 1 and 3 exactly as upstream does (reusing upstream's
+ * own `createIgnoreFilter` and glob), and turns cut 2 — the one that is invisible
+ * from outside — into data.
+ *
+ * Deliberate duplication: the single `glob(...)` call below mirrors
+ * `filesystem-walker.js:62-67`. It is four lines and must stay in lockstep with
+ * upstream. If it ever drifts, `test/run.mjs` catches it by cross-checking the
+ * reported large-file count against what `analyze` itself prints.
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { loadScanPrimitives } from './root.js';
+/** Mirrors DECLARATION_COMPANION_SUFFIXES in filesystem-walker.js. */
+const DECLARATION_COMPANION_SUFFIXES = Object.freeze([
+    { declaration: '.d.ts', implementations: ['.ts', '.tsx'] },
+    { declaration: '.d.mts', implementations: ['.mts'] },
+    { declaration: '.d.cts', implementations: ['.cts'] },
+]);
+/** Bounded concurrency for `fs.stat`, matching GitNexus's READ_CONCURRENCY. */
+const STAT_CONCURRENCY = 32;
+/**
+ * @returns entries minus redundant declaration files
+ */
+function dropRedundantDeclarations(entries) {
+    const scannedPaths = new Set(entries.map((e) => e.path));
+    return entries.filter((entry) => {
+        const companion = DECLARATION_COMPANION_SUFFIXES.find(({ declaration }) => entry.path.endsWith(declaration));
+        if (!companion)
+            return true;
+        const stem = entry.path.slice(0, -companion.declaration.length);
+        const redundant = companion.implementations.some((suffix) => scannedPaths.has(`${stem}${suffix}`));
+        return !redundant;
+    });
+}
+function redundantDeclarations(entries, selectedPaths) {
+    const kept = new Set(selectedPaths);
+    return entries.filter((e) => !kept.has(e.path));
+}
+/**
+ * Run a batched `fs.stat` over repo-relative paths.
+ * Unreadable files are skipped rather than failing the scan: a file that
+ * disappears mid-scan is normal, not an error.
+ */
+async function statAll(repoPath, relativePaths) {
+    const out = [];
+    for (let i = 0; i < relativePaths.length; i += STAT_CONCURRENCY) {
+        const batch = relativePaths.slice(i, i + STAT_CONCURRENCY);
+        const settled = await Promise.allSettled(batch.map(async (relativePath) => {
+            const stat = await fs.stat(path.join(repoPath, relativePath));
+            return { path: relativePath.replace(/\\/g, '/'), size: stat.size };
+        }));
+        for (const result of settled) {
+            if (result.status === 'fulfilled')
+                out.push(result.value);
+        }
+    }
+    return out;
+}
+/**
+ * Scan a repository the way GitNexus does, and report the size cut as data.
+ *
+ * @param repoPath absolute path to the repository root
+ * @param options `capBytes` overrides the cap (used when the index records its own coverage
+ *   policy); otherwise `GITNEXUS_MAX_FILE_SIZE` decides, as it does for `analyze`.
+ */
+export async function scanRepository(repoPath, options = {}) {
+    const env = options.env ?? process.env;
+    const primitives = options.primitives === undefined ? await loadScanPrimitives({ env }) : options.primitives;
+    const defaultCapBytes = primitives?.DEFAULT_MAX_FILE_SIZE_BYTES ?? 512 * 1024;
+    const maxCapBytes = primitives?.MAX_FILE_SIZE_UPPER_BOUND_BYTES ?? 32 * 1024 * 1024;
+    let capBytes;
+    let capSource;
+    if (typeof options.capBytes === 'number' && Number.isFinite(options.capBytes) && options.capBytes > 0) {
+        capBytes = Math.min(options.capBytes, maxCapBytes);
+        capSource = 'index';
+    }
+    else if (primitives) {
+        capBytes = Math.min(primitives.getMaxFileSizeBytes(), maxCapBytes);
+        capSource = env.GITNEXUS_MAX_FILE_SIZE ? 'env' : 'default';
+    }
+    else {
+        const parsed = Number(env.GITNEXUS_MAX_FILE_SIZE);
+        const valid = Number.isInteger(parsed) && parsed > 0;
+        capBytes = valid ? Math.min(parsed * 1024, maxCapBytes) : defaultCapBytes;
+        capSource = valid ? 'env' : 'default';
+    }
+    let matched;
+    if (primitives) {
+        // Upstream's own filter and glob options, verbatim.
+        const ignoreFilter = await primitives.createIgnoreFilter(repoPath);
+        matched = await primitives.glob('**/*', {
+            cwd: repoPath,
+            nodir: true,
+            dot: false,
+            ignore: ignoreFilter,
+        });
+    }
+    else {
+        matched = await fallbackWalk(repoPath);
+    }
+    const scanned = await statAll(repoPath, matched);
+    scanned.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+    const large = [];
+    const withinCap = [];
+    for (const file of scanned) {
+        if (file.size > capBytes)
+            large.push(file);
+        else
+            withinCap.push(file);
+    }
+    const selected = dropRedundantDeclarations(withinCap);
+    const suppressed = redundantDeclarations(withinCap, selected.map((f) => f.path));
+    large.sort((a, b) => b.size - a.size || (a.path < b.path ? -1 : 1));
+    return {
+        selected,
+        large,
+        suppressedDeclarations: suppressed,
+        scannedCount: scanned.length,
+        capBytes,
+        defaultCapBytes,
+        capSource,
+        maxCapBytes,
+        gitnexusVersion: primitives?.gitnexusVersion ?? 'unknown',
+        primitives: primitives ? 'gitnexus' : 'fallback',
+    };
+}
+/**
+ * Minimal `.gitignore`-style matcher used **only** when GitNexus's ignore service
+ * cannot be loaded.
+ *
+ * This is an approximation and is labelled as one wherever it surfaces
+ * (`ScanReport.primitives === 'fallback'`). It deliberately does not implement
+ * negation: refusing to un-ignore a file can over-report exclusions, whereas
+ * honouring `!` incorrectly would under-report skipped large files — and the
+ * second error is the one this tool exists to prevent.
+ *
+ * @param pattern a gitignore line, already trimmed
+ */
+function compileIgnorePattern(pattern) {
+    const cleaned = pattern.replace(/^\//, '').replace(/\/+$/, '');
+    const parts = cleaned.split('/').filter((p) => p !== '');
+    const toSegmentRegex = (segment) => new RegExp(`^${segment.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '[^/]*').replace(/\?/g, '[^/]')}$`, 'i');
+    return (segments) => {
+        // A pattern with no slash matches a basename at any depth; a pattern with one
+        // is anchored to the repository root (gitignore's own rule).
+        if (parts.length === 1) {
+            const re = toSegmentRegex(parts[0]);
+            return segments.some((s) => re.test(s));
+        }
+        // `**` spans any number of segments; expand it greedily by simple recursion.
+        const matchFrom = (pi, si) => {
+            if (pi === parts.length)
+                return true;
+            if (si > segments.length)
+                return false;
+            if (parts[pi] === '**') {
+                for (let skip = si; skip <= segments.length; skip += 1) {
+                    if (matchFrom(pi + 1, skip))
+                        return true;
+                }
+                return false;
+            }
+            if (si === segments.length)
+                return false;
+            return toSegmentRegex(parts[pi]).test(segments[si]) && matchFrom(pi + 1, si + 1);
+        };
+        return parts[0] === '**' ? matchFrom(0, 0) : matchFrom(0, 0);
+    };
+}
+/**
+ * Read `.gitignore` and `.gitnexusignore` into predicates, plus the two
+ * directories GitNexus always ignores.
+ */
+async function loadFallbackRules(repoPath) {
+    const matchers = [compileIgnorePattern('node_modules'), compileIgnorePattern('.git')];
+    for (const name of ['.gitignore', '.gitnexusignore']) {
+        let text;
+        try {
+            text = await fs.readFile(path.join(repoPath, name), 'utf8');
+        }
+        catch {
+            continue;
+        }
+        for (const raw of text.split(/\r?\n/)) {
+            const line = raw.trim();
+            if (line === '' || line.startsWith('#') || line.startsWith('!'))
+                continue;
+            matchers.push(compileIgnorePattern(line));
+        }
+    }
+    return matchers;
+}
+/**
+ * Dependency-free fallback walk, used only when GitNexus's `glob` cannot be
+ * resolved. Mirrors two upstream behaviours that are easy to get wrong:
+ *
+ *   - `dot: false` — a path is excluded when *any* segment begins with `.`,
+ *     which is why `.github/workflows/ci.yml` never reaches the pipeline.
+ *   - directories matched by the ignore rules prune their whole subtree.
+ *
+ * @returns repo-relative paths, forward slashes
+ */
+async function fallbackWalk(repoPath) {
+    const rules = await loadFallbackRules(repoPath);
+    const ignored = (segments) => rules.some((rule) => rule(segments));
+    const out = [];
+    const queue = [{ abs: repoPath, rel: [] }];
+    while (queue.length > 0) {
+        const dir = queue.pop();
+        let entries;
+        try {
+            entries = await fs.readdir(dir.abs, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            if (entry.name.startsWith('.'))
+                continue; // dot: false
+            const segments = [...dir.rel, entry.name];
+            if (ignored(segments))
+                continue;
+            const abs = path.join(dir.abs, entry.name);
+            if (entry.isDirectory()) {
+                queue.push({ abs, rel: segments });
+            }
+            else if (entry.isFile()) {
+                out.push(segments.join('/'));
+            }
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=scan.js.map

package/lib/gitnexus/scan.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scan.js","sourceRoot":"","sources":["../../src/gitnexus/scan.ts"],"names":[],"mappings":"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"}

package/lib/gitnexus/toolchain.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Whether GitNexus is actually available on this machine.
+ *
+ * WHY THIS EXISTS
+ * ---------------
+ * The plugin declares **no runtime dependencies** and never imports `gitnexus` as a
+ * module. It reads an index another tool produced and, when it can, deep-imports the
+ * upstream scan primitives at runtime. That design keeps the plugin a pure observer —
+ * but it means "the operator has no GitNexus" is a first-class reachable state, not
+ * an edge case, and nothing was checking for it.
+ *
+ * The consequence was not a crash. The engine degrades: `loadScanPrimitives` returns
+ * `null`, the local walker takes over, and the size caps fall back to their built-in
+ * defaults. The damage was in what the operator was **told**: with no index, the panel
+ * handed over `gitnexus analyze --index-only …` — a command that fails with
+ * `command not found` on a machine that has no GitNexus, presented as the next step.
+ *
+ * TWO SEPARATE QUESTIONS
+ * ----------------------
+ * The library tree and the CLI are different things and are reported separately,
+ * because they gate different promises:
+ *
+ *   - **package root** — can this plugin reuse GitNexus's own scan rules and language
+ *     detector, and are the numbers therefore authoritative?
+ *   - **CLI on PATH** — will the maintenance command the panel hands over actually
+ *     run when the operator pastes it?
+ *
+ * A `gitnexus` installed as a dependency but never linked globally satisfies the
+ * first and not the second, and collapsing them into one boolean would make the
+ * panel either over- or under-promise in that case.
+ */
+/** The probe order for a platform. Exported so a test can assert the ordering. */
+export declare function cliShimNames(platform?: NodeJS.Platform): readonly string[];
+/**
+ * The POSIX probe order, kept exported under its original name.
+ *
+ * Callers that need the real answer must use {@link cliShimNames}; this is the list
+ * for a platform where the extensionless shim is the correct one.
+ */
+export declare const CLI_SHIM_NAMES: readonly string[];
+export interface CliProbeFound {
+    present: true;
+    /**
+     * Absolute path to the thing that runs the CLI.
+     *
+     * A `.js` script when it came from the declared `gitnexus` dependency — that
+     * package's `bin` is `dist/cli/index.js` — and a shim path when it came from PATH.
+     * `viaNode` says which, because the two need different command shapes: a script is
+     * spawned as `node <path>`, a shim is spawned directly (and on Windows needs the
+     * shell's call operator).
+     */
+    cliPath: string;
+    /** Whether `cliPath` has to be run through `node`. */
+    viaNode: boolean;
+    /** Where this came from, so an unexpected pick can be diagnosed. */
+    source: 'override' | 'managed' | 'dependency' | 'path';
+    /** The package root it was resolved from, when it came from a dependency. */
+    packageRoot: string | null;
+}
+export interface CliProbeMissing {
+    present: false;
+    /** How many PATH entries were examined — evidence the probe actually ran. */
+    probedDirs: number;
+}
+/**
+ * How much of GitNexus is available.
+ *
+ * `library-only` is the case worth naming: analysis is authoritative, but a handed-over
+ * command will not run as typed.
+ */
+export type ToolchainVerdict = 
+/** Both the library tree and a CLI shim are present. Every promise holds. */
+'ready'
+/** The library tree is present but no CLI shim was found on PATH. */
+ | 'library-only'
+/** Neither was found: the plugin falls back to its own scan rules. */
+ | 'absent';
+export interface ToolchainStatus {
+    /** Where the GitNexus package tree was found, if anywhere. */
+    packageRoot: string | null;
+    /** Version read from that tree's manifest, for provenance. */
+    packageVersion: string | null;
+    /** Whether a `gitnexus` executable is reachable through PATH. */
+    cli: CliProbeFound | CliProbeMissing;
+    verdict: ToolchainVerdict;
+}
+export interface ToolchainOptions {
+    env?: NodeJS.ProcessEnv;
+    moduleUrl?: string;
+    /** Platform whose shim naming applies. Defaults to the running one. */
+    platform?: NodeJS.Platform;
+    /**
+     * Where this plugin installs GitNexus when the operator asks it to.
+     *
+     * Checked before the dependency and PATH so that a copy the plugin installed is the
+     * one it uses: that copy is the only one whose version it chose, and finding a
+     * different one later would make the refresh behave differently from the install that
+     * preceded it.
+     */
+    managedPrefix?: string;
+    /** Skips discovery entirely, returning an `absent` verdict — for tests. */
+    discover?: boolean;
+}
+/**
+ * Resolve the `gitnexus` CLI this plugin will run.
+ *
+ * ORDER: explicit override, then the declared dependency, then PATH.
+ *
+ * The dependency comes first because the plugin now declares `gitnexus` as one, so it
+ * is present by construction and no PATH search is needed — the "is GitNexus installed"
+ * question stops being a runtime check and becomes an install-time guarantee. That was
+ * the whole point of taking the dependency: a check that always succeeds is not a check.
+ *
+ * PATH remains as the fallback rather than the primary, because a normal `npm install`
+ * of this plugin puts `gitnexus` beside it in `node_modules`, where PATH never looks.
+ * Keeping the search means a machine with a global install still works if the
+ * dependency somehow did not land, and it keeps this repository's own tests runnable
+ * without a 1 GB install.
+ *
+ * Does not execute anything. Spawning the CLI to ask its version would be the direct
+ * test, but a confined DSH process denies piped stdio (`spawn EPERM`), which is the
+ * same constraint that shaped the maintenance commands — so a probe that only stats the
+ * filesystem is the one that works everywhere this plugin runs.
+ */
+export declare function findGitnexusCli(options?: ToolchainOptions): CliProbeFound | CliProbeMissing;
+/** Resolve the full picture: library tree, CLI shim, and the verdict they imply. */
+export declare function readToolchainStatus(options?: ToolchainOptions): ToolchainStatus;
+/**
+ * The one-line explanation the panel and the CLI show, or `null` when everything is
+ * present and there is nothing to warn about.
+ *
+ * Kept here rather than in the browser half so the CLI and the panel cannot describe
+ * the same machine state two different ways.
+ */
+export declare function toolchainNotice(status: ToolchainStatus): string | null;
+//# sourceMappingURL=toolchain.d.ts.map

package/lib/gitnexus/toolchain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"toolchain.d.ts","sourceRoot":"","sources":["../../src/gitnexus/toolchain.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AA2CH,kFAAkF;AAClF,wBAAgB,YAAY,CAAC,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAAG,SAAS,MAAM,EAAE,CAE5F;AAED;;;;;GAKG;AACH,eAAO,MAAM,cAAc,EAAE,SAAS,MAAM,EAAqB,CAAC;AAElE,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,IAAI,CAAC;IACd;;;;;;;;OAQG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB,sDAAsD;IACtD,OAAO,EAAE,OAAO,CAAC;IACjB,oEAAoE;IACpE,MAAM,EAAE,UAAU,GAAG,SAAS,GAAG,YAAY,GAAG,MAAM,CAAC;IACvD,6EAA6E;IAC7E,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,KAAK,CAAC;IACf,6EAA6E;IAC7E,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB;AAC1B,6EAA6E;AAC3E,OAAO;AACT,qEAAqE;GACnE,cAAc;AAChB,sEAAsE;GACpE,QAAQ,CAAC;AAEb,MAAM,WAAW,eAAe;IAC9B,8DAA8D;IAC9D,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,8DAA8D;IAC9D,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,iEAAiE;IACjE,GAAG,EAAE,aAAa,GAAG,eAAe,CAAC;IACrC,OAAO,EAAE,gBAAgB,CAAC;CAC3B;AAED,MAAM,WAAW,gBAAgB;IAC/B,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,uEAAuE;IACvE,QAAQ,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC;IAC3B;;;;;;;OAOG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,2EAA2E;IAC3E,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAuBD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,eAAe,CAAC,OAAO,GAAE,gBAAqB,GAAG,aAAa,GAAG,eAAe,CAkD/F;AAoDD,oFAAoF;AACpF,wBAAgB,mBAAmB,CAAC,OAAO,GAAE,gBAAqB,GAAG,eAAe,CASnF;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,eAAe,GAAG,MAAM,GAAG,IAAI,CAgBtE"}

package/lib/gitnexus/toolchain.js

@@ -0,0 +1,251 @@
+/**
+ * Whether GitNexus is actually available on this machine.
+ *
+ * WHY THIS EXISTS
+ * ---------------
+ * The plugin declares **no runtime dependencies** and never imports `gitnexus` as a
+ * module. It reads an index another tool produced and, when it can, deep-imports the
+ * upstream scan primitives at runtime. That design keeps the plugin a pure observer —
+ * but it means "the operator has no GitNexus" is a first-class reachable state, not
+ * an edge case, and nothing was checking for it.
+ *
+ * The consequence was not a crash. The engine degrades: `loadScanPrimitives` returns
+ * `null`, the local walker takes over, and the size caps fall back to their built-in
+ * defaults. The damage was in what the operator was **told**: with no index, the panel
+ * handed over `gitnexus analyze --index-only …` — a command that fails with
+ * `command not found` on a machine that has no GitNexus, presented as the next step.
+ *
+ * TWO SEPARATE QUESTIONS
+ * ----------------------
+ * The library tree and the CLI are different things and are reported separately,
+ * because they gate different promises:
+ *
+ *   - **package root** — can this plugin reuse GitNexus's own scan rules and language
+ *     detector, and are the numbers therefore authoritative?
+ *   - **CLI on PATH** — will the maintenance command the panel hands over actually
+ *     run when the operator pastes it?
+ *
+ * A `gitnexus` installed as a dependency but never linked globally satisfies the
+ * first and not the second, and collapsing them into one boolean would make the
+ * panel either over- or under-promise in that case.
+ */
+import { existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+import { findGitnexusRoot, readGitnexusVersion } from './root.js';
+/**
+ * Filenames a `gitnexus` CLI shim can have, in probe order **per platform**.
+ *
+ * Written out rather than derived from `PATHEXT`, for the reason `root.ts` already
+ * documents: under nvm-for-windows the shim is `gitnexus.ps1`, and `PATHEXT` does not
+ * list `.ps1`, so extension-driven discovery silently finds nothing on exactly the
+ * machines where the CLI is installed.
+ *
+ * ORDER IS PLATFORM-SPECIFIC, AND THAT IS THE WHOLE POINT
+ * ------------------------------------------------------
+ * npm writes three shims side by side: `gitnexus` (a `#!/bin/sh` script), `gitnexus.cmd`
+ * and `gitnexus.ps1`. The extensionless one is the POSIX entry point; on Windows it is
+ * inert. Measured on the reference machine:
+ *
+ *     gitnexus      -> no output, no exit status
+ *     gitnexus.ps1  -> 1.6.12, exit 0
+ *     gitnexus.cmd  -> 1.6.12, exit 0
+ *
+ * A single order listing the extensionless name first — which is the natural way to
+ * write it — therefore selects a shim that cannot run on Windows, and the `.ps1`
+ * fix above it never gets a chance to help. The runner would build a command around
+ * that path and report a failure that has nothing to do with the repository.
+ *
+ * `.cmd` leads on Windows because it is the one a batch *or* a PowerShell host can
+ * spawn; `.ps1` follows for installs that ship only that.
+ */
+const WINDOWS_SHIM_NAMES = [
+    'gitnexus.cmd',
+    'gitnexus.exe',
+    'gitnexus.bat',
+    'gitnexus.ps1',
+    'gitnexus',
+];
+const POSIX_SHIM_NAMES = ['gitnexus'];
+/** The probe order for a platform. Exported so a test can assert the ordering. */
+export function cliShimNames(platform = process.platform) {
+    return platform === 'win32' ? WINDOWS_SHIM_NAMES : POSIX_SHIM_NAMES;
+}
+/**
+ * The POSIX probe order, kept exported under its original name.
+ *
+ * Callers that need the real answer must use {@link cliShimNames}; this is the list
+ * for a platform where the extensionless shim is the correct one.
+ */
+export const CLI_SHIM_NAMES = POSIX_SHIM_NAMES;
+/**
+ * The effective `PATH`, whatever the platform spells it.
+ *
+ * `process.env` is a case-insensitive proxy — `process.env.PATH` resolves on Windows
+ * even though the variable is stored as `Path`. **Spreading it into a plain object
+ * drops that**, so `{ ...process.env }.PATH` is `undefined` on the default Windows
+ * layout and the probe walks zero directories while reporting a plausible-looking
+ * miss. That is how this was found: the runner reported "no gitnexus" on a machine
+ * where `gitnexus` runs, with `probedDirs: 0` as the only clue.
+ *
+ * Caller-supplied values still win, checked in the same three spellings so an
+ * override cannot be lost the same way.
+ */
+function effectivePath(override) {
+    const pick = (source) => {
+        if (source === undefined)
+            return undefined;
+        return source.PATH ?? source.Path ?? source.path;
+    };
+    return pick(override) ?? pick(process.env) ?? '';
+}
+/**
+ * Resolve the `gitnexus` CLI this plugin will run.
+ *
+ * ORDER: explicit override, then the declared dependency, then PATH.
+ *
+ * The dependency comes first because the plugin now declares `gitnexus` as one, so it
+ * is present by construction and no PATH search is needed — the "is GitNexus installed"
+ * question stops being a runtime check and becomes an install-time guarantee. That was
+ * the whole point of taking the dependency: a check that always succeeds is not a check.
+ *
+ * PATH remains as the fallback rather than the primary, because a normal `npm install`
+ * of this plugin puts `gitnexus` beside it in `node_modules`, where PATH never looks.
+ * Keeping the search means a machine with a global install still works if the
+ * dependency somehow did not land, and it keeps this repository's own tests runnable
+ * without a 1 GB install.
+ *
+ * Does not execute anything. Spawning the CLI to ask its version would be the direct
+ * test, but a confined DSH process denies piped stdio (`spawn EPERM`), which is the
+ * same constraint that shaped the maintenance commands — so a probe that only stats the
+ * filesystem is the one that works everywhere this plugin runs.
+ */
+export function findGitnexusCli(options = {}) {
+    if (options.discover === false)
+        return { present: false, probedDirs: 0 };
+    const platform = options.platform ?? process.platform;
+    // An explicit override wins, so a machine with a non-standard layout — or a test —
+    // can name the executable directly.
+    const explicit = options.env?.GITNEXUS_CLI ?? process.env.GITNEXUS_CLI;
+    if (typeof explicit === 'string' && explicit !== '' && existsSync(explicit)) {
+        return {
+            present: true,
+            cliPath: explicit,
+            viaNode: explicit.endsWith('.js'),
+            source: 'override',
+            packageRoot: null,
+        };
+    }
+    // The copy this plugin installed, when there is one. Ahead of the dependency and PATH
+    // because it is the only copy whose version this plugin chose: finding a different one
+    // afterwards would make the refresh behave differently from the install before it.
+    const managed = options.managedPrefix;
+    if (typeof managed === 'string' && managed !== '') {
+        const script = path.join(managed, 'node_modules', 'gitnexus', 'dist', 'cli', 'index.js');
+        try {
+            if (existsSync(script)) {
+                return { present: true, cliPath: script, viaNode: true, source: 'managed', packageRoot: path.join(managed, 'node_modules', 'gitnexus') };
+            }
+        }
+        catch {
+            /* unreadable managed tree — fall through to the other sources */
+        }
+    }
+    const fromDependency = resolveDependencyCli(options);
+    if (fromDependency !== null)
+        return fromDependency;
+    const entries = effectivePath(options.env).split(path.delimiter).filter((dir) => dir !== '');
+    for (const dir of entries) {
+        for (const name of cliShimNames(platform)) {
+            const candidate = path.join(dir, name);
+            try {
+                if (existsSync(candidate)) {
+                    return { present: true, cliPath: candidate, viaNode: false, source: 'path', packageRoot: null };
+                }
+            }
+            catch {
+                /* unreadable PATH entry — keep looking */
+            }
+        }
+    }
+    return { present: false, probedDirs: entries.length };
+}
+/**
+ * The CLI shipped inside the `gitnexus` dependency, if it is installed.
+ *
+ * Resolved by walking up from this module rather than by asking Node to resolve the
+ * package name, because these modules are CommonJS-compiled and a bare `require` of an
+ * ESM-only package would throw for a reason unrelated to whether the file exists. Each
+ * candidate is a plain `node_modules/gitnexus` directory on the way to the filesystem
+ * root, which is exactly where npm and pnpm put it.
+ */
+function resolveDependencyCli(options) {
+    const startDir = options.moduleUrl === undefined ? undefined : safeDirname(options.moduleUrl);
+    let dir = startDir ?? undefined;
+    // `import.meta.url` is only available in the host half, so the caller may not pass
+    // one; without a starting point there is nothing to walk and PATH is the answer.
+    if (dir === undefined)
+        return null;
+    for (let depth = 0; depth < 24; depth += 1) {
+        const candidateRoot = path.join(dir, 'node_modules', 'gitnexus');
+        const manifest = path.join(candidateRoot, 'package.json');
+        const script = path.join(candidateRoot, 'dist', 'cli', 'index.js');
+        try {
+            if (existsSync(manifest) && existsSync(script)) {
+                return {
+                    present: true,
+                    cliPath: script,
+                    viaNode: true,
+                    source: 'dependency',
+                    packageRoot: candidateRoot,
+                };
+            }
+        }
+        catch {
+            /* unreadable directory — keep walking up */
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return null;
+}
+/** Directory of one module url, or `undefined` when it cannot be read as a path. */
+function safeDirname(moduleUrl) {
+    try {
+        return path.dirname(fileURLToPath(moduleUrl));
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Resolve the full picture: library tree, CLI shim, and the verdict they imply. */
+export function readToolchainStatus(options = {}) {
+    const packageRoot = findGitnexusRoot(options);
+    const packageVersion = packageRoot === null ? null : readGitnexusVersion(packageRoot);
+    const cli = findGitnexusCli(options);
+    const verdict = packageRoot !== null && cli.present ? 'ready' : packageRoot !== null ? 'library-only' : 'absent';
+    return { packageRoot, packageVersion, cli, verdict };
+}
+/**
+ * The one-line explanation the panel and the CLI show, or `null` when everything is
+ * present and there is nothing to warn about.
+ *
+ * Kept here rather than in the browser half so the CLI and the panel cannot describe
+ * the same machine state two different ways.
+ */
+export function toolchainNotice(status) {
+    switch (status.verdict) {
+        case 'ready':
+            return null;
+        case 'library-only':
+            return ('本机有 GitNexus 库但没有 gitnexus 命令（可能只作为依赖安装、未全局链接）。' +
+                '下面的命令需要先 `npm i -g gitnexus` 才能直接执行。');
+        case 'absent':
+            return ('本机没有 GitNexus。扫描规则来自本插件内置的回退实现，' +
+                '与 GitNexus 自身的忽略规则不完全一致，覆盖差异数字仅供参考。' +
+                '初始化索引需要先安装：`npm i -g gitnexus`。');
+    }
+}
+//# sourceMappingURL=toolchain.js.map

package/lib/gitnexus/toolchain.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"toolchain.js","sourceRoot":"","sources":["../../src/gitnexus/toolchain.ts"],"names":[],"mappings":"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"}