@monoes/monograph 1.3.0 → 1.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@monoes/monograph",
-  "version": "1.3.0",
+  "version": "1.4.1",
   "type": "module",
   "description": "Native TypeScript code intelligence engine for monomind",
   "main": "dist/src/index.js",
@@ -11,6 +11,9 @@
       "import": "./dist/src/index.js"
     }
   },
+  "engines": {
+    "node": ">=20.0.0"
+  },
   "publishConfig": {
     "access": "public",
     "tag": "latest"
@@ -50,7 +53,7 @@
     "@types/express": "^5.0.0",
     "@types/micromatch": "^4.0.10",
     "@types/node": "^20.0.0",
-    "typescript": "^5.3.0",
+    "typescript": "^7.0.2",
     "vitest": "^4.1.4"
   }
 }

package/src/__tests__/graph/dead-code.test.ts

@@ -34,6 +34,11 @@ function insertCallEdge(db: Database.Database, src: string, tgt: string) {
     .run(`${src}_${tgt}_calls`, src, tgt);
 }
 
+function insertReExportEdge(db: Database.Database, srcFileId: string, tgtFileId: string) {
+  db.prepare(`INSERT INTO edges (id, source_id, target_id, relation, confidence, confidence_score) VALUES (?, ?, ?, 'RE_EXPORTS', 'INFERRED', 0.8)`)
+    .run(`${srcFileId}_${tgtFileId}_reexports`, srcFileId, tgtFileId);
+}
+
 describe('detectDeadCode', () => {
   it('returns empty array for empty graph', () => {
     const db = makeTempDb();
@@ -93,24 +98,39 @@ describe('detectDeadCode', () => {
     db.close();
   });
 
-  it('skips functions with same-name node in another file', () => {
+  it('does NOT suppress on a same-name coincidence alone (no real edge)', () => {
+    // Regression test for P2-18(a): the old suppression matched on NAME EQUALITY
+    // anywhere in the codebase, so a genuinely-dead `shared()` in a.ts was hidden
+    // just because an unrelated `shared` also existed in b.ts. With no actual
+    // RE_EXPORTS/IMPORTS edge between them, the candidate must still be flagged.
     const db = makeTempDb();
     insertFileNode(db, 'src/a.ts');
     insertFileNode(db, 'src/b.ts');
-    insertFunction(db, 'shared', 'src/a.ts', { exported: true });
-    // Same name in another file (import binding)
+    const id = insertFunction(db, 'shared', 'src/a.ts', { exported: true });
     insertFunction(db, 'shared', 'src/b.ts', { exported: false });
-    expect(detectDeadCode(db)).toEqual([]);
+    expect(detectDeadCode(db)).toContain(id);
     db.close();
   });
 
-  it('skips functions re-exported through barrel index', () => {
+  it('does NOT suppress on same-name-in-index.ts alone (no real RE_EXPORTS edge)', () => {
+    // Regression test for P2-18(a): a function sharing a name with something
+    // index.ts happens to also define is not the same as being re-exported by it.
     const db = makeTempDb();
     insertFileNode(db, 'src/utils.ts');
     insertFileNode(db, 'src/index.ts');
-    insertFunction(db, 'helper', 'src/utils.ts', { exported: true });
-    // Same name in index.ts (barrel re-export)
+    const id = insertFunction(db, 'helper', 'src/utils.ts', { exported: true });
     insertFunction(db, 'helper', 'src/index.ts', { exported: true });
+    expect(detectDeadCode(db)).toContain(id);
+    db.close();
+  });
+
+  it('skips functions re-exported through a REAL RE_EXPORTS edge from a barrel', () => {
+    const db = makeTempDb();
+    const utilsFileId = insertFileNode(db, 'src/utils.ts');
+    const indexFileId = insertFileNode(db, 'src/index.ts');
+    insertFunction(db, 'helper', 'src/utils.ts', { exported: true });
+    // Actual barrel edge: src/index.ts RE_EXPORTS src/utils.ts's File node.
+    insertReExportEdge(db, indexFileId, utilsFileId);
     expect(detectDeadCode(db)).toEqual([]);
     db.close();
   });

package/src/__tests__/pipeline/phases/bridge-adapters/electron-ipc.test.ts

@@ -0,0 +1,87 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdtempSync, writeFileSync, mkdirSync, rmSync } from 'fs';
+import { join, dirname } from 'path';
+import { tmpdir } from 'os';
+import Database from 'better-sqlite3';
+import { openDb, closeDb } from '../../../../storage/db.js';
+import { insertNodes } from '../../../../storage/node-store.js';
+import type { MonographNode } from '../../../../types.js';
+import type { PipelineContext } from '../../../../pipeline/types.js';
+import { DEFAULT_OPTIONS } from '../../../../pipeline/types.js';
+import { electronIpcAdapter } from '../../../../pipeline/phases/bridge-adapters/electron-ipc.js';
+
+function makeCtx(repoPath: string, db: Database.Database): PipelineContext {
+  return {
+    repoPath,
+    db,
+    graph: undefined as never,
+    onProgress: () => {},
+    options: DEFAULT_OPTIONS,
+  };
+}
+
+function writeFile(root: string, relPath: string, content: string): void {
+  const full = join(root, relPath);
+  mkdirSync(dirname(full), { recursive: true });
+  writeFileSync(full, content, 'utf-8');
+}
+
+function fileNode(id: string, filePath: string): MonographNode {
+  return {
+    id, label: 'File', name: filePath.split('/').pop()!, normLabel: '', filePath,
+    isExported: false,
+  };
+}
+
+describe('electronIpcAdapter', () => {
+  let tmpDir: string;
+  let db: Database.Database;
+
+  beforeEach(() => {
+    tmpDir = mkdtempSync(join(tmpdir(), 'electron-ipc-bridge-test-'));
+    db = openDb(join(tmpDir, 'test.db'));
+  });
+
+  afterEach(() => {
+    closeDb(db);
+    rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it('detects a repo with both ipcMain and ipcRenderer usage', () => {
+    writeFile(tmpDir, 'main.js', `ipcMain.handle('get-data', () => {});`);
+    writeFile(tmpDir, 'renderer.js', `ipcRenderer.invoke('get-data');`);
+    const ctx = makeCtx(tmpDir, db);
+    expect(electronIpcAdapter.detect(ctx, ['main.js', 'renderer.js'])).toBe(true);
+  });
+
+  it('does not detect main-only usage (no renderer side)', () => {
+    writeFile(tmpDir, 'main.js', `ipcMain.handle('get-data', () => {});`);
+    const ctx = makeCtx(tmpDir, db);
+    expect(electronIpcAdapter.detect(ctx, ['main.js'])).toBe(false);
+  });
+
+  it('links a channel from ipcMain.handle to ipcRenderer.invoke by name', () => {
+    writeFile(tmpDir, 'main.js', `ipcMain.handle('get-data', () => fetchData());`);
+    writeFile(tmpDir, 'renderer.js', `const data = await ipcRenderer.invoke('get-data');`);
+    insertNodes(db, [fileNode('main_file', 'main.js'), fileNode('renderer_file', 'renderer.js')]);
+    const ctx = makeCtx(tmpDir, db);
+
+    const defs = electronIpcAdapter.findDefinitions(ctx, ['main.js', 'renderer.js']);
+    expect(defs).toEqual([{ key: 'get-data', nodeId: 'main_file', language: 'javascript' }]);
+
+    const sites = electronIpcAdapter.findCallSites(ctx, ['main.js', 'renderer.js']);
+    expect(sites).toEqual([{ key: 'get-data', nodeId: 'renderer_file', language: 'javascript' }]);
+  });
+
+  it('also matches ipcMain.on / ipcRenderer.send', () => {
+    writeFile(tmpDir, 'main.js', `ipcMain.on('log', (e, msg) => console.log(msg));`);
+    writeFile(tmpDir, 'renderer.js', `ipcRenderer.send('log', 'hello');`);
+    insertNodes(db, [fileNode('main_file', 'main.js'), fileNode('renderer_file', 'renderer.js')]);
+    const ctx = makeCtx(tmpDir, db);
+
+    expect(electronIpcAdapter.findDefinitions(ctx, ['main.js']))
+      .toEqual([{ key: 'log', nodeId: 'main_file', language: 'javascript' }]);
+    expect(electronIpcAdapter.findCallSites(ctx, ['renderer.js']))
+      .toEqual([{ key: 'log', nodeId: 'renderer_file', language: 'javascript' }]);
+  });
+});

package/src/__tests__/pipeline/phases/bridge-adapters/tauri.test.ts

@@ -0,0 +1,116 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdtempSync, writeFileSync, mkdirSync, rmSync } from 'fs';
+import { join, dirname } from 'path';
+import { tmpdir } from 'os';
+import Database from 'better-sqlite3';
+import { openDb, closeDb } from '../../../../storage/db.js';
+import { insertNodes } from '../../../../storage/node-store.js';
+import type { MonographNode } from '../../../../types.js';
+import type { PipelineContext } from '../../../../pipeline/types.js';
+import { DEFAULT_OPTIONS } from '../../../../pipeline/types.js';
+import { tauriAdapter } from '../../../../pipeline/phases/bridge-adapters/tauri.js';
+
+function makeCtx(repoPath: string, db: Database.Database): PipelineContext {
+  return {
+    repoPath,
+    db,
+    graph: undefined as never,
+    onProgress: () => {},
+    options: DEFAULT_OPTIONS,
+  };
+}
+
+function writeFile(root: string, relPath: string, content: string): void {
+  const full = join(root, relPath);
+  mkdirSync(dirname(full), { recursive: true });
+  writeFileSync(full, content, 'utf-8');
+}
+
+function fnNode(id: string, name: string, filePath: string): MonographNode {
+  return {
+    id, label: 'Function', name, normLabel: name.toLowerCase(), filePath,
+    isExported: true, language: 'rust',
+  };
+}
+
+function fileNode(id: string, filePath: string): MonographNode {
+  return {
+    id, label: 'File', name: filePath.split('/').pop()!, normLabel: '', filePath,
+    isExported: false,
+  };
+}
+
+describe('tauriAdapter', () => {
+  let tmpDir: string;
+  let db: Database.Database;
+
+  beforeEach(() => {
+    tmpDir = mkdtempSync(join(tmpdir(), 'tauri-bridge-test-'));
+    db = openDb(join(tmpDir, 'test.db'));
+  });
+
+  afterEach(() => {
+    closeDb(db);
+    rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it('detects a repo with a #[tauri::command]-annotated Rust file', () => {
+    writeFile(tmpDir, 'src-tauri/src/main.rs', `
+#[tauri::command]
+fn greet(name: String) -> String {
+    format!("Hello, {}!", name)
+}
+`);
+    const ctx = makeCtx(tmpDir, db);
+    expect(tauriAdapter.detect(ctx, ['src-tauri/src/main.rs'])).toBe(true);
+  });
+
+  it('does not detect a repo with no Rust files', () => {
+    const ctx = makeCtx(tmpDir, db);
+    expect(tauriAdapter.detect(ctx, ['src/App.tsx'])).toBe(false);
+  });
+
+  it('does not detect a Rust file with no #[tauri::command] annotation', () => {
+    writeFile(tmpDir, 'src-tauri/src/main.rs', `
+fn internal_helper() -> i32 { 42 }
+`);
+    const ctx = makeCtx(tmpDir, db);
+    expect(tauriAdapter.detect(ctx, ['src-tauri/src/main.rs'])).toBe(false);
+  });
+
+  it('finds a #[tauri::command] fn matched to its existing Function node', () => {
+    writeFile(tmpDir, 'src-tauri/src/main.rs', `
+#[tauri::command]
+fn greet(name: String) -> String {
+    format!("Hello, {}!", name)
+}
+`);
+    insertNodes(db, [fnNode('rust_fn_1', 'greet', 'src-tauri/src/main.rs')]);
+    const ctx = makeCtx(tmpDir, db);
+    const defs = tauriAdapter.findDefinitions(ctx, ['src-tauri/src/main.rs']);
+    expect(defs).toEqual([{ key: 'greet', nodeId: 'rust_fn_1', language: 'rust' }]);
+  });
+
+  it('ignores a plain fn with no #[tauri::command] attribute', () => {
+    writeFile(tmpDir, 'src-tauri/src/main.rs', `
+fn internal_helper() -> i32 { 42 }
+`);
+    insertNodes(db, [fnNode('rust_fn_2', 'internal_helper', 'src-tauri/src/main.rs')]);
+    const ctx = makeCtx(tmpDir, db);
+    const defs = tauriAdapter.findDefinitions(ctx, ['src-tauri/src/main.rs']);
+    expect(defs).toEqual([]);
+  });
+
+  it('finds an invoke() call site attached to its containing File node', () => {
+    writeFile(tmpDir, 'src/App.tsx', `
+import { invoke } from '@tauri-apps/api/core';
+async function onClick() {
+  await invoke('greet', { name: 'world' });
+}
+`);
+    insertNodes(db, [fileNode('file_1', 'src/App.tsx')]);
+    const ctx = makeCtx(tmpDir, db);
+    const sites = tauriAdapter.findCallSites(ctx, ['src/App.tsx']);
+    expect(sites).toEqual([{ key: 'greet', nodeId: 'file_1', language: 'javascript' }]);
+  });
+});

package/src/__tests__/pipeline/phases/bridge-adapters/wails.test.ts

@@ -0,0 +1,81 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdtempSync, writeFileSync, mkdirSync, rmSync } from 'fs';
+import { join } from 'path';
+import { tmpdir } from 'os';
+import Database from 'better-sqlite3';
+import { openDb, closeDb } from '../../../../storage/db.js';
+import { insertNodes } from '../../../../storage/node-store.js';
+import type { MonographNode } from '../../../../types.js';
+import type { PipelineContext } from '../../../../pipeline/types.js';
+import { DEFAULT_OPTIONS } from '../../../../pipeline/types.js';
+import { wailsAdapter } from '../../../../pipeline/phases/bridge-adapters/wails.js';
+
+function makeCtx(repoPath: string, db: Database.Database): PipelineContext {
+  return {
+    repoPath,
+    db,
+    graph: undefined as never,
+    onProgress: () => {},
+    options: DEFAULT_OPTIONS,
+  };
+}
+
+function methodNode(id: string, name: string, filePath: string): MonographNode {
+  return {
+    id, label: 'Method', name, normLabel: name.toLowerCase(), filePath,
+    isExported: true, language: 'go',
+  };
+}
+
+function functionNode(id: string, name: string, filePath: string, language = 'typescript'): MonographNode {
+  return {
+    id, label: 'Function', name, normLabel: name.toLowerCase(), filePath,
+    isExported: true, language,
+  };
+}
+
+describe('wailsAdapter', () => {
+  let tmpDir: string;
+  let db: Database.Database;
+
+  beforeEach(() => {
+    tmpDir = mkdtempSync(join(tmpdir(), 'wails-bridge-test-'));
+    db = openDb(join(tmpDir, 'test.db'));
+  });
+
+  afterEach(() => {
+    closeDb(db);
+    rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it('detects a repo with a wailsjs/go binding directory', () => {
+    const ctx = makeCtx(tmpDir, db);
+    expect(wailsAdapter.detect(ctx, ['frontend/src/wailsjs/go/main/App.js'])).toBe(true);
+  });
+
+  it('does not detect a repo with no wails bindings', () => {
+    const ctx = makeCtx(tmpDir, db);
+    expect(wailsAdapter.detect(ctx, ['app.go', 'frontend/src/App.jsx'])).toBe(false);
+  });
+
+  it('finds Go methods as definitions', () => {
+    insertNodes(db, [methodNode('go_method_1', 'SendMessage', 'app.go')]);
+    const ctx = makeCtx(tmpDir, db);
+    const defs = wailsAdapter.findDefinitions(ctx, []);
+    expect(defs).toEqual([{ key: 'SendMessage', nodeId: 'go_method_1', language: 'go' }]);
+  });
+
+  it('finds wailsjs binding functions as call sites', () => {
+    insertNodes(db, [functionNode('js_fn_1', 'SendMessage', 'frontend/src/wailsjs/go/main/App.js')]);
+    const ctx = makeCtx(tmpDir, db);
+    const sites = wailsAdapter.findCallSites(ctx, []);
+    expect(sites).toEqual([{ key: 'SendMessage', nodeId: 'js_fn_1', language: 'typescript' }]);
+  });
+
+  it('does not treat a Function outside wailsjs/go/ as a call site', () => {
+    insertNodes(db, [functionNode('js_fn_2', 'SendMessage', 'frontend/src/services/api.js')]);
+    const ctx = makeCtx(tmpDir, db);
+    const sites = wailsAdapter.findCallSites(ctx, []);
+    expect(sites).toEqual([]);
+  });
+});

package/src/__tests__/pipeline/phases/bridge-resolver.test.ts

@@ -0,0 +1,110 @@
+import { describe, it, expect, afterEach } from 'vitest';
+import { mkdtempSync, writeFileSync, mkdirSync, rmSync } from 'fs';
+import { join, dirname } from 'path';
+import { tmpdir } from 'os';
+import Database from 'better-sqlite3';
+import { buildAsync } from '../../../pipeline/orchestrator.js';
+
+function writeFile(root: string, relPath: string, content: string): void {
+  const full = join(root, relPath);
+  mkdirSync(dirname(full), { recursive: true });
+  writeFileSync(full, content, 'utf-8');
+}
+
+function edgeRows(dbPath: string): { source_id: string; target_id: string; relation: string; confidence: string; reason: string | null }[] {
+  const db = new Database(dbPath, { readonly: true });
+  try {
+    return db.prepare(`SELECT source_id, target_id, relation, confidence, reason FROM edges`).all() as never[];
+  } finally {
+    db.close();
+  }
+}
+
+/** Bridge edges are tagged with a reason of the form "<adapter> bridge (<lang> -> <lang>): ...". */
+function isBridgeEdge(e: { reason: string | null }): boolean {
+  return !!e.reason && / bridge \(.+ -> .+\): /.test(e.reason);
+}
+
+describe('bridge-resolver (full pipeline)', () => {
+  let tmpDir: string;
+
+  afterEach(() => {
+    rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it('links a Wails Go method to its generated JS binding function', async () => {
+    tmpDir = mkdtempSync(join(tmpdir(), 'bridge-e2e-wails-'));
+
+    writeFile(tmpDir, 'app.go', `
+package main
+
+type App struct{}
+
+func (a *App) SendMessage(text string) error {
+	return nil
+}
+`);
+    writeFile(tmpDir, 'frontend/src/wailsjs/go/main/App.js', `
+export function SendMessage(arg1) {
+  return window['go']['main']['App']['SendMessage'](arg1);
+}
+`);
+    writeFile(tmpDir, 'frontend/src/App.jsx', `
+import { SendMessage } from './wailsjs/go/main/App';
+function onClick() { SendMessage('hi'); }
+`);
+
+    await buildAsync(tmpDir, { codeOnly: true });
+
+    const edges = edgeRows(join(tmpDir, '.monomind', 'monograph.db'));
+    const bridgeEdge = edges.find((e) => e.relation === 'CALLS' && e.confidence === 'INFERRED' && isBridgeEdge(e));
+    expect(bridgeEdge).toBeDefined();
+  });
+
+  it('does not emit a bridge edge when there is no matching Go method', async () => {
+    tmpDir = mkdtempSync(join(tmpdir(), 'bridge-e2e-wails-negative-'));
+
+    writeFile(tmpDir, 'app.go', `
+package main
+
+type App struct{}
+
+func (a *App) UnrelatedMethod() error {
+	return nil
+}
+`);
+    writeFile(tmpDir, 'frontend/src/wailsjs/go/main/App.js', `
+export function SendMessage(arg1) {
+  return window['go']['main']['App']['SendMessage'](arg1);
+}
+`);
+
+    await buildAsync(tmpDir, { codeOnly: true });
+
+    const db = new Database(join(tmpDir, '.monomind', 'monograph.db'), { readonly: true });
+    const jsFn = db.prepare(`SELECT id FROM nodes WHERE name = 'SendMessage' AND label = 'Function'`).get() as { id: string } | undefined;
+    db.close();
+    expect(jsFn).toBeDefined();
+
+    const edges = edgeRows(join(tmpDir, '.monomind', 'monograph.db'));
+    const bridgeEdgeToJsFn = edges.find((e) => e.target_id === jsFn!.id && isBridgeEdge(e));
+    expect(bridgeEdgeToJsFn).toBeUndefined();
+  });
+
+  it('does nothing in a repo with no bridge frameworks present', async () => {
+    tmpDir = mkdtempSync(join(tmpdir(), 'bridge-e2e-none-'));
+    writeFile(tmpDir, 'main.go', `
+package main
+
+func main() {
+	println("hello")
+}
+`);
+
+    await buildAsync(tmpDir, { codeOnly: true });
+
+    const edges = edgeRows(join(tmpDir, '.monomind', 'monograph.db'));
+    const bridgeEdges = edges.filter(isBridgeEdge);
+    expect(bridgeEdges).toEqual([]);
+  });
+});

package/src/analysis/changed-files.ts

@@ -1,4 +1,4 @@
-import { execSync } from 'child_process';
+import { execFileSync } from 'child_process';
 import * as path from 'path';
 
 export class ChangedFilesError extends Error {
@@ -8,9 +8,18 @@ export class ChangedFilesError extends Error {
   }
 }
 
+// Leading '-' is rejected explicitly (not just by the character class) so a
+// value like "--output=/tmp/pwned" can't be passed through and interpreted
+// by git as a command-line option instead of a ref (git option injection).
 const VALID_REF_RE = /^[a-zA-Z0-9\-_./@~^]+$/;
 
 export function validateGitRef(ref: string): string {
+  if (ref.startsWith('-')) {
+    throw new ChangedFilesError(
+      `Invalid git ref: "${ref}". Refs must not start with '-' (would be interpreted as a git option)`,
+      'invalid_ref',
+    );
+  }
   if (VALID_REF_RE.test(ref)) {
     return ref;
   }
@@ -25,7 +34,10 @@ export async function getChangedFiles(root: string, sinceRef: string): Promise<S
 
   let output: string;
   try {
-    output = execSync(`git diff --name-only -z ${sinceRef} HEAD`, {
+    // execFileSync with array argv — no shell involved, so a `root` (cwd)
+    // containing '"' or '$(...)' cannot break out and execute arbitrary
+    // commands.
+    output = execFileSync('git', ['diff', '--name-only', '-z', sinceRef, 'HEAD'], {
       cwd: root,
       encoding: 'utf8',
     });

package/src/analysis/changed-workspaces.ts

@@ -1,4 +1,4 @@
-import { execSync } from 'child_process';
+import { execFileSync } from 'child_process';
 import { existsSync, readdirSync, readFileSync } from 'fs';
 import { join, relative, resolve } from 'path';
 
@@ -48,15 +48,24 @@ export function getChangedWorkspaces(
   sinceRef: string,
   workspaceRoots?: string[],
 ): WorkspacePackage[] {
-  // Validate git ref (same allowlist as changed-files.ts)
+  // Validate git ref (same allowlist as changed-files.ts). Leading '-' is
+  // rejected explicitly so a value like "--output=/tmp/pwned" can't be
+  // interpreted by git as a command-line option (git option injection).
+  if (sinceRef.startsWith('-')) {
+    throw new Error(`Invalid git ref: "${sinceRef}". Refs must not start with '-' (would be interpreted as a git option)`);
+  }
   if (!/^[a-zA-Z0-9\-_./@~^]+$/.test(sinceRef)) {
     throw new Error(`Invalid git ref: "${sinceRef}"`);
   }
 
   let changedFiles: Set<string>;
   try {
-    const raw = execSync(
-      `git -C "${projectRoot}" diff --name-only "${sinceRef}"...HEAD`,
+    // execFileSync with array argv — no shell involved, so a `projectRoot`
+    // containing '"' or '$(...)' cannot break out and execute arbitrary
+    // commands.
+    const raw = execFileSync(
+      'git',
+      ['-C', projectRoot, 'diff', '--name-only', `${sinceRef}...HEAD`],
       { encoding: 'utf8' }
     );
     changedFiles = new Set(raw.split('\n').map(l => l.trim()).filter(Boolean));

package/src/analysis/churn.ts

@@ -1,5 +1,5 @@
 import { execSync } from 'child_process';
-import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync, unlinkSync } from 'fs';
 import { join, relative } from 'path';
 
 export type ChurnTrend = 'accelerating' | 'stable' | 'cooling';
@@ -59,7 +59,15 @@ export function computeRecencyWeight(ageDays: number): number {
   return Math.exp(-Math.LN2 * ageDays / 90);
 }
 
-export function classifyChurnTrend(recentWeighted: number, olderWeighted: number): ChurnTrend {
+export function classifyChurnTrend(
+  recentWeighted: number,
+  olderWeighted: number,
+  commitCount = 2,
+): ChurnTrend {
+  // A file with 0-1 commits in the window has no "older" phase to compare against —
+  // classifying it as 'cooling' (declining activity) is nonsensical for something
+  // that was just created or touched once.
+  if (commitCount <= 1) return 'stable';
   if (olderWeighted === 0) {
     return recentWeighted > 0 ? 'accelerating' : 'stable';
   }
@@ -69,6 +77,40 @@ export function classifyChurnTrend(recentWeighted: number, olderWeighted: number
   return 'stable';
 }
 
+/** Coarse day-granularity bucket for the current moment, e.g. "2026-07-08". */
+function todayBucket(): string {
+  return new Date().toISOString().slice(0, 10);
+}
+
+/**
+ * Delete churn cache files whose date bucket is older than `maxAgeDays` — the
+ * weighted-commit numbers decay with time even at a fixed HEAD, and without this
+ * a repo idle for weeks would keep serving stale cache, while cache files from
+ * every past HEAD/day combination would accumulate forever.
+ */
+function pruneChurnCache(cacheDir: string, maxAgeDays = 3): void {
+  let entries: string[];
+  try {
+    entries = readdirSync(cacheDir);
+  } catch {
+    return;
+  }
+  const now = Date.now();
+  for (const entry of entries) {
+    const m = entry.match(/^churn-.+-(\d{4}-\d{2}-\d{2})\.json$/);
+    if (!m) continue;
+    const bucketMs = Date.parse(m[1]);
+    if (isNaN(bucketMs)) continue;
+    if ((now - bucketMs) / 86400000 > maxAgeDays) {
+      try {
+        unlinkSync(join(cacheDir, entry));
+      } catch {
+        // non-fatal — best-effort prune
+      }
+    }
+  }
+}
+
 export async function analyzeChurn(
   root: string,
   since: SinceDuration | string,
@@ -76,12 +118,16 @@ export async function analyzeChurn(
   const sinceDuration: SinceDuration =
     typeof since === 'string' ? parseSince(since) : since;
 
-  // Cache lookup
+  // Cache lookup — keyed by HEAD SHA + window size + a coarse day bucket, so
+  // entries naturally invalidate as time passes even at the same HEAD (the
+  // recency weighting is time-dependent, not just HEAD-dependent).
   const cacheDir = join(root, '.monograph', 'cache');
+  const dateBucket = todayBucket();
+  pruneChurnCache(cacheDir);
   let treeHash = '';
   try {
     treeHash = execSync('git rev-parse HEAD', { cwd: root }).toString().trim();
-    const cacheFile = join(cacheDir, `churn-${treeHash}-${sinceDuration.days}.json`);
+    const cacheFile = join(cacheDir, `churn-${treeHash}-${sinceDuration.days}-${dateBucket}.json`);
     if (existsSync(cacheFile)) {
       try {
         const cached = JSON.parse(readFileSync(cacheFile, 'utf8'));
@@ -154,8 +200,10 @@ export async function analyzeChurn(
     const authorWeights = new Map<number, number>();
     let totalWeighted = 0;
 
-    // Split into two halves for trend analysis
-    const midpoint = Math.floor(sortedCommits.length / 2);
+    // Split by TIME (midpoint of the `since` window), not by commit-array index —
+    // otherwise 10 commits all from the last week still get split 5-old/5-recent,
+    // misrepresenting genuinely-recent-only activity as having an "older" phase.
+    const windowMidpoint = now - (sinceDuration.days * 86400000) / 2;
     let recentWeighted = 0;
     let olderWeighted = 0;
 
@@ -176,15 +224,14 @@ export async function analyzeChurn(
       authorWeights.set(authorIdx, existing + weight);
       totalWeighted += weight;
 
-      // recent = first half (newest), older = second half
-      if (i < midpoint) {
+      if (commitDate >= windowMidpoint) {
         recentWeighted += weight;
       } else {
         olderWeighted += weight;
       }
     }
 
-    const trend = classifyChurnTrend(recentWeighted, olderWeighted);
+    const trend = classifyChurnTrend(recentWeighted, olderWeighted, sortedCommits.length);
 
     const authors: AuthorContribution[] = Array.from(authorWeights.entries()).map(
       ([authorIdx, weightedCommits]) => ({ authorIdx, weightedCommits }),
@@ -205,7 +252,7 @@ export async function analyzeChurn(
   if (treeHash) {
     try {
       mkdirSync(cacheDir, { recursive: true });
-      const cacheFile = join(cacheDir, `churn-${treeHash}-${sinceDuration.days}.json`);
+      const cacheFile = join(cacheDir, `churn-${treeHash}-${sinceDuration.days}-${dateBucket}.json`);
       writeFileSync(cacheFile, JSON.stringify(result), 'utf8');
     } catch {
       // cache write failure is non-fatal