@dogsbay/format-starlight 0.2.0-beta.115 → 0.2.0-beta.116

package/dist/adapter.d.ts

@@ -17,6 +17,12 @@ export interface ComponentMapping {
     container: boolean;
     /** Strip the component entirely. If container=true, inner content is kept. */
     strip?: boolean;
+    /**
+     * A stripped non-container loses whatever it rendered, so it is REPORTED
+     * (onDrop) like an unmapped component. `silent` marks the few whose removal
+     * loses nothing (a widget replaced by structure built elsewhere).
+     */
+    silent?: boolean;
 }
 export interface SiteAdapter {
     /** Adapter name (e.g. "cloudflare") */
@@ -38,9 +44,71 @@ export interface SiteAdapter {
      *
      * @param source - MDX source text
      * @param partialsDir - Base directory for partial files (auto-detected or CLI flag)
+     * @param options - `mode: "template"` emits template-page directives
+     *   (`{% with %}{% include %}`) instead of inlining; see IncludeOptions
      * @returns Source with include tags replaced by partial content
      */
-    resolveIncludes?: (source: string, partialsDir?: string) => string;
+    /** `frontmatter`: the page's own (raw) front matter, for components that read it (`<ProductReleaseNotes>`). */
+    resolveIncludes?: (source: string, partialsDir?: string, options?: IncludeOptions, frontmatter?: Record<string, unknown>) => string;
     /** Frontmatter field name that carries the redirect/external link URL */
     redirectField?: string;
+    /**
+     * Rewrite the finished tree — for structure a component mapping cannot
+     * express alone (sibling components that together form one group).
+     */
+    transformTree?: (tree: TreeNode[]) => TreeNode[];
+}
+/**
+ * How `resolveIncludes` treats partials.
+ *
+ * - `inline` (default): splice each partial's content into the page, with
+ *   its parameters substituted. Works for every output format.
+ * - `template`: emit `{% with k=v %}{% include "/_partials/<product>/<file>.md" %}{% endwith %}`
+ *   and let the caller convert each partial into a TEMPLATE partial
+ *   (plans/page-templates.md). Only a Dogsbay-MD output can carry it.
+ */
+import type { DirectiveTable } from "./template-tokens.js";
+import type { TreeNode } from "@dogsbay/types";
+/** What `<APIRequest>` takes from an OpenAPI operation. */
+export interface ApiOperation {
+    summary?: string;
+    /** Security scheme names (`api_token`, `api_key`, …). */
+    security?: string[];
+    /** `x-api-token-group`: the token permissions that grant it. */
+    tokenGroups?: string[];
+}
+export interface IncludeOptions {
+    mode?: "inline" | "template";
+    /** Directory of the page being converted: relative `?raw` imports resolve against it. */
+    pageDir?: string;
+    /** Product for a `<Render>` with no `product=` (the page's own). */
+    defaultProduct?: string;
+    /** Called for every partial reference emitted as a directive, with the parameter names it passes. */
+    onTemplateInclude?: (ref: {
+        product: string;
+        file: string;
+        params: string[];
+    }) => void;
+    /** Where emitted directives are registered, so they survive the MDX parse (template-tokens.ts). */
+    directives?: DirectiveTable;
+    /** `props.x` names read by param values (a partial forwarding its own parameters), for its `params:`. */
+    names?: Set<string>;
+    /** Called for every partial inlined in template mode because its params are outside the convertible subset. */
+    onInlined?: (ref: {
+        product: string;
+        file: string;
+        reason: string;
+    }) => void;
+    /** Called for every Cloudflare `<APIRequest>`: converted to a curl block, or left (and reported) when its props cannot be read. */
+    onApiRequest?: (converted: boolean) => void;
+    /**
+     * The Cloudflare API's operations (`--api-schema`), by `METHOD /path`:
+     * what `<APIRequest>` reads from the OpenAPI schema upstream.
+     */
+    apiSchema?: Map<string, ApiOperation>;
+    /** An `<APIRequest>` whose operation the schema does not have. */
+    onApiMissing?: (key: string) => void;
+    /** Called for every component converted to a DECLARED lesser form (`<GitHubCode>` → a link to the source). */
+    /** `how`: what the lesser form is, shown in the report. */
+    onDegraded?: (tag: string, how: string) => void;
 }

package/dist/adapters/cloudflare.d.ts

@@ -6,5 +6,187 @@
  *
  * Source: https://github.com/cloudflare/cloudflare-docs/tree/production/src/components
  */
-import type { SiteAdapter } from "../adapter.js";
+import type { ApiOperation, SiteAdapter } from "../adapter.js";
+import type { TreeNode } from "@dogsbay/types";
+/**
+ * Page-level string constants: `export const x = "…";` (or a backtick
+ * template with no `${}`), used as `{x}`, `<Code code={x} lang="…" />` or
+ * `<Markdown text={x} />`. ESM is never rendered, but nothing read it: the
+ * statement showed as text, `{owaspCrsVersion}` literally, and a JSON-mode
+ * page's three code samples were missing (5 pages). Other values are left
+ * alone.
+ */
+export declare function resolvePageConstants(source: string): string;
+/**
+ * A `<LinkButton>` inside RAW HTML (a `<DashButton>` in an `<ol><li>`, which
+ * becomes a LinkButton above) is not a component there, it is a leaked tag.
+ * In HTML the button is a link: `<a href>label</a>`.
+ */
+export declare function linkButtonsInHtml(tree: TreeNode[]): TreeNode[];
+/** `<Render …/>` tags outside code, as [start, end) offsets; mid-line tags included. */
+export declare function findRenderTags(src: string): Array<[number, number]>;
+/**
+ * The indent a directive may keep where the tag stood. In MDX, whitespace
+ * before a JSX element means nothing — Cloudflare writes
+ * `         <Render …/>` inside a <TabItem> after unindented prose. In
+ * Markdown four spaces after a blank line open an INDENTED CODE BLOCK, and
+ * the include came out as a literal code sample. So the indent is capped at
+ * the content column of the previous non-blank line: a list item's text
+ * column (the directive stays in the item), otherwise that line's indent.
+ */
+export declare function markdownIndent(source: string, offset: number, indent: string): string;
+/**
+ * Cloudflare's plan components, from `src/content/plans/index.json` at
+ * import, outside fenced and inline code. An unknown id leaves the tag, which
+ * is reported (both are lossy strips in the component map).
+ */
+export declare function resolvePlans(source: string, partialsDir?: string): string;
+/**
+ * `<Plan type="…" />` → its label, `<Plan id="a.b.c" />` → that string from
+ * `plans/index.json` — in bold, as the component's emphasised line (a
+ * `<div>`: alone on its line it ends its paragraph). The old transform
+ * printed the raw type (`**ent-add-on plan**`) and never read `id=` (7
+ * reported). An unresolved tag is left to the parser: alone on a line it is
+ * dropped and reported as an unknown component; mid-line the leak scan
+ * reports it.
+ */
+export declare function resolvePlanBadges(source: string, partialsDir?: string): string;
+/**
+ * `<AvailableNotifications product notificationFilter />` → a `<Details>`
+ * per notification (grouped under `##` product headings when unfiltered), as
+ * AvailableNotifications.astro renders, from `notifications/index.yaml`. The
+ * Details go through the normal component mapping.
+ */
+export declare function resolveNotifications(source: string, partialsDir?: string): string;
+/**
+ * `<PagesBuildPreset framework />` → its configuration table, and
+ * `<PagesBuildPresetsTable />` → every preset, as the components render them,
+ * from `pages-framework-presets/index.yaml`. An unknown framework leaves the
+ * tag, which is reported.
+ */
+export declare function resolvePagesPresets(source: string, partialsDir?: string): string;
+/**
+ * `<GitHubCode repo commit file lines tag lang />` fetches a file from GitHub
+ * at build time and shows it (or its `lines`, or a tagged region). An import
+ * does not reach the network, so it becomes a LINK to exactly that file at
+ * that commit (and those lines), and is counted as degraded — the reader
+ * can still get the code; the page no longer shows it.
+ */
+export declare function resolveGitHubCode(source: string, onDegraded?: (tag: string, how: string) => void): string;
+/**
+ * `<AutoconfigDiagram framework configs={[…]}>` draws DATA — the framework,
+ * the configuration Wrangler generates, Workers — so it becomes that sentence
+ * and a File / Setting / Value table (nothing lost, not reported). Other
+ * diagrams are illustrations: the CLI's `describeComponent` keeps the
+ * description their component declares, reported as degraded.
+ */
+export declare function resolveDiagrams(source: string): string;
+/**
+ * `<TypeScriptExample omitTabs>` inside a `<Tabs>` contributes its tabs to
+ * THAT group (upstream: JavaScript, generated from the TypeScript, then
+ * TypeScript). Stripped like the plain form, it left a bare code block as a
+ * direct child of the tab group, which broke the group. It becomes a
+ * TypeScript tab; the JavaScript variant is not generated by the import.
+ */
+export declare function resolveOmitTabsTypeScript(source: string): string;
+/**
+ * Three small components over LOCAL data, read at import:
+ * - `<RSSButton href|changelog text?>` → a link (it renders one).
+ * - `<WARPReleases track>` → the latest release open and the rest in a
+ *   collapsed history, from `src/content/warp-releases/<track>/*.yaml`.
+ *   Upstream keeps the releases of the year before NOW; an import keeps the
+ *   year before the LATEST release, so the output does not depend on the day
+ *   it runs. The Linux distribution picker becomes one link per distribution.
+ * - `<CompatibilityFlags experimental?>` → each flag (`src/content/
+ *   compatibility-flags/*.md`) as a heading, its dates and flags, and its
+ *   body, newest first.
+ * Anything unreadable leaves the tag, which is reported.
+ */
+export declare function resolveLocalDataComponents(source: string, partialsDir?: string): string;
+/**
+ * The value of `const NAME = [ … ]` / `{ … }` in a component or TS source,
+ * read with the no-eval literal reader. Brackets are matched OUTSIDE strings
+ * and comments (a `]` in a description must not end the array).
+ */
+export declare function readConstLiteral(src: string, name: string): unknown;
+/**
+ * The agent-setup pages (8): `<AgentHeader slug>`, `<OtherAgents currentSlug>`,
+ * `<ExamplePromptsList />`, `<RandomPrompt />` and `<PlatformAccess />`, from
+ * `components/agent-setup/{agents,prompts,definitions}.ts` and the section's
+ * own markup, read — never run. Upstream picks prompts at RANDOM per build;
+ * an import picks deterministically (the first ones). The skills and MCP
+ * server lists inside `<PlatformAccess>` are fetched at build time upstream,
+ * so they become links to where those lists live (reported as degraded).
+ */
+export declare function resolveAgentSetup(source: string, partialsDir?: string, onDegraded?: (tag: string, how: string) => void): string;
+/**
+ * `<BuildAgentsCallout />` → its intro sentence and its cards, read from the
+ * component's own source (`const cards = [ … ]`, by the no-eval literal
+ * reader; the sentence is its first `<p>`). A component that cannot be read
+ * leaves the tag, which is reported.
+ */
+export declare function resolveBuildAgentsCallout(source: string, partialsDir?: string): string;
+/**
+ * `<Image src={x} alt="…" />` → `![alt](path)`, where `x` is an image the
+ * source IMPORTS (`import x from "~/assets/…png"`). A relative import is
+ * resolved against `file` and, under an `assets/` folder, rewritten to the `~/assets`
+ * alias (which becomes `/_assets` later). Unresolvable ones are left.
+ */
+export declare function resolveImageImports(source: string, file?: string): string;
+/**
+ * `<ProductChangelog product="x" hideEntry publish_future_dated_entry numberOfEntries />`
+ * (or `area="Group"`, via the product directory's `entry.group`) → the
+ * product's changelog entries, newest first: `## date`, **title**, and the
+ * entry's MDX body spliced in, so its components are resolved like the
+ * page's own (this runs first in resolveIncludes). As upstream: hidden entries
+ * and future-dated ones are left out, `hideEntry` names one to skip. Not
+ * carried: the RSS button, per-entry product pills, WARP release entries.
+ */
+export declare function resolveProductChangelog(source: string, partialsDir?: string): string;
+/**
+ * `<ProductReleaseNotes />` → the page's release notes (its front matter
+ * `release_notes_file_name`, from `release-notes/<name>.yaml`), newest date
+ * first, as ProductReleaseNotes.astro renders. An entry with its own page
+ * links to it: upstream EMBEDS that page's body, which would duplicate a page
+ * the site already has. `api-deprecations` is its own file, as upstream.
+ */
+export declare function resolveReleaseNotes(source: string, partialsDir?: string, frontmatter?: Record<string, unknown>): string;
+/**
+ * Cloudflare's glossary components, from the glossary data at import:
+ * - `<GlossaryDefinition term prepend>` → the definition itself;
+ * - `<Glossary product>` → a table of terms (a Product column when unfiltered);
+ * - `<GlossaryTooltip term link>text</…>` → the text, linked when `link` is a
+ *   string. The tooltip itself cannot travel to a static page.
+ * An unknown term leaves the tag as written, so it is REPORTED as unmapped
+ * rather than silently becoming nothing. Code is left alone.
+ */
+export declare function resolveGlossary(source: string, partialsDir?: string): string;
+/**
+ * `<APIRequest path method parameters json form />` → the curl command
+ * Cloudflare's component renders (APIRequest.astro + CURL.astro), built
+ * from the tag's own props. The component also fetches the OpenAPI schema
+ * over the network at build time, for two things we therefore do not
+ * produce: the "Required API token permissions" panel, and the block title
+ * (the operation summary). An import does not reach the network.
+ *
+ * Without the schema, a parameter is a PATH parameter when the path names it
+ * (`{zone_id}`) and a query parameter otherwise; unfilled path parameters
+ * become `$ZONE_ID`, as upstream writes them; auth is the API token (what
+ * nearly every operation takes). A tag whose props cannot be READ (a
+ * variable, a spread) is left as written and reported, never guessed.
+ *
+ * With the schema (`--api-schema <openapi.json>`, a local copy — the import
+ * still does not fetch): the operation summary titles the block, the auth
+ * headers follow the operation's security (email + key where it takes no
+ * token), and `roles` adds the "Required API token permissions" panel,
+ * filtered by a `roles="…"` string as upstream filters it.
+ */
+export declare function resolveApiRequest(source: string, onApiRequest?: (converted: boolean) => void, schema?: Map<string, ApiOperation>, onMissing?: (key: string) => void): string;
+/**
+ * Each run of consecutive `rtk-snippet` siblings → one `tabs` group, synced
+ * on `realtimekit-sdk`, one tab per SDK. A snippet for several SDKs appears
+ * in each of their tabs, so picking an SDK in any group shows its code in
+ * every group. Recursive: snippets also sit in list items and steps.
+ */
+export declare function groupRtkSnippets(nodes: TreeNode[]): TreeNode[];
 export declare const cloudflareAdapter: SiteAdapter;