@riebeckite/core 0.0.29 → 0.0.31

package/dist/index.d.ts

@@ -32,6 +32,8 @@ export { buildGraphEdges, layoutForceGraph, layoutRadialGraph, } from "./src/con
 export { IMAGE_EXTENSIONS } from "./src/content/image_extensions.js";
 export type { OutputChangeSet, OutputDescriptor, OutputKind, } from "./src/content/output_dependency.js";
 export { buildOutputInventory, determineOutputChanges, htmlOutputPath, } from "./src/content/output_dependency.js";
+export type { OutputPlan, OutputPlanAction, OutputPlanComparison, OutputPlanConflict, OutputPlanEntry, OutputPlanInput, OutputPlanKind, OutputPlanOwner, } from "./src/content/output_plan.js";
+export { buildOutputPlan, compareOutputPlan, } from "./src/content/output_plan.js";
 export { createPublicContentView, type PublicContentEntry, type PublicContentView, } from "./src/content/public_content_view.js";
 export type { PublishingResolutionOptions, PublishingVisibility, ResolvedPublishingState, } from "./src/content/publishing.js";
 export { resolvePublishingBuildTime, resolvePublishingState, } from "./src/content/publishing.js";

package/dist/index.js

@@ -826,7 +826,7 @@ function getFileName(filePath) {
 }
 
 // src/content/content_build_state.ts
-var CONTENT_BUILD_STATE_VERSION = 19;
+var CONTENT_BUILD_STATE_VERSION = 20;
 var CONTENT_BUILD_STATE_DIRECTORY = ".riebeckite";
 var CONTENT_BUILD_STATE_EXCLUDE = `${CONTENT_BUILD_STATE_DIRECTORY}/**`;
 
@@ -834,8 +834,11 @@ var CONTENT_BUILD_STATE_EXCLUDE = `${CONTENT_BUILD_STATE_DIRECTORY}/**`;
 import { randomUUID } from "node:crypto";
 import fs from "node:fs/promises";
 import path from "node:path";
