knosky 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 All notable changes to KnoSky. Versions are git-tagged on this repo.
 
+## [0.4.0] - 2026-06-29 — File Connections + churn (code-intel)
+
+### Added
+- **File Connections:** import/dependency edges drawn as roads between buildings — select a file to see what it imports and what imports it. Per-language import scan over a bounded prefix; specifiers are resolved to repo files and then discarded (file-to-file edges only).
+- **Churn heat:** recently-changed files glow on the map, from `git log` (per-file commit count only).
+- **MCP `kc_related`:** ask your assistant "what connects to this file?" — out-edges, in-edges, and churn, with citations.
+- Flags: `--no-graph`, `--no-churn` to omit either signal.
+
+### Notes
+- Strictly **file-level metadata** (decision D-155): no symbol names, no ASTs, no code bodies, no commit messages/diffs. KnoSky maps how files connect; it does not analyze your code.
+
 ## [0.3.0] - 2026-06-29 — One-command launcher (npx)
 
 ### Added

package/README.md

@@ -32,14 +32,13 @@ Developers, founders, and architects sitting on a sprawling repo or knowledge ba
 
 ## How it works
 
-**Quickstart:**
+**Quickstart — one command:**
 ```bash
-git clone https://github.com/SathiaAI/knosky && cd knosky && npm install
-node bin/knosky.mjs /path/to/your/repo
+npx knosky .
 ```
-Indexes the folder, opens the city, prints the MCP config for your AI assistant (Claude Code / Claude Desktop / Cursor / VS Code) plus a few starter prompts, and starts the local connector. Flags: `--no-open`, `--no-serve`.
+Indexes the current folder, opens the city, prints the MCP config for your AI assistant (Claude Code / Claude Desktop / Cursor / VS Code) plus a few starter prompts, and starts the local connector. Point it anywhere with `npx knosky /path/to/your/repo`. Flags: `--no-open`, `--no-serve`.
 
-*Coming to npm:* `npx knosky .` — the same thing in one command, no clone.
+Prefer a clone? `git clone https://github.com/SathiaAI/knosky && cd knosky && npm install && node bin/knosky.mjs .`
 
 Want the individual pieces instead? Read on.
 
