fundus 0.9.1 → 0.11.0

package/dist/server/operations.js

@@ -5,10 +5,11 @@
  * and the CLI consume this class, so every
  * operation has exactly one implementation and there is no other save path.
  */
+import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
-import { assetIdError, allDeliveredAssetIds, canonicalizeParameters, collectAllReferences, compareCodeUnits, computeLibraryMembership, folderOfRawPath, normalizeFolderPath, parentFolderPath, portableFolderPathKey, proposeAssetId, rawFileNameOfPath, typesForFileName } from '../core/index.js';
+import { assetIdError, allDeliveredAssetIds, canonicalizeParameters, collectAllReferences, compareCodeUnits, computeLibraryMembership, folderOfRawPath, normalizeFolderPath, parentFolderPath, portableFolderPathKey, proposeAssetId, rawFileNameOfPath, serializeLibrary, typesForFileName } from '../core/index.js';
 import { LibraryStore } from './library-store.js';
-import { generateManifestModules } from './codegen.js';
+import { generateManifestModules, locateGeneratedAssetDeclaration, manifestModuleFileName } from './codegen.js';
 import { descriptorsByType, serverPluginForType, serverPluginsByType } from './plugins.js';
 import { processAssets, readCurrentProxy } from './processing/processor.js';
 import { encodeRelativePathForUrl } from './folder-filesystem.js';
@@ -18,6 +19,7 @@ import { serverImporters } from './importers.js';
 import { SourceImportError } from './importers/contract.js';
 import { validateFigmaSourceParameters } from './importers/figma.js';
 import { currentGitBranch, gitAssetChanges } from './git.js';
+import { FundusUsageAnalyzer, usageSnapshotRevision } from './usage.js';
 /**
  * The CLI's `--parameters` merge semantics (M7): a SHALLOW merge at the top
  * level onto the current parameters — a nested object value replaces the whole
@@ -54,6 +56,7 @@ export class FundusOperations {
     #registry;
     #store;
     #importers;
+    #usageAnalyzer;
     #operationQueue = Promise.resolve();
     #pipelineQueue = Promise.resolve();
     constructor(config, registry = serverPluginsByType, importerRegistry = serverImporters) {
@@ -61,6 +64,7 @@ export class FundusOperations {
         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;
@@ -68,11 +72,90 @@ export class FundusOperations {
     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
+            });
+            const current = await this.#enqueueOperation(() => this.#usageSnapshot());
+            if (current.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 = 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());

package/dist/server/plugins/audio.js

@@ -36,6 +36,7 @@ export const audioServerPlugin = {
     buildManifestEntry: ({ src, proxy }) => ({
         kind: 'audio',
         src,
+        byteSize: proxy.fileSize,
         durationMs: requireProxyField(proxy, 'durationMs')
     })
 };

package/dist/server/plugins/chroma-key-video.js

@@ -30,6 +30,7 @@ export const chromaKeyVideoServerPlugin = {
     buildManifestEntry: ({ parameters, src, proxy }) => ({
         kind: 'chroma-key-video',
         src,
+        byteSize: proxy.fileSize,
         width: requireProxyField(proxy, 'width'),
         height: requireProxyField(proxy, 'height'),
         durationMs: requireProxyField(proxy, 'durationMs'),

package/dist/server/plugins/image.js

@@ -37,6 +37,7 @@ export const imageServerPlugin = {
     buildManifestEntry: ({ src, proxy }) => ({
         kind: 'image',
         src,
+        byteSize: proxy.fileSize,
         width: requireProxyField(proxy, 'width'),
         height: requireProxyField(proxy, 'height')
     })

package/dist/server/plugins/slice.js

@@ -80,6 +80,7 @@ export const sliceServerPlugin = {
         return {
             kind: 'slice',
             src,
+            byteSize: proxy.fileSize,
             slicing,
             sourceWidth,
             sourceHeight

package/dist/server/plugins/video.js

@@ -55,6 +55,7 @@ export const videoServerPlugin = {
     buildManifestEntry: ({ src, proxy }) => ({
         kind: 'video',
         src,
+        byteSize: proxy.fileSize,
         width: requireProxyField(proxy, 'width'),
         height: requireProxyField(proxy, 'height'),
         durationMs: requireProxyField(proxy, 'durationMs')

package/dist/server/start.d.ts

@@ -1,3 +1,4 @@
+import type { FundusServer } from './server.js';
 export declare const DEFAULT_PORT = 7583;
 interface StartBannerOptions {
     port: number;
@@ -9,6 +10,13 @@ export interface RunStartOptions {
     openBrowser?: boolean;
     port?: number;
 }
+/** Bootstrap the real server context and distinguish optional absence from route failure. */
+export declare function probeUsageCapability(editorUrl: string, fetcher?: typeof fetch): Promise<boolean>;
+/** Probe the started server, warning on optional absence and cleaning up on failure. */
+export declare function bootstrapUsageCapability(editorUrl: string, server: FundusServer, options?: {
+    fetcher?: typeof fetch;
+    warn?: (message: string) => void;
+}): Promise<void>;
 /** Format the human startup summary without pulling a terminal UI dependency into the CLI. */
 export declare function formatStartBanner({ port, projectRoot, color, terminalWidth }: StartBannerOptions): string;
 export declare function runStart(projectRoot: string, { openBrowser, port }?: RunStartOptions): Promise<void>;

