sensemaking 0.26.0 → 0.27.0

package/dist/cjs/commands/peek.js

@@ -232,7 +232,7 @@ function resolveNote(paths, arg) {
     if (matches.length > 1) throw new _errorsts.SenseError('NOTE_AMBIGUOUS', '"'.concat(arg, '" is ambiguous: ').concat(matches.join(', ')));
     throw new _errorsts.SenseError('NOTE_NOT_FOUND', 'no note matches "'.concat(arg, '"'));
 }
-var PEEK_LIST_LIMIT = 20;
+var PEEK_COUNT_LIMIT = 20;
 function peek(store, cfg, pathArg) {
     var overrides = arguments.length > 3 && arguments[3] !== void 0 ? arguments[3] : {};
     return (0, _serialqueryts.serialQuery)(store, function() {
@@ -241,12 +241,25 @@ function peek(store, cfg, pathArg) {
 }
 function peekIndexed(store, cfg, pathArg, overrides) {
     return _async_to_generator(function() {
+        var _overrides_sectionCountLimit, _overrides_linkCountLimit, _i, _iter, name, value, sectionCountLimit, linkCountLimit;
         return _ts_generator(this, function(_state) {
+            for(_i = 0, _iter = [
+                'sectionCountLimit',
+                'linkCountLimit'
+            ]; _i < _iter.length; _i++){
+                name = _iter[_i];
+                value = overrides[name];
+                if (value !== undefined && (!Number.isSafeInteger(value) || value <= 0)) {
+                    throw new _errorsts.SenseError('SEARCH_OPTION_INVALID', 'peek option "'.concat(name, '" must be a positive safe integer, got ').concat(String(value)));
+                }
+            }
+            sectionCountLimit = (_overrides_sectionCountLimit = overrides.sectionCountLimit) !== null && _overrides_sectionCountLimit !== void 0 ? _overrides_sectionCountLimit : PEEK_COUNT_LIMIT;
+            linkCountLimit = (_overrides_linkCountLimit = overrides.linkCountLimit) !== null && _overrides_linkCountLimit !== void 0 ? _overrides_linkCountLimit : PEEK_COUNT_LIMIT;
             return [
                 2,
                 store.transaction(function() {
                     return _async_to_generator(function() {
-                        var _row__parse_error, _row__size, _this, pathsStmt, paths, allowed, path, excludedPath, rowStmt, row, parseError, frontmatter, _iteratorNormalCompletion, _didIteratorError, _iteratorError, _iterator, _step, _step_value, key, value, sectionsTotal, sections, outbound, backlinks, unresolved, backlinksTotal, out, body, byteTokens, tokens;
+                        var _row__parse_error, _row__size, _this, pathsStmt, paths, allowed, path, excludedPath, rowStmt, row, parseError, frontmatter, _iteratorNormalCompletion, _didIteratorError, _iteratorError, _iterator, _step, _step_value, key, value, sectionsTotal, sections, outbound, backlinks, unresolved, outboundTotal, backlinksTotal, unresolvedTotal, body, byteTokens, tokens;
                         return _ts_generator(this, function(_state) {
                             switch(_state.label){
                                 case 0:
@@ -354,7 +367,7 @@ function peekIndexed(store, cfg, pathArg, overrides) {
                                 case 9:
                                     return [
                                         4,
-                                        _state.sent().all(path, PEEK_LIST_LIMIT)
+                                        _state.sent().all(path, sectionCountLimit)
                                     ];
                                 case 10:
                                     sections = _state.sent();
@@ -363,10 +376,12 @@ function peekIndexed(store, cfg, pathArg, overrides) {
                                     outbound = [];
                                     backlinks = [];
                                     unresolved = [];
+                                    outboundTotal = 0;
                                     backlinksTotal = 0;
+                                    unresolvedTotal = 0;
                                     if (!(0, _indexts1.featureEnabled)(cfg, 'links')) return [
                                         3,
-                                        19
+                                        25
                                     ];
                                     return [
                                         4,
@@ -376,61 +391,89 @@ function peekIndexed(store, cfg, pathArg, overrides) {
                                     _state.sent();
                                     return [
                                         4,
-                                        store.prepare('SELECT target, dst FROM links WHERE src = ? AND (dst IS NULL OR (dst != src AND dst IN (SELECT "path" FROM _peek_scope))) ORDER BY target')
+                                        store.prepare('SELECT COUNT(DISTINCT dst) AS n FROM links WHERE src = ? AND dst != src AND dst IN (SELECT "path" FROM _peek_scope)')
                                     ];
                                 case 13:
                                     return [
                                         4,
-                                        _state.sent().all(path)
+                                        _state.sent().get(path)
                                     ];
                                 case 14:
-                                    out = _state.sent();
-                                    outbound = _to_consumable_array(new Set(out.filter(function(l) {
-                                        return l.dst !== null;
-                                    }).map(function(l) {
-                                        return l.dst;
-                                    })));
-                                    unresolved = out.filter(function(l) {
-                                        return l.dst === null;
-                                    }).map(function(l) {
-                                        return l.target;
+                                    outboundTotal = _state.sent().n;
+                                    return [
+                                        4,
+                                        store.prepare('SELECT dst FROM links WHERE src = ? AND dst != src AND dst IN (SELECT "path" FROM _peek_scope) GROUP BY dst ORDER BY MIN(target) LIMIT ?')
+                                    ];
+                                case 15:
+                                    return [
+                                        4,
+                                        _state.sent().all(path, linkCountLimit)
+                                    ];
+                                case 16:
+                                    // The first written target determines each resolved destination's position.
+                                    outbound = _state.sent().map(function(r) {
+                                        return r.dst;
+                                    });
+                                    return [
+                                        4,
+                                        store.prepare('SELECT COUNT(*) AS n FROM links WHERE src = ? AND dst IS NULL')
+                                    ];
+                                case 17:
+                                    return [
+                                        4,
+                                        _state.sent().get(path)
+                                    ];
+                                case 18:
+                                    unresolvedTotal = _state.sent().n;
+                                    return [
+                                        4,
+                                        store.prepare('SELECT target FROM links WHERE src = ? AND dst IS NULL ORDER BY target LIMIT ?')
+                                    ];
+                                case 19:
+                                    return [
+                                        4,
+                                        _state.sent().all(path, linkCountLimit)
+                                    ];
+                                case 20:
+                                    unresolved = _state.sent().map(function(r) {
+                                        return r.target;
                                     });
                                     return [
                                         4,
                                         store.prepare('SELECT COUNT(DISTINCT src) AS n FROM links WHERE dst = ? AND src != dst AND src IN (SELECT "path" FROM _peek_scope)')
                                     ];
-                                case 15:
+                                case 21:
                                     return [
                                         4,
                                         _state.sent().get(path)
                                     ];
-                                case 16:
+                                case 22:
                                     backlinksTotal = _state.sent().n;
                                     return [
                                         4,
                                         store.prepare('SELECT DISTINCT src FROM links WHERE dst = ? AND src != dst AND src IN (SELECT "path" FROM _peek_scope) ORDER BY src LIMIT ?')
                                     ];
-                                case 17:
+                                case 23:
                                     return [
                                         4,
-                                        _state.sent().all(path, PEEK_LIST_LIMIT)
+                                        _state.sent().all(path, linkCountLimit)
                                     ];
-                                case 18:
+                                case 24:
                                     backlinks = _state.sent().map(function(r) {
                                         return r.src;
                                     });
-                                    _state.label = 19;
-                                case 19:
+                                    _state.label = 25;
+                                case 25:
                                     return [
                                         4,
                                         store.prepare('SELECT text FROM content WHERE "path" = ?')
                                     ];
-                                case 20:
+                                case 26:
                                     return [
                                         4,
                                         _state.sent().get(path)
                                     ];
-                                case 21:
+                                case 27:
                                     body = (_this = _state.sent()) === null || _this === void 0 ? void 0 : _this.text;
                                     byteTokens = Math.ceil(((_row__size = row._size) !== null && _row__size !== void 0 ? _row__size : 0) / 4);
                                     tokens = body !== undefined ? Math.max(Math.ceil((0, _indexts.estimateTokens)(body)), byteTokens) : byteTokens;
@@ -442,13 +485,13 @@ function peekIndexed(store, cfg, pathArg, overrides) {
                                             frontmatter: frontmatter,
                                             parseError: parseError,
                                             sections: sections,
-                                            outbound: outbound.slice(0, PEEK_LIST_LIMIT),
+                                            outbound: outbound,
                                             backlinks: backlinks,
-                                            unresolved: unresolved.slice(0, PEEK_LIST_LIMIT),
+                                            unresolved: unresolved,
                                             sectionsTotal: sectionsTotal,
-                                            outboundTotal: outbound.length,
+                                            outboundTotal: outboundTotal,
                                             backlinksTotal: backlinksTotal,
-                                            unresolvedTotal: unresolved.length,
+                                            unresolvedTotal: unresolvedTotal,
                                             off: [
                                                 'sections',
                                                 'links'

package/dist/cjs/commands/peek.js.map

@@ -1 +1 @@
-{"version":3,"sources":["/Users/kevin/Dev/OpenSource/ai/sensemaking/src/commands/peek.ts"],"sourcesContent":["import posix from 'node:path/posix';\nimport { estimateTokens } from '../chunk/index.ts';\nimport type { FeatureName, ResolvedConfig, SearchOverrides } from '../config/index.ts';\nimport { featureEnabled } from '../config/index.ts';\nimport { SenseError } from '../errors.ts';\nimport { serialQuery } from '../lib/serial-query.ts';\nimport type { Row } from '../output/output.ts';\nimport type { Store } from '../store/types.ts';\nimport { INTERNAL_COLUMNS, materializeScope, scopedPaths } from './scope.ts';\nimport { assertQuerySnapshot } from './snapshot.ts';\n\n// Note resolution shared by peek and path: an exact path, or a unique basename (case\n// insensitive, .md stripped).\nexport function resolveNote(paths: string[], arg: string): string {\n  const exact = paths.find((p) => p === arg);\n  if (exact) return exact;\n  const base = posix.basename(arg).replace(/\\.md$/i, '').toLowerCase();\n  const matches = paths.filter((p) => posix.basename(p).replace(/\\.md$/i, '').toLowerCase() === base);\n  if (matches.length === 1) return matches[0];\n  if (matches.length > 1) throw new SenseError('NOTE_AMBIGUOUS', `\"${arg}\" is ambiguous: ${matches.join(', ')}`);\n  throw new SenseError('NOTE_NOT_FOUND', `no note matches \"${arg}\"`);\n}\n\n/** Structured, bounded metadata returned by the root {@link peek} API. */\nexport interface Peek {\n  path: string;\n  tokens: number;\n  frontmatter: Row;\n  /** Set when frontmatter parsing failed, distinguishing that case from an empty block. */\n  parseError: string | null;\n  sections: PeekSection[];\n  outbound: string[];\n  backlinks: string[];\n  unresolved: string[];\n  /** Totals before each bounded list is truncated. */\n  sectionsTotal: number;\n  outboundTotal: number;\n  backlinksTotal: number;\n  unresolvedTotal: number;\n  /** Disabled features whose result blocks are omitted rather than returned empty. */\n  off: FeatureName[];\n}\n\nexport interface PeekSection {\n  level: number;\n  heading: string;\n  start_line: number;\n  end_line: number;\n  tokens: number;\n}\n\nconst PEEK_LIST_LIMIT = 20;\n\n/**\n * Returns indexed metadata for a note in scope. Exact excluded paths fail before scoped basename\n * resolution; resolved neighbors stay in scope, while unresolved written targets remain visible.\n */\nexport function peek(store: Store, cfg: ResolvedConfig, pathArg: string, overrides: SearchOverrides = {}): Promise<Peek> {\n  return serialQuery(store, () => peekIndexed(store, cfg, pathArg, overrides));\n}\n\nasync function peekIndexed(store: Store, cfg: ResolvedConfig, pathArg: string, overrides: SearchOverrides): Promise<Peek> {\n  return store.transaction(async () => {\n    await assertQuerySnapshot(store, cfg);\n    const pathsStmt = await store.prepare('SELECT \"path\" FROM frontmatter');\n    const paths = ((await pathsStmt.all()) as Array<{ path: string }>).map((r) => r.path);\n    const allowed = await scopedPaths(store, cfg, overrides);\n    if (paths.includes(pathArg) && !allowed.has(pathArg)) {\n      throw new SenseError('NOTE_NOT_FOUND', `note \"${pathArg}\" exists but is outside the current scope; change the preset, include/exclude patterns, or where condition`);\n    }\n    let path: string;\n    try {\n      path = resolveNote([...allowed], pathArg);\n    } catch (err) {\n      if (err instanceof SenseError && err.code === 'NOTE_NOT_FOUND') {\n        let excludedPath: string;\n        try {\n          excludedPath = resolveNote(paths, pathArg);\n        } catch (unscopedErr) {\n          if (unscopedErr instanceof SenseError && unscopedErr.code === 'NOTE_AMBIGUOUS') {\n            throw new SenseError('NOTE_NOT_FOUND', `no note in the current scope matches \"${pathArg}\"; indexed matches exist outside the scope, so change the preset, include/exclude patterns, or where condition`);\n          }\n          throw err;\n        }\n        throw new SenseError('NOTE_NOT_FOUND', `note \"${excludedPath}\" exists but is outside the current scope; change the preset, include/exclude patterns, or where condition`);\n      }\n      throw err;\n    }\n\n    const rowStmt = await store.prepare('SELECT * FROM frontmatter WHERE \"path\" = ?');\n    const row = (await rowStmt.get(path)) as Row;\n    const parseError = (row._parse_error as string | null) ?? null;\n    const frontmatter: Row = {};\n    for (const [key, value] of Object.entries(row)) {\n      if (!INTERNAL_COLUMNS.has(key) && value !== null) frontmatter[key] = value;\n    }\n\n    let sectionsTotal = 0;\n    let sections: PeekSection[] = [];\n    if (featureEnabled(cfg, 'sections')) {\n      sectionsTotal = ((await (await store.prepare('SELECT COUNT(*) AS n FROM sections WHERE \"path\" = ?')).get(path)) as { n: number }).n;\n      sections = (await (await store.prepare('SELECT level, heading, start_line, end_line, tokens FROM sections WHERE \"path\" = ? ORDER BY idx LIMIT ?')).all(path, PEEK_LIST_LIMIT)) as PeekSection[];\n    }\n\n    let outbound: string[] = [];\n    let backlinks: string[] = [];\n    let unresolved: string[] = [];\n    let backlinksTotal = 0;\n    if (featureEnabled(cfg, 'links')) {\n      await materializeScope(store, '_peek_scope', allowed);\n      const out = (await (await store.prepare('SELECT target, dst FROM links WHERE src = ? AND (dst IS NULL OR (dst != src AND dst IN (SELECT \"path\" FROM _peek_scope))) ORDER BY target')).all(path)) as Array<{ target: string; dst: string | null }>;\n      outbound = [...new Set(out.filter((l): l is { target: string; dst: string } => l.dst !== null).map((l) => l.dst))];\n      unresolved = out.filter((l) => l.dst === null).map((l) => l.target);\n      backlinksTotal = ((await (await store.prepare('SELECT COUNT(DISTINCT src) AS n FROM links WHERE dst = ? AND src != dst AND src IN (SELECT \"path\" FROM _peek_scope)')).get(path)) as { n: number }).n;\n      backlinks = ((await (await store.prepare('SELECT DISTINCT src FROM links WHERE dst = ? AND src != dst AND src IN (SELECT \"path\" FROM _peek_scope) ORDER BY src LIMIT ?')).all(path, PEEK_LIST_LIMIT)) as Array<{ src: string }>).map((r) => r.src);\n    }\n\n    // content.text is the stripped body already computed at reconcile time (no extra file read),\n    // floored by the byte/4 estimate so stripped-away syntax and frontmatter can't vanish from the price.\n    const body = ((await (await store.prepare('SELECT text FROM content WHERE \"path\" = ?')).get(path)) as { text: string } | undefined)?.text;\n    const byteTokens = Math.ceil(((row._size as number) ?? 0) / 4);\n    const tokens = body !== undefined ? Math.max(Math.ceil(estimateTokens(body)), byteTokens) : byteTokens;\n\n    return {\n      path,\n      tokens,\n      frontmatter,\n      parseError,\n      sections,\n      outbound: outbound.slice(0, PEEK_LIST_LIMIT),\n      backlinks,\n      unresolved: unresolved.slice(0, PEEK_LIST_LIMIT),\n      sectionsTotal,\n      outboundTotal: outbound.length,\n      backlinksTotal,\n      unresolvedTotal: unresolved.length,\n      off: (['sections', 'links'] as FeatureName[]).filter((name) => !featureEnabled(cfg, name)),\n    };\n  });\n}\n"],"names":["peek","resolveNote","paths","arg","exact","find","p","base","posix","basename","replace","toLowerCase","matches","filter","length","SenseError","join","PEEK_LIST_LIMIT","store","cfg","pathArg","overrides","serialQuery","peekIndexed","transaction","row","pathsStmt","allowed","path","excludedPath","rowStmt","parseError","frontmatter","key","value","sectionsTotal","sections","outbound","backlinks","unresolved","backlinksTotal","out","body","byteTokens","tokens","assertQuerySnapshot","prepare","all","map","r","scopedPaths","includes","has","err","code","unscopedErr","get","_parse_error","Object","entries","INTERNAL_COLUMNS","featureEnabled","n","materializeScope","Set","l","dst","target","src","text","Math","ceil","_size","undefined","max","estimateTokens","slice","outboundTotal","unresolvedTotal","off","name"],"mappings":"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"}
+{"version":3,"sources":["/Users/kevin/Dev/OpenSource/ai/sensemaking/src/commands/peek.ts"],"sourcesContent":["import posix from 'node:path/posix';\nimport { estimateTokens } from '../chunk/index.ts';\nimport type { FeatureName, ResolvedConfig, SearchOverrides } from '../config/index.ts';\nimport { featureEnabled } from '../config/index.ts';\nimport { SenseError } from '../errors.ts';\nimport { serialQuery } from '../lib/serial-query.ts';\nimport type { Row } from '../output/output.ts';\nimport type { Store } from '../store/types.ts';\nimport { INTERNAL_COLUMNS, materializeScope, scopedPaths } from './scope.ts';\nimport { assertQuerySnapshot } from './snapshot.ts';\n\n// Note resolution shared by peek and path: an exact path, or a unique basename (case\n// insensitive, .md stripped).\nexport function resolveNote(paths: string[], arg: string): string {\n  const exact = paths.find((p) => p === arg);\n  if (exact) return exact;\n  const base = posix.basename(arg).replace(/\\.md$/i, '').toLowerCase();\n  const matches = paths.filter((p) => posix.basename(p).replace(/\\.md$/i, '').toLowerCase() === base);\n  if (matches.length === 1) return matches[0];\n  if (matches.length > 1) throw new SenseError('NOTE_AMBIGUOUS', `\"${arg}\" is ambiguous: ${matches.join(', ')}`);\n  throw new SenseError('NOTE_NOT_FOUND', `no note matches \"${arg}\"`);\n}\n\n/** Structured, bounded metadata returned by the root {@link peek} API. */\nexport interface Peek {\n  path: string;\n  tokens: number;\n  frontmatter: Row;\n  /** Set when frontmatter parsing failed, distinguishing that case from an empty block. */\n  parseError: string | null;\n  sections: PeekSection[];\n  outbound: string[];\n  backlinks: string[];\n  unresolved: string[];\n  /** Totals before each bounded list is truncated. */\n  sectionsTotal: number;\n  outboundTotal: number;\n  backlinksTotal: number;\n  unresolvedTotal: number;\n  /** Disabled features whose result blocks are omitted rather than returned empty. */\n  off: FeatureName[];\n}\n\n/** A section description, with an inclusive source line range and token estimate, not section prose. */\nexport interface PeekSection {\n  level: number;\n  heading: string;\n  start_line: number;\n  end_line: number;\n  tokens: number;\n}\n\n/** Options for the root {@link peek} API. */\nexport interface PeekOptions extends SearchOverrides {\n  /** Maximum section descriptions. Defaults to 20; must be a positive safe integer. */\n  sectionCountLimit?: number;\n  /** Maximum entries in each link group independently. Defaults to 20; must be a positive safe integer. */\n  linkCountLimit?: number;\n}\n\nconst PEEK_COUNT_LIMIT = 20;\n\n/**\n * Returns indexed metadata for a note in scope. Exact excluded paths fail before scoped basename\n * resolution; resolved neighbors stay in scope, while unresolved written targets remain visible.\n */\nexport function peek(store: Store, cfg: ResolvedConfig, pathArg: string, overrides: PeekOptions = {}): Promise<Peek> {\n  return serialQuery(store, () => peekIndexed(store, cfg, pathArg, overrides));\n}\n\nasync function peekIndexed(store: Store, cfg: ResolvedConfig, pathArg: string, overrides: PeekOptions): Promise<Peek> {\n  for (const name of ['sectionCountLimit', 'linkCountLimit'] as const) {\n    const value = overrides[name];\n    if (value !== undefined && (!Number.isSafeInteger(value) || value <= 0)) {\n      throw new SenseError('SEARCH_OPTION_INVALID', `peek option \"${name}\" must be a positive safe integer, got ${String(value)}`);\n    }\n  }\n  const sectionCountLimit = overrides.sectionCountLimit ?? PEEK_COUNT_LIMIT;\n  const linkCountLimit = overrides.linkCountLimit ?? PEEK_COUNT_LIMIT;\n  return store.transaction(async () => {\n    await assertQuerySnapshot(store, cfg);\n    const pathsStmt = await store.prepare('SELECT \"path\" FROM frontmatter');\n    const paths = ((await pathsStmt.all()) as Array<{ path: string }>).map((r) => r.path);\n    const allowed = await scopedPaths(store, cfg, overrides);\n    if (paths.includes(pathArg) && !allowed.has(pathArg)) {\n      throw new SenseError('NOTE_NOT_FOUND', `note \"${pathArg}\" exists but is outside the current scope; change the preset, include/exclude patterns, or where condition`);\n    }\n    let path: string;\n    try {\n      path = resolveNote([...allowed], pathArg);\n    } catch (err) {\n      if (err instanceof SenseError && err.code === 'NOTE_NOT_FOUND') {\n        let excludedPath: string;\n        try {\n          excludedPath = resolveNote(paths, pathArg);\n        } catch (unscopedErr) {\n          if (unscopedErr instanceof SenseError && unscopedErr.code === 'NOTE_AMBIGUOUS') {\n            throw new SenseError('NOTE_NOT_FOUND', `no note in the current scope matches \"${pathArg}\"; indexed matches exist outside the scope, so change the preset, include/exclude patterns, or where condition`);\n          }\n          throw err;\n        }\n        throw new SenseError('NOTE_NOT_FOUND', `note \"${excludedPath}\" exists but is outside the current scope; change the preset, include/exclude patterns, or where condition`);\n      }\n      throw err;\n    }\n\n    const rowStmt = await store.prepare('SELECT * FROM frontmatter WHERE \"path\" = ?');\n    const row = (await rowStmt.get(path)) as Row;\n    const parseError = (row._parse_error as string | null) ?? null;\n    const frontmatter: Row = {};\n    for (const [key, value] of Object.entries(row)) {\n      if (!INTERNAL_COLUMNS.has(key) && value !== null) frontmatter[key] = value;\n    }\n\n    let sectionsTotal = 0;\n    let sections: PeekSection[] = [];\n    if (featureEnabled(cfg, 'sections')) {\n      sectionsTotal = ((await (await store.prepare('SELECT COUNT(*) AS n FROM sections WHERE \"path\" = ?')).get(path)) as { n: number }).n;\n      sections = (await (await store.prepare('SELECT level, heading, start_line, end_line, tokens FROM sections WHERE \"path\" = ? ORDER BY idx LIMIT ?')).all(path, sectionCountLimit)) as PeekSection[];\n    }\n\n    let outbound: string[] = [];\n    let backlinks: string[] = [];\n    let unresolved: string[] = [];\n    let outboundTotal = 0;\n    let backlinksTotal = 0;\n    let unresolvedTotal = 0;\n    if (featureEnabled(cfg, 'links')) {\n      await materializeScope(store, '_peek_scope', allowed);\n      outboundTotal = ((await (await store.prepare('SELECT COUNT(DISTINCT dst) AS n FROM links WHERE src = ? AND dst != src AND dst IN (SELECT \"path\" FROM _peek_scope)')).get(path)) as { n: number }).n;\n      // The first written target determines each resolved destination's position.\n      outbound = ((await (await store.prepare('SELECT dst FROM links WHERE src = ? AND dst != src AND dst IN (SELECT \"path\" FROM _peek_scope) GROUP BY dst ORDER BY MIN(target) LIMIT ?')).all(path, linkCountLimit)) as Array<{ dst: string }>).map((r) => r.dst);\n      unresolvedTotal = ((await (await store.prepare('SELECT COUNT(*) AS n FROM links WHERE src = ? AND dst IS NULL')).get(path)) as { n: number }).n;\n      unresolved = ((await (await store.prepare('SELECT target FROM links WHERE src = ? AND dst IS NULL ORDER BY target LIMIT ?')).all(path, linkCountLimit)) as Array<{ target: string }>).map((r) => r.target);\n      backlinksTotal = ((await (await store.prepare('SELECT COUNT(DISTINCT src) AS n FROM links WHERE dst = ? AND src != dst AND src IN (SELECT \"path\" FROM _peek_scope)')).get(path)) as { n: number }).n;\n      backlinks = ((await (await store.prepare('SELECT DISTINCT src FROM links WHERE dst = ? AND src != dst AND src IN (SELECT \"path\" FROM _peek_scope) ORDER BY src LIMIT ?')).all(path, linkCountLimit)) as Array<{ src: string }>).map((r) => r.src);\n    }\n\n    // content.text is the stripped body already computed at reconcile time (no extra file read),\n    // floored by the byte/4 estimate so stripped-away syntax and frontmatter can't vanish from the price.\n    const body = ((await (await store.prepare('SELECT text FROM content WHERE \"path\" = ?')).get(path)) as { text: string } | undefined)?.text;\n    const byteTokens = Math.ceil(((row._size as number) ?? 0) / 4);\n    const tokens = body !== undefined ? Math.max(Math.ceil(estimateTokens(body)), byteTokens) : byteTokens;\n\n    return {\n      path,\n      tokens,\n      frontmatter,\n      parseError,\n      sections,\n      outbound,\n      backlinks,\n      unresolved,\n      sectionsTotal,\n      outboundTotal,\n      backlinksTotal,\n      unresolvedTotal,\n      off: (['sections', 'links'] as FeatureName[]).filter((name) => !featureEnabled(cfg, name)),\n    };\n  });\n}\n"],"names":["peek","resolveNote","paths","arg","exact","find","p","base","posix","basename","replace","toLowerCase","matches","filter","length","SenseError","join","PEEK_COUNT_LIMIT","store","cfg","pathArg","overrides","serialQuery","peekIndexed","name","value","sectionCountLimit","linkCountLimit","undefined","Number","isSafeInteger","String","transaction","row","pathsStmt","allowed","path","excludedPath","rowStmt","parseError","frontmatter","key","sectionsTotal","sections","outbound","backlinks","unresolved","outboundTotal","backlinksTotal","unresolvedTotal","body","byteTokens","tokens","assertQuerySnapshot","prepare","all","map","r","scopedPaths","includes","has","err","code","unscopedErr","get","_parse_error","Object","entries","INTERNAL_COLUMNS","featureEnabled","n","materializeScope","dst","target","src","text","Math","ceil","_size","max","estimateTokens","off"],"mappings":"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"}

package/dist/cjs/commands/search.d.cts

@@ -1,7 +1,7 @@
 import type { ResolvedConfig } from '../config/index.js';
 import type { Store } from '../store/types.js';
-import type { SearchResultVia } from './signals.js';
-export type { SearchResultVia } from './signals.js';
+import type { SearchResultVia, SearchSignalContribution } from './signals.js';
+export type { SearchResultVia, SearchSignalContribution } from './signals.js';
 export declare const SNIPPET_CHAR_LIMIT_DEFAULT = 80;
 export declare const SNIPPET_COUNT_LIMIT_DEFAULT = 1;
 export declare function computeSnippets(text: string, terms: string[], charLimit: number, countLimit: number): {
@@ -12,6 +12,8 @@ export declare function lineNumberAt(text: string, offset: number): number;
 /** Options for the root {@link search} API. */
 export interface SearchOptions {
     k?: number;
+    /** Collects ranking contributions for returned candidates; omitted or false preserves ordinary output. */
+    explain?: boolean;
     where?: string;
     preset?: string;
     include?: string[];
@@ -31,6 +33,8 @@ export type SearchResult = {
     score: number;
     lines: string | null;
     similarity?: number | null;
+    /** Present only with explain: true, in words/links/vectors order; contributions can differ from via labels. */
+    explanation?: SearchSignalContribution[];
 };
 export interface SearchHydrationRow {
     path: string;

package/dist/cjs/commands/search.d.ts

@@ -1,7 +1,7 @@
 import type { ResolvedConfig } from '../config/index.js';
 import type { Store } from '../store/types.js';
-import type { SearchResultVia } from './signals.js';
-export type { SearchResultVia } from './signals.js';
+import type { SearchResultVia, SearchSignalContribution } from './signals.js';
+export type { SearchResultVia, SearchSignalContribution } from './signals.js';
 export declare const SNIPPET_CHAR_LIMIT_DEFAULT = 80;
 export declare const SNIPPET_COUNT_LIMIT_DEFAULT = 1;
 export declare function computeSnippets(text: string, terms: string[], charLimit: number, countLimit: number): {
@@ -12,6 +12,8 @@ export declare function lineNumberAt(text: string, offset: number): number;
 /** Options for the root {@link search} API. */
 export interface SearchOptions {
     k?: number;
+    /** Collects ranking contributions for returned candidates; omitted or false preserves ordinary output. */
+    explain?: boolean;
     where?: string;
     preset?: string;
     include?: string[];
@@ -31,6 +33,8 @@ export type SearchResult = {
     score: number;
     lines: string | null;
     similarity?: number | null;
+    /** Present only with explain: true, in words/links/vectors order; contributions can differ from via labels. */
+    explanation?: SearchSignalContribution[];
 };
 export interface SearchHydrationRow {
     path: string;

package/dist/cjs/commands/search.js

@@ -631,6 +631,9 @@ function lineRangeFor(store, path, line) {
     })();
 }
 function validateSearchOptions(opts) {
+    if (opts.explain !== undefined && typeof opts.explain !== 'boolean') {
+        throw new _errorsts.SenseError('SEARCH_OPTION_INVALID', 'search option "explain" must be a boolean, got '.concat(String(opts.explain)));
+    }
     for(var _i = 0, _iter = [
         [
             'k',
@@ -966,7 +969,7 @@ function searchIndexed(store, cfg, terms, opts) {
 }
 function searchSnapshot(store, cfg, terms, opts, prepared, preparedSignature) {
     return _async_to_generator(function() {
-        var _ref, signature, effective, allPaths, scopePaths, allowedPaths, semanticEligible, k, signals, fetch, scopeActive, semanticEnabled, scope, whereJoin, whereCond, scopeCond, candidates, matchRows, hasEmptyPhrase, hasBareSyntaxOnly, syntaxError, err1, matchedPaths, chunkLines, chunkSimilarity, ref, where, similarityCol, selectStmt, rows, _iteratorNormalCompletion, _didIteratorError, _iteratorError, _iterator, _step, row;
+        var _ref, signature, effective, allPaths, scopePaths, allowedPaths, semanticEligible, k, signals, fetch, scopeActive, semanticEnabled, scope, whereJoin, whereCond, scopeCond, candidates, matchRows, hasEmptyPhrase, hasBareSyntaxOnly, syntaxError, err1, matchedPaths, chunkLines, chunkSimilarity, ref, where, similarityCol, selectStmt, rows, _iteratorNormalCompletion, _didIteratorError, _iteratorError, _iterator, _step, row, _ref1, _candidates_get, _iteratorNormalCompletion1, _didIteratorError1, _iteratorError1, _iterator1, _step1, row1;
         return _ts_generator(this, function(_state) {
             switch(_state.label){
                 case 0:
@@ -1029,7 +1032,7 @@ function searchSnapshot(store, cfg, terms, opts, prepared, preparedSignature) {
                     ]);
                     return [
                         4,
-                        (0, _signalsts.wordsCandidates)(store, candidates, terms, whereJoin, whereCond, scopeCond, fetch, signals.words)
+                        (0, _signalsts.wordsCandidates)(store, candidates, terms, whereJoin, whereCond, scopeCond, fetch, signals.words, opts.explain)
                     ];
                 case 5:
                     matchRows = _state.sent();
@@ -1052,7 +1055,7 @@ function searchSnapshot(store, cfg, terms, opts, prepared, preparedSignature) {
                     ];
                     return [
                         4,
-                        (0, _signalsts.linksCandidates)(store, candidates, matchRows, allPaths, allowedPaths, fetch, signals.links)
+                        (0, _signalsts.linksCandidates)(store, candidates, matchRows, allPaths, allowedPaths, fetch, signals.links, opts.explain)
                     ];
                 case 8:
                     _state.sent();
@@ -1066,7 +1069,7 @@ function searchSnapshot(store, cfg, terms, opts, prepared, preparedSignature) {
                     ];
                     return [
                         4,
-                        (0, _signalsts.vectorsCandidates)(store, prepared, candidates, fetch, allowedPaths, allPaths.length, signals.vectors)
+                        (0, _signalsts.vectorsCandidates)(store, prepared, candidates, fetch, allowedPaths, allPaths.length, signals.vectors, opts.explain)
                     ];
                 case 10:
                     ref = _state.sent(), chunkLines = ref.chunkLines, chunkSimilarity = ref.chunkSimilarity, ref;
@@ -1157,6 +1160,30 @@ function searchSnapshot(store, cfg, terms, opts, prepared, preparedSignature) {
                     ];
                 case 18:
                     _state.sent();
+                    if (opts.explain) {
+                        ;
+                        ;
+                        _iteratorNormalCompletion1 = true, _didIteratorError1 = false, _iteratorError1 = undefined;
+                        try {
+                            for(_iterator1 = rows[Symbol.iterator](); !(_iteratorNormalCompletion1 = (_step1 = _iterator1.next()).done); _iteratorNormalCompletion1 = true){
+                                row1 = _step1.value;
+                                row1.explanation = (_ref1 = (_candidates_get = candidates.get(row1.path)) === null || _candidates_get === void 0 ? void 0 : _candidates_get.explanation) !== null && _ref1 !== void 0 ? _ref1 : [];
+                            }
+                        } catch (err) {
+                            _didIteratorError1 = true;
+                            _iteratorError1 = err;
+                        } finally{
+                            try {
+                                if (!_iteratorNormalCompletion1 && _iterator1.return != null) {
+                                    _iterator1.return();
+                                }
+                            } finally{
+                                if (_didIteratorError1) {
+                                    throw _iteratorError1;
+                                }
+                            }
+                        }
+                    }
                     return [
                         2,
                         rows