@ecopages/core 0.2.0-alpha.52 → 0.2.0-alpha.54

package/src/plugins/alias-resolver-cache.test.ts

@@ -0,0 +1,110 @@
+import { describe, expect, it } from 'vitest';
+import { AliasResolverCache } from './alias-resolver-cache.ts';
+
+describe('AliasResolverCache', () => {
+	const srcDir = '/app/src';
+	const specifier = '@/components/Button';
+
+	it('misses on first lookup', () => {
+		const cache = new AliasResolverCache();
+		expect(cache.get(srcDir, specifier)).toEqual({ hit: false });
+		expect(cache.stats().misses).toBe(1);
+	});
+
+	it('hits after a set', () => {
+		const cache = new AliasResolverCache();
+		cache.set(srcDir, specifier, '/app/src/components/Button.tsx');
+		expect(cache.get(srcDir, specifier)).toEqual({
+			hit: true,
+			resolved: '/app/src/components/Button.tsx',
+		});
+		expect(cache.stats().hits).toBe(1);
+	});
+
+	it('caches negative results (unresolvable specifier)', () => {
+		const cache = new AliasResolverCache();
+		cache.set(srcDir, '@/missing', undefined);
+		expect(cache.get(srcDir, '@/missing')).toEqual({ hit: true, resolved: undefined });
+	});
+
+	it('different srcDirs do not collide', () => {
+		const cache = new AliasResolverCache();
+		cache.set('/app1/src', specifier, '/app1/src/components/Button.tsx');
+		cache.set('/app2/src', specifier, '/app2/src/components/Button.tsx');
+		expect(cache.get('/app1/src', specifier)).toEqual({
+			hit: true,
+			resolved: '/app1/src/components/Button.tsx',
+		});
+		expect(cache.get('/app2/src', specifier)).toEqual({
+			hit: true,
+			resolved: '/app2/src/components/Button.tsx',
+		});
+	});
+
+	it('evicts oldest entry when capacity exceeded', () => {
+		const cache = new AliasResolverCache(2);
+		cache.set('/a/src', '@/x', '/a/x.ts');
+		cache.set('/b/src', '@/y', '/b/y.ts');
+		cache.set('/c/src', '@/z', '/c/z.ts');
+		expect(cache.size).toBe(2);
+		// /a/src @/x should have been evicted
+		expect(cache.get('/a/src', '@/x')).toEqual({ hit: false });
+	});
+
+	it('invalidateUnder drops all entries under a rootDir', () => {
+		const cache = new AliasResolverCache();
+		cache.set('/app/src', '@/a', '/app/src/a.ts');
+		cache.set('/app/src', '@/b', '/app/src/b.ts');
+		cache.set('/other/src', '@/c', '/other/src/c.ts');
+		const removed = cache.invalidateUnder('/app/src');
+		expect(removed).toBe(2);
+		expect(cache.size).toBe(1);
+		expect(cache.get('/other/src', '@/c')).toEqual({ hit: true, resolved: '/other/src/c.ts' });
+	});
+
+	it('invalidateUnder treats sibling paths with shared prefix as distinct', () => {
+		// Regression: a previous startsWith-based check would match
+		// '/app/src-foo' against '/app/src/'. The path-aware check
+		// normalizes and only matches true descendants.
+		const cache = new AliasResolverCache();
+		cache.set('/app/src', '@/a', '/app/src/a.ts');
+		cache.set('/app/src-foo', '@/b', '/app/src-foo/b.ts');
+		const removed = cache.invalidateUnder('/app/src');
+		expect(removed).toBe(1);
+		expect(cache.size).toBe(1);
+		expect(cache.get('/app/src-foo', '@/b')).toEqual({
+			hit: true,
+			resolved: '/app/src-foo/b.ts',
+		});
+	});
+
+	it('invalidateUnder handles deep nested descendants', () => {
+		// Validates path.relative walks arbitrarily deep hierarchies.
+		const cache = new AliasResolverCache();
+		cache.set('/app/src', '@/a', '/app/src/a.ts');
+		cache.set('/app/src/components/buttons/primary', '@/b', '/app/src/components/buttons/primary/b.ts');
+		cache.set('/app/other', '@/c', '/app/other/c.ts');
+		const removed = cache.invalidateUnder('/app/src');
+		expect(removed).toBe(2);
+		expect(cache.size).toBe(1);
+		expect(cache.get('/app/other', '@/c')).toEqual({ hit: true, resolved: '/app/other/c.ts' });
+	});
+
+	it('invalidateUnder returns 0 on empty cache', () => {
+		const cache = new AliasResolverCache();
+		expect(cache.invalidateUnder('/app/src')).toBe(0);
+	});
+
+	it('clear() resets state', () => {
+		const cache = new AliasResolverCache();
+		cache.set(srcDir, specifier, '/app/src/Button.tsx');
+		cache.get(srcDir, specifier);
+		cache.clear();
+		expect(cache.size).toBe(0);
+		expect(cache.stats().hits).toBe(0);
+	});
+
+	it('throws on invalid maxEntries', () => {
+		expect(() => new AliasResolverCache(0)).toThrow();
+	});
+});

