sailfork / t3code-github / .repos/ alchemy-effect/ scripts/ jsdoc-blocks.ts

/**
 * Source-mapped JSDoc prose, shared by the API reference generator and the
 * website's dev-time copy editor.
 *
 * The generator renders a resource's JSDoc as a markdown page. With copy
 * markers on:
 *
 * - each prose region (the summary, a section's description, an example's
 *   body) is wrapped in a `<div data-copy="jsdoc:<file>@<comment>#r<n>"
 *   data-copy-format="markdown">` the copy editor edits as markdown source;
 * - each remaining one-line block (section and example titles) ends with a
 *   `<!--copy:jsdoc:<file>@<comment>#<n>-->` marker for inline text edits.
 *
 * Saving re-derives the same regions and blocks from the source file to find
 * what to rewrite, so both sides MUST segment comments with
 * {@link docRegions} and {@link docBlocks}.
 */

export interface DocLine {
  /** The line with its ` * ` prefix removed (what the generator parses). */
  text: string;
  /** Source offset where the raw line (including its ` * ` prefix) starts. */
  lineStart: number;
  /** Source offset where `text` starts. */
  start: number;
  /** Source offset where `text` ends. */
  end: number;
}

/**
 * Splits the `/** ... *\/` comment at `commentStart` into cleaned lines with
 * source offsets. Cleaning matches the generator's historical behavior.
 */
export function docCommentLines(fileText: string, commentStart: number): DocLine[] {
  if (!fileText.startsWith("/*", commentStart)) {
    throw new Error(`No doc comment at offset ${commentStart}`);
  }
  const close = fileText.indexOf("*/", commentStart + 2);
  if (close === -1) throw new Error(`Unterminated doc comment at ${commentStart}`);
  const raw = fileText.slice(commentStart, close + 2);
  const open = /^\/\*\*?/.exec(raw)![0].length;
  const body = raw.slice(open, raw.length - 2);
  const lines: DocLine[] = [];
  let offset = commentStart + open;
  for (const line of body.split("\n")) {
    const prefix = /^\s*\*\s?/.exec(line)?.[0].length ?? 0;
    lines.push({
      text: line.slice(prefix),
      lineStart: offset,
      start: offset + prefix,
      end: offset + line.length,
    });
    offset += line.length + 1;
  }
  return lines;
}

export type DocBlockKind =
  | "paragraph"
  | "listItem"
  | "heading"
  | "proseHeading"
  | "sectionTitle"
  | "exampleTitle";

export interface DocBlock {
  kind: DocBlockKind;
  firstLine: number;
  lastLine: number;
  /** Source range of the block's editable inline markdown. */
  start: number;
  end: number;
}

