dsh-gitnexus-plus 0.0.0-stage → 0.1.1

package/lib/gitnexus/git-activity.js

@@ -0,0 +1,345 @@
+/**
+ * Git activity, correlated with the index.
+ *
+ * WHAT THIS ADDS THAT PLAIN `git log` DOES NOT
+ * -------------------------------------------
+ * GitNexus is built on git, and its manifest records a content hash for every file
+ * it indexed. Crossing recent git activity with that set answers a question neither
+ * tool answers alone:
+ *
+ *     of the files people are actively changing right now,
+ *     how many does the knowledge graph even see?
+ *
+ * A file that is edited weekly but absent from the index contributes nothing to
+ * `impact`, `context` or `query` — and nothing in GitNexus's own UI says so. That
+ * is the `indexed` flag on every row here.
+ *
+ * BOUNDS ARE PART OF THE CONTRACT
+ * -------------------------------
+ * `git log --numstat` on a large repository is unbounded work, so every dimension
+ * is capped and the result says when a cap was hit (`window.truncated`). A silently
+ * truncated activity list reads as "this is all the activity there was", which is
+ * the one thing it must not mean.
+ */
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { normalizePathKey } from './index-meta.js';
+const run = promisify(execFile);
+/** Generous but finite: the log is informational, and it must not outlast the scan. */
+const TIMEOUT_MS = 20_000;
+/** Record separator (RS) opens each commit; unit separator (US) separates its fields. */
+const RS = '\u001e';
+const US = '\u001f';
+const DEFAULTS = Object.freeze({
+    sinceDays: 90,
+    maxCommits: 300,
+    maxFiles: 200,
+    maxAuthors: 20,
+    maxBranches: 20,
+});
+async function git(repoPath, args, maxBuffer = 32 * 1024 * 1024) {
+    try {
+        const { stdout } = await run('git', args, {
+            cwd: repoPath,
+            timeout: TIMEOUT_MS,
+            windowsHide: true,
+            maxBuffer,
+        });
+        return stdout;
+    }
+    catch (error) {
+        // `maxBuffer` overflow still leaves usable prefix output on some platforms, but
+        // treating it as failure is honest: a partial parse would understate activity.
+        return null;
+    }
+}
+/**
+ * Whether an author is a machine account.
+ *
+ * Worth separating because a bot's commit count and its file count disagree in a
+ * way a human's never does — measured on a real repository, `dependabot[bot]` was
+ * the second-busiest author with 80 commits against just 12 files. Left in the same
+ * list, it makes "who is active here" unreadable.
+ */
+function looksLikeBot(name, email) {
+    return (/\[bot\]$/i.test(name) ||
+        /(^|[-_.])bot@/i.test(email) ||
+        /^(dependabot|renovate|github-actions|greenkeeper)/i.test(name));
+}
+/**
+ * Bucket commit stamps into a time histogram.
+ *
+ * Daily buckets while the window is short enough to read, weekly once it is not:
+ * 90 daily columns in a sidebar is a smear, not a chart. The bucket width is
+ * returned so the axis can be labelled with the real unit instead of implying one.
+ *
+ * Empty buckets are materialised rather than skipped — a gap in a bar chart must
+ * read as "no commits that day", and inferring that from irregular spacing is
+ * exactly the misreading the chart exists to prevent.
+ */
+export function buildHistogram(stamps, sinceDays) {
+    if (stamps.length === 0)
+        return { bucketDays: 1, buckets: [] };
+    const bucketDays = sinceDays > 60 ? 7 : 1;
+    const sorted = [...stamps].sort((a, b) => (a.date < b.date ? -1 : 1));
+    const first = Date.parse(sorted[0].date);
+    const last = Date.parse(sorted[sorted.length - 1].date);
+    if (!Number.isFinite(first) || !Number.isFinite(last))
+        return { bucketDays, buckets: [] };
+    const dayMs = 86_400_000;
+    const byIndex = new Map();
+    for (const stamp of sorted) {
+        const at = Date.parse(stamp.date);
+        if (!Number.isFinite(at))
+            continue;
+        const index = Math.floor((at - first) / dayMs / bucketDays);
+        let bucket = byIndex.get(index);
+        if (bucket === undefined) {
+            const startMs = first + index * bucketDays * dayMs;
+            bucket = {
+                label: new Date(startMs).toISOString().slice(0, 10),
+                commits: 0,
+                insertions: 0,
+                deletions: 0,
+            };
+            byIndex.set(index, bucket);
+        }
+        bucket.commits += 1;
+        bucket.insertions += stamp.insertions;
+        bucket.deletions += stamp.deletions;
+    }
+    const count = Math.max(...byIndex.keys()) + 1;
+    const buckets = [];
+    for (let i = 0; i < count; i += 1) {
+        const existing = byIndex.get(i);
+        if (existing !== undefined) {
+            buckets.push(existing);
+            continue;
+        }
+        const startMs = first + i * bucketDays * dayMs;
+        buckets.push({
+            label: new Date(startMs).toISOString().slice(0, 10),
+            commits: 0,
+            insertions: 0,
+            deletions: 0,
+        });
+    }
+    return { bucketDays, buckets };
+}
+/**
+ * Read recent commits, authors, changed files and branches.
+ *
+ * Returns `null` when git cannot answer at all.
+ */
+export async function readGitActivity(repoPath, options = {}) {
+    // The window is expressed in days rather than as a git date expression so the
+    // result can be *labelled* without parsing one back out. A first revision passed
+    // the raw spec straight into the UI, which rendered "近 90 days ago 内".
+    const sinceDays = options.sinceDays ?? DEFAULTS.sinceDays;
+    const since = `${sinceDays} days ago`;
+    const maxCommits = options.maxCommits ?? DEFAULTS.maxCommits;
+    const maxFiles = options.maxFiles ?? DEFAULTS.maxFiles;
+    const maxAuthors = options.maxAuthors ?? DEFAULTS.maxAuthors;
+    const maxBranches = options.maxBranches ?? DEFAULTS.maxBranches;
+    const indexed = new Set([...(options.indexedPaths ?? [])].map((p) => normalizePathKey(p)));
+    const scannable = new Set([...(options.scannablePaths ?? [])].map((p) => normalizePathKey(p)));
+    const classified = indexed.size > 0 || scannable.size > 0;
+    /**
+     * Three-way, because "not in the index" is two different facts. A `.gitignore`
+     * or a `package-lock.json` is absent by design; a source file a fresh scan would
+     * pick up is absent because the index is behind. Reporting them as one number
+     * would make every repository look badly stale.
+     */
+    const classify = (filePath) => {
+        const key = normalizePathKey(filePath);
+        if (indexed.has(key))
+            return 'indexed';
+        if (scannable.size > 0 && scannable.has(key))
+            return 'missing';
+        return 'excluded';
+    };
+    const log = await git(repoPath, [
+        'log',
+        `--since=${since}`,
+        `--max-count=${maxCommits}`,
+        '--numstat',
+        '--no-renames',
+        `--format=${RS}%H${US}%an${US}%ae${US}%aI${US}%s`,
+    ]);
+    if (log === null)
+        return null;
+    const authors = [];
+    const files = new Map();
+    const authorMap = new Map();
+    let commitCount = 0;
+    let totalInsertions = 0;
+    let totalDeletions = 0;
+    let newestCommit = '';
+    let oldestCommit = '';
+    /** Per-commit stamps, for the time histogram. Bounded by `maxCommits`. */
+    const stamps = [];
+    for (const chunk of log.split(RS)) {
+        if (chunk.trim() === '')
+            continue;
+        const newline = chunk.indexOf('\n');
+        const header = newline === -1 ? chunk : chunk.slice(0, newline);
+        const body = newline === -1 ? '' : chunk.slice(newline + 1);
+        // `split` yields a plain array, so a short header really can leave these
+        // undefined even though the declared element type says otherwise.
+        const [sha, author, email, date, _subject] = header.split(US);
+        if (sha === undefined || date === undefined)
+            continue;
+        commitCount += 1;
+        if (newestCommit === '' || date > newestCommit)
+            newestCommit = date;
+        if (oldestCommit === '' || date < oldestCommit)
+            oldestCommit = date;
+        const key = `${author ?? '?'} <${email ?? '?'}>`;
+        let entry = authorMap.get(key);
+        if (entry === undefined) {
+            entry = {
+                name: author ?? '?',
+                email: email ?? '?',
+                commits: 0,
+                insertions: 0,
+                deletions: 0,
+                files: 0,
+                lastCommit: date,
+                fileSet: new Set(),
+            };
+            authorMap.set(key, entry);
+        }
+        entry.commits += 1;
+        if (date > entry.lastCommit)
+            entry.lastCommit = date;
+        let commitInsertions = 0;
+        let commitDeletions = 0;
+        for (const line of body.split('\n')) {
+            if (line.trim() === '')
+                continue;
+            const parts = line.split('\t');
+            if (parts.length < 3)
+                continue;
+            const [addedRaw, deletedRaw, ...pathParts] = parts;
+            const filePath = pathParts.join('\t');
+            if (filePath === '')
+                continue;
+            // `-` marks a binary file in --numstat; it counts as a change with no
+            // line delta, which is the truthful reading.
+            const added = Number.parseInt(addedRaw, 10);
+            const deleted = Number.parseInt(deletedRaw, 10);
+            const ins = Number.isFinite(added) ? added : 0;
+            const del = Number.isFinite(deleted) ? deleted : 0;
+            totalInsertions += ins;
+            totalDeletions += del;
+            commitInsertions += ins;
+            commitDeletions += del;
+            entry.insertions += ins;
+            entry.deletions += del;
+            entry.fileSet.add(filePath);
+            let file = files.get(filePath);
+            if (file === undefined) {
+                file = { path: filePath, changes: 0, insertions: 0, deletions: 0, lastChange: date };
+                files.set(filePath, file);
+            }
+            file.changes += 1;
+            file.insertions += ins;
+            file.deletions += del;
+            if (date > file.lastChange)
+                file.lastChange = date;
+        }
+        stamps.push({ date, insertions: commitInsertions, deletions: commitDeletions });
+    }
+    const toActivityFile = (file) => {
+        const verdict = classified ? classify(file.path) : 'excluded';
+        return { ...file, indexed: verdict === 'indexed', verdict };
+    };
+    const byChanges = [...files.values()]
+        .sort((a, b) => b.changes - a.changes || (a.path < b.path ? -1 : 1))
+        .slice(0, maxFiles)
+        .map(toActivityFile);
+    const byRecency = [...files.values()]
+        .sort((a, b) => (a.lastChange < b.lastChange ? 1 : a.lastChange > b.lastChange ? -1 : 0))
+        .slice(0, maxFiles)
+        .map(toActivityFile);
+    authors.push(...[...authorMap.values()]
+        .sort((a, b) => b.commits - a.commits)
+        .slice(0, maxAuthors)
+        .map(({ fileSet, ...rest }) => ({
+        ...rest,
+        files: fileSet.size,
+        bot: looksLikeBot(rest.name, rest.email),
+    })));
+    const branchRaw = await git(repoPath, [
+        'for-each-ref',
+        `--count=${maxBranches}`,
+        '--sort=-committerdate',
+        `--format=%(refname:short)${US}%(committerdate:iso-strict)${US}%(authorname)${US}%(HEAD)`,
+        'refs/heads',
+    ]);
+    const branches = [];
+    if (branchRaw !== null) {
+        for (const line of branchRaw.split('\n')) {
+            if (line.trim() === '')
+                continue;
+            const [name, date, author, head] = line.split(US);
+            if (name === undefined)
+                continue;
+            branches.push({
+                name,
+                lastCommitDate: date ?? '',
+                lastAuthor: author ?? '',
+                current: head === '*',
+            });
+        }
+    }
+    const verdictCounts = { indexed: 0, excluded: 0, missing: 0 };
+    for (const path of files.keys()) {
+        verdictCounts[classified ? classify(path) : 'excluded'] += 1;
+    }
+    // Kept out of the `byChanges`/`byRecency` display caps on purpose. Those caps
+    // exist to bound a list a reader browses; "missing from the index" is the
+    // actionable subset, and a first revision lost it there — the summary reported
+    // "1 MISSING" and then listed nothing, because the file was not among the 200
+    // most-changed. A count with no rows is worse than no count.
+    const missingFiles = [...files.values()]
+        .filter((file) => classified && classify(file.path) === 'missing')
+        .sort((a, b) => b.changes - a.changes || (a.path < b.path ? -1 : 1))
+        .slice(0, 50)
+        .map(toActivityFile);
+    return {
+        window: {
+            sinceDays,
+            since,
+            maxCommits,
+            maxFiles,
+            // A capped log that does not say so reads as "this is all the activity there
+            // was" — the one conclusion the caller must not draw.
+            truncated: commitCount >= maxCommits,
+            oldestCommit: oldestCommit === '' ? null : oldestCommit,
+            newestCommit: newestCommit === '' ? null : newestCommit,
+        },
+        totals: {
+            commits: commitCount,
+            authors: authorMap.size,
+            bots: authors.filter((a) => a.bot).length,
+            files: files.size,
+            insertions: totalInsertions,
+            deletions: totalDeletions,
+            verdicts: verdictCounts,
+            indexKnown: classified,
+            // Kept under their original names so a caller written against the first
+            // revision keeps working; `verdicts` is the richer view.
+            filesTouchedThatAreIndexed: verdictCounts.indexed,
+            filesTouchedThatAreNotIndexed: verdictCounts.excluded + verdictCounts.missing,
+        },
+        authors,
+        byChanges,
+        byRecency,
+        missingFiles,
+        branches,
+        histogram: buildHistogram(stamps, sinceDays),
+        currentBranch: branches.find((b) => b.current)?.name ?? null,
+    };
+}
+//# sourceMappingURL=git-activity.js.map

