blume 2.1.0 → 2.1.1

package/dist/types/astro/pages.d.ts

@@ -29,6 +29,16 @@ export interface OgCustomRoute {
 export declare const hasGeneratedChangelog: (project: BlumeProject, userPages: {
     pattern: string;
 }[]) => boolean;
+/**
+ * Every route a navigation entry (a tab, selector item, featured link, header
+ * action, or CTA) may point at: content routes, custom `.astro` pages, the
+ * generated changelog, and reference routes (so a tab an author points at one
+ * still validates). `generateRuntime` and `blume doctor` both check
+ * `validateNavTargets` against it, so they flag the same entries.
+ */
+export declare const navTargetRoutes: (project: BlumeProject, userPages: {
+    pattern: string;
+}[]) => Set<string>;
 /**
  * Pick the custom-page routes that should get a generated Open Graph card, with
  * the card's slug and text. OG is otherwise content-route only, so a custom page

package/dist/types/cli/init/scaffold.d.ts

@@ -126,7 +126,7 @@ export interface PlanEnvironment {
  * What the project still needs from a workspace it sits in, when `init` left
  * that workspace's config alone: a place in a pnpm workspace's `packages`
  * (pnpm skips a folder it doesn't list), pnpm's approval for esbuild's build
- * script (pnpm 10 and later fail the install without it), or Yarn Berry's
+ * script (pnpm 11 and later fail the install without it), or Yarn Berry's
  * `node_modules` linker. Undefined when the workspace already has it, or the
  * project doesn't sit in one.
  */

package/dist/types/components/content/api-field.d.ts

@@ -32,7 +32,10 @@ export interface ParamFieldProps extends FieldProps {
     /** The name, for a field with no location attribute. */
     name?: string;
     path?: string;
-    /** Placeholder text for the parameter's playground input. */
+    /**
+     * An example value: the one the playground and request samples start
+     * with, not an input's placeholder hint (see `fieldSchema`).
+     */
     placeholder?: string;
     query?: string;
 }

package/dist/types/components/content/api-page.d.ts

@@ -74,10 +74,15 @@ export declare const endpointTarget: (target: string, server?: string) => Endpoi
 export declare const fieldSchema: (field: EndpointField) => SchemaLike;
 /** The path, query, and header fields as OpenAPI parameters. */
 export declare const endpointParameters: (fields: EndpointField[]) => ParameterLike[];
-/** The body fields as a JSON request body, or `undefined` when there are none. */
+/**
+ * The body fields as a JSON request body, or `undefined` when there are none.
+ * Its example, which the playground and samples start from, holds only the
+ * {@link sentFields}.
+ */
 export declare const endpointBody: (fields: EndpointField[]) => {
     content: {
         "application/json": {
+            example: import("../openapi/helpers.ts").SpecValue;
             schema: SchemaLike;
         };
     };

package/dist/types/components/openapi/code-samples.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Hand-written code samples from a spec: the `x-codeSamples` extension on an
+ * operation (Redocly's, which Mintlify, Speakeasy, and Stainless write too),
+ * or its older spelling `x-code-samples`. Each entry names a `lang`, holds
+ * the `source`, and may carry a `label`. They render as their own tabs ahead
+ * of the generated samples and, being fixed text, the playground leaves them
+ * as written.
+ */
+/** One hand-written sample, ready to render as a tab. */
+export interface CustomCodeSample {
+    /** A stable, unique tab key. */
+    key: string;
+    /** The tab label: the entry's own, else the language's name. */
+    label: string;
+    /** The Shiki language to highlight `source` with. */
+    lang: string;
+    source: string;
+}
+/** The two places an operation keeps them. */
+export interface CodeSamplesCarrier {
+    "x-code-samples"?: unknown;
+    "x-codeSamples"?: unknown;
+}
+/**
+ * The operation's hand-written samples, with a unique tab label each. A label
+ * two samples share gains its language (`List plants · JavaScript`), and one
+ * that still repeats gains a number. Malformed entries are skipped.
+ */
+export declare const customCodeSamples: (operation: CodeSamplesCarrier) => CustomCodeSample[];

package/dist/types/components/openapi/helpers.d.ts

@@ -73,13 +73,34 @@ export declare const resolveComponentRef: <T extends {
 export declare const mergeParameters: (pathParameters: ParameterLike[] | undefined, operationParameters: ParameterLike[] | undefined, components?: ComponentsLike) => ParameterLike[];
 /** The display name of a `$ref`, e.g. `#/components/schemas/Pet` -> `Pet`. */
 export declare const refName: (ref: string) => string;
-/** Resolve one level of `$ref` against the document's component schemas. */
+/**
+ * The one member of an `allOf` that only wraps it: `allOf: [{ $ref }]` beside
+ * a `description`, `readOnly`, or `default`, which is how drf-spectacular and
+ * other generators attach keywords a 3.0 `$ref` can't carry. `undefined` for
+ * a real composition: several members, or properties or branches of its own.
+ */
+export declare const soleAllOfMember: (schema: SchemaLike) => SchemaLike | undefined;
+/**
+ * Resolve one level of `$ref` against the document's component schemas. A
+ * single-member `allOf` wrapper resolves like its member, with the wrapper's
+ * own keywords on top: its `description` is about this field.
+ */
 export declare const resolveSchema: (schemas: Record<string, SchemaLike>, schema?: SchemaLike) => SchemaLike;
+/**
+ * A parameter's description: its own, else its schema's (resolved one `$ref`
+ * level), which is where generators like Elysia and oRPC write it.
+ */
+export declare const parameterDescription: (param: {
+    description?: string;
+    schema?: SchemaLike;
+}, schemas: Record<string, SchemaLike>) => string | undefined;
 /**
  * A short, human-readable type label for a schema row. `$ref`s label by name
  * (`Pet`, `Pet[]`) without resolving — which also means circular refs through
  * array items can't recurse forever. A `null` member stays out of a union's
  * label: rows mark it with {@link isNullable}, as they do `type: [T, "null"]`.
+ * A single-member `allOf` wrapper labels as its member; a real composition is
+ * an `object`.
  */
 export declare const typeLabel: (schema: SchemaLike) => string;
 /**

package/dist/types/components/openapi/security.d.ts

@@ -29,6 +29,11 @@ export interface ResolvedScheme {
     /** The scheme object; undefined when the requirement names an unknown one. */
     scheme?: SecuritySchemeLike;
     scopes: string[];
+    /**
+     * AsyncAPI: the servers that declare this scheme, set only when the
+     * channel's servers don't all declare the same ones.
+     */
+    servers?: string[];
 }
 /** The security state one operation renders. */
 export interface OperationSecurity {
@@ -36,6 +41,11 @@ export interface OperationSecurity {
     alternatives: ResolvedScheme[][];
     /** True when an empty requirement also allows unauthenticated calls. */
     optional: boolean;
+    /**
+     * AsyncAPI: the servers that declare no security while others do, so the
+     * schemes apply on the other servers only.
+     */
+    unauthenticatedServers?: string[];
 }
 /**
  * The requirement list an operation actually enforces: its own `security` when

package/dist/types/components/openapi/snippets.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Code-sample generation for an operation. Deliberately dependency-free: the
+ * playground client renders samples live in the browser, so this module must
+ * stay out of the server-only dependency graph (no helpers.ts, no
+ * openapi-sampler). Requests are assembled once by `buildRequest` in
+ * `request.ts`; the builders here only render a finished `RequestSample` as
+ * simple, copy-pasteable starter code — not an exhaustive SDK.
+ */
+export interface RequestSample {
+    method: string;
+    url: string;
+    headers: Record<string, string>;
+    /**
+     * The request body as sent, when the operation takes one: JSON text,
+     * form-urlencoded pairs, or a raw media type's text.
+     */
+    body?: string;
+    bodyValue?: unknown;
+    /**
+     * A `multipart/form-data` body's parts as `[name, value]` pairs, set
+     * instead of `body`. The request carries no Content-Type of its own for
+     * them: the client writes one with the parts' boundary.
+     */
+    formData?: [string, string][];
+}
+/**
+ * Whether fetch refuses to send `method` (an upper-case HTTP method). TRACE is
+ * one of the Fetch standard's forbidden methods, and the only one an OpenAPI
+ * spec can declare: browsers and Node's fetch alike throw a TypeError before
+ * any request goes out.
+ */
+export declare const fetchRefusesMethod: (method: string) => boolean;
+/** A code-sample language: config id -> label, Shiki lang, and builder. */
+export interface SampleLanguage {
+    id: string;
+    label: string;
+    lang: string;
+    build: (sample: RequestSample) => string;
+}
+/** Every id `codeSamples` accepts for a generated sample. */
+export declare const SAMPLE_LANGUAGE_IDS: string[];
+/** A configured id or alias, as the id it names (lowercased). */
+export declare const sampleLanguageId: (raw: string) => string;
+/** A language's display name and the Shiki language that highlights it. */
+export interface SampleLanguageInfo {
+    label: string;
+    lang: string;
+}
+/**
+ * The display name and Shiki language of a language id or alias, or `null`
+ * when Blume doesn't generate that language.
+ */
+export declare const sampleLanguageInfo: (raw: string) => SampleLanguageInfo | null;
+/** `openapi()`'s default `codeSamples`, which hand-written endpoint pages always use. */
+export declare const DEFAULT_SAMPLE_LANGUAGES: string[];
+/**
+ * The sample languages to render, resolved from config ids (unknown ids
+ * dropped), in order. `false` and an empty list both render none.
+ */
+export declare const sampleLanguages: (ids: string[] | false) => SampleLanguage[];

package/dist/types/core/changelog-index.d.ts

@@ -1,3 +1,4 @@
+import type { UIStrings } from "./i18n-ui.ts";
 import type { ResolvedConfig } from "./schema.ts";
 import type { PageRecord } from "./types.ts";
 /** Where the changelog timeline index is served. */
@@ -11,3 +12,10 @@ export declare const CHANGELOG_INDEX_ROUTE = "/changelog";
  * `/changelog` tab at the index rather than its newest entry.
  */
 export declare const hasChangelogIndex: (pages: Pick<PageRecord, "contentType" | "meta">[], config: ResolvedConfig) => boolean;
+/**
+ * A locale's UI strings with the index's title and description taken from
+ * the `changelog` config where it sets them (a string, or a per-locale map
+ * resolved like a header label), so every surface that reads the
+ * `changelog` strings (the page, its OG card, its Markdown mirror) agrees.
+ */
+export declare const withChangelogIndexText: (config: ResolvedConfig, ui: UIStrings, locale?: string) => UIStrings;

package/dist/types/core/config-input.d.ts

@@ -126,6 +126,18 @@ export interface FooterConfig {
      */
     socials?: Partial<Record<FooterSocial, string>>;
 }
+/**
+ * The generated `/changelog` index's heading and description. Each is a
+ * string, or a map of locale code to text; the index renders in the default
+ * locale. Unset, they're the `changelog` UI strings (`Changelog` in English),
+ * which `i18n.ui` translates.
+ */
+export interface ChangelogConfig {
+    /** The index's description, below its heading and in its meta description. */
+    description?: LocalizableLabel;
+    /** The index's heading, page title, and OG card title. */
+    title?: LocalizableLabel;
+}
 /**
  * Where content lives and how it's discovered. `root`/`include`/`exclude` are
  * zero-config shorthand for a single `filesystem()` source; set `sources` to
@@ -441,6 +453,16 @@ export interface SearchPopularLink {
 export type SearchProviderConfig = AnySearchAdapter | false;
 /** The object form of `search`: the adapter plus adapter-independent settings. */
 export interface SearchOptions {
+    /** What search reports to the configured analytics providers. */
+    analytics?: {
+        /**
+         * Send each query's text with the `search` and `search_select` events.
+         * Defaults to `true`. `false` sends the query's length (`queryChars`)
+         * instead, and the text rides only the `blume:track` DOM event, for a
+         * site to forward on its own terms.
+         */
+        queries?: boolean;
+    };
     /** Indexing behavior. */
     indexing?: {
         /**
@@ -463,7 +485,7 @@ export interface SearchOptions {
 /**
  * Search configuration. Pass an adapter directly (`search: algolia({…})`, or
  * `false`) as shorthand for the object form, which also carries `popular`
- * links and `indexing` settings.
+ * links and `indexing` and `analytics` settings.
  */
 export type SearchConfig = SearchProviderConfig | SearchOptions;
 /** An empty-state prompt shown before the first question to the assistant. */
@@ -1177,8 +1199,8 @@ export interface MarkdownConfig {
 export interface ReactConfig {
     /**
      * Auto-memoize React components/hooks with the React Compiler
-     * (`babel-plugin-react-compiler`). On by default whenever React is enabled;
-     * set to `false` to skip the compiler's babel pass. Defaults to `true`.
+     * (`oxc-transform-react`). On by default whenever React is enabled;
+     * set to `false` to skip the compiler pass. Defaults to `true`.
      */
     compiler?: boolean;
 }
@@ -1341,6 +1363,11 @@ export interface BlumeConfig {
      * compose: with both set, a page lands at `{deployment.base}/{basePath}/page`.
      */
     basePath?: string;
+    /**
+     * The generated `/changelog` index's title and description, each a string
+     * or a per-locale map. Unset, they're the `changelog` UI strings.
+     */
+    changelog?: ChangelogConfig;
     /**
      * Ask readers before analytics runs, with an adapter from `blume/consent`:
      * `native()` for Blume's own banner, or a hosted consent manager

package/dist/types/core/data.d.ts

@@ -264,6 +264,10 @@ export interface BlumeDataConfig {
     /** Repository URL for header/edit links, or `null`. */
     repoUrl: string | null;
     search: {
+        /** `search.analytics`: whether the dialog's events carry each query's text. */
+        analytics: {
+            queries: boolean;
+        };
         enabled: boolean;
         /** Resolved empty-state links; empty when unset (Search falls back to sidebar). */
         popular: {

package/dist/types/core/i18n-ui.d.ts

@@ -56,6 +56,7 @@ declare const uiStringsObject: z.ZodObject<{
     }, z.core.$strip>>;
     changelog: z.ZodPrefault<z.ZodObject<{
         description: z.ZodDefault<z.ZodString>;
+        empty: z.ZodDefault<z.ZodString>;
         title: z.ZodDefault<z.ZodString>;
     }, z.core.$strip>>;
     consent: z.ZodPrefault<z.ZodObject<{
@@ -227,6 +228,7 @@ export declare const uiStringsSchema: z.ZodPrefault<z.ZodObject<{
     }, z.core.$strip>>;
     changelog: z.ZodPrefault<z.ZodObject<{
         description: z.ZodDefault<z.ZodString>;
+        empty: z.ZodDefault<z.ZodString>;
         title: z.ZodDefault<z.ZodString>;
     }, z.core.$strip>>;
     consent: z.ZodPrefault<z.ZodObject<{

package/dist/types/core/links.d.ts

@@ -58,6 +58,12 @@ export interface FileRouteIndex {
      * into the reader's locale onto the fallback copy.
      */
     byDefaultNavPath: Map<string, string>;
+    /**
+     * A staged page's entry id (`<source>/<ref>`) → its route. A remote
+     * source's files have no path on disk, so a file link between two of them
+     * (`./02-errors.mdx`) resolves by entry id, as the rendered link does.
+     */
+    byEntryId: Map<string, string>;
 }
 /** The linking side of a file link: where the page's source lives. */
 export interface FileLinkBase {
@@ -90,6 +96,8 @@ export declare const validateLinks: (graph: ContentGraph, options: {
     i18n?: LocaleRouting | null;
     publicDir: string | null;
     checkExternal?: boolean;
+    /** External URLs not to request (`--ignore`). Internal links are always checked. */
+    ignore?: (url: string) => boolean;
     /** Configured redirects; their `from` paths count as valid link targets. */
     redirects?: {
         from: string;

package/dist/types/core/probe.d.ts

@@ -7,6 +7,8 @@ export interface ProbeResult {
     status?: number;
     timedOut?: boolean;
     error?: string;
+    /** The system error code behind a request that got no response (`ENOTFOUND`). */
+    code?: string;
     /** Whether the request was redirected before landing on `status`. */
     redirected?: boolean;
     /** The URL finally landed on, after following redirects. */

package/dist/types/core/project-graph.d.ts

@@ -48,4 +48,10 @@ export declare const scanProject: (root: string, options?: {
     overrides?: ConfigOverrides;
     /** Relocate the generated runtime (e.g. `.blume-verify` for isolation). */
     runtimeDir?: string;
+    /**
+     * Called with the resolved config before any source loads, so a command
+     * can report an unset secret ahead of a fetch that fails without it: a
+     * source that can't load fails the scan, and nothing after it runs.
+     */
+    beforeSources?: (config: ResolvedConfig) => void;
 }) => Promise<BlumeProject>;

package/dist/types/core/redirect-patterns.d.ts

@@ -115,11 +115,19 @@ export type CompiledRedirect = [
 ];
 /**
  * The pattern redirects among `redirects`, compiled for the server wrappers
- * and the dev server, in the order to try them. The `Location` template is
- * percent-encoded as the header needs; a capture is encoded when it's filled
- * (see {@link fillLocation}).
+ * and Vercel's routing config, in the order to try them. The `Location`
+ * template is percent-encoded as the header needs; a capture is encoded when
+ * it's filled (see {@link fillLocation}).
  */
 export declare const compileRedirects: (redirects: readonly RedirectEnds[]) => CompiledRedirect[];
+/**
+ * Every redirect among `redirects` compiled, exact paths first: a pattern as
+ * {@link compileRedirects} compiles it, an exact path as a rule matching
+ * just that path, a trailing slash optional. What the dev server answers
+ * with, where Astro's own handler would send an exact redirect to a page
+ * served by `[...slug]` as a `301` whatever its status.
+ */
+export declare const compileEveryRedirect: (redirects: readonly RedirectEnds[]) => CompiledRedirect[];
 /** A captured value, encoded for a `Location` header that must not grow a query or fragment. */
 export declare const encodeCapture: (value: string) => string;
 /** A `Location` template with its `$n` references filled from `match`. */