blume 2.1.3 → 2.2.1

package/src/markdown/title-heading.ts

@@ -0,0 +1,134 @@
+/**
+ * The heading a page's title came from. A page without a frontmatter `title`
+ * takes the text of its first `#` heading as its title (`deriveTitle` in
+ * `core/sources/normalize.ts`), and the page template renders that title as
+ * the page's `<h1>`, so a page that opens with the heading showed it twice,
+ * one above the other. This Satteri hast plugin drops that opening `<h1>`
+ * from such a page. Only a Markdown heading with nothing rendered before it
+ * counts: a raw HTML or JSX `<h1>` isn't the scan's heading, and one after
+ * other content stays where it is. A page in a mode without page chrome
+ * (`custom`, `frame`) renders no title, so its heading stays too.
+ *
+ * It runs after `heading-anchors`, so every other heading keeps the id the
+ * scan gave it (`setup`, `setup-1`): only the title's own element goes. Its
+ * id doesn't: the anchor index lists it, and links to `#setup` still land,
+ * because the dropped heading's id goes out through the render's front matter
+ * under {@link TITLE_ID_KEY}, which the page template sets on its `<h1>`.
+ */
+
+import { pageModeLayout } from "../core/page-modes.ts";
+import type { PageMode } from "../core/page-modes.ts";
+
+/**
+ * Front matter key carrying the id of the heading this plugin dropped out of
+ * a render. The page template reads it back via `remarkPluginFrontmatter` and
+ * gives the title `<h1>` it renders in the heading's place that id.
+ */
+export const TITLE_ID_KEY = "blumeTitleId";
+
+/** A minimal hast node (avoids a hast type dependency). */
+interface HastNode {
+  children?: HastNode[];
+  /** An element's properties: a heading's `id` is the slug `heading-anchors` set. */
+  properties?: { id?: string };
+  type: string;
+  value?: string;
+}
+
+/** The front matter keys this plugin reads and writes. */
+interface TitleFrontmatter {
+  [TITLE_ID_KEY]?: string;
+  mode?: PageMode;
+  title?: string;
+}
+
+/** The slice of Satteri's hast visitor context this plugin reads. */
+interface TitleHeadingContext {
+  data?: { astro?: { frontmatter?: TitleFrontmatter } };
+  indexOf: (node: HastNode) => number | undefined;
+  parent: (node: HastNode) => HastNode | undefined;
+  removeNode: (node: HastNode) => void;
+}
+
+/** A Satteri hast plugin, typed structurally to avoid a Satteri dep. */
+export interface TitleHeadingPlugin {
+  before: (root: HastNode, ctx: TitleHeadingContext) => void;
+  name: string;
+  element: {
+    filter: string[];
+    visit: (node: HastNode, ctx: TitleHeadingContext) => void;
+  };
+}
+
+// An MDX expression that is only a comment, `{/* … */}`, and raw HTML that is
+// only a comment, `<!-- … -->`.
+const COMMENT_EXPRESSION = /^\s*\/\*[\s\S]*\*\/\s*$/u;
+const HTML_COMMENT = /^\s*<!--[\s\S]*-->\s*$/u;
+
+/** Whether a node renders nothing: whitespace, a comment, or an MDX import. */
+const rendersNothing = (node: HastNode): boolean => {
+  switch (node.type) {
+    case "comment":
+    case "mdxjsEsm": {
+      return true;
+    }
+    case "text": {
+      return (node.value ?? "").trim() === "";
+    }
+    case "mdxFlowExpression": {
+      return COMMENT_EXPRESSION.test(node.value ?? "");
+    }
+    case "raw": {
+      return HTML_COMMENT.test(node.value ?? "");
+    }
+    default: {
+      return false;
+    }
+  }
+};
+
+// The renders whose first `<h1>` has been seen. The plugin instance is shared
+// across every page; the render-scoped `astro` data object is a stable,
+// unique key for one render (as in `heading-anchors`).
+const seen = new WeakSet<object>();
+
+export const titleHeadingPlugin = (): TitleHeadingPlugin => ({
+  // A render of an entry Astro rendered before can get the front matter
+  // object that render wrote to, so a heading dropped then leaves no id.
+  before(_root, ctx) {
+    const frontmatter = ctx.data?.astro?.frontmatter;
+    if (frontmatter) {
+      Reflect.deleteProperty(frontmatter, TITLE_ID_KEY);
+    }
+  },
+  element: {
+    filter: ["h1"],
+    visit(node, ctx) {
+      const astro = ctx.data?.astro;
+      const frontmatter = astro?.frontmatter;
+      if (
+        !(astro && frontmatter) ||
+        frontmatter.title ||
+        node.type !== "element" ||
+        seen.has(astro)
+      ) {
+        return;
+      }
+      seen.add(astro);
+      const parent = ctx.parent(node);
+      const before = parent?.children?.slice(0, ctx.indexOf(node) ?? 0) ?? [];
+      if (
+        parent?.type === "root" &&
+        before.every(rendersNothing) &&
+        pageModeLayout(frontmatter.mode).chrome
+      ) {
+        const id = node.properties?.id;
+        if (id) {
+          frontmatter[TITLE_ID_KEY] = id;
+        }
+        ctx.removeNode(node);
+      }
+    },
+  },
+  name: "blume:title-heading",
+});

