@doweljs/vite 0.0.0-stage → 0.1.0

package/src/analysis/registry.ts

@@ -0,0 +1,239 @@
+/**
+ * The project-wide graph assembled from per-module analyses.
+ *
+ * Nodes are identified by `kind:name`. Names are unique the way the runtime
+ * requires: scopes share one name space, and slots, services and executions
+ * share another. Dependency references are resolved through each module's
+ * imports and re-exports, so edges cross module boundaries and barrels.
+ */
+
+import type { Declaration, ModuleAnalysis, Ref } from './analyze.ts'
+
+export interface GraphEdge {
+	readonly key: string
+	/** Target node id, or null when the reference could not be resolved statically. */
+	readonly target: string | null
+	readonly optional: boolean
+}
+
+export interface GraphNode {
+	readonly id: string
+	readonly kind: 'slot' | 'service' | 'scope' | 'execution'
+	readonly name: string
+	/** The scope's name when known statically, or null when it is inferred at runtime. */
+	readonly scope: string | null
+	/** For scopes: the parent scope's node id. */
+	readonly parent: string | null
+	/** Whether a slot is a multi-binding; null when its options cannot be read statically. */
+	readonly many: boolean | null
+	readonly module: string
+	readonly local: string
+	/** Offsets of the declaration in the code the plugin received, after earlier transforms. */
+	readonly start: number
+	readonly end: number
+	readonly deps: readonly GraphEdge[]
+}
+
+export interface Duplicate {
+	/** The name, prefixed with `scope ` for scopes. */
+	readonly id: string
+	/** Every module declaring it, once per declaration. */
+	readonly modules: readonly string[]
+}
+
+export interface Graph {
+	readonly nodes: readonly GraphNode[]
+	readonly duplicates: readonly Duplicate[]
+}
+
+interface Entry {
+	readonly analysis: ModuleAnalysis
+	/** Import and re-export sources to the module ids they resolve to. */
+	readonly resolved: ReadonlyMap<string, string>
+}
+
+const nodeId = (declaration: Pick<Declaration, 'kind' | 'name'>): string =>
+	`${declaration.kind}:${declaration.name}`
+
+/** The runtime's name space for a declaration (see `keyOf` in `@doweljs/core/hot`). */
+const nameKey = (declaration: Pick<Declaration, 'kind' | 'name'>): string =>
+	declaration.kind === 'scope' ? `scope ${declaration.name}` : declaration.name
+
+/** How deep re-export and import chains are followed. */
+const MAX_HOPS = 8
+
+export class Registry {
+	private readonly modules = new Map<string, Entry>()
+	/** Declarations by node id, then by module. */
+	private readonly byId = new Map<string, Map<string, Declaration>>()
+	/** Declaration counts by name key, then by module. */
+	private readonly byName = new Map<string, Map<string, number>>()
+
+	set(id: string, analysis: ModuleAnalysis, resolved: ReadonlyMap<string, string>): void {
+		this.delete(id)
+		this.modules.set(id, { analysis, resolved })
+		for (const declaration of analysis.declarations) {
+			index(this.byId, nodeId(declaration)).set(id, declaration)
+			const counts = index(this.byName, nameKey(declaration))
+			counts.set(id, (counts.get(id) ?? 0) + 1)
+		}
+	}
+
+	delete(id: string): void {
+		const entry = this.modules.get(id)
+		if (entry === undefined) return
+		this.modules.delete(id)
+		for (const declaration of entry.analysis.declarations) {
+			unindex(this.byId, nodeId(declaration), id)
+			unindex(this.byName, nameKey(declaration), id)
+		}
+	}
+
+	/** Forgets every module of a deleted file, queries included. */
+	deleteFile(file: string): void {
+		for (const id of [...this.modules.keys()]) {
+			if (id === file || id.startsWith(`${file}?`)) this.delete(id)
+		}
+	}
+
+	/** Names a module declares that are also declared elsewhere, or more than once in it. */
+	duplicatesOf(id: string): Duplicate[] {
+		const entry = this.modules.get(id)
+		if (entry === undefined) return []
+		const keys = new Set(entry.analysis.declarations.map(nameKey))
+		return [...keys].flatMap((key) => duplicate(key, this.byName.get(key)))
+	}
+
+	graph(): Graph {
+		const nodes: GraphNode[] = []
+		for (const [module, entry] of this.modules) {
+			for (const declaration of entry.analysis.declarations) {
+				nodes.push({
+					id: nodeId(declaration),
+					kind: declaration.kind,
+					name: declaration.name,
+					scope: this.resolveScope(module, declaration),
+					parent:
+						declaration.kind === 'scope' && declaration.scopeRef !== null
+							? this.resolveRef(module, declaration.scopeRef)
+							: null,
+					many: declaration.many,
+					module,
+					local: declaration.local,
+					start: declaration.start,
+					end: declaration.end,
+					deps: declaration.deps.map((dep) => {
+						const target = dep.ref === null ? null : this.resolveRef(module, dep.ref)
+						return {
+							key: dep.key,
+							target,
+							optional: dep.optional,
+						}
+					}),
+				})
+			}
+		}
+		const duplicates = [...this.byName].flatMap(([key, counts]) => duplicate(key, counts))
+		return { nodes, duplicates }
+	}
+
+	/**
+	 * The scope name of a declaration: literal, or the name of the referenced
+	 * scope declaration. An execution lives in the parent of the scope its
+	 * runs open, as it does at runtime.
+	 */
+	private resolveScope(module: string, declaration: Declaration): string | null {
+		if (declaration.scope !== null) return declaration.scope
+		if (declaration.scopeRef === null) return null
+		const id = this.resolveRef(module, declaration.scopeRef)
+		const found = id === null ? null : this.find(id)
+		if (found === null) return null
+		return declaration.kind === 'execution'
+			? this.resolveScope(found.module, found.declaration)
+			: found.declaration.name
+	}
+
+	private find(id: string): { module: string; declaration: Declaration } | null {
+		const declarations = this.byId.get(id)
+		if (declarations === undefined) return null
+		for (const [module, declaration] of declarations) return { module, declaration }
+		return null
+	}
+
+	/** Resolves a reference in a module to a node id, following imports and re-exports. */
+	private resolveRef(module: string, ref: Ref, hops = 0): string | null {
+		const entry = this.modules.get(module)
+		if (entry === undefined || hops > MAX_HOPS) return null
+		const local = entry.analysis.declarations.find((d) => d.local === ref.local)
+		if (local !== undefined) return ref.member === null ? nodeId(local) : null
+		const imported = entry.analysis.imports.get(ref.local)
+		const source = imported === undefined ? undefined : entry.resolved.get(imported.source)
+		if (imported === undefined || source === undefined) return null
+		if (imported.imported === '*') {
+			return ref.member === null ? null : this.resolveExport(source, ref.member, hops + 1)
+		}
+		return ref.member === null ? this.resolveExport(source, imported.imported, hops + 1) : null
+	}
+
+	/** Resolves a name a module exports to a node id. */
+	private resolveExport(module: string, name: string, hops: number): string | null {
+		const entry = this.modules.get(module)
+		if (entry === undefined || hops > MAX_HOPS) return null
+		const local = entry.analysis.exports.get(name)
+		if (local !== undefined) return this.resolveRef(module, { local, member: null }, hops + 1)
+		const reexport = entry.analysis.reexports.get(name)
+		if (reexport !== undefined) {
+			const source = entry.resolved.get(reexport.source)
+			if (source === undefined || reexport.imported === '*') return null
+			return this.resolveExport(source, reexport.imported, hops + 1)
+		}
+		for (const star of entry.analysis.stars) {
+			const source = entry.resolved.get(star)
+			const found = source === undefined ? null : this.resolveExport(source, name, hops + 1)
+			if (found !== null) return found
+		}
+		return null
+	}
+}
+
+/**
+ * The import and re-export sources a module's graph edges may lead through:
+ * those `Registry` follows when it resolves the module's references and
+ * exports. The plugin resolves exactly these to module ids.
+ */
+export function sourcesToResolve(analysis: ModuleAnalysis): Set<string> {
+	const sources = new Set<string>(analysis.stars)
+	for (const reexport of analysis.reexports.values()) sources.add(reexport.source)
+	const locals = new Set<string>(analysis.exports.values())
+	for (const declaration of analysis.declarations) {
+		for (const ref of [declaration.scopeRef, ...declaration.deps.map((dep) => dep.ref)]) {
+			if (ref !== null) locals.add(ref.local)
+		}
+	}
+	for (const local of locals) {
+		const imported = analysis.imports.get(local)
+		if (imported !== undefined) sources.add(imported.source)
+	}
+	return sources
+}
+
+function index<V>(map: Map<string, Map<string, V>>, key: string): Map<string, V> {
+	let inner = map.get(key)
+	if (inner === undefined) {
+		inner = new Map()
+		map.set(key, inner)
+	}
+	return inner
+}
+
+function unindex(map: Map<string, Map<string, unknown>>, key: string, module: string): void {
+	const inner = map.get(key)
+	inner?.delete(module)
+	if (inner?.size === 0) map.delete(key)
+}
+
+function duplicate(key: string, counts: ReadonlyMap<string, number> | undefined): Duplicate[] {
+	if (counts === undefined) return []
+	const modules = [...counts].flatMap(([module, count]) => Array<string>(count).fill(module))
+	return modules.length > 1 ? [{ id: key, modules }] : []
+}

