@kudzujs/core 0.16.8 → 0.16.9

package/MIGRATION_ROADMAP.md

@@ -51,7 +51,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.19.0` 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.19.1` 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,16 @@
 
 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.9 Compatibility Boundary And Inventory
+
+Measured 2026-08-31 on Linux x64 with Node 24.14.0 and required Chrome. The
+compatibility inventory is compiler scratch generated from reachable original
+source before normalization; it emits no deploy file or browser capability.
+Existing project-output baselines and package-specific diagnostics pass without
+change. 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 532.6 ms
+median on this loaded host; timing is not compared.
+
 ## 0.16.8 Shared Lazy Capability Graph
 
 Measured 2026-08-31 on Linux x64 with Node 24.14.0 and Chrome. Two route owners

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.8 - Shared lazy capability graphs.** Multiple route owners now share one interaction-triggered CodeMirror graph, with lexical ownership validation and no loader, cache, or eager prefetch. Read the [release notes](./RELEASES.md#0168---shared-lazy-capability-graphs), open the [release page](https://github.com/kudzujs/kudzu/releases/tag/v0.16.8), or follow the [architecture packet](./docs/next-architecture/README.md).
+**Latest release: 0.16.9 - Compatibility boundary and inventory.** Reachable authored package sites now receive deterministic compatibility classes and source ranges in a compiler-only report without entering semantic IR or browser output. Read the [release notes](./RELEASES.md#0169---compatibility-boundary-and-inventory), open the [release page](https://github.com/kudzujs/kudzu/releases/tag/v0.16.9), 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,33 @@
 # Kudzu Releases
 
+## 0.16.9 - Compatibility Boundary And Inventory
+
+Kudzu 0.16.9 records deterministic package compatibility provenance from the
+reachable authored source graph without changing semantic IR or browser output.
+
+### Changed in 0.16.9
+
+- Centralizes package identities and compatibility classifications used by
+  React, React Router, React Bootstrap, Zustand, `clsx`, and browser-signal
+  normalization.
+- Writes `.kudzu/kudzu-compatibility.json` from original, pre-normalization
+  source with package/API identity and exact line/column ranges.
+- Classifies sites as Native, Compiled, Normalized, Adapter, Owned External UI,
+  Partial, or Unsupported with stable rule names and deterministic ordering.
+- Includes only modules reachable from page entries; unused migration source is
+  excluded from the report just as it is from compilation.
+- Keeps package origin out of ComponentAnalysis, ModuleIR, RouteIR, codegen,
+  runtime modules, and deploy output. No plugin API or browser capability is
+  added.
+- Updates `create-kudzu@0.1.134` to generate projects on
+  `@kudzujs/core@^0.16.9`.
+
+### Upgrade
+
+```sh
+npm install @kudzujs/core@^0.16.9
+```
+
 ## 0.16.8 - Shared Lazy Capability Graphs
 
 Kudzu 0.16.8 shares one deferred package graph across route owners while

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.19.0`. 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.19.1`. 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

@@ -1615,6 +1615,34 @@ comparison. This packet ships as the actual `0.16.8` patch to retain the public
 - **Done condition:** existing React Router, Bootstrap, Zustand, and browser
   normalizations preserve output and diagnostics.
 
+Implementation and release-candidate evidence complete. One internal registry
+now owns package identities and classifies original reachable import, re-export,
+and literal dynamic-import sites before normalization. The deterministic
+`.kudzu/kudzu-compatibility.json` report records package/API identity, stable
+rule, Native, Compiled, Normalized, Adapter, Owned External UI, Partial, or
+Unsupported treatment, and exact authored line/column range. Type-only,
+relative, Node, Kudzu-first-party, and unreachable source stays outside the
+inventory.
+
+React Router, React Bootstrap, Zustand, React migration, browser-signal, `clsx`,
+and i18next recognition reuse the registry's package identities. Focused tests
+cover all seven classes, aliases, exact ranges, deterministic ordering, and a
+real build where an unreachable unsupported module is excluded. Existing
+project output baselines and package diagnostics remain green. Package origin
+does not enter SourceResult, ComponentAnalysis, ModuleIR, RouteIR, codegen,
+runtime files, `afterBuild()`, or deploy output.
+
+The slice adds zero semantic primitives, IR kinds, compiler passes,
+normalization entries, runtime concepts/files, browser bytes, or public APIs.
+Production compiler/orchestration changes are 161 added and 13 removed lines,
+including the 141-line registry, for +148 net compatibility/build lines and zero
+core semantic LOC. `npm run check`, 290 required-Chrome tests, package smoke,
+and the maintained benchmark pass. Worker and window graphs remain 907 raw /
+477 gzip and 14,456 raw / 6,160 gzip bytes; seven clean Linux x64 builds record
+a 532.6 ms median without a timing comparison. This packet ships as the actual
+`0.16.9` patch, with `create-kudzu@0.1.134`, to retain the public
+`0.16.x` line.
+
 ### `0.19.1`: Apache Answer Authentication Journey
 
 - **Purpose:** promote the existing build-only auth fixture to browser evidence.
@@ -1900,3 +1928,4 @@ release transaction where possible or document and publish a forward-fix patch.
 | `0.18.1` | Released as `0.16.6` | Preserve one guarded literal package edge, native module-map deduplication, exact owner cleanup, deferred artifact ownership, and static exclusion. | Patch release retained the `0.16.x` public version line |
 | `0.18.2` | Released as `0.16.7` | Preserve on-demand retained editor mount, bidirectional updates, failure recovery, identity, exact cleanup, cached fresh remount, and static exclusion. | Patch release retained the `0.16.x` public version line |
 | `0.18.3` | Released as `0.16.8` | Preserve shared deferred ownership, interaction-only loading, native document module-map deduplication, exact owner cleanup, binding-aware import validation, and static exclusion. | Patch release retained the `0.16.x` public version line |
+| `0.19.0` | Released as `0.16.9` | Preserve the compatibility registry, reachable source inventory, exact ranges, and package-neutral output boundary. | Patch release retained the `0.16.x` public version line |

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

@@ -1,6 +1,6 @@
 # Current Compiler Architecture
 
-This maps the current `0.16.8` 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.19.0`; 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.9` 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.19.1`; file and function names are the stable references, while line numbers are intentionally omitted because later work may still move code.
 
 ## Responsibility Map
 
@@ -11,6 +11,7 @@ This maps the current `0.16.8` architecture, built on the completed `0.9.0` sema
 | 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. |
 | Reachability/import resolution | [`framework/compiler/source-compiler.mjs`](../../framework/compiler/source-compiler.mjs), `reachableSourceFiles()`; [`framework/compiler/source-graph.mjs`](../../framework/compiler/source-graph.mjs), `ordinaryRuntimeDependencies()`, `resolveSourceImport()` | Starts from page entries, follows relative runtime imports/re-exports and validated Worker references, excludes unreachable migration source, and fails unresolved ordinary edges or dynamic imports at the importer source location before code generation. A lazy package edge must resolve lexically to a named React or Kudzu `useEffect` import. |
+| Compatibility inventory | [`framework/compiler/compatibility-registry.mjs`](../../framework/compiler/compatibility-registry.mjs), `createCompatibilityReport()` | Classifies package/API sites in reachable original source as Native, Compiled, Normalized, Adapter, Owned External UI, Partial, or Unsupported and writes deterministic source ranges to `.kudzu/kudzu-compatibility.json`. Package provenance ends here and never enters semantic IR or browser output. |
 | Ordered normalization | [`framework/compiler/normalization-pipeline.mjs`](../../framework/compiler/normalization-pipeline.mjs), `applyNormalizationPasses()`; [`framework/compiler/source-compiler.mjs`](../../framework/compiler/source-compiler.mjs), `normalizeCompilerSource()` | Applies migration/resource passes in order and repairs TypeScript parent pointers after every structural change. Imported source uses the same pipeline. |
 | Focused normalization passes | [`framework/compiler/`](../../framework/compiler/) | React, Router, browser signals, animation-frame refs, custom-hook timers, Zustand, and render control each validate and lower a narrow source shape. |
 | Shared AST/scope helpers | [`framework/compiler/ast-helpers.mjs`](../../framework/compiler/ast-helpers.mjs) | Binding, scope, reference, inclusive ancestry, effect-return, and source-location analysis. |
@@ -43,6 +44,7 @@ This maps the current `0.16.8` architecture, built on the completed `0.9.0` sema
 src/pages entries + config
   -> ProjectSession(root) with project paths, source records, parsed/symbol caches, graph, and Worker compiler
   -> project discovery and reachable relative graph
+       -> classify original package sites into the scratch compatibility report
        -> in development, intersect changed paths with current and prior per-page graphs
        -> reuse unaffected SourceResult and pre-family route render records
   -> compileSource()

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.19.0`. 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.19.1`. 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.19.0`; 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.19.1`; 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.19.0` Compatibility Boundary And Inventory 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.19.1` Apache Answer Authentication Journey 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.19.0`; 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.19.1`; 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.133` retains the explicit install instructions and generates projects with `@kudzujs/core@^0.16.8`.
+`create-kudzu@0.1.134` retains the explicit install instructions and generates projects with `@kudzujs/core@^0.16.9`.
 
 ## Release Boundary
 

package/framework/README.md

@@ -78,7 +78,7 @@ Reduced Zustand migration stores lower through package-neutral `SharedStateIR` a
 
 Compiler ownership follows explicit stages. `build.mjs` coordinates project discovery, source compilation, RouteIR rendering, RouteBuildRecord collection, CapabilityIR planning, generator calls, and artifact emission. `compiler/normalization-pipeline.mjs` owns pass order and parent repair. The main transformer analyzes normalized source while `compiler/descriptor-session.mjs` owns one per-source semantic artifact containing HandlerIR, BindingIR, DerivedIR, KeyedBlockIR, EffectIR, and client imports. `core.mjs` emits complete HTML, RouteIR v1, and exact handler references: route-local state `slot` is an internal array reference, `id` remains the browser/DOM identity, and `name` remains readable development metadata. `compiler/route-build-record.mjs` validates structural artifact edges, and `compiler/route-capability-planner.mjs` projects CapabilityIR v1 from those records. Focused codegen modules consume IR/descriptors and return route-specific source without source analysis or filesystem ownership. The completed architecture record lives in `docs/next-architecture`; it adds no runtime or accepted syntax by itself.
 
-`.kudzu/kudzu-artifacts.json` records each route's exact CapabilityIR signature, assigned emitted runtime family, handler, Worker, stylesheet, and transitive chunk edges. Equal standalone signatures reuse `dist/assets/runtime/<family>/`; every enhanced-navigation group intentionally shares one union family. The same JSON-safe contract is available to `afterBuild()` as `artifacts`.
+`.kudzu/kudzu-artifacts.json` records each route's exact CapabilityIR signature, assigned emitted runtime family, handler, Worker, stylesheet, and transitive chunk edges. Equal standalone signatures reuse `dist/assets/runtime/<family>/`; every enhanced-navigation group intentionally shares one union family. The same JSON-safe contract is available to `afterBuild()` as `artifacts`. `.kudzu/kudzu-compatibility.json` separately inventories reachable authored package sites before normalization with deterministic compatibility classes and source ranges; that provenance does not enter semantic IR, codegen, runtime files, or deploy output.
 
 New syntax support belongs in an existing pass or a focused new pass only when a reduced migration fixture proves it. Passes must preserve source-located diagnostics, avoid module-global analysis state, and expose metadata through return values rather than AST-identity side channels. Build orchestration stays in `build.mjs`; feature-specific graph validation or code generation moves under `compiler/` when it has a stable input/output boundary.
 

package/framework/build.mjs

@@ -4,6 +4,7 @@ import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path"
 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 { generateListRuntime } from "./compiler/list-runtime-codegen.mjs"
 import { assetPath, browserPath, relativeModulePath, withBase } from "./compiler/path-helpers.mjs"
 import { createProjectSession } from "./compiler/project-session.mjs"
@@ -103,6 +104,7 @@ async function buildInto(project, outputDirectory, { changedFiles, minify, quiet
   if (!pageFiles.length) throw new Error("No pages found in src/pages/")
   const pageSources = new Map(pageFiles.map(file => [file, new Set(reachableSourceFiles([file], allSourceFileSet, sourceIndex))]))
   const sourceFiles = [...new Set([...pageSources.values()].flatMap(files => [...files]))].sort()
+  await writePrettyJson(join(workDirectory, "kudzu-compatibility.json"), createCompatibilityReport(sourceFiles.map(file => ({ file: relative(root, file).replaceAll(sep, "/"), source: sourceIndex.get(file) }))))
   const sourceFileSet = project.sourceFiles
   sourceFileSet.clear()
   for (const file of sourceFiles) sourceFileSet.add(file)

package/framework/compiler/browser-signal-passes.mjs

@@ -1,8 +1,9 @@
 import ts from "typescript"
 import { bindingNames, containsJsx, functionVarDeclaresName, importDeclarationNames, isNodeWithin, isShadowedIdentifier, isUnshadowedGlobal, nearestFunction, referenceIdentifiers, sourceNodeError, statementDeclaresName, unwrapExpression } from "./ast-helpers.mjs"
+import { compatibilityPackages } from "./compatibility-registry.mjs"
 
 export function normalizeMediaQueryExternalStores(sourceFile, factory, context) {
-    const imports = sourceFile.statements.filter(statement => ts.isImportDeclaration(statement) && !statement.importClause?.isTypeOnly && ts.isStringLiteral(statement.moduleSpecifier) && statement.moduleSpecifier.text === "react" && statement.importClause?.namedBindings && ts.isNamedImports(statement.importClause.namedBindings))
+    const imports = sourceFile.statements.filter(statement => ts.isImportDeclaration(statement) && !statement.importClause?.isTypeOnly && ts.isStringLiteral(statement.moduleSpecifier) && statement.moduleSpecifier.text === compatibilityPackages.react && statement.importClause?.namedBindings && ts.isNamedImports(statement.importClause.namedBindings))
     const externalStoreImport = imports.flatMap(statement => statement.importClause.namedBindings.elements.map(entry => ({ entry, statement }))).find(({ entry }) => !entry.isTypeOnly && !entry.propertyName && entry.name.text === "useSyncExternalStore")
     if (!externalStoreImport) return sourceFile
     const returnedExpression = callback => {

package/framework/compiler/compatibility-registry.mjs

@@ -0,0 +1,141 @@
+import ts from "typescript"
+
+export const compatibilityClasses = Object.freeze([
+  "Native",
+  "Compiled",
+  "Normalized",
+  "Adapter",
+  "Owned External UI",
+  "Partial",
+  "Unsupported"
+])
+
+export const compatibilityPackages = Object.freeze({
+  clsx: "clsx",
+  react: "react",
+  reactBootstrap: "react-bootstrap",
+  reactI18next: "react-i18next",
+  reactRouter: "react-router-dom",
+  zustand: "zustand"
+})
+
+const compiledReact = new Set(["default", "*", "Fragment", "createContext", "useContext", "useEffect", "useId", "useReducer", "useRef", "useState"])
+const normalizedReact = new Set(["createRef", "forwardRef", "memo", "useCallback", "useMemo", "useSyncExternalStore"])
+const normalizedRouter = new Set(["useMatch", "useParams", "useSearchParams"])
+const ownedExternalUi = new Set(["@codemirror/view", "chart.js", "gsap", "sortablejs", "typed.js"])
+
+export function createCompatibilityReport(sources) {
+  const sites = sources.flatMap(({ file, source }) => compatibilitySites(file, source)).sort(compareSites)
+  const counts = Object.fromEntries(compatibilityClasses.map(name => [name, 0]))
+  const packages = new Map()
+  for (const site of sites) {
+    counts[site.classification]++
+    const key = `${site.package}\0${site.classification}`
+    packages.set(key, { package: site.package, classification: site.classification, sites: (packages.get(key)?.sites ?? 0) + 1 })
+  }
+  return {
+    version: 1,
+    summary: counts,
+    packages: [...packages.values()].sort((left, right) => compareText(left.package, right.package) || compareText(left.classification, right.classification)),
+    sites
+  }
+}
+
+function compatibilitySites(file, source) {
+  const sourceFile = ts.createSourceFile(file, source, ts.ScriptTarget.Latest, true, file.endsWith(".tsx") ? ts.ScriptKind.TSX : ts.ScriptKind.TS)
+  const sites = []
+  const add = (target, imported, local, kind, node) => {
+    if (!isBarePackage(target) || target === "@kudzujs/core" || target.startsWith("@kudzujs/core/")) return
+    const rule = classify(target, imported, kind)
+    const start = sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile))
+    const end = sourceFile.getLineAndCharacterOfPosition(node.getEnd())
+    sites.push({
+      package: target,
+      imported,
+      ...(local && local !== imported ? { local } : {}),
+      kind,
+      classification: rule.classification,
+      rule: rule.id,
+      file,
+      location: { line: start.line + 1, column: start.character + 1, endLine: end.line + 1, endColumn: end.character + 1 }
+    })
+  }
+  const visit = node => {
+    if (ts.isImportDeclaration(node) && ts.isStringLiteral(node.moduleSpecifier)) {
+      const target = node.moduleSpecifier.text
+      const clause = node.importClause
+      if (!clause?.isTypeOnly) {
+        if (!clause) add(target, null, null, "side-effect-import", node.moduleSpecifier)
+        if (clause?.name) add(target, "default", clause.name.text, "import", clause.name)
+        const bindings = clause?.namedBindings
+        if (bindings && ts.isNamespaceImport(bindings)) add(target, "*", bindings.name.text, "import", bindings.name)
+        if (bindings && ts.isNamedImports(bindings)) for (const entry of bindings.elements) {
+          if (!entry.isTypeOnly) add(target, (entry.propertyName ?? entry.name).text, entry.name.text, "import", entry)
+        }
+      }
+      return
+    }
+    if (ts.isExportDeclaration(node) && node.moduleSpecifier && ts.isStringLiteral(node.moduleSpecifier)) {
+      const target = node.moduleSpecifier.text
+      const clause = node.exportClause
+      if (!node.isTypeOnly) {
+        if (!clause || ts.isNamespaceExport(clause)) add(target, "*", null, "re-export", clause ?? node.moduleSpecifier)
+        else for (const entry of clause.elements) if (!entry.isTypeOnly) add(target, (entry.propertyName ?? entry.name).text, entry.name.text, "re-export", entry)
+      }
+      return
+    }
+    if (ts.isCallExpression(node) && node.expression.kind === ts.SyntaxKind.ImportKeyword && node.arguments.length === 1 && ts.isStringLiteral(node.arguments[0])) {
+      add(node.arguments[0].text, "*", null, "dynamic-import", node.arguments[0])
+      return
+    }
+    ts.forEachChild(node, visit)
+  }
+  visit(sourceFile)
+  return sites
+}
+
+function classify(target, imported, kind) {
+  if (kind === "re-export") return { id: "package.re-export.unsupported", classification: "Unsupported" }
+  if (kind === "side-effect-import") return { id: "package.side-effect.unsupported", classification: "Unsupported" }
+  const root = packageRoot(target)
+  if (kind === "dynamic-import") return { id: "package.dynamic.partial", classification: "Partial" }
+  if (target === compatibilityPackages.react) {
+    if (compiledReact.has(imported)) return { id: "react.compiled", classification: "Compiled" }
+    if (normalizedReact.has(imported)) return { id: "react.normalized", classification: "Normalized" }
+    return { id: "react.partial", classification: "Partial" }
+  }
+  if (target === compatibilityPackages.reactRouter) {
+    if (imported === "Link" || imported === "useNavigate") return { id: "react-router-dom.native", classification: "Native" }
+    if (normalizedRouter.has(imported)) return { id: "react-router-dom.normalized", classification: "Normalized" }
+    return { id: "react-router-dom.partial", classification: "Partial" }
+  }
+  if (target === compatibilityPackages.reactBootstrap) return ["Row", "Col"].includes(imported)
+    ? { id: "react-bootstrap.normalized", classification: "Normalized" }
+    : { id: "react-bootstrap.partial", classification: "Partial" }
+  if (target === compatibilityPackages.zustand) return imported === "create"
+    ? { id: "zustand.adapter", classification: "Adapter" }
+    : { id: "zustand.partial", classification: "Partial" }
+  if (target === compatibilityPackages.clsx) return ["default", "clsx"].includes(imported)
+    ? { id: "clsx.normalized", classification: "Normalized" }
+    : { id: "clsx.partial", classification: "Partial" }
+  if (target === compatibilityPackages.reactI18next) return { id: "react-i18next.unsupported", classification: "Unsupported" }
+  if (ownedExternalUi.has(root)) return { id: "owned-external-ui", classification: "Owned External UI" }
+  return { id: "package.contextual", classification: "Partial" }
+}
+
+function packageRoot(target) {
+  const parts = target.split("/")
+  return target.startsWith("@") ? parts.slice(0, 2).join("/") : parts[0]
+}
+
+function isBarePackage(target) {
+  return !target.startsWith(".") && !target.startsWith("/") && !target.startsWith("node:") && !/^[a-z][a-z+.-]*:/i.test(target)
+}
+
+function compareSites(left, right) {
+  return compareText(left.file, right.file) || left.location.line - right.location.line || left.location.column - right.location.column || compareText(left.package, right.package) || compareText(String(left.imported), String(right.imported))
+}
+
+function compareText(left, right) {
+  return left < right ? -1 : left > right ? 1 : 0
+}

package/framework/compiler/react-migration-pass.mjs

@@ -1,12 +1,13 @@
 import ts from "typescript"
 import { bindingNames, importDeclarationNames, isFunctionLike, isLocalConst, isReferenceIdentifier, isShadowedByParameter, isShadowedIdentifier, loopDeclaresName, nearestFunction, nearestFunctionLike, referenceIdentifiers, sourceNodeError, statementDeclaresName, unwrapExpression } from "./ast-helpers.mjs"
 import { analyzeCollectionPipeline, isArrayFromCall } from "./collection-analysis.mjs"
+import { compatibilityPackages } from "./compatibility-registry.mjs"
 
 export function createReactMigrationPass({ cloneAst, jsxTagName }) {
   function normalizeReactBootstrapLayout(sourceFile, factory, context) {
     const layouts = new Map()
     for (const statement of sourceFile.statements) {
-      if (!ts.isImportDeclaration(statement) || statement.importClause?.isTypeOnly || !ts.isStringLiteral(statement.moduleSpecifier) || statement.moduleSpecifier.text !== "react-bootstrap") continue
+      if (!ts.isImportDeclaration(statement) || statement.importClause?.isTypeOnly || !ts.isStringLiteral(statement.moduleSpecifier) || statement.moduleSpecifier.text !== compatibilityPackages.reactBootstrap) continue
       const clause = statement.importClause
       if (!clause || clause.name || !clause.namedBindings || ts.isNamespaceImport(clause.namedBindings)) throw sourceNodeError(statement, sourceFile, "React Bootstrap layout migration requires named Row or Col imports")
       for (const entry of clause.namedBindings.elements) {
@@ -52,7 +53,7 @@ export function createReactMigrationPass({ cloneAst, jsxTagName }) {
       }
       if (ts.isJsxSelfClosingElement(node) && layout(node.tagName)) return factory.updateJsxSelfClosingElement(node, factory.createIdentifier("div"), node.typeArguments, attributes(node.attributes))
       if (ts.isIdentifier(node) && layouts.has(node.text) && isReferenceIdentifier(node) && !isShadowedIdentifier(node, sourceFile)) throw sourceNodeError(node, sourceFile, "React Bootstrap Row and Col imports may only be used as direct JSX elements")
-      if (ts.isImportDeclaration(node) && !node.importClause?.isTypeOnly && ts.isStringLiteral(node.moduleSpecifier) && node.moduleSpecifier.text === "react-bootstrap") {
+      if (ts.isImportDeclaration(node) && !node.importClause?.isTypeOnly && ts.isStringLiteral(node.moduleSpecifier) && node.moduleSpecifier.text === compatibilityPackages.reactBootstrap) {
         const clause = node.importClause
         const bindings = clause?.namedBindings
         if (!clause || !bindings || !ts.isNamedImports(bindings)) return node
@@ -71,7 +72,7 @@ export function createReactMigrationPass({ cloneAst, jsxTagName }) {
     const aliases = new Map()
     const reactObjects = new Set()
     for (const statement of sourceFile.statements) {
-      if (!ts.isImportDeclaration(statement) || statement.importClause?.isTypeOnly || !ts.isStringLiteral(statement.moduleSpecifier) || statement.moduleSpecifier.text !== "react") continue
+      if (!ts.isImportDeclaration(statement) || statement.importClause?.isTypeOnly || !ts.isStringLiteral(statement.moduleSpecifier) || statement.moduleSpecifier.text !== compatibilityPackages.react) continue
       if (statement.importClause?.name) reactObjects.add(statement.importClause.name.text)
       const bindings = statement.importClause?.namedBindings
       if (bindings && ts.isNamespaceImport(bindings)) reactObjects.add(bindings.name.text)
@@ -257,7 +258,7 @@ export function createReactMigrationPass({ cloneAst, jsxTagName }) {
     const missing = [...required].filter(name => !imported.has(name)).sort()
     if (!missing.length) return normalizeReactBootstrapLayout(normalized, factory, context)
     for (const name of missing) {
-      const collision = sourceFile.statements.some(statement => statementDeclaresName(statement, name) || ts.isImportDeclaration(statement) && importDeclarationNames(statement).includes(name) && statement.moduleSpecifier.text !== "react")
+      const collision = sourceFile.statements.some(statement => statementDeclaresName(statement, name) || ts.isImportDeclaration(statement) && importDeclarationNames(statement).includes(name) && statement.moduleSpecifier.text !== compatibilityPackages.react)
       if (collision) throw sourceNodeError(sourceFile, sourceFile, `React.${name} cannot be normalized because ${JSON.stringify(name)} is already declared`)
     }
     const declaration = factory.createImportDeclaration(undefined, factory.createImportClause(false, undefined, factory.createNamedImports(missing.map(name => factory.createImportSpecifier(false, undefined, factory.createIdentifier(name))))), factory.createStringLiteral("react"))

package/framework/compiler/router-pass.mjs

@@ -1,5 +1,6 @@
 import ts from "typescript"
 import { bindingNames, functionVarDeclaresName, isFunctionLike, isLocalConst, isReferenceIdentifier, isShadowedIdentifier, loopDeclaresName, nearestFunction, sourceNodeError, statementDeclaresName, unwrapExpression } from "./ast-helpers.mjs"
+import { compatibilityPackages } from "./compatibility-registry.mjs"
 
 export function createRouterPass({ withBase }) {
   return function normalizeReactRouterSyntax(sourceFile, factory, context, base, importedCollections = new Map()) {
@@ -9,7 +10,7 @@ export function createRouterPass({ withBase }) {
     const searchHooks = new Set()
     const navigateHooks = new Set()
     for (const statement of sourceFile.statements) {
-      if ((ts.isExportDeclaration(statement) || ts.isImportDeclaration(statement)) && statement.moduleSpecifier && ts.isStringLiteral(statement.moduleSpecifier) && statement.moduleSpecifier.text === "react-router-dom") {
+      if ((ts.isExportDeclaration(statement) || ts.isImportDeclaration(statement)) && statement.moduleSpecifier && ts.isStringLiteral(statement.moduleSpecifier) && statement.moduleSpecifier.text === compatibilityPackages.reactRouter) {
         if (ts.isExportDeclaration(statement)) throw sourceNodeError(statement, sourceFile, "React Router exports are not supported; import Link directly where it renders")
         const clause = statement.importClause
         if (clause?.isTypeOnly) continue
@@ -306,7 +307,7 @@ export function createRouterPass({ withBase }) {
       if (ts.isIdentifier(node) && matchHooks.has(node.text) && isReferenceIdentifier(node) && !isShadowedIdentifier(node, sourceFile)) throw sourceNodeError(node, sourceFile, "React Router useMatch imports may only initialize the supported top-level const binding")
       if (ts.isIdentifier(node) && searchHooks.has(node.text) && isReferenceIdentifier(node) && !isShadowedIdentifier(node, sourceFile)) throw sourceNodeError(node, sourceFile, "React Router useSearchParams imports may only initialize the supported top-level tuple binding")
       if (ts.isIdentifier(node) && navigateHooks.has(node.text) && isReferenceIdentifier(node) && !isShadowedIdentifier(node, sourceFile)) throw sourceNodeError(node, sourceFile, "React Router useNavigate imports may only initialize the supported top-level navigate binding")
-      if (ts.isImportDeclaration(node) && ts.isStringLiteral(node.moduleSpecifier) && node.moduleSpecifier.text === "react-router-dom") {
+      if (ts.isImportDeclaration(node) && ts.isStringLiteral(node.moduleSpecifier) && node.moduleSpecifier.text === compatibilityPackages.reactRouter) {
         const clause = node.importClause
         if (!clause || clause.isTypeOnly) return node
         const bindings = clause.namedBindings

package/framework/compiler/source-compiler.mjs

@@ -8,6 +8,7 @@ import { normalizeEffectPrivateRefs } from "./effect-private-ref-pass.mjs"
 import { bindingNames, containsJsx, effectReturns, functionVarDeclaresName, importDeclarationNames, isFunctionLike, isLocalConst, isReferenceIdentifier, isShadowedByParameter, isShadowedIdentifier, isUnshadowedGlobal, nearestFunction, referenceIdentifiers, referencesIdentifier, sourceLocation, sourceNodeError, statementDeclaresName, unwrapExpression } from "./ast-helpers.mjs"
 import { normalizeMediaQueryExternalStores, normalizeNavigatorCapabilityConditions } from "./browser-signal-passes.mjs"
 import { analyzeCollectionPipeline, collectionExpression, collectionParameters, isArrayFromCall, mutatingCollectionMethods as mutatingListMethods, pureCollectionMathMethods as pureMathMethods, pureCollectionMethods as pureListMethods } from "./collection-analysis.mjs"
+import { compatibilityPackages } from "./compatibility-registry.mjs"
 import { normalizeCustomHookTimerRefs } from "./custom-hook-timer-pass.mjs"
 import { captureNames, createDescriptorSession, createSemanticArtifact, nativeCaptureNames, referencedReducerDispatches, referencedStateNames } from "./descriptor-session.mjs"
 import { analyzeEffectDependencies, validateEffectOwnedBrowserResources } from "./effect-analysis.mjs"
@@ -170,7 +171,7 @@ function reachableSourceFiles(entries, sourceFiles, sourceIndex) {
 function normalizeClsxSyntax(sourceFile, factory, context) {
   const names = new Set()
   for (const statement of sourceFile.statements) {
-    if (!ts.isImportDeclaration(statement) || statement.importClause?.isTypeOnly || !ts.isStringLiteral(statement.moduleSpecifier) || statement.moduleSpecifier.text !== "clsx") continue
+    if (!ts.isImportDeclaration(statement) || statement.importClause?.isTypeOnly || !ts.isStringLiteral(statement.moduleSpecifier) || statement.moduleSpecifier.text !== compatibilityPackages.clsx) continue
     if (statement.importClause?.name) names.add(statement.importClause.name.text)
     const bindings = statement.importClause?.namedBindings
     if (bindings && ts.isNamedImports(bindings)) for (const entry of bindings.elements) if (!entry.isTypeOnly && (entry.propertyName ?? entry.name).text === "clsx") names.add(entry.name.text)
@@ -197,7 +198,7 @@ function normalizeClsxSyntax(sourceFile, factory, context) {
   const visitor = node => {
     if (ts.isCallExpression(node) && ts.isIdentifier(node.expression) && names.has(node.expression.text) && !isShadowedIdentifier(node.expression, sourceFile)) return combine(node.arguments.map(lower))
     if (ts.isIdentifier(node) && names.has(node.text) && isReferenceIdentifier(node) && !isShadowedIdentifier(node, sourceFile) && !(ts.isCallExpression(node.parent) && node.parent.expression === node)) throw sourceNodeError(node, sourceFile, "clsx imports may only be called directly")
-    if (ts.isImportDeclaration(node) && ts.isStringLiteral(node.moduleSpecifier) && node.moduleSpecifier.text === "clsx") {
+    if (ts.isImportDeclaration(node) && ts.isStringLiteral(node.moduleSpecifier) && node.moduleSpecifier.text === compatibilityPackages.clsx) {
       const clause = node.importClause
       if (!clause || clause.isTypeOnly) return node
       let bindings = clause.namedBindings
@@ -403,7 +404,7 @@ function createKudzuTransformer({ semantic, handlerUrl, file, sourceFiles, sourc
     for (const [name, binding] of packageBindings) {
       const references = referenceIdentifiers(sourceFile, name)
       const invalid = references.find(reference => !insideJsxEventHandler(reference, sourceFile) && !insideOwnedEffectCallback(reference, sourceFile))
-      if (invalid && binding.target === "react-i18next" && binding.imported === "useTranslation") throw sourceNodeError(invalid, sourceFile, "React i18next useTranslation() depends on runtime locale resources; migrate build-known locales through getStaticPaths() and props, or browser-only locale reads through an owned effect")
+      if (invalid && binding.target === compatibilityPackages.reactI18next && binding.imported === "useTranslation") throw sourceNodeError(invalid, sourceFile, "React i18next useTranslation() depends on runtime locale resources; migrate build-known locales through getStaticPaths() and props, or browser-only locale reads through an owned effect")
       if (invalid) throw sourceNodeError(invalid, sourceFile, `Package import ${JSON.stringify(name)} may only be referenced directly inside JSX event handlers or owned effect setup/cleanup callbacks`)
     }
     const hasUseEffectImport = sourceFile.statements.some(statement => ts.isImportDeclaration(statement) && ["@kudzujs/core", "react"].includes(statement.moduleSpecifier.text) && statement.importClause?.namedBindings && ts.isNamedImports(statement.importClause.namedBindings) && statement.importClause.namedBindings.elements.some(entry => !entry.propertyName && entry.name.text === "useEffect"))

package/framework/compiler/zustand-pass.mjs

@@ -1,12 +1,13 @@
 import { relative, sep } from "node:path"
 import ts from "typescript"
 import { isReferenceIdentifier, isShadowedIdentifier, nearestFunction, sourceNodeError, unwrapExpression } from "./ast-helpers.mjs"
+import { compatibilityPackages } from "./compatibility-registry.mjs"
 
 export function createZustandPass({ isSerializableStateLiteral, nativeCaptureNames, sourceDirectory }) {
   function analyzeZustandStores(sourceFile) {
     const createNames = new Set()
     for (const statement of sourceFile.statements) {
-      if (!ts.isImportDeclaration(statement) || statement.importClause?.isTypeOnly || !ts.isStringLiteral(statement.moduleSpecifier) || statement.moduleSpecifier.text !== "zustand") continue
+      if (!ts.isImportDeclaration(statement) || statement.importClause?.isTypeOnly || !ts.isStringLiteral(statement.moduleSpecifier) || statement.moduleSpecifier.text !== compatibilityPackages.zustand) continue
       const bindings = statement.importClause?.namedBindings
       if (statement.importClause?.name || !bindings || !ts.isNamedImports(bindings)) throw sourceNodeError(statement, sourceFile, "Zustand migration input requires a named create import")
       for (const entry of bindings.elements) {
@@ -77,7 +78,7 @@ export function createZustandPass({ isSerializableStateLiteral, nativeCaptureNam
   function normalizeZustandMigrationSyntax(sourceFile, factory, context) {
     const stores = analyzeZustandStores(sourceFile)
     if (!stores.size) {
-      const declaration = sourceFile.statements.find(statement => ts.isImportDeclaration(statement) && ts.isStringLiteral(statement.moduleSpecifier) && statement.moduleSpecifier.text === "zustand" && !statement.importClause?.isTypeOnly)
+      const declaration = sourceFile.statements.find(statement => ts.isImportDeclaration(statement) && ts.isStringLiteral(statement.moduleSpecifier) && statement.moduleSpecifier.text === compatibilityPackages.zustand && !statement.importClause?.isTypeOnly)
       if (declaration) throw sourceNodeError(declaration, sourceFile, "Zustand create must directly initialize an exported const store")
       return sourceFile
     }
@@ -92,7 +93,7 @@ export function createZustandPass({ isSerializableStateLiteral, nativeCaptureNam
           factory.createStringLiteral(store.sourceKind)
         ]))
       }
-      if (ts.isImportDeclaration(node) && ts.isStringLiteral(node.moduleSpecifier) && node.moduleSpecifier.text === "zustand") return undefined
+      if (ts.isImportDeclaration(node) && ts.isStringLiteral(node.moduleSpecifier) && node.moduleSpecifier.text === compatibilityPackages.zustand) return undefined
       return ts.visitEachChild(node, visitor, context)
     }
     const normalized = ts.visitNode(sourceFile, visitor)

package/package.json

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