pi-vault-mind 0.14.2 → 0.16.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (164) hide show
  1. package/CHANGELOG.md +293 -0
  2. package/README.md +5 -5
  3. package/agents/broadcaster.agent.md +2 -2
  4. package/agents/heavy-lifter.agent.md +1 -1
  5. package/agents/main.agent.md +29 -0
  6. package/agents/manager.agent.md +1 -1
  7. package/agents/miner.agent.md +1 -1
  8. package/dist/packages/obsidian/src/client.js +331 -0
  9. package/dist/packages/obsidian/src/types.js +1 -0
  10. package/dist/src/activity.d.ts +49 -0
  11. package/dist/src/activity.js +175 -0
  12. package/dist/src/agent-bus/Agent.d.ts +9 -1
  13. package/dist/src/agent-bus/Agent.js +18 -2
  14. package/dist/src/agent-bus/index.d.ts +5 -5
  15. package/dist/src/agent-bus/index.js +1 -1
  16. package/dist/src/agent-queue.js +12 -3
  17. package/dist/src/agents/BroadcasterAgent.d.ts +1 -1
  18. package/dist/src/agents/BroadcasterAgent.js +2 -2
  19. package/dist/src/agents/HeavyLifterAgent.d.ts +1 -1
  20. package/dist/src/agents/HeavyLifterAgent.js +2 -2
  21. package/dist/src/agents/ManagerAgent.js +1 -1
  22. package/dist/src/agents/MinerAgent.d.ts +1 -1
  23. package/dist/src/agents/MinerAgent.js +2 -2
  24. package/dist/src/agents/index.d.ts +2 -2
  25. package/dist/src/agents/index.js +2 -2
  26. package/dist/src/auth.d.ts +17 -15
  27. package/dist/src/auth.js +26 -37
  28. package/dist/src/autosync.js +2 -2
  29. package/dist/src/commands.d.ts +2 -19
  30. package/dist/src/commands.js +301 -231
  31. package/dist/src/config-keys.d.ts +16 -0
  32. package/dist/src/config-keys.js +45 -0
  33. package/dist/src/discover-schema.js +4 -4
  34. package/dist/src/edits.d.ts +21 -0
  35. package/dist/src/edits.js +75 -0
  36. package/dist/src/embedding-probe.d.ts +34 -0
  37. package/dist/src/embedding-probe.js +142 -0
  38. package/dist/src/embedding-providers.d.ts +133 -0
  39. package/dist/src/embedding-providers.js +173 -0
  40. package/dist/src/embedding-secrets.d.ts +38 -0
  41. package/dist/src/embedding-secrets.js +291 -0
  42. package/dist/src/engine.d.ts +6 -0
  43. package/dist/src/engine.js +78 -6
  44. package/dist/src/events.js +7 -10
  45. package/dist/src/extension-packages.d.ts +9 -0
  46. package/dist/src/extension-packages.js +14 -0
  47. package/dist/src/git.d.ts +19 -0
  48. package/dist/src/git.js +78 -0
  49. package/dist/src/graph.d.ts +2 -1
  50. package/dist/src/graph.js +47 -13
  51. package/dist/src/identities-config.d.ts +6 -0
  52. package/dist/src/identities-config.js +39 -0
  53. package/dist/src/identity-injector.js +1 -1
  54. package/dist/src/index.js +9 -26
  55. package/dist/src/lance.d.ts +9 -0
  56. package/dist/src/lance.js +143 -203
  57. package/dist/src/modal-client.d.ts +16 -0
  58. package/dist/src/modal-client.js +16 -0
  59. package/dist/src/modal-config.d.ts +37 -14
  60. package/dist/src/modal-config.js +59 -32
  61. package/dist/src/model-router.d.ts +27 -0
  62. package/dist/src/model-router.js +67 -0
  63. package/dist/src/models.d.ts +42 -0
  64. package/dist/src/models.js +78 -0
  65. package/dist/src/personalize.js +17 -3
  66. package/dist/src/scaffold.d.ts +48 -0
  67. package/dist/src/scaffold.js +246 -0
  68. package/dist/src/server.d.ts +47 -4
  69. package/dist/src/server.js +988 -221
  70. package/dist/src/session-search.d.ts +63 -0
  71. package/dist/src/session-search.js +379 -0
  72. package/dist/src/settings-ui.d.ts +2 -2
  73. package/dist/src/settings-ui.js +76 -135
  74. package/dist/src/sync.d.ts +3 -3
  75. package/dist/src/sync.js +19 -15
  76. package/dist/src/tool-catalog.d.ts +18 -0
  77. package/dist/src/tool-catalog.js +232 -0
  78. package/dist/src/tools/marksman.js +1 -1
  79. package/dist/src/tools.js +111 -65
  80. package/dist/src/types.d.ts +127 -71
  81. package/dist/src/utils.d.ts +57 -6
  82. package/dist/src/utils.js +114 -28
  83. package/dist/src/vault-tools.d.ts +34 -0
  84. package/dist/src/vault-tools.js +99 -0
  85. package/dist/src/vault-writer.js +4 -1
  86. package/dist/src/vm-handlers.js +140 -43
  87. package/dist/src/watcher.js +9 -9
  88. package/dist/test/activity-tool.test.js +54 -0
  89. package/dist/test/agent-bus/Agent.test.js +174 -0
  90. package/dist/test/agent-bus/AgentLoader.test.js +180 -0
  91. package/dist/test/agent-bus/AgentRegistry.test.js +86 -0
  92. package/dist/test/agent-bus/LLMProvider.test.js +162 -0
  93. package/dist/test/agent-bus/TaskQueue.test.js +256 -0
  94. package/dist/test/agent-dispatch-context.test.js +73 -0
  95. package/dist/test/agent-queue.test.js +1 -1
  96. package/dist/test/agents/Agents.test.js +282 -0
  97. package/dist/test/auth.test.js +57 -56
  98. package/dist/test/bridge-identity.test.js +34 -3
  99. package/dist/test/classify-search-mode.test.js +51 -0
  100. package/dist/test/commands.test.js +410 -0
  101. package/dist/test/config-merge.test.js +98 -0
  102. package/dist/test/context-capture.test.js +56 -0
  103. package/dist/test/discover-schema.test.js +8 -5
  104. package/dist/test/dispatch.test.js +45 -91
  105. package/dist/test/edits.test.js +144 -0
  106. package/dist/test/embedding-probe.test.js +424 -0
  107. package/dist/test/embedding-providers.test.js +157 -0
  108. package/dist/test/embedding-secrets.test.js +210 -0
  109. package/dist/test/engine-identity.test.js +1 -1
  110. package/dist/test/events.test.js +675 -0
  111. package/dist/test/git-bridge.test.js +160 -0
  112. package/dist/test/graph.test.js +464 -0
  113. package/dist/test/helpers/server.js +81 -0
  114. package/dist/test/identity-injector.test.js +197 -0
  115. package/dist/test/index.test.js +5 -7
  116. package/dist/test/lance-modal.test.js +67 -2
  117. package/dist/test/lance.test.js +429 -0
  118. package/dist/test/modal-client.test.js +1 -1
  119. package/dist/test/modal-config.test.js +92 -79
  120. package/dist/test/model-readiness.test.js +122 -0
  121. package/dist/test/model-router.test.js +99 -0
  122. package/dist/test/obsidian-client.test.js +42 -0
  123. package/dist/test/personalize.test.js +1 -1
  124. package/dist/test/rest-models.test.js +153 -0
  125. package/dist/test/rest-queue.test.js +135 -87
  126. package/dist/test/rest-setup.test.js +625 -115
  127. package/dist/test/rest-vm.test.js +355 -94
  128. package/dist/test/server-cors.test.js +48 -0
  129. package/dist/test/server-ws.test.js +61 -34
  130. package/dist/test/session-crud.test.js +323 -0
  131. package/dist/test/session-search.test.js +139 -0
  132. package/dist/test/settings-ui.test.js +113 -4
  133. package/dist/test/sync.test.js +12 -12
  134. package/dist/test/tombstone.test.js +8 -10
  135. package/dist/test/tool-catalog.test.js +86 -0
  136. package/dist/test/utils.test.js +588 -0
  137. package/dist/test/vault-tools.test.js +103 -12
  138. package/dist/test/vault-writer.test.js +371 -0
  139. package/dist/test/vm-handlers.test.js +620 -0
  140. package/extension-packages.json +9 -0
  141. package/package.json +107 -90
  142. package/pi-vault-mind.config.example.json +24 -2
  143. package/scripts/check-deps.sh +35 -32
  144. package/scripts/cli-e2e.mjs +215 -0
  145. package/scripts/configuration-e2e.mjs +783 -0
  146. package/scripts/e2e-commands.mjs +391 -0
  147. package/scripts/e2e-ws.mjs +3 -2
  148. package/scripts/fetch-modal-token.sh +4 -3
  149. package/scripts/generate-config-keys-json.mjs +45 -0
  150. package/scripts/generate-extension-packages-json.mjs +55 -0
  151. package/scripts/pi-session-query +0 -0
  152. package/scripts/publish-obsidian-plugin.sh +0 -0
  153. package/scripts/reset-test-vault.sh +2 -2
  154. package/scripts/setup-test-config.sh +0 -0
  155. package/scripts/setup-vault-pi.sh +48 -9
  156. package/scripts/test-slash-commands.mjs +2 -2
  157. package/scripts/vault-pi.sh +12 -3
  158. package/skills/github-release-notes-file/SKILL.md +42 -0
  159. package/skills/obsidian-guided-test-session/SKILL.md +110 -0
  160. package/skills/obsidian-interactive-test/SKILL.md +88 -0
  161. package/skills/obsidian-plugin-publish/SKILL.md +58 -0
  162. package/skills/pi-vault-mind-release/SKILL.md +141 -0
  163. package/skills/pre-test-release/SKILL.md +116 -0
  164. package/dist/test/auto-indexer.test.js +0 -2
