@pathmx/core 0.5.0

package/source/markdown/blocks.ts

@@ -0,0 +1,46 @@
+import { isFenceClose, matchFenceOpen } from "./fences.ts"
+
+function isBlank(line: string | undefined) {
+  return !line?.trim()
+}
+
+/**
+ * Split ordinary PathMX Markdown into blank-line-isolated Blocks. A thematic
+ * divider inside a fenced code example remains authored content, not a Block
+ * boundary.
+ */
+export function splitMarkdownBlocks(markdown: string) {
+  const lines = markdown.split(/\r?\n/)
+  const blocks: string[] = []
+  let blockStart = 0
+  let marker: string | undefined
+
+  for (let index = 0; index < lines.length; index++) {
+    const line = lines[index] ?? ""
+
+    if (marker) {
+      if (isFenceClose(line, marker)) marker = undefined
+      continue
+    }
+
+    const fence = matchFenceOpen(line)
+    if (fence) {
+      marker = fence.marker
+      continue
+    }
+
+    if (
+      line.trim() !== "---" ||
+      !isBlank(lines[index - 1]) ||
+      !isBlank(lines[index + 1])
+    )
+      continue
+    const block = lines.slice(blockStart, index).join("\n").trim()
+    if (block) blocks.push(block)
+    blockStart = index + 1
+  }
+
+  const block = lines.slice(blockStart).join("\n").trim()
+  if (block) blocks.push(block)
+  return blocks
+}

package/source/markdown/comments.ts

@@ -0,0 +1,32 @@
+export type HtmlCommentState = Readonly<{
+  line: string
+  inComment: boolean
+}>
+
+/** Remove non-rendered HTML comments while preserving visible text around them. */
+export function withoutHtmlComments(
+  line: string,
+  startsInComment: boolean,
+): HtmlCommentState {
+  let inComment = startsInComment
+  let visible = ""
+  let cursor = 0
+  while (cursor < line.length) {
+    if (inComment) {
+      const end = line.indexOf("-->", cursor)
+      if (end === -1) return { line: visible, inComment }
+      inComment = false
+      cursor = end + 3
+      continue
+    }
+    const start = line.indexOf("<!--", cursor)
+    if (start === -1) {
+      visible += line.slice(cursor)
+      break
+    }
+    visible += line.slice(cursor, start)
+    inComment = true
+    cursor = start + 4
+  }
+  return { line: visible, inComment }
+}

package/source/markdown/fences.ts