package/lib/gitnexus/git-activity.js.map

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

package/lib/gitnexus/git.d.ts

@@ -0,0 +1,70 @@
+/**
+ * The two git facts the panel needs, read without a shell.
+ *
+ * Deliberately not `exec`: a repository path is caller-supplied, and the only way
+ * to keep it from becoming an argument is to pass it as `cwd` and never as part of
+ * a command string. No shell is spawned, so nothing in the path can be
+ * interpreted.
+ *
+ * Both calls are bounded and both fail soft. A repository with no commits, a
+ * detached worktree, or no git at all is a normal state for an index that still
+ * has a valid manifest — the panel should say "unknown", not refuse to render.
+ */
+/**
+ * How far each side has moved from the other, as `rev-list --left-right --count`
+ * reports it: commits the indexed commit has that HEAD does not, and the reverse.
+ */
+export interface AheadBehind {
+    /** commits the index side has that HEAD does not */
+    behind: number;
+    /** commits HEAD has that the index side does not */
+    ahead: number;
+}
+export interface GitState {
+    /** git answered at all */
+    available: boolean;
+    /** full sha of HEAD */
+    headCommit: string | null;
+    /** current branch, or null when detached */
+    branch: string | null;
+    /** tracked modifications plus untracked files */
+    dirtyCount: number | null;
+    /** commits ahead/behind the indexed commit */
+    aheadBehind: AheadBehind | null;
+}
+/**
+ * Read HEAD, branch and working-tree dirtiness.
+ *
+ * @returns the state, with every unanswerable field left `null`
+ */
+export declare function readGitState(repoPath: string, indexedCommit?: string | null): Promise<GitState>;
+/** The states {@link classifyStaleness} can report. */
+export type StalenessState = 'current' | 'behind' | 'diverged' | 'unknown';
+/** What {@link classifyStaleness} judges: the indexed commit and the live git state. */
+export interface StalenessInput {
+    lastCommit: string | null;
+    git: GitState;
+}
+/**
+ * Classify staleness the way `gitnexus status` does, so the panel and the CLI
+ * cannot disagree.
+ *
+ * READING `rev-list --left-right --count <indexed>...<HEAD>`
+ * ---------------------------------------------------------
+ * The output is `<left> <right>`: commits reachable from the first ref but not the
+ * second, then the reverse. With the indexed commit first:
+ *
+ *   left  = commits the INDEX has that HEAD does not  → histories have split
+ *   right = commits HEAD has that the index does not  → how far the index lags
+ *
+ * So a linear fast-forward is `left = 0, right = N`: the index is simply N commits
+ * behind, and calling that "diverged" is wrong. Divergence requires `left > 0` —
+ * the indexed commit carries work that HEAD no longer reaches, which is when the
+ * distance between them stops measuring how stale the index is.
+ *
+ * A first revision had this exactly backwards, and the panel told an operator their
+ * index had diverged when it was one ordinary commit behind. The condition is
+ * asserted in both directions by `test/run.mjs` for that reason.
+ */
+export declare function classifyStaleness({ lastCommit, git }: StalenessInput): StalenessState;
+//# sourceMappingURL=git.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"git.d.ts","sourceRoot":"","sources":["../../src/gitnexus/git.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AA6CH;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,oDAAoD;IACpD,MAAM,EAAE,MAAM,CAAC;IACf,oDAAoD;IACpD,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,QAAQ;IACvB,0BAA0B;IAC1B,SAAS,EAAE,OAAO,CAAC;IACnB,uBAAuB;IACvB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,4CAA4C;IAC5C,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,iDAAiD;IACjD,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,8CAA8C;IAC9C,WAAW,EAAE,WAAW,GAAG,IAAI,CAAC;CACjC;AAED;;;;GAIG;AACH,wBAAsB,YAAY,CAChC,QAAQ,EAAE,MAAM,EAChB,aAAa,GAAE,MAAM,GAAG,IAAW,GAClC,OAAO,CAAC,QAAQ,CAAC,CA0CnB;AAED,uDAAuD;AACvD,MAAM,MAAM,cAAc,GAAG,SAAS,GAAG,QAAQ,GAAG,UAAU,GAAG,SAAS,CAAC;AAE3E,wFAAwF;AACxF,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,GAAG,EAAE,QAAQ,CAAC;CACf;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,iBAAiB,CAAC,EAAE,UAAU,EAAE,GAAG,EAAE,EAAE,cAAc,GAAG,cAAc,CAOrF"}

