dsh-gitnexus-plus 0.0.0-stage → 0.1.2

package/lib/gitnexus/index-meta.d.ts

@@ -0,0 +1,160 @@
+/**
+ * Read the on-disk GitNexus index metadata.
+ *
+ * `.gitnexus/gitnexus.json` is the only fully machine-readable artifact GitNexus
+ * writes: the graph itself lives in a single LadybugDB file (`lbug`) and there is
+ * no persisted graph JSON/CSV. Everything this plugin shows about an index that
+ * is not the graph comes from here or from `~/.gitnexus/registry.json`.
+ */
+/** Directory GitNexus keeps its global state in, honouring `GITNEXUS_HOME`. */
+export declare function globalDir(env?: NodeJS.ProcessEnv): string;
+/** The environment a caller may thread through instead of the real one. */
+export interface RegistryOptions {
+    env?: NodeJS.ProcessEnv;
+}
+/** The counters every manifest and registry entry carries. */
+export interface IndexStats {
+    files: number;
+    nodes: number;
+    edges: number;
+    communities: number;
+    processes: number;
+    embeddings: number;
+}
+export interface RegistryEntry {
+    name: string;
+    path: string;
+    storagePath: string;
+    indexedAt: string;
+    lastCommit: string;
+    remoteUrl?: string;
+    branch?: string;
+    stats: IndexStats;
+}
+/**
+ * Read the global registry. Never throws: an absent or malformed registry yields
+ * an empty list, because "GitNexus has never run here" is a normal state.
+ *
+ * The registry is written by GitNexus, not by this plugin, so entries are taken
+ * as written: the guard checks the one field a lookup needs (`path`) and nothing
+ * else, exactly as the untyped revision did.
+ */
+export declare function readRegistry(options?: RegistryOptions): Promise<RegistryEntry[]>;
+/**
+ * Normalize a path for comparison.
+ *
+ * Windows paths in the registry are not case-stable in practice — this machine's
+ * registry holds both `D:\Project\...` and `D:\project\...` for the same tree.
+ * Comparing raw strings would treat one repository as two.
+ */
+export declare function normalizePathKey(p: string): string;
+/**
+ * Find the registry entry for a repository path or alias.
+ *
+ * @param target absolute path or registry alias
+ */
+export declare function findRegistryEntry(target: string, options?: RegistryOptions): Promise<RegistryEntry | null>;
+/**
+ * Whether a directory holds a GitNexus index.
+ *
+ * The panel shows the project the user is *in*, which need not appear in the global
+ * registry at all — and a plugin that refused to describe the user's own working
+ * directory because a global file elsewhere had not heard of it would be wrong.
+ * This is not by itself the route bound any more: a git project with no index still
+ * has a readable working tree, so the routes use {@link isProjectRoot}, which
+ * accepts either an index or a `.git` marker.
+ */
+export declare function hasIndex(repoPath: string): Promise<boolean>;
+/**
+ * Whether a directory is a project the routes may describe.
+ *
+ * Deliberately wider than {@link hasIndex}: a git repository with no index still has
+ * a readable working tree, and both the scan-only coverage report and the initialize
+ * action are for exactly that state. A directory with neither an index nor a `.git`
+ * marker is refused, which is what keeps these routes from becoming a filesystem
+ * probe. `.git` may be a directory or a file (worktrees and submodules), so this
+ * checks existence rather than type.
+ */
+export declare function isProjectRoot(repoPath: string): Promise<boolean>;
+/** `indexCoverage` as the `analyze` that produced the index wrote it. */
+export interface RawIndexCoverage {
+    maxFileSizeBytes?: unknown;
+    dirtyPaths?: unknown;
+    [key: string]: unknown;
+}
+/** `runnerIdentity`, the analyzer-provenance receipt (schema v4). */
+export interface RunnerIdentity {
+    cliVersion?: string;
+    [key: string]: unknown;
+}
+/**
+ * The parsed manifest, as far as this plugin reads it.
+ *
+ * Named fields are the ones read here or in the report built from them; the index
+ * signature carries the rest of a manifest GitNexus is free to extend, so a newer
+ * manifest stays readable without a change here. Nothing in this file validates
+ * the manifest — a field of the wrong type is reported as absent, not repaired.
+ */
+export interface RawIndexManifest {
+    storagePath?: unknown;
+    repoPath?: unknown;
+    indexedAt?: unknown;
+    lastCommit?: unknown;
+    branch?: unknown;
+    stats?: IndexStats;
+    fileHashes?: Record<string, unknown> | null;
+    indexCoverage?: RawIndexCoverage | null;
+    capabilities?: Record<string, unknown>;
+    schemaFingerprint?: unknown;
+    runnerIdentity?: RunnerIdentity;
+    remoteUrl?: string;
+    contentRetention?: string | null;
+    ftsProfile?: string | null;
+    analysisFeatures?: Record<string, number>;
+    crossLanguageProperties?: unknown[];
+    unresolvedReceiverMembers?: unknown;
+    [key: string]: unknown;
+}
+export interface IndexMeta {
+    /** which of the two manifest names the values came from */
+    metaFile: string | null;
+    storagePath: string;
+    repoPath: string;
+    indexedAt: string;
+    lastCommit: string;
+    branch?: string;
+    stats: IndexStats;
+    /** repo-relative path -> sha256 */
+    fileHashes: Record<string, string>;
+    /** size cap in force when the index was written */
+    coverageMaxFileSizeBytes: number | null;
+    /** files that were dirty vs HEAD when indexed */
+    dirtyPaths: string[];
+    capabilities: Record<string, unknown>;
+    schemaFingerprint?: string;
+    runnerIdentity?: RunnerIdentity;
+    /** the full parsed manifest */
+    raw: RawIndexManifest;
+}
+/**
+ * Read the index manifest for a repository.
+ *
+ * Two file names exist in the wild and both must be honoured:
+ *
+ *   `gitnexus.json` — current format, written by the `analyze` that produced the
+ *                     index. Carries `indexCoverage`, `storagePath`, `branch`,
+ *                     `runnerIdentity` on top of the shared fields.
+ *   `meta.json`     — the older name, still present on indexes built by earlier
+ *                     releases. Observed on this machine holding a 28 536-entry
+ *                     `fileHashes` with **no** `indexCoverage` at all.
+ *
+ * Reading only `gitnexus.json` makes the tool report a perfectly good 28k-file
+ * index as "not indexed" — which is how this fallback came to exist. Absent
+ * coverage fields are reported as absent (`null`), never defaulted: claiming a cap
+ * the index never recorded would misattribute files as "skipped".
+ *
+ * @param repoPath absolute repository root
+ * @returns `null` when the repository is not indexed.
+ */
+export declare function readIndexMeta(repoPath: string): Promise<IndexMeta | null>;
+//# sourceMappingURL=index-meta.d.ts.map