package/src/plugins/alias-resolver-cache.ts

@@ -0,0 +1,145 @@
+/**
+ * Per-plugin cache for `@/...` alias resolution.
+ *
+ * @remarks
+ * The `ecopages-alias-resolver` plugin resolves project aliases like
+ * `@/components/Button` to concrete file paths under the app's `srcDir`.
+ * Each resolution can trigger up to 22 `existsSync` calls and (when
+ * the resolved path is a barrel) a `readFileSync` to detect
+ * `export * from './...'` forwarding.
+ *
+ * This cache memoizes the result keyed by `(srcDir, specifier)`. It is
+ * process-local and not currently invalidated by the file watcher —
+ * `srcDir` contents are assumed to be stable for the lifetime of the
+ * process.
+ */
+
+import path from 'node:path';
+
+const DEFAULT_MAX_ENTRIES = 2_000;
+
+type CacheKey = string;
+
+type CacheEntry = {
+	srcDir: string;
+	/** Resolved absolute path, or `undefined` if the specifier did not resolve. */
+	resolved: string | undefined;
+};
+
+export class AliasResolverCache {
+	private readonly entries = new Map<CacheKey, CacheEntry>();
+	private readonly maxEntries: number;
+	private hits = 0;
+	private misses = 0;
+
+	constructor(maxEntries: number = DEFAULT_MAX_ENTRIES) {
+		if (maxEntries <= 0) {
+			throw new Error(`AliasResolverCache: maxEntries must be > 0, got ${maxEntries}`);
+		}
+		this.maxEntries = maxEntries;
+	}
+
+	/**
+	 * Look up a previously-computed resolution for `(srcDir, specifier)`.
+	 *
+	 * Returns `{ hit: true, resolved }` on cache hit (resolved may be
+	 * `undefined` for an unresolvable specifier), or `{ hit: false }` on
+	 * miss. The caller is responsible for re-running the resolver and
+	 * calling `set` to store the new entry.
+	 */
+	get(srcDir: string, specifier: string): { hit: true; resolved: string | undefined } | { hit: false } {
+		const key = makeKey(srcDir, specifier);
+		const existing = this.entries.get(key);
+		if (existing) {
+			this.hits += 1;
+			// Refresh LRU position.
+			this.entries.delete(key);
+			this.entries.set(key, existing);
+			return { hit: true, resolved: existing.resolved };
+		}
+		this.misses += 1;
+		return { hit: false };
+	}
+
+	/**
+	 * Store a resolution result.
+	 *
+	 * Pass `undefined` for `resolved` to memoize the negative case
+	 * (specifier did not resolve) and avoid repeating the FS walk on
+	 * every `@/...` import.
+	 */
+	set(srcDir: string, specifier: string, resolved: string | undefined): void {
+		const key = makeKey(srcDir, specifier);
+		this.entries.set(key, { srcDir, resolved });
+
+		if (this.entries.size > this.maxEntries) {
+			const oldestKey = this.entries.keys().next().value;
+			if (oldestKey !== undefined) {
+				this.entries.delete(oldestKey);
+			}
+		}
+	}
+
+	/**
+	 * Drop all entries whose `srcDir` is under `rootDir`. Use this from
+	 * the file watcher when files are added or removed under the app's
+	 * source tree.
+	 *
+	 * Path comparison is path-aware (handles both POSIX `/` and
+	 * Windows `\` separators) via `path.relative` so cached entries
+	 * normalized on one platform still match the watcher's `rootDir`
+	 * on another. Without this, a Windows build that sees
+	 * `entry.srcDir === 'C:\app\src'` would miss
+	 * `entry.srcDir.startsWith('C:/app/src/')` and leave stale entries.
+	 */
+	invalidateUnder(rootDir: string): number {
+		const normalizedRoot = path.resolve(rootDir);
+		let removed = 0;
+		for (const [key, entry] of this.entries) {
+			if (isUnderDirectory(path.resolve(entry.srcDir), normalizedRoot)) {
+				this.entries.delete(key);
+				removed += 1;
+			}
+		}
+		return removed;
+	}
+
+	/** Clear all entries. */
+	clear(): void {
+		this.entries.clear();
+		this.hits = 0;
+		this.misses = 0;
+	}
+
+	/** Current cache size. */
+	get size(): number {
+		return this.entries.size;
+	}
+
+	/** Hit/miss counters for observability. */
+	stats(): { hits: number; misses: number; size: number; hitRate: number } {
+		const total = this.hits + this.misses;
+		return {
+			hits: this.hits,
+			misses: this.misses,
+			size: this.entries.size,
+			hitRate: total === 0 ? 0 : this.hits / total,
+		};
+	}
+}
+
+function makeKey(srcDir: string, specifier: string): string {
+	return `${srcDir} ${specifier}`;
+}
+
+/**
+ * Returns true if `candidate` is the same as `parent` or a descendant
+ * of it. Uses `path.relative` so the comparison is path-aware and
+ * works across POSIX and Windows separators.
+ */
+function isUnderDirectory(candidate: string, parent: string): boolean {
+	if (candidate === parent) return true;
+	const rel = path.relative(parent, candidate);
+	if (!rel || rel.startsWith('..') || path.isAbsolute(rel)) return false;
+	return true;
+}

