@kudzujs/core 0.16.12 → 0.16.13

package/MIGRATION_ROADMAP.md

@@ -57,7 +57,7 @@ Syntax compatibility does not mean reproducing React wholesale. Kudzu accepts th
 - stronger JavaScript failure resilience;
 - no remaining material large-route build-scaling weakness.
 
-The completed 0.9 plan defines the cross-framework comparison and release gate. The active application packet is `0.20.2` in the capability release plan below. Benchmark-only feature omission, unmatched accessibility, weighted scores that hide losses, and unrecorded environment differences do not count as proof.
+The completed 0.9 plan defines the cross-framework comparison and release gate. The active application packet is `0.20.3` in the capability release plan below. Benchmark-only feature omission, unmatched accessibility, weighted scores that hide losses, and unrecorded environment differences do not count as proof.
 
 ### 0.10.0 Through 0.21.x: Application Capability Release Train
 

package/PERFORMANCE.md

@@ -2,6 +2,19 @@
 
 Reproducibility classes: `npm run benchmark`, `npm run benchmark:keyed`, `npm run benchmark:native`, `npm run benchmark:module-cache`, `npm run benchmark:project-navigation`, `npm run benchmark:project-state`, and `npm run benchmark:source-scale` are maintained in this repository; `npm run benchmark:commerce` is a maintained paired runner over the public external storefront; older excluded-workspace sections are historical provenance only and are not current framework rankings.
 
+## 0.16.13 Route Artifact Explanations
+
+Measured 2026-09-01 on Linux x64 with Node 24.14.0. Route explanation is a
+build-time projection over existing route, source, compatibility, ownership,
+capability, and artifact records. Representative deploy manifests and hashes
+remain unchanged. The maintained Worker graph remains 907 raw / 477 gzip B and
+the window graph remains 14,456 raw / 6,160 gzip B. Seven clean builds record a
+605 ms median on this host without a timing comparison. Browser-disabled and
+required-Chrome suites pass 296/296 tests, package smoke passes, and focused CLI
+coverage includes an effect-owned Worker route, configured base, exact missing
+route diagnostic, deterministic output, artifact hashes, and zero-JavaScript
+static exclusion.
+
 ## 0.16.12 Bounded Application Inspection
 
 Measured 2026-08-31 on Linux x64 with Node 24.14.0. Inspection is a build-time

package/README.md

@@ -14,7 +14,7 @@ Kudzu compiles ordinary React-shaped TypeScript and TSX into complete static HTM
 
 > Experimental `0.16.x`: the compiler API and supported TSX surface may change.
 
