@monoes/monograph 1.5.5 → 1.5.6

package/.monomind/data/ranked-context.json

@@ -0,0 +1,5 @@
+{
+  "version": 1,
+  "computedAt": 1778102154767,
+  "entries": []
+}

package/.monomind/loops/mastermind-review-1782162423447.json

@@ -0,0 +1,16 @@
+{
+  "id": "mastermind-review-1782162423447",
+  "sessionId": "mastermind-review-1782162423447",
+  "type": "tillend",
+  "command": "/mastermind:review",
+  "prompt": "check the updates on monograph and monoplaybook",
+  "maxReps": 50,
+  "interval": 1,
+  "wait": 60,
+  "currentRep": 1,
+  "startedAt": 1782162423447,
+  "lastRunAt": 1782162423447,
+  "nextRunAt": 1782162423447,
+  "status": "running",
+  "source": "_repeat.md"
+}

package/.monomind/sessions/session-1777578175215.json

@@ -0,0 +1,15 @@
+{
+  "id": "session-1777578175215",
+  "startedAt": "2026-04-30T19:42:55.215Z",
+  "platform": "darwin",
+  "cwd": "/Users/morteza/Desktop/tools/monomind/packages/@monomind/monograph",
+  "context": {},
+  "metrics": {
+    "edits": 42,
+    "commands": 0,
+    "tasks": 10,
+    "errors": 0
+  },
+  "endedAt": "2026-05-03T15:52:50.959Z",
+  "duration": 245395745
+}

package/.monomind/sessions/session-1777823684507.json

@@ -0,0 +1,15 @@
+{
+  "id": "session-1777823684507",
+  "startedAt": "2026-05-03T15:54:44.507Z",
+  "platform": "darwin",
+  "cwd": "/Users/morteza/Desktop/tools/monomind/packages/@monomind/monograph",
+  "context": {},
+  "metrics": {
+    "edits": 34,
+    "commands": 0,
+    "tasks": 0,
+    "errors": 0
+  },
+  "endedAt": "2026-05-04T21:07:59.511Z",
+  "duration": 105195004
+}

package/.monomind/sessions/session-1777928944749.json

@@ -0,0 +1,15 @@
+{
+  "id": "session-1777928944749",
+  "startedAt": "2026-05-04T21:09:04.749Z",
+  "platform": "darwin",
+  "cwd": "/Users/morteza/Desktop/tools/monomind/packages/@monomind/monograph",
+  "context": {},
+  "metrics": {
+    "edits": 18,
+    "commands": 0,
+    "tasks": 3,
+    "errors": 0
+  },
+  "endedAt": "2026-05-06T07:32:36.650Z",
+  "duration": 123811901
+}

package/.monomind/sessions/session-1778052902210.json

@@ -0,0 +1,15 @@
+{
+  "id": "session-1778052902210",
+  "startedAt": "2026-05-06T07:35:02.210Z",
+  "platform": "darwin",
+  "cwd": "/Users/morteza/Desktop/tools/monomind/packages/@monomind/monograph",
+  "context": {},
+  "metrics": {
+    "edits": 29,
+    "commands": 0,
+    "tasks": 2,
+    "errors": 0
+  },
+  "endedAt": "2026-05-06T08:37:15.370Z",
+  "duration": 3733161
+}

package/.monomind/sessions/session-1778056744636.json

@@ -0,0 +1,15 @@
+{
+  "id": "session-1778056744636",
+  "startedAt": "2026-05-06T08:39:04.636Z",
+  "platform": "darwin",
+  "cwd": "/Users/morteza/Desktop/tools/monomind/packages/@monomind/monograph",
+  "context": {},
+  "metrics": {
+    "edits": 30,
+    "commands": 0,
+    "tasks": 2,
+    "errors": 0
+  },
+  "endedAt": "2026-05-06T09:49:21.825Z",
+  "duration": 4217190
+}

package/.monomind/sessions/session-1778061077599.json

@@ -0,0 +1,15 @@
+{
+  "id": "session-1778061077599",
+  "startedAt": "2026-05-06T09:51:17.599Z",
+  "platform": "darwin",
+  "cwd": "/Users/morteza/Desktop/tools/monomind/packages/@monomind/monograph",
+  "context": {},
+  "metrics": {
+    "edits": 11,
+    "commands": 0,
+    "tasks": 0,
+    "errors": 0
+  },
+  "endedAt": "2026-05-06T21:13:36.832Z",
+  "duration": 40939234
+}

