dsh-gitnexus-plus 0.0.0-stage → 0.1.2

package/lib/gitnexus/format.js

@@ -0,0 +1,178 @@
+/**
+ * Plain-text rendering of a coverage report.
+ *
+ * Kept free of any DSH import so it can be tested — and reused — without a host
+ * running. Tool output is read by a model as often as by a person, so there is no
+ * ANSI here; `bin/gitnexus-coverage.mjs` owns the colourised terminal variant.
+ */
+import { formatBytes, } from './coverage.js';
+/**
+ * Render a coverage report as plain text.
+ *
+ * @param report the report to render
+ * @param withLanguages include the per-language breakdown
+ */
+export function formatReport(report, withLanguages = true) {
+    const lines = [];
+    const { repo, cap, totals } = report;
+    if (!repo.indexed) {
+        return (`GitNexus index: NOT FOUND\n${repo.path}\n` +
+            'No .gitnexus/gitnexus.json or .gitnexus/meta.json — run `gitnexus analyze` first.');
+    }
+    lines.push(`GitNexus coverage · ${repo.name}`);
+    lines.push(`  ${repo.path}`);
+    lines.push(`  indexed ${repo.indexedAt} · ${repo.branch ?? 'unknown'}@${(repo.lastCommit || 'unknown').slice(0, 8)}` +
+        ` · manifest ${repo.metaFile ?? 'unknown'} · GitNexus ${report.analyzer.gitnexusVersion}`);
+    lines.push(`  scanned ${totals.scanned} · selected ${totals.selected} · in graph ${totals.indexedInGraph}` +
+        ` · skipped ${totals.large} · declarations suppressed ${totals.suppressedDeclarations}`);
+    lines.push(`  size cap ${cap.text} (${cap.source})`);
+    // Freshness. The commit above is the *indexed* one; without this line a reader
+    // takes it for HEAD, which on a real repository it was not.
+    if (report.staleness !== undefined && report.staleness !== null) {
+        const s = report.staleness;
+        const short = (sha) => (typeof sha === 'string' && sha !== '' ? sha.slice(0, 8) : '?');
+        // `dirtyCount` is null when git could not be asked at all — which must not render
+        // as "0 uncommitted", because that is a claim about the tree, not an absence of
+        // information.
+        const dirtyCount = s.dirtyCount;
+        const dirty = dirtyCount !== null && dirtyCount > 0 ? `, ${dirtyCount} uncommitted` : '';
+        if (s.gitAvailable !== true) {
+            lines.push('  freshness unknown (git unavailable)');
+        }
+        else if (s.state === 'current') {
+            lines.push(`  freshness current — HEAD ${short(s.headCommit)} matches the index${dirty}`);
+        }
+        else if (s.state === 'behind') {
+            // `ahead`, not `behind`. `rev-list --left-right --count <indexed>...<HEAD>`
+            // reports the index side first, so a linear fast-forward is `behind: 0` — the
+            // distance the index lags is `ahead`. Reading `.behind` here printed
+            // "index is 0 commit(s) behind" for an index that was one commit behind, which
+            // is how this was caught: the deployed plugin's own tool output said it.
+            const lag = s.aheadBehind?.ahead ?? '?';
+            lines.push(`  freshness BEHIND — index is ${lag} commit(s) behind ` +
+                `(${short(s.indexedCommit)} -> ${short(s.headCommit)})${dirty}`);
+        }
+        else if (s.state === 'diverged') {
+            lines.push(`  freshness DIVERGED — HEAD ${short(s.headCommit)} is not on the indexed commit ` +
+                `${short(s.indexedCommit)}; the gap is not countable${dirty}`);
+        }
+        else {
+            lines.push(`  freshness unknown — cannot compare ${short(s.indexedCommit)} with ${short(s.headCommit)}${dirty}`);
+        }
+    }
+    // What the graph holds, and which query surfaces are live. Both were already in
+    // the manifest and previously went unreported.
+    if (report.graph !== null && report.graph !== undefined) {
+        const g = report.graph;
+        lines.push(`  graph: ${g.nodes} nodes, ${g.edges} edges, ${g.communities} communities, ` +
+            `${g.processes} processes, ${g.embeddings} embeddings (${g.edgesPerNode.toFixed(2)} edges/node)`);
+    }
+    const caps = report.capabilities ?? {};
+    const capNames = ['graph', 'fts', 'vectorSearch'];
+    if (capNames.some((n) => caps[n] !== undefined)) {
+        lines.push(`  query surfaces: ${capNames
+            .map((n) => {
+            const entry = caps[n];
+            if (entry === undefined)
+                return `${n}=absent`;
+            return entry.status === 'available'
+                ? `${n}=available`
+                : `${n}=UNAVAILABLE (${entry.skipReason ?? entry.status})`;
+        })
+            .join(', ')}`);
+    }
+    if (report.largeFiles.length > 0) {
+        lines.push('');
+        lines.push(`Skipped large files (${report.largeFiles.length}, ${formatBytes(totals.largeBytes)}):`);
+        for (const file of report.largeFiles.slice(0, 30)) {
+            const flags = [];
+            if (file.minified?.binary)
+                flags.push('binary asset — cannot hold symbols');
+            else if (file.minified?.suspect) {
+                flags.push(`single-line ~${Math.round(file.minified.avgLineLength)} chars`);
+            }
+            if (file.generatedHint)
+                flags.push('generated-output path');
+            const share = file.shareOfLanguage > 0
+                ? ` (${(file.shareOfLanguage * 100).toFixed(0)}% of ${file.language.label})`
+                : '';
+            lines.push(`  ${file.sizeText.padStart(9)}  ${file.path}${share}` +
+                `${flags.length > 0 ? `  [${flags.join('; ')}]` : ''}`);
+        }
+        if (report.largeFiles.length > 30)
+            lines.push(`  …and ${report.largeFiles.length - 30} more`);
+    }
+    if (withLanguages && report.languages !== null) {
+        lines.push('');
+        lines.push(`Languages (${report.languages.rows.length}, by bytes):`);
+        const total = report.languages.totalBytes || 1;
+        for (const row of report.languages.rows.slice(0, 15)) {
+            lines.push(`  ${row.label.padEnd(14)} ${((row.bytes / total) * 100).toFixed(1).padStart(5)}%` +
+                `  ${row.files} files  ${row.klass}`);
+        }
+        if (report.languages.rows.length > 15) {
+            lines.push(`  …and ${report.languages.rows.length - 15} more`);
+        }
+    }
+    const notable = report.warnings.filter((w) => w.level === 'warn');
+    if (notable.length > 0) {
+        lines.push('');
+        for (const w of notable)
+            lines.push(`  ! ${w.message}`);
+    }
+    const info = report.warnings.filter((w) => w.level === 'info');
+    if (info.length > 0) {
+        lines.push('');
+        for (const w of info)
+            lines.push(`  - ${w.message}`);
+    }
+    // Git activity crossed with the index. The three-way verdict is the point: a
+    // bare "not indexed" count reads as a defect, when most of it is files no scan
+    // would select either (lockfiles, dotfiles, binary assets).
+    const activity = report.activity;
+    if (activity !== null && activity !== undefined) {
+        const v = activity.totals.verdicts;
+        lines.push('');
+        lines.push(`Git activity, last ${activity.window.sinceDays} days` +
+            `${activity.window.truncated ? ` (capped at ${activity.window.maxCommits} commits)` : ''}: ` +
+            `${activity.totals.commits} commits by ${activity.totals.authors} author(s)` +
+            `${activity.totals.bots > 0 ? ` (${activity.totals.bots} bot)` : ''}, ` +
+            `+${activity.totals.insertions}/-${activity.totals.deletions} lines across ${activity.totals.files} file(s)`);
+        lines.push(`  touched files: ${v.indexed} indexed, ${v.missing} MISSING from the index, ${v.excluded} excluded by design`);
+        if (v.missing > 0) {
+            lines.push('  files that should be indexed but are not:');
+            const missing = activity.missingFiles ?? activity.byChanges.filter((f) => f.verdict === 'missing');
+            for (const file of missing.slice(0, 10)) {
+                lines.push(`    ${String(file.changes).padStart(3)}x  ${file.path}`);
+            }
+            if (missing.length < v.missing)
+                lines.push(`    …and ${v.missing - missing.length} more`);
+        }
+        if (activity.byChanges.some((f) => f.verdict === 'indexed')) {
+            lines.push('  most-changed indexed files:');
+            for (const file of activity.byChanges.filter((f) => f.verdict === 'indexed').slice(0, 5)) {
+                lines.push(`    ${String(file.changes).padStart(3)}x  ${file.path}`);
+            }
+        }
+        if (activity.authors.length > 0) {
+            lines.push(`  authors: ${activity.authors
+                .slice(0, 5)
+                .map((a) => `${a.name}${a.bot ? ' [bot]' : ''} (${a.commits})`)
+                .join(', ')}`);
+        }
+    }
+    const quality = report.graphQuality;
+    if (quality !== null && quality !== undefined && quality.counts !== undefined) {
+        const names = Object.entries(quality.counts)
+            .sort((a, b) => b[1] - a[1])
+            .slice(0, 6)
+            .map(([name, count]) => `${name} ${count}`);
+        lines.push('');
+        lines.push(`  resolver: ${quality.totalSites ?? 0} untyped receiver site(s) — while these exist, ` +
+            `impact/context results are a LOWER BOUND, not exact`);
+        if (names.length > 0)
+            lines.push(`    ${names.join(', ')}`);
+    }
+    return lines.join('\n');
+}
+//# sourceMappingURL=format.js.map

