@gmickel/gno 1.30.7 → 1.32.0

package/src/core/link-inventory-types.ts

@@ -0,0 +1,47 @@
+/**
+ * Shared inventory token types and caps for reference-safe refactors.
+ *
+ * @module src/core/link-inventory-types
+ */
+
+import type {
+  FileRefactorReasonCode,
+  FileRefactorReferenceClassification,
+  FileRefactorReferenceKind,
+} from "./file-refactor-contract";
+import type { LinkEncodingStyle } from "./link-destination-parse";
+
+/** Hard caps — callers must fail closed when truncated. */
+export const LINK_INVENTORY_CAPS = {
+  maxContentChars: 1_000_000,
+  maxTokensPerDocument: 2_000,
+} as const;
+
+export interface LinkInventoryToken {
+  kind: FileRefactorReferenceKind;
+  classification?: FileRefactorReferenceClassification;
+  reasonCode?: FileRefactorReasonCode;
+  raw: string;
+  originalDestination: string;
+  destinationStart: number;
+  destinationEnd: number;
+  startOffset: number;
+  endOffset: number;
+  startLine: number;
+  startCol: number;
+  endLine: number;
+  endCol: number;
+  targetRef: string;
+  targetAnchor?: string;
+  targetCollection?: string;
+  targetQuery?: string;
+  hadLeadingDotSlash: boolean;
+  encodingStyle: LinkEncodingStyle;
+}
+
+export interface LinkInventoryResult {
+  tokens: LinkInventoryToken[];
+  truncated: boolean;
+  /** True when destination spans overlap after inventory. */
+  overlapping: boolean;
+}

package/src/core/link-inventory.ts