const FENCE = /^\s*```/;
const PROSE_HEADING = /^(\s*###\s+)(.+?)\s+<!-- api-prose -->\s*$/;
const SECTION = /^(\s*###\s+)(.+?)\s*$/;
const EXAMPLE = /^(\s*\*\*Example:\*\*\s*)(.*?)\s*$/;
const TAG = /^\s*@(\w+)/;
const LIST_ITEM = /^(\s*(?:[-*+]|\d+[.)])\s+)/;
const HEADING = /^(\s*#{1,6}\s+)/;
/** Lines that aren't inline prose: tables, HTML, directives, quotes, rules. */
const NON_PROSE = /^\s*(?:\||<|:::|>|---+\s*$|\*\*\*+\s*$)/;

/**
 * Finds the rendered prose blocks in a comment's lines, mirroring how the
 * generator's `parseJSDoc` routes each line (summary, section description,
 * example body, tag) so only lines that reach the page become blocks.
 */
export function docBlocks(lines: DocLine[]): DocBlock[] {
  const blocks: DocBlock[] = [];
  let sawTag = false;
  let inExample = false;
  let inSectionDesc = false;
  let insideFence = false;
  let open: DocBlock | undefined;

  const close = () => {
    if (open) blocks.push(open);
    open = undefined;
  };
  const single = (kind: DocBlockKind, i: number, from: number, to: number) => {
    close();
    const line = lines[i];
    if (to > from) {
      blocks.push({
        kind,
        firstLine: i,
        lastLine: i,
        start: line.start + from,
        end: line.start + to,
      });
    }
  };

  lines.forEach((line, i) => {
    const text = line.text;
    if (FENCE.test(text)) {
      insideFence = !insideFence;
      close();
      return;
    }
    if (insideFence) return;

    const prose = PROSE_HEADING.exec(text);
    if (prose) {
      if (!sawTag) single("proseHeading", i, prose[1].length, prose[1].length + prose[2].length);
      else close();
      return;
    }
    const section = SECTION.exec(text);
    if (section) {
      sawTag = true;
      inExample = false;
      inSectionDesc = true;
      single("sectionTitle", i, section[1].length, section[1].length + section[2].length);
      return;
    }
    const example = EXAMPLE.exec(text);
    if (example) {
      sawTag = true;
      inSectionDesc = false;
      inExample = true;
      single("exampleTitle", i, example[1].length, example[1].length + example[2].length);
      return;
    }
    const tag = TAG.exec(text);
    if (tag) {
      sawTag = true;
      if (tag[1] === "section") {
        inExample = false;
        inSectionDesc = true;
      } else if (tag[1] === "example") {
        inSectionDesc = false;
        inExample = true;
      }
      close();
      return;
    }

    const rendered = !sawTag || (!inExample && inSectionDesc);
    if (!rendered || text.trim() === "" || NON_PROSE.test(text)) {
      close();
      return;
    }

    const trimmedEnd = text.trimEnd().length;
    const heading = HEADING.exec(text);
    if (heading) {
      single("heading", i, heading[1].length, trimmedEnd);
      return;
    }
    const item = LIST_ITEM.exec(text);
    if (item) {
      close();
      open = {
        kind: "listItem",
        firstLine: i,
        lastLine: i,
        start: line.start + item[1].length,
        end: line.start + trimmedEnd,
      };
      return;
    }
    if (open) {
      open.lastLine = i;
      open.end = line.start + trimmedEnd;
      return;
    }
    const indent = text.length - text.trimStart().length;
    open = {
      kind: "paragraph",
      firstLine: i,
      lastLine: i,
      start: line.start + indent,
      end: line.start + trimmedEnd,
    };
  });
  close();
  return blocks;
}

// ── prose regions ─────────────────────────────────────────────────────────

export type DocRegionKind = "summary" | "sectionDescription" | "exampleBody";

export interface DocRegion {
  kind: DocRegionKind;
  /** First and last content line; `lastLine < firstLine` for an empty region. */
  firstLine: number;
  lastLine: number;
  /** For an empty region, the line new content is inserted after. */
  anchorLine: number;
  /** False when the region shares a line with the comment's delimiters. */
  editable: boolean;
}

type Route = "summary" | "sectionDescription" | "exampleBody" | "structural";

/**
 * Finds the prose regions in a comment's lines: runs of lines the generator
 * routes into one rendered chunk (summary, section description, example
 * body), trimmed of blank edge lines. A section title with no description
 * yields an empty region so a description can be added.
 */
export function docRegions(lines: DocLine[]): DocRegion[] {
  const routes: Route[] = [];
  let sawTag = false;
  let inExample = false;
  let inSectionDesc = false;
  let insideFence = false;
  const sectionTitles = new Set<number>();

  lines.forEach((line, i) => {
    const text = line.text;
    if (FENCE.test(text)) insideFence = !insideFence;
    if (!insideFence && !FENCE.test(text)) {
      if (PROSE_HEADING.test(text)) {
        routes.push(sawTag ? "structural" : "summary");
        return;
      }
      if (SECTION.test(text)) {
        sawTag = true;
        inExample = false;
        inSectionDesc = true;
        sectionTitles.add(i);
        routes.push("structural");
        return;
      }
      if (EXAMPLE.test(text)) {
        sawTag = true;
        inSectionDesc = false;
        inExample = true;
        routes.push("structural");
        return;
      }
      const tag = TAG.exec(text);
      if (tag) {
        sawTag = true;
        if (tag[1] === "section") {
          inExample = false;
          inSectionDesc = true;
        } else if (tag[1] === "example") {
          inSectionDesc = false;
          inExample = true;
        }
        routes.push("structural");
        return;
      }
    }
    routes.push(
      !sawTag
        ? "summary"
        : inExample
          ? "exampleBody"
          : inSectionDesc
            ? "sectionDescription"
            : "structural",
    );
  });

  const regions: DocRegion[] = [];
  const last = lines.length - 1;
  let i = 0;
  while (i < lines.length) {
    const route = routes[i]!;
    let j = i;
    while (j + 1 < lines.length && routes[j + 1] === route) j++;
    if (route !== "structural") {
      let first = i;
      let end = j;
      while (first <= end && lines[first]!.text.trim() === "") first++;
      while (end >= first && lines[end]!.text.trim() === "") end--;
      if (first <= end) {
        regions.push({
          kind: route,
          firstLine: first,
          lastLine: end,
          anchorLine: first - 1,
          editable: first > 0 && end < last,
        });
      } else if (route === "sectionDescription" && sectionTitles.has(i - 1)) {
        regions.push(emptyAfter(i - 1, last));
      }
    } else {
      // A section title followed directly by an example, tag, or section.
      for (let k = i; k <= j; k++) {
        if (sectionTitles.has(k) && routes[k + 1] !== "sectionDescription") {
          regions.push(emptyAfter(k, last));
        }
      }
    }
    i = j + 1;
  }
  return regions;
}

const emptyAfter = (anchorLine: number, last: number): DocRegion => ({
  kind: "sectionDescription",
  firstLine: anchorLine + 1,
  lastLine: anchorLine,
  anchorLine,
  editable: anchorLine < last,
});

/**
 * The copy-editable targets in a comment: prose regions (edited as markdown)
 * and the inline blocks outside editable regions (titles, edited as text).
 * Inline blocks are indexed among themselves so editing a region's markdown
 * never shifts their ids.
 */
export function docTargets(lines: DocLine[]) {
  const regions = docRegions(lines);
  const inRegion = (line: number) =>
    regions.some((r) => r.editable && line >= r.firstLine && line <= r.lastLine);
  const inline = docBlocks(lines).filter((b) => !inRegion(b.firstLine));
  return { regions, inline };
}

/** The region's markdown, as shown for editing. */
export const regionSource = (lines: DocLine[], region: DocRegion) =>
  lines
    .slice(region.firstLine, region.lastLine + 1)
    .map((l) => l.text)
    .join("\n");

/**
 * Returns `fileText` with `region` replaced by `markdown`, written as JSDoc
 * lines in the comment's own indentation.
 */
export function replaceRegion(
  fileText: string,
  lines: DocLine[],
  region: DocRegion,
  markdown: string,
): string {
  const reference =
    lines[region.lastLine >= region.firstLine ? region.firstLine : region.anchorLine]!;
  const prefix = fileText.slice(reference.lineStart, reference.start).replace(/\*\s*$/, "* ");
  const bare = prefix.trimEnd();

  let inCode = false;
  let insideFence = false;
  const body = markdown
    .replace(/\r\n?/g, "\n")
    .replace(/^\n+|\s+$/g, "")
    .split("\n")
    // Outside code, one blank line separates blocks as well as several.
    .filter((line, i, all) => {
      if (FENCE.test(line)) inCode = !inCode;
      return inCode || line.trim() !== "" || all[i - 1]?.trim() !== "";
    })
    .map((line) => {
      if (FENCE.test(line)) insideFence = !insideFence;
      // Outside code, a leading `@` would start a JSDoc tag.
      const safe = !insideFence && /^\s*@/.test(line) ? line.replace("@", "\\@") : line;
      return safe.trim() === "" ? bare : `${prefix}${safe}`;
    });
  if (body.join("\n").includes("*/")) {
    throw new Error("Markdown in a JSDoc comment can't contain */.");
  }

  const empty = body.length === 1 && body[0] === bare;
  if (region.lastLine < region.firstLine) {
    if (empty) return fileText;
    const at = lines[region.anchorLine]!.end;
    return `${fileText.slice(0, at)}\n${body.join("\n")}${fileText.slice(at)}`;
  }
  const from = lines[region.firstLine]!.lineStart;
  if (empty) {
    // Drop the region's lines entirely, including their line breaks.
    const to = lines[region.lastLine + 1]!.lineStart;
    return fileText.slice(0, from) + fileText.slice(to);
  }
  const to = lines[region.lastLine]!.end;
  return fileText.slice(0, from) + body.join("\n") + fileText.slice(to);
}

// ── copy markers ──────────────────────────────────────────────────────────

export const JSDOC_COPY_SCHEME = "jsdoc";

/** Matches what follows `\n` on a JSDoc continuation line (` * `). */
export const JSDOC_LINE_PREFIX = "[ \\t]*\\*(?!/)[ \\t]?";

/** Style preset the website applies to previews of edited JSDoc markdown. */
export const JSDOC_COPY_STYLE = "docs";

export const jsdocCopyId = (
  file: string,
  commentStart: number,
  target: `${number}` | `r${number}`,
) => `${JSDOC_COPY_SCHEME}:${file}@${commentStart}#${target}`;

