fundus 0.9.1 → 0.11.0

package/build/server/chunks/chunks/{context.js-mXbNUDBD.js → context.js-BJfk3ZiR.js}

@@ -1,14 +1,15 @@
-import { g as folderOfRawPath, h as rawFileNameOfPath, j as canonicalizeParameters, n as normalizeFolderPath, c as compareCodeUnits, H as typesForFileName, J as proposeAssetId, k as parentFolderPath, u as portableFolderPathKey } from './core.js-Cj7hjmtV.js';
-import { s as serverPluginsByType, i as isRecord, L as LibraryStore, a as serverPluginForType, S as SourceImportError, p as processAssets, g as generateManifestModules, d as descriptorsByType, r as readCurrentProxy, e as encodeRelativePathForUrl, b as invalidInput, c as parseLibrary } from './contract.js-BCXeXDmU.js';
-import { a as assetIdError, c as collectAllReferences, b as computeLibraryMembership, d as allDeliveredAssetIds } from './manifest-membership.js-vIb-KkQi.js';
+import { c as compareCodeUnits, g as folderOfRawPath, h as rawFileNameOfPath, j as canonicalizeParameters, n as normalizeFolderPath, H as typesForFileName, J as proposeAssetId, k as parentFolderPath, u as portableFolderPathKey } from './core.js-Cj7hjmtV.js';
+import { s as serverPluginsByType, i as isRecord, L as LibraryStore, d as descriptorsByType, m as manifestModuleFileName, l as locateGeneratedAssetDeclaration, a as serializeLibrary, b as serverPluginForType, S as SourceImportError, p as processAssets, g as generateManifestModules, r as readCurrentProxy, e as encodeRelativePathForUrl, c as invalidInput, f as parseLibrary } from './contract.js-DRcxzb4o.js';
+import { c as collectAllReferences, a as assetIdError, b as computeLibraryMembership, d as allDeliveredAssetIds } from './manifest-membership.js-vIb-KkQi.js';
 import { v as verifyStableRawFile, c as classifyRawDirectory } from './raw-reconciliation2.js-5mUCDiJk.js';
 import { isAbsolute, resolve, join, extname, relative, sep } from 'node:path';
 import { existsSync } from 'node:fs';
 import { createJiti } from 'jiti';
-import { realpath } from 'node:fs/promises';
+import { readFile, realpath } from 'node:fs/promises';
 import { execFile } from 'node:child_process';
 import { isDeepStrictEqual, promisify } from 'node:util';
 import sharp from 'sharp';
+import { randomBytes, createHmac, timingSafeEqual, createHash } from 'node:crypto';
 import { lookup } from 'node:dns/promises';
 import { isIP } from 'node:net';
 import { request } from 'node:https';
@@ -57,6 +58,10 @@ function resolveConfig(projectRoot, value, registry = serverPluginsByType) {
 	if (!isRecord(defaults)) throw new Error("fundus.config: \"import.figma.defaults\" must be an object.");
 	const scale = defaults.scale === void 0 ? 2 : defaults.scale;
 	if (scale !== 1 && scale !== 2 && scale !== 3 && scale !== 4) throw new Error("fundus.config: \"import.figma.defaults.scale\" must be 1, 2, 3, or 4.");
+	const usage = value.usage;
+	if (usage !== void 0 && !isRecord(usage)) throw new Error("fundus.config: \"usage\" must be an object.");
+	if (usage !== void 0 && typeof usage.referenceProvider !== "function") throw new Error("fundus.config: \"usage.referenceProvider\" must be a function.");
+	if (usage !== void 0 && typeof usage.openLocation !== "function") throw new Error("fundus.config: \"usage.openLocation\" must be a function.");
 	return {
 		projectRoot: resolve(projectRoot),
 		rawDir: resolvePath(projectRoot, requiredString(value, "rawDir")),
@@ -68,7 +73,8 @@ function resolveConfig(projectRoot, value, registry = serverPluginsByType) {
 		import: { figma: {
 			...figma.token !== void 0 ? { token: figma.token } : {},
 			defaults: { scale }
-		} }
+		} },
+		usage: usage === void 0 ? null : usage
 	};
 }
 /** Load `fundus.config.ts` from the host project root. */
