@gmickel/gno 1.30.7 → 1.31.0

package/src/core/section-parse.ts

@@ -0,0 +1,187 @@
+/**
+ * Shared Markdown section extraction (ATX headings + fence awareness).
+ * Private helper module — import public API from `./sections`.
+ *
+ * @module src/core/section-parse
+ */
+
+export interface DocumentSection {
+  anchor: string;
+  level: number;
+  line: number;
+  title: string;
+}
+
+/** Structural section record used by target create/resolve. */
+export interface SectionRecord {
+  section: DocumentSection;
+  headingPath: string[];
+  occurrence: number;
+  /** Inclusive start line through exclusive end line of section body. */
+  endLine: number;
+  titleStartOffset: number;
+  titleEndOffset: number;
+}
+
+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;
+
+interface OpenFence {
+  marker: "`" | "~";
+  length: number;
+}
+
+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 };
+};
+
+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 const normalizeHeadingTitle = (title: string): string =>
+  title.normalize("NFC").trim();
+
+export const pathKey = (headingPath: readonly string[]): string =>
+  headingPath.join("\0");
+
+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 const lineStartOffsets = (content: string): number[] => {
+  const offsets = [0];
+  for (let index = 0; index < content.length; index += 1) {
+    if (content[index] === "\n") offsets.push(index + 1);
+  }
+  return offsets;
+};
+
+/** Extract structural section records (no quote evidence). */
+export function extractSectionRecords(content: string): SectionRecord[] {
+  const records: SectionRecord[] = [];
+  const counts = new Map<string, number>();
+  const pathCounts = new Map<string, number>();
+  const lines = content.split("\n");
+  const starts = lineStartOffsets(content);
+  let openFence: OpenFence | null = null;
+  const stack: { level: number; title: string }[] = [];
+
+  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 normalizedTitle = normalizeHeadingTitle(title);
+    while (stack.length > 0 && (stack.at(-1)?.level ?? 0) >= level) {
+      stack.pop();
+    }
+    stack.push({ level, title: normalizedTitle });
+    const headingPath = stack.map((entry) => entry.title);
+    const occurrence = (pathCounts.get(pathKey(headingPath)) ?? 0) + 1;
+    pathCounts.set(pathKey(headingPath), occurrence);
+
+    const baseAnchor = slugifySectionTitle(title);
+    const count = (counts.get(baseAnchor) ?? 0) + 1;
+    counts.set(baseAnchor, count);
+    const anchor = count === 1 ? baseAnchor : `${baseAnchor}-${count}`;
+
+    const lineStart = starts[index] ?? 0;
+    const titleOffsetInLine = line.indexOf(title);
+    const titleStartOffset =
+      titleOffsetInLine >= 0 ? lineStart + titleOffsetInLine : lineStart;
+    const titleEndOffset = titleStartOffset + title.length;
+
+    records.push({
+      section: {
+        anchor,
+        level,
+        line: index + 1,
+        title,
+      },
+      headingPath,
+      occurrence,
+      endLine: lines.length,
+      titleStartOffset,
+      titleEndOffset,
+    });
+  }
+
+  for (const [recordIndex, record] of records.entries()) {
+    let endLine = lines.length;
+    for (let next = recordIndex + 1; next < records.length; next += 1) {
+      const candidate = records[next];
+      if (candidate && candidate.section.level <= record.section.level) {
+        endLine = candidate.section.line - 1;
+        break;
+      }
+    }
+    record.endLine = endLine;
+  }
+
+  return records;
+}
+
+export function extractSections(content: string): DocumentSection[] {
+  return extractSectionRecords(content).map((record) => record.section);
+}
+
+/** 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;
+}

package/src/core/section-target-link.ts

@@ -0,0 +1,154 @@
+/**
+ * Privacy-safe, bounded encoding of SectionTargetV1 for additive URL params.
+ * Private helper — import public API from `./sections`.
+ *
+ * Human-readable `#anchor` fragments stay unchanged. The optional `st`
+ * query param carries a versioned, size-bounded target for citation-safe
+ * recovery. It must never embed a full section body.
+ *
+ * @module src/core/section-target-link
+ */
+
+import {
+  isBoundedSectionTarget,
+  SECTION_TARGET_BOUNDS,
+  type SectionTargetV1,
+} from "./section-target";
+import { parseSectionTargetV1 } from "./section-target-transport";
+
+/** Query parameter name for the additive durable selector. */
+export const SECTION_TARGET_LINK_PARAM = "st" as const;
+
+/** Version prefix for the encoded selector payload. */
+export const SECTION_TARGET_LINK_VERSION = "1" as const;
+
+/**
+ * Hard cap on the encoded `st` value (version prefix + base64url payload).
+ * Keeps citation links shareable in local tooling without giant URLs.
+ */
+export const SECTION_TARGET_LINK_MAX_ENCODED_CHARS = 3072 as const;
+
+const UTF8 = new TextEncoder();
+const UTF8_DECODER = new TextDecoder();
+
+const bytesToBase64Url = (bytes: Uint8Array): string => {
+  let binary = "";
+  for (const byte of bytes) {
+    binary += String.fromCharCode(byte);
+  }
+  return btoa(binary)
+    .replaceAll("+", "-")
+    .replaceAll("/", "_")
+    .replace(/=+$/u, "");
+};
+
+const base64UrlToBytes = (value: string): Uint8Array | null => {
+  if (!/^[A-Za-z0-9_-]*$/u.test(value)) {
+    return null;
+  }
+  const padded = value.replaceAll("-", "+").replaceAll("_", "/");
+  const padLength = (4 - (padded.length % 4)) % 4;
+  const base64 = padded + "=".repeat(padLength);
+  try {
+    const binary = atob(base64);
+    const bytes = new Uint8Array(binary.length);
+    for (let index = 0; index < binary.length; index += 1) {
+      bytes[index] = binary.charCodeAt(index);
+    }
+    return bytes;
+  } catch {
+    return null;
+  }
+};
+
+/**
+ * Encode a bounded SectionTargetV1 as `1.<base64url(json)>`.
+ * Returns null when the target is unbounded or the encoded form exceeds
+ * {@link SECTION_TARGET_LINK_MAX_ENCODED_CHARS}.
+ */
+export function encodeSectionTargetLinkParam(
+  target: SectionTargetV1
+): string | null {
+  if (!isBoundedSectionTarget(target)) {
+    return null;
+  }
+  const json = JSON.stringify(target);
+  if (UTF8.encode(json).byteLength > SECTION_TARGET_BOUNDS.maxSerializedBytes) {
+    return null;
+  }
+  const encoded = `${SECTION_TARGET_LINK_VERSION}.${bytesToBase64Url(UTF8.encode(json))}`;
+  if (encoded.length > SECTION_TARGET_LINK_MAX_ENCODED_CHARS) {
+    return null;
+  }
+  return encoded;
+}
+
+/**
+ * Decode an `st` query value into a validated SectionTargetV1.
+ * Fail-closed: malformed version, padding, JSON, or bounds → null.
+ * Error paths never echo quote/body text.
+ */
+export function decodeSectionTargetLinkParam(
+  value: string
+): SectionTargetV1 | null {
+  if (
+    value.length < 3 ||
+    value.length > SECTION_TARGET_LINK_MAX_ENCODED_CHARS
+  ) {
+    return null;
+  }
+  const dot = value.indexOf(".");
+  if (dot < 1) {
+    return null;
+  }
+  const version = value.slice(0, dot);
+  const payload = value.slice(dot + 1);
+  if (version !== SECTION_TARGET_LINK_VERSION || payload.length < 1) {
+    return null;
+  }
+  const bytes = base64UrlToBytes(payload);
+  if (!bytes || bytes.byteLength > SECTION_TARGET_BOUNDS.maxSerializedBytes) {
+    return null;
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(UTF8_DECODER.decode(bytes));
+  } catch {
+    return null;
+  }
+  const validated = parseSectionTargetV1(parsed);
+  if (!validated.ok) {
+    return null;
+  }
+  return validated.value;
+}
+
+/** Stable, content-free reason codes for link decode failures. */
+export type SectionTargetLinkDecodeFailure =
+  | "missing"
+  | "malformed"
+  | "unsupported_version"
+  | "oversized";
+
+/**
+ * Classify why an `st` value could not be decoded without inspecting body text.
+ */
+export function classifySectionTargetLinkDecodeFailure(
+  value: string | null | undefined
+): SectionTargetLinkDecodeFailure {
+  if (value === null || value === undefined || value.length < 1) {
+    return "missing";
+  }
+  if (value.length > SECTION_TARGET_LINK_MAX_ENCODED_CHARS) {
+    return "oversized";
+  }
+  const dot = value.indexOf(".");
+  if (dot < 1) {
+    return "malformed";
+  }
+  const version = value.slice(0, dot);
+  if (version !== SECTION_TARGET_LINK_VERSION) {
+    return "unsupported_version";
+  }
+  return "malformed";
+}