package/.monomind/sessions/session-1778102154764.json

@@ -0,0 +1,15 @@
+{
+  "id": "session-1778102154764",
+  "startedAt": "2026-05-06T21:15:54.764Z",
+  "platform": "darwin",
+  "cwd": "/Users/morteza/Desktop/tools/monomind/packages/@monomind/monograph",
+  "context": {},
+  "metrics": {
+    "edits": 12,
+    "commands": 0,
+    "tasks": 0,
+    "errors": 0
+  },
+  "endedAt": "2026-05-09T05:42:40.302Z",
+  "duration": 203205539
+}

package/README.md

@@ -0,0 +1,135 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/monoes/monomind/main/assets/packages/monograph.png" alt="@monoes/monograph" width="600" />
+</p>
+
+# @monoes/monograph
+
+[![npm version](https://img.shields.io/npm/v/@monoes/monograph?style=flat-square)](https://www.npmjs.com/package/@monoes/monograph)
+[![license](https://img.shields.io/npm/l/@monoes/monograph?style=flat-square)](https://github.com/monoes/monomind/blob/main/LICENSE)
+[![node](https://img.shields.io/badge/node-%3E%3D20-339933?style=flat-square&logo=node.js&logoColor=white)](https://nodejs.org)
+
+**Code intelligence as a graph** — tree-sitter parses your codebase into a SQLite-backed knowledge graph of files, functions, classes, imports, and call relationships. Query blast radius, find callers, and navigate architecture without grep.
+
+> Part of the [Monomind](https://github.com/monoes/monomind) ecosystem.
+
+## Install
+
+```bash
+npm install @monoes/monograph
+```
+
+## What it does
+
+Monograph walks your source tree with [tree-sitter](https://tree-sitter.github.io/tree-sitter/), extracts symbols and their relationships, and stores them in a SQLite database. The result is a queryable graph where:
+
+- **Nodes** are files, functions, classes, methods, and exports
+- **Edges** are imports, calls, extends, and contains relationships
+
+## CLI usage
+
+```bash
+# Build the graph for the current project
+monograph build
+
+# Query symbols
+monograph query "UserService"
+
+# Find blast radius of a change
+monograph impact src/auth.ts
+
+# Check index freshness
+monograph health
+
+# Find high-centrality files
+monograph god-nodes
+```
+
+## Programmatic usage
+
+```typescript
+import { MonographEngine } from '@monoes/monograph';
+
+const engine = new MonographEngine({ projectRoot: process.cwd() });
+await engine.build();
+
+const results = engine.query('authenticate');
+const impact = engine.impact('src/auth/login.ts');
+const godNodes = engine.godNodes({ limit: 10 });
+```
+
+## MCP tools
+
+When used via Monomind's MCP server, monograph exposes 19 tools by default (+27 advanced via `MONOGRAPH_MCP_ADVANCED=1`):
+
+| Tool | Purpose |
+|---|---|
+| `monograph_suggest` | Start every task — ranked relevant files |
+| `monograph_query` | BM25 keyword search with PPR graph reranking |
+| `monograph_impact` | Blast radius analysis (upstream + downstream) |
+| `monograph_god_nodes` | High-centrality internal files |
+| `monograph_context` | 360° view of a file |
+| `monograph_augment` | Graph-RAG context retrieval |
+| `monograph_dead_code` | Dead exports, orphan files, stale dist |
+| `monograph_detect_changes` | Map git diff to affected graph nodes |
+| `monograph_route_map` | List HTTP routes with handlers |
+
+## Supported languages & Parsers
+
+Monograph utilizes a dual-tier parsing strategy for extracting code structure and symbols:
+
+1. **Tree-sitter AST Parsers (25 supported extensions)**:
+   - **Extensions**: `.ts`, `.tsx`, `.js`, `.jsx`, `.mjs`, `.cjs`, `.py`, `.go`, `.rs`, `.java`, `.c`, `.h`, `.cpp`, `.cc`, `.cxx`, `.hpp`, `.hxx`, `.cs`, `.rb`, `.swift`, `.php`, `.vue`, `.kt`, `.kts`, `.dart`.
+   - **Grammar Loader**: Dynamically loads and caches Tree-sitter grammars per extension via `getParser(ext)` ([`loader.ts:64-83`](file:///Users/morteza/Desktop/tools/monomind/packages/@monomind/monograph/src/parsers/loader.ts#L64-L83)). Supports `<script>` block isolation for `.vue` files ([`loader.ts:128-142`](file:///Users/morteza/Desktop/tools/monomind/packages/@monomind/monograph/src/parsers/loader.ts#L128-L142)).
+2. **Regex Fallback Parsers (5 languages)**:
+   - Lightweight regex-based symbol extractors for languages when Tree-sitter grammars are uninstalled or unsupported: **Scala**, **Lua**, **Zig**, **PowerShell**, and **Elixir** ([`language-parsers.ts:1-100`](file:///Users/morteza/Desktop/tools/monomind/packages/@monomind/monograph/src/parsers/language-parsers.ts#L1-L100)).
+
+## SQLite Database Schema
+
+The graph is stored in a WAL-mode SQLite database (`PRAGMA journal_mode = WAL`) managed in [`schema.ts`](file:///Users/morteza/Desktop/tools/monomind/packages/@monomind/monograph/src/storage/schema.ts) and [`db.ts`](file:///Users/morteza/Desktop/tools/monomind/packages/@monomind/monograph/src/storage/db.ts):
+
+- **`nodes`**: Code symbols and files (`id`, `label`, `name`, `norm_label`, `file_path`, `start_line`, `end_line`, `community_id`, `is_exported`, `language`, `properties`, `embedding`).
+- **`edges`**: Directed relationships between nodes (`id`, `source_id`, `target_id`, `relation`, `confidence`, `confidence_score`, `weight`, `reason`, `evidence`).
+- **`communities`**: Hierarchical community clusters (`id`, `label`, `size`, `cohesion_score`).
+- **`file_cache`**: SHA-256 incremental parse cache (`file_path`, `content_hash`, `last_parsed`, `node_count`, `edge_count`).
+- **`nodes_fts`**: Trigram-tokenized FTS5 virtual table (`tokenize='trigram'`) indexing `name`, `norm_label`, and `file_path` with sync triggers for rapid symbol and fuzzy text queries.
+- **`index_meta`**: Key-value system index metadata (including `last_commit_hash`).
+
+## Relationship Types
+
+Monograph defines typed edges ([`types.ts:20-29`](file:///Users/morteza/Desktop/tools/monomind/packages/@monomind/monograph/src/types.ts#L20-L29)) categorized into structural, static analysis, and semantic relationships:
+
+- **`CONTAINS`**: Parent container to child element (e.g. File contains Class/Function, Class contains Method).
+- **`IMPORTS`**: File/Module import dependency (`import { x } from './y'`).
+- **`CALLS`**: Function/Method invocation between symbols.
+- **`ENTRY_POINT_OF`**: Entry point symbol associated with an agent process or application workflow.
+- Additional relations include `RE_EXPORTS`, `EXTENDS`, `IMPLEMENTS`, `HAS_METHOD`, `HAS_PROPERTY`, `ACCESSES`, `HANDLES_ROUTE`, `FETCHES`, `HANDLES_TOOL`, `WRAPS`, `QUERIES`, `REFERENCES`, `CO_OCCURS`, and LLM-inferred semantic relations (`DESCRIBES`, `CAUSES`, `CONTRASTS_WITH`, `PART_OF`, `RELATED_TO`, `USES`, `STRUCTURALLY_SIMILAR`).
+
+## Blast Radius Calculation (`rippleImpact`)
+
+Monograph calculates downstream cascade impact using the multi-hop `rippleImpact` BFS algorithm ([`ripple-impact.ts:51-84`](file:///Users/morteza/Desktop/tools/monomind/packages/@monomind/monograph/src/graph/ripple-impact.ts#L51-L84)):
+
+- **Algorithm**: Breadth-First Search propagating through outgoing directed edge adjacency maps.
+- **Scoring Formula**:
+  $$\text{TotalScore} = \sum_{\text{depth}=1}^{\text{maxDepth}} N_{\text{depth}} \times (\text{decayFactor})^{\text{depth}}$$
+  *(Default `maxDepth = 3`, `decayFactor = 0.5`)*
+- **Output**: Groups affected nodes by depth level (`byDepth: Record<number, string[]>`) and calculates a weighted decay impact score (`totalScore`). Exposes native blast radius insights via the `monograph_impact` MCP tool.
+
+## Graph Freshness & Git Staleness Tracking
+
+Monograph maintains graph synchronization with git repository state without full re-indexes ([`git-staleness.ts:13-66`](file:///Users/morteza/Desktop/tools/monomind/packages/@monomind/monograph/src/staleness/git-staleness.ts#L13-L66)):
+
+- **Commit Verification**: Compares stored `last_commit_hash` in `index_meta` against `git rev-parse HEAD`.
+- **Change Diffing**: If hashes diverge, executes `git diff --name-only <indexedCommit>..HEAD` to populate `changedSince` files.
+- **Divergence Timestamp**: Identifies `staleSince` ISO timestamp via `git log --format="%ai" <indexedCommit>..HEAD --reverse --max-count=1`.
+- **File Content Caching**: Computes SHA-256 hashes (`file_cache` table) to skip parsing untouched files during incremental builds.
+
+## Links
+
+- [GitHub](https://github.com/monoes/monomind)
+- [Documentation](https://monoes.github.io/monomind/)
+- [Issues](https://github.com/monoes/monomind/issues)
+
+## License
+
+MIT
+

package/__tests__/integration/graph-report-freshness.test.ts

@@ -0,0 +1,53 @@
+import { tmpdir } from 'os';
+import { join } from 'path';
+import { mkdirSync, writeFileSync, rmSync, readFileSync, existsSync } from 'fs';
+
+// Regression (issue #91): the graph report used to be generated inside the
+// open build transaction via the string overload of generateGraphReport,
+// which opens a SECOND DB connection. In WAL mode that connection only sees
+// the last committed snapshot, so GRAPH_REPORT.md was always one build stale —
+// on the very first build it rendered a completely empty graph. The report is
+// now generated after COMMIT.
+const tmpRepo = join(tmpdir(), `monograph-report-freshness-${Date.now()}`);
+
+beforeAll(() => {
+  mkdirSync(join(tmpRepo, 'src'), { recursive: true });
+  writeFileSync(join(tmpRepo, 'src', 'greeter.ts'), `
+export interface Greeter {
+  greet(name: string): string;
+}
+export class GreeterImpl implements Greeter {
+  greet(name: string): string {
+    return 'hello ' + name;
+  }
+}
+  `);
+});
+
+afterAll(() => rmSync(tmpRepo, { recursive: true, force: true }));
+
+describe('graph report freshness — report reflects the build that produced it', () => {
+  it('first build writes a report with the actual node count, not an empty snapshot', async () => {
+    const { buildAsync } = await import('../../src/pipeline/orchestrator.js');
+    await buildAsync(tmpRepo);
+
+    const reportPath = join(tmpRepo, 'GRAPH_REPORT.md');
+    expect(existsSync(reportPath)).toBe(true);
+
+    const { openDb, closeDb } = await import('../../src/storage/db.js');
+    const { countNodes } = await import('../../src/storage/node-store.js');
+    const db = openDb(join(tmpRepo, '.monomind', 'monograph.db'));
+    let nodeCount: number;
+    try {
+      nodeCount = countNodes(db);
+    } finally {
+      closeDb(db);
+    }
+    expect(nodeCount).toBeGreaterThan(0);
+
+    const report = readFileSync(reportPath, 'utf8');
+    // The report's overview table must reflect the just-committed build,
+    // not the previous (here: nonexistent) snapshot.
+    expect(report).toContain(`| Total nodes | ${nodeCount} |`);
+  }, 60000);
+});

package/__tests__/integration/incremental-build.test.ts

@@ -0,0 +1,103 @@
+import { tmpdir } from 'os';
+import { join } from 'path';
+import { mkdirSync, writeFileSync, rmSync, existsSync, unlinkSync } from 'fs';
+import { buildAsync, buildIncrementalAsync } from '../../src/pipeline/orchestrator.js';
+import { openDb, closeDb } from '../../src/storage/db.js';
+import { countNodes } from '../../src/storage/node-store.js';
+import { countEdges } from '../../src/storage/edge-store.js';
+import { ftsSearch } from '../../src/storage/fts-store.js';
+import { getNodesForFile } from '../../src/storage/node-store.js';
+
+const tmpRepo = join(tmpdir(), `monograph-incremental-${Date.now()}`);
+const dbPath = join(tmpRepo, '.monomind', 'monograph.db');
+const srcDir = join(tmpRepo, 'src');
+
+beforeAll(async () => {
+  mkdirSync(srcDir, { recursive: true });
+  writeFileSync(join(srcDir, 'auth.ts'), `
+export class AuthService {
+  login(u: string): boolean { return u.length > 0; }
+}
+  `);
+  writeFileSync(join(srcDir, 'user.ts'), `
+export class UserController {
+  greet(): string { return 'hello'; }
+}
+  `);
+  await buildAsync(tmpRepo);
+}, 30000);
+
+afterAll(() => rmSync(tmpRepo, { recursive: true, force: true }));
+
+describe('incremental build', () => {
+  it('updates nodes when a file is modified', async () => {
+    const db1 = openDb(dbPath);
+    const authNodesBefore = getNodesForFile(db1, 'src/auth.ts');
+    closeDb(db1);
+    expect(authNodesBefore.some(n => n.name === 'logout')).toBe(false);
+
+    writeFileSync(join(srcDir, 'auth.ts'), `
+export class AuthService {
+  login(u: string): boolean { return u.length > 0; }
+  logout(): void {}
+}
+export function helperFn(): string { return 'x'; }
+    `);
+
+    await buildIncrementalAsync(tmpRepo, [join(srcDir, 'auth.ts')]);
+
+    const db2 = openDb(dbPath);
+    const authNodesAfter = getNodesForFile(db2, 'src/auth.ts');
+    closeDb(db2);
+
+    expect(authNodesAfter.some(n => n.name === 'logout')).toBe(true);
+    expect(authNodesAfter.some(n => n.name === 'helperFn')).toBe(true);
+  }, 15000);
+
+  it('removes nodes when a file is deleted', async () => {
+    const db1 = openDb(dbPath);
+    const nodesBefore = countNodes(db1);
+    const userNodesBefore = getNodesForFile(db1, 'src/user.ts');
+    closeDb(db1);
+    expect(userNodesBefore.length).toBeGreaterThan(0);
+
+    unlinkSync(join(srcDir, 'user.ts'));
+    await buildIncrementalAsync(tmpRepo, [join(srcDir, 'user.ts')]);
+
+    const db2 = openDb(dbPath);
+    const nodesAfter = countNodes(db2);
+    const userNodesAfter = getNodesForFile(db2, 'src/user.ts');
+    closeDb(db2);
+
+    expect(userNodesAfter.length).toBe(0);
+    expect(nodesAfter).toBeLessThan(nodesBefore);
+  }, 15000);
+
+  it('FTS stays in sync after incremental update', async () => {
+    const db = openDb(dbPath);
+    const results = ftsSearch(db, 'helperFn', 10);
+    closeDb(db);
+    expect(results.some(r => r.name === 'helperFn')).toBe(true);
+  });
+
+  it('FTS removes deleted file symbols', async () => {
+    const db = openDb(dbPath);
+    const results = ftsSearch(db, 'UserController', 10);
+    closeDb(db);
+    expect(results.some(r => r.name === 'UserController')).toBe(false);
+  });
+
+  it('falls back to full build when threshold exceeded', async () => {
+    const manyFiles = Array.from({ length: 25 }, (_, i) => join(srcDir, `gen${i}.ts`));
+    for (const f of manyFiles) {
+      writeFileSync(f, `export const x${Math.random().toString(36).slice(2)} = 1;`);
+    }
+
+    await buildIncrementalAsync(tmpRepo, manyFiles);
+
+    const db = openDb(dbPath);
+    const nodes = countNodes(db);
+    closeDb(db);
+    expect(nodes).toBeGreaterThan(0);
+  }, 30000);
+}, 60000);