blume 1.1.3 → 1.2.0

package/src/eval/schema.ts

@@ -0,0 +1,124 @@
+import { readFile } from "node:fs/promises";
+
+import { load } from "js-yaml";
+import { z } from "zod";
+
+/** Question ids are kebab-case slugs so they read well in reports and CI logs. */
+const ID_PATTERN = /^[a-z0-9][a-z0-9-]*$/u;
+
+const questionSchema = z.strictObject({
+  expected: z
+    .array(z.string().min(1))
+    .min(1, "expected must list at least one fact"),
+  id: z
+    .string()
+    .regex(ID_PATTERN, "id must be a kebab-case slug (a-z, 0-9, dashes)"),
+  question: z.string().min(1),
+  routes: z
+    .union([z.string(), z.array(z.string())])
+    .default([])
+    .transform((value) => (typeof value === "string" ? [value] : value)),
+  severity: z.enum(["error", "warning"]).default("error"),
+  skip: z.boolean().default(false),
+});
+
+/** One author-written eval: a question plus the facts a passing answer states. */
+export type EvalQuestion = z.infer<typeof questionSchema>;
+
+const fullSchema = z.strictObject({
+  questions: z.array(questionSchema).min(1),
+  version: z.literal(1).default(1),
+});
+
+/**
+ * The evals file schema. A bare top-level list of questions is accepted as
+ * shorthand — `loadEvalsFile` wraps it before validating, rather than a
+ * `z.union`, so schema errors name the offending field instead of collapsing
+ * into an opaque "invalid union" issue.
+ */
+export const evalsFileSchema = fullSchema.superRefine((value, context) => {
+  const seen = new Set<string>();
+  for (const question of value.questions) {
+    if (seen.has(question.id)) {
+      context.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: `duplicate question id "${question.id}"`,
+        path: ["questions"],
+      });
+    }
+    seen.add(question.id);
+  }
+});
+
+export type EvalsFile = z.infer<typeof evalsFileSchema>;
+
+/** A problem loading or validating the evals file, with the path it names. */
+export class EvalsFileError extends Error {
+  readonly path: string;
+
+  constructor(path: string, message: string) {
+    super(message);
+    this.name = "EvalsFileError";
+    this.path = path;
+  }
+}
+
+const describeIssues = (error: z.ZodError): string =>
+  error.issues
+    .map((issue) => {
+      const at = issue.path.length > 0 ? ` at ${issue.path.join(".")}` : "";
+      return `${issue.message}${at}`;
+    })
+    .join("; ");
+
+/**
+ * Read and validate an evals file. Returns the parsed questions plus the raw
+ * text, kept so findings can anchor to the line a question is defined on.
+ */
+export const loadEvalsFile = async (
+  path: string
+): Promise<{ evals: EvalsFile; raw: string }> => {
+  let raw: string;
+  try {
+    raw = await readFile(path, "utf-8");
+  } catch {
+    throw new EvalsFileError(
+      path,
+      `No evals file found at ${path}. Run \`blume eval init\` to draft one.`
+    );
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = load(raw);
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    throw new EvalsFileError(path, `Invalid YAML in ${path}: ${detail}`);
+  }
+
+  // The bare-list shorthand: a top-level sequence of questions.
+  const candidate = Array.isArray(parsed) ? { questions: parsed } : parsed;
+  const result = evalsFileSchema.safeParse(candidate);
+  if (!result.success) {
+    throw new EvalsFileError(
+      path,
+      `Invalid evals file at ${path}: ${describeIssues(result.error)}`
+    );
+  }
+  return { evals: result.data, raw };
+};
+
+/**
+ * The 1-based line where a question's `id:` entry appears in the raw evals
+ * file, so a finding with no route hint can still point somewhere editable.
+ */
+export const locateQuestion = (raw: string, id: string): number | undefined => {
+  const pattern = new RegExp(`^\\s*-?\\s*id:\\s*["']?${id}["']?\\s*$`, "u");
+  const lines = raw.split("\n");
+  for (const [index, line] of lines.entries()) {
+    if (pattern.test(line)) {
+      return index + 1;
+    }
+  }
+  return undefined;
+};

package/src/markdown/code-title.ts

