blume 1.1.2 → 1.1.4

package/src/astro/generate.ts

@@ -3,6 +3,7 @@ import {
   lstat,
   mkdir,
   readFile,
+  readlink,
   realpath,
   rename,
   rm,
@@ -12,7 +13,7 @@ import {
 import { createRequire } from "node:module";
 import { pathToFileURL } from "node:url";
 
-import { basename, dirname, join, normalize, relative } from "pathe";
+import { basename, dirname, join, normalize, relative, resolve } from "pathe";
 import { glob } from "tinyglobby";
 
 import { buildAskData } from "../ai/ask-data.ts";
@@ -39,7 +40,7 @@ import type { BlumeProject } from "../core/project-graph.ts";
 import type { ResolvedConfig } from "../core/schema.ts";
 import { resolveDocsCollection } from "../core/sources/resolve.ts";
 import { resolveTsconfigAliases } from "../core/tsconfig-aliases.ts";
-import type { Navigation } from "../core/types.ts";
+import type { Diagnostic, Navigation, ProjectContext } from "../core/types.ts";
 import { buildRssFeeds, renderRssFeed } from "../deploy/rss.ts";
 import { resolveOgLogo } from "../og/logo.ts";
 import { hasScalarReferences, referenceRoutes } from "../openapi/references.ts";
@@ -58,7 +59,7 @@ import { buildThemeCss } from "../theme/palette.ts";
 import { twoslashCss } from "../theme/twoslash.ts";
 import { planComponentSlots } from "./component-slots.ts";
 import type { ComponentSlotPlan } from "./component-slots.ts";
-import { discoverExamples } from "./examples.ts";
+import { discoverExamples, exampleMarkdownLookup } from "./examples.ts";
 import { discoverIslands } from "./islands.ts";
 import {
   customOgRoutes,
@@ -87,6 +88,7 @@ import {
   ogEndpointTemplate,
   rawMarkdownEndpointTemplate,
   rssEndpointTemplate,
+  runtimeDirWithin,
   staticJsonEndpointTemplate,
   runtimeDependencies,
   runtimePackageTemplate,
@@ -118,17 +120,18 @@ const canResolveFrom = (fromDir: string, spec: string): boolean => {
  * that never installed the plugin directly. Resolving from `packageRoot()` binds
  * to Blume's shipped copy regardless of the user's package manager or hoisting.
  */
-const resolveReactCompiler = (
+export const resolveReactCompiler = (
   config: ResolvedConfig,
-  needsReact: boolean
+  needsReact: boolean,
+  pkgDir: string = packageRoot()
 ): string | null => {
   if (!(needsReact && config.react.compiler)) {
     return null;
   }
   try {
-    return createRequire(
-      pathToFileURL(join(packageRoot(), "_.js")).href
-    ).resolve("babel-plugin-react-compiler");
+    return createRequire(pathToFileURL(join(pkgDir, "_.js")).href).resolve(
+      "babel-plugin-react-compiler"
+    );
   } catch {
     return null;
   }
@@ -137,9 +140,9 @@ const resolveReactCompiler = (
 /**
  * Warning (as a spreadable list) for the case where the React Compiler was
  * requested but its plugin couldn't be resolved — so the build silently drops
- * to uncompiled output rather than failing.
+ * to uncompiled output rather than failing. Exported for testing.
  */
-const reactCompilerWarnings = (
+export const reactCompilerWarnings = (
   config: ResolvedConfig,
   needsReact: boolean,
   compilerPath: string | null
@@ -160,8 +163,9 @@ const resolveAstroPackageJson = (modulesDir: string): string | null => {
 };
 
 /**
- * Realpath of the `astro` package reachable through the normal node_modules
- * ancestor walk from a generated runtime, or null when none resolves.
+ * The `astro` package reachable through the normal node_modules ancestor walk
+ * from a generated runtime — its realpath'd `package.json` plus the
+ * `node_modules` directory the walk found it in — or null when none resolves.
  *
  * This deliberately does not use `createRequire().resolve()`. pnpm's generated
  * bin shim adds Blume's virtual-store dependencies to `NODE_PATH`, which
@@ -170,13 +174,21 @@ const resolveAstroPackageJson = (modulesDir: string): string | null => {
  * reachable skips the dependency link and makes `import "astro/config"` fail.
  * Walking the physical node_modules ancestors mirrors the lookup that config
  * actually gets.
+ *
+ * The containing directory matters as much as the package: under an isolated
+ * linker the walk can find a store-deduped astro in a directory that holds
+ * nothing else of Blume's, so "the right astro resolves" does not imply "the
+ * integrations resolve" — callers must check where the hit came from.
  */
-const resolvedAstroPath = (fromDir: string): string | null => {
+const resolvedAstroHit = (
+  fromDir: string
+): { modulesDir: string; pkg: string } | null => {
   let dir = normalize(fromDir);
   while (true) {
-    const resolved = resolveAstroPackageJson(join(dir, "node_modules"));
-    if (resolved) {
-      return resolved;
+    const modulesDir = join(dir, "node_modules");
+    const pkg = resolveAstroPackageJson(modulesDir);
+    if (pkg) {
+      return { modulesDir, pkg };
     }
     const parent = dirname(dir);
     if (parent === dir) {
@@ -186,6 +198,18 @@ const resolvedAstroPath = (fromDir: string): string | null => {
   }
 };
 
+/**
+ * Whether two paths name the same physical directory (realpath equality).
+ * Exported for testing.
+ */
+export const sameRealDir = (a: string, b: string): boolean => {
+  try {
+    return realpathSync(a) === realpathSync(b);
+  } catch {
+    return false;
+  }
+};
+
 /**
  * The two places an installer can put Blume's dependencies:
  *   - `<blume>/node_modules` — deps nested under the package (workspace source,
@@ -263,6 +287,17 @@ const linkDepsJunction = async (
     if (!existing.isSymbolicLink()) {
       return;
     }
+    // Already pointing at the right target — leave it alone. This runs on
+    // every dev regeneration, and an unconditional rm+recreate opens a window
+    // in which the Vite server's module resolution races a missing
+    // `node_modules` and 500s intermittently.
+    try {
+      if (resolve(dirname(link), await readlink(link)) === resolve(depsDir)) {
+        return;
+      }
+    } catch {
+      // Unreadable link — replace it below.
+    }
     await rm(link, { force: true });
   }
   await mkdir(dirname(link), { recursive: true });
@@ -358,7 +393,11 @@ const dropStaleDepsLink = async (
  *     install. An `overrides` pin plus an incremental `npm install` hoists
  *     astro to the project root (deleting Blume's nested copy) but leaves
  *     `@astrojs/mdx` and friends nested under `blume/node_modules`, where the
- *     upward walk from `.blume/` can't see them.
+ *     upward walk from `.blume/` can't see them. The same shape arises under
+ *     an isolated linker when the workspace itself declares astro at a version
+ *     matching Blume's: the store dedupes both to one copy, so the walk finds
+ *     the "correct" astro through the workspace's own direct-dep symlink — in
+ *     a node_modules holding none of Blume's other deps.
  *
  * The repair is the same symlink: Blume's dependency directory linked in as
  * `.blume/node_modules` so the generated config's bare specifiers (`astro`,
@@ -387,12 +426,22 @@ export const ensureDepsLink = async (
   // that binds it to a superseded Blume — the probes below would otherwise
   // pass right through it (same astro, older blume) and leave it in place.
   await dropStaleDepsLink(join(outDir, "node_modules"), pkgDir);
-  const outDirAstro = resolvedAstroPath(outDir);
+  const outDirHit = resolvedAstroHit(outDir);
   // `.blume/` resolves the very same astro Blume's deps provide.
-  const astroCorrect = blumeAstro !== null && outDirAstro === blumeAstro;
-  // Clean hoisted install: astro is correct and the integrations sit beside
-  // it, so they resolve through the same walk — nothing to do.
-  if (astroCorrect && mdxDir === astroDir) {
+  const astroCorrect = blumeAstro !== null && outDirHit?.pkg === blumeAstro;
+  // Clean hoisted install: astro is correct, found in Blume's own dependency
+  // directory, and the integrations sit beside it — the same walk resolves
+  // them too, so there is nothing to do. Requiring the walk to land in
+  // `astroDir` itself (not merely resolve an identical astro) matters under
+  // isolated linkers: a workspace that declares astro at a version matching
+  // Blume's gets a store-deduped symlink in its own node_modules, so the walk
+  // finds the "correct" astro in a directory holding only the workspace's
+  // direct deps — none of Blume's integrations (issue #103).
+  const walkLandsInDeps =
+    astroCorrect &&
+    outDirHit !== null &&
+    sameRealDir(outDirHit.modulesDir, astroDir);
+  if (walkLandsInDeps && mdxDir === astroDir) {
     return null;
   }
   // Linking the integrations' directory yields a consistent set when it also
@@ -406,7 +455,7 @@ export const ensureDepsLink = async (
   // Split layout: Blume's astro is nested (a conflicting astro took the root
   // spot) but @astrojs/mdx hoisted away from it, binding to the shadow. Only a
   // root pin fixes this — surface it.
-  return astroConflictWarning(blumeAstro, outDirAstro);
+  return astroConflictWarning(blumeAstro, outDirHit?.pkg ?? null);
 };
 
 /**
@@ -555,6 +604,34 @@ const deploymentAdapterWarnings = (
   return [];
 };
 
+/**
+ * Warn when the configured search provider's SDK is missing. Provider SDKs are
+ * optional peers; warn (rather than fail opaquely in Vite) when the package
+ * isn't installed. A dep is available if the project installed it (resolves
+ * from the root) OR Blume ships it (resolves from the Blume package — the same
+ * set the `.blume` deps link exposes to the build). Resolving from the project
+ * root alone falsely flagged a shipped SDK like Orama (the default provider)
+ * as missing whenever it wasn't hoisted into the project, e.g. under isolated
+ * linkers. We resolve from each package's real location rather than through
+ * the `.blume` junction, which can't be traversed reliably for store-symlinked
+ * deps. `pkgDir` is injectable for testing.
+ */
+export const searchProviderWarnings = (
+  provider: ResolvedConfig["search"]["provider"],
+  root: string,
+  pkgDir: string = packageRoot()
+): string[] => {
+  const warnings: string[] = [];
+  for (const dep of searchProviderMeta(provider).runtimeDeps) {
+    if (!(canResolveFrom(root, dep) || canResolveFrom(pkgDir, dep))) {
+      warnings.push(
+        `Search provider "${provider}" needs "${dep}", which isn't installed. Run \`npm install ${dep}\` (or your package manager's equivalent).`
+      );
+    }
+  }
+  return warnings;
+};
+
 /** Absolute path to the configured `examples.css`, or null when unset. */
 const examplesCssFile = (root: string, config: ResolvedConfig): string | null =>
   config.examples.css ? join(root, config.examples.css) : null;
@@ -1014,6 +1091,7 @@ export const buildRuntimeData = (project: BlumeProject): string => {
       basePath: config.basePath,
       codeThemes: config.markdown.codeBlocks.theme,
       codeWrap: config.markdown.code.wrap,
+      dateFormat: config.dateFormat,
       description: config.description,
       favicon: resolveFavicon(project),
       feedback: config.feedback,
@@ -1236,6 +1314,15 @@ const writeNotFoundPage = async (
   await write(join(srcDir, "pages", "404.astro"), notFoundPageTemplate());
 };
 
+/**
+ * Flatten a diagnostic to a single warning line, appending the suggestion when
+ * one exists. Exported for testing.
+ */
+export const diagnosticWarning = (diagnostic: Diagnostic): string =>
+  diagnostic.suggestion
+    ? `${diagnostic.message} ${diagnostic.suggestion}`
+    : diagnostic.message;
+
 export interface GenerateResult {
   /** Whether any structural file changed (config/page/content config). */
   structuralChange: boolean;
@@ -1272,6 +1359,20 @@ const buildComponentSlots = async (
   };
 };
 
+/**
+ * Whether the docs glob-loader's watcher observes the runtime dir: a
+ * filesystem collection whose base contains it (a migrated, `content.root:
+ * "."` project) — the one layout where the dev watcher must be kept out of
+ * Astro's cache dir. See `devWatchOption` in templates.ts.
+ */
+const contentWatchesRuntimeDir = (
+  hasFilesystemSource: boolean,
+  collectionBase: string,
+  context: ProjectContext
+): boolean =>
+  hasFilesystemSource &&
+  runtimeDirWithin(collectionBase, context.outDir) !== null;
+
 /**
  * Write (or update) the generated `.blume/` Astro runtime for a project.
  * Only files whose content changed are rewritten so Vite HMR stays fast.
@@ -1335,6 +1436,9 @@ export const generateRuntime = async (
     tags: overrideTags,
     warnings: overrideWarnings,
   } = componentSlots;
+  // Expose the discovered examples for agent-facing Markdown downleveling
+  // (`<Component>` → source) before any consumer (raw `.md`, MCP, llms) runs.
+  project.examples = exampleMarkdownLookup(exampleDiscovery.examples);
 
   // Each island/example framework enables its Astro renderer. React also
   // switches on for any project `.tsx`/`.jsx` and for Ask AI; Vue/Svelte are
@@ -1372,6 +1476,7 @@ export const generateRuntime = async (
   // sources, so the `docs` glob would otherwise scan (and watch) the whole
   // project root for nothing — see contentConfigTemplate.
   const hasFilesystemSource = project.sources.some((source) => !source.staged);
+  const docsCollection = resolveDocsCollection(config, context);
 
   // All of these write to distinct generated paths and never read one another's
   // output, so the structural files, the per-convention hydration wrappers, and
@@ -1386,6 +1491,11 @@ export const generateRuntime = async (
           askPath,
           config,
           contentRoutes: project.manifest.routes.map((route) => route.path),
+          contentWatchesRuntimeDir: contentWatchesRuntimeDir(
+            hasFilesystemSource,
+            docsCollection.base,
+            context
+          ),
           context,
           dataPath,
           examplesPath,
@@ -1411,7 +1521,7 @@ export const generateRuntime = async (
       write(
         join(srcDir, "content.config.ts"),
         contentConfigTemplate({
-          collection: resolveDocsCollection(config, context),
+          collection: docsCollection,
           config,
           context,
           filesystem: hasFilesystemSource,
@@ -1631,11 +1741,7 @@ export const generateRuntime = async (
     ...[
       ...validateNavTargets(project.graph.navigation, navTargetRoutes),
       ...validateSearchPopularIcons(config.search.popular),
-    ].map((diagnostic) =>
-      diagnostic.suggestion
-        ? `${diagnostic.message} ${diagnostic.suggestion}`
-        : diagnostic.message
-    )
+    ].map(diagnosticWarning)
   );
 
   // Unknown-component check: a `<Tag>` in MDX that isn't a built-in, an island,
@@ -1644,40 +1750,17 @@ export const generateRuntime = async (
     ...islandDiscovery.islands.map((island) => island.name),
     ...overrideTags,
   ]);
+  // Missing-dependency preflights: the search provider's SDK, the deployment
+  // adapter's package, and — since React ships with Blume while Vue/Svelte
+  // don't — any island framework's Astro integration. Warn early rather than
+  // let Vite fail to resolve them opaquely.
   warnings.push(
     ...validateUsedComponents(
       project.graph.pages,
       knownComponentTags,
       new Set(registry.map((item) => item.name))
-    ).map((diagnostic) =>
-      diagnostic.suggestion
-        ? `${diagnostic.message} ${diagnostic.suggestion}`
-        : diagnostic.message
-    )
-  );
-
-  // Provider SDKs are optional peers; warn (rather than fail opaquely in Vite)
-  // when the configured provider's package isn't installed. A dep is available
-  // if the project installed it (resolves from the root) OR Blume ships it
-  // (resolves from the Blume package — the same set the `.blume` deps link
-  // exposes to the build). Resolving from the project root alone falsely flagged
-  // a shipped SDK like Orama (the default provider) as missing whenever it
-  // wasn't hoisted into the project, e.g. under isolated linkers. We resolve
-  // from each package's real location rather than through the `.blume` junction,
-  // which can't be traversed reliably for store-symlinked deps.
-  for (const dep of searchProviderMeta(config.search.provider).runtimeDeps) {
-    if (
-      !(canResolveFrom(context.root, dep) || canResolveFrom(packageRoot(), dep))
-    ) {
-      warnings.push(
-        `Search provider "${config.search.provider}" needs "${dep}", which isn't installed. Run \`npm install ${dep}\` (or your package manager's equivalent).`
-      );
-    }
-  }
-
-  // React ships with Blume; Vue/Svelte islands need their Astro integration
-  // installed by the project. Warn early rather than let Vite fail to resolve it.
-  warnings.push(
+    ).map(diagnosticWarning),
+    ...searchProviderWarnings(config.search.provider, context.root),
     ...deploymentAdapterWarnings(config.deployment, context.root),
     ...islandFrameworkWarnings(frameworks, context.root)
   );

package/src/astro/templates.ts

@@ -261,6 +261,35 @@ const reactIntegration = (compilerPath: string | null | undefined): string =>
     ? `react({ babel: { plugins: [[${JSON.stringify(compilerPath)}, { target: "19" }]] }, ${REACT_EXCLUDE} })`
     : `react({ ${REACT_EXCLUDE} })`;
 
+/**
+ * The `server.watch` block for the generated dev config. Keeps the watcher out
+ * of Astro's cache dir — but ONLY when the docs collection is rooted at a
+ * directory containing the runtime dir (a migrated, `content.root: "."`
+ * project). There, the glob loader's watcher match (`picomatch.isMatch(entry,
+ * pattern)` with array-OR semantics, where any negated pattern matches
+ * unrelated files) fires on every `.blume/.astro` write — "No entry type
+ * found" noise, and a `data-store.json` event can re-ingest the store file as
+ * a JSON entry and loop the sync. Everywhere else the watcher MUST see
+ * `.astro/data-store.json`: its change events are the only trigger for
+ * Astro's dev-time content invalidation (see vite-plugin-content-virtual-mod),
+ * and `.md` bodies are rendered into the store at load time — so ignoring the
+ * file serves stale `.md` HTML on every request until the server restarts,
+ * even though the loader logs a reload.
+ */
+const devWatchOption = (
+  outDir: string,
+  contentWatchesRuntimeDir: boolean | undefined
+): string =>
+  contentWatchesRuntimeDir
+    ? `
+      // Astro's cache dir sits inside the docs collection, whose watcher would
+      // otherwise churn (and can loop) on Astro's own writes. Trade-off: .md
+      // body edits need a dev-server restart in this layout.
+      watch: {
+        ignored: ${JSON.stringify([join(outDir, ".astro", "**")])},
+      },`
+    : "";
+
 export const astroConfigTemplate = (options: {
   context: ProjectContext;
   config: ResolvedConfig;
@@ -286,6 +315,13 @@ export const astroConfigTemplate = (options: {
   reactCompilerPath?: string | null;
   /** Project tsconfig path aliases (`find` -> absolute dir), e.g. `@` -> src. */
   aliases?: Record<string, string>;
+  /**
+   * Whether the filesystem `docs` collection is rooted at a directory that
+   * contains the runtime dir (a migrated, `content.root: "."` project) — the
+   * only layout where the dev watcher must be kept out of Astro's cache dir.
+   * See {@link devWatchOption} for why this must stay scoped.
+   */
+  contentWatchesRuntimeDir?: boolean;
 }): string => {
   const { context, config, needsReact, pages, dataPath, themePath } = options;
   const {
@@ -446,6 +482,11 @@ export const astroConfigTemplate = (options: {
     `blumeIntegration(${JSON.stringify({ base: deployment.base, contentRoutes, pages })})`
   );
 
+  const watchOption = devWatchOption(
+    context.outDir,
+    options.contentWatchesRuntimeDir
+  );
+
   return `// Generated by Blume. Do not edit; this file is recreated on each run.
 ${defineConfigImport}
 import mdx from "@astrojs/mdx";
@@ -522,16 +563,7 @@ export default defineConfig({
     server: {
       fs: {
         allow: ${JSON.stringify(fsAllow)},
-      },
-      // Keep the file watcher out of Astro's own cache dir. In a migrated
-      // (root-rooted) project the docs collection is rooted at the project dir,
-      // so its glob-loader watcher would otherwise fire on every write Astro
-      // makes under .blume/.astro (data-store.json, content module manifests,
-      // self-hosted fonts) -- pure noise the loader logs as "No entry type
-      // found". Vite appends this to its default ignores.
-      watch: {
-        ignored: ${JSON.stringify([join(context.outDir, ".astro", "**")])},
-      },
+      },${watchOption}
     },
   },
 });
@@ -542,6 +574,21 @@ export default defineConfig({
 export const stagedContentDir = (outDir: string): string =>
   join(outDir, "content");
 
+/**
+ * The runtime dir relative to the docs collection `base` when it sits inside
+ * it (a migrated, `content.root: "."` project) — null when it lives elsewhere.
+ * Drives both the collection's negative glob (`contentConfigTemplate`) and
+ * whether the dev watcher is kept out of Astro's cache dir (the
+ * `contentWatchesRuntimeDir` option of `astroConfigTemplate`).
+ */
+export const runtimeDirWithin = (
+  base: string,
+  outDir: string
+): string | null => {
+  const rel = relative(base, outDir);
+  return rel && !rel.startsWith("..") && !isAbsolute(rel) ? rel : null;
+};
+
 /**
  * Astro's glob loader resolves `base` with `new URL(base, config.root)`. On
  * Windows an absolute path like `C:\\docs\\content` makes `new URL` parse the
@@ -585,11 +632,8 @@ export const contentConfigTemplate = (options: {
   // collection doesn't ingest ignored trees (`node_modules`, `snippets`, the
   // staged bodies under `.blume/content`, …) as entries. This matters when
   // the collection base is the project root (a migrated `.`-rooted project).
-  const outDirRel = relative(collectionBase, context.outDir);
-  const outDirIgnore =
-    outDirRel && !outDirRel.startsWith("..") && !isAbsolute(outDirRel)
-      ? [`!${outDirRel}/**`]
-      : [];
+  const outDirRel = runtimeDirWithin(collectionBase, context.outDir);
+  const outDirIgnore = outDirRel ? [`!${outDirRel}/**`] : [];
 
   // With no filesystem source, no route renders through `docs`, so glob nothing.
   // Beyond skipping wasted work, this is the only thing that keeps Astro's
@@ -1445,6 +1489,7 @@ const LayoutComponent = resolveSlot(layoutOverrides.Layout, RootLayout);
   page={{ title: seo.title ?? title, description: seo.description ?? frontmatter.description, route }}
   headings={headings}
   toc={data.config.toc}
+  dateFormat={data.config.dateFormat}
   themeMode={data.config.theme.mode}
   fontCssVars={data.fontCssVars}
   searchEnabled={data.config.search.enabled}
@@ -1502,6 +1547,7 @@ import RootLayout from "blume/components/layout/RootLayout.astro";
 import Update from "blume/components/content/Update.astro";
 import { withBase } from "blume/components/islands/base-path.ts";
 import { resolveSlot } from "blume/components/layout/overrides.ts";
+import { resolveDateFormatOptions } from "blume/core/date-format.ts";
 import { layoutOverrides } from "../generated/components.ts";
 import data from "blume:data";
 
@@ -1529,8 +1575,9 @@ const localeMeta = i18n
 const dir = localeMeta?.dir ?? "ltr";
 const htmlLang = i18n ? i18n.defaultLocale : "en";
 
-// Formatted in the same locale as the chrome, and in UTC, to match the
-// per-page "last updated" stamp.
+// Formatted in the same locale as the chrome, and with the configured
+// \`dateFormat\` (UTC by default), to match the per-page "last updated" stamp.
+const dateFormatOptions = resolveDateFormatOptions(data.config.dateFormat);
 const formatDate = (value: string | null | undefined) => {
   if (!value) {
     return;
@@ -1538,10 +1585,7 @@ const formatDate = (value: string | null | undefined) => {
   const date = new Date(value);
   return Number.isNaN(date.getTime())
     ? undefined
-    : new Intl.DateTimeFormat(htmlLang, {
-        dateStyle: "long",
-        timeZone: "UTC",
-      }).format(date);
+    : new Intl.DateTimeFormat(htmlLang, dateFormatOptions).format(date);
 };
 
 const slugify = (text: string) =>

package/src/audit/checks/duplicates.ts

@@ -1,17 +1,24 @@
+import { normalizeBasePath, stripBasePath } from "../../core/base-path.ts";
 import type { Diagnostic } from "../../core/types.ts";
 import { finding } from "../catalog.ts";
 import type { CheckId } from "../catalog.ts";
 import { pageSite } from "../locate.ts";
 import type { AuditContext, CheckModule, PageSnapshot } from "../types.ts";
+import { decodePath } from "../url.ts";
 
-const isNonCanonical = (page: PageSnapshot): boolean => {
+const isNonCanonical = (page: PageSnapshot, deployBase: string): boolean => {
   if (!page.canonical) {
     return false;
   }
   try {
+    // Canonicals are emitted as `site + base + route`; page URLs carry no
+    // deployment base — without stripping it, every page of a subpath
+    // deployment would look non-canonical and escape these checks entirely.
     return (
-      new URL(page.canonical).pathname.replace(/\/$/u, "") !==
-      page.url.replace(/\/$/u, "")
+      stripBasePath(
+        deployBase,
+        decodePath(new URL(page.canonical).pathname)
+      ).replace(/\/$/u, "") !== page.url.replace(/\/$/u, "")
     );
   } catch {
     return false;
@@ -19,8 +26,9 @@ const isNonCanonical = (page: PageSnapshot): boolean => {
 };
 
 /** Pages that can meaningfully be compared against each other for duplication. */
-const comparable = (context: AuditContext): PageSnapshot[] =>
-  context.pages.filter(
+const comparable = (context: AuditContext): PageSnapshot[] => {
+  const deployBase = normalizeBasePath(context.project.config.deployment.base);
+  return context.pages.filter(
     (page) =>
       page.indexable &&
       // A fallback page renders the default locale's content at a localized URL.
@@ -29,8 +37,9 @@ const comparable = (context: AuditContext): PageSnapshot[] =>
       !page.route?.fallback &&
       // A page that points its canonical elsewhere has already declared itself a
       // duplicate; that's the mechanism working, not a finding.
-      !isNonCanonical(page)
+      !isNonCanonical(page, deployBase)
   );
+};
 
 /**
  * Group pages by a value and report every group with more than one member.

package/src/audit/checks/indexability.ts

@@ -1,10 +1,11 @@
+import { normalizeBasePath, stripBasePath } from "../../core/base-path.ts";
 import { SITE_INFERRING_ADAPTERS } from "../../core/deployment-env.ts";
 import type { Diagnostic } from "../../core/types.ts";
 import { finding } from "../catalog.ts";
 import { pageSite } from "../locate.ts";
 import { ERROR_ROUTES } from "../types.ts";
 import type { AuditContext, CheckModule, PageSnapshot } from "../types.ts";
-import { normalizePath, siteOrigin } from "../url.ts";
+import { decodePath, normalizePath, siteOrigin } from "../url.ts";
 
 /** The canonical URL parsed, or null when it isn't a usable absolute URL. */
 const parseCanonical = (page: PageSnapshot): URL | null => {
@@ -76,7 +77,15 @@ const canonicalChecks = (
     return found;
   }
 
-  const target = normalizePath(canonical.pathname);
+  // Canonicals are emitted as `site + base + route`; page URLs and `byUrl`
+  // keys carry no deployment base, so strip it (and percent-encoding) before
+  // comparing.
+  const target = normalizePath(
+    stripBasePath(
+      normalizeBasePath(context.project.config.deployment.base),
+      decodePath(canonical.pathname)
+    )
+  );
   if (target === normalizePath(page.url)) {
     return found;
   }

package/src/audit/checks/network.ts

@@ -12,9 +12,17 @@ const SERVER_ERROR = 500;
 /** Past this, a page is slow enough that it costs you crawl budget and readers. */
 const SLOW_MS = 1500;
 
-/** The live URL a built page is served at, under the `--url` origin. */
-const liveUrl = (origin: string, page: PageSnapshot): string =>
-  new URL(page.url, origin).toString();
+/**
+ * The live URL a built page is served at, under the `--url` origin. Page URLs
+ * come from the built file tree and carry no `deployment.base`, but the live
+ * site serves everything under it — probing without the base would 4xx every
+ * page of a healthy subpath deployment.
+ */
+const liveUrl = (
+  origin: string,
+  page: PageSnapshot,
+  deployBase: string
+): string => new URL(`${deployBase}${page.url}`, origin).toString();
 
 /**
  * Whether the response failed outright, and how. Null when the page is served.
@@ -144,17 +152,23 @@ export const networkChecks: CheckModule = {
     }
 
     const found: Diagnostic[] = [];
-    const targets = context.pages.map((page) => liveUrl(origin, page));
+    const deployBase = normalizeBasePath(
+      context.project.config.deployment.base
+    );
+    const targets = context.pages.map((page) =>
+      liveUrl(origin, page, deployBase)
+    );
     // robots.txt and sitemap.xml are fetched alongside the pages: they're the
     // two files a crawler asks for first, and a deploy that hides them silently
-    // undoes everything else the audit checks.
-    const robotsUrl = new URL("/robots.txt", origin).toString();
-    const sitemapUrl = new URL("/sitemap.xml", origin).toString();
+    // undoes everything else the audit checks. They sit at the root of the
+    // build output, which the host serves under the deployment base.
+    const robotsUrl = new URL(`${deployBase}/robots.txt`, origin).toString();
+    const sitemapUrl = new URL(`${deployBase}/sitemap.xml`, origin).toString();
 
     const results = await probeAll([...targets, robotsUrl, sitemapUrl]);
 
     for (const page of context.pages) {
-      const result = results.get(liveUrl(origin, page));
+      const result = results.get(liveUrl(origin, page, deployBase));
       if (!result) {
         continue;
       }