blume 2.1.3 → 2.2.1

package/src/core/builtin-tags.ts

@@ -14,6 +14,7 @@ export const BUILTIN_MDX_TAGS = new Set<string>([
   "Callout",
   "Card",
   "CardGroup",
+  "Changelog",
   "CodeBlock",
   "CodeGroup",
   "Color",
@@ -48,3 +49,78 @@ export const BUILTIN_MDX_TAGS = new Set<string>([
   "Visibility",
   "YouTube",
 ]);
+
+/**
+ * The props each built-in that shows its children takes, keyed by MDX tag. A
+ * childless use with any other prop renders without the content its author
+ * meant it to carry (VitePress writes `<Badge type="tip" text="beta" />`, and
+ * Blume's Badge shows only its children), which the unknown-prop diagnostic
+ * reports. Each list is the component's own `Props` (or what it reads from
+ * `Astro.props`); a test checks them against the `.astro` files.
+ */
+export const BUILTIN_CHILD_PROPS: ReadonlyMap<string, readonly string[]> =
+  new Map([
+    ["Accordion", []],
+    ["AccordionItem", ["defaultOpen", "description", "icon", "id", "title"]],
+    [
+      "Badge",
+      [
+        "class",
+        "className",
+        "color",
+        "disabled",
+        "icon",
+        "shape",
+        "size",
+        "stroke",
+        "tooltip",
+        "variant",
+      ],
+    ],
+    ["Callout", ["color", "icon", "title", "type"]],
+    [
+      "Card",
+      [
+        "arrow",
+        "color",
+        "cta",
+        "horizontal",
+        "href",
+        "icon",
+        "img",
+        "title",
+        "type",
+      ],
+    ],
+    ["CardGroup", ["cols"]],
+    ["CodeBlock", ["code", "icons", "lang", "title"]],
+    ["CodeGroup", ["dropdown"]],
+    ["Column", []],
+    ["Columns", ["cols"]],
+    ["Expandable", ["defaultOpen", "title"]],
+    ["Frame", ["caption", "hint"]],
+    ["Panel", ["title"]],
+    ["Prompt", ["actions", "description"]],
+    ["RequestExample", ["dropdown"]],
+    ["ResponseExample", ["dropdown"]],
+    ["Step", ["icon", "title"]],
+    ["Steps", ["titleSize"]],
+    ["Tab", ["class", "icon", "id", "style", "title"]],
+    [
+      "Tabs",
+      [
+        "borderBottom",
+        "defaultTabIndex",
+        "dropdown",
+        "hash",
+        "inline",
+        "param",
+        "sync",
+        "syncKey",
+      ],
+    ],
+    ["Tile", ["description", "href", "title"]],
+    ["Tooltip", ["cta", "headline", "href", "tip"]],
+    ["View", ["class", "icon", "title"]],
+    ["Visibility", ["for"]],
+  ]);

package/src/core/changelog-list.ts

@@ -0,0 +1,87 @@
+/**
+ * The policy the changelog index lists by, shared by the surfaces that build
+ * it: the `<Changelog />` component (reading Astro collection entries) and
+ * `ai/changelog-markdown.ts` (reading the build-time page graph for the
+ * `/changelog.md` mirror and MCP `get_page`).
+ *
+ * The data sources genuinely differ — a collection entry on the Astro side, a
+ * `PageRecord` on the Node side — so what lives here is the *decisions*, not
+ * the access: which date a row carries, what order rows come in, and how they
+ * fall into year groups. Keeping them in one place is what stops the rendered
+ * page and the Markdown an agent reads from drifting apart.
+ */
+
+/**
+ * A changelog entry's date, from `date` or the `changelog.date` it may live
+ * under instead. Front matter hands either a `Date` (an unquoted YAML date) or
+ * a string, and an unparseable value is treated as no date at all rather than
+ * failing the build — a malformed date costs the row its stamp and its year
+ * group, not the page.
+ */
+export const parseChangelogDate = (
+  value: Date | string | null | undefined
+): Date | null => {
+  if (value === null || value === undefined) {
+    return null;
+  }
+  const date = value instanceof Date ? value : new Date(value);
+  return Number.isNaN(date.getTime()) ? null : date;
+};
+
+/**
+ * Newest first. An undated entry sorts as the epoch, so undated rows collect
+ * at the end of the list (and, through {@link groupChangelogYears}, into a
+ * final group with no year label).
+ */
+export const compareChangelogDates = (a: Date | null, b: Date | null): number =>
+  (b?.getTime() ?? 0) - (a?.getTime() ?? 0);
+
+/** One year's run of rows. `year` is `null` for the undated group. */
+export interface ChangelogYearGroup<T> {
+  items: T[];
+  year: string | null;
+}
+
+/**
+ * Consecutive rows sharing a year, in list order, so the index reads as a year
+ * rail beside its rows. Runs are consecutive rather than keyed, which matters
+ * only for a list that isn't sorted by date: such a list keeps its order and
+ * repeats the year heading instead of silently regrouping around it.
+ *
+ * `yearOf` returns the label the surface wants — a locale-formatted year on the
+ * rendered page, a plain number in Markdown — or `null` for an undated row.
+ */
+export const groupChangelogYears = <T>(
+  items: T[],
+  yearOf: (item: T) => string | null
+): ChangelogYearGroup<T>[] => {
+  const groups: ChangelogYearGroup<T>[] = [];
+  for (const item of items) {
+    const year = yearOf(item);
+    const last = groups.at(-1);
+    if (last && last.year === year) {
+      last.items.push(item);
+    } else {
+      groups.push({ items: [item], year });
+    }
+  }
+  return groups;
+};
+
+/**
+ * Make each row's anchor unique. Repeated labels slug to the same id (two
+ * entries with neither a title nor a version both fall back to "update"), so
+ * the later ones take a `-2`, `-3`, … suffix and the first keeps the plain
+ * slug — every row ends up with its own hash anchor.
+ */
+export const uniqueAnchorIds = (ids: string[]): string[] => {
+  const seen = new Set<string>();
+  return ids.map((id) => {
+    let unique = id;
+    for (let n = 2; seen.has(unique); n += 1) {
+      unique = `${id}-${n}`;
+    }
+    seen.add(unique);
+    return unique;
+  });
+};

package/src/core/closest-match.ts

@@ -0,0 +1,41 @@
+/** Edit distance between two short strings (insertions, deletions, swaps of one letter). */
+const distance = (from: string, to: string): number => {
+  let previous = Array.from({ length: to.length + 1 }, (_, index) => index);
+  for (const [row, fromChar] of [...from].entries()) {
+    const current = [row + 1];
+    for (const [column, toChar] of [...to].entries()) {
+      current.push(
+        Math.min(
+          (previous[column + 1] ?? 0) + 1,
+          (current[column] ?? 0) + 1,
+          (previous[column] ?? 0) + (fromChar === toChar ? 0 : 1)
+        )
+      );
+    }
+    previous = current;
+  }
+  return previous[to.length] ?? 0;
+};
+
+/**
+ * The candidate closest to `name`, when it's close enough to be the likely
+ * intent: at most two edits away, and fewer edits than half the candidate's
+ * length, so a short typo doesn't "suggest" an unrelated short word.
+ */
+export const closestMatch = (
+  name: string,
+  candidates: readonly string[]
+): string | undefined => {
+  let best: { candidate: string; edits: number } | undefined;
+  for (const candidate of candidates) {
+    const edits = distance(name, candidate);
+    if (
+      edits <= 2 &&
+      edits * 2 < candidate.length &&
+      (best === undefined || edits < best.edits)
+    ) {
+      best = { candidate, edits };
+    }
+  }
+  return best?.candidate;
+};

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}.`,
       });
     }
   }