@taurgis/bonsai 3.2.0 → 3.2.2

package/dist/lib/research/docs/capabilities.d.ts

@@ -1,12 +1,18 @@
+/** Two-valued confidence marker: `verified` = observed in bytes; `signal` = hinted but unproven. */
 export type Evidence = 'verified' | 'signal';
+/** Recognized client-side doc rendering engines. */
 export type DocsEngine = 'vitepress' | 'docusaurus' | 'starlight' | 'next' | 'generated-static' | 'spa';
+/** Reusable docs generators and hosted platforms layered on top of (or independent of) an engine. */
 export type DocsFramework = 'mkdocs' | 'material-mkdocs' | 'sphinx' | 'nextra' | 'fumadocs' | 'gitbook' | 'mintlify' | 'readme' | 'redocly' | 'docsify' | 'rspress' | 'vuepress' | 'docsy' | 'just-the-docs';
+/** Recognized machine-readable artifact types a docs site may expose. */
 export type MachineReadableType = 'llms.txt' | 'llms-full.txt' | 'route-markdown' | 'search-index' | 'sitemap' | 'source-edit-link';
+/** A machine-readable artifact discovered (or inferred) for a docs site. */
 export interface MachineReadableArtifact {
     type: MachineReadableType;
     url: string;
     evidence: Evidence;
 }
