@gmickel/gno 1.30.7 → 1.31.0

package/src/core/section-target.ts

@@ -0,0 +1,263 @@
+/**
+ * Durable SectionTargetV1 types, bounds, and creation.
+ * Private helper module — import public API from `./sections`.
+ *
+ * @module src/core/section-target
+ */
+
+import {
+  extractSectionRecords,
+  lineStartOffsets,
+  type SectionRecord,
+} from "./section-parse";
+
+/** Versioned, bounded, content-derived section locator (v1). */
+export interface SectionTargetV1 {
+  schemaVersion: "1";
+  document: {
+    uri: string;
+  };
+  /** Human-readable heading anchor at capture time. */
+  anchor: string;
+  /** NFC-normalized heading ancestry including the section title. */
+  headingPath: string[];
+  /** 1-based occurrence among sections with the same headingPath. */
+  occurrence: number;
+  quote: {
+    exact: string;
+    prefix: string;
+    suffix: string;
+  };
+  /** SHA-256 hex fingerprint of the full source document content. */
+  sourceFingerprint: string;
+  /** Line/offset hints only — never identity. */
+  hints: {
+    line: number;
+    startOffset: number;
+    endOffset: number;
+  };
+}
+
+export const SECTION_TARGET_SCHEMA_VERSION = "1" as const;
+
+/**
+ * Hard bounds so targets never embed full section bodies and remain
+ * schema-faithful. Identity fields (uri/anchor/headingPath) are never
+ * truncated — creation fails closed when they cannot fit.
+ */
+export const SECTION_TARGET_BOUNDS = {
+  exactMaxChars: 96,
+  prefixMaxChars: 32,
+  suffixMaxChars: 32,
+  uriMaxChars: 1024,
+  anchorMaxChars: 512,
+  headingPathItemMaxChars: 512,
+  headingPathMaxItems: 6,
+  maxSerializedBytes: 2048,
+} as const;
+
+const UTF8 = new TextEncoder();
+
+/** Structural section record with bounded quote evidence. */
+export interface QuotedSectionRecord extends SectionRecord {
+  quote: {
+    exact: string;
+    prefix: string;
+    suffix: string;
+  };
+  quoteStartOffset: number;
+  quoteEndOffset: number;
+}
+
+const clipStart = (value: string, maxChars: number): string =>
+  value.length <= maxChars ? value : value.slice(0, maxChars);
+
+const clipEnd = (value: string, maxChars: number): string =>
+  value.length <= maxChars ? value : value.slice(value.length - maxChars);
+
+const bytesOf = (value: string): number => UTF8.encode(value).byteLength;
+
+/** SHA-256 hex digest via Web Crypto (browser- and Bun-safe). */
+export async function fingerprintSourceContent(
+  content: string
+): Promise<string> {
+  const digest = new Uint8Array(
+    await crypto.subtle.digest("SHA-256", UTF8.encode(content))
+  );
+  return [...digest].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+
+const chooseQuoteRange = (
+  content: string,
+  recordTitleStart: number,
+  recordTitleEnd: number,
+  bodyStartOffset: number,
+  bodyEndOffset: number
+): { start: number; end: number } => {
+  const body = content.slice(bodyStartOffset, bodyEndOffset);
+  const trimmedLead = body.match(/^\s*/)?.[0]?.length ?? 0;
+  const trimmedTrail = body.match(/\s*$/)?.[0]?.length ?? 0;
+  const bodyContentStart = bodyStartOffset + trimmedLead;
+  const bodyContentEnd = Math.max(
+    bodyContentStart,
+    bodyEndOffset - trimmedTrail
+  );
+  if (bodyContentStart < bodyContentEnd) {
+    const exact = clipStart(
+      content.slice(bodyContentStart, bodyContentEnd),
+      SECTION_TARGET_BOUNDS.exactMaxChars
+    );
+    if (exact.length > 0) {
+      return {
+        start: bodyContentStart,
+        end: bodyContentStart + exact.length,
+      };
+    }
+  }
+  return { start: recordTitleStart, end: recordTitleEnd };
+};
+
+/**
+ * Prefer local context so heading renames / insertions do not poison prefix
+ * evidence. Falls back to a short global clip only when local context is empty.
+ */
+const buildBoundedQuote = (
+  content: string,
+  exactStart: number,
+  exactEnd: number,
+  localPrefixFloor: number
+): { exact: string; prefix: string; suffix: string } => {
+  const exact = clipStart(
+    content.slice(exactStart, exactEnd),
+    SECTION_TARGET_BOUNDS.exactMaxChars
+  );
+  const boundedEnd = exactStart + exact.length;
+  const localPrefix = content.slice(localPrefixFloor, exactStart);
+  const prefixSource =
+    localPrefix.length > 0 ? localPrefix : content.slice(0, exactStart);
+  return {
+    exact,
+    prefix: clipEnd(prefixSource, SECTION_TARGET_BOUNDS.prefixMaxChars),
+    suffix: clipStart(
+      content.slice(boundedEnd),
+      SECTION_TARGET_BOUNDS.suffixMaxChars
+    ),
+  };
+};
+
+/** Attach bounded quote evidence to structural section records. */
+export const withQuotes = (
+  content: string,
+  records: readonly SectionRecord[]
+): QuotedSectionRecord[] => {
+  const starts = lineStartOffsets(content);
+  return records.map((record) => {
+    const bodyStartOffset = starts[record.section.line] ?? content.length;
+    const bodyEndOffset =
+      record.endLine >= starts.length
+        ? content.length
+        : (starts[record.endLine] ?? content.length);
+    const quoteRange = chooseQuoteRange(
+      content,
+      record.titleStartOffset,
+      record.titleEndOffset,
+      bodyStartOffset,
+      bodyEndOffset
+    );
+    // Keep prefix local to the gap after the heading title (or markers before
+    // a title-only quote) so renames do not poison quote recovery.
+    const prefixFloor =
+      quoteRange.start >= record.titleEndOffset
+        ? record.titleEndOffset
+        : (starts[record.section.line - 1] ?? record.titleStartOffset);
+    return {
+      ...record,
+      quoteStartOffset: quoteRange.start,
+      quoteEndOffset: quoteRange.end,
+      quote: buildBoundedQuote(
+        content,
+        quoteRange.start,
+        quoteRange.end,
+        prefixFloor
+      ),
+    };
+  });
+};
+
+/**
+ * True when every identity/quote field and the UTF-8 JSON encoding satisfy
+ * runtime bounds. Identity fields must be present faithfully — never truncated.
+ */
+export const isBoundedSectionTarget = (target: SectionTargetV1): boolean => {
+  const { uri } = target.document;
+  if (
+    uri.length < 1 ||
+    uri.length > SECTION_TARGET_BOUNDS.uriMaxChars ||
+    target.anchor.length < 1 ||
+    target.anchor.length > SECTION_TARGET_BOUNDS.anchorMaxChars ||
+    target.headingPath.length < 1 ||
+    target.headingPath.length > SECTION_TARGET_BOUNDS.headingPathMaxItems ||
+    target.headingPath.some(
+      (item) =>
+        item.length < 1 ||
+        item.length > SECTION_TARGET_BOUNDS.headingPathItemMaxChars
+    ) ||
+    target.quote.exact.length > SECTION_TARGET_BOUNDS.exactMaxChars ||
+    target.quote.prefix.length > SECTION_TARGET_BOUNDS.prefixMaxChars ||
+    target.quote.suffix.length > SECTION_TARGET_BOUNDS.suffixMaxChars
+  ) {
+    return false;
+  }
+  return (
+    bytesOf(JSON.stringify(target)) <= SECTION_TARGET_BOUNDS.maxSerializedBytes
+  );
+};
+
+export interface CreateSectionTargetInput {
+  content: string;
+  uri: string;
+  /** Capture by current readable anchor, or by 1-based heading line. */
+  anchor?: string;
+  line?: number;
+}
+
+/**
+ * Create a bounded SectionTargetV1 for a heading in `content`.
+ * Returns null when the section cannot be found, or when a faithful
+ * bounded target cannot be produced (oversized uri/anchor/path/serialized).
+ */
+export async function createSectionTarget(
+  input: CreateSectionTargetInput
+): Promise<SectionTargetV1 | null> {
+  const records = withQuotes(
+    input.content,
+    extractSectionRecords(input.content)
+  );
+  const record =
+    input.anchor !== undefined
+      ? records.find((entry) => entry.section.anchor === input.anchor)
+      : input.line !== undefined
+        ? records.find((entry) => entry.section.line === input.line)
+        : undefined;
+  if (!record) return null;
+
+  const sourceFingerprint = await fingerprintSourceContent(input.content);
+  const target: SectionTargetV1 = {
+    schemaVersion: SECTION_TARGET_SCHEMA_VERSION,
+    document: { uri: input.uri },
+    anchor: record.section.anchor,
+    headingPath: [...record.headingPath],
+    occurrence: record.occurrence,
+    quote: { ...record.quote },
+    sourceFingerprint,
+    hints: {
+      line: record.section.line,
+      startOffset: record.quoteStartOffset,
+      endOffset: record.quoteEndOffset,
+    },
+  };
+
+  // Fail closed: never truncate identity-bearing uri/anchor/path.
+  if (!isBoundedSectionTarget(target)) return null;
+  return target;
+}

package/src/core/sections.ts

@@ -1,125 +1,70 @@
 /**
- * Shared section extraction and anchor helpers.
+ * Shared section extraction, anchors, and durable section targets.
  *
- * Browser-safe.
+ * Browser-safe (Web Crypto + standard string APIs only).
  *
  * @module src/core/sections
  */
 
-export interface DocumentSection {
-  anchor: string;
-  level: number;
-  line: number;
-  title: string;
-}
+export type { DocumentSection } from "./section-parse";
+export {
+  extractInclusiveLines,
+  extractSections,
+  headingForLine,
+  slugifySectionTitle,
+} from "./section-parse";
 
-const HEADING_REGEX = /^(#{1,6})\s+(.+?)\s*#*\s*$/u;
-const FENCE_REGEX = /^ {0,3}(`{3,}|~{3,})(.*)$/u;
-const FENCE_CLOSE_REGEX = /^ {0,3}(`{3,}|~{3,})[\t ]*$/u;
+export type {
+  CreateSectionTargetInput,
+  SectionTargetV1,
+} from "./section-target";
+export {
+  SECTION_TARGET_BOUNDS,
+  SECTION_TARGET_SCHEMA_VERSION,
+  createSectionTarget,
+  fingerprintSourceContent,
+  isBoundedSectionTarget,
+} from "./section-target";
 
-interface OpenFence {
-  marker: "`" | "~";
-  length: number;
-}
+export type {
+  ResolveSectionTargetInput,
+  SectionResolution,
+  SectionResolutionCandidate,
+  SectionResolutionStatus,
+} from "./section-target-resolve";
+export {
+  isNavigableSectionResolution,
+  resolveSectionTarget,
+} from "./section-target-resolve";
 
-const fenceOpener = (line: string): OpenFence | null => {
-  const match = FENCE_REGEX.exec(line);
-  const run = match?.[1];
-  const suffix = match?.[2] ?? "";
-  if (!run || (run[0] === "`" && suffix.includes("`"))) return null;
-  return { marker: run[0] as OpenFence["marker"], length: run.length };
-};
+export type {
+  SectionCitationV1,
+  SectionResolutionDiagnostics,
+  SectionTargetCreateResult,
+  SectionTargetCreateSelector,
+  SectionTargetResolveResult,
+  TransportValidationResult,
+} from "./section-target-transport";
+export {
+  CANONICAL_URI_EXCEEDS_TRANSPORT_BOUNDS,
+  CITATION_EXCEEDS_TRANSPORT_BOUNDS,
+  SECTION_TARGET_TRANSPORT_BOUNDS,
+  isTransportBoundedCandidate,
+  isTransportBoundedCanonicalUri,
+  isTransportBoundedCitation,
+  parseSectionTargetCreateSelector,
+  parseSectionTargetResolveBody,
+  parseSectionTargetV1,
+  projectSectionTargetCreateResult,
+  projectSectionTargetResolveResult,
+} from "./section-target-transport";
 
-const closesFence = (line: string, fence: OpenFence): boolean => {
-  const run = FENCE_CLOSE_REGEX.exec(line)?.[1];
-  return Boolean(run && run[0] === fence.marker && run.length >= fence.length);
-};
-
-export function slugifySectionTitle(title: string): string {
-  return (
-    title
-      .normalize("NFC")
-      .toLowerCase()
-      .trim()
-      .replaceAll(/[^\p{L}\p{N}\s-]/gu, "")
-      .replaceAll(/\s+/g, "-")
-      .replaceAll(/-+/g, "-")
-      .replace(/^-|-$/g, "") || "section"
-  );
-}
-
-export function extractSections(content: string): DocumentSection[] {
-  const sections: DocumentSection[] = [];
-  const counts = new Map<string, number>();
-  const lines = content.split("\n");
-  let openFence: OpenFence | null = null;
-
-  for (const [index, line] of lines.entries()) {
-    if (openFence) {
-      if (closesFence(line, openFence)) openFence = null;
-      continue;
-    }
-    const opener = fenceOpener(line);
-    if (opener) {
-      openFence = opener;
-      continue;
-    }
-    const match = HEADING_REGEX.exec(line);
-    if (!match) {
-      continue;
-    }
-
-    const level = match[1]?.length ?? 0;
-    const title = match[2]?.trim() ?? "";
-    if (!title) {
-      continue;
-    }
-
-    const baseAnchor = slugifySectionTitle(title);
-    const count = (counts.get(baseAnchor) ?? 0) + 1;
-    counts.set(baseAnchor, count);
-    const anchor = count === 1 ? baseAnchor : `${baseAnchor}-${count}`;
-
-    sections.push({
-      anchor,
-      level,
-      line: index + 1,
-      title,
-    });
-  }
-
-  return sections;
-}
-
-/** Extract one inclusive, 1-based line range without normalizing source bytes. */
-export function extractInclusiveLines(
-  content: string,
-  startLine: number,
-  endLine: number
-): string | null {
-  if (
-    content.includes("\r") ||
-    !Number.isSafeInteger(startLine) ||
-    !Number.isSafeInteger(endLine) ||
-    startLine < 1 ||
-    endLine < startLine
-  ) {
-    return null;
-  }
-  const lines = content.split("\n");
-  if (endLine > lines.length) return null;
-  return lines.slice(startLine - 1, endLine).join("\n");
-}
-
-/** Find the nearest Markdown heading governing a 1-based source line. */
-export function headingForLine(
-  sections: readonly DocumentSection[],
-  line: number
-): string | null {
-  let heading: string | null = null;
-  for (const section of sections) {
-    if (section.line > line) break;
-    heading = section.title;
-  }
-  return heading;
-}
+export type { SectionTargetLinkDecodeFailure } from "./section-target-link";
+export {
+  SECTION_TARGET_LINK_MAX_ENCODED_CHARS,
+  SECTION_TARGET_LINK_PARAM,
+  SECTION_TARGET_LINK_VERSION,
+  classifySectionTargetLinkDecodeFailure,
+  decodeSectionTargetLinkParam,
+  encodeSectionTargetLinkParam,
+} from "./section-target-link";

package/src/mcp/AGENTS.md

@@ -13,6 +13,7 @@ src/mcp/
 │   ├── vsearch.ts     # gno_vsearch (vector)
 │   ├── query.ts       # gno_query (hybrid)
 │   ├── get.ts         # gno_get (single doc)
+│   ├── sections.ts    # gno_section (section target create/resolve)
 │   ├── multi-get.ts   # gno_multi_get (batch)
 │   └── status.ts      # gno_status
 └── resources/         # Resource implementations

package/src/mcp/CLAUDE.md

@@ -13,6 +13,7 @@ src/mcp/
 │   ├── vsearch.ts     # gno_vsearch (vector)
 │   ├── query.ts       # gno_query (hybrid)
 │   ├── get.ts         # gno_get (single doc)
+│   ├── sections.ts    # gno_section (section target create/resolve)
 │   ├── multi-get.ts   # gno_multi_get (batch)
 │   └── status.ts      # gno_status
 └── resources/         # Resource implementations

package/src/mcp/http-egress.ts

@@ -53,6 +53,7 @@ export const MCP_HTTP_EGRESS_TOOLS = {
   gno_remove_collection: "metadata",
   gno_rename_note: "metadata",
   gno_search: "snippet",
+  gno_section: "metadata",
   gno_similar: "snippet",
   gno_status: "metadata",
   gno_sync: "metadata",

package/src/mcp/tools/index.ts

@@ -67,6 +67,12 @@ import { handleMultiGet } from "./multi-get";
 import { handleQuery, handleQueryDiagnose } from "./query";
 import { handleRemoveCollection } from "./remove-collection";
 import { handleSearch } from "./search";
+import {
+  handleSection,
+  SECTION_MCP_ANNOTATIONS,
+  sectionInputSchema,
+  sectionOutputSchema,
+} from "./sections";
 import { handleStatus } from "./status";
 import { handleSync } from "./sync";
 import {
@@ -116,6 +122,8 @@ export const MCP_TOOL_DESCRIPTIONS = {
   get: "Retrieve one document by gno:// URI, docid (#abc123), or collection/path. After search results include line, pass fromLine and lineCount to fetch only the relevant range before expanding to the full document.",
   multiGet:
     "Retrieve multiple documents by refs array or glob pattern. Use after gno_search/gno_query to batch top result URIs/docids; set maxBytes and lineNumbers to control context size.",
+  section:
+    "Create or resolve a durable SectionTargetV1 against one indexed document. action=create needs ref plus exactly one of anchor|line; action=resolve needs ref plus target. Exact/recovered include citation (uri, anchor, title, inclusive lines, fingerprint); ambiguous/stale/missing omit citation and are not safe to navigate or cite. Read-only — does not write or persist targets. Follow navigable ranges with gno_get fromLine/lineCount.",
   status:
     "Get index health: collection count, document count, chunk count, embedding backlog, and per-collection stats. Check first when vector/hybrid results look stale or unavailable.",
   context:
@@ -1064,6 +1072,17 @@ export function registerTools(server: McpServer, ctx: ToolContext): void {
     (args) => handleGet(args, ctx)
   );
 
+  server.registerTool(
+    "gno_section",
+    {
+      description: MCP_TOOL_DESCRIPTIONS.section,
+      inputSchema: sectionInputSchema,
+      outputSchema: sectionOutputSchema,
+      annotations: SECTION_MCP_ANNOTATIONS,
+    },
+    (args) => handleSection(args, ctx)
+  );
+
   server.tool(
     "gno_multi_get",
     MCP_TOOL_DESCRIPTIONS.multiGet,