blume 2.1.3 → 2.2.0

package/src/core/content-assets.ts

@@ -1,20 +1,19 @@
-import { readdirSync, statSync } from "node:fs";
 import { readFile } from "node:fs/promises";
 
-import {
-  basename,
-  dirname,
-  extname,
-  normalize,
-  relative,
-  resolve,
-} from "pathe";
+import { dirname, extname, relative } from "pathe";
 
 import { normalizeBasePath } from "./base-path.ts";
 import { nextFenceState } from "./code-fences.ts";
 import type { FenceState } from "./code-fences.ts";
+import { resolveRelativeFile, resolveRelativeImage } from "./relative-files.ts";
 import { hashText } from "./sources/cache.ts";
-import { INLINE_CODE, MD_IMAGE, targetOffsetIn } from "./sources/normalize.ts";
+import {
+  isLinkElementUrl,
+  rewriteCardImages,
+  rewriteElementUrls,
+  rewriteImageTargets,
+  rewriteLinkTargets,
+} from "./sources/normalize.ts";
 import { readExpandedEntryText } from "./sources/read.ts";
 import type { ContentSource } from "./sources/types.ts";
 import type { PageRecord } from "./types.ts";
@@ -29,31 +28,18 @@ import type { PageRecord } from "./types.ts";
  * `/blume-assets/content/<project-relative path>` by a generated endpoint (see
  * `contentAssetsEndpointTemplate`), and these helpers rewrite the relative
  * references in agent-facing output to that URL.
+ *
+ * Other files beside a page are published the same way: a link to one
+ * (`[spec](./spec.pdf)`, a reference definition), a raw HTML or `.mdx`
+ * element's `src` (`<img src="./diagram.png">`, `<video>`, `<source>`,
+ * `<audio>`), and an `<a>`'s or a component's `href`. Nothing else serves
+ * them, so the HTML render points those at the same URLs (see
+ * `markdown/content-assets.ts`).
  */
 
-/** The endpoint route prefix colocated content images are served under. */
+/** The endpoint route prefix colocated content files are served under. */
 export const CONTENT_ASSETS_PREFIX = "/blume-assets/content";
 
-// The formats Astro's image pipeline accepts, plus the web-safe pass-throughs;
-// anything else referenced relatively (a `.pdf`, a source file) is left alone.
-const IMAGE_EXTENSIONS = new Set([
-  ".apng",
-  ".avif",
-  ".bmp",
-  ".gif",
-  ".ico",
-  ".jpeg",
-  ".jpg",
-  ".png",
-  ".svg",
-  ".tiff",
-  ".webp",
-]);
-
-/** Whether a link target is a relative filesystem path (not URL/absolute/hash). */
-const isRelativeTarget = (target: string): boolean =>
-  !(target.startsWith("/") || target.startsWith("#")) && !URL.canParse(target);
-
 /**
  * The endpoint param a colocated image is served under: its project-relative
  * path (readable, collision-free — it mirrors the source tree). A file outside
@@ -71,118 +57,35 @@ export const contentAssetParam = (
   return rel;
 };
 
-/** Percent-decode an image target; malformed escapes stay verbatim. */
-const decodeTarget = (target: string): string => {
-  try {
-    return decodeURI(target);
-  } catch {
-    return target;
-  }
-};
-
-/**
- * Whether a target is *shaped* like a colocated image reference: a relative
- * filesystem path with an image extension. Exported so link validation can
- * tell "not a colocated candidate" apart from "a candidate that resolves
- * nowhere" — the former falls through to the public-dir probe, the latter is
- * a broken reference beside the page source.
- */
-export const isRelativeImageTarget = (target: string): boolean =>
-  isRelativeTarget(target) &&
-  IMAGE_EXTENSIONS.has(extname(decodeTarget(target)).toLowerCase());
-
-/**
- * Whether `abs` is a file whose trailing `segments` names match the on-disk
- * entries exactly. A bare `existsSync` accepts `./Diagram.PNG` for
- * `diagram.png` (or a directory named like an image) on a case-insensitive
- * filesystem — the reference then validates and serves locally but breaks on
- * the case-sensitive Linux build.
- */
-const existsAsWritten = (abs: string, segments: number): boolean => {
-  let current = abs;
-  for (let i = 0; i < segments; i += 1) {
-    const parent = dirname(current);
-    let entries: string[];
-    try {
-      entries = readdirSync(parent);
-    } catch {
-      return false;
-    }
-    if (!entries.includes(basename(current))) {
-      return false;
-    }
-    current = parent;
-  }
-  const stat = statSync(abs, { throwIfNoEntry: false });
-  return stat !== undefined && stat.isFile();
-};
-
 /**
- * Resolve one image target against its page's directory. Returns the absolute
- * file path when the target is relative, is an image, and exists on disk —
- * anything else (remote URLs, `public/` absolutes, broken refs, code-block
- * examples that happen to look like paths) is null and left untouched. Shared
- * with link validation, so what counts as a colocated image is decided once.
+ * The URL a colocated image's endpoint param is served at, under
+ * `deployment.base` when set, encoded for a Markdown or HTML URL with its `/`
+ * separators kept.
  */
