obsidian-mcp-server 3.5.4 → 3.6.0

package/dist/services/obsidian/section-extractor.d.ts

@@ -1,16 +1,18 @@
 /**
- * @fileoverview Client-side section extraction from a NoteJson body.
- * The upstream Local REST API exposes section *targeting* for PATCH but not
- * section-extracted GET, so we slice the markdown ourselves for `format: 'section'`.
+ * @fileoverview Client-side section extraction from a NoteJson body for
+ * `format: 'section'`. Headings are found the way the plugin's markdown-patch
+ * finds them for its document map and PATCH targeting, so a section read
+ * covers the span a section write edits, sliced from the note's own bytes.
  * @module services/obsidian/section-extractor
  */
 import type { NoteJson, SectionTarget } from './types.js';
 /** An extracted section value plus, for heading targets, how the locator resolved. */
 export interface SectionExtraction {
     /**
-     * Every full heading path sharing the bare-leaf target, in document order.
-     * Present only when more than one heading matched — the read still returns
-     * the first, so this is disclosure, not a new failure mode.
+     * Every full heading path the target could name, in document order: each
+     * heading sharing a bare-leaf target, or each repeat of a delimited target's
+     * resolved path. Present only when more than one heading matched — the read
+     * still returns the first, so this is disclosure, not a new failure mode.
      */
     candidates?: string[];
     /**
@@ -26,6 +28,107 @@ export interface SectionExtraction {
  * Throws `NotFound` if the target does not exist in the note.
  */
 export declare function extractSection(note: NoteJson, section: SectionTarget): SectionExtraction;
+/** A heading as the plugin's parser reads it, located in the note's own bytes. */
+export interface Heading {
+    /**
+     * Offset just past the heading's last line — its underline, for a setext
+     * heading — and that line's ending, or the note's length.
+     */
+    end: number;
+    /** 1–6: the `#` count of an ATX heading, 1 or 2 for a setext `=` or `-` underline. */
+    level: number;
+    /** Offset of the heading's first byte: its `#` line (indent included), or a setext heading's first text line. */
+    start: number;
+    /**
+     * Heading text as the document map keys it: the parser's text, trimmed.
+     * Empty for an untitled heading; a multi-line setext heading keeps its
+     * newlines.
+     */
+    text: string;
+}
+/**
+ * Every heading in `content`, in document order, found the way the plugin's
+ * markdown-patch 2.0 finds them for its document map and PATCH targeting: the
+ * frontmatter-stripped body, line endings normalized, lexed with `marked`, and
+ * each top-level `heading` token located by accumulating token `raw` lengths.
+ * That reads setext headings and skips `#` lines inside fences, HTML blocks,
+ * list items, and blockquotes, exactly as the map does. Offsets are mapped
+ * back to `content`, so a slice between them is the note's own bytes, CRs
+ * included.
+ */
+export declare function scanHeadings(content: string): Heading[];
+/** A section's own body, as markdown-patch 2.0 models it for a `within` write. */
+export interface SectionBody {
+    /**
+     * `marked` token type of each top-level block in the section's direct body —
+     * below its heading line and above its first sub-heading — in order: the
+     * blocks a 2.0 `within` index counts (`paragraph`, `list`, `table`, `code`, …).
+     */
+    blocks: string[];
+    /**
+     * The section's `content` scope in the note's own bytes: below its heading
+     * line through its last subsection. What 2.0's `rejectIfContentPreexists`
+     * searches on a plain heading write.
+     */
+    content: string;
+    /** Whether sub-headings follow the direct body — a plain append lands below them. */
+    subsections: boolean;
+}
+/**
+ * The body of the heading at full path `path` (its first occurrence), read
+ * from one lex of the note, or `undefined` when the note has no such heading.
+ * 2.0 assigns a section every top-level token between its heading and the
+ * next heading of any level; a `space` token is not a block.
+ */
+export declare function sectionBody(content: string, path: string): SectionBody | undefined;
+/** The `marked` token type of each top-level block in `markdown`, in order. */
+export declare function blockKinds(markdown: string): string[];
+/**
+ * Full `::`-joined path of every heading in `content`, in document order,
+ * repeats included — the markdown-patch 2.0 map's heading tree, flattened.
+ * Deduplicated and with the `""` entry dropped, it is the 1.x map's `headings`
+ * array.
+ */
+export declare function listHeadingPaths(content: string): string[];
+/**
+ * The level of the heading at full path `path` in `content` — its first
+ * occurrence. For a path the note does not have: with `create`, the level
+ * markdown-patch 2.0 gives it when `createTargetIfMissing` creates it — one
+ * below the deepest existing ancestor for each missing segment, counted from 0
+ * when no ancestor exists — and without, `undefined`.
+ */
+export declare function sectionLevel(content: string, path: string, create: boolean): number | undefined;
+/**
+ * True when `blockId` is referenced in `content` by an isolated marker: a
+ * `^blockId` line on its own, after a blank line (or at the body's start), so
+ * the parser reads it as its own paragraph and the id names the block above.
+ * A marker line with no blank line above it continues that block instead (a
+ * table row, a paragraph line, a list item), and a line inside a fence or
+ * indented as code is not a marker.
+ */
+export declare function isIsolatedBlockId(content: string, blockId: string): boolean;
+/** The `#` run opening a top-level ATX heading in a markdown fragment. */
+export interface AtxHeadingMarker {
+    /** Length of the `#` run — the heading's level. */
+    hashes: number;
+    /** The heading's line, trimmed, for messages. */
+    line: string;
+    /** Offset of the run's first `#` in the fragment's `normalized` text. */
+    start: number;
+}
+/** A markdown fragment with its line endings read as `\n`, and its ATX heading markers. */
+export interface AtxHeadingFragment {
+    markers: AtxHeadingMarker[];
+    normalized: string;
+}
+/**
+ * The `#` run of every top-level ATX heading in `markdown`, found as
+ * markdown-patch 2.0 finds the headings it re-levels in written content: line
+ * endings normalized, lexed with `marked`, and each top-level `heading` token
+ * whose raw text opens with a `#` run. A setext heading, a `#` line inside a
+ * fence or HTML block, and a hashtag carry none.
+ */
+export declare function atxHeadingMarkers(markdown: string): AtxHeadingFragment;
 /**
  * Mark line indices that fall inside fenced code blocks (` ``` ` or `~~~`) so
  * downstream scanning doesn't false-match on markdown-about-markdown notes.

package/dist/services/obsidian/section-extractor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"section-extractor.d.ts","sourceRoot":"","sources":["../../../src/services/obsidian/section-extractor.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAK1D,sFAAsF;AACtF,MAAM,WAAW,iBAAiB;IAChC;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,wEAAwE;IACxE,KAAK,EAAE,OAAO,CAAC;CAChB;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,aAAa,GAAG,iBAAiB,CASxF;AAgMD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,IAAI,SAAI,GAAG,OAAO,EAAE,CA0BrE"}
+{"version":3,"file":"section-extractor.d.ts","sourceRoot":"","sources":["../../../src/services/obsidian/section-extractor.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH,OAAO,KAAK,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAK1D,sFAAsF;AACtF,MAAM,WAAW,iBAAiB;IAChC;;;;;OAKG;IACH,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,wEAAwE;IACxE,KAAK,EAAE,OAAO,CAAC;CAChB;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,aAAa,GAAG,iBAAiB,CASxF;AAYD,kFAAkF;AAClF,MAAM,WAAW,OAAO;IACtB;;;OAGG;IACH,GAAG,EAAE,MAAM,CAAC;IACZ,sFAAsF;IACtF,KAAK,EAAE,MAAM,CAAC;IACd,iHAAiH;IACjH,KAAK,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,IAAI,EAAE,MAAM,CAAC;CACd;AAaD;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,EAAE,CAMvD;AA6BD,kFAAkF;AAClF,MAAM,WAAW,WAAW;IAC1B;;;;OAIG;IACH,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB;;;;OAIG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB,qFAAqF;IACrF,WAAW,EAAE,OAAO,CAAC;CACtB;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAoBlF;AAED,+EAA+E;AAC/E,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,CAIrD;AAuJD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAE1D;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAW/F;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAa3E;AAED,0EAA0E;AAC1E,MAAM,WAAW,gBAAgB;IAC/B,mDAAmD;IACnD,MAAM,EAAE,MAAM,CAAC;IACf,iDAAiD;IACjD,IAAI,EAAE,MAAM,CAAC;IACb,yEAAyE;IACzE,KAAK,EAAE,MAAM,CAAC;CACf;AAED,2FAA2F;AAC3F,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,gBAAgB,EAAE,CAAC;IAC5B,UAAU,EAAE,MAAM,CAAC;CACpB;AAKD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,kBAAkB,CActE;AAmJD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,IAAI,SAAI,GAAG,OAAO,EAAE,CA0BrE"}