export const parseJsdocCopyId = (id: string) => {
  const m = /^jsdoc:(.+)@(\d+)#(r?)(\d+)$/.exec(id);
  if (!m) return undefined;
  const base = { file: m[1]!, commentStart: Number(m[2]) };
  return m[3] ? { ...base, region: Number(m[4]) } : { ...base, block: Number(m[4]) };
};

const REGION_CLOSE = "</div><!--/copy-->";
const COPY_MARKUP_RE = new RegExp(
  `<!--copy:[^>]*?-->|^<div data-copy=[^\\n]*>$|^${REGION_CLOSE.replace(/[/]/g, "\\/")}

	
		
		
		
		
		
		
		
		
		
		
		
		
		
		
		
		
		
		
		
		
		
		
		
		
		
		
		
		
		
		
		
		
		
		
		
		
		
		
	.repos/alchemy-effect/scripts/jsdoc-blocks.ts at main · sailfork/t3code-github · Sailfork
	
		
, "gm", ); /** Removes copy markers and region wrappers from generated markdown. */ export const stripCopyMarkers = (text: string) => text.replace(COPY_MARKUP_RE, ""); /** * Returns the comment's cleaned line texts with copy markup added: region * wrappers around each editable prose region, and a trailing marker on each * title block outside them. */ export function markDocLines( lines: DocLine[], idFor: (target: `${number}` | `r${number}`) => string, ): string[] { const texts = lines.map((l) => l.text); const { regions, inline } = docTargets(lines); inline.forEach((block, index) => { const marker = `<!--copy:${idFor(`${index}`)}-->`; const text = texts[block.lastLine]!; const prose = /\s+<!-- api-prose -->\s*$/.exec(text); texts[block.lastLine] = prose ? `${text.slice(0, prose.index).trimEnd()}${marker}${prose[0]}` : `${text.trimEnd()}${marker}`; }); const before = new Map<number, string[]>(); const after = new Map<number, string[]>(); const add = (map: Map<number, string[]>, line: number, add: string[]) => map.set(line, [...(map.get(line) ?? []), ...add]); regions.forEach((region, index) => { if (!region.editable) return; const open = `<div data-copy="${idFor(`r${index}`)}" data-copy-format="markdown" data-copy-style="${JSDOC_COPY_STYLE}">`; if (region.lastLine < region.firstLine) { add(after, region.anchorLine, ["", open, REGION_CLOSE]); } else { add(before, region.firstLine, [open, ""]); add(after, region.lastLine, ["", REGION_CLOSE]); } }); return texts.flatMap((text, i) => [...(before.get(i) ?? []), text, ...(after.get(i) ?? [])]); } // ── {@link} tags ────────────────────────────────────────────────────────── export const LINK_TAG_RE = /\{@link\s+([^}]+)\}/g; /** Split a `{@link ...}` tag's inner text into target + optional label. */ export function parseLinkTag(inner: string): { target: string; label?: string; } { const trimmed = inner.trim(); const pipe = trimmed.indexOf("|"); if (pipe !== -1) { return { target: trimmed.slice(0, pipe).trim(), label: trimmed.slice(pipe + 1).trim() || undefined, }; } const space = trimmed.search(/\s/); if (space !== -1) { return { target: trimmed.slice(0, space).trim(), label: trimmed.slice(space + 1).trim() || undefined, }; } return { target: trimmed }; } /** * Reduce a typedoc-style `import("./Secrets.ts").Secrets` target to the bare * symbol name — resolution (same-directory first) and display both want the * name, not the module expression. */ export function normalizeLinkTarget(target: string): string { const match = target.match(/^import\((["'])[^"']+\1\)\.(.+)$/); return match ? match[2] : target; } /** The text a `{@link}` tag renders as (its label, or the bare target). */ export function linkTagText(inner: string): string { const { target, label } = parseLinkTag(inner.replace(/\s+/g, " ")); return label ?? normalizeLinkTarget(target); }
.repos/alchemy-effect/scripts/jsdoc-blocks.ts at main · sailfork/t3code-github · Sailfork
,\n \"gm\",\n);\n\n/** Removes copy markers and region wrappers from generated markdown. */\nexport const stripCopyMarkers = (text: string) => text.replace(COPY_MARKUP_RE, \"\");\n\n/**\n * Returns the comment's cleaned line texts with copy markup added: region\n * wrappers around each editable prose region, and a trailing marker on each\n * title block outside them.\n */\nexport function markDocLines(\n lines: DocLine[],\n idFor: (target: `${number}` | `r${number}`) => string,\n): string[] {\n const texts = lines.map((l) => l.text);\n const { regions, inline } = docTargets(lines);\n\n inline.forEach((block, index) => {\n const marker = `\u003c!--copy:${idFor(`${index}`)}-->`;\n const text = texts[block.lastLine]!;\n const prose = /\\s+\u003c!-- api-prose -->\\s*$/.exec(text);\n texts[block.lastLine] = prose\n ? `${text.slice(0, prose.index).trimEnd()}${marker}${prose[0]}`\n : `${text.trimEnd()}${marker}`;\n });\n\n const before = new Map\u003cnumber, string[]>();\n const after = new Map\u003cnumber, string[]>();\n const add = (map: Map\u003cnumber, string[]>, line: number, add: string[]) =>\n map.set(line, [...(map.get(line) ?? []), ...add]);\n regions.forEach((region, index) => {\n if (!region.editable) return;\n const open = `\u003cdiv data-copy=\"${idFor(`r${index}`)}\" data-copy-format=\"markdown\" data-copy-style=\"${JSDOC_COPY_STYLE}\">`;\n if (region.lastLine \u003c region.firstLine) {\n add(after, region.anchorLine, [\"\", open, REGION_CLOSE]);\n } else {\n add(before, region.firstLine, [open, \"\"]);\n add(after, region.lastLine, [\"\", REGION_CLOSE]);\n }\n });\n return texts.flatMap((text, i) => [...(before.get(i) ?? []), text, ...(after.get(i) ?? [])]);\n}\n\n// ── {@link} tags ──────────────────────────────────────────────────────────\n\nexport const LINK_TAG_RE = /\\{@link\\s+([^}]+)\\}/g;\n\n/** Split a `{@link ...}` tag's inner text into target + optional label. */\nexport function parseLinkTag(inner: string): {\n target: string;\n label?: string;\n} {\n const trimmed = inner.trim();\n const pipe = trimmed.indexOf(\"|\");\n if (pipe !== -1) {\n return {\n target: trimmed.slice(0, pipe).trim(),\n label: trimmed.slice(pipe + 1).trim() || undefined,\n };\n }\n const space = trimmed.search(/\\s/);\n if (space !== -1) {\n return {\n target: trimmed.slice(0, space).trim(),\n label: trimmed.slice(space + 1).trim() || undefined,\n };\n }\n return { target: trimmed };\n}\n\n/**\n * Reduce a typedoc-style `import(\"./Secrets.ts\").Secrets` target to the bare\n * symbol name — resolution (same-directory first) and display both want the\n * name, not the module expression.\n */\nexport function normalizeLinkTarget(target: string): string {\n const match = target.match(/^import\\(([\"'])[^\"']+\\1\\)\\.(.+)$/);\n return match ? match[2] : target;\n}\n\n/** The text a `{@link}` tag renders as (its label, or the bare target). */\nexport function linkTagText(inner: string): string {\n const { target, label } = parseLinkTag(inner.replace(/\\s+/g, \" \"));\n return label ?? normalizeLinkTarget(target);\n}\n","preview":null,"history":null,"version":"295eeb8d29fe80f06786067a5832f98ba06f1e09"},"/_session?shell=1":null}