package/src/index.ts

@@ -0,0 +1,155 @@
+/**
+ * `@doweljs/vite`: Vite integration for dowel.
+ *
+ * - Hot replacement: editing a service swaps it (and its dependents) inside
+ *   live containers without reloading, keeping unrelated instances such as
+ *   database connections alive.
+ * - Diagnostics: duplicate slot or service names across modules are reported
+ *   at transform time.
+ * - A static graph of every declaration, which `@doweljs/devtools` draws.
+ *
+ * ```ts
+ * import dowel from '@doweljs/vite'
+ * export default defineConfig({ plugins: [dowel()] })
+ * ```
+ */
+
+import type { Plugin } from 'vite'
+import { analyze, mayDeclare } from './analysis/analyze.ts'
+import { type Graph, Registry, sourcesToResolve } from './analysis/registry.ts'
+import { inject } from './inject.ts'
+import { showHotErrors } from './overlay.ts'
+
+export type { Duplicate, Graph, GraphEdge, GraphNode } from './analysis/registry.ts'
+
+export interface DowelPluginOptions {
+	/**
+	 * How modules that declare slots or services take part in hot replacement.
+	 * - `auto` (default): modules register their declarations on every
+	 *   evaluation, and accept their own updates when every export is a dowel
+	 *   declaration. Mixed modules fall back to Vite's normal propagation.
+	 * - `always`: every declaring module accepts its own updates.
+	 * - `false`: no hot replacement code is injected.
+	 */
+	readonly hot?: 'auto' | 'always' | false
+	/** Module ids to analyze. Default: every `.js`/`.ts` module. */
+	readonly include?: RegExp | readonly RegExp[]
+	/** Module ids to skip, in addition to `node_modules`, which is always skipped. */
+	readonly exclude?: RegExp | readonly RegExp[]
+}
+
+/** What other plugins can ask of the dowel plugin, found by its name in the resolved config. */
+export interface DowelPluginApi {
+	/** The graph as currently known from static analysis. */
+	graph(): Graph
+	/**
+	 * Has every module given hot code import `id` too, so it runs in each
+	 * environment that declares nodes. The devtools load their client this way.
+	 */
+	addClientModule(id: string): void
+}
+
+export interface DowelPlugin extends Plugin {
+	readonly api: DowelPluginApi
+}
+
+const DEFAULT_INCLUDE = /\.[cm]?[jt]sx?$/
+const DEFAULT_EXCLUDE = /node_modules/
+
+export default function dowel(options: DowelPluginOptions = {}): DowelPlugin {
+	const hot = options.hot ?? 'auto'
+	const registry = new Registry()
+	const clients = new Set<string>()
+	let serve = false
+	/** Modules given hot code, by environment: each environment's runtime keeps its own registrations. */
+	const hotModules = new Set<string>()
+	const hotKey = (environment: string | undefined, id: string) => `${environment ?? ''}\0${id}`
+	/**
+	 * A module that registered declarations and now has none still registers
+	 * the empty set, so @doweljs/core/hot releases its names for other modules.
+	 */
+	const release = (environment: string | undefined, code: string, id: string) => {
+		if (!serve || hot === false || !hotModules.has(hotKey(environment, id))) return
+		return inject(code, { id, locals: [], accept: false, clients: [] })
+	}
+
+	return {
+		name: '@doweljs/vite',
+		enforce: 'post',
+
+		api: {
+			graph: () => registry.graph(),
+			addClientModule: (id) => void clients.add(id),
+		},
+
+		config(config, { command }) {
+			// The injected `import "@doweljs/core/hot"` is invisible to the dependency scanner. Optimizing it
+			// together with dowel up front avoids a re-optimization and reload on first load, during
+			// which the two could be separate copies.
+			if (command !== 'serve' || hot === false) return
+			if (config.optimizeDeps?.exclude?.includes('@doweljs/core')) return
+			return { optimizeDeps: { include: ['@doweljs/core', '@doweljs/core/hot'] } }
+		},
+
+		configResolved(config) {
+			// No hot code where nothing replaces modules: test runners such as Vitest, or HMR turned off.
+			serve =
+				config.command === 'serve' &&
+				config.server.hmr !== false &&
+				process.env['VITEST'] === undefined
+		},
+
+		transform: {
+			filter: {
+				id: {
+					include: patterns(options.include ?? DEFAULT_INCLUDE),
+					exclude: [DEFAULT_EXCLUDE, ...patterns(options.exclude ?? [])],
+				},
+			},
+			async handler(code, id) {
+				const analysis = mayDeclare(code) ? analyze(id, code) : null
+				if (analysis === null) {
+					registry.delete(id)
+					return release(this.environment?.name, code, id)
+				}
+
+				// Only the sources the graph can follow, resolved in parallel.
+				const sources = sourcesToResolve(analysis)
+				const resolved = new Map<string, string>()
+				await Promise.all(
+					[...sources].map(async (source) => {
+						const target = await this.resolve(source, id)
+						if (target !== null) resolved.set(source, target.id)
+					}),
+				)
+				registry.set(id, analysis, resolved)
+
+				for (const duplicate of registry.duplicatesOf(id)) {
+					this.warn(
+						`'${duplicate.id}' is declared more than once. Names must be unique; ` +
+							`hot replacement treats these as the same node.\n  ${duplicate.modules.join('\n  ')}`,
+					)
+				}
+
+				if (analysis.declarations.length === 0) return release(this.environment?.name, code, id)
+				if (!serve || hot === false) return
+				hotModules.add(hotKey(this.environment?.name, id))
+				return inject(code, {
+					id,
+					locals: analysis.declarations.map((declaration) => declaration.local),
+					accept: hot === 'always' || analysis.selfContained,
+					clients: [...clients],
+				})
+			},
+		},
+
+		configureServer(server) {
+			server.watcher.on('unlink', (file) => registry.deleteFile(file))
+			if (hot !== false) showHotErrors(server)
+		},
+	}
+}
+
+function patterns(value: RegExp | readonly RegExp[]): RegExp[] {
+	return value instanceof RegExp ? [value] : [...value]
+}

