skillwiki 0.8.1-beta.2 → 0.8.1-beta.4

package/dist/cli.js

@@ -548,23 +548,137 @@ function extractBodyWikilinks(body) {
   return out;
 }
 
-// src/commands/graph.ts
-async function runGraphBuild(input) {
-  const scan = await scanVault(input.vault);
-  if (!scan.ok) return { exitCode: ExitCode.VAULT_PATH_INVALID, result: scan };
+// src/utils/community.ts
+async function buildWikilinkAdjacency(typedKnowledge) {
   const adjacency = {};
   const slugToPath = {};
-  for (const p of scan.data.typedKnowledge) {
+  for (const p of typedKnowledge) {
     const slug = p.relPath.replace(/\.md$/, "").split("/").pop();
     slugToPath[slug] = p.relPath;
   }
-  for (const p of scan.data.typedKnowledge) {
+  for (const p of typedKnowledge) {
     const text = await readPage(p);
     const split = splitFrontmatter(text);
     const body = split.ok ? split.data.body : text;
     const links = extractBodyWikilinks(body);
     adjacency[p.relPath] = links.map((slug) => slugToPath[slug.split("/").pop()]).filter((x) => Boolean(x));
   }
+  return adjacency;
+}
+function toUndirectedWeighted(adj) {
+  const g = /* @__PURE__ */ new Map();
+  const ensure = (n) => {
+    let m = g.get(n);
+    if (!m) {
+      m = /* @__PURE__ */ new Map();
+      g.set(n, m);
+    }
+    return m;
+  };
+  for (const node of Object.keys(adj)) ensure(node);
+  for (const [a, nbrs] of Object.entries(adj)) {
+    for (const b of nbrs) {
+      if (a === b) continue;
+      ensure(a).set(b, 1);
+      ensure(b).set(a, 1);
+    }
+  }
+  return g;
+}
+function louvain(g) {
+  const nodes = [...g.keys()].sort();
+  const comm = /* @__PURE__ */ new Map();
+  nodes.forEach((n, i) => comm.set(n, i));
+  const k = /* @__PURE__ */ new Map();
+  let m2 = 0;
+  for (const n of nodes) {
+    let deg = 0;
+    for (const w of g.get(n).values()) deg += w;
+    k.set(n, deg);
+    m2 += deg;
+  }
+  if (m2 === 0) return comm;
+  const sumTot = /* @__PURE__ */ new Map();
+  for (const n of nodes) {
+    const c = comm.get(n);
+    sumTot.set(c, (sumTot.get(c) ?? 0) + k.get(n));
+  }
+  let improved = true;
+  while (improved) {
+    improved = false;
+    for (const n of nodes) {
+      const cur = comm.get(n);
+      const kn = k.get(n);
+      sumTot.set(cur, sumTot.get(cur) - kn);
+      const wToComm = /* @__PURE__ */ new Map();
+      for (const [nb, w] of g.get(n)) {
+        if (nb === n) continue;
+        const c = comm.get(nb);
+        wToComm.set(c, (wToComm.get(c) ?? 0) + w);
+      }
+      const gainFor = (c) => (wToComm.get(c) ?? 0) - (sumTot.get(c) ?? 0) * kn / m2;
+      const curGain = gainFor(cur);
+      let bestComm = cur;
+      let bestDelta = 0;
+      for (const c of wToComm.keys()) {
+        const delta = gainFor(c) - curGain;
+        if (delta > bestDelta) {
+          bestDelta = delta;
+          bestComm = c;
+        }
+      }
+      comm.set(n, bestComm);
+      sumTot.set(bestComm, (sumTot.get(bestComm) ?? 0) + kn);
+      if (bestComm !== cur) improved = true;
+    }
+  }
+  return comm;
+}
+function communityCohesion(members, g) {
+  const n = members.length;
+  if (n < 2) return 1;
+  const set = new Set(members);
+  let internal = 0;
+  for (const a of members) {
+    for (const [b, w] of g.get(a) ?? /* @__PURE__ */ new Map()) {
+      if (a < b && set.has(b)) internal += w;
+    }
+  }
+  return internal / (n * (n - 1) / 2);
+}
+function findSparseCommunities(adj, opts = {}) {
+  const minSize = opts.minSize ?? 3;
+  const maxCohesion = opts.maxCohesion ?? 0.15;
+  const g = toUndirectedWeighted(adj);
+  const comm = louvain(g);
+  const groups = /* @__PURE__ */ new Map();
+  for (const [node, c] of comm) {
+    const arr = groups.get(c);
+    if (arr) arr.push(node);
+    else groups.set(c, [node]);
+  }
+  const out = [];
+  for (const members of groups.values()) {
+    if (members.length < minSize) continue;
+    const cohesion = communityCohesion(members, g);
+    if (cohesion < maxCohesion) {
+      out.push({
+        members: [...members].sort(),
+        size: members.length,
+        cohesion: Math.round(cohesion * 1e3) / 1e3,
+        action: members.length <= 5 ? "merge into adjacent community" : "split into smaller topics"
+      });
+    }
+  }
+  out.sort((a, b) => a.cohesion - b.cohesion);
+  return out;
+}
+
+// src/commands/graph.ts
+async function runGraphBuild(input) {
+  const scan = await scanVault(input.vault);
+  if (!scan.ok) return { exitCode: ExitCode.VAULT_PATH_INVALID, result: scan };
+  const adjacency = await buildWikilinkAdjacency(scan.data.typedKnowledge);
   const adamicAdar = computeAdamicAdar(adjacency);
   const edge_count = Object.values(adjacency).reduce((acc, arr) => acc + arr.length, 0);
   try {
@@ -2469,6 +2583,19 @@ import { existsSync as existsSync4 } from "fs";
 import { readFile as readFile16, rename as rename6 } from "fs/promises";
 import { join as join21 } from "path";
 
+// src/commands/sparse-community.ts
+async function runSparseCommunity(input) {
+  const scan = await scanVault(input.vault);
+  if (!scan.ok) return { exitCode: ExitCode.VAULT_PATH_INVALID, result: scan };
+  const adjacency = await buildWikilinkAdjacency(scan.data.typedKnowledge);
+  const communities = findSparseCommunities(adjacency, {
+    minSize: input.minSize,
+    maxCohesion: input.maxCohesion
+  });
+  const humanHint = communities.length === 0 ? "no sparse communities" : communities.map((c) => `  cohesion ${c.cohesion} (${c.size} pages): ${c.action}`).join("\n");
+  return { exitCode: ExitCode.OK, result: ok({ communities, humanHint }) };
+}
+
 // src/commands/topic-map-check.ts
 var DEFAULT_THRESHOLD = 200;
 async function runTopicMapCheck(input) {
@@ -2941,7 +3068,7 @@ function extractSourceEntries(rawFm) {
 }
 var ERROR_ORDER = ["broken_wikilinks", "invalid_frontmatter", "raw_dedup", "broken_sources", "tag_not_in_taxonomy", "path_too_long"];
 var WARNING_ORDER = ["raw_body_duplicate", "raw_subdirectory_duplicate", "file_source_url", "index_incomplete", "index_link_format", "stale_page", "page_too_large", "log_rotate_needed", "orphans", "compound_refs", "legacy_citation_style", "orphaned_citations", "duplicate_frontmatter", "work_item_health", "orphaned_project_pages", "missing_overview", "missing_diagram"];
-var INFO_ORDER = ["bridges", "page_structure", "topic_map_recommended", "frontmatter_wikilink", "wikilink_citation", "missing_tldr", "stale_sections", "cli_refs"];
+var INFO_ORDER = ["bridges", "sparse_community", "page_structure", "topic_map_recommended", "frontmatter_wikilink", "wikilink_citation", "missing_tldr", "stale_sections", "cli_refs"];
 async function runLint(input) {
   const buckets = {};
   const fixed = [];
@@ -2984,6 +3111,10 @@ async function runLint(input) {
     if (orphans.result.data.orphans.length > 0) buckets.orphans = orphans.result.data.orphans;
     if (orphans.result.data.bridges.length > 0) buckets.bridges = orphans.result.data.bridges;
   }
+  const sparse = await runSparseCommunity({ vault: input.vault });
+  if (sparse.result.ok && sparse.result.data.communities.length > 0) {
+    buckets.sparse_community = sparse.result.data.communities;
+  }
   const topicMap = await runTopicMapCheck({ vault: input.vault });
   if (topicMap.result.ok && topicMap.result.data.recommended) {
     buckets.topic_map_recommended = [{ page_count: topicMap.result.data.page_count, threshold: topicMap.result.data.threshold }];
@@ -4855,6 +4986,55 @@ function findSkillNames(dir) {
   }
   return results;
 }
+var METRIC_TYPES = ["entities", "concepts", "comparisons", "queries", "meta"];
+async function vaultMetrics(resolvedPath) {
+  const ids = [
+    ["vault_metric_pages", "Vault pages by type"],
+    ["vault_metric_orphans", "Vault orphan rate"],
+    ["vault_metric_bridges", "Vault bridge count"],
+    ["vault_metric_cohesion", "Mean community cohesion"],
+    ["vault_metric_log_size", "Vault log size"]
+  ];
+  const noVault = () => ids.map(([id, label]) => check("info", id, label, "no vault configured"));
+  if (!resolvedPath) return noVault();
+  const scan = await scanVault(resolvedPath);
+  if (!scan.ok) return noVault();
+  const tk = scan.data.typedKnowledge;
+  const perType = METRIC_TYPES.map((d) => `${d} ${tk.filter((p) => p.relPath.startsWith(d + "/")).length}`).join(", ");
+  const adj = await buildWikilinkAdjacency(tk);
+  const g = toUndirectedWeighted(adj);
+  const nodes = [...g.keys()];
+  const total = nodes.length;
+  const orphanCount = nodes.filter((n) => g.get(n).size === 0).length;
+  const orphanRate = total > 0 ? Math.round(orphanCount / total * 1e3) / 10 : 0;
+  const comm = louvain(g);
+  const groups = /* @__PURE__ */ new Map();
+  for (const [node, c] of comm) {
+    const arr = groups.get(c);
+    if (arr) arr.push(node);
+    else groups.set(c, [node]);
+  }
+  const cohesions = [...groups.values()].filter((m) => m.length >= 2).map((m) => communityCohesion(m, g));
+  const meanCohesion = cohesions.length > 0 ? Math.round(cohesions.reduce((a, b) => a + b, 0) / cohesions.length * 1e3) / 1e3 : 0;
+  let bridges = 0;
+  for (const n of nodes) {
+    const nbrComms = /* @__PURE__ */ new Set();
+    for (const nb of g.get(n).keys()) nbrComms.add(comm.get(nb));
+    if (nbrComms.size >= 3) bridges++;
+  }
+  let logLines = 0;
+  try {
+    logLines = readFileSync7(join26(resolvedPath, "log.md"), "utf8").split("\n").length;
+  } catch {
+  }
+  return [
+    check("info", "vault_metric_pages", "Vault pages by type", `${total} typed (${perType})`),
+    check("info", "vault_metric_orphans", "Vault orphan rate", `${orphanRate}% (${orphanCount}/${total} degree-0)`),
+    check("info", "vault_metric_bridges", "Vault bridge count", `${bridges} page(s) link >= 3 communities`),
+    check("info", "vault_metric_cohesion", "Mean community cohesion", `${meanCohesion} across ${cohesions.length} communities (size >= 2)`),
+    check("info", "vault_metric_log_size", "Vault log size", `${logLines} lines`)
+  ];
+}
 async function runDoctor(input) {
   const checks = [];
   const vsConfig = readVaultSyncConfig(input.home);
@@ -4890,6 +5070,7 @@ async function runDoctor(input) {
     vaultSyncInstalled: vsConfig.installed,
     vaultSyncRole: vsConfig.role
   }));
+  checks.push(...await vaultMetrics(resolvedPath));
   const summary = {
     pass: checks.filter((c) => c.status === "pass").length,
     info: checks.filter((c) => c.status === "info").length,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skillwiki",
-  "version": "0.8.1-beta.2",
+  "version": "0.8.1-beta.4",
   "type": "module",
   "bin": {
     "skillwiki": "dist/cli.js"

package/skills/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "skillwiki",
-  "version": "0.8.1-beta.2",
+  "version": "0.8.1-beta.4",
   "skills": "./",
   "description": "Project-aware Karpathy-style knowledge base for Claude Code: 18 prompt-only skills (wiki-*, proj-*, using-skillwiki) backed by the deterministic `skillwiki` CLI.",
   "author": {

package/skills/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "skillwiki",
-  "version": "0.8.1-beta.2",
+  "version": "0.8.1-beta.4",
   "description": "Project-aware Karpathy-style knowledge base for Codex with 18 prompt-only skills backed by the deterministic skillwiki CLI.",
   "author": {
     "name": "karlorz",

package/skills/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skillwiki/skills",
-  "version": "0.8.1-beta.2",
+  "version": "0.8.1-beta.4",
   "private": true,
   "files": [
     "wiki-*",