@nextsparkjs/core 0.1.0-beta.189 → 0.1.0-beta.190

package/scripts/build/registry/discovery/icons.mjs

@@ -8,13 +8,28 @@
  * Sources are exactly what resolveIcon can be handed, and all of them are
  * source files (never the database):
  * - entity configs (`icon: Users` — an identifier imported from lucide-react)
- * - a theme's app.config (`customSidebarSections[].icon` — a string)
+ * - any `config/*.config.ts` of a theme or a plugin (`icon: 'Grid'`,
+ *   `iconName: Users` — sidebar sections, dashboard menus, feature and flow
+ *   definitions, all of a theme's or plugin's config surface)
  * - block configs (`icon: 'Grid'` — the block's own icon in the editor)
+ * - a literal name handed to DynamicIcon's `name` prop or to resolveIcon's
+ *   first argument in a theme's or plugin's own component code
  *
  * What a block RENDERS is not here: page content names those icons in the page
  * builder, so they live in the database. Those blocks keep resolving through
  * the lucide namespace — deliberately, see themes' features-grid component.
  *
+ * A name that is not a string literal — a variable, a prop, a template
+ * expression — cannot be resolved while building, so it is left out of the
+ * registry rather than guessed; that is the same limit that makes the
+ * unresolved-reference warning below necessary for config files.
+ *
+ * Every source is read as a syntax tree (core's own TypeScript, #195), not as
+ * raw text: a name that only exists inside a comment or a docblock is not
+ * code the app can run, so it must not reach the registry either. Test files
+ * are skipped for the same reason from the other direction — an icon named
+ * only inside a test is never rendered in production.
+ *
  * @module core/scripts/build/registry/discovery/icons
  */
 
@@ -24,6 +39,7 @@ import { createRequire } from 'module'
 import { join, dirname } from 'path'
 
 import { verbose, log } from '../../../utils/index.mjs'
+import { loadTypeScriptFor } from '../shared/typescript-compiler.mjs'
 
 /**
  * Icons the resolver falls back to when a name doesn't resolve. They are
@@ -32,6 +48,15 @@ import { verbose, log } from '../../../utils/index.mjs'
  */
 const FALLBACK_ICONS = ['Box', 'Circle', 'Folder', 'LayoutGrid']
 
+/** A bare identifier-shaped name, the only shape the generated registry can
+ * safely turn into a named import or a lucide-react lookup key. */
+const SAFE_NAME = /^[A-Za-z][\w$-]*$/
+
+/** The property keys a config's icon can be written under — the plain
+ * `icon: X` shape and `iconName: X`, the one a theme's sidebar, dashboard,
+ * feature and flow configs use. */
+const ICON_KEYS = new Set(['icon', 'iconName'])
+
 /**
  * Names lucide-react actually exports, read from its own barrel.
  * A name that isn't there would become a broken named import in the
@@ -63,6 +88,10 @@ async function readLucideExportNames(config) {
 /**
  * Which config files hold icons resolveIcon can be handed. Exported for tests.
  *
+ * Every file directly under a `config/` directory and named `*.config.ts`
+ * counts, not only `app.config.ts`: a theme's dashboard, features and flows
+ * configs name icons by string the same way its app config does.
+ *
  * Separators are normalised first: the generator also runs on Windows, where
  * join() produces '\\' and a '/'-shaped match would silently find nothing —
  * leaving a registry with only its fallbacks, and every entity icon rendering
@@ -73,53 +102,195 @@ export function isIconSourcePath(filePath) {
   return (
     (normalised.includes('/entities/') && normalised.endsWith('.config.ts')) ||
     (normalised.includes('/blocks/') && normalised.endsWith('/config.ts')) ||
-    normalised.endsWith('/config/app.config.ts')
+    /\/config\/[^/]+\.config\.ts$/.test(normalised)
   )
 }
 
+/**
+ * Whether a file is component source a theme or plugin could name an icon
+ * from at runtime — anything DynamicIcon or resolveIcon could be called
+ * from. Exported for tests. Same Windows-separator normalisation as
+ * isIconSourcePath, for the same reason.
+ */
+export function isIconCallSourcePath(filePath) {
+  return /\.tsx?$/.test(filePath.replace(/\\/g, '/'))
+}
+
+/**
+ * Whether a path is test code rather than the app's own source. Exported for
+ * tests. A name that a test hands to resolveIcon or DynamicIcon to exercise a
+ * component is never reached by a real request, so it would only bloat the
+ * registry with icons nothing in production resolves.
+ */
+export function isTestFilePath(filePath) {
+  const normalised = filePath.replace(/\\/g, '/')
+  return /\.(test|spec)\.tsx?$/.test(normalised) || /(^|\/)(__tests__|tests|cypress)\//.test(normalised)
+}
+
+/**
+ * Parse a source file into a TypeScript syntax tree. Exported for tests, so a
+ * test can build a tree once and hand it to more than one extractor.
+ *
+ * Parsed as its own kind of file: a TSX parse reads TypeScript-only syntax in
+ * a .ts file (`<T>(props) => ...`) as JSX and loses what follows, so the
+ * script kind is derived from `filePath` rather than assumed.
+ */
+export async function parseIconSource(content, filePath, projectRoot = process.cwd()) {
+  const ts = await loadTypeScriptFor(projectRoot)
+  const sourceFile = ts.createSourceFile(filePath, content, ts.ScriptTarget.Latest, true, ts.getScriptKindFromFileName(filePath))
+  return { ts, sourceFile }
+}
+
+/** The property key of a `PropertyAssignment` node, whether written bare
+ * (`icon: X`), quoted (`'icon': X`) or computed with a literal (`['icon']: X`);
+ * anything else — a computed key that isn't a literal — has no static name. */
+function propertyKeyName(nameNode, ts) {
+  if (ts.isIdentifier(nameNode) || ts.isStringLiteralLike(nameNode)) {
+    return nameNode.text
+  }
+  if (ts.isComputedPropertyName(nameNode)) {
+    const expression = unwrapTransparentExpression(nameNode.expression, ts)
+    return expression && ts.isStringLiteralLike(expression) ? expression.text : null
+  }
+  return null
+}
+
+/**
+ * Peel off the TypeScript wrappers that change nothing about which value an
+ * expression is at runtime — `(expr)`, `expr as T`, `<T>expr`,
+ * `expr satisfies T`, `expr!` — so `icon: 'Wallet' as const`, `icon: <any>Wallet`
+ * and `icon: Wallet!` are read the same as `icon: 'Wallet'` and `icon: Wallet`.
+ * A regex-based scanner never saw these wrappers in the first place; reading
+ * syntax does, so it has to strip them explicitly instead of failing to match
+ * and dropping the icon silently.
+ */
+function unwrapTransparentExpression(expression, ts) {
+  let current = expression
+  while (current) {
+    if (
+      ts.isParenthesizedExpression(current) ||
+      ts.isAsExpression(current) ||
+      ts.isTypeAssertionExpression(current) ||
+      ts.isSatisfiesExpression(current) ||
+      ts.isNonNullExpression(current)
+    ) {
+      current = current.expression
+      continue
+    }
+    return current
+  }
+  return current
+}
+
 /**
  * Map of local name -> exported lucide name for a file's lucide imports.
  * `import { Home as HouseIcon }` means the config's `icon: HouseIcon` is
- * lucide's `Home`.
+ * lucide's `Home`. Read from the syntax tree, so an import mentioned only in
+ * a comment is not a real import.
  */
-function parseLucideImports(content) {
+function parseLucideImports(sourceFile, ts) {
   const imports = new Map()
 
-  for (const match of content.matchAll(/import\s*(?:type\s*)?\{([^}]*)\}\s*from\s*['"]lucide-react['"]/g)) {
-    for (const specifier of match[1].split(',')) {
-      const parts = specifier.trim().replace(/^type\s+/, '').split(/\s+as\s+/)
-      const exported = parts[0]?.trim()
-      const local = (parts[1] || parts[0])?.trim()
-      if (exported && local) {
-        imports.set(local, exported)
-      }
+  for (const statement of sourceFile.statements) {
+    if (!ts.isImportDeclaration(statement) || !ts.isStringLiteralLike(statement.moduleSpecifier)) continue
+    if (statement.moduleSpecifier.text !== 'lucide-react') continue
+
+    const namedBindings = statement.importClause?.namedBindings
+    if (!namedBindings || !ts.isNamedImports(namedBindings)) continue
+
+    for (const element of namedBindings.elements) {
+      if (element.isTypeOnly) continue
+      imports.set(element.name.text, (element.propertyName ?? element.name).text)
     }
   }
 
   return imports
 }
 
+/** The expression a `get icon()`-style accessor's body returns, when the
+ * body is exactly one `return <expr>` statement — the only shape simple
+ * enough to read a static icon name from. Anything else (no return,
+ * several statements, a conditional) has no single value to extract, so the
+ * caller falls back to the accessor node itself, which resolves as neither
+ * a literal nor a lucide import and is therefore reported as unresolved
+ * rather than silently dropped. */
+function accessorReturnExpression(node, ts) {
+  const [statement] = node.body?.statements ?? []
+  return node.body?.statements.length === 1 && statement && ts.isReturnStatement(statement) && statement.expression
+    ? statement.expression
+    : null
+}
+
+/** Whether a `set icon(v)` accessor has a `get icon()` beside it in the same
+ * object literal or class, the member that actually supplies the value. */
+function hasSiblingGetter(setter, ts) {
+  const siblings = setter.parent.properties ?? setter.parent.members ?? []
+  const key = propertyKeyName(setter.name, ts)
+  return siblings.some(sibling => ts.isGetAccessorDeclaration(sibling) && propertyKeyName(sibling.name, ts) === key)
+}
+
+/**
+ * Every icon-bearing property value in the tree, wherever it is nested —
+ * `icon` or `iconName` written plain, quoted or computed (`node.initializer`),
+ * as a class field with an initializer, the shorthand form `{ icon }`, where
+ * the property's own name doubles as the value (`node.name`), and a getter
+ * (`get icon() { return 'Wallet' }`), an accessor object configs use the same
+ * as a plain property.
+ *
+ * A member under an icon key that holds no name to read — a method
+ * (`icon() { ... }`, whose value is the function itself) or a setter with no
+ * getter beside it (whose value reads as undefined) — is collected as the
+ * member node, which resolves as neither a literal nor a lucide import and is
+ * therefore reported as unresolved rather than silently dropped.
+ */
+function findIconPropertyValues(sourceFile, ts) {
+  const values = []
+
+  const visit = node => {
+    if ((ts.isPropertyAssignment(node) || (ts.isPropertyDeclaration(node) && node.initializer)) && ICON_KEYS.has(propertyKeyName(node.name, ts))) {
+      values.push(node.initializer)
+    } else if (ts.isShorthandPropertyAssignment(node) && ICON_KEYS.has(node.name.text)) {
+      values.push(node.name)
+    } else if (ts.isGetAccessorDeclaration(node) && ICON_KEYS.has(propertyKeyName(node.name, ts))) {
+      values.push(accessorReturnExpression(node, ts) ?? node)
+    } else if (ts.isMethodDeclaration(node) && ICON_KEYS.has(propertyKeyName(node.name, ts))) {
+      values.push(node)
+    } else if (ts.isSetAccessorDeclaration(node) && ICON_KEYS.has(propertyKeyName(node.name, ts)) && !hasSiblingGetter(node, ts)) {
+      values.push(node)
+    }
+    ts.forEachChild(node, visit)
+  }
+  visit(sourceFile)
+
+  return values
+}
+
 /**
  * Icon names referenced by a single config file. Exported for tests.
  */
-export function extractIconNames(content) {
-  const lucideImports = parseLucideImports(content)
+export async function extractIconNames(content, filePath = 'icons.config.ts', projectRoot) {
+  const { ts, sourceFile } = await parseIconSource(content, filePath, projectRoot)
+  const lucideImports = parseLucideImports(sourceFile, ts)
   const names = []
 
-  // `icon: Users` or `'icon': Users` — only counts when the identifier came
-  // from lucide-react
-  for (const match of content.matchAll(/(?:\bicon|['"]icon['"])\s*:\s*([A-Za-z_$][\w$]*)/g)) {
-    const exported = lucideImports.get(match[1])
-    if (exported) {
-      names.push(exported)
+  for (const value of findIconPropertyValues(sourceFile, ts)) {
+    const initializer = unwrapTransparentExpression(value, ts)
+
+    // `icon: Users` — only counts when the identifier came from lucide-react
+    if (ts.isIdentifier(initializer)) {
+      const exported = lucideImports.get(initializer.text)
+      if (exported) names.push(exported)
+      continue
     }
-  }
 
-  // `icon: 'Users'` or `icon: 'pie-chart'` — a theme's sidebar sections and
-  // block configs use both spellings; the caller folds kebab-case into the
-  // lucide export name and validates the result against lucide's export list.
-  for (const match of content.matchAll(/(?:\bicon|['"]icon['"])\s*:\s*['"]([A-Za-z][\w$-]*)['"]/g)) {
-    names.push(match[1])
+    // `icon: 'Users'` or `icon: 'pie-chart'` — a theme's sidebar sections and
+    // block configs use both spellings; the caller folds kebab-case into the
+    // lucide export name and validates the result against lucide's export
+    // list. The generated registry is TypeScript built from this string, so
+    // anything not shaped like a name is dropped rather than trusted.
+    if (ts.isStringLiteralLike(initializer) && SAFE_NAME.test(initializer.text)) {
+      names.push(initializer.text)
+    }
   }
 
   return names
@@ -131,26 +302,282 @@ export function extractIconNames(content) {
  *
  * Only a direct named import of lucide-react and a string literal reach the
  * registry. Anything else — a namespace access (`I.Users`), an identifier
- * aliased through another module, a component of the project's own — is not
- * resolvable by reading this file, so it never enters the registry and
- * resolveIcon falls back. That is silent, hence the warning.
+ * aliased through another module, a call (`chooseIcon()`), a component of the
+ * project's own — is not resolvable by reading this file, so it never enters
+ * the registry and resolveIcon falls back. That is silent, hence the warning:
+ * whatever isn't one of the two resolvable shapes is reported, whatever kind
+ * of expression it is, rather than allowlisting the shapes worth warning about.
  */
-export function findUnresolvedIconRefs(content) {
-  const lucideImports = parseLucideImports(content)
+export async function findUnresolvedIconRefs(content, filePath = 'icons.config.ts', projectRoot) {
+  const { ts, sourceFile } = await parseIconSource(content, filePath, projectRoot)
+  const lucideImports = parseLucideImports(sourceFile, ts)
   const unresolved = []
 
-  for (const match of content.matchAll(/(?:\bicon|['"]icon['"])\s*:\s*([A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*)/g)) {
-    const reference = match[1]
-    const isMember = reference.includes('.')
+  for (const value of findIconPropertyValues(sourceFile, ts)) {
+    const initializer = unwrapTransparentExpression(value, ts)
 
-    if (isMember || !lucideImports.has(reference)) {
-      unresolved.push(reference)
+    // A wrapper that resolved to a usable literal or a known lucide import is
+    // not unresolved — extractIconNames already has it. Quoting the source as
+    // written (wrapper included) so the warning points at what a developer
+    // would grep for.
+    const resolvedAsLiteral = ts.isStringLiteralLike(initializer) && SAFE_NAME.test(initializer.text)
+    const resolvedAsLucideImport = ts.isIdentifier(initializer) && lucideImports.has(initializer.text)
+
+    if (!resolvedAsLiteral && !resolvedAsLucideImport) {
+      unresolved.push(value.getText(sourceFile))
     }
   }
 
   return unresolved
 }
 
+/** The string literal an expression evaluates to, unwrapping a JSX
+ * expression container (`{'pie-chart'}`) and any transparent TypeScript
+ * wrapper (`'pie-chart' satisfies string`) around it, or null when the
+ * expression isn't a literal — a runtime value that resolveIcon or
+ * DynamicIcon reads at render time, not a name this build can see. */
+function literalTextOf(expression, ts) {
+  const unwrapped = unwrapTransparentExpression(ts.isJsxExpression(expression) ? expression.expression : expression, ts)
+  return unwrapped && ts.isStringLiteralLike(unwrapped) ? unwrapped.text : null
+}
+
+/** Where a theme or plugin actually gets DynamicIcon and resolveIcon from —
+ * every subpath core publishes them under, via its `./lib/*` and
+ * `./components/*` export wildcards. Matched as a whole package name, not a
+ * string prefix: `@nextsparkjs/core-fake/lib/icons` starts with this string
+ * but is a different package entirely. */
+const CORE_PACKAGE_PREFIX = '@nextsparkjs/core'
+
+/** Whether a module specifier is core itself or one of its subpaths — the
+ * whole `@nextsparkjs/core` package segment, not merely a string prefix of it. */
+function isCorePackageSpecifier(moduleSpecifierText) {
+  return moduleSpecifierText === CORE_PACKAGE_PREFIX || moduleSpecifierText.startsWith(`${CORE_PACKAGE_PREFIX}/`)
+}
+
+/**
+ * Local bindings for whatever a file imports from core, so a call site is
+ * matched by what it actually refers to rather than by spelling: a named
+ * import tracks straight to its local name (aliased or not), a namespace
+ * import (`import * as Core from '@nextsparkjs/core/...'`) is tracked so
+ * `Core.resolveIcon(...)` resolves too.
+ */
+function parseCoreImports(sourceFile, ts) {
+  const named = new Map() // local name -> imported name
+  const namespaces = new Set() // local name bound to `import * as X`
+
+  for (const statement of sourceFile.statements) {
+    if (!ts.isImportDeclaration(statement) || !ts.isStringLiteralLike(statement.moduleSpecifier)) continue
+    if (!isCorePackageSpecifier(statement.moduleSpecifier.text)) continue
+
+    const namedBindings = statement.importClause?.namedBindings
+    if (!namedBindings) continue
+
+    if (ts.isNamedImports(namedBindings)) {
+      for (const element of namedBindings.elements) {
+        if (element.isTypeOnly) continue
+        named.set(element.name.text, (element.propertyName ?? element.name).text)
+      }
+    } else if (ts.isNamespaceImport(namedBindings)) {
+      namespaces.add(namedBindings.name.text)
+    }
+  }
+
+  return { named, namespaces }
+}
+
+/** The bare names a node declares in its own lexical scope: a function's
+ * parameters, a `let`/`const`/`var` declaration's bindings, a catch clause's
+ * binding. Destructured names are collected too, so `function f({ resolveIcon })`
+ * shadows the same as `function f(resolveIcon)`. */
+function collectBindingNames(name, ts, into) {
+  if (ts.isIdentifier(name)) {
+    into.add(name.text)
+  } else if (ts.isObjectBindingPattern(name) || ts.isArrayBindingPattern(name)) {
+    for (const element of name.elements) {
+      if (ts.isBindingElement(element)) collectBindingNames(element.name, ts, into)
+    }
+  }
+}
+
+/** Whether `node` starts its own `var` scope, one a hoisted `var` cannot
+ * escape: any function (declaration, expression, arrow, method, getter,
+ * setter, constructor), a class `static { }` block, or a TypeScript
+ * `namespace`, which compiles to a function of its own. This is where
+ * `collectHoistedVarNames` below stops recursing. */
+function isVarScopeBoundary(node, ts) {
+  return ts.isFunctionLike(node) || ts.isClassStaticBlockDeclaration(node) || ts.isModuleDeclaration(node)
+}
+
+/** Every `var`-declared name nested anywhere under `node` — inside an `if`,
+ * a loop, a `switch`, as deep as it goes — except inside a nested `var`
+ * scope (see isVarScopeBoundary). Unlike `let`/`const`, `var` ignores block
+ * boundaries, so a single level of `node.statements` (what the block/module
+ * branch below reads for `let`/`const`) misses one declared inside a nested
+ * block; this walks the whole subtree instead, the way hoisting actually
+ * works. */
+function collectHoistedVarNames(node, ts, into) {
+  if (isVarScopeBoundary(node, ts)) return
+
+  if (ts.isVariableStatement(node) && (node.declarationList.flags & ts.NodeFlags.BlockScoped) === 0) {
+    for (const declaration of node.declarationList.declarations) collectBindingNames(declaration.name, ts, into)
+  } else if (
+    (ts.isForStatement(node) || ts.isForInStatement(node) || ts.isForOfStatement(node)) &&
+    node.initializer &&
+    ts.isVariableDeclarationList(node.initializer) &&
+    (node.initializer.flags & ts.NodeFlags.BlockScoped) === 0
+  ) {
+    for (const declaration of node.initializer.declarations) collectBindingNames(declaration.name, ts, into)
+  }
+
+  ts.forEachChild(node, child => collectHoistedVarNames(child, ts, into))
+}
+
+/** The declarations directly in `statements` that introduce a name into
+ * their enclosing scope: function, class, `let`/`const`/`var` declarations,
+ * and TypeScript's value-bearing `enum`, `namespace` and `import x = ...`.
+ * Shared by a block/module's own statement list and by a `switch`'s case
+ * clauses, which — unlike a block per clause — all share one scope across
+ * the whole switch. */
+function blockScopedBindingNames(statements, ts, into) {
+  for (const statement of statements) {
+    if (
+      (ts.isFunctionDeclaration(statement) ||
+        ts.isClassDeclaration(statement) ||
+        ts.isEnumDeclaration(statement) ||
+        ts.isModuleDeclaration(statement) ||
+        ts.isImportEqualsDeclaration(statement)) &&
+      statement.name &&
+      ts.isIdentifier(statement.name)
+    ) {
+      into.add(statement.name.text)
+    } else if (ts.isVariableStatement(statement)) {
+      for (const declaration of statement.declarationList.declarations) {
+        collectBindingNames(declaration.name, ts, into)
+      }
+    }
+  }
+}
+
+/** The names `node` introduces into its own scope, or an empty set when it
+ * introduces none. Used while walking the tree to track which imported names
+ * are shadowed by a closer local declaration.
+ *
+ * A function's parameters — a getter's, a setter's and a constructor's as
+ * much as a method's or an arrow's — and a named function expression's own
+ * name are scoped to its parameter initializers and body. Its hoisted `var`
+ * names are added separately when the walk enters its body, because parameter
+ * initializers cannot see declarations from that body. A class expression's
+ * own name is scoped to itself, as is every `var` hoisted in a class `static
+ * { }` block or a `namespace` body. A block's (or the module's, or a
+ * namespace's) function, class and `let`/`const`/`var` declarations are
+ * scoped to the whole block, not merely to the statement that introduces
+ * them — a later sibling statement has to see the shadow too, the way it
+ * would at runtime. A `for`/`for-in`/`for-of` loop's own `let`/`const`
+ * initializer is scoped to the whole loop, not just to itself, and every
+ * clause of a `switch` shares one scope. */
+function ownScopeBindingNames(node, ts) {
+  const names = new Set()
+
+  if (ts.isFunctionLike(node)) {
+    for (const parameter of node.parameters) collectBindingNames(parameter.name, ts, names)
+    if (ts.isFunctionExpression(node) && node.name) {
+      names.add(node.name.text)
+    }
+  } else if (ts.isClassExpression(node) && node.name) {
+    names.add(node.name.text)
+  } else if (ts.isClassStaticBlockDeclaration(node)) {
+    collectHoistedVarNames(node.body, ts, names)
+  } else if (ts.isModuleBlock(node)) {
+    blockScopedBindingNames(node.statements, ts, names)
+    for (const statement of node.statements) collectHoistedVarNames(statement, ts, names)
+  } else if (ts.isVariableDeclarationList(node)) {
+    for (const declaration of node.declarations) collectBindingNames(declaration.name, ts, names)
+  } else if ((ts.isForStatement(node) || ts.isForInStatement(node) || ts.isForOfStatement(node)) && node.initializer && ts.isVariableDeclarationList(node.initializer)) {
+    for (const declaration of node.initializer.declarations) collectBindingNames(declaration.name, ts, names)
+  } else if (ts.isCatchClause(node) && node.variableDeclaration) {
+    collectBindingNames(node.variableDeclaration.name, ts, names)
+  } else if (ts.isCaseBlock(node)) {
+    for (const clause of node.clauses) blockScopedBindingNames(clause.statements, ts, names)
+  } else if (ts.isBlock(node) || ts.isSourceFile(node)) {
+    blockScopedBindingNames(node.statements, ts, names)
+    if (ts.isSourceFile(node)) collectHoistedVarNames(node, ts, names)
+  }
+
+  return names
+}
+
+/**
+ * Whether `expression` — a JSX tag name or a call's callee — is the given
+ * core export, resolved through the file's own imports rather than by
+ * comparing text: `import { resolveIcon as ri }` still matches `ri(...)` and
+ * `ri!(...)`, `import * as Core from '@nextsparkjs/core/lib/icons'` still
+ * matches `Core.resolveIcon(...)`, and a same-named local that was never
+ * imported from core — a theme's own `resolveIcon` helper, or a function
+ * parameter that shadows the import — does not.
+ */
+function referencesCoreExport(expression, exportName, imports, ts, shadowStack) {
+  const unwrapped = unwrapTransparentExpression(expression, ts)
+  const isShadowed = name => shadowStack.some(scope => scope.has(name))
+
+  if (ts.isIdentifier(unwrapped)) {
+    return !isShadowed(unwrapped.text) && imports.named.get(unwrapped.text) === exportName
+  }
+  if (ts.isPropertyAccessExpression(unwrapped) && ts.isIdentifier(unwrapped.expression)) {
+    return !isShadowed(unwrapped.expression.text) && imports.namespaces.has(unwrapped.expression.text) && unwrapped.name.text === exportName
+  }
+  return false
+}
+
+/**
+ * Icon names passed as a string literal to DynamicIcon's `name` prop or to
+ * resolveIcon's first argument. Exported for tests.
+ *
+ * Both accept a runtime variable too (`resolveIcon(item.icon)`, the normal
+ * way to render a value that came from the database) — that call is left
+ * alone, since there is no name in it to register.
+ */
+export async function extractLiteralIconCallNames(content, filePath = 'icons.tsx', projectRoot) {
+  const { ts, sourceFile } = await parseIconSource(content, filePath, projectRoot)
+  const imports = parseCoreImports(sourceFile, ts)
+  const names = []
+
+  // A local declaration (a function parameter, a `let`/`const`, a catch
+  // binding) shadows an import of the same name for the rest of its scope,
+  // the same way it would at runtime — so the stack of scopes entered so far
+  // travels with the walk instead of imports being looked up by name alone.
+  const visit = (node, shadowStack) => {
+    const ownNames = ownScopeBindingNames(node, ts)
+    const nextStack = ownNames.size > 0 ? [...shadowStack, ownNames] : shadowStack
+
+    if ((ts.isJsxSelfClosingElement(node) || ts.isJsxOpeningElement(node)) && referencesCoreExport(node.tagName, 'DynamicIcon', imports, ts, nextStack)) {
+      for (const attribute of node.attributes.properties) {
+        if (!ts.isJsxAttribute(attribute) || attribute.name.text !== 'name' || !attribute.initializer) continue
+        const name = literalTextOf(attribute.initializer, ts)
+        if (name && SAFE_NAME.test(name)) names.push(name)
+      }
+    } else if (ts.isCallExpression(node) && referencesCoreExport(node.expression, 'resolveIcon', imports, ts, nextStack)) {
+      const [firstArgument] = node.arguments
+      const name = firstArgument && literalTextOf(firstArgument, ts)
+      if (name && SAFE_NAME.test(name)) names.push(name)
+    }
+
+    if (ts.isFunctionLike(node) && node.body) {
+      const bodyNames = new Set()
+      collectHoistedVarNames(node.body, ts, bodyNames)
+      const bodyStack = bodyNames.size > 0 ? [...nextStack, bodyNames] : nextStack
+      ts.forEachChild(node, child => {
+        const childStack = child === node.body ? bodyStack : node.parameters.includes(child) ? nextStack : shadowStack
+        visit(child, childStack)
+      })
+    } else {
+      ts.forEachChild(node, child => visit(child, nextStack))
+    }
+  }
+  visit(sourceFile, [])
+
+  return names
+}
+
 async function collectConfigFiles(dir, matcher, found = []) {
   if (!existsSync(dir)) {
     return found
@@ -195,12 +622,17 @@ function coreEntitiesDir(config) {
 export async function discoverIcons(blocks, config) {
   const candidates = new Set(FALLBACK_ICONS)
 
-  // Only the configs whose icons reach resolveIcon. Widening this would put
-  // icons in the dashboard bundle that nothing can ask for.
+  // Only the configs whose icons reach resolveIcon: entity configs (core,
+  // themes and plugins), block configs, and every theme's or plugin's
+  // config/*.config.ts. Widening this further would put icons in the
+  // dashboard bundle that nothing can ask for. Test files are excluded even
+  // though a config rarely lives under one, for the same reason call sources
+  // exclude them below.
+  const isIconSource = filePath => isIconSourcePath(filePath) && !isTestFilePath(filePath)
   const iconSources = [
-    ...(await collectConfigFiles(coreEntitiesDir(config), isIconSourcePath)),
-    ...(await collectConfigFiles(config.themesDir, isIconSourcePath)),
-    ...(await collectConfigFiles(config.pluginsDir, isIconSourcePath))
+    ...(await collectConfigFiles(coreEntitiesDir(config), isIconSource)),
+    ...(await collectConfigFiles(config.themesDir, isIconSource)),
+    ...(await collectConfigFiles(config.pluginsDir, isIconSource))
   ]
 
   const unresolved = []
@@ -208,10 +640,10 @@ export async function discoverIcons(blocks, config) {
   for (const configPath of iconSources) {
     try {
       const content = await readFile(configPath, 'utf8')
-      for (const name of extractIconNames(content)) {
+      for (const name of await extractIconNames(content, configPath, config.projectRoot)) {
         candidates.add(name)
       }
-      for (const reference of findUnresolvedIconRefs(content)) {
+      for (const reference of await findUnresolvedIconRefs(content, configPath, config.projectRoot)) {
         unresolved.push({ configPath, reference })
       }
     } catch {
@@ -226,6 +658,29 @@ export async function discoverIcons(blocks, config) {
     )
   }
 
+  // A theme or plugin can also name an icon directly in its own component
+  // code rather than through a config, so its trees are scanned for that too.
+  // Core is not: every core call site resolves a runtime value (item.icon,
+  // config.iconName), never a literal, so there is nothing to add here.
+  // Test files are excluded: a spec exercising DynamicIcon or resolveIcon
+  // with a literal name isn't a real call site the production bundle needs.
+  const isIconCallSource = filePath => isIconCallSourcePath(filePath) && !isTestFilePath(filePath)
+  const callSources = [
+    ...(await collectConfigFiles(config.themesDir, isIconCallSource)),
+    ...(await collectConfigFiles(config.pluginsDir, isIconCallSource))
+  ]
+
+  for (const sourcePath of callSources) {
+    try {
+      const content = await readFile(sourcePath, 'utf8')
+      for (const name of await extractLiteralIconCallNames(content, sourcePath, config.projectRoot)) {
+        candidates.add(name)
+      }
+    } catch {
+      verbose(`[icons] Could not read ${sourcePath}`)
+    }
+  }
+
   for (const block of blocks || []) {
     if (block.icon) {
       candidates.add(block.icon)

package/scripts/build/registry/discovery/templates.mjs

@@ -43,7 +43,7 @@ export async function discoverTemplates(config = DEFAULT_CONFIG) {
 ║  Or ensure your .env file has NEXT_PUBLIC_ACTIVE_THEME set correctly.        ║
 ╚══════════════════════════════════════════════════════════════════════════════╝
 `
-    console.error(errorMsg)
+    for (const line of errorMsg.split('\n')) console.error(line)
     throw new Error('NEXT_PUBLIC_ACTIVE_THEME environment variable is required for template discovery')
   }
 

package/scripts/build/registry/generators/billing-registry.mjs

@@ -140,7 +140,7 @@ export async function generateBillingRegistry(activeTheme, contentsDir, config)
   let billingConfig
   try {
     // Use jiti to import .ts files at build time (Node.js can't import .ts natively)
-    const jiti = createJiti(import.meta.url, { interopDefault: true })
+    const jiti = createJiti(import.meta.url, { interopDefault: true, fsCache: false })
     const module = await jiti.import(absolutePath)
     billingConfig = module.billingConfig || module.default
   } catch (error) {