package/dist/server/start.js

@@ -4,7 +4,30 @@ import { resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import open from 'open';
 import { startServer } from './server.js';
+import { USAGE_NOT_CONFIGURED_MESSAGE } from './config-loader.js';
 export const DEFAULT_PORT = 7583;
+/** Bootstrap the real server context and distinguish optional absence from route failure. */
+export async function probeUsageCapability(editorUrl, fetcher = fetch) {
+    const response = await fetcher(`${editorUrl}/api/usage`, { method: 'HEAD' });
+    const header = response.headers.get('x-fundus-usage-capability');
+    if (response.status === 204 && header === 'available')
+        return true;
+    if (response.status === 404 && header === 'unavailable')
+        return false;
+    throw new Error(`Fundus usage capability bootstrap failed (${response.status}, capability ${header ?? 'missing'}).`);
+}
+/** Probe the started server, warning on optional absence and cleaning up on failure. */
+export async function bootstrapUsageCapability(editorUrl, server, options = {}) {
+    try {
+        if (!(await probeUsageCapability(editorUrl, options.fetcher))) {
+            (options.warn ?? console.warn)(USAGE_NOT_CONFIGURED_MESSAGE);
+        }
+    }
+    catch (cause) {
+        await server.stop();
+        throw cause;
+    }
+}
 function ansi(code, value, enabled) {
     return enabled ? `\u001b[${code}m${value}\u001b[0m` : value;
 }
@@ -81,6 +104,7 @@ export async function runStart(projectRoot, { openBrowser = true, port = DEFAULT
     }
     const server = await startServer({ handler: module.handler, port });
     const editorUrl = `http://127.0.0.1:${server.port}`;
+    await bootstrapUsageCapability(editorUrl, server);
     console.log(formatStartBanner({
         port: server.port,
         projectRoot: resolvedProjectRoot,

package/dist/server/usage.d.ts

@@ -0,0 +1,24 @@
+import type { Library, ReferencesByAsset, SourceLocation, UsageAnalysisDto, UsageConfig } from '../core/index.js';
+export interface UsageSnapshotRoot {
+    manifest: string;
+    assetId: string;
+    declaration: SourceLocation | null;
+    declarationError?: string;
+}
+export interface UsageAnalysisSnapshot {
+    revision: string;
+    library: Library;
+    referencesByAsset: ReferencesByAsset;
+    roots: UsageSnapshotRoot[];
+}
+export declare class FundusUsageAnalyzer {
+    #private;
+    constructor(usage: UsageConfig);
+    analyze(snapshot: UsageAnalysisSnapshot, options?: {
+        assetId?: string;
+        forceFresh?: boolean;
+    }): Promise<UsageAnalysisDto>;
+    stale(snapshot: UsageAnalysisSnapshot, assetId?: string): UsageAnalysisDto;
+    open(token: unknown): Promise<void>;
+}
+export declare function usageSnapshotRevision(parts: readonly string[]): string;