chore: 纳入本地 Dify 1.19.0 源码及品牌与免登改动

演示目录只保留可重建的源码。运行密钥、数据卷、依赖和带口令的本地配置不进入仓库。

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
wuzilongandCursor committed 2026-11-18 13:59:25 +08:00
1 parent 60158935f4
commit 6519682885
15831 files changed
+3063428

No files matched your search

File diff suppressed because it is too large. Load diff
File diff suppressed because it is too large. Load diff
@@ -0,0 +1,215 @@
// @vitest-environment node
import { describe, expect, it } from 'vite-plus/test'
import {
analyzeEnvironmentRoutes,
analyzeRouteNamespaces,
validateRouteNamespaces,
} from '../i18n-analysis/routes'
describe('route namespace analysis', () => {
it('includes ancestor boundaries and parallel slots without leaking sibling layouts', () => {
const usage = new Map(
Object.entries({
'/web/app/layout.tsx': ['common'],
'/web/app/(console)/layout.tsx': ['console'],
'/web/app/(console)/items/page.tsx': ['items'],
'/web/app/(console)/items/loading.tsx': ['loading'],
'/web/app/(console)/items/error.tsx': ['error'],
'/web/app/(console)/@sidebar/default.tsx': ['sidebar'],
'/web/app/(console)/@sidebar/detail/page.tsx': ['detail'],
'/web/app/(public)/layout.tsx': ['public'],
'/web/app/(public)/page.tsx': [],
'/web/shared.ts': ['shared'],
'/web/lazy.ts': ['items', 'lazy'],
}).map(([id, namespaces]) => [id, new Set(namespaces)]),
)
const dependencies = new Map([
['/web/lazy.ts', { static: new Set(['/web/shared.ts']), dynamic: new Set<string>() }],
[
'/web/app/(console)/items/page.tsx',
{ static: new Set(['\0virtual-component']), dynamic: new Set(['/web/lazy.ts']) },
],
['\0virtual-component', { static: new Set(['/web/shared.ts']), dynamic: new Set<string>() }],
['/web/shared.ts', { static: new Set(['\0virtual-component']), dynamic: new Set<string>() }],
])
const report = analyzeRouteNamespaces('/web', dependencies, usage)
expect(report.find((item) => item.page === 'app/(console)/items/page.tsx')).toMatchObject({
route: '/items',
page: 'app/(console)/items/page.tsx',
namespaces: [
'common',
'console',
'detail',
'error',
'items',
'lazy',
'loading',
'shared',
'sidebar',
],
})
expect(() => validateRouteNamespaces(report, () => undefined)).not.toThrow()
expect(() =>
validateRouteNamespaces(report, (route) =>
route === '/items'
? [
'common',
'console',
'detail',
'error',
'items',
'lazy',
'loading',
'shared',
'sidebar',
]
: undefined,
),
).not.toThrow()
expect(() =>
validateRouteNamespaces(report, (route) => (route === '/items' ? [] : undefined)),
).toThrow(
/Route namespace declarations[\s\S]*\/items[\s\S]*\[shared\] app\/layout.tsx[\s\S]*\[slots\][\s\S]*\[page\][\s\S]*\[lazy\] lazy.ts/,
)
const groups = report.find((item) => item.page === 'app/(console)/items/page.tsx')!.groups
expect(groups.page).toEqual([
{ namespace: 'items', sources: ['app/(console)/items/page.tsx'] },
{ namespace: 'shared', sources: ['shared.ts'] },
])
expect(groups.lazy).toEqual([
{ namespace: 'items', sources: ['lazy.ts'] },
{ namespace: 'lazy', sources: ['lazy.ts'] },
])
expect(groups.slots).toEqual([
{ namespace: 'detail', sources: ['app/(console)/@sidebar/detail/page.tsx'] },
{ namespace: 'sidebar', sources: ['app/(console)/@sidebar/default.tsx'] },
])
expect(report.find((item) => item.page === 'app/(public)/page.tsx')).toMatchObject({
route: '/',
page: 'app/(public)/page.tsx',
namespaces: ['common', 'public'],
groups: { page: [], lazy: [], slots: [] },
})
})
})
describe('environment route boundaries', () => {
const edge = (ids: string[]) => ({ static: new Set(ids), dynamic: new Set<string>() })
it('shares dependency paths across routes and namespaces', () => {
const report = analyzeEnvironmentRoutes(
'/web',
new Map([
[
'client',
{
usage: new Map([
['/web/app/a/page.ts', new Set<string>()],
['/web/app/b/page.ts', new Set<string>()],
['/web/app/layout.ts', new Set<string>()],
['/web/shared.ts', new Set(['common', 'app'])],
]),
dependencies: new Map([
['/web/app/layout.ts', edge(['/web/shared.ts'])],
['/web/shared.ts', edge(['/web/app/layout.ts'])],
]),
clientReferences: new Set<string>(),
},
],
]),
)
expect(report.routes).toHaveLength(2)
const references = report.routes.flatMap((route) =>
route.groups.shared.flatMap((group) => group.dependencyPaths!),
)
expect(references).toHaveLength(4)
expect(new Set(references).size).toBe(1)
const [moduleIndex, parentIndex] = report.paths[references[0]!]!
expect(report.modules[moduleIndex]).toEqual({
environment: 'client',
moduleId: '/web/shared.ts',
})
const [rootIndex, rootParent] = report.paths[parentIndex!]!
expect(report.modules[rootIndex]).toEqual({
environment: 'client',
moduleId: '/web/app/layout.ts',
})
expect(rootParent).toBeNull()
expect(report.paths).toHaveLength(2)
})
it('does not combine unrelated paths from different environments', () => {
const usage = new Map([
['/web/app/page.ts', new Set<string>()],
['/web/bridge.ts', new Set<string>()],
['/web/extra.ts', new Set(['extra'])],
])
const graphs = new Map([
[
'client',
{
usage,
dependencies: new Map([['/web/app/page.ts', edge(['/web/bridge.ts'])]]),
clientReferences: new Set<string>(),
},
],
[
'ssr',
{
usage,
dependencies: new Map([['/web/bridge.ts', edge(['/web/extra.ts'])]]),
clientReferences: new Set<string>(),
},
],
])
expect(analyzeEnvironmentRoutes('/web', graphs).routes[0]!.namespaces).toEqual([])
})
it('follows explicit client references into both SSR and client implementations', () => {
const graphs = new Map([
[
'rsc',
{
usage: new Map([
['/web/app/page.ts', new Set<string>()],
['/web/widget.tsx', new Set<string>()],
]),
dependencies: new Map([
['/web/app/page.ts', edge(['/web/widget.tsx'])],
['/web/widget.tsx', edge([])],
]),
clientReferences: new Set(['/web/widget.tsx']),
},
],
[
'ssr',
{
usage: new Map([
['/web/widget.tsx', new Set<string>()],
['/web/server-label.ts', new Set(['server'])],
]),
dependencies: new Map([['/web/widget.tsx', edge(['/web/server-label.ts'])]]),
clientReferences: new Set<string>(),
unknownNamespaces: new Set(['/web/server-label.ts']),
},
],
[
'client',
{
usage: new Map([
['/web/widget.tsx', new Set<string>()],
['/web/browser-label.ts', new Set(['browser'])],
]),
dependencies: new Map([['/web/widget.tsx', edge(['/web/browser-label.ts'])]]),
clientReferences: new Set<string>(),
},
],
])
expect(analyzeEnvironmentRoutes('/web', graphs).routes).toMatchObject([
{
route: '/',
namespaces: ['browser', 'server'],
unknownNamespaceSources: ['server-label.ts'],
},
])
})
})
@@ -0,0 +1,78 @@
import type { Plugin } from 'vite'
import fs from 'node:fs'
import { injectClientSnippet, normalizeViteModuleId } from './utils.ts'
type CustomI18nHmrPluginOptions = {
injectTarget: string
}
export const customI18nHmrPlugin = ({ injectTarget }: CustomI18nHmrPluginOptions): Plugin => {
const i18nHmrClientMarker = 'custom-i18n-hmr-client'
const i18nHmrClientSnippet = `/* ${i18nHmrClientMarker} */
if (import.meta.hot) {
const getI18nUpdateTarget = (file) => {
const match = file.match(/[/\\\\]i18n[/\\\\]locales[/\\\\]([^/\\\\]+)[/\\\\]([^/\\\\]+)\\.json$/)
if (!match)
return null
const [, locale, namespaceFile] = match
return { locale, namespaceFile }
}
import.meta.hot.on('i18n-update', async ({ file, content }) => {
const target = getI18nUpdateTarget(file)
if (!target)
return
const [{ getI18n }, { camelCase }] = await Promise.all([
import('react-i18next'),
import('es-toolkit/string'),
])
const i18n = getI18n()
if (!i18n)
return
if (target.locale !== i18n.language)
return
let resources
try {
resources = JSON.parse(content)
}
catch {
return
}
const namespace = camelCase(target.namespaceFile)
i18n.addResourceBundle(target.locale, namespace, resources, true, true)
i18n.emit('languageChanged', i18n.language)
})
}
`
return {
name: 'custom-i18n-hmr',
apply: 'serve',
handleHotUpdate({ file, server }) {
if (file.endsWith('.json') && file.includes('/i18n/locales/')) {
server.ws.send({
type: 'custom',
event: 'i18n-update',
data: {
file,
content: fs.readFileSync(file, 'utf-8'),
},
})
return []
}
},
transform(code, id) {
const cleanId = normalizeViteModuleId(id)
if (cleanId !== injectTarget) return null
const nextCode = injectClientSnippet(code, i18nHmrClientMarker, i18nHmrClientSnippet)
if (nextCode === code) return null
return { code: nextCode, map: null }
},
}
}
@@ -0,0 +1,357 @@
import type { PluginApi } from '@vitejs/plugin-rsc'
import type { Logger, Plugin } from 'vite'
import type { TranslationAdapter } from './i18n-analysis/api'
import type { createImportBindingReader, ModuleResolutions } from './i18n-analysis/compiler'
import type { AnalysisEvidence } from './i18n-analysis/graph'
import type {
EnvironmentUsage,
ModuleDependencies,
ModuleLocation,
RouteNamespaceReport,
} from './i18n-analysis/routes'
import { createHash } from 'node:crypto'
import fs from 'node:fs/promises'
import path from 'node:path'
import { normalizePath } from 'vite'
import { analyzeEnvironmentRoutes, validateRouteNamespaces } from './i18n-analysis/routes'
import { analyzeGraphInWorker } from './i18n-analysis/worker'
const SOURCE_META = 'dify:i18n-source'
export type AnalysisReport = {
version: 3
routes: RouteNamespaceReport[]
modules: ModuleLocation[]
paths: [module: number, parent: number | null][]
evidence: (AnalysisEvidence & { environment: string })[]
metrics: {
totalMs: number
setupMs: number
routesMs: number
environments: {
environment: string
modules: number
resolveCalls: number
resolutionMs: number
programMs: number
analysisMs: number
}[]
}
}
// Vite shares these instances across client, SSR, and RSC environments. Each
// completed graph replaces its preceding scan build; only buildApp finalizes it.
export function i18nAnalysisPlugin(
options: {
adapters?: readonly TranslationAdapter[]
onAnalysis?: (report: AnalysisReport) => void
strictNamespaces?: boolean
getDeclaredNamespaces?: (route: string) => readonly string[] | undefined
} = {},
): Plugin[] {
let root: string
let logger: Logger
let reportPath: string | undefined
let buildingApp = false
let rscApi: PluginApi | undefined
let readBindings: ReturnType<typeof createImportBindingReader> | undefined
const graphs = new Map<
string,
{
modules: Map<string, string>
dependencies: Map<string, ModuleDependencies>
resolutions: ModuleResolutions
clientReferences: Set<string>
resolveCalls: number
resolutionMs: number
}
>()
const moduleId = normalizePath
const checks = new Map<string, Promise<void>>()
const snapshots = new Map<string, string>()
const environmentOrder = new Set<string>()
const check = async () => {
// Import collection is complete; do not retain source strings and binding
// arrays while the TypeScript programs allocate their type state.
readBindings = undefined
const started = performance.now()
const environments = new Map<string, EnvironmentUsage>()
const evidence: AnalysisReport['evidence'] = []
const metrics: AnalysisReport['metrics'] = {
totalMs: 0,
setupMs: 0,
routesMs: 0,
environments: [],
}
let unused: Record<string, string[]> | undefined
const protectedNamespaces = new Set<string>()
for (const environment of environmentOrder) {
const graph = graphs.get(environment)
if (!graph) continue
const result = await analyzeGraphInWorker({
root,
modules: graph.modules,
resolutions: graph.resolutions,
adapters: options.adapters ?? [],
})
metrics.setupMs += result.setupMs
environments.set(environment, {
dependencies: graph.dependencies,
usage: result.moduleNamespaces,
clientReferences: graph.clientReferences,
unknownNamespaces: new Set(
result.evidence
.filter((item) => item.kind === 'unknown-namespace')
.map((item) => item.moduleId),
),
})
evidence.push(...result.evidence.map((item) => ({ ...item, environment })))
metrics.environments.push({
environment,
modules: graph.modules.size,
resolveCalls: graph.resolveCalls,
resolutionMs: graph.resolutionMs,
...result.timings,
})
for (const namespace of result.protectedNamespaces) protectedNamespaces.add(namespace)
// Intersect unused sets: usage (or protection) in any environment keeps a key.
unused =
unused === undefined
? result.unused
: Object.fromEntries(
Object.entries(unused).map(([namespace, keys]) => {
const remaining = new Set(result.unused[namespace] ?? [])
return [namespace, keys.filter((key) => remaining.has(key))]
}),
)
}
const routesStarted = performance.now()
const { routes, modules, paths } = analyzeEnvironmentRoutes(normalizePath(root), environments)
metrics.routesMs = performance.now() - routesStarted
metrics.totalMs =
performance.now() -
started +
metrics.environments.reduce((sum, item) => sum + item.resolutionMs, 0)
const report: AnalysisReport = { version: 3, routes, modules, paths, evidence, metrics }
options.onAnalysis?.(report)
logger.info(
`[i18n] Analysis: ${metrics.totalMs.toFixed(0)}ms; ${metrics.environments.reduce((sum, item) => sum + item.modules, 0)} environment modules; ${metrics.environments.reduce((sum, item) => sum + item.resolveCalls, 0)} resolver calls.`,
)
const unresolved = evidence.filter((item) => item.kind === 'unresolved-import')
if (unresolved.length) {
const categories = new Map<string, number>()
for (const item of unresolved) {
const category = item.import?.kind ?? 'source'
categories.set(category, (categories.get(category) ?? 0) + 1)
}
logger.warn(
`[i18n] ${unresolved.length} runtime imports could not be traced (${[...categories].map(([kind, count]) => `${kind}: ${count}`).join(', ')}); inspect the report before trusting unused-key findings.`,
)
}
const incomplete = routes.filter((route) => route.unknownNamespaceSources?.length)
if (incomplete.length)
logger.warn(
`[i18n] Namespace analysis is incomplete for ${incomplete.length} routes; inspect unknownNamespaceSources before treating validation as complete.`,
)
const unknown = evidence.filter((item) => item.kind === 'unknown-namespace').length
const dynamic = evidence.filter((item) => item.kind === 'dynamic-key').length
logger.info(
`[i18n] Routes: ${routes.length}; unknown namespace records: ${unknown}; dynamic key records: ${dynamic}; protected namespaces: ${[...protectedNamespaces].sort().join(', ') || '(none)'}.`,
)
if (reportPath) {
await fs.mkdir(path.dirname(reportPath), { recursive: true })
await fs.writeFile(reportPath, `${JSON.stringify(report, null, 2)}\n`)
logger.info(`[i18n] Full namespace sources: ${reportPath}`)
}
if (options.getDeclaredNamespaces)
validateRouteNamespaces(routes, options.getDeclaredNamespaces, options.strictNamespaces)
const keys = Object.entries(unused ?? {}).flatMap(([namespace, unused]) =>
unused.map((key) => `${namespace}:${key}`),
)
if (keys.length) {
throw new Error(
[
`Found ${keys.length} potentially unused i18n keys in the application build:`,
'This report uses static analysis of the current build module graph and may contain false positives or miss unused keys.',
'Review actual usage before removing any keys.',
...keys.map((key) => ` - ${key}`),
'Remove confirmed unused keys from web/i18n/locales/ locale files or restore their application usage.',
...(protectedNamespaces.size
? [
`Dynamic keys protect these namespaces: ${[...protectedNamespaces].sort().join(', ')}`,
]
: []),
].join('\n'),
)
}
}
return [
{
name: 'i18n-analysis:collect',
apply: 'build',
enforce: 'pre',
sharedDuringBuild: true,
async configResolved(config) {
const { getPluginApi } = await import('@vitejs/plugin-rsc')
rscApi = getPluginApi(config)
root = config.root
logger = config.logger
reportPath = config.build.write
? path.resolve(root, config.build.outDir, 'i18n-routes.json')
: undefined
},
async buildApp() {
readBindings = undefined
graphs.clear()
environmentOrder.clear()
checks.clear()
snapshots.clear()
buildingApp = true
},
buildStart() {
if (this.meta.watchMode) {
readBindings = undefined
checks.delete(this.environment.name)
snapshots.delete(this.environment.name)
}
if (!buildingApp && !snapshots.has(this.environment.name)) {
graphs.clear()
environmentOrder.clear()
}
environmentOrder.add(this.environment.name)
},
transform: {
filter: {
id: { include: /\.[cm]?[jt]sx?(?:\?.*)?$/, exclude: /(?:^\0|\/node_modules\/)/ },
},
handler(code, id) {
if (!path.isAbsolute(id.split('?')[0]!)) return
// Keep original source in cached metadata before TS/JSX/RSC transforms.
return { code, map: null, meta: { [SOURCE_META]: code } }
},
},
async buildEnd(error) {
if (error) return
// RSC explicitly marks its reference scans; write:false alone also
// describes ordinary in-memory builds whose usage must be checked.
if (buildingApp && rscApi?.manager.isScanBuild) return
const resolutionStarted = performance.now()
const graph = new Map<string, string>()
const compiledModules = new Map<string, string>()
const dependencies = new Map<string, ModuleDependencies>()
for (const id of this.getModuleIds()) {
const info = this.getModuleInfo(id)
if (info) {
const imports = dependencies.get(moduleId(id)) ?? {
static: new Set<string>(),
dynamic: new Set<string>(),
}
for (const dependency of info.importedIds) imports.static.add(moduleId(dependency))
for (const dependency of info.dynamicallyImportedIds)
imports.dynamic.add(moduleId(dependency))
dependencies.set(moduleId(id), imports)
}
// Analyze the actual JSON module produced by Vite, never the raw disk file.
if (id.endsWith('.json') && info?.code) {
graph.set(moduleId(id), info.code)
compiledModules.set(moduleId(id), info.code)
}
const source: unknown = info?.meta[SOURCE_META]
if (typeof source === 'string') {
graph.set(moduleId(id), source)
compiledModules.set(moduleId(id), info?.code ?? '')
}
}
// Rolldown may rebuild for another output format. Reuse only within
// this open bundle and only when source, transforms and edges agree.
const hash = createHash('sha256')
for (const [id, imports] of [...dependencies].sort(([a], [b]) => a.localeCompare(b))) {
hash.update(
JSON.stringify([
id,
graph.get(id),
compiledModules.get(id),
[...imports.static].sort(),
[...imports.dynamic].sort(),
]),
)
}
const snapshot = hash.digest('hex')
if (snapshots.get(this.environment.name) === snapshot) return
checks.delete(this.environment.name)
snapshots.set(this.environment.name, snapshot)
const { createImportBindingReader, hasClientDirective, resolveTranslationImports } =
await import('./i18n-analysis/compiler')
readBindings ??= createImportBindingReader()
const clientReferences = new Set<string>()
if (this.environment.name === 'rsc') {
for (const [id, code] of graph) {
if (!hasClientDirective(code)) continue
clientReferences.add(id)
graph.set(id, compiledModules.get(id) ?? '')
}
}
const { resolutions, resolveCalls } = await resolveTranslationImports(
graph,
compiledModules,
async (specifier, importer) => {
const resolved = await this.resolve(specifier, importer)
return resolved
? { id: moduleId(resolved.id), external: !!resolved.external }
: undefined
},
(specifier) =>
!specifier.includes('?') && this.environment.config.assetsInclude(specifier),
readBindings,
)
graphs.set(this.environment.name, {
modules: graph,
dependencies,
resolutions,
resolveCalls,
resolutionMs: performance.now() - resolutionStarted,
clientReferences,
})
},
closeBundle() {
if (!buildingApp) readBindings = undefined
snapshots.delete(this.environment.name)
checks.delete(this.environment.name)
},
async generateBundle() {
if (buildingApp) return
let pending = checks.get(this.environment.name)
if (!pending) {
pending = check()
checks.set(this.environment.name, pending)
}
await pending
},
},
{
name: 'i18n-analysis:check',
apply: 'build',
sharedDuringBuild: true,
buildApp: {
order: 'post',
async handler(builder) {
try {
// Vite's default environment loop runs after post hooks. Vinext
// builds earlier; plain Vite needs its default loop completed here.
if (Object.values(builder.environments).every((environment) => !environment.isBuilt)) {
for (const environment of Object.values(builder.environments))
await builder.build(environment)
}
await check()
} finally {
buildingApp = false
readBindings = undefined
graphs.clear()
}
},
},
},
]
}
@@ -0,0 +1,216 @@
# i18n build analysis
`i18nAnalysisPlugin()` prints a compact summary during production Vite builds,
before the existing unused-key check. With Vinext it reports once, after combining
the completed client, SSR and RSC graphs. Development does not run the analysis.
Reference scans explicitly marked by the RSC plugin API are skipped; ordinary
`build.write: false` builds still receive the full analysis.
The console shows route and diagnostic counts, namespaces protected by dynamic
keys, and the report path. Diagnostic counts include separate environment records.
Individual route/group listings are available in `i18n-routes.json` (or through
`onAnalysis` when `build.write` is false). Each route retains its pattern, source
page, sorted namespaces and the page/shared/lazy/slots groups. Validation failures
still print the affected route and source details.
The report follows resolved static and dynamic imports, including virtual modules,
and adds ancestor layouts, templates, loading/error/not-found boundaries. Route
groups are omitted from the URL pattern. Parallel slots include all built branches
because their active page can depend on navigation history. Interception segments
remain visible in labels; the source page disambiguates entries with the same URL.
## Module resolution
Vite owns module identity and runtime import resolution. Each completed environment
retains original source in module metadata and resolves surviving imports through
that environment's plugin resolver. When a transform changes an import specifier,
matching import/export bindings connect it back to the original source. Ambiguous
or removed application value imports, including unchanged imports resolved to unanalyzed virtual
modules, are reported as unresolved instead of silently reading
the old runtime module from disk. Rewritten or removed literal dynamic imports
are also blocked: without a stable binding, their replacement cannot be inferred
from call order. Matching checks binding signatures and occurrence counts rather
than merely whether a specifier survives. If uses of one specifier disagree, the
TypeScript host blocks that specifier as a whole because its resolution is shared
across import occurrences. Explicit type-only imports and package declarations
continue to use TypeScript resolution. Package barrel rewrites retain declaration
resolution only when every imported local binding is traced to the same external
package. Resource imports are excluded from diagnostics, while application source
query variants remain distinct throughout dependency and
usage analysis, with separate in-memory compiler filenames. Built JSON modules use
Vite-transformed JavaScript under synthetic compiler filenames, preserving inferred
object keys without loading a different JSON file from disk. JSON data modules inform
types but are not scanned as translation call sites. Reports display their
underlying source paths.
This is a conservative module-level estimate, not a runtime loading manifest.
It shares the unused-key analyzer's translation recognition and dynamic-key
fallbacks. Unresolved namespaces can include the entire catalog. Unused exports,
conditional branches, lazy features and parallel slots can overestimate usage;
runtime-only imports or unrecognized translation APIs can be missed. Only pages
and boundaries present in the build graph are reported. Reporting alone does not
change translation loading or introduce additional build failures.
## Groups and source files
- `page`: the page and its transitive static imports.
- `shared`: ancestor layouts, templates and loading/error/not-found boundaries,
including their transitive static imports. This includes same-segment boundaries.
- `lazy`: modules reached through dynamic imports from the page or shared entries,
excluding modules already statically reachable from either. Dynamic import does
not prove that a feature loads only after user interaction.
- `slots`: modules reachable from all built ancestor parallel-slot branches,
excluding modules already reachable from the page/shared entries (including lazy).
Page and shared groups can overlap. A namespace can appear in multiple groups
when different modules use it; group counts must not be added to obtain the total.
Dependencies retain their environment identity. Only explicit `use client`
directives connect an RSC reference to the same module's SSR and client versions;
ordinary shared filenames do not connect environments. The RSC reference stub is
analyzed as generated code, with implementation usage coming from SSR and client.
Route reports are then merged by source page. A group can differ across environments.
This is not a client-only bundle analysis. Custom environment names or other
framework-specific cross-environment reference mechanisms are not inferred.
When build output writing is enabled, `<build.outDir>/i18n-routes.json` contains
`{ version: 3, routes, modules, paths, evidence, metrics }`, including when no routes were detected.
Every route retains `route`, `page` and `namespaces`, with `groups` mapping each
category to `{ namespace, sources, dependencyPaths }` entries. Each dependency
path is an index into the shared `paths` table. Each table entry is a
`[moduleIndex, parentPathIndex]` tuple; a null parent starts a chain. `moduleIndex`
indexes `modules`, whose entries contain `{ environment, moduleId }`, preserving
queries and virtual IDs. Follow parents and reverse the steps to reconstruct a
chain. Shared prefixes are stored once across routes and namespaces.
Paths provide one shortest discovered explanation per reachable source and environment,
not an enumeration of every possible path. Sources are
sorted paths relative to the Vite root and identify modules containing recognized
translation usage, not necessarily the entire chain of imports leading to them.
The report is written before namespace validation and the unused-key check, so
it remains available if either check fails. `build.write: false` only prints the summary and writes no report.
The optional `onAnalysis(report)` callback receives the same report before validation.
`evidence` records recognized usage, dynamic-key protection and unresolved imports,
with environment, full module ID, relative file path and one-based line/column.
`unknown-namespace` records explicit namespace expressions that cannot be fully
resolved. Each route includes `unknownNamespaceSources` for reachable affected
modules, including shared boundaries, lazy dependencies, slots, and client bridges.
An empty list means no unknown expression was detected, not proof that all APIs or
dependencies were understood.
Namespace loading recognizes string literals, inline arrays/spreads of supported
values, and local/imported `const` string bindings. Const string aliases are followed
with a cycle guard. Parameters, defaults, function results, object properties and
arrays stored in variables remain unknown, even with literal types or `as const`.
No mutation/escape analysis, cross-function namespace forwarding, JSX prop tracking,
or route-policy trust exceptions are performed. Prefer a visible unknown result
over inferring runtime behavior.
## Custom translation APIs
Only official translation API names are built in. Register custom
wrappers with `adapters`, using source module paths relative to the Vite root and
zero-based argument indexes:
```ts
i18nAnalysisPlugin({
adapters: [
{ module: 'i18n/lib.client.ts', exportName: 'useTranslation', namespaceArgument: 0 },
{
module: 'app/route-metadata.ts',
exportName: 'getRouteMetadata',
namespaceArgument: 0,
selectorArgument: 1,
},
],
})
```
`selectorArgument` identifies the key/selector argument of a direct translation
adapter. Omit it for a hook/helper returning an object with a `t` function. Imports
are matched by resolved declarations, including aliases, namespace imports and
re-exports, rather than by function name alone. Named functions and function-valued
variables are supported. A registration is an explicit forwarding contract: the
registered implementation is not scanned for translation usage. Optional
`implementationFunctions` lists additional private forwarding functions in the
same module; other functions remain analyzed. Keep contract tests for registered
wrappers and update the configuration if their behavior changes.
Dify's registrations live in `web/vite.config.ts`, including the server hook's
private `getI18nConfig` and the locale-first `getTranslation` helper. The plugin
contains no Dify wrapper paths or names. Dynamic namespace arguments are diagnosed
at call sites and fail opted-in strict validation. Runtime route Providers are not
registered as adapters. This does not infer arbitrary wrapper implementations.
## Key matching
Key matching retains TypeScript selector and finite key types, direct selectors,
static object-map lookup, and syntactic template-prefix protection. Function bodies
are not executed to infer call results; keys returned by runtime helpers protect
the relevant namespace. This deliberately accepts fewer unused-key findings.
Unresolved import warnings focus on untraceable application source imports.
External packages, explicit node_modules paths, styles, Vite assets (including
query variants), server/client boundary markers and imports introduced only by
transforms are opaque analysis boundaries, not individual warnings. This does not
allow TypeScript to fall back to stale runtime files: blocked targets stay blocked.
Local imports rewritten to virtual or external targets still produce diagnostics.
Missing key or namespace information continues to use the normal conservative
fallbacks. No dependency implementations are scanned to classify their behavior.
An empty unresolved-import list does not imply complete dependency coverage.
A dynamic key can protect an entire namespace; these records explain which calls
prevent an unused-key conclusion.
`metrics` records combined environment setup, per-environment resolution, Program/checker setup,
semantic analysis and route traversal durations, plus module and resolver-call
counts. `totalMs` sums work for the final environment graphs and final analysis;
it excludes superseded scan graphs, output serialization and the rest of the build,
and is not wall-clock build duration when environments run concurrently.
Call-signature resolution is limited to overloaded or generic calls whose
parameters can expose a `SelectorParam` type. Ordinary object/function parameter
shapes do not require argument inference; deferred types (including type parameters,
conditional, indexed-access, union/intersection and mapped types) retain resolution.
Calls without arguments skip translation-function inference while explicit namespace
loading and traversal of their children remain unchanged.
Each environment's semantic analysis runs in a separate Node worker. Environments
run sequentially, and analysis waits for the worker to exit before starting the next
one, releasing its TypeScript Program and type state. Only plain analysis results
return to the build process; errors still fail the build. Worker startup and message
transfer are included in `totalMs`. This uses the repository's Node 24 TypeScript
support, so the worker's local imports have explicit `.ts` extensions.
Catalog, exact-key/plural indexes, wildcard matches and compiler options are shared
within each environment analysis. Import binding syntax is cached by complete source text within
one build, including across environments. Only plain binding data is cached, not
TypeScript ASTs, resolved targets or type state. Environment resolution stays independent,
and the syntax cache is discarded before semantic analysis, when the build ends,
or when a watch rebuild starts.
Runtime template prefixes are retained even when an assertion
widens the key to every property of a JSON catalog. Identical multi-format builds in the same open bundle reuse
analysis; changes to source, transformed code or graph edges invalidate that reuse.
Closing the bundle or starting a watch rebuild clears it. Programs and type state
are not cached across environments or independent builds.
## Opt-in route namespace validation
Pass `getDeclaredNamespaces(route)` to enable validation for selected route
subtrees. Returning `undefined` skips validation for that route; an empty array
means no namespaces are allowed. Any detected namespace outside the declaration
fails the production build, with the route, namespace, group and source file.
All four groups are checked, including lazy dependencies and parallel slots.
Set `strictNamespaces: true` to also fail declared routes whose
`unknownNamespaceSources` is nonempty. By default these routes emit an incomplete
analysis warning; unrelated unresolved imports do not automatically fail route
validation. Undeclared routes remain exempt from strict validation.
Explicit, statically resolved `useTranslation` / `getTranslation` namespace
arguments are included even when no translation key is consumed.
Dify does not currently enable this optional validation. Components load their
namespaces through the next-i18next Provider at render time, so there is no
exhaustive route allowlist. Route reports remain available for diagnostics and
preload investigations.
This validates statically detected usage, with the recognition and conservative
limitations described above. It does not prove that arbitrary runtime-generated
imports or unrecognized translation APIs stay within the declaration.
@@ -0,0 +1,118 @@
import path from 'node:path'
import * as ts from 'typescript'
export type TranslationAdapter = {
/** Source module path, relative to the Vite root. */
module: string
exportName: string
namespaceArgument: number
/** Omit for APIs returning a translation object with a t function. */
selectorArgument?: number
/** Additional private forwarding functions in the same source module. */
implementationFunctions?: readonly string[]
}
type TranslationApi =
| { kind: 'translation'; namespaceArgument: number; selectorArgument?: number }
| { kind: 'trans' }
function declarationIdentity(root: string, node: ts.Node) {
if (
(!ts.isFunctionDeclaration(node) && !ts.isVariableDeclaration(node)) ||
!node.name ||
!ts.isIdentifier(node.name)
)
return
return {
module: path.relative(root, node.getSourceFile().fileName).replaceAll('\\', '/'),
name: node.name.text,
}
}
export function createTranslationApiResolver(
root: string,
program: ts.Program,
adapters: readonly TranslationAdapter[],
) {
const checker = program.getTypeChecker()
const exportedAdapters = new Map<ts.Node, TranslationAdapter>()
for (const adapter of adapters) {
const source = program.getSourceFile(path.resolve(root, adapter.module))
const module = source && checker.getSymbolAtLocation(source)
const exported =
module &&
checker.getExportsOfModule(module).find((symbol) => symbol.name === adapter.exportName)
if (!exported) continue
const target =
exported.flags & ts.SymbolFlags.Alias ? checker.getAliasedSymbol(exported) : exported
for (const declaration of target.declarations ?? []) exportedAdapters.set(declaration, adapter)
}
function isAdapter(node: ts.Node) {
if (exportedAdapters.has(node)) return true
const identity = declarationIdentity(root, node)
return (
!!identity &&
adapters.some(
(adapter) =>
adapter.module === identity.module &&
adapter.implementationFunctions?.includes(identity.name),
)
)
}
const known = (name: string, module: string): TranslationApi | undefined => {
if (module !== 'react-i18next') return
if (name === 'useTranslation') return { kind: 'translation', namespaceArgument: 0 }
if (name === 'Trans') return { kind: 'trans' }
}
const cache = new Map<ts.Node, TranslationApi | undefined>()
function resolve(node: ts.Node, seen = new Set<ts.Node>()): TranslationApi | undefined {
if (cache.has(node)) return cache.get(node)
if (seen.has(node)) return
const next = new Set(seen).add(node)
const symbol = checker.getSymbolAtLocation(
ts.isPropertyAccessExpression(node) ? node.name : node,
)
const declarations = symbol?.declarations ?? []
for (const declaration of declarations) {
if (ts.isVariableDeclaration(declaration) && declaration.initializer) {
const api = resolve(declaration.initializer, next)
if (api) return api
}
}
if (symbol && symbol.flags & ts.SymbolFlags.Alias) {
for (const declaration of checker.getAliasedSymbol(symbol).declarations ?? []) {
const api = resolveDeclaration(declaration)
if (api) return api
if (ts.isVariableDeclaration(declaration) && declaration.initializer) {
const aliased = resolve(declaration.initializer, next)
if (aliased) return aliased
}
}
}
for (const declaration of declarations) {
const api = resolveDeclaration(declaration)
if (api) return api
}
}
function resolveDeclaration(declaration: ts.Declaration): TranslationApi | undefined {
const file = declaration.getSourceFile().fileName.replaceAll('\\', '/')
const identity = declarationIdentity(root, declaration)
const adapter = exportedAdapters.get(declaration)
if (adapter)
return {
kind: 'translation',
namespaceArgument: adapter.namespaceArgument,
selectorArgument: adapter.selectorArgument,
}
if (file.includes('/node_modules/react-i18next/') && identity)
return known(identity.name, 'react-i18next')
}
return {
isAdapter,
resolve(node: ts.Node) {
if (!cache.has(node)) cache.set(node, resolve(node))
return cache.get(node)
},
}
}
@@ -0,0 +1,50 @@
import fs from 'node:fs'
import path from 'node:path'
const PLURAL = /_(?:zero|one|two|few|many|other)$/
export const camelCase = (name: string) =>
name.replace(/[-_]+([a-z0-9])/gi, (_, char: string) => char.toUpperCase())
export function readTranslationCatalog(root: string) {
const directory = path.join(root, 'i18n/locales/en-US')
const catalog = new Map<string, Set<string>>()
const exact = new Map<string, Map<string, Set<string>>>()
for (const file of fs
.readdirSync(directory)
.filter((file) => file.endsWith('.json'))
.sort()) {
const content: unknown = JSON.parse(fs.readFileSync(path.join(directory, file), 'utf8'))
if (!content || typeof content !== 'object' || Array.isArray(content))
throw new Error(`Invalid translation catalog: ${file}`)
const namespace = camelCase(file.slice(0, -5))
const keys = new Set(Object.keys(content))
catalog.set(namespace, keys)
const index = new Map<string, Set<string>>()
for (const key of keys) {
for (const lookup of new Set([key, key.replace(PLURAL, '')])) {
const matches = index.get(lookup) ?? new Set<string>()
matches.add(key)
index.set(lookup, matches)
}
}
exact.set(namespace, index)
}
const patterns = new Map<string, Map<string, string[]>>()
return {
catalog,
match(namespace: string, text: string, wildcard: boolean): Iterable<string> {
if (!wildcard) return exact.get(namespace)?.get(text) ?? []
const cached = patterns.get(namespace) ?? new Map<string, string[]>()
let matches = cached.get(text)
if (!matches) {
const regex = new RegExp(`^${text}$`)
matches = [...(catalog.get(namespace) ?? [])].filter(
(key) => regex.test(key) || regex.test(key.replace(PLURAL, '')),
)
cached.set(text, matches)
patterns.set(namespace, cached)
}
return matches
},
}
}
@@ -0,0 +1,385 @@
import path from 'node:path'
import * as ts from 'typescript'
type ModuleResolution = { id: string | null; diagnostic: boolean }
export type ModuleResolutions = ReadonlyMap<string, ReadonlyMap<string, ModuleResolution>>
// Resolve in Vite's environment before creating the synchronous TypeScript host.
// Read surviving imports from Vite's transformed code so erased type imports
// never reach the runtime resolver. Only collected source modules override TS
// resolution; packages and type-only dependencies still use TS declarations.
type ImportBinding = { specifier: string; signature: string; typeOnly: boolean; locals: string[] }
function importBindings(code: string): ImportBinding[] {
const source = ts.createSourceFile(
'module.tsx',
code,
ts.ScriptTarget.Latest,
true,
ts.ScriptKind.TSX,
)
const result: ImportBinding[] = []
for (const statement of source.statements) {
if (ts.isImportDeclaration(statement) && ts.isStringLiteral(statement.moduleSpecifier)) {
const clause = statement.importClause
const bindings = clause?.namedBindings
const names =
bindings && ts.isNamedImports(bindings)
? bindings.elements
.filter((element) => !element.isTypeOnly)
.map(
(element) =>
`${element.propertyName?.text ?? element.name.text}:${element.name.text}`,
)
.sort()
: bindings && ts.isNamespaceImport(bindings)
? [`*:${bindings.name.text}`]
: []
result.push({
specifier: statement.moduleSpecifier.text,
signature: JSON.stringify(['import', clause?.name?.text, names]),
locals: [
...(clause?.name ? [clause.name.text] : []),
...(bindings && ts.isNamedImports(bindings)
? bindings.elements
.filter((element) => !element.isTypeOnly)
.map((element) => element.name.text)
: bindings
? [bindings.name.text]
: []),
],
typeOnly:
clause?.phaseModifier === ts.SyntaxKind.TypeKeyword ||
!!(
bindings &&
ts.isNamedImports(bindings) &&
bindings.elements.length &&
!names.length &&
!clause?.name
),
})
}
if (
ts.isExportDeclaration(statement) &&
statement.moduleSpecifier &&
ts.isStringLiteral(statement.moduleSpecifier)
) {
result.push({
specifier: statement.moduleSpecifier.text,
signature: JSON.stringify([
'export',
!statement.exportClause
? ['all']
: ts.isNamespaceExport(statement.exportClause)
? ['namespace', statement.exportClause.name.text]
: [
'named',
statement.exportClause.elements
.filter((element) => !element.isTypeOnly)
.map((element) =>
JSON.stringify([
(element.propertyName ?? element.name).text,
element.name.text,
]),
)
.sort(),
],
]),
locals: [],
typeOnly:
statement.isTypeOnly ||
!!(
statement.exportClause &&
ts.isNamedExports(statement.exportClause) &&
statement.exportClause.elements.length > 0 &&
statement.exportClause.elements.every((element) => element.isTypeOnly)
),
})
}
}
function visit(node: ts.Node) {
if (
ts.isCallExpression(node) &&
node.expression.kind === ts.SyntaxKind.ImportKeyword &&
node.arguments[0] &&
ts.isStringLiteralLike(node.arguments[0])
) {
const specifier = node.arguments[0].text
// Dynamic imports have no stable local binding after arbitrary transforms.
// Do not pair them by position: rewrites may reorder, split or inline calls.
result.push({
specifier,
signature: JSON.stringify(['dynamic', specifier]),
typeOnly: false,
locals: [],
})
}
ts.forEachChild(node, visit)
}
visit(source)
return result
}
export function createImportBindingReader() {
const cache = new Map<string, readonly ImportBinding[]>()
return (code: string) => {
let bindings = cache.get(code)
if (!bindings) {
bindings = importBindings(code)
cache.set(code, bindings)
}
return bindings
}
}
export function hasClientDirective(code: string) {
if (!code.includes('use client')) return false
const source = ts.createSourceFile(
'module.tsx',
code,
ts.ScriptTarget.Latest,
false,
ts.ScriptKind.TSX,
)
for (const statement of source.statements) {
if (!ts.isExpressionStatement(statement) || !ts.isStringLiteral(statement.expression)) break
if (statement.expression.text === 'use client') return true
}
return false
}
export async function resolveTranslationImports(
modules: ReadonlyMap<string, string>,
compiled: ReadonlyMap<string, string>,
resolve: (
specifier: string,
importer: string,
) => Promise<{ id: string; external?: boolean } | undefined>,
isAsset: (specifier: string) => boolean = () => false,
readBindings = createImportBindingReader(),
) {
const resolutions = new Map<string, Map<string, ModuleResolution>>()
let resolveCalls = 0
await Promise.all(
[...modules].map(async ([id, source]) => {
const imports = new Map<string, string | null>()
const code = compiled.get(id) ?? ''
const surviving = new Set(
ts.preProcessFile(code, true, true).importedFiles.map((file) => file.fileName),
)
const targets = new Map<string, string | undefined>()
const declarationImports = new Set<string>()
const externalImports = new Set<string>()
await Promise.all(
[...surviving].map(async (specifier) => {
resolveCalls++
const resolved = await resolve(specifier, id)
targets.set(specifier, resolved?.id)
if (
!/^[.#/]/.test(specifier) &&
!specifier.startsWith('@/') &&
(resolved?.external || resolved?.id.includes('/node_modules/'))
)
externalImports.add(specifier)
const packageName = specifier.startsWith('@')
? specifier.split('/').slice(0, 2).join('/')
: specifier.split('/')[0]!
// A bare external package or its resolved node_modules implementation
// may use TS declarations. Virtual/local replacements must not fall back.
if (
!/^[.#/]/.test(specifier) &&
!specifier.startsWith('@/') &&
(resolved?.id.includes(`/node_modules/${packageName}/`) ||
(resolved?.external && resolved.id === specifier))
)
declarationImports.add(specifier)
}),
)
for (const [specifier, target] of targets) {
if (target && modules.has(target)) imports.set(specifier, target)
else if (!declarationImports.has(specifier) && !isAsset(specifier))
imports.set(specifier, null)
}
const before = readBindings(source)
const after = readBindings(code)
const proposals = new Map<string, Set<string | null | undefined>>()
const record = (specifier: string, target: string | null | undefined) => {
const values = proposals.get(specifier) ?? new Set<string | null | undefined>()
values.add(target)
proposals.set(specifier, values)
}
for (const binding of before) {
if (binding.typeOnly || isAsset(binding.specifier)) continue
const sameBinding = (candidate: ImportBinding) =>
!candidate.typeOnly &&
candidate.specifier === binding.specifier &&
candidate.signature === binding.signature
const originalCount = before.filter(sameBinding).length
const survivingCount = after.filter(sameBinding).length
if (originalCount === survivingCount) {
record(binding.specifier, imports.get(binding.specifier))
continue
}
// Barrel optimizers may split named imports into per-binding default
// imports. Preserve TS declarations only if every binding still comes
// from the same external package; local rewrites remain strict.
const packageName = binding.specifier.startsWith('@')
? binding.specifier.split('/').slice(0, 2).join('/')
: binding.specifier.split('/')[0]!
const externalBindings =
!/^[.#/]/.test(binding.specifier) &&
!binding.specifier.startsWith('@/') &&
binding.locals.length > 0 &&
binding.locals.every((local) =>
after.some((candidate) => {
const target = targets.get(candidate.specifier)
return (
candidate.locals.includes(local) &&
target?.includes(`/node_modules/${packageName}/`) &&
!modules.has(target)
)
}),
)
if (externalBindings) {
record(binding.specifier, undefined)
continue
}
const candidates = after.filter(
(candidate) => !candidate.typeOnly && candidate.signature === binding.signature,
)
const replacement =
originalCount === 1 && candidates.length === 1
? targets.get(candidates[0]!.specifier)
: undefined
record(binding.specifier, replacement && modules.has(replacement) ? replacement : null)
}
// The TS host resolves by module specifier, not by import occurrence. If
// bindings using one specifier diverge, block all rather than use a stale target.
for (const [specifier, values] of proposals) {
if (values.size > 1 || values.has(null)) imports.set(specifier, null)
else {
const [target] = values
if (target !== undefined) imports.set(specifier, target)
else imports.delete(specifier)
}
}
// Resolution and diagnostics have different scopes: opaque dependencies
// still block stale disk fallback, but only source imports need warnings.
const sourceImports = new Set(
before.filter((binding) => !binding.typeOnly).map((binding) => binding.specifier),
)
resolutions.set(
id,
new Map(
[...imports].map(([specifier, target]) => [
specifier,
{
id: target,
diagnostic:
target === null &&
sourceImports.has(specifier) &&
!externalImports.has(specifier) &&
!specifier.includes('/node_modules/') &&
specifier !== 'server-only' &&
specifier !== 'client-only' &&
!/\.(?:css|scss|sass|less|styl)(?:\?|$)/.test(specifier) &&
!isAsset(specifier.split('?')[0]!),
},
]),
),
)
}),
)
return { resolutions, resolveCalls }
}
export function readCompilerOptions(root: string): ts.CompilerOptions {
const configPath = ts.findConfigFile(root, ts.sys.fileExists)
const config = configPath ? ts.readConfigFile(configPath, ts.sys.readFile) : undefined
if (config?.error)
throw new Error(ts.flattenDiagnosticMessageText(config.error.messageText, '\n'))
const options =
configPath && config
? ts.parseJsonConfigFileContent(
config.config,
{ ...ts.sys, readDirectory: () => [] },
path.dirname(configPath),
).options
: {}
return {
...options,
allowJs: true,
jsx: ts.JsxEmit.ReactJSX,
noEmit: true,
skipLibCheck: true,
}
}
export function createTranslationProgram(
root: string,
modules: ReadonlyMap<string, string>,
resolutions: ModuleResolutions,
compilerOptions = readCompilerOptions(root),
) {
// TypeScript needs recognizable extensions. Give query variants distinct,
// in-memory filenames in the same directory, retaining their Vite identities.
const fileNames = new Map<string, string>()
const moduleIds = new Map<string, string>()
const sources = new Map<string, string>()
for (const [id, source] of modules) {
const file = id.split('?')[0]!
let fileName = id.endsWith('.json') ? `${id}.__dify_i18n.ts` : id
if (id !== file) {
fileName = `${file}.__dify_i18n_${fileNames.size}${path.extname(file)}`
while (modules.has(fileName) || moduleIds.has(fileName))
fileName = `${fileName}${path.extname(file)}`
}
fileNames.set(id, fileName)
moduleIds.set(fileName, id)
sources.set(fileName, source)
}
const host = ts.createCompilerHost(compilerOptions)
const readFile = host.readFile.bind(host)
host.readFile = (file) => sources.get(file) ?? readFile(file)
const fileExists = host.fileExists.bind(host)
host.fileExists = (file) => sources.has(file) || fileExists(file)
const getSourceFile = host.getSourceFile.bind(host)
host.getSourceFile = (file, languageVersion, onError, shouldCreateNewSourceFile) => {
const source = sources.get(file)
return source === undefined
? getSourceFile(file, languageVersion, onError, shouldCreateNewSourceFile)
: ts.createSourceFile(file, source, languageVersion, true)
}
const cache = ts.createModuleResolutionCache(root, host.getCanonicalFileName, compilerOptions)
host.resolveModuleNameLiterals = (
literals,
containingFile,
redirectedReference,
options,
containingSourceFile,
) =>
literals.map((literal) => {
const importer = moduleIds.get(containingFile)
const resolvedId = importer && resolutions.get(importer)?.get(literal.text)?.id
if (resolvedId === null) return { resolvedModule: undefined }
const resolvedFileName = resolvedId && fileNames.get(resolvedId)
if (resolvedFileName) {
const extension = Object.values(ts.Extension).find((extension) =>
resolvedFileName.endsWith(extension),
)
return { resolvedModule: { resolvedFileName, extension: extension ?? ts.Extension.Ts } }
}
return ts.resolveModuleName(
literal.text,
containingFile,
options,
host,
cache,
redirectedReference,
ts.getModeForUsageLocation(containingSourceFile, literal, options),
)
})
const roots = [...fileNames].filter(([id]) => !id.endsWith('.json')).map(([, file]) => file)
const program = ts.createProgram(roots, compilerOptions, host)
return { program, fileNames }
}
@@ -0,0 +1,23 @@
import type { TranslationAdapter } from './api.ts'
import type { ModuleResolutions } from './compiler.ts'
import { parentPort, workerData } from 'node:worker_threads'
import { checkTranslationGraph, createAnalysisContext } from './graph.ts'
export type GraphWorkerInput = {
root: string
modules: ReadonlyMap<string, string>
resolutions: ModuleResolutions
adapters: readonly TranslationAdapter[]
}
export type GraphWorkerResult = ReturnType<typeof checkTranslationGraph> & { setupMs: number }
const { root, modules, resolutions, adapters } = workerData as GraphWorkerInput
const started = performance.now()
const context = createAnalysisContext(root, adapters)
const setupMs = performance.now() - started
const result: GraphWorkerResult = {
...checkTranslationGraph(root, modules, resolutions, context),
setupMs,
}
parentPort!.postMessage(result)
@@ -0,0 +1,722 @@
import type { TranslationAdapter } from './api.ts'
import type { ModuleResolutions } from './compiler.ts'
import path from 'node:path'
import * as ts from 'typescript'
import { createTranslationApiResolver } from './api.ts'
import { camelCase, readTranslationCatalog } from './catalog.ts'
import { createTranslationProgram, readCompilerOptions } from './compiler.ts'
const MAX_VALUES = 200
const escapeRegex = (text: string) => text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
type Translation = { namespaces: string[]; prefix: string; argument: number }
type Value = ts.Expression | ts.FunctionDeclaration
type Key = { text: string; wildcard?: boolean; namespace?: string }
function unwrap(node: ts.Expression): ts.Expression {
if (
ts.isParenthesizedExpression(node) ||
ts.isAsExpression(node) ||
ts.isTypeAssertionExpression(node) ||
ts.isNonNullExpression(node) ||
ts.isSatisfiesExpression(node) ||
ts.isAwaitExpression(node)
)
return unwrap(node.expression)
return node
}
function literalTypes(type: ts.Type): string[] | undefined {
if (type.isStringLiteral()) return [type.value]
if (type.isUnion()) {
const values: string[] = []
for (const member of type.types) {
if (member.flags & (ts.TypeFlags.Undefined | ts.TypeFlags.Null | ts.TypeFlags.Void)) continue
const literals = literalTypes(member)
if (!literals) return
values.push(...literals)
if (values.length > MAX_VALUES) return
}
return values.length ? [...new Set(values)] : undefined
}
}
function initializer(node: ts.Node): Value | undefined {
if (
ts.isVariableDeclaration(node) ||
ts.isPropertyAssignment(node) ||
ts.isParameter(node) ||
ts.isPropertyDeclaration(node)
)
return node.initializer
if (ts.isShorthandPropertyAssignment(node)) return node.name
if (ts.isFunctionDeclaration(node) && node.body) return node
}
export type AnalysisEvidence = {
kind: 'usage' | 'dynamic-key' | 'unresolved-import' | 'unknown-namespace'
moduleId: string
file: string
line: number
column: number
namespaces: string[]
message: string
import?: {
specifier: string
kind: 'style' | 'asset' | 'package' | 'virtual' | 'source'
origin: 'source' | 'generated'
}
}
export function createAnalysisContext(root: string, adapters: readonly TranslationAdapter[] = []) {
return {
adapters,
translations: readTranslationCatalog(root),
compilerOptions: readCompilerOptions(root),
}
}
// Only module IDs supplied by Vite are visited. Type dependencies inform static
// expressions but never contribute usage merely by existing on disk.
export function checkTranslationGraph(
root: string,
modules: ReadonlyMap<string, string>,
resolutions: ModuleResolutions = new Map(),
context = createAnalysisContext(root),
) {
const { catalog } = context.translations
const literalKeys = new Set([...catalog.values()].flatMap((keys) => [...keys]))
const programStarted = performance.now()
const { program, fileNames } = createTranslationProgram(
root,
modules,
resolutions,
context.compilerOptions,
)
const checker = program.getTypeChecker()
const programMs = performance.now() - programStarted
const analysisStarted = performance.now()
const { resolve: translationApi, isAdapter } = createTranslationApiResolver(
root,
program,
context.adapters,
)
const evidence = new Map<string, AnalysisEvidence>()
let currentModule = ''
let currentSite: ts.Node | undefined
function explain(
kind: AnalysisEvidence['kind'],
namespaces: string[],
message: string,
importInfo?: AnalysisEvidence['import'],
) {
if (!currentSite) return
const location = currentSite
.getSourceFile()
.getLineAndCharacterOfPosition(currentSite.getStart())
const item = {
kind,
moduleId: currentModule,
file: path.relative(root, currentModule.split('?')[0]!).replaceAll('\\', '/'),
line: location.line + 1,
column: location.character + 1,
namespaces: [...namespaces].sort(),
message,
...(importInfo ? { import: importInfo } : {}),
}
evidence.set(JSON.stringify(item), item)
}
const used = new Map<string, Set<string>>()
const protectedNamespaces = new Set<string>()
const moduleNamespaces = new Map<string, Set<string>>()
let currentNamespaces = new Set<string>()
function declarations(node: ts.Node): readonly ts.Declaration[] {
const symbol = checker.getSymbolAtLocation(node)
const local = symbol?.declarations ?? []
return symbol && symbol.flags & ts.SymbolFlags.Alias
? [...local, ...(checker.getAliasedSymbol(symbol).declarations ?? [])]
: local
}
function alternatives(expression: Value, seen = new Set<ts.Node>()): (Value | undefined)[] {
if (ts.isFunctionDeclaration(expression)) return [expression]
if (
(ts.isAsExpression(expression) || ts.isTypeAssertionExpression(expression)) &&
/I18nKeys(?:By|With)Prefix/.test(expression.type.getText())
)
return [expression]
const node = unwrap(expression)
if (seen.has(node)) return [undefined]
const next = new Set(seen).add(node)
if (ts.isConditionalExpression(node))
return [...alternatives(node.whenTrue, next), ...alternatives(node.whenFalse, next)]
if (ts.isIdentifier(node)) {
if (node.text === 'undefined') return []
const values = declarations(node)
.map(initializer)
.filter((value) => value !== undefined)
return values.length ? values.flatMap((value) => alternatives(value, next)) : [node]
}
if (ts.isPropertyAccessExpression(node) || ts.isElementAccessExpression(node)) {
const object = checker.getTypeAtLocation(node.expression)
const names = ts.isPropertyAccessExpression(node)
? [node.name.text]
: strings(node.argumentExpression)
const objects = alternatives(node.expression, next)
if (objects.some((value) => value && ts.isObjectLiteralExpression(value))) {
const select = (value: Value | undefined): (Value | undefined)[] => {
if (!value || !ts.isObjectLiteralExpression(value)) return [undefined]
return value.properties.flatMap((member) => {
if (ts.isSpreadAssignment(member))
return alternatives(member.expression, next).flatMap(select)
const memberNames =
member.name && ts.isComputedPropertyName(member.name)
? strings(member.name.expression)
: member.name
? [member.name.getText().replace(/^['"]|['"]$/g, '')]
: undefined
if (names && memberNames && !memberNames.some((name) => names.includes(name))) return []
const value = initializer(member)
return value ? alternatives(value, next) : [undefined]
})
}
return objects.flatMap(select)
}
const symbols = names ? names.map((name) => object.getProperty(name)) : object.getProperties()
const values = symbols.flatMap(
(symbol) => symbol?.declarations?.map(initializer) ?? [undefined],
)
// An open index signature can supply entries absent from the finite map.
if (!names && object.getStringIndexType()) values.push(undefined)
if (values.length)
return values.flatMap((value) => (value ? alternatives(value, next) : [undefined]))
}
return [node]
}
function strings(expression: ts.Expression | undefined): string[] | undefined {
if (!expression) return
const node = unwrap(expression)
if (ts.isStringLiteralLike(node)) return [node.text]
if (ts.isCallExpression(node)) return undefined
if (ts.isArrayLiteralExpression(node)) {
const values = node.elements.map((element) => strings(element))
return values.every((value) => value !== undefined) ? values.flat() : undefined
}
return literalTypes(checker.getTypeAtLocation(expression))
}
function property(
expression: ts.Expression | undefined,
name: string,
): ts.Expression | undefined {
if (!expression) return
const node = unwrap(expression)
if (!ts.isObjectLiteralExpression(node)) return
for (const member of node.properties) {
if (ts.isShorthandPropertyAssignment(member) && member.name.text === name) return member.name
if (
ts.isPropertyAssignment(member) &&
member.name.getText().replace(/^['"]|['"]$/g, '') === name
)
return member.initializer
}
}
function selectorType(type: ts.Type): ts.Type | undefined {
if (type.aliasSymbol?.getName() === 'SelectorParam') return type
const constraint = checker.getBaseConstraintOfType(type)
return constraint && constraint !== type ? selectorType(constraint) : undefined
}
function mayInstantiateSelector(type: ts.Type): boolean {
if (selectorType(type)) return true
// Instantiation can reduce these types to a selector alias. Keep them even
// when the declaration itself does not expose SelectorParam.
if (
type.flags &
(ts.TypeFlags.TypeParameter |
ts.TypeFlags.IndexedAccess |
ts.TypeFlags.Conditional |
ts.TypeFlags.Substitution |
ts.TypeFlags.UnionOrIntersection)
)
return true
// Ordinary object/function types retain their shape and alias when their
// type arguments are instantiated. Mapped types can instead reduce.
return !!(
type.flags & ts.TypeFlags.Object &&
(type as ts.ObjectType).objectFlags & (ts.ObjectFlags.Mapped | ts.ObjectFlags.ReverseMapped)
)
}
function typedTranslation(node: ts.Node, call?: ts.CallExpression): Translation | undefined {
const type = checker.getTypeAtLocation(node)
const brand = type.getProperty('$TFunctionBrand')
if (brand) {
const namespaces = literalTypes(checker.getTypeOfSymbolAtLocation(brand, node))
if (namespaces?.length) return { namespaces, prefix: '', argument: 0 }
}
// Prefer the instantiated namespace. Inferred selector functions can lose
// their alias, so retain declaration signatures for recognizing adapters.
const declared = type.getCallSignatures()
// Resolving a call checks its arguments and contextual types too. Only
// request that work if overload selection or generic instantiation could
// expose a selector parameter; unrelated generic APIs need neither.
const resolved =
call &&
(declared.length > 1 || declared.some((signature) => signature.typeParameters?.length)) &&
declared.some((signature) =>
signature.parameters.some((parameter) =>
mayInstantiateSelector(checker.getTypeOfSymbolAtLocation(parameter, node)),
),
)
? checker.getResolvedSignature(call)
: undefined
const signatures = [...(resolved ? [resolved] : []), ...declared]
for (const signature of signatures) {
for (const [argument, parameter] of signature.parameters.entries()) {
const selector = selectorType(checker.getTypeOfSymbolAtLocation(parameter, node))
if (!selector) continue
const namespaceType = selector.aliasTypeArguments?.[0]
const namespaces = namespaceType ? literalTypes(namespaceType) : undefined
return { namespaces: namespaces ?? [...catalog.keys()], prefix: '', argument }
}
}
}
function translation(
node: ts.Expression,
call?: ts.CallExpression,
seen = new Set<ts.Node>(),
): Translation | undefined {
if (seen.has(node)) return
seen.add(node)
for (const declaration of declarations(
ts.isPropertyAccessExpression(node) ? node.name : node,
)) {
if (
ts.isBindingElement(declaration) &&
(declaration.propertyName ?? declaration.name).getText() === 't'
) {
const variable = declaration.parent.parent
if (ts.isParameter(variable))
return typedTranslation(node, call) ?? { namespaces: ['app'], prefix: '', argument: 0 }
if (ts.isVariableDeclaration(variable) && variable.initializer) {
const call = unwrap(variable.initializer)
if (ts.isCallExpression(call)) {
const api = translationApi(call.expression)
if (api?.kind === 'translation' && api.selectorArgument === undefined) {
const nsIndex = api.namespaceArgument
return {
namespaces:
(call.arguments[nsIndex] && namespaceStrings(call.arguments[nsIndex]!)) ??
(call.arguments[nsIndex] ? [...catalog.keys()] : ['app']),
prefix: strings(property(call.arguments[nsIndex + 1], 'keyPrefix'))?.[0] ?? '',
argument: 0,
}
}
}
}
}
if (
ts.isImportSpecifier(declaration) &&
(declaration.propertyName ?? declaration.name).text === 't'
) {
const importDeclaration = declaration.parent.parent.parent
if (
ts.isImportDeclaration(importDeclaration) &&
ts.isStringLiteral(importDeclaration.moduleSpecifier) &&
importDeclaration.moduleSpecifier.text === 'i18next'
)
return { namespaces: ['app'], prefix: '', argument: 0 }
}
if (ts.isParameter(declaration)) {
const match = declaration.type?.getText().match(/TFunction\s*<\s*['"]([^'"]+)/)
if (match) return { namespaces: [match[1]!], prefix: '', argument: 0 }
const typed = typedTranslation(node, call)
if (typed) return typed
if (declaration.name.getText() === 't')
return { namespaces: ['app'], prefix: '', argument: 0 }
}
if (ts.isVariableDeclaration(declaration) && declaration.initializer) {
const alias = translation(unwrap(declaration.initializer), call, seen)
if (alias) return alias
}
}
const typed = typedTranslation(node, call)
if (typed) return typed
if (ts.isPropertyAccessExpression(node) && node.name.text === 't')
return { namespaces: ['app'], prefix: '', argument: 0 }
}
function keyPatterns(expression: ts.Expression): Key[] {
const node = unwrap(expression)
if (ts.isCallExpression(node)) return [{ text: '.*', wildcard: true }]
if (ts.isIdentifier(node)) {
const values = alternatives(node)
if (
values.some((value) => value !== node) &&
values.some(
(value) =>
value && !ts.isFunctionDeclaration(value) && ts.isTemplateExpression(unwrap(value)),
)
) {
return values.flatMap((value) =>
value && !ts.isFunctionDeclaration(value)
? keyPatterns(value)
: [{ text: '.*', wildcard: true }],
)
}
}
const values = ts.isTemplateExpression(node) ? undefined : strings(expression)
if (values) return values.map((text) => ({ text }))
if (
(ts.isAsExpression(expression) || ts.isTypeAssertionExpression(expression)) &&
ts.isTypeReferenceNode(expression.type) &&
/I18nKeys(?:By|With)Prefix$/.test(expression.type.typeName.getText())
) {
const prefix = expression.type.typeArguments?.[1]
if (prefix && ts.isLiteralTypeNode(prefix) && ts.isStringLiteral(prefix.literal))
return [{ text: `${escapeRegex(prefix.literal.text)}.*`, wildcard: true }]
}
if (ts.isTemplateExpression(node)) {
let patterns = [escapeRegex(node.head.text)]
for (const span of node.templateSpans) {
const values = strings(span.expression)?.map(escapeRegex) ?? ['.*']
if (patterns.length * values.length > MAX_VALUES) return [{ text: '.*', wildcard: true }]
patterns = patterns.flatMap((prefix) =>
values.map((value) => prefix + value + escapeRegex(span.literal.text)),
)
}
return patterns.map((text) => ({ text, wildcard: true }))
}
if (ts.isBinaryExpression(node) && node.operatorToken.kind === ts.SyntaxKind.PlusToken) {
const left = keyPatterns(node.left)
const right = keyPatterns(node.right)
if (left.length * right.length > MAX_VALUES) return [{ text: '.*', wildcard: true }]
return left.flatMap((a) =>
right.map((b) => ({
text:
(a.wildcard ? a.text : escapeRegex(a.text)) +
(b.wildcard ? b.text : escapeRegex(b.text)),
wildcard: true,
})),
)
}
return [{ text: '.*', wildcard: true }]
}
function selectorKeys(
node: ts.ArrowFunction | ts.FunctionExpression | ts.FunctionDeclaration,
): Key[] {
const source = node.parameters[0]?.name
if (!source || !node.body) return [{ text: '.*', wildcard: true }]
const returns: ts.Expression[] = []
if (ts.isBlock(node.body)) {
const visit = (child: ts.Node) => {
if (ts.isReturnStatement(child) && child.expression) returns.push(child.expression)
else if (!ts.isFunctionLike(child)) ts.forEachChild(child, visit)
}
ts.forEachChild(node.body, visit)
} else returns.push(node.body)
const access = (expression: ts.Expression): Key[] => {
const value = unwrap(expression)
if (ts.isConditionalExpression(value))
return [...access(value.whenTrue), ...access(value.whenFalse)]
const chain: (ts.Expression | string)[] = []
let current = value
while (ts.isPropertyAccessExpression(current) || ts.isElementAccessExpression(current)) {
chain.unshift(
ts.isPropertyAccessExpression(current) ? current.name.text : current.argumentExpression,
)
current = unwrap(current.expression)
}
if (current.getText() !== source.getText() || !chain.length)
return [{ text: '.*', wildcard: true }]
const key = chain.at(-1)!
const keys = typeof key === 'string' ? [{ text: key }] : keyPatterns(key)
if (chain.length === 1) return keys
const namespacePart = chain[0]!
const namespaces =
typeof namespacePart === 'string' ? [namespacePart] : strings(namespacePart)
if (!namespaces?.length) return [{ text: '.*', wildcard: true, namespace: '*' }]
return namespaces.flatMap((namespace) => keys.map((key) => ({ ...key, namespace })))
}
return returns.length ? returns.flatMap(access) : [{ text: '.*', wildcard: true }]
}
function record(keys: Key[], info: Translation) {
for (const key of keys) {
const separator = key.text.indexOf(':')
const namespaces = key.namespace
? key.namespace === '*'
? [...catalog.keys()]
: [key.namespace]
: separator > 0
? key.wildcard
? [...catalog.keys()].filter((namespace) =>
new RegExp(`^${key.text.slice(0, separator)}$`).test(namespace),
)
: [key.text.slice(0, separator)]
: info.namespaces
const text = separator > 0 && !key.namespace ? key.text.slice(separator + 1) : key.text
for (const rawNamespace of namespaces) {
const namespace = camelCase(rawNamespace)
currentNamespaces.add(namespace)
if (!catalog.has(namespace)) continue
if (key.wildcard && text === '.*' && !info.prefix) {
protectedNamespaces.add(namespace)
explain(
'dynamic-key',
[namespace],
'The key cannot be narrowed; every key in this namespace is protected.',
)
continue
}
const prefix = info.prefix ? `${info.prefix}.` : ''
const kept = used.get(namespace) ?? new Set<string>()
const matches = context.translations.match(
namespace,
key.wildcard ? `${escapeRegex(prefix)}${text}` : prefix + text,
!!key.wildcard,
)
for (const candidate of matches) kept.add(candidate)
explain(
'usage',
[namespace],
key.wildcard ? `Static key pattern: ${prefix}${text}` : `Static key: ${prefix}${text}`,
)
used.set(namespace, kept)
}
}
}
function consume(expression: ts.Expression, info: Translation) {
// Typed forwarding adapters are checked at their concrete call sites.
if (
ts.isIdentifier(expression) &&
selectorType(checker.getTypeAtLocation(expression)) &&
declarations(expression).some(ts.isParameter)
)
return
for (const value of alternatives(expression)) {
if (
value &&
(ts.isArrowFunction(value) ||
ts.isFunctionExpression(value) ||
ts.isFunctionDeclaration(value))
) {
record(selectorKeys(value), info)
} else {
record(value ? keyPatterns(value) : [{ text: '.*', wildcard: true }], info)
}
}
}
// Namespace values are deliberately narrower than key/type matching. Only
// inline arrays and immutable string bindings are concrete loading evidence.
function namespaceValues(
expression: ts.Expression,
seen = new Set<ts.Node>(),
allowArray = true,
): { namespaces: string[]; unknown: boolean } {
const unknown = { namespaces: [], unknown: true }
const node = unwrap(expression)
if (seen.has(node)) return unknown
const next = new Set(seen).add(node)
if (ts.isStringLiteralLike(node)) return { namespaces: [node.text], unknown: false }
if (allowArray && ts.isArrayLiteralExpression(node)) {
const values = node.elements.map((element) => namespaceValues(element, next))
return {
namespaces: values.flatMap((value) => value.namespaces),
unknown: values.some((value) => value.unknown),
}
}
if (allowArray && ts.isSpreadElement(node)) return namespaceValues(node.expression, next)
if (
!ts.isIdentifier(node) &&
!ts.isPropertyAccessExpression(node) &&
!ts.isElementAccessExpression(node)
)
return unknown
const values = declarations(node).filter(ts.isVariableDeclaration)
if (!values.length) return unknown
const resolved = values.map((declaration) =>
ts.isVariableDeclarationList(declaration.parent) &&
declaration.parent.flags & ts.NodeFlags.Const &&
declaration.initializer
? namespaceValues(declaration.initializer, next, false)
: unknown,
)
return {
namespaces: resolved.flatMap((value) => value.namespaces),
unknown: resolved.some((value) => value.unknown),
}
}
function namespaceStrings(expression: ts.Expression): string[] {
const { namespaces, unknown } = namespaceValues(expression)
// Unknown values may select any catalog namespace. Preserve known values
// outside the catalog too, so route validation still sees those requests.
return unknown ? [...new Set([...namespaces, ...catalog.keys()])] : namespaces
}
function recordLoadedNamespaces(expression: ts.Expression): boolean {
const { namespaces, unknown } = namespaceValues(expression)
for (const namespace of namespaces) {
currentNamespaces.add(namespace)
explain('usage', [namespace], 'Explicit namespace load.')
}
return !unknown
}
function visit(node: ts.Node) {
if (isAdapter(node)) return
currentSite = node
// Contextual key unions can only contribute usage when the literal itself
// exists in a catalog. Avoid type-checking unrelated paths, URLs and text.
if (
ts.isStringLiteralLike(node) &&
(node.text.includes('.') || node.text.includes(':')) &&
literalKeys.has(node.text)
) {
const contextual = checker.getContextualType(node)
const values = contextual && literalTypes(contextual)
if (values?.includes(node.text)) {
const namespaces = [...catalog]
.filter(([, keys]) => values.every((value) => keys.has(value)))
.map(([namespace]) => namespace)
if (namespaces.length)
record([{ text: node.text }], { namespaces, prefix: '', argument: 0 })
}
}
if (ts.isCallExpression(node)) {
currentSite = node
const api = translationApi(node.expression)
if (api?.kind === 'translation') {
// Explicit loading requests matter even when their t function is unused.
// Do not mark translation keys as used merely because a namespace loads.
const nsIndex = api.namespaceArgument
const argument = node.arguments[nsIndex]
if (argument && !recordLoadedNamespaces(argument))
explain(
'unknown-namespace',
[],
'Only literal namespaces, inline arrays and const string bindings are resolved; runtime values remain unknown.',
)
}
const info =
api?.kind === 'translation' && api.selectorArgument !== undefined
? {
namespaces: (node.arguments[api.namespaceArgument] &&
namespaceStrings(node.arguments[api.namespaceArgument]!)) || [...catalog.keys()],
prefix: '',
argument: api.selectorArgument,
}
: node.arguments.length
? translation(node.expression, node)
: undefined
const argument = info && node.arguments[info.argument]
if (info && argument) {
const options =
api?.kind === 'translation' && api.selectorArgument !== undefined
? undefined
: node.arguments.at(-1)
const namespaceOption = property(options, 'ns')
const namespaces = namespaceOption && namespaceStrings(namespaceOption)
if (namespaceOption && namespaceValues(namespaceOption).unknown)
explain(
'unknown-namespace',
[],
'The translation namespace cannot be narrowed to finite values.',
)
consume(argument, {
...info,
namespaces: namespaces ?? (namespaceOption ? [...catalog.keys()] : info.namespaces),
})
}
}
if (
(ts.isJsxSelfClosingElement(node) || ts.isJsxOpeningElement(node)) &&
translationApi(node.tagName)?.kind === 'trans'
) {
currentSite = node
const attributes = new Map<string, ts.Expression>()
for (const attribute of node.attributes.properties) {
if (!ts.isJsxAttribute(attribute) || !attribute.initializer) continue
const value = ts.isJsxExpression(attribute.initializer)
? attribute.initializer.expression
: attribute.initializer
if (value) attributes.set(attribute.name.getText(), value)
}
const key = attributes.get('i18nKey')
if (attributes.has('ns') && namespaceValues(attributes.get('ns')!).unknown)
explain('unknown-namespace', [], 'The Trans namespace cannot be narrowed to finite values.')
if (key)
consume(key, {
namespaces:
(attributes.get('ns') && namespaceStrings(attributes.get('ns')!)) ??
(attributes.has('ns') ? [...catalog.keys()] : ['app']),
prefix: '',
argument: 0,
})
}
ts.forEachChild(node, visit)
}
for (const id of modules.keys()) {
if (id.endsWith('.json')) continue
currentModule = id
const source = program.getSourceFile(fileNames.get(id)!)
currentNamespaces = new Set<string>()
moduleNamespaces.set(id, currentNamespaces)
if (source) {
const sourceImports = new Set(
ts.preProcessFile(source.text, true, true).importedFiles.map((item) => item.fileName),
)
for (const [specifier, resolved] of resolutions.get(id) ?? []) {
if (!resolved.diagnostic) continue
currentSite =
source.statements.find(
(statement) =>
ts.isImportDeclaration(statement) &&
ts.isStringLiteral(statement.moduleSpecifier) &&
statement.moduleSpecifier.text === specifier,
) ?? source
explain(
'unresolved-import',
[],
`Cannot trace runtime import ${specifier} after transforms; the original file was not used as a fallback.`,
{
specifier,
kind: /\.(?:css|scss|sass|less|styl)(?:\?|$)|vite-rsc\/css/.test(specifier)
? 'style'
: /\.(?:svg|png|jpe?g|webp|gif|ico|woff2?)(?:\?|$)/.test(specifier)
? 'asset'
: specifier.startsWith('\0') || specifier.startsWith('virtual:')
? 'virtual'
: specifier.includes('/node_modules/') ||
/^(?:@[^/]+\/[^/]+|[\w-]+)(?:\/|$)/.test(specifier)
? 'package'
: 'source',
origin: sourceImports.has(specifier) ? 'source' : 'generated',
},
)
}
visit(source)
}
}
const unused: Record<string, string[]> = {}
for (const [namespace, keys] of catalog) {
if (protectedNamespaces.has(namespace)) continue
const missing = [...keys].filter((key) => !used.get(namespace)?.has(key)).sort()
if (missing.length) unused[namespace] = missing
}
return {
unused,
evidence: [...evidence.values()],
timings: { programMs, analysisMs: performance.now() - analysisStarted },
protectedNamespaces: [...protectedNamespaces].sort(),
moduleNamespaces,
}
}
@@ -0,0 +1,312 @@
import path from 'node:path'
export type ModuleDependencies = { static: Set<string>; dynamic: Set<string> }
export type ModuleLocation = { environment: string; moduleId: string }
type NamespaceSources = {
namespace: string
sources: string[]
dependencyPaths?: number[]
}
export type RouteNamespaceReport = {
route: string
page: string
namespaces: string[]
unknownNamespaceSources?: string[]
groups: Record<'page' | 'shared' | 'lazy' | 'slots', NamespaceSources[]>
}
export function validateRouteNamespaces(
routes: readonly RouteNamespaceReport[],
getDeclaredNamespaces: (route: string) => readonly string[] | undefined,
strictNamespaces = false,
) {
const violations: string[] = []
for (const report of routes) {
const declared = getDeclaredNamespaces(report.route)
if (declared === undefined) continue
const missing = report.namespaces.filter((namespace) => !declared.includes(namespace))
const unknown = strictNamespaces ? (report.unknownNamespaceSources ?? []) : []
if (!missing.length && !unknown.length) continue
violations.push(
` ${report.route} (${report.page})`,
` Declared: ${declared.join(', ') || '(none)'}`,
)
for (const source of unknown) violations.push(` Cannot verify namespace usage: ${source}`)
for (const namespace of missing) {
violations.push(` Undeclared namespace: ${namespace}`)
for (const [group, entries] of Object.entries(report.groups)) {
for (const source of entries.find((entry) => entry.namespace === namespace)?.sources ?? [])
violations.push(` [${group}] ${source}`)
}
}
}
if (violations.length) {
throw new Error(
[
'Route namespace declarations do not cover statically detected usage:',
...violations,
'Remove the dependency or update the route namespace declaration after reviewing its usage.',
'Includes shared boundaries, dynamic imports and conservative parallel-slot additions; inspect the reported sources before changing declarations.',
].join('\n'),
)
}
}
// Use resolved build edges (including virtual modules), not an independent
// resolver which could disagree with aliases, exports or environment conditions.
export function analyzeRouteNamespaces(
root: string,
dependencies: ReadonlyMap<string, ModuleDependencies>,
usage: ReadonlyMap<string, ReadonlySet<string>>,
options: {
sourcePath?: (id: string) => string
entries?: ReadonlySet<string>
unknownNamespaces?: ReadonlySet<string>
recordPath?: (id: string, parent: number | null) => number
} = {},
): RouteNamespaceReport[] {
const sourcePath = (id: string) => (options.sourcePath?.(id) ?? id).split('?')[0]!
const app = `${root.replaceAll('\\', '/')}/app/`
const files = [...usage.keys()].filter(
(file) => sourcePath(file).startsWith(app) && (!options.entries || options.entries.has(file)),
)
const boundaries = files.filter((file) =>
/\/(?:layout|template|loading|error|not-found|global-error)\.[jt]sx?$/.test(sourcePath(file)),
)
const reachability = new Map<
string,
{ modules: Set<string>; parents: Map<string, string | null> }
>()
return files
.filter((file) => /\/page\.[jt]sx?$/.test(sourcePath(file)))
.sort()
.map((page) => {
const segments = sourcePath(page).slice(app.length).split('/').slice(0, -1)
const route = `/${segments.filter((segment) => !/^\([^)]*\)$/.test(segment) && !segment.startsWith('@')).join('/')}`
const ancestors = new Set([app.slice(0, -1)])
for (let i = 1; i <= segments.length; i++) ancestors.add(app + segments.slice(0, i).join('/'))
const sharedEntries = boundaries.filter((file) =>
ancestors.has(path.posix.dirname(sourcePath(file))),
)
const slotEntries: string[] = []
// Parallel slots can retain previously active pages on navigation.
for (const file of files) {
const parts = sourcePath(file).slice(app.length).split('/')
if (
parts.some(
(part, index) =>
part.startsWith('@') &&
ancestors.has(index ? app + parts.slice(0, index).join('/') : app.slice(0, -1)),
)
)
slotEntries.push(file)
}
function reachable(entries: string[], includeDynamic: boolean, cache = false) {
const key = JSON.stringify([includeDynamic, [...entries].sort()])
const cached = cache && reachability.get(key)
if (cached) return cached
const visited = new Set<string>()
const pending = [...entries]
const parents = new Map<string, string | null>(entries.map((id) => [id, null]))
for (let cursor = 0; cursor < pending.length; cursor++) {
const id = pending[cursor]!
if (visited.has(id)) continue
visited.add(id)
const imports = dependencies.get(id)
for (const dependency of [
...(imports?.static ?? []),
...(includeDynamic ? (imports?.dynamic ?? []) : []),
]) {
if (parents.has(dependency)) continue
parents.set(dependency, id)
pending.push(dependency)
}
}
const result = { modules: visited, parents }
if (cache) reachability.set(key, result)
return result
}
function sources(
modules: Set<string>,
parents: Map<string, string | null>,
): NamespaceSources[] {
const paths = new Map<string, Set<number>>()
const recorded = new Map<string, number>()
function recordPath(id: string): number {
const existing = recorded.get(id)
if (existing !== undefined) return existing
const parent = parents.get(id)
const index = options.recordPath!(id, parent ? recordPath(parent) : null)
recorded.set(id, index)
return index
}
const byNamespace = new Map<string, Set<string>>()
for (const id of modules) {
for (const namespace of usage.get(id) ?? []) {
const files = byNamespace.get(namespace) ?? new Set<string>()
files.add(path.posix.relative(root.replaceAll('\\', '/'), sourcePath(id)))
byNamespace.set(namespace, files)
if (options.recordPath) {
const entries = paths.get(namespace) ?? new Set<number>()
entries.add(recordPath(id))
paths.set(namespace, entries)
}
}
}
return [...byNamespace]
.sort(([a], [b]) => a.localeCompare(b))
.map(([namespace, files]) => ({
namespace,
sources: [...files].sort(),
...(options.recordPath ? { dependencyPaths: [...(paths.get(namespace) ?? [])] } : {}),
}))
}
const pageModules = reachable([page], false)
const sharedModules = reachable(sharedEntries, false, true)
const mainModules = reachable([page, ...sharedEntries], true)
const lazyModules = new Set(
[...mainModules.modules].filter(
(id) => !pageModules.modules.has(id) && !sharedModules.modules.has(id),
),
)
const slots = reachable(slotEntries, true, true)
const slotModules = new Set([...slots.modules].filter((id) => !mainModules.modules.has(id)))
const groups = {
page: sources(pageModules.modules, pageModules.parents),
shared: sources(sharedModules.modules, sharedModules.parents),
lazy: sources(lazyModules, mainModules.parents),
slots: sources(slotModules, slots.parents),
}
const namespaces = new Set(
Object.values(groups).flatMap((group) => group.map((item) => item.namespace)),
)
return {
// Keep interception segments visible; their URL depends on navigation.
route,
page: sourcePath(page).slice(root.replaceAll('\\', '/').length + 1),
namespaces: [...namespaces].sort(),
groups,
...(options.unknownNamespaces
? {
unknownNamespaceSources: [
...new Set(
[...mainModules.modules, ...slotModules]
.filter((id) => options.unknownNamespaces!.has(id))
.map((id) => path.posix.relative(root.replaceAll('\\', '/'), sourcePath(id))),
),
].sort(),
}
: {}),
}
})
}
export type EnvironmentUsage = {
dependencies: ReadonlyMap<string, ModuleDependencies>
usage: ReadonlyMap<string, ReadonlySet<string>>
clientReferences: ReadonlySet<string>
unknownNamespaces?: ReadonlySet<string>
}
export function analyzeEnvironmentRoutes(
root: string,
environments: ReadonlyMap<string, EnvironmentUsage>,
) {
const modules: ModuleLocation[] = []
const moduleIndexes = new Map<string, number>()
const paths: [module: number, parent: number | null][] = []
const pathIndexes = new Map<string, number>()
function recordPath(id: string, parent: number | null) {
let module = moduleIndexes.get(id)
if (module === undefined) {
const [environment, moduleId] = JSON.parse(id) as [string, string]
module = modules.length
modules.push({ environment, moduleId })
moduleIndexes.set(id, module)
}
const key = `${module}:${parent}`
let index = pathIndexes.get(key)
if (index === undefined) {
index = paths.length
paths.push([module, parent])
pathIndexes.set(key, index)
}
return index
}
const key = (environment: string, id: string) => JSON.stringify([environment, id])
const sourcePaths = new Map<string, string>()
const dependencies = new Map<string, ModuleDependencies>()
const usage = new Map<string, ReadonlySet<string>>()
const unknownNamespaces = new Set<string>()
for (const [environment, graph] of environments) {
for (const id of graph.unknownNamespaces ?? []) unknownNamespaces.add(key(environment, id))
for (const [id, namespaces] of graph.usage) {
const identity = key(environment, id)
usage.set(identity, namespaces)
sourcePaths.set(identity, id)
}
for (const [id, edges] of graph.dependencies) {
const identity = key(environment, id)
sourcePaths.set(identity, id)
const imports = {
static: new Set([...edges.static].map((id) => key(environment, id))),
dynamic: new Set([...edges.dynamic].map((id) => key(environment, id))),
}
// RSC imports a client reference stub. Only this explicit boundary may
// cross into the corresponding SSR and browser implementations.
if (environment === 'rsc' && graph.clientReferences.has(id)) {
for (const target of ['ssr', 'client']) {
if (environments.get(target)?.usage.has(id)) imports.static.add(key(target, id))
}
}
dependencies.set(identity, imports)
}
}
const reports = new Map<string, RouteNamespaceReport>()
for (const [environment, graph] of environments) {
const entries = new Set([...graph.usage.keys()].map((id) => key(environment, id)))
for (const report of analyzeRouteNamespaces(root, dependencies, usage, {
entries,
sourcePath: (id) => sourcePaths.get(id) ?? id,
recordPath,
unknownNamespaces,
})) {
const previous = reports.get(report.page)
if (!previous) {
reports.set(report.page, report)
continue
}
previous.unknownNamespaceSources = [
...new Set([
...(previous.unknownNamespaceSources ?? []),
...(report.unknownNamespaceSources ?? []),
]),
].sort()
previous.namespaces = [...new Set([...previous.namespaces, ...report.namespaces])].sort()
for (const group of ['page', 'shared', 'lazy', 'slots'] as const) {
const byNamespace = new Map<string, Set<string>>()
const paths = new Map<string, Set<number>>()
for (const item of [...previous.groups[group], ...report.groups[group]]) {
const chains = paths.get(item.namespace) ?? new Set<number>()
for (const chain of item.dependencyPaths ?? []) chains.add(chain)
paths.set(item.namespace, chains)
const sources = byNamespace.get(item.namespace) ?? new Set<string>()
for (const source of item.sources) sources.add(source)
byNamespace.set(item.namespace, sources)
}
previous.groups[group] = [...byNamespace]
.sort(([a], [b]) => a.localeCompare(b))
.map(([namespace, sources]) => ({
namespace,
sources: [...sources].sort(),
dependencyPaths: [...(paths.get(namespace) ?? [])],
}))
}
}
}
return {
routes: [...reports.values()].sort((a, b) => a.page.localeCompare(b.page)),
modules,
paths,
}
}
@@ -0,0 +1,19 @@
import type { GraphWorkerInput, GraphWorkerResult } from './graph-worker.ts'
import { Worker } from 'node:worker_threads'
export function analyzeGraphInWorker(input: GraphWorkerInput): Promise<GraphWorkerResult> {
return new Promise((resolve, reject) => {
const worker = new Worker(new URL('./graph-worker.ts', import.meta.url), { workerData: input })
let result: GraphWorkerResult | undefined
worker.once('message', (message: GraphWorkerResult) => {
result = message
})
worker.once('error', reject)
worker.once('exit', (code) => {
// Wait for the isolate to exit, not just its message, so its TypeScript
// program and type state are released before the next environment starts.
if (code === 0 && result) resolve(result)
else reject(new Error(`i18n graph analysis worker exited without a result (code ${code})`))
})
})
}
@@ -0,0 +1,7 @@
import path from 'node:path'
const rootClientInjectTargetRelativePath = 'instrumentation-client.ts'
export const getRootClientInjectTarget = (projectRoot: string): string => {
return path.resolve(projectRoot, rootClientInjectTargetRelativePath)
}
@@ -0,0 +1,30 @@
import type { Plugin } from 'vite'
import path from 'node:path'
import { normalizeViteModuleId } from './utils.ts'
type NextStaticImageTestPluginOptions = {
projectRoot: string
}
const STATIC_ASSET_RE = /\.(?:svg|png|jpe?g|gif)$/i
const EXCLUDED_QUERY_RE = /[?&](?:raw|url)\b/
export const nextStaticImageTestPlugin = ({
projectRoot,
}: NextStaticImageTestPluginOptions): Plugin => {
return {
name: 'next-static-image-test',
enforce: 'pre',
load(id) {
if (EXCLUDED_QUERY_RE.test(id)) return null
const cleanId = normalizeViteModuleId(id)
if (!cleanId.startsWith(projectRoot) || !STATIC_ASSET_RE.test(cleanId)) return null
const relativePath = path.relative(projectRoot, cleanId).split(path.sep).join('/')
const src = `/__static__/${relativePath}`
return `export default { src: ${JSON.stringify(src)} }\n`
},
}
}
+17
View File
@@ -0,0 +1,17 @@
export const normalizeViteModuleId = (id: string): string => {
const withoutQuery = id.split('?', 1)[0]!
if (withoutQuery!.startsWith('/@fs/')) return withoutQuery!.slice('/@fs'.length)
return withoutQuery
}
export const injectClientSnippet = (code: string, marker: string, snippet: string): string => {
if (code.includes(marker)) return code
const useClientMatch = code.match(/(['"])use client\1;?\s*\n/)
if (!useClientMatch) return `${snippet}\n${code}`
const insertAt = (useClientMatch.index ?? 0) + useClientMatch[0].length
return `${code.slice(0, insertAt)}\n${snippet}\n${code.slice(insertAt)}`
}