@@ -0,0 +1,182 @@
+/**
+ * Parser-backed link inventory for reference-safe file refactors.
+ *
+ * Produces exact UTF-16 destination token spans plus conservative opaque /
+ * malformed detections. Does not mutate disk or change parseLinks behavior.
+ *
+ * @module src/core/link-inventory
+ */
+
+import type { ExcludedRange } from "../ingestion/strip";
+import type {
+  LinkInventoryResult,
+  LinkInventoryToken,
+} from "./link-inventory-types";
+
+import { getExcludedRanges } from "../ingestion/strip";
+import {
+  inventoryInlineMarkdown,
+  inventoryReferenceDefinitions,
+  inventoryWikiLinks,
+} from "./link-inventory-markdown";
+import {
+  buildLineOffsets,
+  inventoryEmbeds,
+  inventoryHtmlHrefs,
+  inventoryMalformedWiki,
+} from "./link-inventory-opaque";
+import { LINK_INVENTORY_CAPS } from "./link-inventory-types";
+
+export {
+  LINK_INVENTORY_CAPS,
+  type LinkInventoryResult,
+  type LinkInventoryToken,
+} from "./link-inventory-types";
+export {
+  buildContentPrefilterNeedles,
+  buildSourceRelevanceKeys,
+  isRelevantDestination,
+} from "./link-relevance";
+
+/**
+ * Destination identity for inventory dedupe.
+ * Kind is intentionally omitted so identical spans from overlapping scanners
+ * collapse to the first (scanner-precedence) token.
+ */
+export function inventoryDestinationKey(token: {
+  destinationStart: number;
+  destinationEnd: number;
+  originalDestination: string;
+}): string {
+  return `${token.destinationStart}:${token.destinationEnd}:${token.originalDestination}`;
+}
+
+/**
+ * Dedupe identical destination spans (regardless of scanner kind) and detect
+ * true partial overlaps. First token wins — callers should push in scanner order.
+ */
+export function dedupeInventoryDestinationTokens(
+  tokens: LinkInventoryToken[]
+): {
+  tokens: LinkInventoryToken[];
+  overlapping: boolean;
+} {
+  const seen = new Set<string>();
+  const unique: LinkInventoryToken[] = [];
+  for (const token of tokens) {
+    const key = inventoryDestinationKey(token);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    unique.push(token);
+  }
+  unique.sort((a, b) => {
+    if (a.destinationStart !== b.destinationStart) {
+      return a.destinationStart - b.destinationStart;
+    }
+    return a.destinationEnd - b.destinationEnd;
+  });
+  let overlapping = false;
+  for (let i = 1; i < unique.length; i += 1) {
+    const prev = unique[i - 1]!;
+    const cur = unique[i]!;
+    if (cur.destinationStart < prev.destinationEnd) {
+      overlapping = true;
+      break;
+    }
+  }
+  unique.sort((a, b) => {
+    if (a.startLine !== b.startLine) return a.startLine - b.startLine;
+    if (a.startCol !== b.startCol) return a.startCol - b.startCol;
+    return a.destinationStart - b.destinationStart;
+  });
+  return { tokens: unique, overlapping };
+}
+
+/**
+ * Inventory all relevant rewrite / opaque reference tokens in one document.
+ */
+export function inventoryDocumentLinks(
+  markdown: string,
+  options: {
+    sourceKeys: ReadonlySet<string>;
+    excludedRanges?: ExcludedRange[];
+  }
+): LinkInventoryResult {
+  const truncated = { value: false };
+  if (markdown.length > LINK_INVENTORY_CAPS.maxContentChars) {
+    return { tokens: [], truncated: true, overlapping: false };
+  }
+
+  const excluded = options.excludedRanges ?? getExcludedRanges(markdown);
+  const lineOffsets = buildLineOffsets(markdown);
+  const tokens: LinkInventoryToken[] = [];
+  const consumed = new Set<number>();
+  const sourceKeys = options.sourceKeys;
+
+  const ok =
+    inventoryEmbeds(
+      markdown,
+      lineOffsets,
+      sourceKeys,
+      excluded,
+      tokens,
+      truncated,
+      consumed
+    ) &&
+    inventoryHtmlHrefs(
+      markdown,
+      lineOffsets,
+      sourceKeys,
+      excluded,
+      tokens,
+      truncated,
+      consumed
+    ) &&
+    inventoryMalformedWiki(
+      markdown,
+      lineOffsets,
+      sourceKeys,
+      excluded,
+      tokens,
+      truncated,
+      consumed
+    ) &&
+    inventoryWikiLinks(
+      markdown,
+      lineOffsets,
+      sourceKeys,
+      excluded,
+      tokens,
+      truncated,
+      consumed
+    ) &&
+    inventoryReferenceDefinitions(
+      markdown,
+      lineOffsets,
+      sourceKeys,
+      excluded,
+      tokens,
+      truncated,
+      consumed
+    ) &&
+    inventoryInlineMarkdown(
+      markdown,
+      lineOffsets,
+      sourceKeys,
+      excluded,
+      tokens,
+      truncated,
+      consumed
+    );
+
+  if (!ok) {
+    return { tokens, truncated: true, overlapping: false };
+  }
+
+  const finalized = dedupeInventoryDestinationTokens(tokens);
+  return {
+    tokens: finalized.tokens,
+    truncated: truncated.value,
+    overlapping: finalized.overlapping,
+  };
+}

package/src/core/link-relevance.ts