+/** A pointer to the public Markdown/MDX source for a page. Only `verified` once a raw URL is fetched successfully. */
 export interface SourceHint {
     type: 'markdown' | 'mdx' | 'html';
     url?: string;
@@ -15,7 +21,9 @@ export interface SourceHint {
     path?: string;
     evidence: Evidence;
 }
+/** Known search providers a docs site may use. */
 export type SearchProvider = 'algolia-docsearch' | 'vitepress-local' | 'pagefind' | 'docusaurus-local' | 'mkdocs-local' | 'sphinx-searchindex' | 'jekyll-json' | 'sitemap' | 'llms.txt' | 'readme-algolia' | 'custom';
+/** Search capability detected for a docs site, with optional index coordinates. */
 export interface SearchCapability {
     provider: SearchProvider;
     evidence: Evidence;
@@ -25,11 +33,13 @@ export interface SearchCapability {
     apiKey?: string;
     publicEndpoint?: string;
 }
+/** A single entry in a docs site's page map: title, route URL, and optional source path. */
 export interface PageMapEntry {
     title: string;
     url: string;
     sourcePath?: string;
 }
+/** Full capability snapshot for a docs site, as populated by the detector and probe modules. */
 export interface SiteCapabilities {
     docsEngine?: DocsEngine;
     framework?: DocsFramework;
@@ -40,4 +50,9 @@ export interface SiteCapabilities {
     pageMap?: PageMapEntry[];
     notes: string[];
 }
+/**
+ * Returns a baseline SiteCapabilities with no engine/framework detected and an empty capability set.
+ *
+ * @returns A minimal SiteCapabilities object suitable as a starting point for detectors and probes.
+ */
 export declare function emptyCapabilities(): SiteCapabilities;

package/dist/lib/research/docs/capabilities.js

@@ -4,6 +4,11 @@
 // two-valued: `verified` means observed in the supplied bytes (markup/data/HTTP), `signal` means
 // the page hints at the capability but the endpoint/index/source is not proven. A visible search
 // button is at most a `signal` — never `verified` (see T-16/T-20 acceptance criteria).
+/**
+ * Returns a baseline SiteCapabilities with no engine/framework detected and an empty capability set.
+ *
+ * @returns A minimal SiteCapabilities object suitable as a starting point for detectors and probes.
+ */
 export function emptyCapabilities() {
     return { recommendedCapture: 'static', machineReadable: [], notes: [] };
 }

package/dist/lib/research/docs/clean-dom.d.ts

@@ -1,4 +1,6 @@
 /**
  * Strips decorative docs chrome and base64 images from the document in place before extraction.
+ *
+ * @param document - linkedom Document object to mutate.
  */
 export declare function cleanDocsChrome(document: any): void;

package/dist/lib/research/docs/clean-dom.js

@@ -33,6 +33,8 @@ function dropDataImages(document) {
 }
 /**
  * Strips decorative docs chrome and base64 images from the document in place before extraction.
+ *
+ * @param document - linkedom Document object to mutate.
  */
 export function cleanDocsChrome(document) {
     for (const selector of CHROME_SELECTORS)

package/dist/lib/research/docs/code-blocks.d.ts

@@ -1,5 +1,7 @@
 /**
  * Reconstructs newline-delimited text for every highlighted code block in the document and tags it
  * with a `language-x` class when one is detectable. Idempotent and a no-op on plain `<pre>` blocks.
+ *
+ * @param document - linkedom Document object to mutate in place.
  */
 export declare function normalizeCodeBlocks(document: any): void;

package/dist/lib/research/docs/code-blocks.js

@@ -76,6 +76,8 @@ function flattenCodeStructure(pre, code) {
 /**
  * Reconstructs newline-delimited text for every highlighted code block in the document and tags it
  * with a `language-x` class when one is detectable. Idempotent and a no-op on plain `<pre>` blocks.
+ *
+ * @param document - linkedom Document object to mutate in place.
  */
 export function normalizeCodeBlocks(document) {
     removeCopyButtons(document);

package/dist/lib/research/docs/detect.d.ts

@@ -2,5 +2,9 @@ import type { SiteCapabilities } from './capabilities.js';
 /**
  * Inspects page HTML and returns the detected docs engine/framework plus any capability signals.
  * Always returns a result; an unrecognized page yields a best-effort static/SPA shape classification.
+ *
+ * @param html - Full page HTML to inspect (not executed — signals matched as substrings).
+ * @param url - Page URL used to resolve relative links in source/llms.txt hints.
+ * @returns Detected SiteCapabilities including engine, framework, recommended capture, and signals.
  */
 export declare function detectDocsEngine(html: string, url: string): SiteCapabilities;

package/dist/lib/research/docs/detect.js

@@ -226,6 +226,10 @@ const FAMILY_DETECTORS = [
 /**
  * Inspects page HTML and returns the detected docs engine/framework plus any capability signals.
  * Always returns a result; an unrecognized page yields a best-effort static/SPA shape classification.
+ *
+ * @param html - Full page HTML to inspect (not executed — signals matched as substrings).
+ * @param url - Page URL used to resolve relative links in source/llms.txt hints.
+ * @returns Detected SiteCapabilities including engine, framework, recommended capture, and signals.
  */
 export function detectDocsEngine(html, url) {
     const { document } = parseHTML(html);

package/dist/lib/research/docs/machine-readable.d.ts

@@ -1,8 +1,16 @@
 import type { MachineReadableArtifact, SiteCapabilities } from './capabilities.js';
+/** A successfully validated machine-readable artifact and its body text. */
 export interface MachineReadableResult {
     artifact: MachineReadableArtifact;
     body: string;
 }
+/**
+ * Injectable HTTP fetcher used by the machine-readable probe functions.
+ * Tests supply a fixture fetcher; production code uses `fetchText`.
+ *
+ * @param url - Absolute URL to fetch.
+ * @returns Response body, final URL after redirects, status code, and content-type header.
+ */
 export type TextFetcher = (url: string) => Promise<{
     content: string;
     finalUrl: string;
@@ -12,10 +20,20 @@ export type TextFetcher = (url: string) => Promise<{
 /**
  * Probes conventional and advertised `llms.txt` URLs. Returns the first that validates as same-origin
  * text, or null. The result is a site-INDEX artifact for discovery — not a replacement for page content.
+ *
+ * @param pageUrl - The doc page URL; its origin is used for same-origin checks and candidate construction.
+ * @param caps - Site capabilities from the detector, carrying any advertised llms.txt links.
+ * @param fetcher - HTTP fetcher (injectable for tests).
+ * @returns A verified MachineReadableResult, or null when no valid llms.txt is found.
  */
 export declare function probeLlmsTxt(pageUrl: string, caps: SiteCapabilities, fetcher?: TextFetcher): Promise<MachineReadableResult | null>;
 /**
  * Probes a page-level `.md` route. The derived route is only a candidate: it must be same-origin,
  * fetch successfully, and validate as non-HTML/non-error Markdown before being trusted.
+ *
+ * @param pageUrl - The doc page URL to derive the `.md` route from.
+ * @param caps - Site capabilities carrying any advertised route-markdown links.
+ * @param fetcher - HTTP fetcher (injectable for tests).
+ * @returns A verified MachineReadableResult, or null when no valid route Markdown is found.
  */
 export declare function probeRouteMarkdown(pageUrl: string, caps: SiteCapabilities, fetcher?: TextFetcher): Promise<MachineReadableResult | null>;

package/dist/lib/research/docs/machine-readable.js

@@ -34,6 +34,11 @@ async function tryFetchValidText(url, fetcher) {
 /**
  * Probes conventional and advertised `llms.txt` URLs. Returns the first that validates as same-origin
  * text, or null. The result is a site-INDEX artifact for discovery — not a replacement for page content.
+ *
+ * @param pageUrl - The doc page URL; its origin is used for same-origin checks and candidate construction.
+ * @param caps - Site capabilities from the detector, carrying any advertised llms.txt links.
+ * @param fetcher - HTTP fetcher (injectable for tests).
+ * @returns A verified MachineReadableResult, or null when no valid llms.txt is found.
  */
 export async function probeLlmsTxt(pageUrl, caps, fetcher = defaultFetcher) {
     for (const candidate of llmsTxtCandidates(pageUrl, caps)) {
@@ -50,6 +55,11 @@ export async function probeLlmsTxt(pageUrl, caps, fetcher = defaultFetcher) {
 /**
  * Probes a page-level `.md` route. The derived route is only a candidate: it must be same-origin,
  * fetch successfully, and validate as non-HTML/non-error Markdown before being trusted.
+ *
+ * @param pageUrl - The doc page URL to derive the `.md` route from.
+ * @param caps - Site capabilities carrying any advertised route-markdown links.
+ * @param fetcher - HTTP fetcher (injectable for tests).
+ * @returns A verified MachineReadableResult, or null when no valid route Markdown is found.
  */
 export async function probeRouteMarkdown(pageUrl, caps, fetcher = defaultFetcher) {
     const advertised = caps.machineReadable

package/dist/lib/research/docs/markdown-source.d.ts

@@ -1,12 +1,24 @@
 import type { ExtractionResult } from '../extract.js';
+/** Result of stripping a YAML frontmatter block from a Markdown document. */
 export interface ParsedFrontmatter {
     frontmatter: Record<string, string>;
     body: string;
 }
+/**
+ * Extracts the leading YAML frontmatter block from a Markdown string. Only flat scalar keys are
+ * read; nested structures are silently ignored. The returned `body` has the frontmatter block
+ * and its delimiters stripped.
+ *
+ * @param md - Raw Markdown/MDX string, possibly starting with `---` frontmatter.
+ * @returns Parsed flat key/value frontmatter and the remaining Markdown body.
+ */
 export declare function parseFrontmatter(md: string): ParsedFrontmatter;
 /**
  * Removes dangerous embedded HTML from untrusted Markdown: <script>/<style> blocks, inline event
  * handler attributes, and javascript: URLs. Leaves ordinary Markdown and benign inline HTML intact.
+ *
+ * @param md - Markdown/MDX source string from a public but untrusted URL.
+ * @returns Sanitized Markdown with unsafe HTML constructs removed.
  */
 export declare function sanitizeSourceMarkdown(md: string): string;
 /**
@@ -14,11 +26,19 @@ export declare function sanitizeSourceMarkdown(md: string): string;
  * fences through verbatim. Every text-level cleanup in this pipeline must go through this guard:
  * fenced code is quoted material, and "cleaning" it destroys the samples readers came for
  * (a `<script>` line in an example, a bash `# comment`, a literal `javascript:` URL).
+ *
+ * @param md - Markdown document to process.
+ * @param transform - Function applied to each non-fenced segment.
+ * @returns Transformed Markdown with fenced code blocks left verbatim.
  */
 export declare function outsideFences(md: string, transform: (segment: string) => string): string;
 /**
  * Builds an ExtractionResult from public Markdown/MDX source. Frontmatter is parsed for the title
  * and the body is sanitized. The detailed Markdown is the source itself, preserving code fences,
  * tabs, and admonitions better than HTML conversion.
+ *
+ * @param md - Raw Markdown/MDX source from a public URL.
+ * @param sourceUrl - The URL the source was fetched from; used for MDN KumaScript gating and the quality note.
+ * @returns ExtractionResult with the cleaned Markdown body as `detailedMarkdown`.
  */
 export declare function extractFromSource(md: string, sourceUrl: string): ExtractionResult;

package/dist/lib/research/docs/markdown-source.js

@@ -1,7 +1,13 @@
 import { dropEmptyLinks, htmlToMarkdown } from '../markdown.js';
 import { sanitizePromptInjection } from '../prompt-injection.js';
-// Parses a leading YAML frontmatter block (--- ... ---). Only flat scalar keys are read; nested
-// structures are ignored (we only need title/description). The block is stripped from the body.
+/**
+ * Extracts the leading YAML frontmatter block from a Markdown string. Only flat scalar keys are
+ * read; nested structures are silently ignored. The returned `body` has the frontmatter block
+ * and its delimiters stripped.
+ *
+ * @param md - Raw Markdown/MDX string, possibly starting with `---` frontmatter.
+ * @returns Parsed flat key/value frontmatter and the remaining Markdown body.
+ */
 export function parseFrontmatter(md) {
     const normalized = md.replace(/^/, '');
     if (!normalized.startsWith('---'))
@@ -29,6 +35,9 @@ export function parseFrontmatter(md) {
 /**
  * Removes dangerous embedded HTML from untrusted Markdown: <script>/<style> blocks, inline event
  * handler attributes, and javascript: URLs. Leaves ordinary Markdown and benign inline HTML intact.
+ *
+ * @param md - Markdown/MDX source string from a public but untrusted URL.
+ * @returns Sanitized Markdown with unsafe HTML constructs removed.
  */
 export function sanitizeSourceMarkdown(md) {
     return (md
@@ -103,6 +112,10 @@ function stripMdnHiddenSamples(md) {
  * fences through verbatim. Every text-level cleanup in this pipeline must go through this guard:
  * fenced code is quoted material, and "cleaning" it destroys the samples readers came for
  * (a `<script>` line in an example, a bash `# comment`, a literal `javascript:` URL).
+ *
+ * @param md - Markdown document to process.
+ * @param transform - Function applied to each non-fenced segment.
+ * @returns Transformed Markdown with fenced code blocks left verbatim.
  */
 export function outsideFences(md, transform) {
     return md
@@ -198,6 +211,10 @@ function confidenceFor(length) {
  * Builds an ExtractionResult from public Markdown/MDX source. Frontmatter is parsed for the title
  * and the body is sanitized. The detailed Markdown is the source itself, preserving code fences,
  * tabs, and admonitions better than HTML conversion.
+ *
+ * @param md - Raw Markdown/MDX source from a public URL.
+ * @param sourceUrl - The URL the source was fetched from; used for MDN KumaScript gating and the quality note.
+ * @returns ExtractionResult with the cleaned Markdown body as `detailedMarkdown`.
  */
 export function extractFromSource(md, sourceUrl) {
     const { frontmatter, body } = parseFrontmatter(md);

package/dist/lib/research/docs/quality-gates.d.ts

@@ -1,3 +1,4 @@
+/** Quality analysis result: stable `quality:*` codes and an index-hub detection flag. */
 export interface QualitySignals {
     codes: string[];
     isIndexHub: boolean;
@@ -5,5 +6,9 @@ export interface QualitySignals {
 /**
  * Analyzes extracted Markdown and returns stable quality codes plus an index/hub flag. `markdown`
  * is the detailed representation; `title` helps the error-page heuristic on short pages.
+ *
+ * @param markdown - Detailed Markdown text to analyze.
+ * @param title - Page title used to strengthen the error-page heuristic on short pages.
+ * @returns Stable `quality:*` codes and `isIndexHub` flag.
  */
 export declare function analyzeMarkdownQuality(markdown: string, title?: string): QualitySignals;

package/dist/lib/research/docs/quality-gates.js

@@ -40,6 +40,10 @@ function hasCollapsedCode(markdown) {
 /**
  * Analyzes extracted Markdown and returns stable quality codes plus an index/hub flag. `markdown`
  * is the detailed representation; `title` helps the error-page heuristic on short pages.
+ *
+ * @param markdown - Detailed Markdown text to analyze.
+ * @param title - Page title used to strengthen the error-page heuristic on short pages.
+ * @returns Stable `quality:*` codes and `isIndexHub` flag.
  */
 export function analyzeMarkdownQuality(markdown, title = '') {
     const codes = [];

package/dist/lib/research/docs/rsc.d.ts

@@ -1,10 +1,17 @@
 import type { PageMapEntry } from './capabilities.js';
+/**
+ * Page-map and source-path data recovered from a Next.js / React Server Components (RSC) HTML payload.
+ * `sourcePathHints` are unverified; they must be validated before being promoted to a source link.
+ */
 export interface NextRscData {
     pageMap: PageMapEntry[];
     sourcePathHints: string[];
 }
 /**
- * Scans Next/RSC HTML for a page map (route + title, with optional source path) and any
- * `filePath` source hints. Returns empty arrays when no payload is present.
+ * Scans Next.js / React Server Components (RSC) HTML for a page map (route + title, with optional
+ * source path) and any `filePath` source hints. Returns empty arrays when no payload is present.
+ *
+ * @param html - Full page HTML containing embedded `__NEXT_DATA__` or `self.__next_f` payloads.
+ * @returns Recovered page map entries and unverified source-path hints.
  */
 export declare function extractNextRscData(html: string): NextRscData;

package/dist/lib/research/docs/rsc.js

@@ -7,8 +7,11 @@ function dedupe(items) {
     return [...new Set(items.filter(Boolean))];
 }
 /**
- * Scans Next/RSC HTML for a page map (route + title, with optional source path) and any
- * `filePath` source hints. Returns empty arrays when no payload is present.
+ * Scans Next.js / React Server Components (RSC) HTML for a page map (route + title, with optional
+ * source path) and any `filePath` source hints. Returns empty arrays when no payload is present.
+ *
+ * @param html - Full page HTML containing embedded `__NEXT_DATA__` or `self.__next_f` payloads.
+ * @returns Recovered page map entries and unverified source-path hints.
  */
 export function extractNextRscData(html) {
     const text = unescapeFlight(html);

package/dist/lib/research/docs/section-artifacts.d.ts

@@ -3,11 +3,23 @@ import type { SummaryLevel } from '../../config/schema.js';
 /**
  * Derives section child artifacts from a parent page artifact. Returns [] when the page is short
  * or has too few headings to chunk.
+ *
+ * @param parent - The parent page artifact whose `detailed` Markdown will be split.
+ * @param currentTime - Timestamp to embed in child artifact metadata.
+ * @param summaryLevel - Extractive summarization level for building each child's `compressed` field.
+ * @returns Array of section ResearchArtifacts, empty when the page is below the token threshold.
  */
 export declare function buildSectionArtifacts(parent: ResearchArtifact, currentTime: Date, summaryLevel: SummaryLevel): ResearchArtifact[];
 /**
  * Regenerates a page's section artifacts: writes fresh children and archives any prior child whose
  * heading no longer exists, so a revalidated parent never leaves orphaned sections active. Returns
  * the number of active section children written.
+ *
+ * @param dataDir - Root data directory used by `scanCacheDir` and `writeArtifact`.
+ * @param parent - The parent page artifact to derive sections from.
+ * @param currentTime - Timestamp embedded in the child artifacts.
+ * @param summaryLevel - Extractive summarization level for child `compressed` fields.
+ * @returns Count of active section children written to disk.
+ * @throws {Error} When `writeArtifact` rejects a path or the filesystem write fails.
  */
 export declare function persistSectionArtifacts(dataDir: string, parent: ResearchArtifact, currentTime: Date, summaryLevel: SummaryLevel): number;

package/dist/lib/research/docs/section-artifacts.js

@@ -16,6 +16,11 @@ function childKey(parentKey, anchor) {
 /**
  * Derives section child artifacts from a parent page artifact. Returns [] when the page is short
  * or has too few headings to chunk.
+ *
+ * @param parent - The parent page artifact whose `detailed` Markdown will be split.
+ * @param currentTime - Timestamp to embed in child artifact metadata.
+ * @param summaryLevel - Extractive summarization level for building each child's `compressed` field.
+ * @returns Array of section ResearchArtifacts, empty when the page is below the token threshold.
  */
 export function buildSectionArtifacts(parent, currentTime, summaryLevel) {
     if (estimateTokens(parent.detailed) <= SECTION_TOKEN_THRESHOLD)
@@ -58,6 +63,13 @@ function activeChildrenOf(dataDir, parentKey) {
  * Regenerates a page's section artifacts: writes fresh children and archives any prior child whose
  * heading no longer exists, so a revalidated parent never leaves orphaned sections active. Returns
  * the number of active section children written.
+ *
+ * @param dataDir - Root data directory used by `scanCacheDir` and `writeArtifact`.
+ * @param parent - The parent page artifact to derive sections from.
+ * @param currentTime - Timestamp embedded in the child artifacts.
+ * @param summaryLevel - Extractive summarization level for child `compressed` fields.
+ * @returns Count of active section children written to disk.
+ * @throws {Error} When `writeArtifact` rejects a path or the filesystem write fails.
  */
 export function persistSectionArtifacts(dataDir, parent, currentTime, summaryLevel) {
     const children = buildSectionArtifacts(parent, currentTime, summaryLevel);

package/dist/lib/research/docs/sections.d.ts

@@ -1,13 +1,31 @@
+/** A single H2/H3 section chunk extracted from a long Markdown document. */
 export interface SectionChunk {
     anchor: string;
     headingPath: string;
     level: number;
     content: string;
 }
+/**
+ * Strips Markdown formatting from a raw heading string, returning plain text suitable for building
+ * GitHub-style anchors and breadcrumb labels.
+ *
+ * @param raw - The heading text as it appears in Markdown (may contain links, code, emphasis).
+ * @returns Plain text with links, images, inline code, and emphasis markers removed.
+ */
 export declare function headingPlainText(raw: string): string;
+/**
+ * Converts plain heading text into a GitHub-compatible anchor slug: lowercase, punctuation
+ * removed, spaces replaced with hyphens.
+ *
+ * @param text - Plain heading text (output of `headingPlainText`).
+ * @returns URL-safe anchor slug string.
+ */
 export declare function slugifyHeading(text: string): string;
 /**
  * Splits Markdown into H2/H3 section chunks. Returns an empty array when the document has fewer
  * than two such headings (nothing meaningful to chunk).
+ *
+ * @param markdown - Full detailed Markdown document to split.
+ * @returns Ordered array of H2/H3 section chunks, or an empty array for short/flat documents.
  */
 export declare function splitMarkdownSections(markdown: string): SectionChunk[];

package/dist/lib/research/docs/sections.js

@@ -8,6 +8,13 @@ const HEADING_RE = /^(#{1,6})\s+(.+?)\s*#*\s*$/;
 // "API documentation" — not the raw link syntax, which otherwise leaks the URL into the anchor and
 // breadcrumb. Confirmed against github-slugger, which documents that it operates on plain heading
 // text rather than parsing Markdown: https://github.com/Flet/github-slugger
+/**
+ * Strips Markdown formatting from a raw heading string, returning plain text suitable for building
+ * GitHub-style anchors and breadcrumb labels.
+ *
+ * @param raw - The heading text as it appears in Markdown (may contain links, code, emphasis).
+ * @returns Plain text with links, images, inline code, and emphasis markers removed.
+ */
 export function headingPlainText(raw) {
     // The `\(…\)` part tolerates one level of balanced parens so a real-world target like
     // `URL_(disambiguation)` doesn't leave a dangling ")" in the rendered breadcrumb text.
@@ -20,7 +27,13 @@ export function headingPlainText(raw) {
         .replace(/\s+/g, ' ')
         .trim();
 }
-// GitHub-style anchor slug: lowercase, drop punctuation, spaces -> hyphens.
+/**
+ * Converts plain heading text into a GitHub-compatible anchor slug: lowercase, punctuation
+ * removed, spaces replaced with hyphens.
+ *
+ * @param text - Plain heading text (output of `headingPlainText`).
+ * @returns URL-safe anchor slug string.
+ */
 export function slugifyHeading(text) {
     return text
         .toLowerCase()
@@ -61,6 +74,9 @@ function breadcrumb(headings, current) {
 /**
  * Splits Markdown into H2/H3 section chunks. Returns an empty array when the document has fewer
  * than two such headings (nothing meaningful to chunk).
+ *
+ * @param markdown - Full detailed Markdown document to split.
+ * @returns Ordered array of H2/H3 section chunks, or an empty array for short/flat documents.
  */
 export function splitMarkdownSections(markdown) {
     const lines = markdown.split('\n');

package/dist/lib/research/docs/source-map.d.ts

@@ -1,3 +1,4 @@
+/** A resolved pointer to a public GitHub source file for a documentation page. */
 export interface GithubSource {
     repository: string;
     branch: string;
@@ -7,13 +8,40 @@ export interface GithubSource {
 /**
  * Converts a GitHub `edit`/`blob` URL into a raw.githubusercontent.com URL. Returns null for any
  * URL that is not a recognized GitHub edit/blob link, so callers never fabricate a raw URL.
+ *
+ * @param href - A GitHub edit or blob URL (or any other string).
+ * @returns A GithubSource candidate, or null when `href` is not a recognized edit/blob link.
  */
 export declare function parseGithubSourceLink(href: string): GithubSource | null;
+/**
+ * Maps a Node.js API docs URL to its source file in the nodejs/node GitHub repository.
+ * Returns null when the URL is not a recognized Node.js API page.
+ *
+ * @param url - A nodejs.org API documentation URL.
+ * @returns A GithubSource candidate, or null for unrecognized URLs.
+ */
 export declare function mapNodeApiSource(url: string): GithubSource | null;
+/**
+ * Maps an MDN developer.mozilla.org URL to its source file in the mdn/content GitHub repository.
+ * Returns null when the URL is not a recognized MDN docs page.
+ *
+ * @param url - An MDN documentation URL.
+ * @returns A GithubSource candidate, or null for unrecognized URLs.
+ */
 export declare function mapMdnSource(url: string): GithubSource | null;
+/**
+ * Derives the candidate `.md` route URL for a VitePress page. Returns null when the URL already
+ * ends with `.md` or cannot be parsed. The result is a candidate that must be validated by fetching.
+ *
+ * @param url - A VitePress documentation page URL.
+ * @returns The derived `.md` route URL, or null for non-applicable URLs.
+ */
 export declare function vitepressRouteMarkdown(url: string): string | null;
 /**
  * Tries every known URL->source mapper in turn. Returns the first candidate, or null. The result
  * is a CANDIDATE; it must be validated by fetching before being recorded as a verified source.
+ *
+ * @param url - A documentation page URL to map.
+ * @returns The first GithubSource candidate, or null when no mapper recognizes the URL.
  */
 export declare function mapUrlToSource(url: string): GithubSource | null;

package/dist/lib/research/docs/source-map.js

@@ -5,6 +5,9 @@ const GITHUB_EDIT_BLOB = /^https?:\/\/github\.com\/([^/]+)\/([^/]+)\/(?:edit|blo
 /**
  * Converts a GitHub `edit`/`blob` URL into a raw.githubusercontent.com URL. Returns null for any
  * URL that is not a recognized GitHub edit/blob link, so callers never fabricate a raw URL.
+ *
+ * @param href - A GitHub edit or blob URL (or any other string).
+ * @returns A GithubSource candidate, or null when `href` is not a recognized edit/blob link.
  */
 export function parseGithubSourceLink(href) {
     const match = href.match(GITHUB_EDIT_BLOB);
@@ -25,6 +28,13 @@ export function parseGithubSourceLink(href) {
 // Node.js API docs: https://nodejs.org/api/url.html -> nodejs/node/doc/api/url.md on the release
 // line. Deterministic and fixture-proven; mapping is advertised only after a successful fetch.
 const NODE_API = /^https?:\/\/nodejs\.org\/(?:[a-z-]+\/)?(?:docs\/)?(?:latest(?:-v\d+\.x)?\/)?api\/([a-z_]+)\.html/i;
+/**
+ * Maps a Node.js API docs URL to its source file in the nodejs/node GitHub repository.
+ * Returns null when the URL is not a recognized Node.js API page.
+ *
+ * @param url - A nodejs.org API documentation URL.
+ * @returns A GithubSource candidate, or null for unrecognized URLs.
+ */
 export function mapNodeApiSource(url) {
     const match = url.match(NODE_API);
     if (!match)
@@ -41,6 +51,13 @@ export function mapNodeApiSource(url) {
 // MDN: https://developer.mozilla.org/en-US/docs/Web/JavaScript/...  ->  mdn/content
 // files/en-us/web/javascript/.../index.md (content paths are lowercased).
 const MDN_DOCS = /^https?:\/\/developer\.mozilla\.org\/([a-zA-Z-]+)\/docs\/(.+?)\/?$/;
+/**
+ * Maps an MDN developer.mozilla.org URL to its source file in the mdn/content GitHub repository.
+ * Returns null when the URL is not a recognized MDN docs page.
+ *
+ * @param url - An MDN documentation URL.
+ * @returns A GithubSource candidate, or null for unrecognized URLs.
+ */
 export function mapMdnSource(url) {
     const match = url.match(MDN_DOCS);
     if (!match)
@@ -59,6 +76,13 @@ export function mapMdnSource(url) {
 }
 // VitePress route Markdown: a docs page at /guide/intro.html (or /guide/intro) also serves
 // /guide/intro.md. Returns the candidate `.md` route URL; validate before use (T-24/T-19).
+/**
+ * Derives the candidate `.md` route URL for a VitePress page. Returns null when the URL already
+ * ends with `.md` or cannot be parsed. The result is a candidate that must be validated by fetching.
+ *
+ * @param url - A VitePress documentation page URL.
+ * @returns The derived `.md` route URL, or null for non-applicable URLs.
+ */
 export function vitepressRouteMarkdown(url) {
     let parsed;
     try {
@@ -81,6 +105,9 @@ export function vitepressRouteMarkdown(url) {
 /**
  * Tries every known URL->source mapper in turn. Returns the first candidate, or null. The result
  * is a CANDIDATE; it must be validated by fetching before being recorded as a verified source.
+ *
+ * @param url - A documentation page URL to map.
+ * @returns The first GithubSource candidate, or null when no mapper recognizes the URL.
  */
 export function mapUrlToSource(url) {
     return mapNodeApiSource(url) ?? mapMdnSource(url);

package/dist/lib/research/docs/validate.d.ts

@@ -1,13 +1,46 @@
+/** Result of validating a machine-readable artifact body. `reason` is set when `ok` is false. */
 export interface ArtifactValidation {
     ok: boolean;
     reason?: string;
 }
-/** True when short text reads like an error/soft-404 page rather than real content. */
+/** True when short text reads like an error/soft-404 page rather than real content.
+ *
+ * @param text - Body text to inspect (only short bodies trigger the heuristic).
+ * @returns True when the text matches an error/soft-404 pattern.
+ */
 export declare function looksLikeErrorPage(text: string): boolean;
-/** Same docs origin guard: a probed artifact must live on the same hostname as the page. */
+/** Same docs origin guard: a probed artifact must live on the same hostname as the page.
+ *
+ * @param candidateUrl - URL of the artifact to validate.
+ * @param baseUrl - URL of the original page being researched.
+ * @returns True when both URLs share the same hostname.
+ */
 export declare function isSameDocsOrigin(candidateUrl: string, baseUrl: string): boolean;
 /**
  * Validates that an `llms.txt` or route-Markdown body is usable: non-empty, not an HTML page, and
  * not a soft error page. HTML returned for a `.md`/`.txt` probe is the most common false positive.
+ *
+ * @param body - Raw response body from the probe fetch.
+ * @returns `{ ok: true }` when the body is valid, or `{ ok: false, reason }` explaining the failure.
  */
 export declare function validateTextArtifact(body: string): ArtifactValidation;
+/** The subset of a fetch response a Markdown-twin probe needs to validate. */
+export interface MarkdownTwinResponse {
+    contentType: string | null;
+    finalUrl: string;
+    content: string;
+}
+/**
+ * Validates a probed `.md`-route response as a trustworthy Markdown twin, the shared trust
+ * contract behind both the developer.salesforce.com and help.salesforce.com twin probes: the
+ * server must label it `text/markdown`, the redirect chain must land on the expected host over
+ * https (never a plain-http downgrade or an on-path host), and the body must pass
+ * {@link validateTextArtifact} (non-empty, non-HTML, not a soft-error page). A 200 HTML "not
+ * found" shell — the most common false positive for a `.md` probe — fails the content-type check
+ * before the body is even inspected.
+ *
+ * @param res - The probe response's content-type, final URL after redirects, and body.
+ * @param allowedHost - Hostname the redirect chain must land on (compared case-insensitively).
+ * @returns True when the response is a trustworthy Markdown twin.
+ */
+export declare function isValidatedMarkdownTwin(res: MarkdownTwinResponse, allowedHost: string): boolean;