package/src/inject.ts

@@ -0,0 +1,48 @@
+/**
+ * Appends the development-only hot replacement snippet to a module that
+ * declares slots or services. Appending keeps every original line in place,
+ * so the generated source map is a plain extension of the original.
+ */
+
+import { MagicString } from 'magic-string'
+import { HOT_ERROR } from './overlay.ts'
+
+export interface InjectOptions {
+	/** Module id, used as the registration key for `@doweljs/core/hot`. */
+	readonly id: string
+	/** Local names of the module's slot and service declarations. */
+	readonly locals: readonly string[]
+	/** Whether the module should accept its own updates. */
+	readonly accept: boolean
+	/** Modules other plugins asked every module with hot code to import. */
+	readonly clients: readonly string[]
+}
+
+export function inject(
+	code: string,
+	options: InjectOptions,
+): { code: string; map: ReturnType<MagicString['generateMap']> } {
+	const s = new MagicString(code)
+	const declarations = options.locals.join(', ')
+	s.append(`
+
+// @doweljs/vite: hot replacement
+import * as __dowel_hot__ from "@doweljs/core/hot";
+${options.clients.map((client) => `import ${JSON.stringify(client)};\n`).join('')}if (import.meta.hot) {
+	__dowel_hot__.update(${JSON.stringify(options.id)}, { ${declarations} }).then(
+		(result) => {
+			if (result.changed.length > 0) console.info("[dowel] replaced " + result.changed.join(", "));
+		},
+		(error) => {
+			const message = __dowel_hot__.describeFailure(error);
+			console.error(message);
+			import.meta.hot.send(${JSON.stringify(HOT_ERROR)}, { message, stack: String((error && error.stack) || "") });
+		},
+	);
+	// Release the module's names once nothing imports it any more, so another module may declare them.
+	import.meta.hot.prune(() => __dowel_hot__.forget(${JSON.stringify(options.id)}));
+${options.accept ? '\timport.meta.hot.accept();\n' : ''}}
+`)
+	// Only appended code changes, so a map at token boundaries is exact enough.
+	return { code: s.toString(), map: s.generateMap({ hires: 'boundary' }) }
+}

package/src/overlay.ts

@@ -0,0 +1,27 @@
+/**
+ * Hot replacement failures in Vite's error overlay. The injected code reports
+ * a failed update over its environment's hot channel; the plugin shows it in
+ * the browser, whichever environment it came from.
+ */
+
+import type { ViteDevServer } from 'vite'
+
+/** The event injected code sends when an update fails. */
+export const HOT_ERROR = 'dowel:error'
+
+export interface HotErrorMessage {
+	readonly message: string
+	readonly stack: string
+}
+
+/** Shows the failures every environment of `server` reports in the browser's error overlay. */
+export function showHotErrors(server: ViteDevServer): void {
+	for (const environment of Object.values(server.environments)) {
+		environment.hot.on(HOT_ERROR, (data: HotErrorMessage) => {
+			server.environments.client.hot.send({
+				type: 'error',
+				err: { message: data.message, stack: data.stack, plugin: '@doweljs/vite' },
+			})
+		})
+	}
+}