package/src/core/section-target-resolve.ts

@@ -0,0 +1,351 @@
+/**
+ * Conservative SectionTargetV1 resolution.
+ * Private helper module — import public API from `./sections`.
+ *
+ * @module src/core/section-target-resolve
+ */
+
+import {
+  extractSectionRecords,
+  lineStartOffsets,
+  normalizeHeadingTitle,
+  type DocumentSection,
+  type SectionRecord,
+} from "./section-parse";
+import {
+  fingerprintSourceContent,
+  withQuotes,
+  type QuotedSectionRecord,
+  type SectionTargetV1,
+} from "./section-target";
+
+export type SectionResolutionStatus =
+  | "exact"
+  | "recovered"
+  | "ambiguous"
+  | "stale"
+  | "missing";
+
+export interface SectionResolutionCandidate {
+  anchor: string;
+  line: number;
+  title: string;
+  headingPath: string[];
+  occurrence: number;
+}
+
+export interface SectionResolution {
+  status: SectionResolutionStatus;
+  target: SectionTargetV1;
+  currentFingerprint: string;
+  /** Present only when status is exact or recovered (navigable). */
+  section?: DocumentSection & { endLine: number };
+  /** Safe candidate list when status is ambiguous. */
+  candidates?: SectionResolutionCandidate[];
+  reason?: string;
+}
+
+const pathsEqual = (
+  left: readonly string[],
+  right: readonly string[]
+): boolean =>
+  left.length === right.length &&
+  left.every(
+    (value, index) => value === normalizeHeadingTitle(right[index] ?? "")
+  );
+
+const sectionSpan = (
+  content: string,
+  record: SectionRecord,
+  starts: readonly number[]
+): { start: number; end: number } => {
+  const start = record.titleStartOffset;
+  const end =
+    record.endLine >= starts.length
+      ? content.length
+      : (starts[record.endLine] ?? content.length);
+  return { start, end };
+};
+
+const quoteMatchesAt = (
+  content: string,
+  quote: SectionTargetV1["quote"]
+): number[] => {
+  if (!quote.exact) return [];
+  const hits: number[] = [];
+  let from = 0;
+  while (from <= content.length) {
+    const index = content.indexOf(quote.exact, from);
+    if (index < 0) break;
+    const prefixOk = content
+      .slice(Math.max(0, index - quote.prefix.length), index)
+      .endsWith(quote.prefix);
+    const suffixOk = content
+      .slice(index + quote.exact.length)
+      .startsWith(quote.suffix);
+    if (prefixOk && suffixOk) hits.push(index);
+    from = index + 1;
+  }
+  return hits;
+};
+
+const innermostRecordAt = (
+  records: readonly QuotedSectionRecord[],
+  offset: number,
+  content: string,
+  starts: readonly number[]
+): QuotedSectionRecord | null => {
+  let best: QuotedSectionRecord | null = null;
+  for (const record of records) {
+    const span = sectionSpan(content, record, starts);
+    if (offset < span.start || offset >= span.end) continue;
+    if (
+      !best ||
+      record.titleStartOffset > best.titleStartOffset ||
+      (record.titleStartOffset === best.titleStartOffset &&
+        record.section.level > best.section.level)
+    ) {
+      best = record;
+    }
+  }
+  return best;
+};
+
+const sectionContainsExact = (
+  content: string,
+  record: SectionRecord,
+  exact: string,
+  starts: readonly number[]
+): boolean => {
+  if (!exact) return false;
+  const span = sectionSpan(content, record, starts);
+  return content.slice(span.start, span.end).includes(exact);
+};
+
+const findQuoteMatches = (
+  content: string,
+  records: readonly QuotedSectionRecord[],
+  quote: SectionTargetV1["quote"]
+): QuotedSectionRecord[] => {
+  const starts = lineStartOffsets(content);
+  const matched = new Map<string, QuotedSectionRecord>();
+  for (const offset of quoteMatchesAt(content, quote)) {
+    const owner = innermostRecordAt(records, offset, content, starts);
+    if (owner) matched.set(owner.section.anchor, owner);
+  }
+  // Also accept exact structural quote equality for the record itself.
+  for (const record of records) {
+    if (
+      record.quote.exact === quote.exact &&
+      record.quote.prefix === quote.prefix &&
+      record.quote.suffix === quote.suffix
+    ) {
+      matched.set(record.section.anchor, record);
+    }
+  }
+  return [...matched.values()];
+};
+
+const toCandidate = (
+  record: QuotedSectionRecord
+): SectionResolutionCandidate => ({
+  anchor: record.section.anchor,
+  line: record.section.line,
+  title: record.section.title,
+  headingPath: [...record.headingPath],
+  occurrence: record.occurrence,
+});
+
+const navigable = (
+  status: "exact" | "recovered",
+  target: SectionTargetV1,
+  currentFingerprint: string,
+  record: QuotedSectionRecord
+): SectionResolution => ({
+  status,
+  target,
+  currentFingerprint,
+  section: {
+    ...record.section,
+    endLine: record.endLine,
+  },
+});
+
+export interface ResolveSectionTargetInput {
+  content: string;
+  target: SectionTargetV1;
+  /** When set, a URI mismatch yields missing (wrong document). */
+  uri?: string;
+}
+
+/**
+ * Conservatively resolve a SectionTargetV1 against current document content.
+ * Never silently navigates ambiguous or stale evidence.
+ */
+export async function resolveSectionTarget(
+  input: ResolveSectionTargetInput
+): Promise<SectionResolution> {
+  const { target } = input;
+  const currentFingerprint = await fingerprintSourceContent(input.content);
+
+  if (input.uri !== undefined && input.uri !== target.document.uri) {
+    return {
+      status: "missing",
+      target,
+      currentFingerprint,
+      reason: "document_uri_mismatch",
+    };
+  }
+
+  const records = withQuotes(
+    input.content,
+    extractSectionRecords(input.content)
+  );
+  const sameRevision = currentFingerprint === target.sourceFingerprint;
+
+  // Stage 1: same-revision structural match (anchor, else path+occurrence).
+  if (sameRevision) {
+    const byAnchor = records.filter(
+      (entry) => entry.section.anchor === target.anchor
+    );
+    if (byAnchor.length === 1 && byAnchor[0]) {
+      return navigable("exact", target, currentFingerprint, byAnchor[0]);
+    }
+    const byPath = records.filter(
+      (entry) =>
+        pathsEqual(entry.headingPath, target.headingPath) &&
+        entry.occurrence === target.occurrence
+    );
+    if (byPath.length === 1 && byPath[0]) {
+      return navigable("exact", target, currentFingerprint, byPath[0]);
+    }
+    if (byAnchor.length > 1 || byPath.length > 1) {
+      return {
+        status: "ambiguous",
+        target,
+        currentFingerprint,
+        candidates: [...byAnchor, ...byPath]
+          .filter(
+            (entry, index, all) =>
+              all.findIndex(
+                (candidate) => candidate.section.anchor === entry.section.anchor
+              ) === index
+          )
+          .map(toCandidate),
+        reason: "same_revision_multiple_matches",
+      };
+    }
+  }
+
+  // Quote matches are computed once; non-unique quotes fail closed as ambiguous.
+  const starts = lineStartOffsets(input.content);
+  const quoteMatches = findQuoteMatches(input.content, records, target.quote);
+  if (quoteMatches.length > 1) {
+    return {
+      status: "ambiguous",
+      target,
+      currentFingerprint,
+      candidates: quoteMatches.map(toCandidate),
+      reason: "quote_context_multiple_matches",
+    };
+  }
+
+  // Stage 2: exact heading path/occurrence with quote evidence in-span.
+  const pathMatches = records.filter(
+    (entry) =>
+      pathsEqual(entry.headingPath, target.headingPath) &&
+      entry.occurrence === target.occurrence
+  );
+  if (pathMatches.length === 1 && pathMatches[0]) {
+    const candidate = pathMatches[0];
+    const quoteOk =
+      sectionContainsExact(
+        input.content,
+        candidate,
+        target.quote.exact,
+        starts
+      ) ||
+      (quoteMatches.length === 1 &&
+        quoteMatches[0]?.section.anchor === candidate.section.anchor);
+    if (quoteOk) {
+      return navigable(
+        sameRevision ? "exact" : "recovered",
+        target,
+        currentFingerprint,
+        candidate
+      );
+    }
+  } else if (pathMatches.length > 1) {
+    return {
+      status: "ambiguous",
+      target,
+      currentFingerprint,
+      candidates: pathMatches.map(toCandidate),
+      reason: "path_occurrence_multiple_matches",
+    };
+  }
+
+  // Stage 3: unique quote + context recovery.
+  if (quoteMatches.length === 1 && quoteMatches[0]) {
+    return navigable(
+      sameRevision ? "exact" : "recovered",
+      target,
+      currentFingerprint,
+      quoteMatches[0]
+    );
+  }
+
+  // Fail closed: partial structural residue without unique recovery → stale;
+  // no residue → missing.
+  const pathResidue = records.some((entry) =>
+    pathsEqual(entry.headingPath, target.headingPath)
+  );
+  const titleResidue = records.some(
+    (entry) =>
+      normalizeHeadingTitle(entry.section.title) ===
+      normalizeHeadingTitle(target.headingPath.at(-1) ?? "")
+  );
+  const anchorResidue = records.some(
+    (entry) => entry.section.anchor === target.anchor
+  );
+
+  if (!sameRevision && (pathResidue || titleResidue || anchorResidue)) {
+    return {
+      status: "stale",
+      target,
+      currentFingerprint,
+      reason: "fingerprint_mismatch_without_unique_recovery",
+      candidates: records
+        .filter(
+          (entry) =>
+            pathsEqual(entry.headingPath, target.headingPath) ||
+            entry.section.anchor === target.anchor ||
+            normalizeHeadingTitle(entry.section.title) ===
+              normalizeHeadingTitle(target.headingPath.at(-1) ?? "")
+        )
+        .map(toCandidate),
+    };
+  }
+
+  return {
+    status: "missing",
+    target,
+    currentFingerprint,
+    reason: sameRevision
+      ? "section_not_found_same_revision"
+      : "section_not_found",
+  };
+}
+
+/** True when the resolution may safely navigate to `section`. */
+export function isNavigableSectionResolution(
+  resolution: SectionResolution
+): resolution is SectionResolution & {
+  status: "exact" | "recovered";
+  section: DocumentSection & { endLine: number };
+} {
+  return (
+    (resolution.status === "exact" || resolution.status === "recovered") &&
+    resolution.section !== undefined
+  );
+}