@@ -0,0 +1,160 @@
1
+ import { strict as assert } from "node:assert";
2
+ import { execFileSync } from "node:child_process";
3
+ import * as fs from "node:fs";
4
+ import * as os from "node:os";
5
+ import * as path from "node:path";
6
+ import { after, afterEach, before, beforeEach, describe, it } from "node:test";
7
+ import { _resetAuthCache } from "../src/auth.js";
8
+ import { fakePi, fetchJson, makeVault, startTestServer, TEST_TOKEN, writeVaultConfig, } from "./helpers/server.js";
9
+ const envVar = "PVM_API_TOKEN";
10
+ describe("Git bridge routes", () => {
11
+ let vaultPath;
12
+ let port;
13
+ let srv;
14
+ let savedEnv;
15
+ let savedCwd;
16
+ before(() => {
17
+ savedEnv = process.env[envVar];
18
+ savedCwd = process.cwd();
19
+ process.env[envVar] = TEST_TOKEN;
20
+ });
21
+ afterEach(() => {
22
+ // Always release the server handle — even on assertion failure.
23
+ srv?.stop();
24
+ });
25
+ after(() => {
26
+ srv?.stop();
27
+ if (savedEnv === undefined)
28
+ delete process.env[envVar];
29
+ else
30
+ process.env[envVar] = savedEnv;
31
+ process.chdir(savedCwd);
32
+ _resetAuthCache();
33
+ });
34
+ beforeEach(() => {
35
+ // Each test gets a fresh vault + git repo
36
+ vaultPath = makeVault("git-bridge");
37
+ process.chdir(vaultPath);
38
+ });
39
+ function initGitRepo(dir) {
40
+ execFileSync("git", ["init"], { cwd: dir, timeout: 5000 });
41
+ execFileSync("git", ["config", "user.email", "test@test.com"], { cwd: dir, timeout: 5000 });
42
+ execFileSync("git", ["config", "user.name", "Test"], { cwd: dir, timeout: 5000 });
43
+ fs.writeFileSync(path.join(dir, "README.md"), "# test\n", "utf-8");
44
+ // Ignore server-created files so the tree stays clean after server boot.
45
+ fs.writeFileSync(path.join(dir, ".gitignore"), ".vault-mind/\n", "utf-8");
46
+ writeVaultConfig(vaultPath, {
47
+ vaultMind: { vaults: { default: { path: dir } } },
48
+ });
49
+ execFileSync("git", ["add", "."], { cwd: dir, timeout: 5000 });
50
+ execFileSync("git", ["commit", "-m", "init"], { cwd: dir, timeout: 5000 });
51
+ execFileSync("git", ["branch", "feature-x"], { cwd: dir, timeout: 5000 });
52
+ }
53
+ async function bootServer() {
54
+ srv = await startTestServer(fakePi);
55
+ port = srv.port;
56
+ }
57
+ it("GET /git/status returns 401 without token", async () => {
58
+ initGitRepo(vaultPath);
59
+ await bootServer();
60
+ const { status } = await fetchJson(port, "GET", "/git/status");
61
+ assert.equal(status, 401);
62
+ });
63
+ it("GET /git/status returns repo info for a git repo", async () => {
64
+ initGitRepo(vaultPath);
65
+ await bootServer();
66
+ const { status, body } = await fetchJson(port, "GET", "/git/status", { token: TEST_TOKEN });
67
+ assert.equal(status, 200);
68
+ const d = body;
69
+ assert.equal(d.isRepo, true);
70
+ assert.ok(d.branch === "main" || d.branch === "master", `expected main or master, got ${d.branch}`);
71
+ assert.equal(d.dirty, false);
72
+ assert.equal(d.detached, false);
73
+ assert.equal(d.ahead, 0);
74
+ assert.equal(d.behind, 0);
75
+ });
76
+ it("GET /git/branches lists branches", async () => {
77
+ initGitRepo(vaultPath);
78
+ await bootServer();
79
+ const { status, body } = await fetchJson(port, "GET", "/git/branches", { token: TEST_TOKEN });
80
+ assert.equal(status, 200);
81
+ const d = body;
82
+ assert.equal(d.isRepo, true);
83
+ const branches = d.branches;
84
+ assert.ok(branches.includes("feature-x"), "branches should include feature-x");
85
+ assert.ok(d.current === "main" || d.current === "master", `expected main or master, got ${d.current}`);
86
+ });
87
+ it("POST /git/checkout switches to feature-x", async () => {
88
+ initGitRepo(vaultPath);
89
+ await bootServer();
90
+ const { status, body } = await fetchJson(port, "POST", "/git/checkout", {
91
+ body: { branch: "feature-x" },
92
+ token: TEST_TOKEN,
93
+ });
94
+ assert.equal(status, 200);
95
+ const d = body;
96
+ assert.equal(d.ok, true);
97
+ assert.equal(d.branch, "feature-x");
98
+ // Verify via status
99
+ const { status: s2, body: b2 } = await fetchJson(port, "GET", "/git/status", {
100
+ token: TEST_TOKEN,
101
+ });
102
+ assert.equal(s2, 200);
103
+ assert.equal(b2.branch, "feature-x");
104
+ });
105
+ it("POST /git/checkout returns 400 for unknown branch", async () => {
106
+ initGitRepo(vaultPath);
107
+ await bootServer();
108
+ const { status } = await fetchJson(port, "POST", "/git/checkout", {
109
+ body: { branch: "no-such" },
110
+ token: TEST_TOKEN,
111
+ });
112
+ assert.equal(status, 400);
113
+ });
114
+ it("POST /git/checkout returns 400 for missing branch", async () => {
115
+ initGitRepo(vaultPath);
116
+ await bootServer();
117
+ const { status } = await fetchJson(port, "POST", "/git/checkout", {
118
+ body: {},
119
+ token: TEST_TOKEN,
120
+ });
121
+ assert.equal(status, 400);
122
+ });
123
+ it("POST /git/checkout returns 400 for invalid branch name", async () => {
124
+ initGitRepo(vaultPath);
125
+ await bootServer();
126
+ const { status } = await fetchJson(port, "POST", "/git/checkout", {
127
+ body: { branch: "-x" },
128
+ token: TEST_TOKEN,
129
+ });
130
+ assert.equal(status, 400);
131
+ });
132
+ it("GET /git/status returns isRepo:false for non-repo", async () => {
133
+ // Create a vault OUTSIDE any git repo so git rev-parse can't walk up
134
+ // to the parent pi-vault-mind .git directory.
135
+ const nonRepoVault = fs.mkdtempSync(path.join(os.tmpdir(), "pvm-nogit-"));
136
+ try {
137
+ writeVaultConfig(nonRepoVault, {
138
+ vaultMind: { vaults: { default: { path: nonRepoVault } } },
139
+ });
140
+ process.chdir(nonRepoVault);
141
+ await bootServer();
142
+ const { status, body } = await fetchJson(port, "GET", "/git/status", { token: TEST_TOKEN });
143
+ assert.equal(status, 200);
144
+ const d = body;
145
+ assert.equal(d.isRepo, false);
146
+ assert.equal(d.branch, null);
147
+ }
148
+ finally {
149
+ srv?.stop();
150
+ process.chdir(savedCwd);
151
+ fs.rmSync(nonRepoVault, { recursive: true, force: true });
152
+ }
153
+ });
154
+ it("GET /git/status returns 405 for POST", async () => {
155
+ initGitRepo(vaultPath);
156
+ await bootServer();
157
+ const { status } = await fetchJson(port, "POST", "/git/status", { token: TEST_TOKEN });
158
+ assert.equal(status, 405);
159
+ });
160
+ });
@@ -0,0 +1,464 @@
1
+ import { strict as assert } from "node:assert";
2
+ import { mkdtempSync, rmSync } from "node:fs";
3
+ import { tmpdir } from "node:os";
4
+ import { join } from "node:path";
5
+ import { afterEach, beforeEach, describe, it } from "node:test";
6
+ import * as lancedb from "@lancedb/lancedb";
7
+ import * as arrow from "apache-arrow";
8
+ import { graphUpsert, queryGraph } from "../src/graph.js";
9
+ import { resetConnection } from "../src/lance.js";
10
+ import { normalizeGraphResult } from "../src/vault-tools.js";
11
+ // ---------------------------------------------------------------------------
12
+ // Helpers
13
+ // ---------------------------------------------------------------------------
14
+ function makeConfig(dataDir) {
15
+ return {
16
+ dataDir,
17
+ embedding: {
18
+ // No remote URL — graph tables don't need embeddings for these tests
19
+ },
20
+ };
21
+ }
22
+ function makeEntitySchema() {
23
+ return new arrow.Schema([
24
+ new arrow.Field("id", new arrow.Utf8()),
25
+ new arrow.Field("name", new arrow.Utf8()),
26
+ new arrow.Field("type", new arrow.Utf8()),
27
+ new arrow.Field("aliases", new arrow.Utf8()),
28
+ new arrow.Field("summary", new arrow.Utf8()),
29
+ new arrow.Field("collection_ids", new arrow.Utf8()),
30
+ new arrow.Field("created_at", new arrow.Utf8()),
31
+ new arrow.Field("updated_at", new arrow.Utf8()),
32
+ ]);
33
+ }
34
+ function makeRelationSchema() {
35
+ return new arrow.Schema([
36
+ new arrow.Field("id", new arrow.Utf8()),
37
+ new arrow.Field("from_entity_id", new arrow.Utf8()),
38
+ new arrow.Field("to_entity_id", new arrow.Utf8()),
39
+ new arrow.Field("relation_type", new arrow.Utf8()),
40
+ new arrow.Field("fact", new arrow.Utf8()),
41
+ new arrow.Field("fact_strength", new arrow.Float32()),
42
+ new arrow.Field("source_entry_ids", new arrow.Utf8()),
43
+ new arrow.Field("valid_at", new arrow.Utf8()),
44
+ new arrow.Field("expired_at", new arrow.Utf8()),
45
+ new arrow.Field("created_at", new arrow.Utf8()),
46
+ ]);
47
+ }
48
+ async function createGraphTables(dataDir) {
49
+ const conn = await lancedb.connect(dataDir);
50
+ const existing = await conn.tableNames();
51
+ if (!existing.includes("entities")) {
52
+ await conn.createEmptyTable("entities", makeEntitySchema());
53
+ }
54
+ if (!existing.includes("relations")) {
55
+ await conn.createEmptyTable("relations", makeRelationSchema());
56
+ }
57
+ }
58
+ // ---------------------------------------------------------------------------
59
+ // extractEntities (pure function, tested via graphUpsert behavior)
60
+ // ---------------------------------------------------------------------------
61
+ describe("extractEntities", () => {
62
+ it("extracts capitalized multi-word phrases", async () => {
63
+ const dir = mkdtempSync(join(tmpdir(), "graph-test-"));
64
+ try {
65
+ await createGraphTables(dir);
66
+ const cfg = makeConfig(dir);
67
+ await graphUpsert(dir, cfg, {
68
+ id: "entry-1",
69
+ fact: "Authentication Service depends on User Database for identity verification.",
70
+ });
71
+ const result = (await queryGraph(dir, cfg, "Authentication", 1));
72
+ const names = result.entities.map((e) => e.name);
73
+ assert.ok(names.includes("Authentication Service"), "should extract 'Authentication Service'");
74
+ // Query separately for User Database
75
+ const result2 = (await queryGraph(dir, cfg, "User Database", 1));
76
+ const names2 = result2.entities.map((e) => e.name);
77
+ assert.ok(names2.includes("User Database"), "should extract 'User Database'");
78
+ }
79
+ finally {
80
+ resetConnection();
81
+ rmSync(dir, { recursive: true, force: true });
82
+ }
83
+ });
84
+ it("extracts quoted phrases", async () => {
85
+ const dir = mkdtempSync(join(tmpdir(), "graph-test-"));
86
+ try {
87
+ await createGraphTables(dir);
88
+ const cfg = makeConfig(dir);
89
+ await graphUpsert(dir, cfg, {
90
+ id: "entry-2",
91
+ fact: 'The "primary key" concept is fundamental to database design.',
92
+ });
93
+ const result = (await queryGraph(dir, cfg, "primary", 1));
94
+ const names = result.entities.map((e) => e.name);
95
+ assert.ok(names.includes("primary key"), "should extract quoted phrase 'primary key'");
96
+ }
97
+ finally {
98
+ resetConnection();
99
+ rmSync(dir, { recursive: true, force: true });
100
+ }
101
+ });
102
+ it("detects keyword-based entity types", async () => {
103
+ const dir = mkdtempSync(join(tmpdir(), "graph-test-"));
104
+ try {
105
+ await createGraphTables(dir);
106
+ const cfg = makeConfig(dir);
107
+ await graphUpsert(dir, cfg, {
108
+ id: "entry-3",
109
+ fact: "The authentication system requires a database for the API server.",
110
+ });
111
+ // Query for each keyword entity individually
112
+ const authResult = (await queryGraph(dir, cfg, "Authentication", 1));
113
+ const authEntity = authResult.entities.find((e) => e.name === "Authentication");
114
+ assert.ok(authEntity, "should find Authentication entity");
115
+ assert.equal(authEntity?.type, "system", "keyword 'authentication' → type 'system'");
116
+ const dbResult = (await queryGraph(dir, cfg, "Database", 1));
117
+ const dbEntity = dbResult.entities.find((e) => e.name === "Database");
118
+ assert.ok(dbEntity, "should find Database entity");
119
+ assert.equal(dbEntity?.type, "system", "keyword 'database' → type 'system'");
120
+ const apiResult = (await queryGraph(dir, cfg, "Api", 1));
121
+ const apiEntity = apiResult.entities.find((e) => e.name === "Api");
122
+ assert.ok(apiEntity, "should find Api entity");
123
+ assert.equal(apiEntity?.type, "system", "keyword 'api' → type 'system'");
124
+ const serverResult = (await queryGraph(dir, cfg, "Server", 1));
125
+ const serverEntity = serverResult.entities.find((e) => e.name === "Server");
126
+ assert.ok(serverEntity, "should find Server entity");
127
+ assert.equal(serverEntity?.type, "system", "keyword 'server' → type 'system'");
128
+ }
129
+ finally {
130
+ resetConnection();
131
+ rmSync(dir, { recursive: true, force: true });
132
+ }
133
+ });
134
+ it("returns empty array for text with no entities", async () => {
135
+ const dir = mkdtempSync(join(tmpdir(), "graph-test-"));
136
+ try {
137
+ await createGraphTables(dir);
138
+ const cfg = makeConfig(dir);
139
+ // graphUpsert returns early when no entities are found — no error
140
+ await graphUpsert(dir, cfg, {
141
+ id: "entry-4",
142
+ fact: "just some lowercase words with nothing special",
143
+ });
144
+ const result = (await queryGraph(dir, cfg, "nothing", 1));
145
+ assert.equal(result.entities.length, 0, "no entities should be stored");
146
+ assert.ok(result.message, "should include a message about no matches");
147
+ }
148
+ finally {
149
+ resetConnection();
150
+ rmSync(dir, { recursive: true, force: true });
151
+ }
152
+ });
153
+ it("handles empty string", async () => {
154
+ const dir = mkdtempSync(join(tmpdir(), "graph-test-"));
155
+ try {
156
+ await createGraphTables(dir);
157
+ const cfg = makeConfig(dir);
158
+ // Should not throw — returns early
159
+ await graphUpsert(dir, cfg, {
160
+ id: "entry-5",
161
+ fact: "",
162
+ });
163
+ }
164
+ finally {
165
+ resetConnection();
166
+ rmSync(dir, { recursive: true, force: true });
167
+ }
168
+ });
169
+ });
170
+ // ---------------------------------------------------------------------------
171
+ // extractRelations (pure function, tested via graphUpsert + queryGraph)
172
+ // ---------------------------------------------------------------------------
173
+ describe("extractRelations", () => {
174
+ it("extracts relations between entities in the same sentence", async () => {
175
+ const dir = mkdtempSync(join(tmpdir(), "graph-test-"));
176
+ try {
177
+ await createGraphTables(dir);
178
+ const cfg = makeConfig(dir);
179
+ await graphUpsert(dir, cfg, {
180
+ id: "entry-6",
181
+ fact: "The Authentication Service relates to the User Database.",
182
+ });
183
+ const result = (await queryGraph(dir, cfg, "Authentication", 2));
184
+ assert.ok(result.relations.length > 0, "should have at least one relation");
185
+ }
186
+ finally {
187
+ resetConnection();
188
+ rmSync(dir, { recursive: true, force: true });
189
+ }
190
+ });
191
+ it("detects 'depends on' relation type", async () => {
192
+ const dir = mkdtempSync(join(tmpdir(), "graph-test-"));
193
+ try {
194
+ await createGraphTables(dir);
195
+ const cfg = makeConfig(dir);
196
+ await graphUpsert(dir, cfg, {
197
+ id: "entry-7",
198
+ fact: "The Frontend depends on the Backend API for data.",
199
+ });
200
+ const result = (await queryGraph(dir, cfg, "Frontend", 2));
201
+ const depRelations = result.relations.filter((r) => r.relation_type === "depends-on");
202
+ assert.ok(depRelations.length > 0, "should detect 'depends on' → depends-on relation");
203
+ }
204
+ finally {
205
+ resetConnection();
206
+ rmSync(dir, { recursive: true, force: true });
207
+ }
208
+ });
209
+ it("detects 'is a' relation type", async () => {
210
+ const dir = mkdtempSync(join(tmpdir(), "graph-test-"));
211
+ try {
212
+ await createGraphTables(dir);
213
+ const cfg = makeConfig(dir);
214
+ await graphUpsert(dir, cfg, {
215
+ id: "entry-8",
216
+ fact: "A Car is a Vehicle in the transportation domain.",
217
+ });
218
+ const result = (await queryGraph(dir, cfg, "Car", 2));
219
+ const isARelations = result.relations.filter((r) => r.relation_type === "is-a");
220
+ assert.ok(isARelations.length > 0, "should detect 'is a' → is-a relation");
221
+ }
222
+ finally {
223
+ resetConnection();
224
+ rmSync(dir, { recursive: true, force: true });
225
+ }
226
+ });
227
+ it("detects 'part of' relation type", async () => {
228
+ const dir = mkdtempSync(join(tmpdir(), "graph-test-"));
229
+ try {
230
+ await createGraphTables(dir);
231
+ const cfg = makeConfig(dir);
232
+ await graphUpsert(dir, cfg, {
233
+ id: "entry-9",
234
+ fact: "The Engine is part of the Car assembly.",
235
+ });
236
+ const result = (await queryGraph(dir, cfg, "Engine", 2));
237
+ const partOfRelations = result.relations.filter((r) => r.relation_type === "part-of");
238
+ assert.ok(partOfRelations.length > 0, "should detect 'part of' → part-of relation");
239
+ }
240
+ finally {
241
+ resetConnection();
242
+ rmSync(dir, { recursive: true, force: true });
243
+ }
244
+ });
245
+ it("detects 'contradicts' relation type", async () => {
246
+ const dir = mkdtempSync(join(tmpdir(), "graph-test-"));
247
+ try {
248
+ await createGraphTables(dir);
249
+ const cfg = makeConfig(dir);
250
+ await graphUpsert(dir, cfg, {
251
+ id: "entry-10",
252
+ fact: "The New Design contradicts the Old Specification in several ways.",
253
+ });
254
+ const result = (await queryGraph(dir, cfg, "New Design", 2));
255
+ const contradictRelations = result.relations.filter((r) => r.relation_type === "contradicts");
256
+ assert.ok(contradictRelations.length > 0, "should detect 'contradicts' → contradicts relation");
257
+ }
258
+ finally {
259
+ resetConnection();
260
+ rmSync(dir, { recursive: true, force: true });
261
+ }
262
+ });
263
+ it("returns empty array when no relations found (single entity)", async () => {
264
+ const dir = mkdtempSync(join(tmpdir(), "graph-test-"));
265
+ try {
266
+ await createGraphTables(dir);
267
+ const cfg = makeConfig(dir);
268
+ await graphUpsert(dir, cfg, {
269
+ id: "entry-11",
270
+ fact: "Kubernetes runs.",
271
+ });
272
+ const result = (await queryGraph(dir, cfg, "Kubernetes", 2));
273
+ // Only one entity → no relations can be formed
274
+ assert.equal(result.relations.length, 0, "single entity should produce no relations");
275
+ }
276
+ finally {
277
+ resetConnection();
278
+ rmSync(dir, { recursive: true, force: true });
279
+ }
280
+ });
281
+ it("assigns strength 0.8 to relations", async () => {
282
+ const dir = mkdtempSync(join(tmpdir(), "graph-test-"));
283
+ try {
284
+ await createGraphTables(dir);
285
+ const cfg = makeConfig(dir);
286
+ await graphUpsert(dir, cfg, {
287
+ id: "entry-12",
288
+ fact: "The Logger depends on the Config module.",
289
+ });
290
+ const result = (await queryGraph(dir, cfg, "Logger", 2));
291
+ assert.ok(result.relations.length > 0, "should have relations");
292
+ for (const rel of result.relations) {
293
+ assert.ok(Math.abs(rel.fact_strength - 0.8) < 0.001, "all relations should have strength ~0.8");
294
+ }
295
+ }
296
+ finally {
297
+ resetConnection();
298
+ rmSync(dir, { recursive: true, force: true });
299
+ }
300
+ });
301
+ });
302
+ // ---------------------------------------------------------------------------
303
+ // graphUpsert (LanceDB integration)
304
+ // ---------------------------------------------------------------------------
305
+ describe("graphUpsert", () => {
306
+ let dir;
307
+ let cfg;
308
+ beforeEach(async () => {
309
+ dir = mkdtempSync(join(tmpdir(), "graph-test-"));
310
+ await createGraphTables(dir);
311
+ cfg = makeConfig(dir);
312
+ });
313
+ afterEach(() => {
314
+ resetConnection();
315
+ rmSync(dir, { recursive: true, force: true });
316
+ });
317
+ it("creates entity rows from the entry's fact field", async () => {
318
+ await graphUpsert(dir, cfg, {
319
+ id: "entry-upsert-1",
320
+ fact: "Payment Service processes transactions.",
321
+ });
322
+ const result = (await queryGraph(dir, cfg, "Payment", 1));
323
+ assert.ok(result.entities.length > 0, "should have stored entities");
324
+ const names = result.entities.map((e) => e.name);
325
+ assert.ok(names.includes("Payment Service"), "should store 'Payment Service'");
326
+ });
327
+ it("upserts relations between extracted entities", async () => {
328
+ await graphUpsert(dir, cfg, {
329
+ id: "entry-upsert-2",
330
+ fact: "The Cache depends on the Database for persistence.",
331
+ });
332
+ const result = (await queryGraph(dir, cfg, "Cache", 2));
333
+ assert.ok(result.relations.length > 0, "should have stored relations");
334
+ });
335
+ it("handles entries with no extractable entities gracefully", async () => {
336
+ // Should not throw — returns early when no entities found
337
+ await graphUpsert(dir, cfg, {
338
+ id: "entry-upsert-3",
339
+ fact: "just some words",
340
+ });
341
+ // Verify nothing was stored
342
+ const result = (await queryGraph(dir, cfg, "words", 1));
343
+ assert.equal(result.entities.length, 0, "no entities should be stored for unextractable text");
344
+ });
345
+ it("deduplicates entities by name on re-upsert", async () => {
346
+ await graphUpsert(dir, cfg, {
347
+ id: "entry-dup-1",
348
+ fact: "Auth Module handles login.",
349
+ });
350
+ await graphUpsert(dir, cfg, {
351
+ id: "entry-dup-2",
352
+ fact: "Auth Module also handles logout.",
353
+ });
354
+ const result = (await queryGraph(dir, cfg, "Auth", 1));
355
+ const authEntities = result.entities.filter((e) => e.name === "Auth Module");
356
+ assert.equal(authEntities.length, 1, "should have exactly one 'Auth Module' entity");
357
+ });
358
+ });
359
+ // ---------------------------------------------------------------------------
360
+ // queryGraph (LanceDB integration)
361
+ // ---------------------------------------------------------------------------
362
+ describe("queryGraph", () => {
363
+ let dir;
364
+ let cfg;
365
+ beforeEach(async () => {
366
+ dir = mkdtempSync(join(tmpdir(), "graph-test-"));
367
+ await createGraphTables(dir);
368
+ cfg = makeConfig(dir);
369
+ });
370
+ afterEach(() => {
371
+ resetConnection();
372
+ rmSync(dir, { recursive: true, force: true });
373
+ });
374
+ it("returns entities matching the query", async () => {
375
+ await graphUpsert(dir, cfg, {
376
+ id: "entry-q-1",
377
+ fact: "Notification Service sends alerts.",
378
+ });
379
+ const result = (await queryGraph(dir, cfg, "Notification", 1));
380
+ assert.ok(result.entities.length > 0, "should find matching entities");
381
+ assert.equal(result.entities[0].name, "Notification Service");
382
+ });
383
+ it("returns relations for matched entities up to specified depth", async () => {
384
+ // Create a chain: A depends on B, B depends on C
385
+ await graphUpsert(dir, cfg, {
386
+ id: "entry-chain-1",
387
+ fact: "Frontend depends on Backend.",
388
+ });
389
+ await graphUpsert(dir, cfg, {
390
+ id: "entry-chain-2",
391
+ fact: "Backend depends on Database.",
392
+ });
393
+ // Depth 1: should find Frontend and its relation to Backend
394
+ const resultDepth1 = (await queryGraph(dir, cfg, "Frontend", 1));
395
+ assert.ok(resultDepth1.entities.length > 0, "depth 1 should find seed entity");
396
+ assert.ok(resultDepth1.relations.length > 0, "depth 1 should find direct relations");
397
+ // Depth 2: should also traverse to Database
398
+ const resultDepth2 = (await queryGraph(dir, cfg, "Frontend", 2));
399
+ assert.ok(resultDepth2.relations.length >= resultDepth1.relations.length, "depth 2 should find at least as many relations as depth 1");
400
+ });
401
+ it("returns empty results for non-matching queries", async () => {
402
+ await graphUpsert(dir, cfg, {
403
+ id: "entry-q-2",
404
+ fact: "The Logger writes to disk.",
405
+ });
406
+ const result = (await queryGraph(dir, cfg, "NonexistentEntity", 1));
407
+ assert.equal(result.entities.length, 0, "should return empty entities");
408
+ assert.equal(result.relations.length, 0, "should return empty relations");
409
+ assert.ok(result.message, "should include a message");
410
+ });
411
+ it("returns partial match via LIKE query", async () => {
412
+ await graphUpsert(dir, cfg, {
413
+ id: "entry-q-3",
414
+ fact: "The UserAuthenticationService is critical.",
415
+ });
416
+ const result = (await queryGraph(dir, cfg, "Auth", 1));
417
+ assert.ok(result.entities.length > 0, "LIKE query should find partial matches");
418
+ assert.ok(result.entities[0].name.includes("Auth"), "matched entity should contain query substring");
419
+ });
420
+ });
421
+ // ---------------------------------------------------------------------------
422
+ // normalizeGraphResult (pure — the shared graph→search-shape normalizer)
423
+ // ---------------------------------------------------------------------------
424
+ describe("normalizeGraphResult", () => {
425
+ it("flattens entities into a flat hits array tagged _source: graph with entity=name", () => {
426
+ const norm = normalizeGraphResult({
427
+ entities: [
428
+ { id: "e1", name: "Alpha", kind: "service" },
429
+ { id: "e2", name: "Beta" },
430
+ ],
431
+ relations: [{ from: "e1", to: "e2", relation_type: "depends_on" }],
432
+ });
433
+ assert.equal(norm.hits.length, 2);
434
+ assert.ok(norm.hits.every((h) => h._source === "graph"), "every hit is tagged _source: graph");
435
+ assert.equal(norm.hits[0].entity, "Alpha");
436
+ assert.equal(norm.hits[0].name, "Alpha");
437
+ assert.equal(norm.hits[0].kind, "service");
438
+ assert.equal(norm.hits[1].entity, "Beta");
439
+ });
440
+ it("preserves relations as a sibling array, not as a hit", () => {
441
+ const norm = normalizeGraphResult({
442
+ entities: [{ name: "X" }],
443
+ relations: [{ relation_type: "depends_on" }],
444
+ });
445
+ assert.ok(Array.isArray(norm.relations));
446
+ assert.equal(norm.relations.length, 1);
447
+ assert.ok(norm.hits.every((h) => h.relation_type === undefined), "relations must not leak into hits");
448
+ });
449
+ it("carries through the empty-graph message with empty hits/relations", () => {
450
+ const norm = normalizeGraphResult({
451
+ entities: [],
452
+ relations: [],
453
+ message: "No matching entities found.",
454
+ });
455
+ assert.equal(norm.hits.length, 0);
456
+ assert.equal(norm.relations.length, 0);
457
+ assert.equal(norm.message, "No matching entities found.");
458
+ });
459
+ it("tolerates missing fields and non-object input", () => {
460
+ assert.deepEqual(normalizeGraphResult(undefined), { hits: [], relations: [] });
461
+ assert.deepEqual(normalizeGraphResult({}), { hits: [], relations: [] });
462
+ assert.deepEqual(normalizeGraphResult([]), { hits: [], relations: [] });
463
+ });
464
+ });