@@ -0,0 +1,67 @@
+export type MarkdownCodeFence = {
+  lang: string
+  info: string
+  body: string
+}
+
+export type FenceOpen = {
+  indent: string
+  marker: string
+  /** The trimmed info string after the fence marker, e.g. `js no-copy`. */
+  info: string
+}
+
+const FENCE_LINE = /^(\s*)([`~]{3,})(.*)$/
+
+/** Match a fence opening line (``` / ~~~), or `undefined` for ordinary text. */
+export function matchFenceOpen(line: string): FenceOpen | undefined {
+  const match = line.match(FENCE_LINE)
+  if (!match) return
+  return { indent: match[1]!, marker: match[2]!, info: match[3]!.trim() }
+}
+
+/** A closing fence uses the same character, is at least as long, and carries no info. */
+export function isFenceClose(line: string, marker: string) {
+  const match = line.match(FENCE_LINE)
+  return Boolean(
+    match &&
+      match[2]![0] === marker[0] &&
+      match[2]!.length >= marker.length &&
+      !match[3]!.trim(),
+  )
+}
+
+/**
+ * Collect fenced code blocks (``` / ~~~) in source order. `lang` is the first
+ * info-string word; `body` is the interior text, untrimmed.
+ */
+export function parseCodeFences(markdown: string): MarkdownCodeFence[] {
+  const fences: MarkdownCodeFence[] = []
+  const lines = markdown.split(/\r?\n/)
+  let open:
+    | { marker: string; lang: string; info: string; start: number }
+    | undefined
+
+  for (let index = 0; index < lines.length; index++) {
+    const line = lines[index] ?? ""
+
+    if (open) {
+      if (isFenceClose(line, open.marker)) {
+        fences.push({
+          lang: open.lang,
+          info: open.info,
+          body: lines.slice(open.start, index).join("\n"),
+        })
+        open = undefined
+      }
+      continue
+    }
+
+    const fence = matchFenceOpen(line)
+    if (!fence) continue
+    const lang = fence.info.split(/\s+/, 1)[0] ?? ""
+    open = { marker: fence.marker, lang, info: fence.info, start: index + 1 }
+  }
+
+  return fences
+}

package/source/markdown/headings.ts

@@ -0,0 +1,88 @@
+import { isFenceClose, matchFenceOpen } from "./fences.ts"
+
+export type MarkdownHeading = {
+  depth: number
+  id: string
+  text: string
+}
+
+function plainHeadingText(markdown: string) {
+  return markdown
+    .replace(/!\[([^\]]*)\]\([^)]*\)/g, "$1")
+    .replace(/\[([^\]]+)\]\([^)]*\)/g, "$1")
+    .replace(/`([^`]*)`/g, "$1")
+    .replace(/<[^>]*>/g, "")
+    .replace(/\\([\\`*_{}\[\]()#+.!-])/g, "$1")
+    .replace(/[\*_~]/g, "")
+    .trim()
+}
+
+/** Match `Bun.markdown.html(..., { headings: { ids: true } })` slugs. */
+function slugify(text: string) {
+  return text
+    .toLowerCase()
+    .replace(/[^a-z0-9\s-]/g, "")
+    .trim()
+    .replace(/[\s-]+/g, "-")
+}
+
+function nextHeadingId(text: string, counts: Map<string, number>) {
+  const base = slugify(text)
+  const count = counts.get(base) ?? 0
+  counts.set(base, count + 1)
+  return count === 0 ? base : `${base}-${count}`
+}
+
+/** @internal Parse one already fence-filtered Markdown line. */
+export function headingFromLine(
+  line: string,
+  counts: Map<string, number>,
+): MarkdownHeading | undefined {
+  const match = line.match(/^\s{0,3}(#{1,6})[ \t]+(.+?)(?:[ \t]+#+[ \t]*)?$/)
+  if (!match?.[1] || !match[2]) return
+  const text = plainHeadingText(match[2])
+  if (!text) return
+  return {
+    depth: match[1].length,
+    id: nextHeadingId(text, counts),
+    text,
+  }
+}
+
+/** Reassign heading ids so they are unique across a whole Source. */
+export function assignHeadingIds(
+  headings: readonly MarkdownHeading[],
+): MarkdownHeading[] {
+  const counts = new Map<string, number>()
+  return headings.map((heading) => ({
+    ...heading,
+    id: nextHeadingId(heading.text, counts),
+  }))
+}
+
+/**
+ * Collect ATX headings while leaving examples inside fenced code untouched.
+ * Heading `id`s match `Bun.markdown.html(..., { headings: { ids: true } })`.
+ */
+export function collectHeadings(markdown: string): MarkdownHeading[] {
+  const headings: MarkdownHeading[] = []
+  const counts = new Map<string, number>()
+  let marker: string | undefined
+
+  for (const line of markdown.split(/\r?\n/)) {
+    if (marker) {
+      if (isFenceClose(line, marker)) marker = undefined
+      continue
+    }
+    const fence = matchFenceOpen(line)
+    if (fence) {
+      marker = fence.marker
+      continue
+    }
+
+    const heading = headingFromLine(line, counts)
+    if (heading) headings.push(heading)
+  }
+
+  return headings
+}

package/source/markdown/index.ts

@@ -0,0 +1,34 @@
+export {
+  isExternalHref,
+  parseLinkDirective,
+  parseLinks,
+  rewriteLinks,
+  unlinkLinks,
+  type LinkDirective,
+  type SourceLink,
+  type SourceLinkKind,
+  type SourceLinkType,
+} from "./links.ts"
+export { splitMarkdownBlocks } from "./blocks.ts"
+export {
+  markdownListItemLink,
+  parseMarkdownLists,
+  type MarkdownList,
+  type MarkdownListItem,
+  type MarkdownListLink,
+  type MarkdownListParse,
+  type MarkdownTask,
+} from "./lists.ts"
+export {
+  assignHeadingIds,
+  collectHeadings,
+  type MarkdownHeading,
+} from "./headings.ts"
+export {
+  isFenceClose,
+  matchFenceOpen,
+  parseCodeFences,
+  type FenceOpen,
+  type MarkdownCodeFence,
+} from "./fences.ts"
+export { cleanInlineText, firstParagraph } from "./text.ts"

package/source/markdown/inline-code.ts

@@ -0,0 +1,6 @@
+const INLINE_CODE = /(`+)([\s\S]*?)\1/g
+
+/** @internal Preserve offsets while hiding inline code from syntax indexes. */
+export function maskInlineCode(markdown: string) {
+  return markdown.replace(INLINE_CODE, (code) => " ".repeat(code.length))
+}

package/source/markdown/links.ts

@@ -0,0 +1,326 @@
+import { maskInlineCode } from "./inline-code.ts"
+
+export type SourceLinkType =
+  "source" | "asset" | "external" | "fragment" | "actor-relative" | "unresolved"
+
+export type SourceLinkKind = "inline" | "definition" | "html" | "image"
+
+export type LinkDirective = {
+  name: string
+  qualifiers: string[]
+}
+
+export type SourceLink = {
+  href: string
+  type: SourceLinkType
+  kind: SourceLinkKind
+  label?: string
+  directive?: LinkDirective
+  targetPath?: string
+  fragment?: string
+}
+
+// This is deliberately source-local syntax indexing, not Markdown AST parsing
+// or PathMX graph resolution. Classification stays unresolved until
+// Graph.rebuild().
+const INTERPOLATION_TOKEN = String.raw`\{\{\s*[A-Za-z_][\w-]*(?:\.[A-Za-z_][\w-]*)*\s*\}\}`
+const INLINE_DESTINATION = String.raw`(?:(?:${INTERPOLATION_TOKEN})|[^\s)])+`
+const INLINE_LINK = new RegExp(
+  String.raw`(!?)\[([^\]]*)\]\(\s*(?:<([^>\r\n]+)>|(${INLINE_DESTINATION}))`,
+  "g",
+)
+const HTML_ANCHOR = /<a\b[^>]*\bhref\s*=\s*(?:"([^"]+)"|'([^']+)'|([^\s>]+))/gi
+const DEFINITION =
+  /^[ \t]{0,3}\[([^\]]+)\]:[ \t]+(?:<([^>\r\n]+)>|(\S+))(?:[ \t]+(?:"([^"]*)"|'([^']*)'|\(([^)]*)\)))?[ \t]*$/gm
+const DIRECTIVE = /^@([A-Za-z][\w-]*)((?:\.[A-Za-z][\w-]*)*)(?:\s+([\s\S]*))?$/
+
+const EXTERNAL_HREF = /^[a-z][a-z\d+.-]*:/i
+
+/** Protocol or protocol-relative destinations leave the current PathMX site. */
+export function isExternalHref(href: string) {
+  const normalized = href.trim()
+  return EXTERNAL_HREF.test(normalized) || normalized.startsWith("//")
+}
+
+/** @internal Structural relationships target exact authored Markdown files. */
+export function isExactMarkdownSourceHref(value: string) {
+  const href = value.trim()
+  return Boolean(
+    href &&
+    href.endsWith(".md") &&
+    !href.includes("?") &&
+    !href.includes("#") &&
+    !href.includes("\\") &&
+    !href.startsWith("//") &&
+    !href.startsWith("~/") &&
+    !/^[a-z][a-z\d+.-]*:/i.test(href),
+  )
+}
+
+/** @internal Split one authored link label into its directive and visible text. */
+export function parseDirectiveLabel(raw: string | undefined): {
+  label?: string
+  directive?: LinkDirective
+} {
+  const text = raw?.trim()
+  if (!text) return {}
+  const match = text.match(DIRECTIVE)
+  if (!match) return { label: text }
+  const qualifiers = match[2]
+    ? match[2].slice(1).split(".").filter(Boolean)
+    : []
+  const rest = match[3]?.trim()
+  return {
+    directive: { name: match[1]!, qualifiers },
+    ...(rest ? { label: rest } : {}),
+  }
+}
+
+function addLink(
+  links: SourceLink[],
+  seen: Set<string>,
+  href: string | undefined,
+  kind: SourceLinkKind,
+  rawLabel?: string,
+) {
+  const dest = href?.trim()
+  if (!dest) return
+  if (kind !== "definition") {
+    const key = `${kind}:${dest}`
+    if (seen.has(key)) return
+    seen.add(key)
+  }
+  const { label, directive } = parseDirectiveLabel(rawLabel)
+  links.push({
+    href: dest,
+    type: "unresolved",
+    kind,
+    ...(label ? { label } : {}),
+    ...(directive ? { directive } : {}),
+  })
+}
+
+/** @internal Extract links from ordered, already fence-filtered fragments. */
+export function parseLinkFragments(fragments: readonly string[]): SourceLink[] {
+  const links: SourceLink[] = []
+  const seen = new Set<string>()
+  for (const fragment of fragments) {
+    const markdown = maskInlineCode(fragment)
+    const found: Array<{
+      index: number
+      href?: string
+      kind: SourceLinkKind
+      label?: string
+    }> = []
+
+    for (const match of markdown.matchAll(DEFINITION)) {
+      found.push({
+        index: match.index ?? 0,
+        href: match[2] ?? match[3],
+        kind: "definition",
+        label: match[1],
+      })
+    }
+    for (const match of markdown.matchAll(INLINE_LINK)) {
+      found.push({
+        index: match.index ?? 0,
+        href: match[3] ?? match[4],
+        kind: match[1] === "!" ? "image" : "inline",
+        label: match[2],
+      })
+    }
+    for (const match of markdown.matchAll(HTML_ANCHOR)) {
+      found.push({
+        index: match.index ?? 0,
+        href: match[1] ?? match[2] ?? match[3],
+        kind: "html",
+      })
+    }
+
+    found.sort((a, b) => a.index - b.index)
+    for (const item of found) {
+      addLink(links, seen, item.href, item.kind, item.label)
+    }
+  }
+  return links
+}
+
+/**
+ * Return ordered link destinations from Markdown. Inline and HTML hrefs are
+ * de-duplicated; each reference definition is kept for authored directives.
+ */
+export function parseVisibleLinks(markdown: string): SourceLink[] {
+  return parseLinkFragments([markdown])
+}
+
+export function parseLinks(markdown: string): SourceLink[] {
+  return parseVisibleLinks(markdown)
+}
+
+/** `@include status` → `{ name: "include", qualifiers: [] }`. Caption is not returned. */
+export function parseLinkDirective(label: string): LinkDirective | undefined {
+  return parseDirectiveLabel(label).directive
+}
+
+function scan(re: RegExp, content: string) {
+  return content.matchAll(new RegExp(re.source, re.flags))
+}
+
+function hrefSpan(
+  match: RegExpMatchArray,
+  href: string,
+  after: string,
+): { start: number; end: number } | undefined {
+  if (match.index == null) return
+  const token = after === "<" ? `<${href}` : href
+  const offset = match[0].indexOf(token, match[0].lastIndexOf(after))
+  if (offset === -1) return
+  const start = match.index + offset + (after === "<" ? 1 : 0)
+  return { start, end: start + href.length }
+}
+
+function inlineHrefSpan(match: RegExpMatchArray) {
+  const href = match[3] ?? match[4]
+  if (!href) return
+  return hrefSpan(match, href, match[3] != null ? "<" : "(")
+}
+
+function htmlHrefSpan(match: RegExpMatchArray) {
+  const href = match[1] ?? match[2] ?? match[3]
+  if (!href || match.index == null) return
+  const eq = match[0].search(/href\s*=/i)
+  if (eq === -1) return
+  let i = match[0].indexOf("=", eq) + 1
+  while (i < match[0].length && /\s/.test(match[0][i]!)) i++
+  if (match[0][i] === '"' || match[0][i] === "'") i++
+  return { start: match.index + i, end: match.index + i + href.length }
+}
+
+function definitionHrefSpan(match: RegExpMatchArray) {
+  const href = match[2] ?? match[3]
+  if (!href) return
+  return hrefSpan(match, href, match[2] != null ? "<" : "]:")
+}
+
+function applyReplacements(
+  content: string,
+  replacements: Array<{ start: number; end: number; text: string }>,
+) {
+  replacements.sort((a, b) => b.start - a.start)
+  let result = content
+  for (const { start, end, text } of replacements) {
+    result = `${result.slice(0, start)}${text}${result.slice(end)}`
+  }
+  return result
+}
+
+function closingParenEnd(content: string, afterHref: number) {
+  let i = afterHref
+  while (i < content.length && (content[i] === " " || content[i] === "\t")) i++
+  const quote = content[i]
+  if (quote === '"' || quote === "'") {
+    i++
+    while (i < content.length && content[i] !== quote) i++
+    if (content[i] === quote) i++
+  } else if (content[i] === "(") {
+    i++
+    while (i < content.length && content[i] !== ")") i++
+    if (content[i] === ")") i++
+  }
+  while (i < content.length && (content[i] === " " || content[i] === "\t")) i++
+  if (content[i] === ")") i++
+  return i
+}
+
+function htmlElementSpan(content: string, match: RegExpMatchArray) {
+  if (match.index == null) return
+  const gt = content.indexOf(">", match.index)
+  if (gt === -1) return
+  if (content[gt - 1] === "/") {
+    return { start: match.index, end: gt + 1, inner: "" }
+  }
+  const close = content.toLowerCase().indexOf("</a>", gt + 1)
+  if (close === -1) return
+  return {
+    start: match.index,
+    end: close + 4,
+    inner: content.slice(gt + 1, close),
+  }
+}
+
+function definitionLineSpan(content: string, match: RegExpMatchArray) {
+  if (match.index == null) return
+  let end = match.index + match[0].length
+  if (content[end] === "\r") end++
+  if (content[end] === "\n") end++
+  return { start: match.index, end }
+}
+
+/**
+ * Rewrite every markdown/HTML/definition href whose mapper returns a new value.
+ * Uses the same regexes as `parseLinks` so the rewriter sees the same links.
+ */
+export function rewriteLinks(
+  content: string,
+  mapHref: (href: string) => string | undefined,
+): string {
+  const replacements: Array<{ start: number; end: number; text: string }> = []
+
+  const replace = (
+    href: string | undefined,
+    span: { start: number; end: number } | undefined,
+  ) => {
+    if (!href || !span) return
+    const next = mapHref(href)
+    if (next == null || next === href) return
+    replacements.push({ ...span, text: next })
+  }
+
+  for (const match of scan(INLINE_LINK, content)) {
+    replace(match[3] ?? match[4], inlineHrefSpan(match))
+  }
+  for (const match of scan(HTML_ANCHOR, content)) {
+    replace(match[1] ?? match[2] ?? match[3], htmlHrefSpan(match))
+  }
+  for (const match of scan(DEFINITION, content)) {
+    replace(match[2] ?? match[3], definitionHrefSpan(match))
+  }
+
+  return applyReplacements(content, replacements)
+}
+
+/**
+ * Remove links whose href matches. Inline/image links collapse to their label,
+ * HTML anchors collapse to inner text, and reference-definition lines are deleted.
+ */
+export function unlinkLinks(
+  content: string,
+  shouldUnlink: (href: string) => boolean,
+): string {
+  const replacements: Array<{ start: number; end: number; text: string }> = []
+
+  for (const match of scan(INLINE_LINK, content)) {
+    const href = match[3] ?? match[4]
+    const span = inlineHrefSpan(match)
+    if (!href || !span || match.index == null || !shouldUnlink(href)) continue
+    replacements.push({
+      start: match.index,
+      end: closingParenEnd(content, span.end),
+      text: match[2] ?? "",
+    })
+  }
+  for (const match of scan(HTML_ANCHOR, content)) {
+    const href = match[1] ?? match[2] ?? match[3]
+    const span = htmlElementSpan(content, match)
+    if (!href || !span || !shouldUnlink(href)) continue
+    replacements.push({ ...span, text: span.inner })
+  }
+  for (const match of scan(DEFINITION, content)) {
+    const href = match[2] ?? match[3]
+    const span = definitionLineSpan(content, match)
+    if (!href || !span || !shouldUnlink(href)) continue
+    replacements.push({ ...span, text: "" })
+  }
+
+  return applyReplacements(content, replacements)
+}