+var MAX_CONTENT_BUILD_STATE_BYTES = 64 * 1024 * 1024;
 async function loadContentBuildState(statePath) {
   try {
+    const metadata = await fs.stat(statePath);
+    if (metadata.size > MAX_CONTENT_BUILD_STATE_BYTES) return void 0;
     const parsed = JSON.parse(await fs.readFile(statePath, "utf8"));
     return isContentBuildState(parsed) ? parsed : void 0;
   } catch {
@@ -922,7 +925,7 @@ function isContentBuildStateShape(value) {
 }
 function isManifestHookCache(value) {
   return Array.isArray(value) && value.every(
-    (entry) => isRecord2(entry) && typeof entry.pluginName === "string" && typeof entry.cacheable === "boolean" && (entry.pipelineFingerprint === void 0 || typeof entry.pipelineFingerprint === "string") && typeof entry.inputFingerprint === "string" && (entry.outputFingerprint === void 0 || typeof entry.outputFingerprint === "string") && (entry.snapshot === void 0 || isManifestHookSnapshot(entry.snapshot))
+    (entry) => isRecord2(entry) && typeof entry.pluginName === "string" && typeof entry.cacheVersion === "string" && typeof entry.cacheable === "boolean" && (entry.pipelineFingerprint === void 0 || typeof entry.pipelineFingerprint === "string") && typeof entry.inputFingerprint === "string" && (entry.outputFingerprint === void 0 || typeof entry.outputFingerprint === "string") && (entry.snapshot === void 0 || isManifestHookSnapshot(entry.snapshot))
   );
 }
 function isManifestHookSnapshot(value) {
@@ -2991,16 +2994,18 @@ function serializeManifestEntries(entries) {
     serialized.set(entry.slug, JSON.stringify(entry));
   return serialized;
 }
-function createManifestHookCacheEntry(pluginName, cacheable, pipelineFingerprint, inputFingerprint, manifest, beforeEntries, afterEntries) {
+function createManifestHookCacheEntry(pluginName, cacheVersion, cacheable, pipelineFingerprint, inputFingerprint, manifest, beforeEntries, afterEntries) {
   if (!cacheable)
     return {
       pluginName,
+      cacheVersion,
       cacheable,
       pipelineFingerprint,
       inputFingerprint
     };
   return {
     pluginName,
+    cacheVersion,
     cacheable,
     pipelineFingerprint,
     inputFingerprint,
@@ -3282,9 +3287,10 @@ var ManifestHookRunner = class {
       if (plugin.buildEnd) return "plugin-build-end";
       if (plugin.planGeneratedOutputs) return "plugin-generated-output-plan";
       if (!plugin.onManifestCreated) continue;
+      if (!plugin.manifestHookCache) return "manifest-hook-cache-disabled";
       const cached = previousCache[cacheIndex];
       cacheIndex += 1;
-      if (cached?.pluginName !== plugin.name || !cached.cacheable || cached.pipelineFingerprint !== pipelineFingerprint)
+      if (cached?.pluginName !== plugin.name || cached.cacheVersion !== plugin.manifestHookCache.version || !cached.cacheable || cached.pipelineFingerprint !== pipelineFingerprint)
         return "manifest-hook-cache-miss";
     }
     return void 0;
@@ -3298,10 +3304,14 @@ var ManifestHookRunner = class {
       manifest
     };
     let cacheIndex = 0;
-    let entriesBeforeHook = serializeManifestEntries(manifest.entries);
     for (const plugin of this.options.plugins()) {
       const hook = plugin.onManifestCreated;
       if (!hook) continue;
+      const cacheVersion = plugin.manifestHookCache?.version;
+      if (!cacheVersion) {
+        await this.runManifestHook(plugin, hook, context, "cache-disabled");
+        continue;
+      }
       const inputFingerprint = fingerprintManifestHookInput(manifest);
       const cached = previousCache[cacheIndex];
       cacheIndex += 1;
@@ -3313,46 +3323,29 @@ var ManifestHookRunner = class {
       );
       let restored = false;
       let restorePoint;
-      if (cached !== void 0 && cached.pluginName === plugin.name && cached.cacheable && cached.pipelineFingerprint === pipelineFingerprint && cached.inputFingerprint === inputFingerprint && cached.snapshot !== void 0 && cached.outputFingerprint !== void 0) {
+      if (cached !== void 0 && cached.pluginName === plugin.name && cached.cacheVersion === cacheVersion && cached.cacheable && cached.pipelineFingerprint === pipelineFingerprint && cached.inputFingerprint === inputFingerprint && cached.snapshot !== void 0 && cached.outputFingerprint !== void 0) {
         restorePoint = captureManifestHookRestorePoint(manifest);
         restored = applyManifestHookSnapshot(manifest, cached.snapshot);
         if (restored && fingerprintManifestHookSnapshot(manifest) === cached.outputFingerprint) {
           this.manifestHooksReused += 1;
           this.manifestHookCache.push(cached);
           this.recordManifestHookMetric(plugin.name, "reused", "cache-hit", 0);
-          entriesBeforeHook = serializeManifestEntries(manifest.entries);
           continue;
         }
       }
       if (restored && restorePoint)
         restoreManifestHookEntries(manifest, restorePoint);
+      const entriesBeforeHook = serializeManifestEntries(manifest.entries);
       const sideEffectsBefore = fingerprintManifestHookSideEffects(manifest);
       const outputCountBefore = this.options.generatedOutputCount();
       const diagnosticCountBefore = this.options.diagnosticCount();
       const manifestDiagnosticCountBefore = manifest.diagnostics.length;
-      const started = performance.now();
-      this.manifestHooksExecuted += 1;
-      try {
-        await runPluginHook(
-          plugin,
-          "onManifestCreated",
-          this.options.createPluginContext(plugin, context),
-          hook
-        );
-      } finally {
-        const durationMs = performance.now() - started;
-        this.manifestHookDurationMs += durationMs;
-        this.recordManifestHookMetric(
-          plugin.name,
-          "executed",
-          reason,
-          durationMs
-        );
-      }
+      await this.runManifestHook(plugin, hook, context, reason);
       const entriesAfterHook = serializeManifestEntries(manifest.entries);
       this.manifestHookCache.push(
         createManifestHookCacheEntry(
           plugin.name,
+          cacheVersion,
           plugin.resolveExternalDependencies === void 0 && sideEffectsBefore === fingerprintManifestHookSideEffects(manifest) && outputCountBefore === this.options.generatedOutputCount() && diagnosticCountBefore === this.options.diagnosticCount() && manifestDiagnosticCountBefore === manifest.diagnostics.length,
           pipelineFingerprint,
           inputFingerprint,
@@ -3361,7 +3354,27 @@ var ManifestHookRunner = class {
           entriesAfterHook
         )
       );
-      entriesBeforeHook = entriesAfterHook;
+    }
+  }
+  async runManifestHook(plugin, hook, context, reason) {
+    const started = performance.now();
+    this.manifestHooksExecuted += 1;
+    try {
+      await runPluginHook(
+        plugin,
+        "onManifestCreated",
+        this.options.createPluginContext(plugin, context),
+        hook
+      );
+    } finally {
+      const durationMs = performance.now() - started;
+      this.manifestHookDurationMs += durationMs;
+      this.recordManifestHookMetric(
+        plugin.name,
+        "executed",
+        reason,
+        durationMs
+      );
     }
   }
   recordManifestHookMetric(pluginName, outcome, reason, durationMs) {
@@ -6026,7 +6039,7 @@ var ContentManager = class {
   /** Resolves a page contributed by an enabled plugin. */
   async resolvePage(pathname) {
     const [manifest, contentIndex] = await Promise.all([
-      this.getManifest(),
+      this.getManifest({ incremental: false }),
       this.getContentIndex()
     ]);
     return await this.pluginRuntime.resolvePage(
@@ -6089,7 +6102,7 @@ var ContentManager = class {
   }
   requestBuildStateCommit(options) {
     if (this.pipelineOptions.commitBuildState === false) return;
-    if (options?.incremental === true) this.buildStateCommitRequested = true;
+    if (options?.incremental !== false) this.buildStateCommitRequested = true;
   }
   async commitBuildState() {
     if (this.buildStateCommitted || !this.buildStateCommitRequested || !this.manifest || !this.outputChangeSet) {
@@ -6515,6 +6528,120 @@ function clampFinite(value, min, max) {
   return clamp(value, min, max);
 }
 
+// src/content/output_plan.ts
+function buildOutputPlan(input) {
+  const candidates = [
+    ...input.inventory.map((output) => inventoryEntry(output, input)),
+    ...(input.removed ?? []).map(removedEntry),
+    ...entriesForPaths(
+      input.honoStaticRoutePaths,
+      "hono-static-route",
+      "hono-static-route",
+      "route"
+    ),
+    ...entriesForPaths(
+      input.viteClientAssetPaths,
+      "vite-client-asset",
+      "asset",
+      "client"
+    ),
+    ...entriesForPaths(
+      input.sitePublicAssetPaths,
+      "site-public-asset",
+      "asset",
+      "public"
+    )
+  ];
+  const byPath = /* @__PURE__ */ new Map();
+  for (const candidate of candidates) {
+    const existing = byPath.get(candidate.path) ?? [];
+    existing.push(candidate);
+    byPath.set(candidate.path, existing);
+  }
+  const conflicts = [...byPath.entries()].filter(
+    ([, entries2]) => new Set(entries2.map((entry) => entry.owner)).size > 1
+  ).map(([path6, entries2]) => ({
+    path: path6,
+    owners: [...new Set(entries2.map((entry) => entry.owner))].sort()
+  })).sort((left, right) => left.path.localeCompare(right.path));
+  const entries = [...byPath.values()].map((samePathEntries) => samePathEntries[0]).sort((left, right) => left.path.localeCompare(right.path));
+  return {
+    entries,
+    conflicts,
+    unknownPaths: entries.filter((entry) => entry.owner === "unknown").map((entry) => entry.path)
+  };
+}
+function compareOutputPlan(plan, actualPaths) {
+  const actual = new Set(actualPaths);
+  const entries = new Map(plan.entries.map((entry) => [entry.path, entry]));
+  const missingInPlan = [...actual].filter((path6) => {
+    const entry = entries.get(path6);
+    return entry === void 0 || entry.owner === "unknown";
+  }).sort();
+  const missingInDist = plan.entries.filter((entry) => entry.expectedToExist && !actual.has(entry.path)).map((entry) => entry.path).sort();
+  const publicationViolations = plan.entries.filter(
+    (entry) => entry.owner !== "unknown" && !entry.publicationEligible && actual.has(entry.path)
+  ).map((entry) => entry.path).sort();
+  const unknown = [
+    .../* @__PURE__ */ new Set([
+      ...plan.entries.filter((entry) => entry.owner === "unknown").map((entry) => entry.path),
+      ...missingInPlan
+    ])
+  ].sort();
+  const matched = plan.entries.filter(
+    (entry) => entry.owner !== "unknown" && entry.expectedToExist && actual.has(entry.path)
+  ).map((entry) => entry.path);
+  return {
+    matched,
+    missingInPlan,
+    missingInDist,
+    ownerConflicts: plan.conflicts,
+    unknown,
+    publicationViolations
+  };
+}
+function inventoryEntry(output, input) {
+  const affected = input.affectedPaths?.has(output.path) ?? true;
+  const cacheAvailable = input.cacheAvailable ?? false;
+  return {
+    path: output.path,
+    owner: output.producer.startsWith("content:") ? "content" : "plugin",
+    kind: output.kind,
+    source: output.producer,
+    dependencies: output.dependencies,
+    publicationEligible: true,
+    cacheEligible: true,
+    expectedToExist: true,
+    action: affected || !cacheAvailable ? "generate" : "reuse"
+  };
+}
+function removedEntry(output) {
+  return {
+    path: output.path,
+    owner: output.producer.startsWith("content:") ? "content" : "plugin",
+    kind: output.kind,
+    source: output.producer,
+    dependencies: output.dependencies,
+    publicationEligible: false,
+    cacheEligible: false,
+    expectedToExist: false,
+    action: "remove"
+  };
+}
+function entriesForPaths(paths, owner, kind, sourceKind) {
+  return [...paths ?? []].map((path6) => ({
+    path: path6,
+    owner,
+    kind,
+    source: `${sourceKind}:${path6}`,
+    dependencies: [{ type: "unknown" }],
+    publicationEligible: true,
+    cacheEligible: false,
+    expectedToExist: true,
+    action: "unknown"
+  }));
+}
+
 // src/content/public_content_view.ts
 var emptyEntries = Object.freeze([]);
 function createPublicContentView(manifest) {
@@ -6726,7 +6853,9 @@ export {
   buildContentCollections,
   buildGraphEdges,
   buildOutputInventory,
+  buildOutputPlan,
   calculateReadingTime,
+  compareOutputPlan,
   computePipelineFingerprint,
   createClientEntry,
   createContentGraph,

package/dist/src/content/content_build_state.d.ts

@@ -1,7 +1,7 @@
 import type { ContentManifestEntry } from "../types/content_manifest.js";
 import type { ContentSourceEntry } from "./content_source.js";
 import type { OutputDescriptor } from "./output_dependency.js";
-export declare const CONTENT_BUILD_STATE_VERSION = 19;
+export declare const CONTENT_BUILD_STATE_VERSION = 20;
 /**
  * Build state lives under `<content directory>/.riebeckite`. That directory is
  * build-time state, not content, so content sources must exclude it from scans
@@ -33,6 +33,7 @@ export type ContentBuildState = {
 };
 export type ManifestHookCacheEntry = {
     readonly pluginName: string;
+    readonly cacheVersion: string;
     readonly cacheable: boolean;
     readonly pipelineFingerprint: string | undefined;
     readonly inputFingerprint: string;

package/dist/src/content/manifest_hook_cache.d.ts

@@ -2,7 +2,7 @@ import type { ContentManifest, ContentManifestEntry } from "../types/content_man
 import type { ManifestHookCacheEntry, ManifestHookSnapshot } from "./content_build_state.js";
 export declare function fingerprintManifestHookInput(manifest: ContentManifest): string;
 export declare function serializeManifestEntries(entries: readonly ContentManifestEntry[]): Map<string, string>;
-export declare function createManifestHookCacheEntry(pluginName: string, cacheable: boolean, pipelineFingerprint: string | undefined, inputFingerprint: string, manifest: ContentManifest, beforeEntries: ReadonlyMap<string, string>, afterEntries: ReadonlyMap<string, string>): ManifestHookCacheEntry;
+export declare function createManifestHookCacheEntry(pluginName: string, cacheVersion: string, cacheable: boolean, pipelineFingerprint: string | undefined, inputFingerprint: string, manifest: ContentManifest, beforeEntries: ReadonlyMap<string, string>, afterEntries: ReadonlyMap<string, string>): ManifestHookCacheEntry;
 export declare function fingerprintManifestHookSideEffects(manifest: ContentManifest): string;
 export declare function fingerprintManifestHookSnapshot(manifest: ContentManifest): string;
 export type ManifestHookRestorePoint = {

package/dist/src/content/output_plan.d.ts

@@ -0,0 +1,44 @@
+import type { OutputDependency } from "../types/output_dependency.js";
+import type { OutputDescriptor } from "./output_dependency.js";
+export type OutputPlanOwner = "content" | "plugin" | "hono-static-route" | "vite-client-asset" | "site-public-asset" | "unknown";
+export type OutputPlanKind = "content" | "redirect" | "plugin-page" | "generated" | "hono-static-route" | "asset" | "unknown";
+export type OutputPlanAction = "generate" | "reuse" | "remove" | "unknown";
+export type OutputPlanEntry = {
+    readonly path: string;
+    readonly owner: OutputPlanOwner;
+    readonly kind: OutputPlanKind;
+    readonly source: string;
+    readonly dependencies: readonly OutputDependency[];
+    readonly publicationEligible: boolean;
+    readonly cacheEligible: boolean;
+    readonly expectedToExist: boolean;
+    readonly action: OutputPlanAction;
+};
+export type OutputPlanConflict = {
+    readonly path: string;
+    readonly owners: readonly OutputPlanOwner[];
+};
+export type OutputPlan = {
+    readonly entries: readonly OutputPlanEntry[];
+    readonly conflicts: readonly OutputPlanConflict[];
+    readonly unknownPaths: readonly string[];
+};
+export type OutputPlanComparison = {
+    readonly matched: readonly string[];
+    readonly missingInPlan: readonly string[];
+    readonly missingInDist: readonly string[];
+    readonly ownerConflicts: readonly OutputPlanConflict[];
+    readonly unknown: readonly string[];
+    readonly publicationViolations: readonly string[];
+};
+export type OutputPlanInput = {
+    readonly inventory: readonly OutputDescriptor[];
+    readonly affectedPaths?: ReadonlySet<string>;
+    readonly removed?: readonly OutputDescriptor[];
+    readonly cacheAvailable?: boolean;
+    readonly honoStaticRoutePaths?: ReadonlySet<string>;
+    readonly viteClientAssetPaths?: ReadonlySet<string>;
+    readonly sitePublicAssetPaths?: ReadonlySet<string>;
+};
+export declare function buildOutputPlan(input: OutputPlanInput): OutputPlan;
+export declare function compareOutputPlan(plan: OutputPlan, actualPaths: Iterable<string>): OutputPlanComparison;

package/dist/src/plugin/manifest_hooks.d.ts

@@ -37,6 +37,7 @@ export declare class ManifestHookRunner {
     getNoChangeFastPathBlockReason(previousCache: readonly ManifestHookCacheEntry[], pipelineFingerprint: string | undefined): string | undefined;
     getCache(): readonly ManifestHookCacheEntry[];
     runManifestCreated(manifest: ContentManifest, contentIndex: Map<string, string>, previousCache: readonly ManifestHookCacheEntry[], pipelineFingerprint: string | undefined): Promise<void>;
+    private runManifestHook;
     private recordManifestHookMetric;
 }
 export {};

package/dist/src/types/content_manifest.d.ts

@@ -23,13 +23,6 @@ export type ContentAsset = {
 export type ContentManifestPluginAsset = PluginAsset & {
     path: string;
 };
-/**
- * The standard `article.*` positions the article consumer recognizes.
- *
- * These constants are a convenience for Sites that prefer named references;
- * writing the slot string inline (for example `name="article.metadata"`) stays
- * the recommended, most readable form in TSX layouts.
- */
 /** Client entries and their explicitly public configuration. */
 export type ContentManifestPluginClientEntry = PluginClientEntry;
 export type ContentManifestEntry = {

package/dist/src/types/plugin.d.ts

@@ -74,6 +74,9 @@ export type RiebeckitePlugin<TOptions = unknown> = {
     extendContentLocations?(context: PluginContentLocationAugmentContext): void | Promise<void>;
     onPostParsed?(context: PluginPostContext): void | Promise<void>;
     onPostProcessed?(context: PluginPostContext): void | Promise<void>;
+    manifestHookCache?: {
+        version: string;
+    };
     onManifestCreated?(context: PluginManifestContext): void | Promise<void>;
     extendMarkdownPipeline?(pipeline: MarkdownPipeline, context: MarkdownPipelineContext): void;
     extendHtmlPipeline?(pipeline: HtmlPipeline): void;

package/dist/src/types/plugin_endpoint.d.ts

@@ -36,6 +36,8 @@ export type PluginEndpoint = {
     path: string;
     /** Defaults to `GET` when omitted. */
     method?: PluginEndpointMethod;
+    /** Defaults to `true`; set to `false` for endpoints that only use configuration. */
+    requiresManifest?: boolean;
     handler(context: PluginEndpointContext): PluginEndpointResponse | Promise<PluginEndpointResponse>;
 };
 export type PluginEndpointOptions = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@riebeckite/core",
-  "version": "0.0.29",
+  "version": "0.0.31",
   "license": "Apache-2.0",
   "type": "module",
   "main": "./dist/index.js",
@@ -49,7 +49,7 @@
   },
   "devDependencies": {
     "tsx": "^4.22.4",
-    "@riebeckite/test": "0.0.29"
+    "@riebeckite/test": "0.0.31"
   },
   "repository": {
     "type": "git",