md-semantic-search 0.4.0 → 0.5.0

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 (61) hide show
  1. package/README.md +81 -0
  2. package/bin/cli.mjs +368 -14
  3. package/dist/collapse.d.ts +6 -0
  4. package/dist/collapse.js +20 -0
  5. package/dist/core.d.ts +84 -0
  6. package/dist/core.js +479 -0
  7. package/dist/frontmatter.d.ts +20 -0
  8. package/dist/frontmatter.js +150 -0
  9. package/dist/index-format.d.ts +23 -0
  10. package/dist/index-format.js +125 -0
  11. package/dist/index.d.ts +29 -0
  12. package/dist/index.js +29 -0
  13. package/dist/indexer.d.ts +70 -0
  14. package/dist/indexer.js +452 -0
  15. package/dist/ivf.d.ts +33 -0
  16. package/dist/ivf.js +144 -0
  17. package/dist/lexical.d.ts +44 -0
  18. package/dist/lexical.js +226 -0
  19. package/dist/markdown-parser.d.ts +27 -0
  20. package/dist/markdown-parser.js +252 -0
  21. package/dist/mcp.d.ts +111 -0
  22. package/dist/mcp.js +216 -0
  23. package/dist/metrics.d.ts +43 -0
  24. package/dist/metrics.js +97 -0
  25. package/dist/models.d.ts +38 -0
  26. package/dist/models.js +181 -0
  27. package/dist/rerank.d.ts +10 -0
  28. package/dist/rerank.js +41 -0
  29. package/dist/search.d.ts +135 -0
  30. package/dist/search.js +492 -0
  31. package/dist/serve.d.ts +49 -0
  32. package/dist/serve.js +321 -0
  33. package/dist/tui.d.ts +17 -0
  34. package/dist/tui.js +196 -0
  35. package/dist/wikilinks.d.ts +47 -0
  36. package/dist/wikilinks.js +171 -0
  37. package/package.json +19 -5
  38. package/src/{collapse.mjs → collapse.ts} +7 -12
  39. package/src/core.ts +546 -0
  40. package/src/{frontmatter.mjs → frontmatter.ts} +27 -50
  41. package/src/{index-format.mjs → index-format.ts} +57 -40
  42. package/src/{index.mjs → index.ts} +16 -8
  43. package/src/indexer.ts +585 -0
  44. package/src/ivf.ts +190 -0
  45. package/src/{lexical.mjs → lexical.ts} +66 -100
  46. package/src/{markdown-parser.mjs → markdown-parser.ts} +56 -100
  47. package/src/mcp.ts +243 -0
  48. package/src/metrics.ts +135 -0
  49. package/src/models.ts +219 -0
  50. package/src/rerank.ts +54 -0
  51. package/src/search.ts +628 -0
  52. package/src/serve.ts +372 -0
  53. package/src/tui.ts +227 -0
  54. package/src/{wikilinks.mjs → wikilinks.ts} +70 -67
  55. package/src/core.mjs +0 -535
  56. package/src/indexer.mjs +0 -540
  57. package/src/metrics.mjs +0 -186
  58. package/src/models.mjs +0 -299
  59. package/src/rerank.mjs +0 -75
  60. package/src/search.mjs +0 -636
  61. package/src/serve.mjs +0 -387