-**Latest release: 0.16.12 - Bounded application inspection.** `kudzu inspect --json` now projects reachable modules, routes, packages, capabilities, semantic owners, and first blockers from the existing build graph in deterministic bounded output without dumping raw IR. Read the [release notes](./RELEASES.md#01612---bounded-application-inspection), open the [release page](https://github.com/kudzujs/kudzu/releases/tag/v0.16.12), or follow the [architecture packet](./docs/next-architecture/README.md).
+**Latest release: 0.16.13 - Route artifact explanations.** `kudzu explain --route <route> --json` now traces one exact emitted route from authored source and semantic ownership through its capability family and selected runtime, handler, chunk, style, and Worker bytes without exposing raw IR. Read the [release notes](./RELEASES.md#01613---route-artifact-explanations), open the [release page](https://github.com/kudzujs/kudzu/releases/tag/v0.16.13), or follow the [architecture packet](./docs/next-architecture/README.md).
 
 - [Documentation](https://kudzujs.cloud/docs)
 - [Installation guide](https://kudzujs.cloud/docs#install)

package/RELEASES.md

@@ -1,5 +1,35 @@
 # Kudzu Releases
 
+## 0.16.13 - Route Artifact Explanations
+
+Kudzu 0.16.13 lets tools ask why one exact emitted route owns its browser bytes
+without reading raw semantic records or reconstructing an artifact graph.
+
+### Changed in 0.16.13
+
+- Adds `kudzu explain --route <route> --json`, which runs the authoritative build
+  and projects authored source, normalization provenance, semantic owners,
+  capability facts, selected artifacts, and byte reasons for one emitted route.
+- Reports raw and gzip byte totals plus SHA-256 hashes for runtime, handler,
+  transitive chunk, stylesheet, and Worker artifacts already selected by the
+  existing route artifact report.
+- Explains zero-JavaScript routes from an absent behavior runtime family and an
+  empty compiler-selected JavaScript closure.
+- Uses exact configured-base route matching and returns the structured
+  `explain.route.not-found` diagnostic for missing routes.
+- Sorts every bounded section before truncation and excludes HTML, generated
+  code, RouteIR, ModuleIR, captures, and state values.
+- Adds no analyzer, semantic primitive, compiler pass, runtime concept, public
+  application API, or browser byte.
+- Updates `create-kudzu@0.1.138` to generate projects on
+  `@kudzujs/core@^0.16.13`.
+
+### Upgrade
+
+```sh
+npm install @kudzujs/core@^0.16.13
+```
+
 ## 0.16.12 - Bounded Application Inspection
 
 Kudzu 0.16.12 lets tools select the first migration blocker from a compact

package/bin/kudzu.mjs

@@ -6,27 +6,34 @@ import { fileURLToPath } from "node:url"
 
 const command = process.argv[2] ?? "dev"
 
-if ((command === "build" || command === "inspect") && !process.env.KUDZU_BUILD_CHILD) {
+if ((command === "build" || command === "inspect" || command === "explain") && !process.env.KUDZU_BUILD_CHILD) {
   const child = spawnSync(process.execPath, ["--expose-gc", "--max-semi-space-size=8", fileURLToPath(import.meta.url), ...process.argv.slice(2)], {
     stdio: "inherit",
     env: { ...process.env, KUDZU_BUILD_CHILD: "1" }
   })
   if (child.error) throw child.error
   process.exitCode = child.status ?? 1
-} else if (command === "build" || command === "dev" || command === "inspect") {
+} else if (command === "build" || command === "dev" || command === "inspect" || command === "explain") {
   module.enableCompileCache?.()
-  const { build, dev, inspect } = await import("../framework/build.mjs")
-  const json = command === "build" && process.argv.includes("--json")
+  const { build, dev, explain, inspect } = await import("../framework/build.mjs")
+  const json = (command === "build" || command === "explain") && process.argv.includes("--json")
   try {
-    if (command === "inspect") {
+    if (command === "inspect" || command === "explain") {
+      const args = process.argv.slice(3)
+      const routeIndex = args.indexOf("--route")
+      const route = routeIndex === -1 ? undefined : args[routeIndex + 1]
+      const validExplain = command !== "explain" || args.length === 3 && args.filter(arg => arg === "--json").length === 1 && args.filter(arg => arg === "--route").length === 1 && route && !route.startsWith("--") && args.every((arg, index) => arg === "--json" || arg === "--route" || index === routeIndex + 1)
       if (!process.argv.includes("--json")) {
-        console.error("Use: kudzu inspect --json")
+        console.error(command === "inspect" ? "Use: kudzu inspect --json" : "Use: kudzu explain --route <route> --json")
+        process.exitCode = 1
+      } else if (!validExplain) {
+        console.error("Use: kudzu explain --route <route> --json")
         process.exitCode = 1
       } else {
         const log = console.log
         console.log = console.error
         try {
-          process.stdout.write(`${JSON.stringify(await inspect())}\n`)
+          process.stdout.write(`${JSON.stringify(await (command === "inspect" ? inspect() : explain({ route })))}\n`)
         } finally {
           console.log = log
         }
@@ -40,6 +47,6 @@ if ((command === "build" || command === "inspect") && !process.env.KUDZU_BUILD_C
     process.exitCode = 1
   }
 } else {
-  console.error(`Unknown command: ${command}\nUse: kudzu <build|dev|inspect>`)
+  console.error(`Unknown command: ${command}\nUse: kudzu <build|dev|inspect|explain>`)
   process.exitCode = 1
 }

package/docs/next-architecture/README.md

@@ -15,7 +15,7 @@ The completed `0.9.0` milestone is recorded in [`0.9-semantic-compression.md`](.
 
 [`1.0-large-application-compatibility-audit.md`](./1.0-large-application-compatibility-audit.md) records the first post-0.9 probes against Memos, Apache Answer, and Actual Budget. The audit finds that reduced slices build but whole-application source retention and behavior parity do not yet pass.
 
-[`application-capability-release-plan.md`](./application-capability-release-plan.md) is the authoritative post-0.9 execution queue, currently at `0.20.2`. It assigns one application-capability section to each minor release and one independently accepted evidence packet to each patch release from `0.10.0` through the `1.0.0` gate. It supersedes the provisional 0.10/0.11/0.12 tool-first ordering in the completed 0.9 handoff without rewriting that historical record.
+[`application-capability-release-plan.md`](./application-capability-release-plan.md) is the authoritative post-0.9 execution queue, currently at `0.20.3`. It assigns one application-capability section to each minor release and one independently accepted evidence packet to each patch release from `0.10.0` through the `1.0.0` gate. It supersedes the provisional 0.10/0.11/0.12 tool-first ordering in the completed 0.9 handoff without rewriting that historical record.
 
 ## Required Invariants
 

package/docs/next-architecture/application-capability-release-plan.md

@@ -1856,6 +1856,23 @@ ships as `@kudzujs/core@0.16.12` with `create-kudzu@0.1.137`.
 - **Done condition:** existing route records and artifact reports answer the
   query with bounded output.
 
+Completed by `@kudzujs/core@0.16.13` and `create-kudzu@0.1.138`. The
+`worker-effects` fixture proves exact configured-base lookup for an effect-owned
+Worker route, authored source closure, `Dashboard` ownership, capability family,
+runtime/handler/Worker byte reasons, raw/gzip totals, hashes, deterministic
+output, structured missing-route diagnostics, and a static sibling with an empty
+JavaScript closure. The implementation is one 137-line bounded projection over
+existing source results, compatibility sites, route records, and the sole route
+artifact report plus the existing build/CLI seam. It adds no analyzer, semantic
+primitive, compiler pass, normalization entry, runtime concept, or browser
+module. Representative deploy manifests and hashes remain unchanged. Worker and
+window graphs remain 907 raw / 477 gzip and 14,456 raw / 6,160 gzip bytes; seven
+clean builds record a 605 ms median without a timing comparison. Browser-disabled
+and required-Chrome suites pass 296/296 tests, and package smoke and artifact
+accounting pass. Fixed 100-record section limits expose totals and omitted counts;
+the command requires one exact emitted route and intentionally excludes raw IR,
+HTML, generated code, captures, and state values.
+
 ### `0.20.3`: Deterministic Normalize And Fix
 
 - **Purpose:** automate only edits proven safe and useful by recorded AI trials.
@@ -2073,3 +2090,4 @@ release transaction where possible or document and publish a forward-fix patch.
 | `0.19.5` | Deferred by stop condition | Resume only from a complete pinned Actual Budget workspace with an executable dependency graph and honest retention denominator. | Sparse acquisition omits required workspace and core packages; no compatibility claim |
 | `0.20.0` | Released as `0.16.11` | Preserve stable diagnostic schema/codes, authored ranges, human errors, compatibility reuse, and zero browser/output delta. | Patch release retained the `0.16.x` public version line |
 | `0.20.1` | Released as `0.16.12` | Preserve bounded deterministic reachable inventory, first-blocker retention, existing-record reuse, and zero browser/output delta. | Patch release retained the `0.16.x` public version line |
+| `0.20.2` | Released as `0.16.13` | Preserve exact emitted-route lookup, authored provenance, semantic ownership, capability/artifact byte reasons and hashes, bounded deterministic output, structured missing-route diagnostics, and zero-JavaScript explanation. | Patch release retained the `0.16.x` public version line |

package/docs/next-architecture/compiler-current-architecture.md

@@ -1,12 +1,12 @@
 # Current Compiler Architecture
 
-This maps the current `0.16.12` architecture, built on the completed `0.9.0` semantic-compression release and `0.8.23` Goal A compiler foundation. The active application packet is `0.20.2`; file and function names are the stable references, while line numbers are intentionally omitted because later work may still move code.
+This maps the current `0.16.13` architecture, built on the completed `0.9.0` semantic-compression release and `0.8.23` Goal A compiler foundation. The active application packet is `0.20.3`; file and function names are the stable references, while line numbers are intentionally omitted because later work may still move code.
 
 ## Responsibility Map
 
 | Responsibility | Current owner | Current contract |
 |---|---|---|
-| CLI entry | [`bin/kudzu.mjs`](../../bin/kudzu.mjs) | Dispatches build and development commands. |
+| CLI entry | [`bin/kudzu.mjs`](../../bin/kudzu.mjs) | Dispatches build, development, inspection, and exact-route explanation commands. |
 | Project session | [`framework/compiler/project-session.mjs`](../../framework/compiler/project-session.mjs), `createProjectSession()` | Owns one absolute root, standard project paths, source records, bound graph operations, and Worker compiler. Production builds use one session; development retains it across rebuilds. Omitted roots resolve from call-time CWD. |
 | Parsed module cache and symbols | [`framework/compiler/project-session.mjs`](../../framework/compiler/project-session.mjs) | Parses each unchanged source module once per ProjectSession and records source-local declaration/import/re-export sites. Stable ModuleSymbol records resolve direct, aliased, barrel, and `export *` exports with cycle and ambiguity checks; repeated resolutions are cached against their source dependencies, and normalization consumers locate the resolved SiteId in a fresh clone with independent parent links. |
 | Build orchestration | [`framework/build.mjs`](../../framework/build.mjs), `build()`, `buildWithSession()` | Coordinates config, discovery, source compilation, RouteBuildRecord collection, CapabilityIR projection, generator invocation, artifact emission, and `afterBuild`. A retained session caches source results and pre-family route renders by page graph; successful builds alone replace that cache. |
@@ -22,6 +22,7 @@ This maps the current `0.16.12` architecture, built on the completed `0.9.0` sem
 | Component ownership analysis | [`framework/compiler/analysis/component-analysis.mjs`](../../framework/compiler/analysis/component-analysis.mjs) | Produces ComponentAnalysis v2 with ordered JSON-safe owner and specialization slots for state, setters, props, refs, IDs, direct SignalIR links, direct static property/consumer links, structural OwnerRefs, source-local SiteIds, and source provenance. Three direct callback/ref component boundaries specialize into the same parent signal and intrinsic ownership; Context action-private setters may remain compiler-only and receive collision-free consumer-local aliases; AST identity remains private to its source-local session. |
 | Per-source descriptor registration | [`framework/compiler/descriptor-session.mjs`](../../framework/compiler/descriptor-session.mjs), `createSemanticArtifact()`, `createDescriptorSession()` | Keeps AST descriptors private during analysis, then finalizes ModuleIR v2 with deterministic SymbolRef, SharedStateIR, SharedActionIR, SignalIR, HandlerIR, BindingIR, DerivedIR, EffectIR, KeyedBlockIR, and ImportIR slots. One fail-closed boundary validates every source-local and component ownership edge before build-module generation. |
 | Route artifact graph | [`framework/compiler/route-build-record.mjs`](../../framework/compiler/route-build-record.mjs), `createRouteBuildRecord()`, `planRouteArtifacts()`; [`framework/compiler/route-artifact-report.mjs`](../../framework/compiler/route-artifact-report.mjs), `createRouteArtifactReport()` | Validates each rendered route's RouteIR, capabilities, entry paths, styles, and exact handler/effect references. Handler and Worker esbuild metafiles project transitive output edges back through those records into deterministic per-route capability signatures and runtime requirements plus emitted handler, Worker, stylesheet, and shared-chunk closure. |
+| Tool projections | [`framework/compiler/inspection-report.mjs`](../../framework/compiler/inspection-report.mjs), `createInspectionReport()`; [`framework/compiler/explanation-report.mjs`](../../framework/compiler/explanation-report.mjs), `createExplanationReport()` | Projects bounded deterministic reachable-application inventory and one exact route's authored provenance, ownership, capability, artifact byte reasons, hashes, and zero-JavaScript explanation from existing build records. Raw semantic IR, generated code, HTML, captures, and state values remain private. |
 | Route contract validation | [`framework/compiler/route-ir.mjs`](../../framework/compiler/route-ir.mjs), `assertRouteIR()` | Fails before artifact selection for invalid state/parameter identity, commands, native/effect captures and dependencies, reactive descriptors, conditions, keyed-list identity/ownership, marker fields, or JSON safety. Immutable in-memory contracts validate once by identity. |
 | Command IR and codegen | [`framework/compiler/optimize/command-specialization.mjs`](../../framework/compiler/optimize/command-specialization.mjs), [`framework/compiler/ir/module-ir.mjs`](../../framework/compiler/ir/module-ir.mjs), [`framework/compiler/codegen/command-codegen.mjs`](../../framework/compiler/codegen/command-codegen.mjs) | Direct commands use the existing fast path; proven immutable state aliases and one-call local helpers specialize to the same JSON-safe command ModuleIR. Recursion, escape, mutation, and dynamic helper dispatch fail explicitly, while unrelated handlers retain native ESM. Codegen emits the existing `__kBehavior` AST and command ABI. |
 | Source compilation | [`framework/compiler/source-compiler.mjs`](../../framework/compiler/source-compiler.mjs), `compileSource()` | Runs TypeScript with the Kudzu transformer, rejects surviving React/Router references, and returns a JSON-safe project-relative build module, component analysis, ModuleIR, optional handler module, and imported assets without filesystem writes. |

package/docs/next-architecture/large-application-ai-native-roadmap.md

@@ -2,9 +2,9 @@
 
 ## Status
 
-Completed compiler-foundation record and longer-term plan after `0.8.35`. The [`0.9-semantic-compression.md`](./0.9-semantic-compression.md) execution queue is complete. The active queue for current work is [`application-capability-release-plan.md`](./application-capability-release-plan.md) at packet `0.20.2`. This document does not mark any remaining planned capability as supported and does not authorize a React runtime, VDOM, hydration, retained browser component tree, generic rerenderer, public store/query/resource API, SPA router, or islands.
+Completed compiler-foundation record and longer-term plan after `0.8.35`. The [`0.9-semantic-compression.md`](./0.9-semantic-compression.md) execution queue is complete. The active queue for current work is [`application-capability-release-plan.md`](./application-capability-release-plan.md) at packet `0.20.3`. This document does not mark any remaining planned capability as supported and does not authorize a React runtime, VDOM, hydration, retained browser component tree, generic rerenderer, public store/query/resource API, SPA router, or islands.
 
-[`MIGRATION_ROADMAP.md`](../../MIGRATION_ROADMAP.md) remains the product authority for product invariants and fixture-driven feature selection. [`application-capability-release-plan.md`](./application-capability-release-plan.md) is authoritative for current work order and evidence at packet `0.20.2`; this plan retains the completed foundation, deferred program, and long-term production gates. If implementation evidence changes either boundary, update the relevant document before broadening a patch.
+[`MIGRATION_ROADMAP.md`](../../MIGRATION_ROADMAP.md) remains the product authority for product invariants and fixture-driven feature selection. [`application-capability-release-plan.md`](./application-capability-release-plan.md) is authoritative for current work order and evidence at packet `0.20.3`; this plan retains the completed foundation, deferred program, and long-term production gates. If implementation evidence changes either boundary, update the relevant document before broadening a patch.
 
 ## Product Outcome
 
@@ -483,4 +483,4 @@ The first comparison is Kudzu versus React + Vite using the same agent, model, t
 
 ## Immediate Decision
 
-All listed foundation and `0.9` slices are complete. Current work continues at `0.20.2` `kudzu explain --route` under the [`application-capability-release-plan.md`](./application-capability-release-plan.md); keep ResourceIR limited to qualifying independent fixtures, and do not add range ownership, virtualization, optimistic transactions, a public adapter/store API, or a router before evidence justifies them.
+All listed foundation and `0.9` slices are complete. Current work continues at `0.20.3` deterministic normalize and fix under the [`application-capability-release-plan.md`](./application-capability-release-plan.md); keep ResourceIR limited to qualifying independent fixtures, and do not add range ownership, virtualization, optimistic transactions, a public adapter/store API, or a router before evidence justifies them.

package/docs/next-architecture/versioning.md

@@ -1,6 +1,6 @@
 # Planned Version Sequence
 
-This is an execution sequence, not release history. `0.8.16` through `0.8.62` are completed scopes represented by package/release records. The `0.10.0` through `1.0.0` minor/patch sequence is maintained in [`application-capability-release-plan.md`](./application-capability-release-plan.md), currently at `0.20.2`; that plan supersedes the provisional tool-first 0.10/0.11/0.12 ordering in the completed 0.9 handoff.
+This is an execution sequence, not release history. `0.8.16` through `0.8.62` are completed scopes represented by package/release records. The `0.10.0` through `1.0.0` minor/patch sequence is maintained in [`application-capability-release-plan.md`](./application-capability-release-plan.md), currently at `0.20.3`; that plan supersedes the provisional tool-first 0.10/0.11/0.12 ordering in the completed 0.9 handoff.
 
 Keep each patch behavior-preserving and independently reviewable. If a boundary proves inseparable, revise this plan before combining releases; do not silently broaden a patch.
 
@@ -66,7 +66,7 @@ Keep each patch behavior-preserving and independently reviewable. If a boundary
 
 ## Generator Versions
 
-`create-kudzu@0.1.137` retains the explicit install instructions and generates projects with `@kudzujs/core@^0.16.12`.
+`create-kudzu@0.1.138` retains the explicit install instructions and generates projects with `@kudzujs/core@^0.16.13`.
 
 ## Release Boundary
 

package/framework/build.mjs

@@ -5,7 +5,8 @@ import { pathToFileURL } from "node:url"
 import { build as bundle, transform } from "esbuild"
 import { createEffectCodegen } from "./compiler/effect-codegen.mjs"
 import { createCompatibilityReport } from "./compiler/compatibility-registry.mjs"
-import { diagnosticEnvelope, normalizeDiagnosticError } from "./compiler/diagnostics.mjs"
+import { createDiagnosticError, diagnosticEnvelope, normalizeDiagnosticError } from "./compiler/diagnostics.mjs"
+import { createExplanationReport } from "./compiler/explanation-report.mjs"
 import { createInspectionReport } from "./compiler/inspection-report.mjs"
 import { generateListRuntime } from "./compiler/list-runtime-codegen.mjs"
 import { assetPath, browserPath, relativeModulePath, withBase } from "./compiler/path-helpers.mjs"
@@ -44,7 +45,12 @@ export async function inspect({ minify = true, root: projectRoot = process.cwd()
   return buildWithSession(project, { quiet: true, minify, retainCache: false, inspection: true })
 }
 
-export async function buildWithSession(project, { changedFiles, quiet = false, minify = true, retainCache = true, inspection = false } = {}) {
+export async function explain({ route, minify = true, root: projectRoot = process.cwd() } = {}) {
+  const project = createProjectSession(projectRoot)
+  return buildWithSession(project, { quiet: true, minify, retainCache: false, explanationRoute: route })
+}
+
+export async function buildWithSession(project, { changedFiles, quiet = false, minify = true, retainCache = true, inspection = false, explanationRoute } = {}) {
   const { root, outputDirectory } = project
   const stagedOutput = join(root, ".kudzu-dist-staging")
   const backupOutput = join(root, ".kudzu-dist-backup")
@@ -53,11 +59,11 @@ export async function buildWithSession(project, { changedFiles, quiet = false, m
   try {
     await recoverOutput(outputDirectory, backupOutput)
     await rm(stagedOutput, { recursive: true, force: true })
-    const { result, pageCount, behaviorCount, cache, inspectionData } = await buildInto(project, stagedOutput, { changedFiles, minify, quiet, retainCache })
+    const { result, pageCount, behaviorCount, cache, inspectionData, explanation } = await buildInto(project, stagedOutput, { changedFiles, minify, quiet, retainCache, explanationRoute })
     await promoteOutput(stagedOutput, outputDirectory, backupOutput)
     project.buildCache = retainCache ? cache : undefined
     if (!quiet) console.log(`Built ${pageCount} page(s), ${behaviorCount} interactive page(s) into dist/`)
-    return inspection ? createInspectionReport(inspectionData) : result
+    return explanationRoute ? explanation : inspection ? createInspectionReport(inspectionData) : result
   } catch (error) {
     const normalized = normalizeDiagnosticError(error, root)
     const envelope = inspection && diagnosticEnvelope(normalized)
@@ -76,7 +82,7 @@ export async function buildWithSession(project, { changedFiles, quiet = false, m
   }
 }
 
-async function buildInto(project, outputDirectory, { changedFiles, minify, quiet, retainCache }) {
+async function buildInto(project, outputDirectory, { changedFiles, minify, quiet, retainCache, explanationRoute }) {
   const { root, sourceDirectory, pagesDirectory, workDirectory } = project
   const previous = retainCache ? project.buildCache : undefined
   project.buildGeneration = (project.buildGeneration ?? 0) + 1
@@ -184,6 +190,7 @@ async function buildInto(project, outputDirectory, { changedFiles, minify, quiet
   const bindingPlaceholder = placeholders.binding
   const listPlaceholder = placeholders.list
   const pageRenders = new Map()
+  const routePageFiles = new Map()
   let renderedPages = 0
 
   for (const pageFile of pageFiles) {
@@ -304,6 +311,7 @@ async function buildInto(project, outputDirectory, { changedFiles, minify, quiet
         runtimeSchema
       })
       routeRecords.push(record)
+      routePageFiles.set(record, pageFile)
       if (navigationGroup) navigationGroup.buildRecords.push(record)
       routeDrafts.push({ record, runtimeSchema, navigationGroup, applicationRoute, effectPath, nativePath, paramPath })
       if (!retainCache && config.afterBuild === undefined) {
@@ -534,10 +542,21 @@ async function buildInto(project, outputDirectory, { changedFiles, minify, quiet
     await config.afterBuild({ root, outDir: outputDirectory, sourceDir: sourceDirectory, base, routes: plans.map(plan => plan.route), plans, rewrites: sortedRewrites, artifacts })
   }
 
+  let explanation
+  if (explanationRoute) {
+    const artifact = artifacts.routes.find(entry => entry.route === explanationRoute)
+    const record = routeRecords.find(entry => entry.route === explanationRoute)
+    if (!artifact || !record) throw createDiagnosticError({ code: "explain.route.not-found", stage: "explain", message: `No emitted route exactly matches ${JSON.stringify(explanationRoute)}.`, suggestion: "Use an exact emitted route listed by kudzu inspect --json." })
+    const pageFile = routePageFiles.get(record)
+    const sourceFiles = [...pageSources.get(pageFile)].map(file => relative(root, file).replaceAll(sep, "/"))
+    explanation = await createExplanationReport({ route: explanationRoute, record, artifact, entrySource: relative(root, pageFile).replaceAll(sep, "/"), sourceFiles, sourceResults, compatibility, outputDirectory, base })
+  }
+
   const incremental = { compiledModules, renderedPages }
   return {
     result: { sourceResults, incremental },
     inspectionData: { sourceFiles: sourceFiles.map(file => relative(root, file).replaceAll(sep, "/")), sourceResults, compatibility, artifacts },
+    explanation,
     pageCount: routeRecords.length,
     behaviorCount,
     cache: { pageRenders, pageSources, placeholders, sourceResults: sourceResultsByFile }

package/framework/compiler/explanation-report.mjs

@@ -0,0 +1,137 @@
+import { createHash } from "node:crypto"
+import { readFile } from "node:fs/promises"
+import { join } from "node:path"
+import { gzipSync } from "node:zlib"
+
+const limits = Object.freeze({ sources: 100, normalization: 100, owners: 100, effects: 100, artifacts: 100 })
+
+export async function createExplanationReport({ route, record, artifact, entrySource, sourceFiles, sourceResults, compatibility, outputDirectory, base }) {
+  const sources = [...sourceFiles].sort(compareText)
+  const sourceSet = new Set(sources)
+  const results = sourceResults.filter(result => sourceSet.has(result.file))
+  const normalization = compatibility.sites.filter(site => sourceSet.has(site.file)).map(site => ({ ...site, provenance: "reachable-source" }))
+  const owners = results.flatMap(result => [
+    ...result.componentAnalysis.owners.map(owner => ownerFact(result.file, "component", owner)),
+    ...result.componentAnalysis.specializations.map(owner => ownerFact(result.file, "specialization", owner)),
+  ]).sort((left, right) => compareText(left.module, right.module) || compareText(left.kind, right.kind) || left.slot - right.slot)
+  const effects = effectFacts(record, results, sources)
+  const artifacts = await artifactFacts(artifact, outputDirectory, base)
+  const eager = artifacts.filter(entry => !entry.reasons.includes("lazy-handler-chunk") && !entry.external)
+  const lazy = artifacts.filter(entry => entry.reasons.includes("lazy-handler-chunk") && !entry.external)
+  const javascript = artifacts.filter(entry => entry.path.endsWith(".js") && !entry.external)
+  const zeroJavaScript = artifact.runtime.family === null && javascript.length === 0
+  const sections = { sources, normalization, owners, effects, artifacts }
+  return {
+    version: 1,
+    status: "ready",
+    route,
+    entrySource,
+    runtimeRoute: Boolean(record.runtimeSchema),
+    capability: { signature: artifact.capability.signature, family: artifact.runtime.family, facts: enabledFacts(artifact.capability.manifest) },
+    ...Object.fromEntries(Object.entries(sections).map(([name, entries]) => [name, entries.slice(0, limits[name])])),
+    bytes: {
+      eagerRawBytes: sum(eager, "rawBytes"),
+      eagerGzipBytes: sum(eager, "gzipBytes"),
+      lazyRawBytes: sum(lazy, "rawBytes"),
+      lazyGzipBytes: sum(lazy, "gzipBytes"),
+      javascriptRawBytes: sum(javascript, "rawBytes"),
+      javascriptGzipBytes: sum(javascript, "gzipBytes"),
+    },
+    zeroJavaScript: {
+      value: zeroJavaScript,
+      scope: "compiler-selected-capability-artifacts",
+      reasons: zeroJavaScript
+        ? ["no behavior runtime family", "no runtime or handler entry", "no Worker graph"]
+        : ["route selects one or more browser capability artifacts"],
+    },
+    limits,
+    summary: Object.fromEntries(Object.entries(sections).map(([name, entries]) => [name, entries.length])),
+    omitted: Object.fromEntries(Object.entries(sections).map(([name, entries]) => [name, Math.max(0, entries.length - limits[name])])),
+  }
+}
+
+function effectFacts(record, results, sources) {
+  const facts = []
+  for (const reference of record.artifacts.effects) {
+    const result = results.find(entry => entry.handlerModule && reference.module.endsWith(`/assets/${entry.handlerModule.path}`))
+    if (!result) continue
+    const handler = result.moduleIR.handlers.find(entry => entry.exportName === reference.handler)
+    const effect = result.moduleIR.effects.find(entry => entry.setup?.handler === handler?.slot)
+    if (!handler || !effect) continue
+    const owner = effect.ownership?.owner
+    const descriptor = owner?.kind === "component" ? result.componentAnalysis.owners[owner.slot] : owner?.kind === "specialization" ? result.componentAnalysis.specializations[owner.slot] : undefined
+    facts.push({
+      module: result.file,
+      handler: reference.handler,
+      ...(handler.source ? { source: handler.source } : {}),
+      owner: descriptor?.name ?? descriptor?.component?.name ?? owner?.kind ?? "module",
+      cleanup: Boolean(effect.cleanup),
+      dependencies: effect.dependencies?.length ?? 0,
+      workers: effect.workers.map(worker => {
+        const matches = sources.filter(file => file === worker.root || file.endsWith(`/${worker.root}`))
+        return matches.length === 1 ? matches[0] : worker.root
+      }).sort(compareText),
+    })
+  }
+  return facts.sort((left, right) => compareText(left.module, right.module) || compareText(left.handler, right.handler))
+}
+
+async function artifactFacts(route, outputDirectory, base) {
+  const edges = [
+    ...route.runtime.entries.map(path => [path, "runtime-entry"]),
+    ...route.runtime.requirements.map(path => [path, "runtime-requirement"]),
+    ...route.handlers.entries.map(path => [path, "handler-entry"]),
+    ...route.handlers.chunks.map(path => [path, "handler-chunk"]),
+    ...route.handlers.lazyChunks.map(path => [path, "lazy-handler-chunk"]),
+    ...route.workers.flatMap(worker => [[worker.entry, `worker:${worker.source}`], ...worker.chunks.map(path => [path, `worker-chunk:${worker.source}`])]),
+    ...route.styles.map(path => [path, "style"]),
+  ]
+  const selected = new Map()
+  for (const [url, reason] of edges) {
+    const reasons = selected.get(url) ?? new Set()
+    reasons.add(reason)
+    selected.set(url, reasons)
+  }
+  return Promise.all([...selected].sort(([left], [right]) => compareText(left, right)).map(async ([url, reasons]) => {
+    if (/^https?:\/\//.test(url)) return { path: url, reasons: [...reasons].sort(compareText), external: true }
+    const pathname = new URL(url, "https://kudzu.invalid").pathname
+    const deployed = base && pathname.startsWith(`${base}/`) ? pathname.slice(base.length + 1) : pathname.slice(1)
+    const contents = await readFile(join(outputDirectory, deployed))
+    return {
+      path: deployed,
+      reasons: [...reasons].sort(compareText),
+      rawBytes: contents.byteLength,
+      gzipBytes: gzipSync(contents).byteLength,
+      sha256: createHash("sha256").update(contents).digest("hex"),
+    }
+  }))
+}
+
+function ownerFact(module, kind, owner) {
+  return {
+    module,
+    kind,
+    slot: owner.slot,
+    name: owner.name ?? owner.component?.name ?? "anonymous",
+    states: owner.states?.length ?? 0,
+    refs: owner.refs?.length ?? 0,
+    ids: owner.ids?.length ?? 0,
+    provenance: "reachable-source",
+  }
+}
+
+function enabledFacts(value, prefix = "") {
+  const facts = []
+  for (const [key, entry] of Object.entries(value ?? {}).sort(([left], [right]) => compareText(left, right))) {
+    if (key === "version") continue
+    const path = prefix ? `${prefix}.${key}` : key
+    if (entry === true) facts.push(path)
+    else if (typeof entry === "number" && entry > 0) facts.push(`${path}=${entry}`)
+    else if (Array.isArray(entry)) for (const item of entry) facts.push(`${path}=${item}`)
+    else if (entry && typeof entry === "object") facts.push(...enabledFacts(entry, path))
+  }
+  return facts
+}
+
+const sum = (entries, field) => entries.reduce((total, entry) => total + entry[field], 0)
+const compareText = (left, right) => left < right ? -1 : left > right ? 1 : 0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kudzujs/core",
-  "version": "0.16.12",
+  "version": "0.16.13",
   "description": "HTML-first TSX framework with synchronous state semantics and no virtual DOM",
   "type": "module",
   "license": "MIT",