package/lib/gitnexus/git.js

@@ -0,0 +1,121 @@
+/**
+ * The two git facts the panel needs, read without a shell.
+ *
+ * Deliberately not `exec`: a repository path is caller-supplied, and the only way
+ * to keep it from becoming an argument is to pass it as `cwd` and never as part of
+ * a command string. No shell is spawned, so nothing in the path can be
+ * interpreted.
+ *
+ * Both calls are bounded and both fail soft. A repository with no commits, a
+ * detached worktree, or no git at all is a normal state for an index that still
+ * has a valid manifest — the panel should say "unknown", not refuse to render.
+ */
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+/**
+ * `execFile`, promisified.
+ *
+ * The assertion picks out the text-encoding result: no `encoding` is passed, so
+ * Node decodes stdout as UTF-8, and the `Buffer` arm the generic overload admits
+ * is one this call never takes.
+ */
+const run = promisify(execFile);
+/** Short cap: `rev-parse` and `status` on a large repo are fast, and a hang here
+ *  would block the whole panel for a value that is merely informative. */
+const TIMEOUT_MS = 8000;
+/**
+ * @returns trimmed stdout, or null on any failure
+ */
+async function git(repoPath, args) {
+    try {
+        const { stdout } = await run('git', args, {
+            cwd: repoPath,
+            timeout: TIMEOUT_MS,
+            windowsHide: true,
+            maxBuffer: 8 * 1024 * 1024,
+        });
+        return stdout;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Read HEAD, branch and working-tree dirtiness.
+ *
+ * @returns the state, with every unanswerable field left `null`
+ */
+export async function readGitState(repoPath, indexedCommit = null) {
+    const head = await git(repoPath, ['rev-parse', 'HEAD']);
+    if (head === null) {
+        return {
+            available: false,
+            headCommit: null,
+            branch: null,
+            dirtyCount: null,
+            aheadBehind: null,
+        };
+    }
+    const [branchRaw, statusRaw] = await Promise.all([
+        git(repoPath, ['rev-parse', '--abbrev-ref', 'HEAD']),
+        git(repoPath, ['status', '--porcelain']),
+    ]);
+    let dirtyCount = null;
+    if (statusRaw !== null) {
+        dirtyCount = statusRaw.split('\n').filter((line) => line.trim() !== '').length;
+    }
+    // How far HEAD has moved from the indexed commit, when both are known. Counted
+    // in one direction only: what matters for staleness is whether the index is
+    // behind, and a diverged history is reported as such rather than counted.
+    let aheadBehind = null;
+    const indexed = typeof indexedCommit === 'string' && indexedCommit !== '' ? indexedCommit : null;
+    if (indexed !== null) {
+        const counts = await git(repoPath, ['rev-list', '--left-right', '--count', `${indexed}...HEAD`]);
+        if (counts !== null) {
+            const [behind, ahead] = counts.trim().split(/\s+/).map((n) => Number.parseInt(n, 10));
+            if (Number.isFinite(behind) && Number.isFinite(ahead))
+                aheadBehind = { behind, ahead };
+        }
+    }
+    return {
+        available: true,
+        headCommit: head.trim(),
+        branch: branchRaw === null ? null : branchRaw.trim() === 'HEAD' ? null : branchRaw.trim(),
+        dirtyCount,
+        aheadBehind,
+    };
+}
+/**
+ * Classify staleness the way `gitnexus status` does, so the panel and the CLI
+ * cannot disagree.
+ *
+ * READING `rev-list --left-right --count <indexed>...<HEAD>`
+ * ---------------------------------------------------------
+ * The output is `<left> <right>`: commits reachable from the first ref but not the
+ * second, then the reverse. With the indexed commit first:
+ *
+ *   left  = commits the INDEX has that HEAD does not  → histories have split
+ *   right = commits HEAD has that the index does not  → how far the index lags
+ *
+ * So a linear fast-forward is `left = 0, right = N`: the index is simply N commits
+ * behind, and calling that "diverged" is wrong. Divergence requires `left > 0` —
+ * the indexed commit carries work that HEAD no longer reaches, which is when the
+ * distance between them stops measuring how stale the index is.
+ *
+ * A first revision had this exactly backwards, and the panel told an operator their
+ * index had diverged when it was one ordinary commit behind. The condition is
+ * asserted in both directions by `test/run.mjs` for that reason.
+ */
+export function classifyStaleness({ lastCommit, git }) {
+    if (!git.available || git.headCommit === null)
+        return 'unknown';
+    if (typeof lastCommit !== 'string' || lastCommit === '')
+        return 'unknown';
+    if (git.headCommit === lastCommit)
+        return 'current';
+    if (git.aheadBehind === null)
+        return 'unknown';
+    // `left > 0` means the indexed commit holds commits HEAD does not reach.
+    return git.aheadBehind.behind > 0 ? 'diverged' : 'behind';
+}
+//# sourceMappingURL=git.js.map

package/lib/gitnexus/git.js.map

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