package/dist/serve.js ADDED
@@ -0,0 +1,321 @@
1
+ /**
2
+ * Long-running daemon mode (issue #12): keeps the parsed index AND the
3
+ * embedding extractor in memory across queries, so repeated searches skip
4
+ * the ~280 MB model load and the full vectors.json parse on every call.
5
+ */
6
+ import http from 'node:http';
7
+ import crypto from 'node:crypto';
8
+ import fs from 'node:fs';
9
+ import path from 'node:path';
10
+ import { buildIndex } from './indexer.js';
11
+ import { loadIndex, searchIndex } from './search.js';
12
+ import { walkMarkdown, assertSafePath } from './core.js';
13
+ const DEFAULT_PORT = 8747;
14
+ const DEFAULT_HOST = '127.0.0.1';
15
+ const WATCH_INTERVAL_MS = 3000;
16
+ const WATCH_DELAY_MS = 1000;
17
+ const MAX_BODY_BYTES = 64 * 1024;
18
+ export async function createServe(opts) {
19
+ const { indexDir, cacheDir, db, modelName = 'e5-base', ignore = [], offline = false, watch = false, watchInterval = WATCH_INTERVAL_MS, watchDelay = WATCH_DELAY_MS, apiKey = process.env.MDSS_API_KEY, healthPublic = process.env.MDSS_HEALTH_PUBLIC === 'true', embedFn, rerankFn, log = () => { }, } = opts;
20
+ if (indexDir)
21
+ assertSafePath(indexDir);
22
+ if (db)
23
+ assertSafePath(db);
24
+ fs.mkdirSync(indexDir, { recursive: true });
25
+ if (!fs.existsSync(path.join(indexDir, 'vectors.json'))) {
26
+ if (!db)
27
+ throw new Error('serve: no index found and no --db given to build one');
28
+ log(`No index at ${indexDir} — building it from ${db}…`);
29
+ await buildIndex({ db, indexDir, cacheDir, modelName, ignore, offline, log, embedFn });
30
+ }
31
+ const state = {
32
+ loaded: loadIndex(indexDir),
33
+ indexDir,
34
+ cacheDir,
35
+ offline,
36
+ embedFn,
37
+ rerankFn,
38
+ watching: watch,
39
+ apiKey,
40
+ healthPublic,
41
+ };
42
+ const server = http.createServer((req, res) => {
43
+ handleRequest(req, res, state).catch((e) => {
44
+ json(res, 500, { error: e.message });
45
+ });
46
+ });
47
+ let stopped = false;
48
+ let timer = null;
49
+ const reload = async () => {
50
+ if (!db)
51
+ return false;
52
+ log('Change detected — re-indexing…');
53
+ try {
54
+ await buildIndex({ db, indexDir, cacheDir, modelName, ignore, offline, log, embedFn });
55
+ }
56
+ catch (e) {
57
+ if (/(being written by pid|being written|lock)/i.test(String(e?.message || ''))) {
58
+ log(`re-index deferred: ${e.message}`);
59
+ return false;
60
+ }
61
+ throw e;
62
+ }
63
+ state.loaded = loadIndex(indexDir);
64
+ state.reindexCount = (state.reindexCount ?? 0) + 1;
65
+ log(`Re-indexed; ${state.loaded.index.chunks.length} chunks in memory.`);
66
+ return true;
67
+ };
68
+ const fileMd5 = (f) => crypto.createHash('md5').update(fs.readFileSync(f)).digest('hex');
69
+ const relOf = (f) => path.relative(db, f).split(path.sep).join('/');
70
+ const md5Cache = new Map();
71
+ const hashAt = (f, m) => {
72
+ const hit = md5Cache.get(f);
73
+ if (hit && hit.mtime === m)
74
+ return hit.md5;
75
+ const md5 = fileMd5(f);
76
+ md5Cache.set(f, { mtime: m, md5 });
77
+ return md5;
78
+ };
79
+ const treeContentFingerprint = (tree) => {
80
+ const parts = [];
81
+ for (const [f, { m, rel }] of tree) {
82
+ let md5;
83
+ try {
84
+ md5 = hashAt(f, m);
85
+ }
86
+ catch {
87
+ md5 = 'unreadable';
88
+ }
89
+ parts.push(`${rel}:${md5}`);
90
+ }
91
+ return parts.sort().join('|');
92
+ };
93
+ const readIndexedHashes = () => {
94
+ try {
95
+ return JSON.parse(fs.readFileSync(path.join(indexDir, '.hashes.json'), 'utf8'));
96
+ }
97
+ catch {
98
+ return {};
99
+ }
100
+ };
101
+ const scanTree = () => {
102
+ const tree = new Map();
103
+ if (!db)
104
+ return tree;
105
+ for (const f of walkMarkdown(db, ignore)) {
106
+ try {
107
+ tree.set(f, { m: fs.statSync(f).mtimeMs, rel: relOf(f) });
108
+ }
109
+ catch {
110
+ /* vanished */
111
+ }
112
+ }
113
+ return tree;
114
+ };
115
+ const contentChangedPaths = (tree, indexedHashes) => {
116
+ const out = [];
117
+ const liveRels = new Set();
118
+ for (const [f, { m, rel }] of tree) {
119
+ liveRels.add(rel);
120
+ if (!(rel in indexedHashes)) {
121
+ out.push(rel);
122
+ continue;
123
+ }
124
+ const cached = md5Cache.get(f);
125
+ if (cached && cached.mtime === m && cached.md5 === indexedHashes[rel])
126
+ continue;
127
+ let fresh;
128
+ try {
129
+ fresh = hashAt(f, m);
130
+ }
131
+ catch {
132
+ continue;
133
+ }
134
+ if (fresh !== indexedHashes[rel])
135
+ out.push(rel);
136
+ }
137
+ for (const rel of Object.keys(indexedHashes)) {
138
+ if (!liveRels.has(rel))
139
+ out.push(rel);
140
+ }
141
+ return out;
142
+ };
143
+ const watchLoop = async () => {
144
+ let indexedHashes = readIndexedHashes();
145
+ let lastFingerprint = treeContentFingerprint(scanTree());
146
+ let lastChangeAt = 0;
147
+ let pending = false;
148
+ while (!stopped) {
149
+ await new Promise((r) => {
150
+ timer = setTimeout(r, watchInterval);
151
+ });
152
+ if (stopped)
153
+ return;
154
+ const tree = scanTree();
155
+ const fingerprint = treeContentFingerprint(tree);
156
+ const changed = contentChangedPaths(tree, indexedHashes);
157
+ if (fingerprint !== lastFingerprint) {
158
+ if (!pending)
159
+ log(`watch: change in ${changed.length} file(s) — waiting ${watchDelay} ms for the tree to settle…`);
160
+ pending = true;
161
+ lastFingerprint = fingerprint;
162
+ lastChangeAt = Date.now();
163
+ }
164
+ else if (pending && changed.length > 0 && Date.now() - lastChangeAt >= watchDelay) {
165
+ pending = false;
166
+ await reload().catch((e) => log(`re-index failed: ${e.message}`));
167
+ indexedHashes = readIndexedHashes();
168
+ for (const [f, { m, rel }] of scanTree()) {
169
+ if (!md5Cache.has(f) && rel in indexedHashes) {
170
+ md5Cache.set(f, { mtime: m, md5: indexedHashes[rel] });
171
+ }
172
+ }
173
+ lastFingerprint = treeContentFingerprint(scanTree());
174
+ }
175
+ else if (!pending && changed.length > 0 && fingerprint === lastFingerprint) {
176
+ pending = true;
177
+ lastChangeAt = Date.now();
178
+ log(`watch: tree differs from index (no motion) — settling then re-index…`);
179
+ }
180
+ else if (pending && changed.length === 0 && Date.now() - lastChangeAt < watchDelay) {
181
+ pending = false;
182
+ }
183
+ }
184
+ };
185
+ if (watch) {
186
+ if (!db)
187
+ throw new Error('serve --watch requires --db');
188
+ watchLoop();
189
+ }
190
+ const close = async () => {
191
+ stopped = true;
192
+ if (timer)
193
+ clearTimeout(timer);
194
+ await new Promise((resolve, reject) => server.close((err) => (err ? reject(err) : resolve())));
195
+ };
196
+ return { server, state, close };
197
+ }
198
+ export function isAuthorizedToken(token, expectedKey) {
199
+ if (!token || typeof token !== 'string')
200
+ return false;
201
+ if (!expectedKey || typeof expectedKey !== 'string')
202
+ return false;
203
+ const a = Buffer.from(token);
204
+ const b = Buffer.from(expectedKey);
205
+ if (a.length !== b.length)
206
+ return false;
207
+ return crypto.timingSafeEqual(a, b);
208
+ }
209
+ async function handleRequest(req, res, state) {
210
+ const url = new URL(req.url || '/', 'http://localhost');
211
+ if (state.apiKey) {
212
+ const isPublicHealth = url.pathname === '/health' && req.method === 'GET' && state.healthPublic;
213
+ if (!isPublicHealth) {
214
+ const authHeader = req.headers['authorization'];
215
+ const match = typeof authHeader === 'string' ? authHeader.match(/^Bearer\s+(.+)$/i) : null;
216
+ const token = match ? match[1].trim() : null;
217
+ if (!token || !isAuthorizedToken(token, state.apiKey)) {
218
+ json(res, 401, { error: 'unauthorized' });
219
+ return;
220
+ }
221
+ }
222
+ }
223
+ if (req.method === 'POST' && url.pathname === '/search') {
224
+ const declared = req.headers['content-length'];
225
+ if (declared !== undefined) {
226
+ const n = Number(declared);
227
+ if (!Number.isInteger(n) || n < 0 || n > MAX_BODY_BYTES) {
228
+ json(res, 413, { error: `payload too large (limit ${MAX_BODY_BYTES} bytes)` });
229
+ return;
230
+ }
231
+ }
232
+ let body = '';
233
+ let tooLarge = false;
234
+ for await (const chunk of req) {
235
+ body += chunk;
236
+ if (body.length > MAX_BODY_BYTES) {
237
+ tooLarge = true;
238
+ break;
239
+ }
240
+ }
241
+ if (tooLarge) {
242
+ json(res, 413, { error: `payload too large (limit ${MAX_BODY_BYTES} bytes)` });
243
+ req.resume();
244
+ return;
245
+ }
246
+ let payload;
247
+ try {
248
+ payload = body ? JSON.parse(body) : {};
249
+ }
250
+ catch (e) {
251
+ json(res, 400, { error: `invalid JSON body: ${e.message}` });
252
+ return;
253
+ }
254
+ const query = typeof payload.query === 'string' ? payload.query.trim() : '';
255
+ if (!query) {
256
+ json(res, 400, { error: 'missing "query" string in JSON body' });
257
+ return;
258
+ }
259
+ if (query.length > 2048) {
260
+ json(res, 400, { error: 'query exceeds maximum length of 2048 characters' });
261
+ return;
262
+ }
263
+ const k = Number.isInteger(payload.k) && payload.k > 0 ? payload.k : 6;
264
+ try {
265
+ const results = await searchIndex({
266
+ loaded: state.loaded,
267
+ cacheDir: state.cacheDir,
268
+ query,
269
+ k,
270
+ semanticOnly: !!payload.semanticOnly,
271
+ rerank: !!payload.rerank,
272
+ offline: state.offline,
273
+ embedFn: state.embedFn,
274
+ rerankFn: state.rerankFn,
275
+ tag: payload.tag,
276
+ project: payload.project,
277
+ type: payload.type,
278
+ status: payload.status,
279
+ canonicalOnly: payload.canonicalOnly,
280
+ custom: payload.custom,
281
+ explain: !!payload.explain,
282
+ maxPerFile: payload.maxPerFile || payload.maxPerDoc,
283
+ ann: payload.ann,
284
+ nprobe: payload.nprobe,
285
+ });
286
+ json(res, 200, { query, k, count: results.length, results });
287
+ }
288
+ catch (e) {
289
+ json(res, 500, { error: e.message });
290
+ }
291
+ return;
292
+ }
293
+ if (req.method === 'GET' && url.pathname === '/health') {
294
+ json(res, 200, {
295
+ ok: true,
296
+ chunks: state.loaded.index.chunks.length,
297
+ model: state.loaded.model.id,
298
+ dim: state.loaded.index.dim || state.loaded.model.dim || 0,
299
+ built: state.loaded.index.built || null,
300
+ watching: state.watching,
301
+ indexDir: state.indexDir,
302
+ });
303
+ return;
304
+ }
305
+ if (req.method === 'GET' && (url.pathname === '/' || url.pathname === '/help')) {
306
+ json(res, 200, {
307
+ name: 'mdss serve',
308
+ endpoints: [
309
+ { method: 'POST', path: '/search', body: '{ "query": "...", "k": 6, "semanticOnly": false, "rerank": false }' },
310
+ { method: 'GET', path: '/health' },
311
+ ],
312
+ });
313
+ return;
314
+ }
315
+ json(res, 404, { error: `not found: ${req.method} ${url.pathname}` });
316
+ }
317
+ function json(res, status, data) {
318
+ res.writeHead(status, { 'content-type': 'application/json; charset=utf-8' });
319
+ res.end(JSON.stringify(data));
320
+ }
321
+ export { DEFAULT_PORT, DEFAULT_HOST, MAX_BODY_BYTES, WATCH_INTERVAL_MS };
package/dist/tui.d.ts ADDED
@@ -0,0 +1,17 @@
1
+ import { SearchResultHit } from './search.js';
2
+ export interface TuiOptions {
3
+ indexDir: string;
4
+ cacheDir: string;
5
+ db?: string;
6
+ query?: string;
7
+ k?: number;
8
+ semanticOnly?: boolean;
9
+ offline?: boolean;
10
+ path?: string | string[];
11
+ rerank?: boolean;
12
+ rerankPool?: number;
13
+ embedFn?: any;
14
+ rerankFn?: any;
15
+ debounceMs?: number;
16
+ }
17
+ export declare function runTui(opts: TuiOptions): Promise<SearchResultHit | null>;
package/dist/tui.js ADDED
@@ -0,0 +1,196 @@
1
+ import readline from 'node:readline';
2
+ import { spawn } from 'node:child_process';
3
+ import path from 'node:path';
4
+ import { loadIndex, searchIndex } from './search.js';
5
+ export async function runTui(opts) {
6
+ if (!process.stdin.isTTY || !process.stdout.isTTY) {
7
+ throw new Error('interactive TUI requires a TTY terminal stdin and stdout');
8
+ }
9
+ const loaded = loadIndex(opts.indexDir);
10
+ const db = opts.db || loaded.index.db || process.cwd();
11
+ let query = opts.query || '';
12
+ let selectedIndex = 0;
13
+ let results = [];
14
+ let searching = false;
15
+ let debounceTimer = null;
16
+ const performSearch = async () => {
17
+ if (!query.trim()) {
18
+ results = [];
19
+ selectedIndex = 0;
20
+ render();
21
+ return;
22
+ }
23
+ searching = true;
24
+ render();
25
+ try {
26
+ results = await searchIndex({
27
+ loaded,
28
+ cacheDir: opts.cacheDir,
29
+ query: query.trim(),
30
+ k: opts.k || 20,
31
+ semanticOnly: opts.semanticOnly,
32
+ offline: opts.offline,
33
+ path: opts.path,
34
+ rerank: opts.rerank,
35
+ rerankPool: opts.rerankPool,
36
+ embedFn: opts.embedFn,
37
+ rerankFn: opts.rerankFn,
38
+ });
39
+ if (selectedIndex >= results.length) {
40
+ selectedIndex = Math.max(0, results.length - 1);
41
+ }
42
+ }
43
+ catch {
44
+ results = [];
45
+ }
46
+ finally {
47
+ searching = false;
48
+ render();
49
+ }
50
+ };
51
+ const scheduleSearch = () => {
52
+ if (debounceTimer)
53
+ clearTimeout(debounceTimer);
54
+ debounceTimer = setTimeout(() => {
55
+ performSearch();
56
+ }, opts.debounceMs ?? 300);
57
+ };
58
+ const render = () => {
59
+ const rows = process.stdout.rows || 24;
60
+ const cols = process.stdout.columns || 80;
61
+ let buf = '';
62
+ buf += '\x1b[?25l'; // hide cursor
63
+ buf += '\x1b[H\x1b[J'; // clear screen from cursor down
64
+ // Header
65
+ const searchStatus = searching ? ' [searching...]' : '';
66
+ const headerStr = ` mdss interactive search | Query: ${query}${searchStatus}`;
67
+ buf += `\x1b[7m${headerStr.padEnd(cols).slice(0, cols)}\x1b[0m\n`;
68
+ // Calculate layout heights
69
+ const listHeight = Math.max(4, Math.floor((rows - 4) * 0.4));
70
+ const previewHeight = Math.max(4, rows - 4 - listHeight);
71
+ // Render list
72
+ buf += `\x1b[1m--- Results (${results.length}) ---\x1b[0m\n`;
73
+ const listSlice = results.slice(0, listHeight);
74
+ for (let i = 0; i < listHeight; i++) {
75
+ if (i < listSlice.length) {
76
+ const item = listSlice[i];
77
+ const isSelected = i === selectedIndex;
78
+ const prefix = isSelected ? '> ' : ' ';
79
+ const line = `${prefix}${i + 1}. [${item.score.toFixed(3)}] ${item.file} › ${item.heading || item.title}`;
80
+ const clippedLine = line.slice(0, cols);
81
+ if (isSelected) {
82
+ buf += `\x1b[7m${clippedLine.padEnd(cols)}\x1b[0m\n`;
83
+ }
84
+ else {
85
+ buf += `${clippedLine}\n`;
86
+ }
87
+ }
88
+ else {
89
+ buf += '~ \n';
90
+ }
91
+ }
92
+ // Render Preview
93
+ buf += `\x1b[1m--- Passage Preview ---\x1b[0m\n`;
94
+ const selectedHit = results[selectedIndex];
95
+ if (selectedHit) {
96
+ const textLines = selectedHit.snippet.split('\n');
97
+ for (let i = 0; i < previewHeight; i++) {
98
+ if (i < textLines.length) {
99
+ buf += ` ${textLines[i].slice(0, cols - 3)}\n`;
100
+ }
101
+ else {
102
+ buf += '\n';
103
+ }
104
+ }
105
+ }
106
+ else {
107
+ buf += ' (no passage selected)\n';
108
+ for (let i = 1; i < previewHeight; i++)
109
+ buf += '\n';
110
+ }
111
+ // Footer
112
+ const footerStr = ' [Up/Down/j/k]: Navigate | [Enter]: Open in Editor | [Esc/q/Ctrl+C]: Quit';
113
+ buf += `\x1b[7m${footerStr.padEnd(cols).slice(0, cols)}\x1b[0m`;
114
+ process.stdout.write(buf);
115
+ };
116
+ return new Promise((resolve) => {
117
+ readline.emitKeypressEvents(process.stdin);
118
+ if (process.stdin.isRaw) {
119
+ process.stdin.setRawMode(true);
120
+ }
121
+ process.stdin.resume();
122
+ const onResize = () => {
123
+ render();
124
+ };
125
+ process.stdout.on('resize', onResize);
126
+ const cleanupTui = () => {
127
+ process.stdout.removeListener('resize', onResize);
128
+ if (process.stdin.isRaw) {
129
+ process.stdin.setRawMode(false);
130
+ }
131
+ process.stdin.pause();
132
+ process.stdout.write('\x1b[?25h\x1b[2J\x1b[H'); // show cursor and clear
133
+ };
134
+ const onKeypress = (_str, key) => {
135
+ if (key.ctrl && key.name === 'c') {
136
+ cleanupTui();
137
+ process.removeListener('keypress', onKeypress);
138
+ resolve(null);
139
+ return;
140
+ }
141
+ if (key.name === 'escape' || (key.name === 'q' && query === '')) {
142
+ cleanupTui();
143
+ process.removeListener('keypress', onKeypress);
144
+ resolve(null);
145
+ return;
146
+ }
147
+ if (key.name === 'up' || (key.name === 'k' && key.ctrl)) {
148
+ if (selectedIndex > 0) {
149
+ selectedIndex--;
150
+ render();
151
+ }
152
+ return;
153
+ }
154
+ if (key.name === 'down' || (key.name === 'j' && key.ctrl)) {
155
+ if (selectedIndex < results.length - 1) {
156
+ selectedIndex++;
157
+ render();
158
+ }
159
+ return;
160
+ }
161
+ if (key.name === 'return') {
162
+ const hit = results[selectedIndex];
163
+ cleanupTui();
164
+ process.removeListener('keypress', onKeypress);
165
+ if (hit) {
166
+ const editor = process.env.EDITOR || process.env.VISUAL || 'code';
167
+ const filePath = path.resolve(db, hit.file);
168
+ try {
169
+ spawn(editor, [filePath], { stdio: 'inherit', detached: true });
170
+ }
171
+ catch {
172
+ /* editor launch failed */
173
+ }
174
+ }
175
+ resolve(hit || null);
176
+ return;
177
+ }
178
+ if (key.name === 'backspace') {
179
+ if (query.length > 0) {
180
+ query = query.slice(0, -1);
181
+ scheduleSearch();
182
+ render();
183
+ }
184
+ return;
185
+ }
186
+ if (_str && _str.length === 1 && _str.charCodeAt(0) >= 32) {
187
+ query += _str;
188
+ scheduleSearch();
189
+ render();
190
+ }
191
+ };
192
+ process.stdin.on('keypress', onKeypress);
193
+ // Initial search and render
194
+ performSearch();
195
+ });
196
+ }
@@ -0,0 +1,47 @@
1
+ /**
2
+ * Wikilink and backlink relationship extraction and resolution (issue #61).
3
+ * Supports Obsidian wikilinks [[note]], [[note#heading|alias]], and relative Markdown links.
4
+ */
5
+ import { DocumentMetadata } from './frontmatter.js';
6
+ export interface RawLink {
7
+ type: 'wikilink' | 'markdown';
8
+ target: string;
9
+ anchor?: string;
10
+ label?: string;
11
+ raw: string;
12
+ line: number;
13
+ }
14
+ export interface ResolvedLink {
15
+ raw: string;
16
+ target: string;
17
+ resolvedFile?: string;
18
+ status: 'resolved' | 'broken' | 'ambiguous';
19
+ line: number;
20
+ }
21
+ export interface LinkDoc {
22
+ file: string;
23
+ title?: string;
24
+ meta?: DocumentMetadata;
25
+ text?: string;
26
+ }
27
+ export declare function extractLinks(text?: string): RawLink[];
28
+ export declare function resolveLinks(rawLinks: RawLink[], currentFile: string, docs: LinkDoc[]): ResolvedLink[];
29
+ export interface GraphEdge {
30
+ file: string;
31
+ raw: string;
32
+ line: number;
33
+ }
34
+ export interface RelationshipGraph {
35
+ outgoing: Map<string, GraphEdge[]>;
36
+ backlinks: Map<string, GraphEdge[]>;
37
+ }
38
+ export declare function buildRelationshipGraph(docs: LinkDoc[]): RelationshipGraph;
39
+ export interface RelatedNote {
40
+ file: string;
41
+ distance: number;
42
+ direction: string;
43
+ }
44
+ export declare function getRelatedNotes(graph: RelationshipGraph, targetFile: string, opts?: {
45
+ direction?: 'both' | 'outgoing' | 'backlinks';
46
+ depth?: number;
47
+ }): RelatedNote[];