package/src/plugins/alias-resolver-plugin.test.ts

@@ -0,0 +1,41 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { test } from 'vitest';
+import type { EcoBuildOnResolveResult } from '../build/build-types.ts';
+import { createAliasResolverPlugin } from './alias-resolver-plugin.ts';
+
+test('createAliasResolverPlugin resolves @ aliases to concrete barrel targets', async () => {
+	const rootDir = fs.mkdtempSync(path.join(tmpdir(), 'ecopages-alias-resolver-'));
+	const srcDir = path.join(rootDir, 'src');
+	const layoutDir = path.join(srcDir, 'layouts', 'base-layout');
+	fs.mkdirSync(layoutDir, { recursive: true });
+	fs.writeFileSync(path.join(layoutDir, 'base-layout.kita.tsx'), 'export const BaseLayout = {};\n', 'utf8');
+	fs.writeFileSync(path.join(layoutDir, 'index.ts'), "export * from './base-layout.kita';\n", 'utf8');
+
+	try {
+		const registrations: Array<{
+			filter: RegExp;
+			callback: (args: {
+				path: string;
+			}) => EcoBuildOnResolveResult | undefined | Promise<EcoBuildOnResolveResult | undefined>;
+		}> = [];
+		const plugin = createAliasResolverPlugin(srcDir);
+
+		plugin.setup({
+			onResolve(options, callback) {
+				registrations.push({ filter: options.filter, callback });
+			},
+			onLoad() {},
+			module() {},
+		});
+
+		assert.equal(registrations.length, 1);
+		assert.deepEqual(await registrations[0]?.callback({ path: '@/layouts/base-layout' }), {
+			path: path.join(layoutDir, 'base-layout.kita.tsx'),
+		});
+	} finally {
+		fs.rmSync(rootDir, { recursive: true, force: true });
+	}
+});

package/src/plugins/alias-resolver-plugin.ts

@@ -0,0 +1,75 @@
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import type { EcoBuildPlugin } from '../build/build-types.ts';
+import { AliasResolverCache } from './alias-resolver-cache.ts';
+
+const RESOLVABLE_EXTENSIONS = ['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '.mdx', '.css', '.scss', '.sass', '.less'];
+
+function findResolvablePath(candidate: string): string | undefined {
+	if (path.extname(candidate)) {
+		if (existsSync(candidate)) {
+			return candidate;
+		}
+	}
+
+	for (const extension of RESOLVABLE_EXTENSIONS) {
+		const fileCandidate = `${candidate}${extension}`;
+		if (existsSync(fileCandidate)) {
+			return fileCandidate;
+		}
+	}
+
+	for (const extension of RESOLVABLE_EXTENSIONS) {
+		const indexCandidate = path.join(candidate, `index${extension}`);
+		if (existsSync(indexCandidate)) {
+			return indexCandidate;
+		}
+	}
+
+	return undefined;
+}
+
+function resolveAliasedBarrelTarget(resolvedPath: string): string {
+	if (!path.basename(resolvedPath).startsWith('index.')) {
+		return resolvedPath;
+	}
+
+	const source = readFileSync(resolvedPath, 'utf8').trim();
+	const match = source.match(/^export\s+\*\s+from\s+['"]([^'"]+)['"]\s*;?$/);
+
+	if (!match?.[1]?.startsWith('.')) {
+		return resolvedPath;
+	}
+
+	const target = findResolvablePath(path.resolve(path.dirname(resolvedPath), match[1]));
+	return target ?? resolvedPath;
+}
+
+export function resolveAppSourceAliasPath(srcDir: string, specifier: string): string | undefined {
+	if (!specifier.startsWith('@/')) {
+		return undefined;
+	}
+
+	const candidate = path.join(srcDir, specifier.slice(2));
+	const resolved = findResolvablePath(candidate);
+	return resolved ? resolveAliasedBarrelTarget(resolved) : undefined;
+}
+
+export function createAliasResolverPlugin(srcDir: string, options?: { cache?: AliasResolverCache }): EcoBuildPlugin {
+	const cache = options?.cache ?? new AliasResolverCache();
+	return {
+		name: 'ecopages-alias-resolver',
+		setup(build) {
+			build.onResolve({ filter: /^@\// }, (args) => {
+				const cached = cache.get(srcDir, args.path);
+				if (cached.hit) {
+					return cached.resolved ? { path: cached.resolved } : {};
+				}
+
+				const resolved = resolveAppSourceAliasPath(srcDir, args.path);
+				cache.set(srcDir, args.path, resolved);
+				return resolved ? { path: resolved } : {};
+			});
+		},
+	};
+}