package/src/migrate/migrate.ts

@@ -19,17 +19,41 @@ export const MIGRATE_SOURCES = [
   "docusaurus",
   "starlight",
   "nextra",
+  "vitepress",
+  "vuepress",
+  "docus",
+  "mkdocs",
+  "mdbook",
+  "fern",
+  "gitbook",
+  "redocly",
+  "readme",
+  "docsify",
+  "jekyll",
+  "github-wiki",
 ] as const;
 
 export type MigrateSourceId = (typeof MIGRATE_SOURCES)[number];
 
 /** Display names, for messages and the prompt. */
 export const MIGRATE_SOURCE_NAMES: Record<MigrateSourceId, string> = {
+  docsify: "Docsify",
+  docus: "Docus",
   docusaurus: "Docusaurus",
+  fern: "Fern",
   fumadocs: "Fumadocs",
+  gitbook: "GitBook",
+  "github-wiki": "GitHub Wiki",
+  jekyll: "Jekyll",
+  mdbook: "mdBook",
   mintlify: "Mintlify",
+  mkdocs: "MkDocs",
   nextra: "Nextra",
+  readme: "ReadMe",
+  redocly: "Redocly",
   starlight: "Starlight",
+  vitepress: "VitePress",
+  vuepress: "VuePress",
 };
 
 /** The skill's directory inside the published package. */
