octane 0.1.5 → 0.1.6

package/dist/compiler/bundler.js

@@ -0,0 +1,389 @@
+/**
+ * Bundler-neutral Octane source integration.
+ *
+ * This module owns every decision shared by Vite, Rspack, and future bundlers:
+ * source eligibility, package-manifest rules, canonical compiler IDs, compiler
+ * target/HMR options, raw-source dependency discovery, and runtime requests.
+ * Bundler adapters are responsible only for translating their own lifecycle and
+ * watch APIs to this small surface.
+ */
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { compile } from './compile.js';
+import { slotHooks } from './slot-hooks.js';
+
+const OCTANE_DEPENDENCY_FIELDS = [
+	'dependencies',
+	'devDependencies',
+	'optionalDependencies',
+	'peerDependencies',
+];
+
+export const OCTANE_RUNTIME_REQUESTS = Object.freeze({
+	client: 'octane',
+	server: 'octane/server',
+});
+
+/** Strip bundler query/hash suffixes without changing the underlying path. */
+export function cleanModuleId(id) {
+	const query = id.indexOf('?');
+	const hash = id.indexOf('#');
+	let end = id.length;
+	if (query !== -1) end = query;
+	if (hash !== -1 && hash < end) end = hash;
+	return id.slice(0, end);
+}
+
+function isPathInside(root, file) {
+	const relativeFile = relative(root, file);
+	return relativeFile !== '..' && !relativeFile.startsWith('..' + sep) && !isAbsolute(relativeFile);
+}
+
+function normalizeModulePath(file) {
+	return file.split(/[\\/]/).join('/');
+}
+
+/**
+ * Return the stable ID embedded in hook keys and dev source metadata. Files
+ * inside the project root use a root-relative POSIX path so builds are portable;
+ * external files retain their absolute path. Bundler query suffixes never enter
+ * compiler output or cache keys.
+ */
+export function canonicalModuleId(id, projectRoot) {
+	const file = cleanModuleId(id);
+	if (!projectRoot || !isAbsolute(file)) return normalizeModulePath(file);
+	const root = resolve(projectRoot);
+	const relativeFile = relative(root, file);
+	if (!isPathInside(root, file)) return normalizeModulePath(file);
+	return '/' + normalizeModulePath(relativeFile);
+}
+
+export function resolveOctaneRuntimeRequest(request, environment) {
+	if (request !== 'octane') return null;
+	if (environment !== 'client' && environment !== 'server') {
+		throw new Error(
+			`Unknown Octane environment ${JSON.stringify(environment)} — expected 'client' or 'server'.`,
+		);
+	}
+	return OCTANE_RUNTIME_REQUESTS[environment];
+}
+
+function packageUsesOctane(pkg) {
+	return (
+		pkg.name === 'octane' ||
+		['dependencies', 'optionalDependencies', 'peerDependencies'].some(
+			(field) => typeof pkg[field]?.octane === 'string',
+		)
+	);
+}
+
+function metadata(dependencies = [], missingDependencies = []) {
+	return { dependencies, missingDependencies };
+}
+
+function addMetadata(target, source) {
+	for (const file of source.dependencies) target.dependencies.add(file);
+	for (const file of source.missingDependencies) target.missingDependencies.add(file);
+}
+
+function finishMetadata(value) {
+	return {
+		dependencies: [...value.dependencies].sort(),
+		missingDependencies: [...value.missingDependencies].sort(),
+	};
+}
+
+function normalizeHmrDialect(value) {
+	// Backwards compatibility: compile(..., { hmr: true }) has always meant the
+	// Vite import.meta.hot dialect.
+	if (value === true) return 'vite';
+	if (value === false || value == null) return false;
+	if (value === 'vite' || value === 'webpack') return value;
+	throw new Error(
+		`Unknown Octane HMR dialect ${JSON.stringify(value)} — expected false, 'vite', or 'webpack'.`,
+	);
+}
+
+class OctaneBundlerCompiler {
+	constructor(options) {
+		this.root = resolve(options.root ?? process.cwd());
+		try {
+			this.realRoot = realpathSync(this.root);
+		} catch {
+			this.realRoot = this.root;
+		}
+		this.exclude = [...(options.exclude ?? [])];
+		this.defaults = {
+			environment: options.environment ?? 'client',
+			hmr: normalizeHmrDialect(options.hmr),
+			dev: options.dev,
+			parallelUse: options.parallelUse,
+		};
+		// Deliberately instance-scoped: separate projects/build environments must
+		// never share nearest-manifest decisions.
+		this.manifestRuleCache = new Map();
+		this.discoveryCache = null;
+	}
+
+	/** Clear cached manifest/discovery decisions after a watched path changes. */
+	invalidate(path) {
+		if (path == null) {
+			this.manifestRuleCache.clear();
+			this.discoveryCache = null;
+			return;
+		}
+		const changed = resolve(cleanModuleId(path));
+		for (const [directory, entry] of this.manifestRuleCache) {
+			if (entry.dependencies.includes(changed) || entry.missingDependencies.includes(changed)) {
+				this.manifestRuleCache.delete(directory);
+			}
+		}
+		if (
+			this.discoveryCache?.dependencies.includes(changed) ||
+			this.discoveryCache?.missingDependencies.includes(changed)
+		) {
+			this.discoveryCache = null;
+		}
+	}
+
+	_nearestOctanePackageRule(fileDir) {
+		const dir = resolve(fileDir);
+		const cached = this.manifestRuleCache.get(dir);
+		if (cached !== undefined) return cached;
+
+		const manifest = join(dir, 'package.json');
+		let pkg = null;
+		try {
+			pkg = JSON.parse(readFileSync(manifest, 'utf8'));
+		} catch {
+			// An absent/unreadable/invalid manifest does not own the file. Continue
+			// upward, while retaining the path as watch/cache metadata.
+		}
+
+		let result;
+		if (pkg !== null) {
+			const manual = pkg.octane?.hookSlots?.manual;
+			result = {
+				rule: {
+					root: dir,
+					dirs: Array.isArray(manual) ? manual : [],
+					runtimeDependencies: [
+						...Object.keys(pkg.dependencies ?? {}),
+						...Object.keys(pkg.optionalDependencies ?? {}),
+					],
+					usesOctane: packageUsesOctane(pkg),
+				},
+				...metadata([manifest]),
+			};
+		} else {
+			const parent = dirname(dir);
+			const inherited =
+				parent === dir ? { rule: null, ...metadata() } : this._nearestOctanePackageRule(parent);
+			result = {
+				rule: inherited.rule,
+				dependencies: existsSync(manifest)
+					? [manifest, ...inherited.dependencies]
+					: inherited.dependencies,
+				missingDependencies: existsSync(manifest)
+					? inherited.missingDependencies
+					: [manifest, ...inherited.missingDependencies],
+			};
+		}
+
+		this.manifestRuleCache.set(dir, result);
+		return result;
+	}
+
+	_hasManualHookSlots(file, collected) {
+		const lookup = this._nearestOctanePackageRule(dirname(file));
+		addMetadata(collected, lookup);
+		if (lookup.rule === null) return false;
+		const relativeFile = relative(lookup.rule.root, file);
+		return lookup.rule.dirs.some((directory) => {
+			const relativeDirectory = directory
+				.replace(/[\\/]+$/, '')
+				.split(/[\\/]/)
+				.join(sep);
+			return (
+				relativeDirectory !== '' &&
+				(relativeFile === relativeDirectory || relativeFile.startsWith(relativeDirectory + sep))
+			);
+		});
+	}
+
+	_isInstalledOctaneSource(file, collected) {
+		const absoluteFile = isAbsolute(file) ? resolve(file) : resolve(this.root, file);
+		const isInstalledPath = /(?:^|[\\/])node_modules(?:[\\/]|$)/.test(absoluteFile);
+		// Project-owned TS/JS/TSX is always eligible. A linked package is commonly
+		// handed to bundlers as its real path, without a node_modules segment, so
+		// external files must make the same manifest-declared Octane decision as an
+		// installed package instead of being mistaken for application source.
+		if (
+			!isInstalledPath &&
+			(isPathInside(this.root, absoluteFile) || isPathInside(this.realRoot, absoluteFile))
+		) {
+			return true;
+		}
+		const lookup = this._nearestOctanePackageRule(dirname(absoluteFile));
+		addMetadata(collected, lookup);
+		return lookup.rule?.usesOctane === true;
+	}
+
+	/**
+	 * Discover installed source packages which consume Octane, recursively
+	 * following runtime dependencies between those packages.
+	 */
+	discoverSourceDependencies() {
+		if (this.discoveryCache !== null) return this.discoveryCache;
+		const collected = {
+			dependencies: new Set(),
+			missingDependencies: new Set(),
+		};
+		const projectManifestPath = join(this.root, 'package.json');
+		let projectManifest;
+		try {
+			projectManifest = JSON.parse(readFileSync(projectManifestPath, 'utf8'));
+			collected.dependencies.add(projectManifestPath);
+		} catch {
+			if (existsSync(projectManifestPath)) collected.dependencies.add(projectManifestPath);
+			else collected.missingDependencies.add(projectManifestPath);
+			this.discoveryCache = { packages: [], ...finishMetadata(collected) };
+			return this.discoveryCache;
+		}
+
+		const dependencyNames = new Set();
+		for (const field of OCTANE_DEPENDENCY_FIELDS) {
+			for (const name of Object.keys(projectManifest[field] ?? {})) dependencyNames.add(name);
+		}
+		const sourceDependencies = new Set();
+		const visitedPackageRoots = new Set();
+		const visit = (name, issuerRoot) => {
+			const packageRequire = createRequire(join(issuerRoot, 'package.json'));
+			try {
+				const entry = packageRequire.resolve(name);
+				const lookup = this._nearestOctanePackageRule(dirname(entry));
+				addMetadata(collected, lookup);
+				if (!lookup.rule?.usesOctane) return;
+				sourceDependencies.add(name);
+				let packageRoot = lookup.rule.root;
+				try {
+					packageRoot = realpathSync(packageRoot);
+				} catch {
+					// Keep the resolved/symlink path as the cycle key.
+				}
+				if (visitedPackageRoots.has(packageRoot)) return;
+				visitedPackageRoots.add(packageRoot);
+				for (const dependency of lookup.rule.runtimeDependencies) {
+					visit(dependency, lookup.rule.root);
+				}
+			} catch {
+				// Match Node's upward node_modules search: package managers commonly
+				// satisfy a nested raw-source dependency by hoisting it to the project
+				// root. Any candidate's creation can therefore make this request
+				// resolvable and must invalidate a cached miss.
+				let candidateRoot = resolve(issuerRoot);
+				for (;;) {
+					collected.missingDependencies.add(
+						join(candidateRoot, 'node_modules', name, 'package.json'),
+					);
+					const parent = dirname(candidateRoot);
+					if (parent === candidateRoot) break;
+					candidateRoot = parent;
+				}
+			}
+		};
+		for (const name of dependencyNames) visit(name, this.root);
+
+		this.discoveryCache = {
+			packages: [...sourceDependencies].sort(),
+			...finishMetadata(collected),
+		};
+		return this.discoveryCache;
+	}
+
+	resolveRuntimeRequest(request, environment = this.defaults.environment) {
+		return resolveOctaneRuntimeRequest(request, environment);
+	}
+
+	_passThrough(code, collected) {
+		if (collected.dependencies.size === 0 && collected.missingDependencies.size === 0) {
+			return null;
+		}
+		return {
+			code,
+			map: null,
+			kind: 'none',
+			...finishMetadata(collected),
+		};
+	}
+
+	transform(code, id, options = {}) {
+		const file = cleanModuleId(id);
+		const collected = {
+			dependencies: new Set(),
+			missingDependencies: new Set(),
+		};
+		const environment = options.environment ?? this.defaults.environment;
+		if (environment !== 'client' && environment !== 'server') {
+			throw new Error(
+				`Unknown Octane environment ${JSON.stringify(environment)} — expected 'client' or 'server'.`,
+			);
+		}
+		const requestedHmr = normalizeHmrDialect(options.hmr ?? this.defaults.hmr);
+		const hmr = environment === 'server' ? false : requestedHmr;
+		const dev = environment === 'server' ? false : (options.dev ?? this.defaults.dev ?? !!hmr);
+		const parallelUse = options.parallelUse ?? this.defaults.parallelUse;
+		const filename = canonicalModuleId(file, this.root);
+
+		const fullCompile =
+			file.endsWith('.tsrx') ||
+			(file.endsWith('.tsx') && this._isInstalledOctaneSource(file, collected));
+		if (fullCompile) {
+			const out = compile(code, filename, {
+				hmr,
+				mode: environment,
+				dev,
+				parallelUse: parallelUse !== false,
+			});
+			return {
+				code: out.code,
+				map: out.map,
+				kind: 'compile',
+				...finishMetadata(collected),
+			};
+		}
+		if (file.endsWith('.tsx')) return this._passThrough(code, collected);
+
+		if ((file.endsWith('.ts') || file.endsWith('.js')) && !file.endsWith('.d.ts')) {
+			if (/\/\/\s*octane-no-slot\b/.test(code)) return null;
+			if (this.exclude.some((path) => file.includes(path))) return null;
+			if (!/from\s*['"]octane['"]/.test(code)) return null;
+			if (!this._isInstalledOctaneSource(file, collected)) {
+				return this._passThrough(code, collected);
+			}
+			if (this._hasManualHookSlots(file, collected)) {
+				return this._passThrough(code, collected);
+			}
+			const out = slotHooks(code, filename, { hmr: !!hmr });
+			if (out === null) return this._passThrough(code, collected);
+			return {
+				code: out.code,
+				map: out.map,
+				kind: 'slots',
+				...finishMetadata(collected),
+			};
+		}
+
+		return null;
+	}
+}
+
+export function createOctaneCompiler(options = {}) {
+	return new OctaneBundlerCompiler(options);
+}
+
+/** Backwards-compatible convenience for callers that only need package names. */
+export function discoverOctaneSourceDependencies(projectRoot) {
+	return createOctaneCompiler({ root: projectRoot }).discoverSourceDependencies().packages;
+}