@@ -709,6 +715,367 @@ async function gitAssetChanges(projectRoot, libraryPath, currentLibrary) {
 	}
 }
 //#endregion
+//#region src/lib/server/usage.ts
+var MAX_PATHS = 20;
+var TOKEN_TTL_MS = 600 * 1e3;
+function locationKey(location) {
+	return `${location.file}\u0000${location.line}\u0000${location.column}`;
+}
+function compareLocations(left, right) {
+	return compareCodeUnits(left.file, right.file) || left.line - right.line || left.column - right.column || compareCodeUnits(left.label ?? "", right.label ?? "");
+}
+function validateLocation(value, context, allowLabel) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) throw new Error(`${context} must be an object.`);
+	const record = value;
+	if (typeof record.file !== "string" || record.file.length === 0 || !isAbsolute(record.file)) throw new Error(`${context}.file must be an absolute path.`);
+	for (const key of ["line", "column"]) if (!Number.isSafeInteger(record[key]) || record[key] <= 0) throw new Error(`${context}.${key} must be a positive safe integer.`);
+	if (allowLabel && record.label !== void 0 && typeof record.label !== "string") throw new Error(`${context}.label must be a string.`);
+	return {
+		file: record.file,
+		line: record.line,
+		column: record.column,
+		...allowLabel && typeof record.label === "string" ? { label: record.label } : {}
+	};
+}
+function normalizeResult(value, target) {
+	const context = `fundus.config: usage.referenceProvider for ${target.manifest}.${target.assetId}`;
+	try {
+		if (typeof value !== "object" || value === null || Array.isArray(value)) throw new Error(`${context} must return an object.`);
+		const result = value;
+		if (result.status === "unknown") {
+			if (result.reason !== void 0 && typeof result.reason !== "string") throw new Error(`${context} unknown reason must be a string.`);
+			return {
+				status: "unknown",
+				...typeof result.reason === "string" ? { reason: result.reason } : {}
+			};
+		}
+		if (result.status !== "resolved" || !Array.isArray(result.references)) throw new Error(`${context} must return resolved references or unknown.`);
+		const declarationKey = locationKey(target.declaration);
+		const references = result.references.map((reference, index) => validateLocation(reference, `${context} references[${index}]`, true)).filter((reference) => locationKey(reference) !== declarationKey).sort(compareLocations);
+		const deduplicated = [];
+		const seen = /* @__PURE__ */ new Set();
+		for (const reference of references) {
+			const key = locationKey(reference);
+			if (seen.has(key)) continue;
+			seen.add(key);
+			deduplicated.push(reference);
+		}
+		return {
+			status: "resolved",
+			references: deduplicated
+		};
+	} catch (cause) {
+		return {
+			status: "unknown",
+			reason: cause instanceof Error ? cause.message : String(cause)
+		};
+	}
+}
+var FifoLimiter = class {
+	#active = 0;
+	#queue = [];
+	async run(operation) {
+		if (this.#active >= 4) await new Promise((resolve) => this.#queue.push(resolve));
+		this.#active++;
+		try {
+			return await operation();
+		} finally {
+			this.#active--;
+			this.#queue.shift()?.();
+		}
+	}
+};
+var FundusUsageAnalyzer = class {
+	#usage;
+	#secret = randomBytes(32);
+	#limiter = new FifoLimiter();
+	#inflight = /* @__PURE__ */ new Map();
+	#freshGeneration = 0;
+	constructor(usage) {
+		this.#usage = usage;
+	}
+	async analyze(snapshot, options = {}) {
+		if (options.assetId && !Object.hasOwn(snapshot.library.assets, options.assetId)) throw new Error(`Unknown asset "${options.assetId}".`);
+		const rootsToAnalyze = options.assetId ? relevantRootsForAsset(snapshot, options.assetId) : snapshot.roots;
+		const freshKey = options.forceFresh ? `fresh:${++this.#freshGeneration}` : "normal";
+		const rootResults = /* @__PURE__ */ new Map();
+		await Promise.all(rootsToAnalyze.map(async (root) => {
+			const key = rootKey(root);
+			if (!root.declaration) {
+				rootResults.set(key, {
+					status: "unknown",
+					reason: root.declarationError ?? `Cannot locate generated declaration for ${root.manifest}.${root.assetId}.`
+				});
+				return;
+			}
+			const target = {
+				assetId: root.assetId,
+				manifest: root.manifest,
+				declaration: root.declaration
+			};
+			const inflightKey = `${snapshot.revision}|${locationKey(root.declaration)}|${freshKey}`;
+			let run = !options.forceFresh ? this.#inflight.get(inflightKey) : void 0;
+			if (!run) {
+				run = this.#limiter.run(async () => {
+					try {
+						return normalizeResult(await this.#usage.referenceProvider(target), target);
+					} catch (cause) {
+						return {
+							status: "unknown",
+							reason: `usage.referenceProvider failed for ${root.manifest}.${root.assetId}: ${cause instanceof Error ? cause.message : String(cause)}`
+						};
+					}
+				});
+				if (!options.forceFresh) {
+					this.#inflight.set(inflightKey, run);
+					run.finally(() => this.#inflight.delete(inflightKey));
+				}
+			}
+			rootResults.set(key, await run);
+		}));
+		return this.#assemble(snapshot, rootResults, options.assetId);
+	}
+	stale(snapshot, assetId) {
+		const results = /* @__PURE__ */ new Map();
+		for (const root of assetId ? relevantRootsForAsset(snapshot, assetId) : snapshot.roots) results.set(rootKey(root), {
+			status: "unknown",
+			reason: "The Fundus project changed repeatedly during usage analysis; refresh to retry."
+		});
+		return this.#assemble(snapshot, results, assetId);
+	}
+	async open(token) {
+		if (typeof token !== "string" || token.length === 0) throw new Error("Usage location token must be a non-empty string.");
+		const [encoded, signature, extra] = token.split(".");
+		if (!encoded || !signature || extra !== void 0) throw new Error("Invalid usage location token.");
+		const expected = createHmac("sha256", this.#secret).update(encoded).digest();
+		let received;
+		try {
+			received = Buffer.from(signature, "base64url");
+		} catch {
+			throw new Error("Invalid usage location token.");
+		}
+		if (received.length !== expected.length || !timingSafeEqual(received, expected)) throw new Error("Invalid usage location token; refresh usage and try again.");
+		let payload;
+		try {
+			payload = JSON.parse(Buffer.from(encoded, "base64url").toString("utf8"));
+		} catch {
+			throw new Error("Invalid usage location token.");
+		}
+		if (typeof payload !== "object" || payload === null || Array.isArray(payload)) throw new Error("Invalid usage location token.");
+		const record = payload;
+		if (record.v !== 1 || typeof record.expiresAt !== "number" || Date.now() > record.expiresAt) throw new Error("Usage location token expired; refresh usage and try again.");
+		const location = validateLocation(record.location, "Usage location token", false);
+		const normalized = {
+			file: location.file,
+			line: location.line,
+			column: location.column
+		};
+		try {
+			await this.#usage.openLocation(normalized);
+		} catch (cause) {
+			throw new Error(`Could not open ${normalized.file}:${normalized.line}:${normalized.column}: ${cause instanceof Error ? cause.message : String(cause)}`);
+		}
+	}
+	#token(location) {
+		const encoded = Buffer.from(JSON.stringify({
+			v: 1,
+			expiresAt: Date.now() + TOKEN_TTL_MS,
+			location
+		})).toString("base64url");
+		return `${encoded}.${createHmac("sha256", this.#secret).update(encoded).digest("base64url")}`;
+	}
+	#assemble(snapshot, rootResults, requestedAssetId) {
+		const assetIds = requestedAssetId ? [requestedAssetId] : Object.keys(snapshot.library.assets).sort(compareCodeUnits);
+		const analyzedRoots = snapshot.roots.filter((root) => rootResults.has(rootKey(root)));
+		const cyclicNodes = referenceCycleNodes(snapshot.referencesByAsset);
+		const cycleAncestors = reverseClosure(cyclicNodes, snapshot.referencesByAsset);
+		const adjustedResults = /* @__PURE__ */ new Map();
+		for (const root of analyzedRoots) {
+			const result = rootResults.get(rootKey(root));
+			adjustedResults.set(rootKey(root), cycleAncestors.has(root.assetId) && result.status === "resolved" && result.references.length === 0 ? {
+				status: "unknown",
+				reason: "A reference cycle prevents complete usage analysis for this root."
+			} : result);
+		}
+		const usedAssets = referenceClosureFromSources(analyzedRoots.filter((root) => {
+			const result = adjustedResults.get(rootKey(root));
+			return result?.status === "resolved" && result.references.length > 0;
+		}).map((root) => root.assetId), snapshot.referencesByAsset);
+		const unknownAssets = referenceClosureFromSources(analyzedRoots.filter((root) => adjustedResults.get(rootKey(root))?.status === "unknown").map((root) => root.assetId), snapshot.referencesByAsset);
+		return { assets: assetIds.map((assetId) => {
+			const status = usedAssets.has(assetId) ? "used" : unknownAssets.has(assetId) ? "unknown" : "unused";
+			if (!requestedAssetId) return {
+				assetId,
+				status,
+				references: [],
+				roots: []
+			};
+			const groups = [];
+			const pathCountMemo = /* @__PURE__ */ new Map();
+			for (const root of analyzedRoots) {
+				const paths = pathsFromRoot(root.assetId, assetId, snapshot.referencesByAsset, pathCountMemo, cyclicNodes);
+				if (paths.count > 0n) groups.push({
+					root,
+					paths: paths.paths,
+					count: paths.count
+				});
+			}
+			const allReferences = [];
+			for (const group of groups) {
+				const result = adjustedResults.get(rootKey(group.root));
+				if (result?.status === "resolved") allReferences.push(...result.references);
+			}
+			allReferences.sort(compareLocations);
+			const uniqueReferences = [];
+			const referenceIdByKey = /* @__PURE__ */ new Map();
+			for (const reference of allReferences) {
+				const key = locationKey(reference);
+				if (referenceIdByKey.has(key)) continue;
+				const id = `r${uniqueReferences.length}`;
+				referenceIdByKey.set(key, id);
+				uniqueReferences.push(reference);
+			}
+			const roots = groups.map(({ root, paths, count }) => {
+				const result = adjustedResults.get(rootKey(root)) ?? {
+					status: "unknown",
+					reason: "Usage analysis result is missing."
+				};
+				const dtoResult = result.status === "unknown" ? result : {
+					status: "resolved",
+					referenceIds: result.references.map((reference) => referenceIdByKey.get(locationKey(reference))).filter((id) => id !== void 0)
+				};
+				return {
+					manifest: root.manifest,
+					rootAssetId: root.assetId,
+					paths,
+					pathsTruncated: count > BigInt(paths.length),
+					...count > BigInt(paths.length) ? { additionalPathCount: (count - BigInt(paths.length)).toString() } : {},
+					declaration: root.declaration,
+					result: dtoResult
+				};
+			});
+			return {
+				assetId,
+				status,
+				references: uniqueReferences.map((reference, index) => ({
+					...reference,
+					id: `r${index}`,
+					openToken: this.#token(reference)
+				})),
+				roots
+			};
+		}) };
+	}
+};
+function rootKey(root) {
+	return `${root.manifest}\u0000${root.assetId}`;
+}
+function relevantRootsForAsset(snapshot, assetId) {
+	const ancestors = reverseClosure(/* @__PURE__ */ new Set([assetId]), snapshot.referencesByAsset);
+	return snapshot.roots.filter((root) => ancestors.has(root.assetId));
+}
+function reverseClosure(sources, referencesByAsset) {
+	const incoming = /* @__PURE__ */ new Map();
+	for (const [source, references] of Object.entries(referencesByAsset)) for (const target of new Set(references.map((reference) => reference.assetId))) {
+		const sources = incoming.get(target);
+		if (sources) sources.push(source);
+		else incoming.set(target, [source]);
+	}
+	const closure = /* @__PURE__ */ new Set();
+	const pending = [...sources];
+	while (pending.length > 0) {
+		const current = pending.pop();
+		if (closure.has(current)) continue;
+		closure.add(current);
+		pending.push(...incoming.get(current) ?? []);
+	}
+	return closure;
+}
+function referenceClosureFromSources(sources, referencesByAsset) {
+	const closure = /* @__PURE__ */ new Set();
+	const pending = [...sources];
+	while (pending.length > 0) {
+		const current = pending.pop();
+		if (closure.has(current) || !Object.hasOwn(referencesByAsset, current)) continue;
+		closure.add(current);
+		for (const reference of referencesByAsset[current]) pending.push(reference.assetId);
+	}
+	return closure;
+}
+/** Tarjan SCC detection; singleton components count only when they self-reference. */
+function referenceCycleNodes(referencesByAsset) {
+	let nextIndex = 0;
+	const indexByNode = /* @__PURE__ */ new Map();
+	const lowLink = /* @__PURE__ */ new Map();
+	const stack = [];
+	const onStack = /* @__PURE__ */ new Set();
+	const cyclic = /* @__PURE__ */ new Set();
+	const visit = (node) => {
+		indexByNode.set(node, nextIndex);
+		lowLink.set(node, nextIndex++);
+		stack.push(node);
+		onStack.add(node);
+		for (const target of new Set((referencesByAsset[node] ?? []).map((ref) => ref.assetId))) {
+			if (!Object.hasOwn(referencesByAsset, target)) continue;
+			if (!indexByNode.has(target)) {
+				visit(target);
+				lowLink.set(node, Math.min(lowLink.get(node), lowLink.get(target)));
+			} else if (onStack.has(target)) lowLink.set(node, Math.min(lowLink.get(node), indexByNode.get(target)));
+		}
+		if (lowLink.get(node) !== indexByNode.get(node)) return;
+		const component = [];
+		for (;;) {
+			const member = stack.pop();
+			onStack.delete(member);
+			component.push(member);
+			if (member === node) break;
+		}
+		if (component.length > 1 || (referencesByAsset[node] ?? []).some((reference) => reference.assetId === node)) for (const member of component) cyclic.add(member);
+	};
+	for (const node of Object.keys(referencesByAsset)) if (!indexByNode.has(node)) visit(node);
+	return cyclic;
+}
+function pathsFromRoot(root, target, referencesByAsset, countMemo = /* @__PURE__ */ new Map(), cyclicNodes = referenceCycleNodes(referencesByAsset)) {
+	const count = (assetId, visiting) => {
+		if (assetId === target) return 1n;
+		const visitedCyclicNodes = [...visiting].filter((id) => cyclicNodes.has(id)).sort(compareCodeUnits);
+		const memoKey = JSON.stringify([assetId, visitedCyclicNodes]);
+		const cached = countMemo.get(memoKey);
+		if (cached !== void 0) return cached;
+		if (visiting.has(assetId)) return 0n;
+		const nextVisiting = new Set(visiting).add(assetId);
+		let total = 0n;
+		const nextIds = [...new Set((referencesByAsset[assetId] ?? []).map((ref) => ref.assetId))].sort(compareCodeUnits);
+		for (const next of nextIds) total += count(next, nextVisiting);
+		countMemo.set(memoKey, total);
+		return total;
+	};
+	const total = count(root, /* @__PURE__ */ new Set());
+	const paths = [];
+	const collect = (assetId, path, visiting) => {
+		if (paths.length >= MAX_PATHS) return;
+		if (assetId === target) {
+			paths.push(path);
+			return;
+		}
+		if (visiting.has(assetId)) return;
+		const nextVisiting = new Set(visiting).add(assetId);
+		const nextIds = [...new Set((referencesByAsset[assetId] ?? []).map((ref) => ref.assetId))].sort(compareCodeUnits);
+		for (const next of nextIds) {
+			if (count(next, nextVisiting) > 0n) collect(next, [...path, next], nextVisiting);
+			if (paths.length >= MAX_PATHS) break;
+		}
+	};
+	if (total > 0n) collect(root, [root], /* @__PURE__ */ new Set());
+	return {
+		paths,
+		count: total
+	};
+}
+function usageSnapshotRevision(parts) {
+	return createHash("sha256").update(parts.join("\0")).digest("hex");
+}
+//#endregion
 //#region src/lib/server/operations.ts
 /**
 * The one operations layer: builds the state payload and runs
@@ -740,6 +1107,7 @@ var FundusOperations = class {
 	#registry;
 	#store;
 	#importers;
+	#usageAnalyzer;
 	#operationQueue = Promise.resolve();
 	#pipelineQueue = Promise.resolve();
 	constructor(config, registry = serverPluginsByType, importerRegistry = serverImporters) {
@@ -747,6 +1115,7 @@ var FundusOperations = class {
 		this.#registry = registry;
 		this.#store = new LibraryStore(config, registry);
 		this.#importers = importerRegistry;
+		this.#usageAnalyzer = config.usage ? new FundusUsageAnalyzer(config.usage) : null;
 	}
 	get config() {
 		return this.#config;
@@ -754,11 +1123,76 @@ var FundusOperations = class {
 	get store() {
 		return this.#store;
 	}
+	get usageAvailable() {
+		return this.#usageAnalyzer !== null;
+	}
+	async analyzeUsage(options = {}) {
+		const analyzer = this.#usageAnalyzer;
+		if (!analyzer) throw new Error("Usage analysis is not configured.");
+		for (let attempt = 0; attempt < 2; attempt++) {
+			const snapshot = await this.#enqueueOperation(() => this.#usageSnapshot());
+			const report = await analyzer.analyze(snapshot, {
+				...options,
+				forceFresh: options.forceFresh === true || attempt > 0
+			});
+			if ((await this.#enqueueOperation(() => this.#usageSnapshot())).revision === snapshot.revision) return report;
+		}
+		const current = await this.#enqueueOperation(() => this.#usageSnapshot());
+		if (options.assetId && !Object.hasOwn(current.library.assets, options.assetId)) throw new Error(`Unknown asset "${options.assetId}".`);
+		return analyzer.stale(current, options.assetId);
+	}
+	async openUsageLocation(token) {
+		if (!this.#usageAnalyzer) throw new Error("Usage analysis is not configured.");
+		await this.#usageAnalyzer.open(token);
+	}
 	#enqueueOperation(operation) {
 		const run = this.#operationQueue.then(operation, operation);
 		this.#operationQueue = run.then(() => {}, () => {});
 		return run;
 	}
+	async #usageSnapshot() {
+		await this.#pipelineQueue;
+		const library = structuredClone(await this.#store.read());
+		const referencesByAsset = collectAllReferences(library, descriptorsByType(this.#registry));
+		const modules = /* @__PURE__ */ new Map();
+		const roots = [];
+		for (const manifest of Object.keys(library.manifests).sort(compareCodeUnits)) {
+			const rootAssetIds = Object.keys(library.assets).filter((assetId) => library.assets[assetId].manifests.includes(manifest)).sort(compareCodeUnits);
+			if (rootAssetIds.length === 0) continue;
+			const path = join(this.#config.manifestsDir, manifestModuleFileName(manifest));
+			let content;
+			try {
+				content = await readFile(path, "utf8");
+			} catch (cause) {
+				if (cause.code !== "ENOENT") throw cause;
+				content = null;
+			}
+			modules.set(manifest, {
+				content,
+				path
+			});
+			for (const assetId of rootAssetIds) {
+				const declaration = content === null ? null : locateGeneratedAssetDeclaration(path, content, assetId);
+				roots.push({
+					manifest,
+					assetId,
+					declaration,
+					...declaration ? {} : { declarationError: content === null ? `Generated manifest module is missing: ${path}.` : `Generated declaration ${manifest}.${assetId} was not found in ${path}.` }
+				});
+			}
+		}
+		const revisionParts = [serializeLibrary(library)];
+		for (const manifest of [...modules.keys()].sort(compareCodeUnits)) {
+			const module = modules.get(manifest);
+			revisionParts.push(manifest, module.path, module.content ?? "<missing>");
+		}
+		return {
+			revision: usageSnapshotRevision(revisionParts),
+			library,
+			referencesByAsset,
+			roots
+		};
+	}
 	/** Read-only state snapshot, serialized with mutations but never processing or writing. */
 	state() {
 		return this.#enqueueOperation(() => this.#state());
@@ -1517,4 +1951,4 @@ async function createFundusContext() {
 }
 
 export { getFundusContext as g, initializeFundusContext as i };
-//# sourceMappingURL=context.js-mXbNUDBD.js.map
+//# sourceMappingURL=context.js-BJfk3ZiR.js.map