@@ -0,0 +1,150 @@
+/**
+ * Conservative destination relevance for reference-safe file refactors.
+ *
+ * Uses exact token/path/basename equality after stripping query/fragment,
+ * safe decoding, NFC normalization, and syntax delimiters. No fuzzy
+ * substring matching — unrelated `other-note.md` must not match `note.md`.
+ *
+ * @module src/core/link-relevance
+ */
+
+// node:path/posix — no Bun path utils
+import { posix as pathPosix } from "node:path";
+
+import {
+  stripAngleBracketDestination,
+  unescapeCommonMarkDestination,
+} from "./link-destination-parse";
+import { normalizeWikiName, stripWikiMdExt } from "./links";
+
+function safeDecodeForRelevance(value: string): string {
+  return value
+    .replaceAll("%20", " ")
+    .replaceAll("%28", "(")
+    .replaceAll("%29", ")");
+}
+
+function stripQueryAndFragment(value: string): string {
+  const hash = value.indexOf("#");
+  const withoutHash = hash >= 0 ? value.slice(0, hash) : value;
+  const query = withoutHash.indexOf("?");
+  return query >= 0 ? withoutHash.slice(0, query) : withoutHash;
+}
+
+function addKey(keys: Set<string>, value: string): void {
+  const trimmed = value.trim();
+  if (!trimmed) return;
+  keys.add(normalizeWikiName(trimmed));
+  keys.add(normalizeWikiName(stripWikiMdExt(trimmed)));
+  keys.add(trimmed.toLowerCase());
+  keys.add(stripWikiMdExt(trimmed).toLowerCase());
+  const base = pathPosix.basename(trimmed);
+  keys.add(normalizeWikiName(base));
+  keys.add(normalizeWikiName(stripWikiMdExt(base)));
+  keys.add(base.toLowerCase());
+  keys.add(stripWikiMdExt(base).toLowerCase());
+}
+
+/** Build lookup keys used to decide whether a destination is about the source. */
+export function buildSourceRelevanceKeys(input: {
+  relPath: string;
+  title: string | null | undefined;
+}): Set<string> {
+  const keys = new Set<string>();
+  addKey(keys, input.relPath);
+  addKey(keys, input.relPath.normalize("NFC"));
+  addKey(keys, input.relPath.normalize("NFD"));
+  if (input.title) {
+    addKey(keys, input.title);
+    addKey(keys, input.title.normalize("NFC"));
+    addKey(keys, input.title.normalize("NFD"));
+  }
+  return keys;
+}
+
+/**
+ * Normalize a destination token into candidate equality keys (exact only).
+ */
+export function destinationRelevanceCandidates(destination: string): string[] {
+  const trimmed = destination.trim();
+  if (!trimmed) return [];
+
+  const { path: withoutAngles } = stripAngleBracketDestination(trimmed);
+  const unescaped = unescapeCommonMarkDestination(withoutAngles);
+  const withoutQueryFrag = stripQueryAndFragment(unescaped);
+  const decoded = safeDecodeForRelevance(withoutQueryFrag);
+
+  const forms = [
+    trimmed,
+    withoutAngles,
+    unescaped,
+    withoutQueryFrag,
+    decoded,
+    withoutQueryFrag.normalize("NFC"),
+    withoutQueryFrag.normalize("NFD"),
+    decoded.normalize("NFC"),
+    decoded.normalize("NFD"),
+  ];
+
+  const keys = new Set<string>();
+  for (const form of forms) {
+    addKey(keys, form);
+  }
+  return [...keys];
+}
+
+/**
+ * Exact-token relevance: true only when a normalized destination key equals a
+ * source key. Malformed prefixes may still match when the prefix token itself
+ * equals a source key (bounded exact equality, not substring).
+ */
+export function isRelevantDestination(
+  destination: string,
+  sourceKeys: ReadonlySet<string>
+): boolean {
+  const candidates = destinationRelevanceCandidates(destination);
+  return candidates.some((key) => sourceKeys.has(key));
+}
+
+/**
+ * Content-prefilter needle strings for SQL LIKE (caller escapes wildcards).
+ * Conservative: source path/title identities and common escape encodings.
+ */
+export function buildContentPrefilterNeedles(input: {
+  relPath: string;
+  title: string | null | undefined;
+}): string[] {
+  const needles = new Set<string>();
+  const add = (value: string): void => {
+    const trimmed = value.trim();
+    if (!trimmed || trimmed.length < 2) return;
+    needles.add(trimmed);
+    needles.add(trimmed.normalize("NFC"));
+    needles.add(trimmed.normalize("NFD"));
+    needles.add(trimmed.replaceAll(" ", "%20"));
+    needles.add(
+      trimmed
+        .replaceAll(" ", "%20")
+        .replaceAll("(", "%28")
+        .replaceAll(")", "%29")
+    );
+    needles.add(trimmed.replaceAll("(", "%28").replaceAll(")", "%29"));
+    needles.add(
+      trimmed
+        .replaceAll(" ", "\\ ")
+        .replaceAll("(", "\\(")
+        .replaceAll(")", "\\)")
+    );
+    needles.add(trimmed.replaceAll("(", "\\(").replaceAll(")", "\\)"));
+  };
+
+  add(input.relPath);
+  add(pathPosix.basename(input.relPath));
+  add(stripWikiMdExt(pathPosix.basename(input.relPath)));
+  add(stripWikiMdExt(input.relPath));
+  if (input.title) {
+    add(input.title);
+    add(`${input.title}.md`);
+  }
+  return [...needles].sort((a, b) => (a < b ? -1 : a > b ? 1 : 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;
+}