-export const resolveRelativeImage = (
-  sourceDir: string,
-  target: string
-): string | null => {
-  if (!isRelativeImageTarget(target)) {
-    return null;
-  }
-  const decoded = decodeTarget(target);
-  // Only the segments the author wrote are checked against on-disk names;
-  // `sourceDir`'s own casing is the filesystem's business, not the target's.
-  const segments = normalize(decoded)
+export const contentAssetUrl = (param: string, deployBase?: string): string =>
+  `${normalizeBasePath(deployBase)}${CONTENT_ASSETS_PREFIX}/${param
     .split("/")
-    .filter((part) => part !== "" && part !== "..").length;
-  const abs = resolve(sourceDir, decoded);
-  return existsAsWritten(abs, segments) ? abs : null;
-};
-
-/** Encode an endpoint param for use in a Markdown URL, keeping `/` separators. */
-const encodedParam = (param: string): string =>
-  param.split("/").map(encodeURIComponent).join("/");
+    .map(encodeURIComponent)
+    .join("/")}`;
+
+// Where a link (`[spec](./spec.pdf)`, `[spec]: ./spec.pdf`) or an element's
+// `href`/`src` could name a file beside the page: a destination or value not
+// written as a root path or a fragment, which `resolveRelativeFile` never
+// resolves. They're read in the text as it stands, code included, so a page
+// without one, like a page that links only to routes and anchors, has
+// nothing to rewrite and skips the passes that mask its code to look.
+const RELATIVE_DESTINATION = /\][(:][ \t]*(?![/#\s])/u;
+const RELATIVE_ELEMENT_URL = /(?:href|src)=["'](?![/#])/u;
 
 /**
- * Rewrite one line's relative image targets. Matches run on a copy with inline
- * code blanked out (a `` `![x](./y.png)` `` span is syntax being *shown*, not
- * an image), while replacements splice into the real line by index — the mask
- * preserves length, so the indices line up.
- */
-const rewriteLine = (
-  line: string,
-  toUrl: (target: string) => string | null
-): string => {
-  const masked = line.replaceAll(INLINE_CODE, (span) =>
-    " ".repeat(span.length)
-  );
-  let out = "";
-  let cursor = 0;
-  for (const match of masked.matchAll(MD_IMAGE)) {
-    const target = match.groups?.target ?? "";
-    const url = toUrl(target);
-    if (url === null) {
-      continue;
-    }
-    const offset =
-      (match.index ?? 0) +
-      targetOffsetIn(match[0], target, match.groups?.title);
-    out += line.slice(cursor, offset) + url;
-    cursor = offset + target.length;
-  }
-  return out + line.slice(cursor);
-};
-
-/**
- * Rewrite a page's relative image references to their served
+ * Rewrite a page's relative image references, and its links and element
+ * URLs naming other files beside it, to their served
  * `/blume-assets/content/…` URLs (under `deployment.base` when set). Fenced
  * code blocks and inline code are skipped; only references whose file actually
  * exists next to the source are touched. `register` observes each rewritten
  * asset so a caller can accumulate the files the endpoint must serve.
  */
-export const rewriteRelativeImages = (options: {
+export const rewriteRelativeAssets = (options: {
   source: string;
   sourcePath: string;
   projectRoot: string;
@@ -191,15 +94,18 @@ export const rewriteRelativeImages = (options: {
 }): string => {
   const { source, sourcePath, projectRoot, deployBase, register } = options;
   const sourceDir = dirname(sourcePath);
-  const prefix = `${normalizeBasePath(deployBase)}${CONTENT_ASSETS_PREFIX}`;
-  const toUrl = (target: string): string | null => {
-    const abs = resolveRelativeImage(sourceDir, target);
-    if (abs === null) {
-      return null;
-    }
+  const served = (abs: string): string => {
     const param = contentAssetParam(projectRoot, abs);
     register?.(param, abs);
-    return `${prefix}/${encodedParam(param)}`;
+    return contentAssetUrl(param, deployBase);
+  };
+  const toUrl = (target: string): string | null => {
+    const abs = resolveRelativeImage(sourceDir, target);
+    return abs === null ? null : served(abs);
+  };
+  const toFileUrl = (target: string): string | null => {
+    const file = resolveRelativeFile(sourceDir, target);
+    return file === null ? null : `${served(file.path)}${file.suffix}`;
   };
 
   let fence: FenceState = null;
@@ -207,13 +113,27 @@ export const rewriteRelativeImages = (options: {
     const next = nextFenceState(line, fence);
     const inFence = fence !== null || next !== null;
     fence = next;
-    return inFence ? line : rewriteLine(line, toUrl);
+    // Inline code is skipped too: a `` `![x](./y.png)` `` span is syntax
+    // being shown, not an image.
+    return inFence ? line : rewriteImageTargets(line, toUrl);
   });
-  return lines.join("\n");
+  // A `<Card img>` is an image embed too: its file is served and its value
+  // pointed there, which the HTML render reads back (see
+  // `markdown/content-assets.ts`), as are links and element URLs naming any
+  // other file beside the page.
+  const withCards = rewriteCardImages(lines.join("\n"), toUrl);
+  const withLinks = RELATIVE_DESTINATION.test(withCards)
+    ? rewriteLinkTargets(withCards, toFileUrl)
+    : withCards;
+  return RELATIVE_ELEMENT_URL.test(withLinks)
+    ? rewriteElementUrls(withLinks, (url) =>
+        isLinkElementUrl(url) ? toFileUrl(url.value) : null
+      )
+    : withLinks;
 };
 
 /**
- * Every colocated image the project's pages reference, keyed by endpoint param.
+ * Every colocated file the project's pages reference, keyed by endpoint param.
  * Serialized to `generated/content-assets.json`, which the
  * `/blume-assets/[...asset]` endpoint reads to serve the original files. Runs
  * the same rewrite the agent-Markdown builders apply — over the same
@@ -243,7 +163,7 @@ export const collectContentAssets = async (project: {
       } catch {
         return;
       }
-      rewriteRelativeImages({
+      rewriteRelativeAssets({
         projectRoot: project.context.root,
         register: (param, abs) => {
           files[param] = abs;

package/src/core/diagnostics.ts

@@ -27,40 +27,65 @@ const DOCS_CONTENT_SOURCES = "/docs/content/sources";
 const DOCS_CONTENT_SOURCES_OBSIDIAN = "/docs/content/sources/obsidian";
 const DOCS_CONTENT_NAVIGATION = "/docs/content/navigation";
 const DOCS_CONTENT_INCLUDES = "/docs/content/includes";
+const DOCS_OPENAPI_WARNINGS = "/docs/references/openapi#spec-warnings";
+const DOCS_OTHER_TOOLS_SYNTAX = "/docs/content/syntax#syntax-from-other-tools";
+const DOCS_MARKDOWN_AND_MDX = "/docs/content#markdown-and-mdx";
 
 /** Diagnostic code → the docs page that explains it. */
 const DOCS_PATHS = new Map(
   Object.entries({
     BLUME_ADAPTER_REQUIRED: DOCS_DEPLOYMENT,
-    BLUME_ASSETS_UNCHECKED: DOCS_CLI_VALIDATE,
     BLUME_ASSET_FETCH_FAILED: DOCS_CONTENT_SOURCES,
     BLUME_BROKEN_ANCHOR: DOCS_CLI_VALIDATE,
     BLUME_BROKEN_ASSET: DOCS_CLI_VALIDATE,
     BLUME_BROKEN_LINK: DOCS_CLI_VALIDATE,
+    BLUME_BROKEN_REDIRECT: DOCS_CLI_VALIDATE,
+    BLUME_CODE_FENCE_OPTION: "/docs/content/syntax",
     BLUME_COMPONENTS_INVALID: "/docs/configuration/customization",
     BLUME_CONFIG_INVALID: "/docs/configuration",
     BLUME_CONFIG_LOAD_FAILED: "/docs/configuration",
     BLUME_CONTENT_ROOT_MISSING: DOCS_CONTENT_SOURCES,
     BLUME_DEAD_LINK: DOCS_CLI_VALIDATE,
     BLUME_DEPENDENCY_MISSING: "/docs/cli/doctor",
+    BLUME_DIRECTIVE_CLOSING_TEXT: "/docs/content/syntax",
+    BLUME_DIRECTIVE_OPENING_TEXT: "/docs/content/syntax",
+    BLUME_DIRECTIVE_SPACED_NAME: "/docs/content/syntax",
     BLUME_DUPLICATE_ROUTE: DOCS_CONTENT_NAVIGATION,
     BLUME_DUPLICATE_SIDEBAR_ORDER: DOCS_CONTENT_NAVIGATION,
     BLUME_EXAMPLE_NOT_FOUND: "/docs/content/components#component",
     BLUME_FRONTMATTER_INVALID: "/docs/content/frontmatter",
+    BLUME_GRAPHQL_UNKNOWN_CODE_SAMPLE: "/docs/references/graphql",
     BLUME_INCLUDE_CYCLE: DOCS_CONTENT_INCLUDES,
     BLUME_INCLUDE_MALFORMED: DOCS_CONTENT_INCLUDES,
     BLUME_INCLUDE_NOT_FOUND: DOCS_CONTENT_INCLUDES,
     BLUME_INCLUDE_OUTSIDE_ROOT: DOCS_CONTENT_INCLUDES,
+    BLUME_MDC_SYNTAX: DOCS_OTHER_TOOLS_SYNTAX,
+    BLUME_MDX_ATTRIBUTE_LIST: DOCS_OTHER_TOOLS_SYNTAX,
     BLUME_MDX_CURLY_ANCHOR: "/docs/content/syntax",
-
+    BLUME_MDX_EVENT_HANDLER: "/docs/content/islands",
+    BLUME_MDX_SYNTAX: DOCS_MARKDOWN_AND_MDX,
+    BLUME_MDX_UNCLOSED_ELEMENT: DOCS_OTHER_TOOLS_SYNTAX,
+    BLUME_MDX_UNDEFINED_NAME: DOCS_MARKDOWN_AND_MDX,
+    BLUME_MD_ATTRIBUTE_LIST: DOCS_OTHER_TOOLS_SYNTAX,
+    BLUME_MD_CURLY_ANCHOR: "/docs/content/syntax",
+    BLUME_MD_DIRECTIVE: "/docs/content/syntax",
+    BLUME_MD_GITHUB_ALERT: "/docs/content/syntax",
     BLUME_META_INVALID: "/docs/content/meta",
     BLUME_META_LOAD_FAILED: "/docs/content/meta",
+    BLUME_META_OUTSIDE_INCLUDE: "/docs/content/meta",
+    BLUME_META_UNKNOWN_PAGE: "/docs/content/meta",
     BLUME_MISSING_SECRET: DOCS_DEPLOYMENT,
     BLUME_NAV_DUPLICATE_LABEL: DOCS_CONTENT_NAVIGATION,
     BLUME_NAV_HIDDEN_IN_SIDEBAR: DOCS_CONTENT_NAVIGATION,
     BLUME_NAV_INDEX_TITLE_MISMATCH: DOCS_CONTENT_NAVIGATION,
     BLUME_NAV_MISSING_PAGE: DOCS_CONTENT_NAVIGATION,
     BLUME_NODE_VERSION: "/docs/quickstart",
+    BLUME_OPENAPI_DUPLICATE_OPERATION_ID: DOCS_OPENAPI_WARNINGS,
+    BLUME_OPENAPI_LOCAL_SERVER: DOCS_OPENAPI_WARNINGS,
+    BLUME_OPENAPI_NULLABLE: DOCS_OPENAPI_WARNINGS,
+    BLUME_OPENAPI_UNKNOWN_CODE_SAMPLE:
+      "/docs/references/openapi#code-samples-and-schemas",
+    BLUME_PUBLIC_OPENAPI_JSON: "/docs/discoverability/json-api",
     BLUME_SEARCH_SYNC_FAILED: "/docs/configuration/search",
     BLUME_SERVER_FEATURE_REQUIRED: DOCS_DEPLOYMENT,
     BLUME_SIDEBAR_DISPLAY_IGNORED: DOCS_CONTENT_NAVIGATION,
@@ -72,15 +97,23 @@ const DOCS_PATHS = new Map(
     BLUME_SOURCE_UNAVAILABLE: DOCS_CONTENT_SOURCES,
     BLUME_SOURCE_UNRESOLVED_LINK: "/docs/content/sources/contentful",
     BLUME_SOURCE_UNSUPPORTED_NODE: "/docs/content/sources/payload",
+    BLUME_SVG_UNOPTIMIZED: "/docs/content/syntax#links-and-images",
+    BLUME_TEMPLATE_TAG: DOCS_OTHER_TOOLS_SYNTAX,
+    BLUME_THEME_COLOR_INVALID: "/docs/configuration/theming",
     BLUME_TRANSLATE_MISSING: "/docs/cli/translate",
     BLUME_TRANSLATE_STALE: "/docs/cli/translate",
+    BLUME_TSCONFIG_EXTENDS: "/docs/cli#type-checking",
+    BLUME_UNKNOWN_CODE_LANGUAGE: "/docs/content/syntax",
     BLUME_UNKNOWN_COMPONENT: "/docs/configuration/customization",
     BLUME_UNKNOWN_DIRECTIVE: "/docs/content/syntax",
     BLUME_UNKNOWN_ICON: DOCS_CONTENT_NAVIGATION,
     BLUME_UNKNOWN_OPTION: "/docs/cli",
+    BLUME_UNKNOWN_PROP: "/docs/content/components",
     BLUME_UNLOADABLE_FILE_NAME: "/docs/content",
+    BLUME_UNSUPPORTED_LINK_SCHEME: DOCS_CLI_VALIDATE,
     BLUME_WIKILINK_AMBIGUOUS: DOCS_CONTENT_SOURCES_OBSIDIAN,
     BLUME_WIKILINK_UNRESOLVED: DOCS_CONTENT_SOURCES_OBSIDIAN,
+    BLUME_WIKILINK_UNSUPPORTED: DOCS_OTHER_TOOLS_SYNTAX,
     BLUME_YARN_PNP: "/docs/quickstart",
   })
 );
@@ -317,7 +350,7 @@ const findElement = (scope: Scope, position: number): Step | undefined => {
  * Returns 1-based line/column, or undefined when not even the first segment
  * matches.
  */
-const locatePath = (
+export const locatePath = (
   source: string,
   path: readonly (string | number)[]
 ): { column: number; line: number } | undefined => {