sensemaking 0.25.1 → 0.27.0

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

@@ -2,19 +2,42 @@ import type { FeatureName, ResolvedConfig, SearchOverrides } from '../config/ind
 import type { Row } from '../output/output.js';
 import type { Store } from '../store/types.js';
 export declare function resolveNote(paths: string[], arg: string): string;
+/** Structured, bounded metadata returned by the root {@link peek} API. */
 export interface Peek {
     path: string;
     tokens: number;
     frontmatter: Row;
+    /** Set when frontmatter parsing failed, distinguishing that case from an empty block. */
     parseError: string | null;
-    sections: Row[];
+    sections: PeekSection[];
     outbound: string[];
     backlinks: string[];
     unresolved: string[];
+    /** Totals before each bounded list is truncated. */
     sectionsTotal: number;
     outboundTotal: number;
     backlinksTotal: number;
     unresolvedTotal: number;
+    /** Disabled features whose result blocks are omitted rather than returned empty. */
     off: FeatureName[];
 }
-export declare function peek(store: Store, cfg: ResolvedConfig, pathArg: string, overrides?: SearchOverrides): Promise<Peek>;
+/** A section description, with an inclusive source line range and token estimate, not section prose. */
+export interface PeekSection {
+    level: number;
+    heading: string;
+    start_line: number;
+    end_line: number;
+    tokens: number;
+}
+/** Options for the root {@link peek} API. */
+export interface PeekOptions extends SearchOverrides {
+    /** Maximum section descriptions. Defaults to 20; must be a positive safe integer. */
+    sectionCountLimit?: number;
+    /** Maximum entries in each link group independently. Defaults to 20; must be a positive safe integer. */
+    linkCountLimit?: number;
+}
+/**
+ * Returns indexed metadata for a note in scope. Exact excluded paths fail before scoped basename
+ * resolution; resolved neighbors stay in scope, while unresolved written targets remain visible.
+ */
+export declare function peek(store: Store, cfg: ResolvedConfig, pathArg: string, overrides?: PeekOptions): Promise<Peek>;

package/dist/cjs/commands/peek.js

@@ -22,6 +22,7 @@ var _indexts1 = require("../config/index.js");
 var _errorsts = require("../errors.js");
 var _serialqueryts = require("../lib/serial-query.js");
 var _scopets = require("./scope.js");
+var _snapshotts = require("./snapshot.js");
 function _array_like_to_array(arr, len) {
     if (len == null || len > arr.length) len = arr.length;
     for(var i = 0, arr2 = new Array(len); i < len; i++)arr2[i] = arr[i];
@@ -59,6 +60,12 @@ function _async_to_generator(fn) {
         });
     };
 }
