blume 2.1.3 → 2.2.0

package/src/core/code-fence-diagnostics.ts

@@ -0,0 +1,267 @@
+import type { Nodes } from "mdast";
+import { markdownToMdast, mdxToMdast } from "satteri";
+
+import {
+  MARKDOWN_BODY_FEATURES,
+  MDX_BODY_FEATURES,
+} from "../markdown/features.ts";
+import { isKnownLanguage, normalizeFence } from "../markdown/fence-language.ts";
+import {
+  metaTokens,
+  RUST_LANGUAGES,
+  RUST_META_KEYWORDS,
+} from "../markdown/fence-meta.ts";
+import { strippedLineOffset } from "./sources/normalize.ts";
+import type { SourceEntry } from "./sources/types.ts";
+import type { Diagnostic } from "./types.ts";
+
+type Code = Extract<Nodes, { type: "code" }>;
+
+/**
+ * Fence languages that render without a Shiki grammar on purpose: `math`,
+ * which Astro never highlights, and `package-install`, which `.mdx` turns
+ * into install tabs (and the docs describe as a plain block in `.md`).
+ */
+const BLUME_LANGUAGES: ReadonlySet<string> = new Set([
+  "math",
+  "package-install",
+]);
+
+/** A fence problem at a line of the parsed text, before it's placed in a file. */
+interface Finding {
+  code: string;
+  line: number;
+  message: string;
+  suggestion: string;
+}
+
+/** A fence option another docs tool reads and Blume doesn't. */
+interface ForeignOption {
+  /** Matches the option's token in the fence's info string. */
+  pattern: RegExp;
+  /** The fence languages the option belongs to; any language when unset. */
+  languages?: ReadonlySet<string>;
+  /** What comes of the option, since Blume ignores it. */
+  effect: string;
+  /** The Blume spelling, given the option's quoted value. */
+  instead: (value: string) => string;
+}
+
+/** `hl_lines="2 4-5"` → `{2,4-5}`: MkDocs separates lines with spaces. */
+const lineRange = (value: string): string =>
+  `{${value
+    .trim()
+    .split(/[\s,]+/u)
+    .join(",")}}`;
+
+const FOREIGN_OPTIONS: readonly ForeignOption[] = [
+  {
+    effect: "the block highlights no lines",
+    instead: (value) =>
+      `Put the lines in braces after the language instead: \`${lineRange(value)}\`.`,
+    pattern: /^hl_lines=["'](?<value>[^"']*)["']$/u,
+  },
+  {
+    effect: "the block shows no line numbers",
+    instead: (value) =>
+      `Write \`lineNumbers\` after the language instead.${
+        value.trim() === "1" ? "" : " Blume numbers every block from 1."
+      }`,
+    pattern: /^linenums=["'](?<value>[^"']*)["']$/u,
+  },
+  {
+    effect: "the block shows no line numbers",
+    instead: () => "Write `lineNumbers` after the language instead.",
+    pattern: /^showLineNumbers(?:\{\d*\})?$/u,
+  },
+  {
+    // Mintlify's. Like `showLineNumbers` and `wordWrap`, it never joins the
+    // title (see `markdown/fence-meta.ts`).
+    effect: "the block shows no line numbers",
+    instead: () =>
+      'Write `lineNumbers` after the language instead. To keep the word in the block\'s title, set the title with `title="…"`.',
+    pattern: /^lines$/u,
+  },
+  {
+    effect: "the block doesn't wrap its long lines",
+    instead: () => "Write `wrap` after the language instead.",
+    pattern: /^wordWrap$/u,
+  },
+  {
+    effect: "the block has no title",
+    instead: (value) => `Write \`title="${value}"\` instead.`,
+    pattern: /^filename=["'](?<value>[^"']*)["']$/u,
+  },
+  {
+    // rustdoc's and mdBook's, on a Rust fence. They never join the title.
+    effect:
+      "it does nothing: Blume shows a code block as static text, and never compiles, tests, or runs it",
+    instead: () => "Remove it.",
+    languages: RUST_LANGUAGES,
+    pattern: new RegExp(`^(?:${[...RUST_META_KEYWORDS].join("|")})$`, "u"),
+  },
+];
+
+/** The option `token` is in a fence whose language is `lang`, if any. */
+const foreignOption = (
+  token: string,
+  lang: string
+): { option: ForeignOption; value: string } | null => {
+  for (const option of FOREIGN_OPTIONS) {
+    const match = option.pattern.exec(token);
+    if (match && (option.languages?.has(lang) ?? true)) {
+      return { option, value: match.groups?.value ?? "" };
+    }
+  }
+  return null;
+};
+
+/** Whether a fence's language renders as the author meant: highlighted, or plain on purpose. */
+const rendersLanguage = (lang: string): boolean =>
+  isKnownLanguage(lang) || BLUME_LANGUAGES.has(lang);
+
+/** A fence's language and option tokens, as the renderer reads them. */
+const fenceParts = (
+  lang: string | null | undefined,
+  meta: string | null | undefined
+) => {
+  const fence = normalizeFence(lang, meta) ?? {
+    lang: lang ?? "",
+    meta: meta ?? null,
+  };
+  return { lang: fence.lang, meta: fence.meta, tokens: metaTokens(fence.meta) };
+};
+
+const unknownLanguage = (node: Code, line: number): Finding[] => {
+  const { lang } = fenceParts(node.lang, node.meta);
+  if (!lang || rendersLanguage(lang)) {
+    return [];
+  }
+  return [
+    {
+      code: "BLUME_UNKNOWN_CODE_LANGUAGE",
+      line,
+      message: `\`${lang}\` isn't a language Blume can highlight, so the code block renders as plain text.`,
+      suggestion:
+        'Use a Shiki language id or alias (https://shiki.style/languages), or `text` for plain text. Options like a title go after the language, as in `text title="notes.txt"`.',
+    },
+  ];
+};
+
+const foreignOptions = (node: Code, line: number): Finding[] => {
+  const { lang, tokens } = fenceParts(node.lang, node.meta);
+  // A fence with options and no language reads its first option as the
+  // language, so that token counts too.
+  return [node.lang ?? "", ...tokens].flatMap((token) => {
+    const found = foreignOption(token, lang);
+    if (!found) {
+      return [];
+    }
+    return [
+      {
+        code: "BLUME_CODE_FENCE_OPTION",
+        line,
+        message: `\`${token}\` isn't a Blume code block option, so ${found.option.effect}.`,
+        suggestion: found.option.instead(found.value),
+      },
+    ];
+  });
+};
+
+// A fence opener's info string: the text after a run of three or more
+// backticks or tildes. Matched anywhere in a line, so it also sees fences in
+// list items and quotes (and fence-like inline code, which the parse below
+// sorts out).
+const FENCE_INFO = /(?:`{3,}|~{3,})[\t ]*(?<info>[^`\n]*)/gu;
+
+/** Whether a fence's info string holds anything these checks report. */
+const suspectInfo = (info: string): boolean => {
+  const [lang, ...rest] = info.trim().split(/\s+/u);
+  if (!lang) {
+    return false;
+  }
+  const parts = fenceParts(lang, rest.join(" ") || null);
+  return (
+    !rendersLanguage(parts.lang) ||
+    [lang, ...parts.tokens].some(
+      (token) => foreignOption(token, parts.lang) !== null
+    )
+  );
+};
+
+const parse = (text: string, format: "md" | "mdx"): Nodes | null => {
+  try {
+    return format === "mdx"
+      ? mdxToMdast(text, { features: MDX_BODY_FEATURES })
+      : markdownToMdast(text, { features: MARKDOWN_BODY_FEATURES });
+  } catch {
+    return null;
+  }
+};
+
+/**
+ * The fence problems in a page body, in source order. The body is parsed as
+ * the renderer reads it, so a fence shown inside another code block never
+ * counts. A page is parsed only when an info string looks like one of these
+ * problems, so pages without one cost a scan. A body MDX can't parse fails to
+ * render anyway, with its own error.
+ */
+const fenceFindings = (text: string, format: "md" | "mdx"): Finding[] => {
+  const suspect = [...text.matchAll(FENCE_INFO)].some((match) =>
+    suspectInfo(match.groups?.info ?? "")
+  );
+  const tree = suspect ? parse(text, format) : null;
+  if (!tree) {
+    return [];
+  }
+  const found: Finding[] = [];
+  const walk = (node: Nodes): void => {
+    if (node.type === "code") {
+      const line = node.position?.start.line ?? 1;
+      found.push(...unknownLanguage(node, line), ...foreignOptions(node, line));
+    }
+    if ("children" in node) {
+      for (const child of node.children) {
+        walk(child);
+      }
+    }
+  };
+  walk(tree);
+  return found;
+};
+
+/**
+ * Warn about code fences that don't render as their author meant:
+ *
+ * - `BLUME_UNKNOWN_CODE_LANGUAGE`: a language Shiki doesn't know, so the block
+ *   renders as plain text. Shiki itself only logs a console line naming the
+ *   language, with no page or line.
+ * - `BLUME_CODE_FENCE_OPTION`: an option another docs tool reads, like MkDocs'
+ *   `hl_lines="2 3"`, Docusaurus' `showLineNumbers`, Mintlify's `lines`, or
+ *   rustdoc's `no_run`, which Blume ignores. None of them becomes part of the
+ *   block's title. The suggestion gives the Blume spelling, or says to remove
+ *   an option Blume has no use for.
+ *
+ * Lines point into the file the author wrote, a partial's own file for a
+ * fence an `<include>` brought in.
+ */
+export const codeFenceDiagnostics = (
+  entry: SourceEntry,
+  sourceName: string
+): Diagnostic[] => {
+  const page = entry.sourcePath ?? `${sourceName}:${entry.ref}`;
+  const offset =
+    entry.bodyLineOffset ?? strippedLineOffset(entry.raw, entry.body.text);
+  return fenceFindings(
+    entry.expanded?.text ?? entry.body.text,
+    entry.body.format
+  ).map(({ line, ...finding }) => {
+    const origin = entry.expanded?.origins[line - 1];
+    return {
+      ...finding,
+      file: origin?.file ?? page,
+      line: origin?.line ?? line + offset,
+      severity: "warning",
+    };
+  });
+};