package/lib/gitnexus/format.js.map

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

package/lib/gitnexus/git-activity.d.ts

@@ -0,0 +1,136 @@
+/**
+ * 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.
+ */
+/**
+ *   indexed  — the manifest holds this path, so the graph can answer about it.
+ *   excluded — a fresh scan would not select it either (dotfile, ignore rule, or
+ *              over the size cap). Absent by design; not a staleness signal.
+ *   missing  — a fresh scan *would* select it, but the index does not hold it.
+ *              This is the only verdict that means the index is behind.
+ */
+export type FileVerdict = 'indexed' | 'excluded' | 'missing';
+export interface ActivityFile {
+    path: string;
+    /** commits touching this file */
+    changes: number;
+    insertions: number;
+    deletions: number;
+    /** ISO date of the most recent change */
+    lastChange: string;
+    indexed: boolean;
+    verdict: FileVerdict;
+}
+export interface ActivityAuthor {
+    name: string;
+    email: string;
+    commits: number;
+    insertions: number;
+    deletions: number;
+    /** distinct files touched */
+    files: number;
+    lastCommit: string;
+    /** machine account, judged from the conventional markers */
+    bot: boolean;
+}
+export interface ActivityBranch {
+    name: string;
+    lastCommitDate: string;
+    lastAuthor: string;
+    current: boolean;
+}
+export interface HistogramBucket {
+    label: string;
+    commits: number;
+    insertions: number;
+    deletions: number;
+}
+export interface ActivityHistogram {
+    bucketDays: number;
+    buckets: HistogramBucket[];
+}
+/** One commit-stamp feeding the histogram. */
+export interface ActivityStamp {
+    date: string;
+    insertions: number;
+    deletions: number;
+}
+export interface ActivityWindow {
+    sinceDays: number;
+    since: string;
+    maxCommits: number;
+    maxFiles: number;
+    truncated: boolean;
+    oldestCommit: string | null;
+    newestCommit: string | null;
+}
+export interface ActivityTotals {
+    commits: number;
+    authors: number;
+    bots: number;
+    files: number;
+    insertions: number;
+    deletions: number;
+    verdicts: Record<FileVerdict, number>;
+    indexKnown: boolean;
+    filesTouchedThatAreIndexed: number;
+    filesTouchedThatAreNotIndexed: number;
+}
+export interface ActivityInfo {
+    window: ActivityWindow;
+    totals: ActivityTotals;
+    authors: ActivityAuthor[];
+    byChanges: ActivityFile[];
+    byRecency: ActivityFile[];
+    missingFiles: ActivityFile[];
+    branches: ActivityBranch[];
+    histogram: ActivityHistogram;
+    currentBranch: string | null;
+}
+export interface ReadGitActivityOptions {
+    sinceDays?: number;
+    maxCommits?: number;
+    maxFiles?: number;
+    maxAuthors?: number;
+    maxBranches?: number;
+    indexedPaths?: Iterable<string>;
+    scannablePaths?: Iterable<string>;
+}
+/**
+ * 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 declare function buildHistogram(stamps: ActivityStamp[], sinceDays: number): ActivityHistogram;
+/**
+ * Read recent commits, authors, changed files and branches.
+ *
+ * Returns `null` when git cannot answer at all.
+ */
+export declare function readGitActivity(repoPath: string, options?: ReadGitActivityOptions): Promise<ActivityInfo | null>;
+//# sourceMappingURL=git-activity.d.ts.map

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

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