fundus 0.10.0 → 0.11.1

package/dist/server/codegen.js

@@ -6,10 +6,27 @@
  * for deleted manifests are removed (only files carrying the fundus header).
  */
 import { mkdir, readdir, readFile, unlink, writeFile } from 'node:fs/promises';
-import { join } from 'node:path';
-import { collectAllReferences, compareCodeUnits, computeLibraryMembership, isAssetReference, topologicalReferenceOrder } from '../core/index.js';
+import { isAbsolute, join } from 'node:path';
+import { assetIdError, collectAllReferences, compareCodeUnits, computeLibraryMembership, isAssetReference, topologicalReferenceOrder } from '../core/index.js';
 import { descriptorsByType, serverPluginForType, serverPluginsByType } from './plugins.js';
 export const GENERATED_HEADER = '// generated by fundus — do not edit\n';
+/** Locate a generated top-level manifest member in frozen module source. */
+export function locateGeneratedAssetDeclaration(file, source, assetId) {
+    if (!isAbsolute(file))
+        throw new Error('Generated manifest path must be absolute.');
+    if (assetIdError(assetId))
+        throw new Error(`Cannot locate invalid asset id "${assetId}".`);
+    if (!source.startsWith(GENERATED_HEADER))
+        return null;
+    const lines = source.split('\n');
+    const prefix = `\t${assetId}:`;
+    for (let index = 0; index < lines.length; index++) {
+        if (lines[index].startsWith(prefix)) {
+            return { file, line: index + 1, column: 2 };
+        }
+    }
+    return null;
+}
 /** `mainCatalog` → `main-catalog`. */
 export function kebabCaseFromCamel(name) {
     return name.replace(/([a-z0-9])([A-Z])/g, '$1-$2').toLowerCase();

package/dist/server/config-loader.d.ts

@@ -1,4 +1,4 @@
-import type { AudioPreset, FigmaImportScale, ImagePreset, ResolvedVideoPreset } from '../core/index.js';
+import type { AudioPreset, FigmaImportScale, ImagePreset, ResolvedVideoPreset, UsageConfig } from '../core/index.js';
 import type { ServerPluginRegistry } from './plugins/contract.js';
 export interface ResolvedPresetPluginConfig {
     presets: Record<string, ImagePreset>;
@@ -38,7 +38,9 @@ export interface ResolvedFundusConfig {
             };
         };
     };
+    usage: UsageConfig | null;
 }
+export declare const USAGE_NOT_CONFIGURED_MESSAGE = "Usage analysis is not configured; add usage.referenceProvider and usage.openLocation to fundus.config.ts.";
 /** Pure resolution step (testable without a config file on disk). */
 export declare function resolveConfig(projectRoot: string, value: unknown, registry?: ServerPluginRegistry): ResolvedFundusConfig;
 /** Load `fundus.config.ts` from the host project root. */

package/dist/server/config-loader.js

@@ -8,6 +8,7 @@ import { resolve } from 'node:path';
 import { createJiti } from 'jiti';
 import { serverPluginsByType } from './plugins.js';
 import { isRecord } from './plugins/config.js';
+export const USAGE_NOT_CONFIGURED_MESSAGE = 'Usage analysis is not configured; add usage.referenceProvider and usage.openLocation to fundus.config.ts.';
 function requiredString(config, key) {
     const value = config[key];
     if (typeof value !== 'string' || value.length === 0) {
@@ -70,6 +71,16 @@ export function resolveConfig(projectRoot, value, registry = serverPluginsByType
     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 !== undefined && !isRecord(usage)) {
+        throw new Error('fundus.config: "usage" must be an object.');
+    }
+    if (usage !== undefined && typeof usage.referenceProvider !== 'function') {
+        throw new Error('fundus.config: "usage.referenceProvider" must be a function.');
+    }
+    if (usage !== undefined && 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')),
@@ -83,7 +94,8 @@ export function resolveConfig(projectRoot, value, registry = serverPluginsByType
                 ...(figma.token !== undefined ? { token: figma.token } : {}),
                 defaults: { scale }
             }
-        }
+        },
+        usage: usage === undefined ? null : usage
     };
 }
 /** Load `fundus.config.ts` from the host project root. */

package/dist/server/index.d.ts

@@ -6,10 +6,10 @@ export type { AssetProxyInfo, ProxyOutputInfo, ProcessingReport } from './proces
 export { processAssets, expectedProxyFileName, expectedProxyRelativePath, deliveredAssetIds, isProxyFileName, readProxyOutputInfo } from './processing/processor.js';
 export { ffmpegBinaryPath, runToolchainBinary } from './processing/ffmpeg.js';
 export type { CodegenReport } from './codegen.js';
-export { generateManifestModules } from './codegen.js';
+export { generateManifestModules, locateGeneratedAssetDeclaration, manifestModuleFileName } from './codegen.js';
 export type { BuildReport } from './build.js';
 export { runBuild } from './build.js';
-export type { CheckFinding, CheckReport } from './check.js';
+export type { CheckFinding, CheckAdvisory, CheckReport } from './check.js';
 export { formatCheckFinding, runCheck } from './check.js';
 export type { AssetChangeOptions } from './operations.js';
 export { FundusOperations } from './operations.js';

package/dist/server/index.js

@@ -2,7 +2,7 @@ export { loadConfig, resolveConfig } from './config-loader.js';
 export { LibraryStore } from './library-store.js';
 export { processAssets, expectedProxyFileName, expectedProxyRelativePath, deliveredAssetIds, isProxyFileName, readProxyOutputInfo } from './processing/processor.js';
 export { ffmpegBinaryPath, runToolchainBinary } from './processing/ffmpeg.js';
-export { generateManifestModules } from './codegen.js';
+export { generateManifestModules, locateGeneratedAssetDeclaration, manifestModuleFileName } from './codegen.js';
 export { runBuild } from './build.js';
 export { formatCheckFinding, runCheck } from './check.js';
 export { FundusOperations } from './operations.js';

package/dist/server/operations.d.ts

@@ -1,4 +1,4 @@
-import { type FundusStateDto, type PatchAssetRequestDto, type PatchManifestRequestDto } from '../core/index.js';
+import { type FundusStateDto, type PatchAssetRequestDto, type PatchManifestRequestDto, type UsageAnalysisDto } from '../core/index.js';
 import type { ResolvedFundusConfig } from './config-loader.js';
 import { LibraryStore, type IngestOptions, type ReplaceRawFileOptions } from './library-store.js';
 import type { ServerPluginRegistry } from './plugins/contract.js';
@@ -30,6 +30,12 @@ export declare class FundusOperations {
     constructor(config: ResolvedFundusConfig, registry?: ServerPluginRegistry, importerRegistry?: SourceImporterRegistry);
     get config(): ResolvedFundusConfig;
     get store(): LibraryStore;
+    get usageAvailable(): boolean;
+    analyzeUsage(options?: {
+        assetId?: string;
+        forceFresh?: boolean;
+    }): Promise<UsageAnalysisDto>;
+    openUsageLocation(token: unknown): Promise<void>;
     /** Read-only state snapshot, serialized with mutations but never processing or writing. */
     state(): Promise<FundusStateDto>;
     /** Reconcile only changes that are safe without a user decision: unique moves and deletions. */

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/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;