@@ -68,7 +67,9 @@ Or add to your Claude Desktop / Cursor / VS Code MCP config:
   "env": { "KC_CITY": "/abs/path/city-data.json" }
 }
 ```
-Then ask: *"search KnoSky for what we decided about authentication."* Read-only tools exposed: `kc_search`, `kc_get_node`, `kc_list_categories`, `kc_get_provenance`.
+Then ask: *"search KnoSky for what we decided about authentication."* Read-only tools exposed: `kc_search`, `kc_get_node`, `kc_list_categories`, `kc_get_provenance`, `kc_related`.
+
+**See how your code connects.** Select a file in the city to see its **connections** (roads to the files it imports / that import it) and **churn** (recently-changed files glow). Or ask your assistant *"what connects to src/auth.js?"* — file-level structure only, not code analysis.
 
 ---
 

package/core/churn.mjs

@@ -0,0 +1,20 @@
+// Git churn (D-155): per-file commit count (windowed) + last-commit timestamp ONLY.
+// No commit messages, diffs, hunks, authors, or line-level churn retained.
+import { execSync } from 'node:child_process';
+
+export function gitChurn(root) {
+  const counts = {}, last = {};
+  try {
+    const out = execSync('git log --since=90.days.ago --name-only --pretty=format:%ct -- .', { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], maxBuffer: 64 * 1024 * 1024 });
+    let ts = 0;
+    for (const raw of out.split(/\r?\n/)) {
+      const line = raw.trim();
+      if (!line) continue;
+      if (/^\d+$/.test(line)) { ts = parseInt(line, 10); continue; }
+      const rel = line.replace(/\\/g, '/');
+      counts[rel] = (counts[rel] || 0) + 1;
+      if (!last[rel] || ts > last[rel]) last[rel] = ts;
+    }
+  } catch { /* no git / no history -> empty */ }
+  return { counts, last };
+}

package/core/contract.mjs

@@ -7,7 +7,7 @@ export const SCHEMA_VERSION = '2.0';
 // The ONLY node fields that may ever be serialized into the index. Anything else is dropped/flagged.
 export const NODE_FIELD_ALLOWLIST = [
   'id', 'kind', 'title', 'summary', 'category', 'status',
-  'fact_date', 'tags', 'headings', 'links', 'provenance', 'visibility', 'sensitive',
+  'fact_date', 'tags', 'headings', 'links', 'churn', 'provenance', 'visibility', 'sensitive',
 ];
 export const NODE_REQUIRED = ['id', 'kind', 'title', 'category', 'links', 'provenance'];
 export const PROVENANCE_REQUIRED = ['store', 'ref'];

package/core/edges.mjs

@@ -0,0 +1,44 @@
+// File-level import edges (D-155): file-to-file ONLY. Import specifiers are read transiently
+// and discarded after resolution; nothing but the resolved file-to-file edge is ever stored.
+// No symbol names, no raw import lines, no body text. Reviewer rule: only file paths survive.
+import fs from 'node:fs';
+import path from 'node:path';
+
+const PATTERNS = [
+  /^\s*import\s+[^'"]*?from\s*['"]([^'"]+)['"]/,   // js/ts: import x from 'y'
+  /^\s*import\s*['"]([^'"]+)['"]/,                  // js/ts: import 'y'
+  /\brequire\(\s*['"]([^'"]+)['"]\s*\)/,            // js: require('y')
+  /^\s*export\s+[^'"]*?from\s*['"]([^'"]+)['"]/,    // js/ts: export ... from 'y'
+  /^\s*from\s+([.\w/]+)\s+import\b/,                // python: from x import
+  /^\s*#include\s*["<]([^">]+)[">]/,                // c/c++: #include "y"
+];
+
+// Read up to 8KB / 150 lines, scan for import specifiers, then drop the buffer. Returns specifier strings only.
+export function extractImportSpecifiers(filePath) {
+  let txt = '';
+  try { const fd = fs.openSync(filePath, 'r'); const buf = Buffer.alloc(8192); const n = fs.readSync(fd, buf, 0, 8192, 0); fs.closeSync(fd); txt = buf.slice(0, n).toString('utf8'); }
+  catch { return []; }
+  const lines = txt.split(/\r?\n/);
+  txt = '';
+  const specs = new Set();
+  for (let i = 0; i < lines.length && i < 150; i++) {
+    for (const re of PATTERNS) { const m = lines[i].match(re); if (m && m[1]) { specs.add(m[1]); break; } }
+  }
+  return [...specs];
+}
+
+const EXTS = ['', '.js', '.ts', '.tsx', '.jsx', '.mjs', '.cjs', '.py', '.go', '.rs', '.java', '.rb', '.php', '.c', '.h', '.cpp', '.hpp', '.cs', '.kt', '.swift'];
+
+// Resolve a relative specifier to an indexed repo file (rel path). Returns the target rel or null.
+// Only relative/internal specifiers resolve; bare package names return null (external = no edge).
+export function resolveSpec(fileRel, spec, relSet) {
+  if (!spec || !(spec.startsWith('.') || spec.startsWith('/'))) return null;
+  const baseDir = path.posix.dirname(fileRel);
+  const target = path.posix.normalize(path.posix.join(spec.startsWith('/') ? '.' : baseDir, spec)).replace(/^\.\//, '');
+  for (const e of EXTS) {
+    if (relSet.has(target + e)) return target + e;
+    const idx = path.posix.join(target, 'index' + (e || '.js'));
+    if (relSet.has(idx)) return idx;
+  }
+  return null;
+}

package/core/fs-indexer.mjs

@@ -5,6 +5,8 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { execSync } from 'node:child_process';
 import { SCHEMA_VERSION, IGNORE_DEFAULTS, deriveCategories, serializeNode, validateCity, setRedactTerms, findSecrets } from './contract.mjs';
+import { extractImportSpecifiers, resolveSpec } from './edges.mjs';
+import { gitChurn } from './churn.mjs';
 
 const args = Object.fromEntries(process.argv.slice(2).map((a, i, arr) => a.startsWith('--') ? [a.slice(2), arr[i + 1]] : []).filter(Boolean));
 const ROOT = args.root && path.resolve(args.root);
@@ -13,6 +15,8 @@ const MAX = parseInt(args.max || '6000', 10);
 const SHARE_SAFE = process.argv.includes('--share-safe');
 const INCLUDE_ABS = process.argv.includes('--include-absolute-root');
 const ALLOW_LEAKS = process.argv.includes('--allow-leaks');
+const NO_GRAPH = process.argv.includes('--no-graph');
+const NO_CHURN = process.argv.includes('--no-churn');
 if (!ROOT || !fs.existsSync(ROOT)) { console.log('usage: node fs-indexer.mjs --root <dir> [--out <file>] [--max N] [--redact a,b]'); process.exit(1); }
 const REDACT = (args.redact || '').split(',').map(s => s.trim()).filter(Boolean);
 if (REDACT.length) setRedactTerms(REDACT);
@@ -94,6 +98,7 @@ function walk(dir, depth) {
       tags: ext ? [ext.slice(1)] : [],
       headings,
       links: [],
+      importSpecs: (!NO_GRAPH && readable) ? extractImportSpecifiers(fp) : [],
       provenance: { store: 'fs', ref: rel, source_rev: REV, fetched_at: new Date().toISOString() },
       visibility: 'internal',
     });
@@ -115,11 +120,27 @@ try {
   }
 } catch (e) { /* git unavailable: keep the conservative-parser result */ }
 
-// light edges: markdown relative links that resolve to an indexed node
-const byRel = new Map(raw.map(n => [n.provenance.ref, n]));
-for (const n of raw) {
-  if (n.kind !== 'doc') continue;
-  // (edges intentionally minimal in v1 fs; reserved for Phase 2 — keep links=[] unless trivially resolvable)
+// File Connections (D-155): resolve import specifiers to indexed files; store ONLY file-to-file edges.
+const relSet = new Set(raw.map(n => n.provenance.ref));
+if (!NO_GRAPH) {
+  for (const n of raw) {
+    const targets = new Set();
+    for (const spec of (n.importSpecs || [])) {
+      const t = resolveSpec(n.provenance.ref, spec, relSet);
+      if (t) { const id = 'fs:' + t; if (id !== n.id) targets.add(id); }
+    }
+    n.links = [...targets];
+  }
+}
+for (const n of raw) delete n.importSpecs;   // discard specifiers; only the resolved file-to-file edge survives
+
+// Churn overlay (D-155): per-file commit count + last-commit ts only (no messages/diffs/authors/lines).
+if (!NO_CHURN) {
+  const ch = gitChurn(ROOT);
+  for (const n of raw) {
+    const c = ch.counts[n.provenance.ref] || 0;
+    if (c > 0) n.churn = { c, t: ch.last[n.provenance.ref] || 0, b: c >= 6 ? 3 : c >= 3 ? 2 : 1 };
+  }
 }
 
 const nodes = raw.map(serializeNode);

package/core/retrieve.mjs

@@ -51,3 +51,13 @@ export function getProvenance(ctx, id) {
   if (!n) return null;
   return { id, title: n.title, provenance: n.provenance, links: n.links || [] };
 }
+
+// related = file connections (D-155): out-edges (imports) + in-edges (imported-by) + churn signal. File-level only.
+export function getRelated(ctx, id) {
+  const n = ctx.byId.get(id);
+  if (!n) return null;
+  const ref = (m) => ({ id: m.id, title: m.title, source: m.provenance && m.provenance.ref });
+  const imports = (n.links || []).map(tid => ctx.byId.get(tid)).filter(Boolean).map(ref);
+  const importedBy = ctx.city.nodes.filter(m => (m.links || []).includes(id)).map(ref);
+  return { id, title: n.title, churn: n.churn || null, imports, importedBy };
+}

package/mcp/server.mjs

@@ -3,13 +3,13 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
-import { load, search, getNode, listCategories, getProvenance } from "../core/retrieve.mjs";
+import { load, search, getNode, listCategories, getProvenance, getRelated } from "../core/retrieve.mjs";
 
 const CITY = process.env.KC_CITY || process.argv[2];
 if (!CITY) { console.error("Knowledge City MCP: set KC_CITY (or pass a path) to a city-data.v2.json"); process.exit(1); }
 const ctx = load(CITY);
 
-const server = new McpServer({ name: "knowledge-city", version: "0.2.0" });
+const server = new McpServer({ name: "knowledge-city", version: "0.4.0" });
 
 server.registerTool("kc_search", {
   title: "Search the Knowledge City",
@@ -54,5 +54,21 @@ server.registerTool("kc_get_provenance", {
   return { content: [{ type: "text", text: p ? JSON.stringify(p, null, 2) : `No item with id ${id}` }], structuredContent: p || {} };
 });
 
+server.registerTool("kc_related", {
+  title: "Related files (connections)",
+  description: "How a file connects to others in this project: which files it imports (out), which files import it (in), and its recent-change (churn) signal. File-level structure with citations, not code analysis.",
+  inputSchema: { id: z.string().max(400).describe("node id, e.g. fs:src/auth.js") },
+  annotations: { readOnlyHint: true },
+}, async ({ id }) => {
+  const r = getRelated(ctx, id);
+  if (!r) return { content: [{ type: "text", text: "No item with id " + id }], structuredContent: {} };
+  const NL = String.fromCharCode(10);
+  const lines = [r.title + " (" + id + ")"];
+  if (r.churn) lines.push("recent changes: " + r.churn.c + " commit(s), heat " + r.churn.b);
+  lines.push("imports (" + r.imports.length + "): " + (r.imports.map(x => x.source || x.id).join(", ") || "none"));
+  lines.push("imported by (" + r.importedBy.length + "): " + (r.importedBy.map(x => x.source || x.id).join(", ") || "none"));
+  return { content: [{ type: "text", text: lines.join(NL) }], structuredContent: r };
+});
+
 await server.connect(new StdioServerTransport());
 console.error(`knowledge-city MCP ready — ${ctx.city.node_count} nodes, ${(ctx.city.categories||[]).length} categories`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "knosky",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Turn any repo or docs folder into an explorable city, plus a local MCP that grounds your AI in your own source with citations. Local-first, free, $0 tokens.",
   "type": "module",
   "bin": {

package/renderer/city.template.html

@@ -184,7 +184,7 @@
   function adapt(n){const versions=Array.isArray(n.versions)&&n.versions.length?n.versions:[{v:n.version||"1.0",date:n.fact_date||GD,note:n.status||""}];
     const dc=n.category||n.district;const d=DCFG[dc]?dc:(DKEYS[0]||"general");
     return {id:n.id,d,t:n.title||n.id,s:n.summary||"",kind:n.kind,status:n.status||"",
-      versions,prov:n.provenance||null,links:(n.links||[]),sensitive:!!n.sensitive};}
+      versions,prov:n.provenance||null,links:(n.links||[]),churn:n.churn||null,sensitive:!!n.sensitive};}
   // NODES/byId are (re)built by ingest() from the postMessage payload.
   let NODES=[];
   let byId={};
@@ -501,6 +501,15 @@
       ctx.fillStyle="rgba(255,233,166,.28)";ctx.beginPath();ctx.arc(B[0],B[1],7,0,7);ctx.fill();ctx.setLineDash([2,6]);});
     ctx.setLineDash([]);ctx.fillStyle="#fff2c4";ctx.beginPath();ctx.arc(A[0],A[1],4.5,0,7);ctx.fill();ctx.restore();}
 
+  // ---------- churn heat: ground glow under recently-changed files (D-155, file-level metadata only) ----------
+  function drawChurn(){
+    for(const n of NODES){ const ch=n.churn; if(!ch||!ch.b||ch.b<2||filteredHidden.has(n.id)) continue;
+      const col = ch.b>=3 ? 'rgba(242,104,63,' : 'rgba(232,178,74,';
+      ctx.fillStyle=col+'0.20)'; diamondPath(n.bx,n.by,TW*0.62,TH*0.62); ctx.fill();
+      ctx.fillStyle=col+'0.32)'; diamondPath(n.bx,n.by,TW*0.40,TH*0.40); ctx.fill();
+    }
+  }
+
   // ---------- cars (more realistic iso car) ----------
   const CARCOL=["#e85d54","#3f7fd0","#e8c44e","#43b07a","#d9dde4","#9a6cd0"];
   // Sprite columns: 0=up-left(-x)  1=up-right(-y)  2=down-right(+x)  3=down-left(+y). Each car faces its travel dir.
@@ -569,7 +578,7 @@
   function render(){NOW=performance.now()-T0;moveSky();ctx.setTransform(DPR,0,0,DPR,0,0);drawBackdrop();
     ctx.save();ctx.translate(cam.x,cam.y);ctx.scale(cam.zoom,cam.zoom);
     ctx.globalAlpha=Math.min(1,NOW/450);
-    drawIslandShadow();drawSlab();drawGround();drawCloudShadows();drawShadows();
+    drawIslandShadow();drawSlab();drawGround();drawCloudShadows();drawShadows();drawChurn();
     const list=OBJ.slice();drawCars(list);
     list.sort((a,b)=>(a.gx+a.gy)-(b.gx+b.gy)||a.gx-b.gx);
     for(const o of list){