+function _instanceof(left, right) {
+    "@swc/helpers - instanceof";
+    if (right != null && typeof Symbol !== "undefined" && right[Symbol.hasInstance]) {
+        return !!right[Symbol.hasInstance](left);
+    } else return left instanceof right;
+}
 function _interop_require_default(obj) {
     return obj && obj.__esModule ? obj : {
         default: obj
@@ -225,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() {
@@ -234,41 +241,85 @@ 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, path, 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:
                                     return [
                                         4,
-                                        store.prepare('SELECT "path" FROM frontmatter')
+                                        (0, _snapshotts.assertQuerySnapshot)(store, cfg)
                                     ];
                                 case 1:
+                                    _state.sent();
+                                    return [
+                                        4,
+                                        store.prepare('SELECT "path" FROM frontmatter')
+                                    ];
+                                case 2:
                                     pathsStmt = _state.sent();
                                     return [
                                         4,
                                         pathsStmt.all()
                                     ];
-                                case 2:
+                                case 3:
                                     paths = _state.sent().map(function(r) {
                                         return r.path;
                                     });
-                                    path = resolveNote(paths, pathArg);
+                                    return [
+                                        4,
+                                        (0, _scopets.scopedPaths)(store, cfg, overrides)
+                                    ];
+                                case 4:
+                                    allowed = _state.sent();
+                                    if (paths.includes(pathArg) && !allowed.has(pathArg)) {
+                                        throw new _errorsts.SenseError('NOTE_NOT_FOUND', 'note "'.concat(pathArg, '" exists but is outside the current scope; change the preset, include/exclude patterns, or where condition'));
+                                    }
+                                    try {
+                                        path = resolveNote(_to_consumable_array(allowed), pathArg);
+                                    } catch (err) {
+                                        if (_instanceof(err, _errorsts.SenseError) && err.code === 'NOTE_NOT_FOUND') {
+                                            ;
+                                            try {
+                                                excludedPath = resolveNote(paths, pathArg);
+                                            } catch (unscopedErr) {
+                                                if (_instanceof(unscopedErr, _errorsts.SenseError) && unscopedErr.code === 'NOTE_AMBIGUOUS') {
+                                                    throw new _errorsts.SenseError('NOTE_NOT_FOUND', 'no note in the current scope matches "'.concat(pathArg, '"; indexed matches exist outside the scope, so change the preset, include/exclude patterns, or where condition'));
+                                                }
+                                                throw err;
+                                            }
+                                            throw new _errorsts.SenseError('NOTE_NOT_FOUND', 'note "'.concat(excludedPath, '" exists but is outside the current scope; change the preset, include/exclude patterns, or where condition'));
+                                        }
+                                        throw err;
+                                    }
                                     return [
                                         4,
                                         store.prepare('SELECT * FROM frontmatter WHERE "path" = ?')
                                     ];
-                                case 3:
+                                case 5:
                                     rowStmt = _state.sent();
                                     return [
                                         4,
                                         rowStmt.get(path)
                                     ];
-                                case 4:
+                                case 6:
                                     row = _state.sent();
                                     parseError = (_row__parse_error = row._parse_error) !== null && _row__parse_error !== void 0 ? _row__parse_error : null;
                                     frontmatter = {};
@@ -296,103 +347,133 @@ function peekIndexed(store, cfg, pathArg, overrides) {
                                     sections = [];
                                     if (!(0, _indexts1.featureEnabled)(cfg, 'sections')) return [
                                         3,
-                                        9
+                                        11
                                     ];
                                     return [
                                         4,
                                         store.prepare('SELECT COUNT(*) AS n FROM sections WHERE "path" = ?')
                                     ];
-                                case 5:
+                                case 7:
                                     return [
                                         4,
                                         _state.sent().get(path)
                                     ];
-                                case 6:
+                                case 8:
                                     sectionsTotal = _state.sent().n;
                                     return [
                                         4,
                                         store.prepare('SELECT level, heading, start_line, end_line, tokens FROM sections WHERE "path" = ? ORDER BY idx LIMIT ?')
                                     ];
-                                case 7:
+                                case 9:
                                     return [
                                         4,
-                                        _state.sent().all(path, PEEK_LIST_LIMIT)
+                                        _state.sent().all(path, sectionCountLimit)
                                     ];
-                                case 8:
+                                case 10:
                                     sections = _state.sent();
-                                    _state.label = 9;
-                                case 9:
+                                    _state.label = 11;
+                                case 11:
                                     outbound = [];
                                     backlinks = [];
                                     unresolved = [];
+                                    outboundTotal = 0;
                                     backlinksTotal = 0;
+                                    unresolvedTotal = 0;
+                                    if (!(0, _indexts1.featureEnabled)(cfg, 'links')) return [
+                                        3,
+                                        25
+                                    ];
                                     return [
                                         4,
-                                        (0, _scopets.scopedPaths)(store, cfg, overrides)
+                                        (0, _scopets.materializeScope)(store, '_peek_scope', allowed)
                                     ];
-                                case 10:
-                                    _state.sent(); // validates --preset/--where/--include/--exclude even though peek's own output isn't scope-filtered
-                                    if (!(0, _indexts1.featureEnabled)(cfg, 'links')) return [
-                                        3,
-                                        17
+                                case 12:
+                                    _state.sent();
+                                    return [
+                                        4,
+                                        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,
-                                        store.prepare('SELECT target, dst FROM links WHERE src = ? AND (dst IS NULL OR dst != src) ORDER BY target')
+                                        _state.sent().get(path)
                                     ];
-                                case 11:
+                                case 14:
+                                    outboundTotal = _state.sent().n;
                                     return [
                                         4,
-                                        _state.sent().all(path)
+                                        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 12:
-                                    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;
+                                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(DISTINCT src) AS n FROM links WHERE dst = ? AND src != dst')
+                                        store.prepare('SELECT COUNT(*) AS n FROM links WHERE src = ? AND dst IS NULL')
                                     ];
-                                case 13:
+                                case 17:
                                     return [
                                         4,
                                         _state.sent().get(path)
                                     ];
-                                case 14:
+                                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 21:
+                                    return [
+                                        4,
+                                        _state.sent().get(path)
+                                    ];
+                                case 22:
                                     backlinksTotal = _state.sent().n;
                                     return [
                                         4,
-                                        store.prepare('SELECT DISTINCT src FROM links WHERE dst = ? AND src != dst ORDER BY src LIMIT ?')
+                                        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 15:
+                                case 23:
                                     return [
                                         4,
-                                        _state.sent().all(path, PEEK_LIST_LIMIT)
+                                        _state.sent().all(path, linkCountLimit)
                                     ];
-                                case 16:
+                                case 24:
                                     backlinks = _state.sent().map(function(r) {
                                         return r.src;
                                     });
-                                    _state.label = 17;
-                                case 17:
+                                    _state.label = 25;
+                                case 25:
                                     return [
                                         4,
                                         store.prepare('SELECT text FROM content WHERE "path" = ?')
                                     ];
-                                case 18:
+                                case 26:
                                     return [
                                         4,
                                         _state.sent().get(path)
                                     ];
-                                case 19:
+                                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;
@@ -404,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, scopedPaths } from './scope.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\nexport interface Peek {\n  path: string;\n  tokens: number;\n  frontmatter: Row;\n  // Set when the note's frontmatter was refused, so an empty frontmatter block reads as \"did\n  // not parse\" rather than \"has none\". Same reason `_parse_error` sits in the row.\n  parseError: string | null;\n  sections: Row[];\n  outbound: string[];\n  backlinks: string[];\n  unresolved: string[];\n  // Totals before truncation: a hub can have thousands of backlinks (or a note thousands of\n  // headings), and peek's whole point is bounded output.\n  sectionsTotal: number;\n  outboundTotal: number;\n  backlinksTotal: number;\n  unresolvedTotal: number;\n  // Bounded k-hop expansion beyond the immediate ring already shown by outbound/backlinks\n  // (depth starts at 2).\n  off: FeatureName[]; // disabled features whose blocks are omitted (not empty)\n}\n\nconst PEEK_LIST_LIMIT = 20;\n\n// peek: everything about one note except its prose -- frontmatter, outline with line\n// ranges + token estimates (so the follow-up Read is a range, not the file), links both ways.\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    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 path = resolveNote(paths, pathArg);\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: Row[] = [];\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 Row[];\n    }\n\n    let outbound: string[] = [];\n    let backlinks: string[] = [];\n    let unresolved: string[] = [];\n    let backlinksTotal = 0;\n    await scopedPaths(store, cfg, overrides); // validates --preset/--where/--include/--exclude even though peek's own output isn't scope-filtered\n    if (featureEnabled(cfg, 'links')) {\n      const out = (await (await store.prepare('SELECT target, dst FROM links WHERE src = ? AND (dst IS NULL OR dst != src) ORDER BY target')).all(path)) as Array<{ target: string; dst: string | null }>;\n      outbound = [...new Set(out.filter((l) => l.dst !== null).map((l) => l.dst as string))];\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')).get(path)) as { n: number }).n;\n      backlinks = ((await (await store.prepare('SELECT DISTINCT src FROM links WHERE dst = ? AND src != dst 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","path","rowStmt","parseError","frontmatter","key","value","sectionsTotal","sections","outbound","backlinks","unresolved","backlinksTotal","out","body","byteTokens","tokens","prepare","all","map","r","get","_parse_error","Object","entries","INTERNAL_COLUMNS","has","featureEnabled","n","scopedPaths","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/related.d.cts

@@ -1,7 +1,20 @@
 import type { ResolvedConfig, SearchOverrides } from '../config/index.js';
 import type { Store } from '../store/types.js';
-export declare function resolveRelatedSeed(store: Store, pathArg: string): Promise<string>;
-export declare function relatedNotes(store: Store, cfg: ResolvedConfig, pathArg: string, overrides: SearchOverrides, k: number): Promise<Array<{
+export declare const RELATED_DEFAULT_K = 5;
+/**
+ * Options for {@link relatedNotes}. Scope fields filter result candidates, not the seed note;
+ * `k` defaults to 5, matching the CLI.
+ */
+export interface RelatedOptions extends SearchOverrides {
+    k?: number;
+}
+export type RelatedResult = {
     path: string;
     similarity: number;
-}>>;
+};
+export declare function resolveRelatedSeed(store: Store, pathArg: string): Promise<string>;
+/**
+ * Returns the notes most similar to an indexed seed, excluding the seed and notes linked either
+ * way. The seed resolves across the indexed tree even when it is outside the candidate scope.
+ */
+export declare function relatedNotes(store: Store, cfg: ResolvedConfig, pathArg: string, options?: RelatedOptions): Promise<RelatedResult[]>;

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

@@ -1,7 +1,20 @@
 import type { ResolvedConfig, SearchOverrides } from '../config/index.js';
 import type { Store } from '../store/types.js';
-export declare function resolveRelatedSeed(store: Store, pathArg: string): Promise<string>;
-export declare function relatedNotes(store: Store, cfg: ResolvedConfig, pathArg: string, overrides: SearchOverrides, k: number): Promise<Array<{
+export declare const RELATED_DEFAULT_K = 5;
+/**
+ * Options for {@link relatedNotes}. Scope fields filter result candidates, not the seed note;
+ * `k` defaults to 5, matching the CLI.
+ */
+export interface RelatedOptions extends SearchOverrides {
+    k?: number;
+}
+export type RelatedResult = {
     path: string;
     similarity: number;
-}>>;
+};
+export declare function resolveRelatedSeed(store: Store, pathArg: string): Promise<string>;
+/**
+ * Returns the notes most similar to an indexed seed, excluding the seed and notes linked either
+ * way. The seed resolves across the indexed tree even when it is outside the candidate scope.
+ */
+export declare function relatedNotes(store: Store, cfg: ResolvedConfig, pathArg: string, options?: RelatedOptions): Promise<RelatedResult[]>;