@@ -72,7 +96,9 @@ const dependencyNames = async (root: string): Promise<Set<string>> => {
 
 /**
  * Each source's tell, in the order the skill's workflow checks them: a config
- * file the framework owns, or a dependency only it installs.
+ * file the framework owns, or a dependency only it installs. A GitHub wiki
+ * clone has neither (its tell is the `.wiki.git` remote), so `github-wiki` is
+ * named-only.
  */
 const SIGNALS: {
   deps?: string[];
@@ -96,6 +122,93 @@ const SIGNALS: {
   },
   { deps: ["nextra"], source: "nextra" },
   { deps: ["@astrojs/starlight"], source: "starlight" },
+  // The config usually sits in docs/.vitepress, often with the dependency in
+  // docs/package.json rather than the root one.
+  {
+    deps: ["vitepress"],
+    files: [".vitepress", "docs/.vitepress"].flatMap((dir) =>
+      ["ts", "mts", "js", "mjs"].map((ext) => `${dir}/config.${ext}`)
+    ),
+    source: "vitepress",
+  },
+  // v1 also reads YAML and TOML configs; v2 also reads vuepress.config.* from
+  // the directory it runs in. vuepress-vite and vuepress-webpack were the v2
+  // beta wrappers.
+  {
+    deps: ["vuepress", "vuepress-vite", "vuepress-webpack"],
+    files: [
+      ...[".vuepress", "docs/.vuepress"].flatMap((dir) =>
+        ["ts", "js", "mjs", "yml", "toml"].map((ext) => `${dir}/config.${ext}`)
+      ),
+      "vuepress.config.ts",
+      "vuepress.config.js",
+      "vuepress.config.mjs",
+    ],
+    source: "vuepress",
+  },
+  // The Nuxt docs theme (not Docusaurus); 1.x shipped as @nuxt-themes/docus.
+  { deps: ["docus", "@nuxt-themes/docus"], source: "docus" },
+  // MkDocs and the tools that build its projects (Zensical, ProperDocs). They
+  // come after the JavaScript frameworks, so a stale mkdocs.yml doesn't win.
+  {
+    files: [
+      "mkdocs.yml",
+      "mkdocs.yaml",
+      "zensical.toml",
+      "properdocs.yml",
+      "properdocs.yaml",
+    ],
+    source: "mkdocs",
+  },
+  // A code repo usually keeps its book in a subfolder.
+  {
+    files: ["book.toml", "docs/book.toml", "book/book.toml"],
+    source: "mdbook",
+  },
+  // Not fern.config.json alone: plenty of repos run Fern only to generate SDKs.
+  { files: ["fern/docs.yml"], source: "fern" },
+  // Not SUMMARY.md (mdBook and HonKit books have one too) or book.json (too
+  // generic a name).
+  {
+    deps: ["honkit", "gitbook-cli"],
+    files: ["gitbook-docs.yaml", ".gitbook.yaml", ".gitbook.yml"],
+    source: "gitbook",
+  },
+  // After the config-file sources, and never on redocly.yaml alone: that file
+  // is just as often Redocly CLI lint config in a repo built with another
+  // framework.
+  {
+    deps: [
+      "@redocly/realm",
+      "@redocly/redoc",
+      "@redocly/revel",
+      "@redocly/reef",
+      "@redocly/redoc-revel",
+      "@redocly/redoc-reef",
+      "@redocly/revel-reef",
+    ],
+    files: ["sidebars.yaml"],
+    source: "redocly",
+  },
+  // ReadMe's bi-directional Git sync; repos that only push with the rdme CLI
+  // leave no tell, so those are named-only.
+  {
+    files: [
+      "docs/_order.yaml",
+      "reference/_order.yaml",
+      "recipes/_order.yaml",
+      "custom_pages/_order.yaml",
+    ],
+    source: "readme",
+  },
+  // A Docsify site is an index.html that loads the library from a CDN, so only
+  // the ones with a manifest give themselves away. Not _sidebar.md: on a
+  // case-insensitive filesystem it also matches a GitHub wiki's _Sidebar.md.
+  { deps: ["docsify-cli", "docsify"], source: "docsify" },
+  // Last: _config.yml is a generic name (Hexo and Jupyter Book use it too), so
+  // every more specific tell wins first, and the reference says how to spot
+  // the others.
+  { files: ["_config.yml", "docs/_config.yml"], source: "jekyll" },
 ];
 
 /**
@@ -120,6 +233,15 @@ export const detectMigrateSource = async (
   return null;
 };
 
+/**
+ * The prompt's URL rule, where a source can't follow the default: a GitHub
+ * wiki's old URLs stay on github.com, where no redirect can reach them.
+ */
+const URL_RULES: Partial<Record<MigrateSourceId, string>> = {
+  "github-wiki":
+    "Keep every content page. The old wiki URLs stay on github.com and can't be redirected, so map them with the reference's route table and link stubs instead: add no `redirects`, and never push to the wiki; prepare the stubs for the user.",
+};
+
 /**
  * The handoff prompt: follow the skill, where its mappings for this source
  * are, and the few rules worth restating — the target version, and that no
@@ -139,11 +261,14 @@ export const migratePrompt = (options: {
   const sourceLine = source
     ? `The source is ${MIGRATE_SOURCE_NAMES[source]}${evidence}. Its exact mappings are in ${join(skillDir, "references", `${source}.md`)}.`
     : `The source framework wasn't detected, so inventory the repo first. If it's ${MIGRATE_SOURCES.map((id) => MIGRATE_SOURCE_NAMES[id]).join(", ")}, read that framework's file in ${join(skillDir, "references")}; otherwise follow the skill's mental model directly.`;
+  const urlRule =
+    (source && URL_RULES[source]) ??
+    "Keep every page, and add a redirect for any URL that moves.";
   return `Migrate this documentation project to Blume ${version}.
 
 Follow the blume-migrate skill: read ${join(skillDir, "SKILL.md")} first and work through its migration workflow. Wherever the skill says \`<skill>\`, it means ${skillDir}.
 
 ${sourceLine}
 
-Add \`blume@^${version}\` as the docs package's dependency. Keep every page, and add a redirect for any URL that moves. Report everything you drop or approximate, and run the skill's verification steps before you finish.`;
+Add \`blume@^${version}\` as the docs package's dependency. ${urlRule} Report everything you drop or approximate, and run the skill's verification steps before you finish.`;
 };

package/src/og/card.ts

@@ -52,9 +52,10 @@ export type OgFont =
 export type OgGoogleFont = Exclude<OgFont, OgLocalFont>;
 
 /**
- * Which loaded family each card role renders in. Takumi still falls back
- * across every loaded font per glyph, so a family that misses a script
- * degrades to the rest of the chain instead of tofu.
+ * Which loaded family each card role renders in, by plain family name (the
+ * card quotes it for the renderer). Takumi still falls back across every
+ * loaded font per glyph, so a family that misses a script degrades to the
+ * rest of the chain instead of tofu.
  */
 export interface OgFontFamilies {
   /** Family for the description and footer text. */
@@ -423,9 +424,18 @@ const titleSize = (title: string): number => {
   return 76;
 };
 
+/**
+ * `family` as a quoted CSS string. Takumi parses `fontFamily` with the CSS
+ * grammar, where an unquoted family must be a run of identifiers, so a name
+ * with a token that starts with a digit ("Source Sans 3", "3270") fails the
+ * render. A quoted string accepts any name, escaped per CSS.
+ */
+const cssFamilyName = (family: string): string =>
+  `"${family.replaceAll(/["\\]/gu, "\\$&")}"`;
+
 /** A spreadable `fontFamily` style, empty when no family is configured. */
 const familyStyle = (family?: string): { fontFamily?: string } =>
-  family ? { fontFamily: family } : {};
+  family ? { fontFamily: cssFamilyName(family) } : {};
 
 /** Render a 1200x630 Open Graph card to a PNG buffer. */
 export const renderOgImage = async (

package/src/openapi/asyncapi.ts

@@ -1,4 +1,8 @@
-import type { ApiOperationRef, ApiTagRef } from "./model.ts";
+import type {
+  ApiOperationRef,
+  ApiTagMeta,
+  CollectedOperations,
+} from "./model.ts";
 import { operationCollector, operationKey } from "./model.ts";
 
 /**
@@ -285,10 +289,11 @@ const operationSite = (
   return { action, address: channelAddress(channelId, channel), channelId };
 };
 
-/** The route-mapped operations, ordered tags, and skip warnings of one document. */
-export interface AsyncApiOperationCatalog {
-  operations: ApiOperationRef[];
-  tags: ApiTagRef[];
+/**
+ * The route-mapped operations, ordered tags, moved routes, and skip warnings
+ * of one document.
+ */
+export interface AsyncApiOperationCatalog extends CollectedOperations {
   warnings: string[];
 }
 
@@ -315,7 +320,10 @@ export const extractAsyncApiOperations = (
         (tag): tag is { name: string; description?: string } =>
           typeof tag?.name === "string"
       )
-      .map((tag): [string, string] => [tag.name, tag.description ?? ""])
+      .map((tag): [string, ApiTagMeta] => [
+        tag.name,
+        { description: tag.description ?? "" },
+      ])
   );
   const collector = operationCollector(baseRoute, tagMeta);
   const channels = document.channels ?? {};

package/src/openapi/checks.ts

@@ -1,7 +1,10 @@
 import type { OperationObject } from "@scalar/openapi-types/3.2";
 
+import type { JsonValue } from "../core/adapter.ts";
+import type { AsyncApiSpecValue } from "./asyncapi.ts";
 import type { ApiDocument } from "./model.ts";
-import { HTTP_METHODS } from "./model.ts";
+import { HTTP_METHODS, operationLabel, withServerDefaults } from "./model.ts";
+import { isJsonObject } from "./overlay.ts";
 
 /**
  * Targeted checks for spec mistakes that would otherwise render silently
@@ -32,19 +35,6 @@ const NAMED_OPERATIONS = 3;
 /** One entry of a document's `paths` or `webhooks` map. */
 type PathItem = NonNullable<ApiDocument["paths"]>[string];
 
-/**
- * How a warning names an operation: `GET /pets`, or a webhook by its name
- * (`Webhook "newPet" (POST)`), since a webhook has no path.
- */
-export const operationLabel = (
-  name: string,
-  method: string,
-  webhook: boolean
-): string =>
-  webhook
-    ? `Webhook "${name}" (${method.toUpperCase()})`
-    : `${method.toUpperCase()} ${name}`;
-
 /** One entry of a `parameters` list: a parameter, or a `$ref` to one. */
 type ParameterEntry = NonNullable<OperationObject["parameters"]>[number];
 
@@ -209,6 +199,66 @@ const xWebhooksIssues = (document: ApiDocument): SpecIssue[] =>
       ]
     : [];
 
+/**
+ * A loopback or unspecified host (`localhost`, `127.0.0.1`, `0.0.0.0`,
+ * `[::1]`): one only the machine that wrote the spec can reach.
+ */
+const LOCAL_HOST =
+  /^(?:localhost|.+\.localhost|127(?:\.\d{1,3}){3}|0\.0\.0\.0|\[::1?\])$/u;
+
+/** One `servers` entry, as a hand-written spec may have written it. */
+type ServerEntry = NonNullable<ApiDocument["servers"]>[number];
+
+/** A server's URL, variables at their defaults, when its host is local. */
+const localServerUrl = (server: ServerEntry): string | undefined => {
+  if (!isName(server.url)) {
+    return undefined;
+  }
+  // SAFETY: a parsed spec is JSON, and `withServerDefaults` checks the shape
+  // of the `variables` map it reads.
+  const variables = server.variables as AsyncApiSpecValue;
+  const url = withServerDefaults(server.url, variables);
+  try {
+    return LOCAL_HOST.test(new URL(url).hostname) ? url : undefined;
+  } catch {
+    // A relative URL (`/v1`) or an unresolved variable names no host.
+    return undefined;
+  }
+};
+
+/**
+ * Servers the spec, a path, or an operation declares at a local address,
+ * which a framework exporting its spec from a dev machine writes (Laravel's
+ * Scramble writes `http://localhost/api` from an `.env`-less CI run). The
+ * reference publishes it as the server Try it sends to and the code samples
+ * call, which no reader can reach. One warning per URL.
+ */
+const localServerIssues = (document: ApiDocument): SpecIssue[] => {
+  const lists = [
+    document.servers,
+    ...Object.values(document.paths ?? {}).flatMap((item) =>
+      isObject(item) && !("$ref" in item)
+        ? [
+            item.servers,
+            ...HTTP_METHODS.map((method) => {
+              const operation = item[method];
+              return isObject(operation) ? operation.servers : undefined;
+            }),
+          ]
+        : []
+    ),
+  ];
+  const urls = new Set(
+    lists.flatMap((servers) => listOf(servers).map(localServerUrl))
+  );
+  return [...urls].filter(isName).map((url) => ({
+    code: "BLUME_OPENAPI_LOCAL_SERVER",
+    message: `The spec's server ${url} is a local address, so the reference publishes it as the server Try it sends requests to and the code samples call, which readers can't reach.`,
+    suggestion:
+      "List the API's public URL in the spec's `servers`, or replace it with an overlay (an action with `target: $.servers[0]` and `update: { url: \"https://api.example.com\" }`).",
+  }));
+};
+
 /**
  * Check a parsed document for the mistakes above, and for the OpenAPI 3.2
  * features Blume doesn't render yet. `$ref` path items are skipped: the
@@ -269,5 +319,100 @@ export const specIssues = (document: ApiDocument): SpecIssue[] => {
   for (const [name, item] of Object.entries(document.webhooks ?? {})) {
     visit(name, item, true);
   }
-  return [...issues, ...securitySchemeIssues(document, requirers)];
+  return [
+    ...issues,
+    ...securitySchemeIssues(document, requirers),
+    ...localServerIssues(document),
+  ];
+};
+
+/** The OpenAPI versions that have no `nullable` keyword: 3.1 and later. */
+const NO_NULLABLE = /^3\.[1-9]/u;
+
+/**
+ * Keys whose values are data rather than schemas, so a `nullable` inside
+ * one belongs to an example. Extensions (`x-…`) are skipped too.
+ */
+const DATA_KEYS = new Set(["const", "default", "enum", "example", "examples"]);
+
+/**
+ * Keys whose values map names to objects: the names aren't keywords, so a
+ * property named `nullable` isn't the keyword, and a `default` response
+ * isn't a default value.
+ */
+const NAME_MAPS = new Set([
+  "$defs",
+  "definitions",
+  "dependentSchemas",
+  "patternProperties",
+  "properties",
+  "responses",
+  "schemas",
+]);
+
+/** A JSON Pointer reference token, `~` and `/` escaped (RFC 6901). */
+const pointerToken = (key: string): string =>
+  key.replaceAll("~", "~0").replaceAll("/", "~1");
+
+const isBoolean = (value: JsonValue): value is boolean =>
+  typeof value === "boolean";
+
+/**
+ * Where `node` sets `nullable` to a boolean, as JSON Pointers from
+ * `pointer`. `names` says `node`'s keys are names (see {@link NAME_MAPS}).
+ */
+const nullablePointers = (
+  node: JsonValue,
+  pointer: string,
+  names: boolean
+): string[] => {
+  if (Array.isArray(node)) {
+    return node.flatMap((item, index) =>
+      nullablePointers(item, `${pointer}/${index}`, false)
+    );
+  }
+  if (!isJsonObject(node)) {
+    return [];
+  }
+  return Object.entries(node).flatMap(([key, value]) => {
+    const at = `${pointer}/${pointerToken(key)}`;
+    if (names) {
+      return nullablePointers(value, at, false);
+    }
+    if (key === "nullable" && isBoolean(value)) {
+      return [at];
+    }
+    return DATA_KEYS.has(key) || key.startsWith("x-")
+      ? []
+      : nullablePointers(value, at, NAME_MAPS.has(key));
+  });
+};
+
+/**
+ * A spec written as OpenAPI 3.1 or later that still uses `nullable`, which
+ * 3.1 removed for `type: [T, "null"]`. Read as written (before Blume
+ * upgrades a 3.0 spec, which rewrites `nullable` itself), since that's the
+ * document the author edits. Blume still renders those values as nullable,
+ * but validators and SDK generators that follow 3.1 read them as never
+ * null. One warning per spec, naming the first few places.
+ */
+export const nullableIssues = (document: JsonValue): SpecIssue[] => {
+  const version =
+    isJsonObject(document) && isName(document.openapi) ? document.openapi : "";
+  if (!NO_NULLABLE.test(version)) {
+    return [];
+  }
+  const pointers = nullablePointers(document, "#", false);
+  if (pointers.length === 0) {
+    return [];
+  }
+  const more = pointers.length - NAMED_OPERATIONS;
+  return [
+    {
+      code: "BLUME_OPENAPI_NULLABLE",
+      message: `The spec is OpenAPI ${version}, which removed \`nullable\`, but sets it at ${pointers.slice(0, NAMED_OPERATIONS).join(", ")}${more > 0 ? ` and ${more} more` : ""}. Blume still shows those values as nullable, but tools that follow ${version}, like validators and SDK generators, read them as never null.`,
+      suggestion:
+        'Add "null" to the schema\'s `type` instead (`type: [string, "null"]`), or beside a `$ref`, use `anyOf` with `{ type: "null" }`. If the spec is really 3.0, declare `openapi: 3.0.3`, and Blume upgrades it.',
+    },
+  ];
 };