package/lib/gitnexus/index-meta.d.ts.map

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

package/lib/gitnexus/index-meta.js

@@ -0,0 +1,176 @@
+/**
+ * Read the on-disk GitNexus index metadata.
+ *
+ * `.gitnexus/gitnexus.json` is the only fully machine-readable artifact GitNexus
+ * writes: the graph itself lives in a single LadybugDB file (`lbug`) and there is
+ * no persisted graph JSON/CSV. Everything this plugin shows about an index that
+ * is not the graph comes from here or from `~/.gitnexus/registry.json`.
+ */
+import { existsSync } from 'node:fs';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+/** Directory GitNexus keeps its global state in, honouring `GITNEXUS_HOME`. */
+export function globalDir(env = process.env) {
+    return env.GITNEXUS_HOME && env.GITNEXUS_HOME.trim() !== ''
+        ? path.resolve(env.GITNEXUS_HOME)
+        : path.join(os.homedir(), '.gitnexus');
+}
+/**
+ * Read the global registry. Never throws: an absent or malformed registry yields
+ * an empty list, because "GitNexus has never run here" is a normal state.
+ *
+ * The registry is written by GitNexus, not by this plugin, so entries are taken
+ * as written: the guard checks the one field a lookup needs (`path`) and nothing
+ * else, exactly as the untyped revision did.
+ */
+export async function readRegistry(options = {}) {
+    const file = path.join(globalDir(options.env ?? process.env), 'registry.json');
+    try {
+        const parsed = JSON.parse(await fs.readFile(file, 'utf8'));
+        return Array.isArray(parsed)
+            ? parsed.filter((entry) => Boolean(entry) && typeof entry.path === 'string')
+            : [];
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Normalize a path for comparison.
+ *
+ * Windows paths in the registry are not case-stable in practice — this machine's
+ * registry holds both `D:\Project\...` and `D:\project\...` for the same tree.
+ * Comparing raw strings would treat one repository as two.
+ */
+export function normalizePathKey(p) {
+    const resolved = path.resolve(p).replace(/\\/g, '/').replace(/\/+$/, '');
+    return process.platform === 'win32' ? resolved.toLowerCase() : resolved;
+}
+/**
+ * Find the registry entry for a repository path or alias.
+ *
+ * @param target absolute path or registry alias
+ */
+export async function findRegistryEntry(target, options = {}) {
+    const entries = await readRegistry(options);
+    const wanted = normalizePathKey(target);
+    const byPath = entries.find((e) => {
+        try {
+            return normalizePathKey(e.path) === wanted;
+        }
+        catch {
+            return false;
+        }
+    });
+    if (byPath)
+        return byPath;
+    return entries.find((e) => e.name === target) ?? null;
+}
+/**
+ * Whether a directory holds a GitNexus index.
+ *
+ * The panel shows the project the user is *in*, which need not appear in the global
+ * registry at all — and a plugin that refused to describe the user's own working
+ * directory because a global file elsewhere had not heard of it would be wrong.
+ * This is not by itself the route bound any more: a git project with no index still
+ * has a readable working tree, so the routes use {@link isProjectRoot}, which
+ * accepts either an index or a `.git` marker.
+ */
+export async function hasIndex(repoPath) {
+    const dir = path.join(repoPath, '.gitnexus');
+    for (const name of ['gitnexus.json', 'meta.json']) {
+        try {
+            await fs.access(path.join(dir, name));
+            return true;
+        }
+        catch {
+            /* try the next name */
+        }
+    }
+    return false;
+}
+/**
+ * Whether a directory is a project the routes may describe.
+ *
+ * Deliberately wider than {@link hasIndex}: a git repository with no index still has
+ * a readable working tree, and both the scan-only coverage report and the initialize
+ * action are for exactly that state. A directory with neither an index nor a `.git`
+ * marker is refused, which is what keeps these routes from becoming a filesystem
+ * probe. `.git` may be a directory or a file (worktrees and submodules), so this
+ * checks existence rather than type.
+ */
+export async function isProjectRoot(repoPath) {
+    if (await hasIndex(repoPath))
+        return true;
+    try {
+        return existsSync(path.join(repoPath, '.git'));
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Read the index manifest for a repository.
+ *
+ * Two file names exist in the wild and both must be honoured:
+ *
+ *   `gitnexus.json` — current format, written by the `analyze` that produced the
+ *                     index. Carries `indexCoverage`, `storagePath`, `branch`,
+ *                     `runnerIdentity` on top of the shared fields.
+ *   `meta.json`     — the older name, still present on indexes built by earlier
+ *                     releases. Observed on this machine holding a 28 536-entry
+ *                     `fileHashes` with **no** `indexCoverage` at all.
+ *
+ * Reading only `gitnexus.json` makes the tool report a perfectly good 28k-file
+ * index as "not indexed" — which is how this fallback came to exist. Absent
+ * coverage fields are reported as absent (`null`), never defaulted: claiming a cap
+ * the index never recorded would misattribute files as "skipped".
+ *
+ * @param repoPath absolute repository root
+ * @returns `null` when the repository is not indexed.
+ */
+export async function readIndexMeta(repoPath) {
+    const dir = path.join(repoPath, '.gitnexus');
+    let raw = null;
+    let source = null;
+    for (const name of ['gitnexus.json', 'meta.json']) {
+        try {
+            raw = JSON.parse(await fs.readFile(path.join(dir, name), 'utf8'));
+            source = name;
+            break;
+        }
+        catch {
+            /* try the next name */
+        }
+    }
+    if (raw === null)
+        return null;
+    const fileHashes = {};
+    if (raw.fileHashes && typeof raw.fileHashes === 'object') {
+        for (const [key, value] of Object.entries(raw.fileHashes)) {
+            if (typeof value === 'string')
+                fileHashes[key.replace(/\\/g, '/')] = value;
+        }
+    }
+    const coverage = raw.indexCoverage;
+    return {
+        metaFile: source,
+        storagePath: typeof raw.storagePath === 'string' ? raw.storagePath : path.join(repoPath, '.gitnexus'),
+        repoPath: typeof raw.repoPath === 'string' ? raw.repoPath : repoPath,
+        indexedAt: typeof raw.indexedAt === 'string' ? raw.indexedAt : '',
+        lastCommit: typeof raw.lastCommit === 'string' ? raw.lastCommit : '',
+        branch: typeof raw.branch === 'string' ? raw.branch : undefined,
+        stats: raw.stats ?? { files: 0, nodes: 0, edges: 0, communities: 0, processes: 0, embeddings: 0 },
+        fileHashes,
+        // Absent on indexes written before this field existed — callers must not
+        // invent a cap when it is missing.
+        coverageMaxFileSizeBytes: coverage && typeof coverage.maxFileSizeBytes === 'number' ? coverage.maxFileSizeBytes : null,
+        dirtyPaths: Array.isArray(coverage?.dirtyPaths) ? coverage.dirtyPaths : [],
+        capabilities: raw.capabilities ?? {},
+        schemaFingerprint: typeof raw.schemaFingerprint === 'string' ? raw.schemaFingerprint : undefined,
+        runnerIdentity: raw.runnerIdentity,
+        raw,
+    };
+}
+//# sourceMappingURL=index-meta.js.map

package/lib/gitnexus/index-meta.js.map

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

package/lib/gitnexus/install.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Install GitNexus on this machine, on the operator's explicit instruction.
+ *
+ * WHY THE PLUGIN DOES THIS ITSELF
+ * -------------------------------
+ * The plugin reads `.gitnexus/gitnexus.json` — a file that only GitNexus can produce,
+ * containing every function definition, symbol relationship and execution flow. Without
+ * it there is nothing to display, and no amount of scanning the working tree substitutes
+ * for it. So "the user has no GitNexus" is not a degraded state to design around; it is
+ * a missing prerequisite, and the most useful thing the plugin can do about it is offer
+ * to satisfy it.
+ *
+ * WHAT IT DOES NOT DO
+ * -------------------
+ * It does not download anything itself, and it does not pick a registry. It runs `npm
+ * install` and lets npm use whatever registry the machine is already configured for —
+ * a mirror, a corporate feed, a local Verdaccio. Hardcoding one would break exactly the
+ * users whose network is the reason they need this path, and the operator's `.npmrc` is
+ * the only authority on where their packages come from.
+ *
+ * It also does not build anything itself. npm runs the dependency install scripts that
+ * GitNexus needs (`@ladybugdb/core`, `tree-sitter`, its own grammar build) — which is
+ * why this uses npm rather than pnpm, whose ≥10 line refuses dependency build scripts by
+ * default and would fail the install in a way the operator could not act on.
+ *
+ * INSTALL LOCATION
+ * ----------------
+ * A directory the plugin owns (`$DSH_HOME/gitnexus-plus/gitnexus`), never the global
+ * prefix. A global install needs elevation on Windows and would collide with a GitNexus
+ * the operator already has. A plugin-owned copy is removable, self-describing, and does
+ * not make the plugin responsible for someone else's global state.
+ *
+ * The cost is real and the confirmation must state it: roughly 500 MB to 1 GB, several
+ * minutes, network access, and the package's build scripts running on this machine.
+ */
+import type { ShellLike } from './analyze.js';
+export type InstallState = 'running' | 'done' | 'failed' | 'timed-out' | 'cancelled'
+/** The sandbox refused a write. Reported, never retried wider. */
+ | 'denied'
+/** No shell executor in this deployment, so nothing can be installed. */
+ | 'unavailable';
+export interface InstallStatus {
+    state: InstallState;
+    /** The command as run, so a failure can be reproduced by hand. */
+    command: string;
+    /** Where it installs to. */
+    prefix: string;
+    startedAt: number;
+    finishedAt: number | null;
+    exitCode: number | null;
+    message: string | null;
+    output: string;
+}
+/** The version range this plugin is known to work against. */
+export declare const GITNEXUS_RANGE = "^1.6.12";
+export interface InstallRunnerOptions {
+    shell: ShellLike | null;
+    /** Install target. Defaults to `$DSH_HOME/gitnexus-plus/gitnexus`. */
+    prefix?: string;
+    /** Version spec passed to npm. */
+    spec?: string;
+    timeoutMs?: number;
+    outputLimit?: number;
+    tailLimit?: number;
+    /** How long to wait for the completion notice, for tests. */
+    now?: () => number;
+    /** Platform whose shell syntax applies. */
+    platform?: NodeJS.Platform;
+}
+export interface InstallRunner {
+    start(): InstallStatus;
+    status(): InstallStatus | null;
+    cancel(): boolean;
+    /** Where a successful install puts the CLI. */
+    cliPath(): string;
+    dispose(): void;
+}
+/**
+ * The default install target.
+ *
+ * Under `DSH_HOME` rather than under the plugin, because a profile-installed plugin
+ * lives inside `node_modules` and writing a 500 MB tree there would be lost on the next
+ * install and would confuse the package manager's own bookkeeping.
+ */
+export declare function defaultInstallPrefix(env?: NodeJS.ProcessEnv): string;
+/**
+ * The `npm install` line, as the shell will read it.
+ *
+ * `--prefix` rather than `cd`: the working directory stays wherever the executor put it,
+ * so a failed install cannot leave a half-written tree in the operator's project. No
+ * `--registry` on purpose — see the module comment.
+ */
+export declare function installCommandLine(prefix: string, spec: string, options?: {
+    platform?: NodeJS.Platform;
+}): string;
+export declare function createInstallRunner(options: InstallRunnerOptions): InstallRunner;
+//# sourceMappingURL=install.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"install.d.ts","sourceRoot":"","sources":["../../src/gitnexus/install.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAIH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAE9C,MAAM,MAAM,YAAY,GACpB,SAAS,GACT,MAAM,GACN,QAAQ,GACR,WAAW,GACX,WAAW;AACb,kEAAkE;GAChE,QAAQ;AACV,yEAAyE;GACvE,aAAa,CAAC;AAElB,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,YAAY,CAAC;IACpB,kEAAkE;IAClE,OAAO,EAAE,MAAM,CAAC;IAChB,4BAA4B;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,8DAA8D;AAC9D,eAAO,MAAM,cAAc,YAAY,CAAC;AAMxC,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,SAAS,GAAG,IAAI,CAAC;IACxB,sEAAsE;IACtE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,kCAAkC;IAClC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6DAA6D;IAC7D,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,2CAA2C;IAC3C,QAAQ,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC;CAC5B;AAED,MAAM,WAAW,aAAa;IAC5B,KAAK,IAAI,aAAa,CAAC;IACvB,MAAM,IAAI,aAAa,GAAG,IAAI,CAAC;IAC/B,MAAM,IAAI,OAAO,CAAC;IAClB,+CAA+C;IAC/C,OAAO,IAAI,MAAM,CAAC;IAClB,OAAO,IAAI,IAAI,CAAC;CACjB;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CAGjF;AAOD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAA;CAAO,GAC3C,MAAM,CAIR;AAcD,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,oBAAoB,GAAG,aAAa,CAwJhF"}