@@ -51,7 +51,13 @@ const parseTitle = (raw: string | undefined): string | undefined => {
   if (!raw) {
     return undefined;
   }
-  const explicit = raw.match(TITLE_ATTR);
+  // Blank every *other* quoted attr first, so a `title="…"` embedded in
+  // another attribute's value (`caption='set title="X" here'`) can't be
+  // promoted to the block title.
+  const scrubbed = raw.replace(QUOTED_ATTR, (attr) =>
+    attr.startsWith("title=") ? attr : " "
+  );
+  const explicit = scrubbed.match(TITLE_ATTR);
   const attrTitle = explicit?.groups?.dq ?? explicit?.groups?.sq;
   if (attrTitle) {
     return attrTitle;

package/src/openapi/model.ts

@@ -101,6 +101,32 @@ export type OpenApiData = Record<string, ApiSpecData>;
 const isOperation = (value: unknown): value is OperationObject =>
   typeof value === "object" && value !== null;
 
+/**
+ * Assign each distinct tag name a unique slug. `slugify` can collapse
+ * different names onto one value — any two all-non-ASCII tags (`ペット`,
+ * `注文`) both fall through to the `operations` fallback — and a shared slug
+ * silently merges the tags' routes, sidebar groups, and overview sections.
+ * Collisions gain `-2`, `-3`, … in first-seen order.
+ */
+const tagSlugger = (): ((name: string) => string) => {
+  const assigned = new Map<string, string>();
+  const taken = new Set<string>();
+  return (name) => {
+    const existing = assigned.get(name);
+    if (existing) {
+      return existing;
+    }
+    const base = slugify(name) || "operations";
+    let slug = base;
+    for (let suffix = 2; taken.has(slug); suffix += 1) {
+      slug = `${base}-${suffix}`;
+    }
+    taken.add(slug);
+    assigned.set(name, slug);
+    return slug;
+  };
+};
+
 /**
  * Flatten a 3.1 document into a route-mapped operation list and its ordered
  * tags. Operations inherit the first tag they declare; keys are de-duplicated so
@@ -119,6 +145,7 @@ export const extractOperations = (
   );
   const seen = new Set<string>();
   const warnings: string[] = [];
+  const slugForTag = tagSlugger();
 
   for (const [path, rawItem] of Object.entries(document.paths ?? {})) {
     const item = rawItem as PathItemObject | undefined;
@@ -137,7 +164,7 @@ export const extractOperations = (
         continue;
       }
       const tag = operation.tags?.[0] ?? UNTAGGED;
-      const tagSlug = slugify(tag) || "operations";
+      const tagSlug = slugForTag(tag);
       if (!tagsSeen.has(tag)) {
         tagsSeen.add(tag);
         tagOrder.push(tag);
@@ -166,7 +193,9 @@ export const extractOperations = (
   const tags: ApiTagRef[] = tagOrder.map((name) => ({
     description: tagMeta.get(name) ?? "",
     name,
-    slug: slugify(name) || "operations",
+    // The same slugger instance, so every tag resolves to the slug its
+    // operations were routed under.
+    slug: slugForTag(name),
   }));
 
   return { operations, tags, warnings };

package/src/openapi/references.ts

@@ -38,6 +38,12 @@ export interface ReferenceSource {
    */
   basePath: string;
   label: string;
+  /** Whether generated pages are included in llms.txt/llms-full.txt. */
+  includeInLlms: boolean;
+  /** Whether generated pages are included in site search. */
+  includeInSearch: boolean;
+  /** Whether generated pages emit noindex metadata and stay out of the sitemap. */
+  noindex: boolean;
   /** Local path or `http(s)` URL, verbatim from config. */
   spec: string;
   /** Per-block Scalar theme name override, if any (Scalar renderer only). */
@@ -78,10 +84,22 @@ type Block = ResolvedConfig["openapi"] | ResolvedConfig["asyncapi"];
 /** A spec is a single source (`spec` shorthand prepended to any `sources`). */
 const sourcesOf = (
   block: Block
-): { label?: string; route?: string; spec: string }[] => {
+): {
+  includeInLlms: boolean;
+  includeInSearch: boolean;
+  label?: string;
+  noindex: boolean;
+  route?: string;
+  spec: string;
+}[] => {
   const sources = [...block.sources];
   if (block.spec) {
-    sources.unshift({ spec: block.spec });
+    sources.unshift({
+      includeInLlms: true,
+      includeInSearch: true,
+      noindex: false,
+      spec: block.spec,
+    });
   }
   return sources;
 };
@@ -118,8 +136,11 @@ const referencesFor = (
     return {
       basePath,
       display,
+      includeInLlms: source.includeInLlms,
+      includeInSearch: source.includeInSearch,
       kind,
       label,
+      noindex: source.noindex,
       renderer,
       route,
       scalar: block.scalar,

package/src/openapi/render-mdx.ts

@@ -1,4 +1,5 @@
 import type { ApiOperationRef, ApiSpecData } from "./model.ts";
+import type { ReferenceSource } from "./references.ts";
 
 /**
  * Lower a parsed spec into MDX for the staged content source. Each operation and
@@ -11,13 +12,14 @@ import type { ApiOperationRef, ApiSpecData } from "./model.ts";
  * omit their own top heading.
  */
 
-// Neutralize the few characters MDX treats specially (`{` expressions, `<` JSX)
-// so an arbitrary spec description can be embedded in the body verbatim without
-// breaking compilation. They render as their literal selves.
-const MDX_UNSAFE = /[<>{}]/gu;
+// Neutralize the few characters MDX treats specially (`{` expressions, `<`
+// JSX) so an arbitrary spec description can be embedded in the body verbatim
+// without breaking compilation. They render as their literal selves. `>` is
+// deliberately not escaped: it isn't MDX-special on its own, and escaping it
+// turns a `> Note:` blockquote into literal "&gt; Note:" text.
+const MDX_UNSAFE = /[<{}]/gu;
 const ENTITIES: Record<string, string> = {
   "<": "&lt;",
-  ">": "&gt;",
   "{": "&#123;",
   "}": "&#125;",
 };
@@ -28,8 +30,12 @@ const MDX_ESM_KEYWORD = /^(?<keyword>import|export)\b/gmu;
 // Backtick code — inline spans and fences alike — is already literal in MDX,
 // and entities are NOT decoded inside it, so escaping there would render the
 // entity text verbatim (`/pets/&#123;petId&#125;`). Matching any balanced
-// backtick run covers `code`, ``code``, and ```fences``` in one shot.
-const BACKTICK_CODE = /(?<bt>`+)[\s\S]*?\k<bt>/gu;
+// backtick run covers `code`, ``code``, and ```fences``` in one shot. Both
+// runs are pinned by the backtick lookarounds: CommonMark pairs a span only
+// with an *equal-length* run, so without them a lone backtick would "close" on
+// the first backtick of a longer fence run — leaving `{` in the real prose
+// unescaped (a compile error) and escaping entities into the fence body.
+const BACKTICK_CODE = /(?<!`)(?<bt>`+)(?!`)[\s\S]*?(?<!`)\k<bt>(?!`)/gu;
 
 const escapeProse = (text: string): string =>
   text
@@ -121,7 +127,11 @@ const withDescription = (description: string, component: string): string =>
 
 export const operationMdx = (
   spec: ApiSpecData,
-  operation: ApiOperationRef
+  operation: ApiOperationRef,
+  reference?: Pick<
+    ReferenceSource,
+    "includeInLlms" | "includeInSearch" | "noindex"
+  >
 ): RenderedPage => {
   const method = operation.method.toUpperCase();
   const title = operation.summary || `${method} ${operation.path}`;
@@ -137,9 +147,16 @@ export const operationMdx = (
       `<Operation source="${spec.slug}" id="${operation.key}" />`
     ),
     data: {
+      ...(reference?.includeInLlms === false ? { ai: { exclude: true } } : {}),
       ...(operation.deprecated ? { deprecated: true } : {}),
-      search: { tags: [operation.tag, method] },
-      seo: { description: operationDescription(spec, operation) },
+      search: {
+        ...(reference?.includeInSearch === false ? { exclude: true } : {}),
+        tags: [operation.tag, method],
+      },
+      seo: {
+        description: operationDescription(spec, operation),
+        ...(reference?.noindex ? { noindex: true } : {}),
+      },
       sidebar: { badge: method, label: operation.summary || operation.path },
       title,
       // Signals the two-column API layout (request panel instead of the TOC).
@@ -148,7 +165,13 @@ export const operationMdx = (
   };
 };
 
-export const overviewMdx = (spec: ApiSpecData): RenderedPage => {
+export const overviewMdx = (
+  spec: ApiSpecData,
+  reference?: Pick<
+    ReferenceSource,
+    "includeInLlms" | "includeInSearch" | "noindex"
+  >
+): RenderedPage => {
   // Tag sections: declared tags in spec order, then any tag an operation
   // references that isn't declared under `tags`. The section headings are
   // emitted as real markdown `##` (not markup inside a component) so the
@@ -200,10 +223,15 @@ export const overviewMdx = (spec: ApiSpecData): RenderedPage => {
       ...tagSections,
     ].join("\n\n"),
     data: {
+      ...(reference?.includeInLlms === false ? { ai: { exclude: true } } : {}),
+      ...(reference?.includeInSearch === false
+        ? { search: { exclude: true } }
+        : {}),
       seo: {
         description:
           clip(plainProse(spec.description), META_DESCRIPTION_MAX) ||
           `${apiName(spec)} API reference.`,
+        ...(reference?.noindex ? { noindex: true } : {}),
       },
       sidebar: { label: "Overview" },
       title: apiName(spec),

package/src/openapi/scalar.ts

@@ -167,6 +167,7 @@ export const buildReferenceFiles = async (options: {
           ...ref.scalar,
         },
         dataImport: `${"../".repeat(depth + 1)}generated/data.json`,
+        noindex: ref.noindex,
         route: ref.route,
         title: ref.label,
       }),

package/src/openapi/source.ts

@@ -53,17 +53,24 @@ const toEntry = (rendered: RenderedPage, ref: string): SourceEntry => {
 /** All staged entries for one spec: operations first, overview last. */
 const specEntries = (
   spec: ApiSpecData,
-  operations: ApiOperationRef[]
+  operations: ApiOperationRef[],
+  reference: ReferenceSource
 ): SourceEntry[] => {
   const entries = operations.map((operation) =>
-    toEntry(operationMdx(spec, operation), `${routeToRef(operation.route)}.mdx`)
+    toEntry(
+      operationMdx(spec, operation, reference),
+      `${routeToRef(operation.route)}.mdx`
+    )
   );
   // Overview last so an operation sets the section's routePath before the index
   // page is inserted (the group's routePath is derived from its first child).
   // A root-mounted reference refs `index.mdx`, not `/index.mdx`.
   const base = routeToRef(spec.route);
   entries.push(
-    toEntry(overviewMdx(spec), base ? `${base}/index.mdx` : "index.mdx")
+    toEntry(
+      overviewMdx(spec, reference),
+      base ? `${base}/index.mdx` : "index.mdx"
+    )
   );
   return entries;
 };
@@ -149,7 +156,7 @@ export const openApiSource = (
               ]
             : []),
         ],
-        entries: specEntries(spec, operations),
+        entries: specEntries(spec, operations, reference),
         slug: reference.slug,
         spec,
       };

package/src/registry/eject.ts

@@ -112,7 +112,15 @@ const askFiles = async (
   genDir: string
 ): Promise<{ content: string; path: string }[]> => {
   const { ask } = project.config.ai;
-  if (!ask?.enabled) {
+  if (!(ask?.enabled && !ask.endpoint)) {
+    const endpointPath = join(srcDir, "pages", "api", "ask.ts");
+    if (existsSync(endpointPath)) {
+      const content = await readFile(endpointPath, "utf-8");
+      if (content.startsWith("// Generated by Blume. Do not edit.")) {
+        await rm(endpointPath, { force: true });
+      }
+    }
+    await rm(join(genDir, "ask-data.json"), { force: true });
     return [];
   }
   const grounded = ask.provider !== "inkeep";
@@ -271,6 +279,15 @@ const examplesPreviewFiles = (
       ]
     : [];
 
+const ejectIntegrationBridge = (
+  config: BlumeProject["config"],
+  root: string,
+  configFile: string | null
+): Parameters<typeof astroConfigTemplate>[0]["integrationBridge"] =>
+  config.integrations.length > 0 && configFile
+    ? { configFile: toPosix(relative(root, configFile)) }
+    : undefined;
+
 /**
  * Promote the generated runtime into the project as an owned Astro app. After
  * eject the project has a normal `astro.config.mjs` and `src/`, the `blume` CLI
@@ -367,6 +384,11 @@ export const eject = async (
         dataPath: "./src/generated/data.json",
         examplesPath: "./src/generated/examples.ts",
         examplesThemePath: "./src/generated/examples.css",
+        integrationBridge: ejectIntegrationBridge(
+          config,
+          root,
+          context.configFile
+        ),
         needsReact,
         needsSvelte,
         needsVue,

package/src/search/build.ts

@@ -1,9 +1,10 @@
 import { join } from "pathe";
 
 /**
- * Build a local Pagefind search index over the built site. Pagefind only
- * indexes elements marked with `data-pagefind-body`, which Blume adds to the
- * content of indexable pages, so nav chrome and excluded pages are skipped.
+ * Build a local Pagefind search index over the built site. Pagefind indexes
+ * every rendered page except those whose `<html>` carries
+ * `data-pagefind-ignore`, which Blume stamps on non-indexable pages
+ * (search-excluded, or hidden without the opt-in), so those stay out.
  *
  * Returns the number of pages indexed.
  */