package/src/core/code-fences.ts

@@ -12,37 +12,73 @@
  */
 const CODE_FENCE = /^(?<run>`{3,}|~{3,})/u;
 
-/** The open fence's delimiter char and run length, or null outside one. */
-export type FenceState = { delimiter: "`" | "~"; length: number } | null;
+// One block-quote marker. A fence inside a quote (`> ```ts`) is written after
+// one marker per level of nesting, and so is every line of its code.
+const QUOTE_MARKER = /^[ \t]*>/u;
+
+/**
+ * The open fence's delimiter char, its run length, and the block-quote depth
+ * it opened at, or null outside one.
+ */
+export type FenceState = {
+  delimiter: "`" | "~";
+  length: number;
+  quotes: number;
+} | null;
+
+/** Strip up to `max` leading block-quote markers from `line`. */
+const stripQuotes = (line: string, max: number) => {
+  let rest = line;
+  let depth = 0;
+  while (depth < max) {
+    const marker = QUOTE_MARKER.exec(rest);
+    if (!marker) {
+      break;
+    }
+    rest = rest.slice(marker[0].length);
+    depth += 1;
+  }
+  return { depth, rest };
+};
 
 /**
  * Advance the fenced-code state for one line: an opening fence records its
  * delimiter and run length, only a bare run of the same character at least as
  * long closes it (CommonMark), and any other line leaves the state untouched.
+ * A fence inside block quotes is read past the quote markers it opened under,
+ * and a line without them ends the quote, and the fence with it: code takes
+ * no lazy continuation lines (CommonMark).
  */
 export const nextFenceState = (line: string, fence: FenceState): FenceState => {
-  const trimmed = line.trimStart();
+  const { depth, rest } = stripQuotes(
+    line,
+    fence === null ? Number.POSITIVE_INFINITY : fence.quotes
+  );
+  if (fence !== null && depth < fence.quotes) {
+    return nextFenceState(line, null);
+  }
+  const trimmed = rest.trimStart();
   const run = trimmed.match(CODE_FENCE)?.groups?.run;
   if (run === undefined) {
     return fence;
   }
-  const rest = trimmed.slice(run.length);
+  const info = trimmed.slice(run.length);
   const delimiter = run.startsWith("`") ? ("`" as const) : ("~" as const);
   if (fence === null) {
     // A backtick fence's info string cannot itself contain a backtick
     // (CommonMark) — a line-leading ```inline``` span is a paragraph, and
     // opening a phantom fence on it would swallow every heading and link
     // after it. Tilde fences carry no such rule.
-    if (delimiter === "`" && rest.includes("`")) {
+    if (delimiter === "`" && info.includes("`")) {
       return fence;
     }
-    return { delimiter, length: run.length };
+    return { delimiter, length: run.length, quotes: depth };
   }
   // A closing fence may be followed only by whitespace: a same-length
   // ```js line inside an open ``` block is content, not a closer.
   return fence.delimiter === delimiter &&
     run.length >= fence.length &&
-    rest.trim() === ""
+    info.trim() === ""
     ? null
     : fence;
 };

package/src/core/component-diagnostics.ts

@@ -1,6 +1,6 @@
 import { relative } from "pathe";
 
-import { BUILTIN_MDX_TAGS } from "./builtin-tags.ts";
+import { BUILTIN_CHILD_PROPS, BUILTIN_MDX_TAGS } from "./builtin-tags.ts";
 import type { Diagnostic, PageRecord } from "./types.ts";
 
 /** `CardGroup` → `card-group`, matching registry item names. */
@@ -9,36 +9,89 @@ const toKebab = (tag: string): string =>
     .replaceAll(/(?<lower>[a-z0-9])(?<upper>[A-Z])/gu, "$<lower>-$<upper>")
     .toLowerCase();
 
+const LIST = new Intl.ListFormat("en", { type: "conjunction" });
+
 /**
  * Warn when an `.mdx` page uses a `<Component>` tag that resolves to nothing —
  * a built-in, an island, or a `components.ts` override — so a typo surfaces as a
  * friendly diagnostic (with a `blume add` hint where one exists) instead of a raw
  * MDX "X is not defined" build error. `extraTags` are the project's own known
  * components (islands + overrides); `registryNames` gates the install hint.
+ * One warning per tag names every page that uses it, anchored to the first.
  */
 export const validateUsedComponents = (
   pages: PageRecord[],
   extraTags: Set<string>,
   registryNames: Set<string>
+): Diagnostic[] => {
+  const users = new Map<string, PageRecord[]>();
+  for (const page of pages) {
+    for (const tag of page.componentsUsed ?? []) {
+      if (!(BUILTIN_MDX_TAGS.has(tag) || extraTags.has(tag))) {
+        users.set(tag, [...(users.get(tag) ?? []), page]);
+      }
+    }
+  }
+  return [...users].map(([tag, using]) => {
+    const name = toKebab(tag);
+    const suggestion = registryNames.has(name)
+      ? `Run \`blume add ${name}\` to install it, or register <${tag}> in components.ts (mdx).`
+      : `Register <${tag}> in components.ts (mdx), or add an islands/${tag}.tsx component.`;
+    const routes = using.map((page) => page.route);
+    const [first] = using;
+    return {
+      code: "BLUME_UNKNOWN_COMPONENT",
+      file: first?.sourcePath ?? first?.id,
+      message:
+        routes.length === 1
+          ? `<${tag}> is used in ${LIST.format(routes)} but isn't a known component.`
+          : `<${tag}> is used on ${routes.length} pages but isn't a known component: ${LIST.format(routes)}.`,
+      severity: "warning",
+      suggestion,
+    };
+  });
+};
+
+const EITHER = new Intl.ListFormat("en", { type: "disjunction" });
+const quoted = (names: readonly string[]): string[] =>
+  names.map((name) => `\`${name}\``);
+
+/**
+ * Warn about each childless built-in in an `.mdx` page given props it doesn't
+ * take (`<Badge type="tip" text="beta" />`, VitePress's Badge). Blume's
+ * components ignore unknown props, so the element renders without the
+ * content those props carried. `extraTags` are the project's own components
+ * (islands + overrides): one that replaces a built-in takes its own props,
+ * so its uses aren't checked. A file shared by several locales is reported
+ * once.
+ */
+export const unknownPropDiagnostics = (
+  pages: readonly PageRecord[],
+  extraTags: ReadonlySet<string>
 ): Diagnostic[] => {
   const diagnostics: Diagnostic[] = [];
   const seen = new Set<string>();
   for (const page of pages) {
-    for (const tag of page.componentsUsed ?? []) {
-      if (BUILTIN_MDX_TAGS.has(tag) || extraTags.has(tag) || seen.has(tag)) {
+    for (const use of page.unknownProps ?? []) {
+      const file = use.file ?? page.sourcePath ?? page.id;
+      const key = `${file}:${use.line}:${use.column}`;
+      if (extraTags.has(use.tag) || seen.has(key)) {
         continue;
       }
-      seen.add(tag);
-      const name = toKebab(tag);
-      const suggestion = registryNames.has(name)
-        ? `Run \`blume add ${name}\` to install it, or register <${tag}> in components.ts (mdx).`
-        : `Register <${tag}> in components.ts (mdx), or add an islands/${tag}.tsx component.`;
+      seen.add(key);
+      const accepted = BUILTIN_CHILD_PROPS.get(use.tag) ?? [];
+      const takes =
+        accepted.length > 0
+          ? `, and use the props ${use.tag} takes: ${LIST.format(quoted(accepted))}`
+          : `; ${use.tag} takes no props`;
       diagnostics.push({
-        code: "BLUME_UNKNOWN_COMPONENT",
-        file: page.sourcePath ?? page.id,
-        message: `<${tag}> is used in ${page.route} but isn't a known component.`,
+        code: "BLUME_UNKNOWN_PROP",
+        column: use.column,
+        file,
+        line: use.line,
+        message: `<${use.tag}> in ${page.route} has no children, and ${use.tag} doesn't take ${EITHER.format(quoted(use.props))}, so it renders without what ${use.props.length === 1 ? "that prop" : "those props"} meant to show.`,
         severity: "warning",
-        suggestion,
+        suggestion: `Put the content between the tags (<${use.tag}>…</${use.tag}>)${takes}.`,
       });
     }
   }

package/src/core/config-input.ts

@@ -181,7 +181,7 @@ export interface ChangelogConfig {
 export interface ContentConfig {
   /** Default page `type` for content that sets none. Defaults to `doc`. */
   defaultType?: string;
-  /** Glob patterns to ignore. Defaults to `["**\/_*", "**\/.*"]`. Shorthand; not allowed beside `sources`. */
+  /** Glob patterns to ignore, on top of `["**\/_*", "**\/.*"]`; a `!pattern` entry stops ignoring that pattern, a default included. Shorthand; not allowed beside `sources`. */
   exclude?: string[];
   /** Glob patterns to include. Defaults to `["**\/*.{md,mdx}"]`. Shorthand; not allowed beside `sources`. */
   include?: string[];

package/src/core/config.ts

@@ -3,6 +3,7 @@ import { existsSync, readFileSync } from "node:fs";
 import { basename } from "pathe";
 import { z } from "zod";
 
+import { ACCENTS, invalidColorSettings } from "../theme/palette.ts";
 import type { BlumeConfig } from "./config-input.ts";
 import { applyDeploymentEnv } from "./deployment-env.ts";
 import {
@@ -261,6 +262,50 @@ const configIssues = (
     );
 };
 
+const COLOR_FORMS =
+  "a hex value like #6340ac, rgb(), hsl(), oklch(), or a color name like rebeccapurple";
+
+/**
+ * A warning for each configured color that isn't a CSS color, at the line
+ * that sets it. The schema has always taken any string, so this warns rather
+ * than failing a build that used to pass.
+ */
+const colorDiagnostics = (
+  config: ResolvedConfig,
+  configFile: string | null
+): Diagnostic[] => {
+  const invalid = invalidColorSettings(config);
+  if (invalid.length === 0) {
+    return [];
+  }
+  const source =
+    configFile && existsSync(configFile)
+      ? readFileSync(configFile, "utf-8")
+      : undefined;
+  const located = diagnosticsFromIssues(
+    invalid.map((setting) => ({
+      message: `${JSON.stringify(setting.value)} isn't a CSS color, so ${
+        setting.path[0] === "seo"
+          ? "the social card renderer rejects it"
+          : "browsers ignore the styles that use it"
+      }.`,
+      path: setting.path,
+    })),
+    {
+      code: "BLUME_THEME_COLOR_INVALID",
+      file: configFile ?? undefined,
+      source,
+    }
+  );
+  return located.map((diagnostic, index) => ({
+    ...diagnostic,
+    severity: "warning",
+    suggestion: invalid[index]?.presets
+      ? `Use a preset (${Object.keys(ACCENTS).join(", ")}) or a CSS color: ${COLOR_FORMS}.`
+      : `Use a CSS color: ${COLOR_FORMS}.`,
+  }));
+};
+
 /**
  * Load and validate the project config. When no config file exists, schema
  * defaults produce a fully resolved config so the zero-boilerplate path works.
@@ -364,7 +409,7 @@ export const loadConfig = async (
       seo: { ...config.seo, og: { ...config.seo.og, enabled: ogEnabled } },
     },
     configFile,
-    diagnostics: [],
+    diagnostics: colorDiagnostics(config, configFile),
     themeFontsConfigured,
   };
 };