fundus 0.15.0 → 0.17.0

package/dist/server/check.d.ts

@@ -1,10 +1,10 @@
-import { type Library, type ValidationIssueDto } from '../core/index.js';
+import { type EffectiveLibrary, type Library, type LibraryMembership, type MergeProvenance, type ValidationIssueDto } from '../core/index.js';
 import { type RawClassification } from './raw-reconciliation.js';
 import type { ServerPluginRegistry } from './plugins/contract.js';
 /** One machine-readable check finding (the `--json` failure-list shape, M9). */
 export interface CheckFinding {
     /** The failure category. */
-    kind: 'validation' | 'proxy-missing' | 'proxy-unresolvable' | 'proxy-orphaned' | 'module-missing' | 'module-out-of-sync' | 'module-stray' | 'module-regeneration-failed' | 'unreachable-asset' | 'potential-image-duplicate' | 'raw-hash-drift' | 'raw-type-incompatible' | 'raw-scan-incomplete' | 'raw-unmanaged';
+    kind: 'validation' | 'proxy-missing' | 'proxy-unresolvable' | 'proxy-orphaned' | 'module-missing' | 'module-out-of-sync' | 'module-stray' | 'module-regeneration-failed' | 'unreachable-asset' | 'potential-image-duplicate' | 'raw-hash-drift' | 'raw-type-incompatible' | 'raw-scan-incomplete' | 'raw-unmanaged' | 'slot-unfilled' | 'slot-unmaterialized' | 'package-conflict' | 'package-type-mismatch';
     message: string;
     /** The asset the finding concerns, where applicable. */
     assetId?: string;
@@ -26,9 +26,19 @@ export interface CheckReport {
     manifestCount: number;
 }
 export interface CheckAdvisory {
-    kind: 'usage-not-configured';
+    kind: 'usage-not-configured' | 'package-overridden';
     message: string;
+    /** The asset a `package-overridden` advisory concerns. */
+    assetId?: string;
 }
 export declare function runCheck(projectRoot: string, registry?: ServerPluginRegistry): Promise<CheckReport>;
 /** Pure expansion of a raw classification into canonical hard check findings. */
 export declare function rawCheckFindings(library: Library, raw: RawClassification, registry: ServerPluginRegistry, validationIssues: ValidationIssueDto[]): CheckFinding[];
+/**
+ * The delivered-slot contract: a Package slot that is delivered (explicit member
+ * or in a delivered manifest's reference closure) but has no host-supplied bytes
+ * must be filled. A slot with an `importSource` is `slot-unmaterialized` (run
+ * import); a slot with nothing is `slot-unfilled`. Inert (undelivered) slots
+ * produce no finding.
+ */
+export declare function packageSlotFindings(library: EffectiveLibrary, provenance: MergeProvenance, membership: LibraryMembership): CheckFinding[];

package/dist/server/check.js

@@ -10,13 +10,13 @@
 import { existsSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
-import { collectAllReferences, compareCodeUnits, computeLibraryMembership, rawFileNameOfPath, typesForFileName } from '../core/index.js';
+import { allDeliveredAssetIds, collectAllReferences, compareCodeUnits, computeLibraryMembership, flatLibraryIssues, materializeLibrary, mergePackages, rawFileNameOfPath, typesForFileName } from '../core/index.js';
 import { loadConfig, USAGE_NOT_CONFIGURED_MESSAGE } from './config-loader.js';
 import { LibraryStore } from './library-store.js';
 import { classifyRawDirectory } from './raw-reconciliation.js';
-import { buildManifestEntries, manifestModuleFileName, renderManifestModule, strayGeneratedModuleNames } from './codegen.js';
+import { buildManifestEntries, manifestModuleCollisionIssues, manifestModuleFileName, renderManifestModule, strayGeneratedModuleNames } from './codegen.js';
 import { descriptorsByType, serverPluginsByType } from './plugins.js';
-import { deliveredAssetIds, expectedProxyRelativePath, isProxyFileName, readCurrentProxy } from './processing/processor.js';
+import { expectedProxyRelativePath, isProxyFileName, readCurrentProxy } from './processing/processor.js';
 import { listRelativeFiles } from './folder-filesystem.js';
 import { ImageDuplicateDetector } from './image-duplicates.js';
 /** The human rendering of a finding — `[assetId] message`, as `fundus check` prints it. */
@@ -26,18 +26,47 @@ export function formatCheckFinding(finding) {
 export async function runCheck(projectRoot, registry = serverPluginsByType) {
     const config = await loadConfig(projectRoot);
     const store = new LibraryStore(config, registry);
-    const library = await store.read();
+    const host = await store.read();
+    // Merge Packages under the host into one in-memory effective library. Raw
+    // scans stay on the host (it owns the bytes); everything id-space runs over
+    // the effective library; processing/codegen run over the materialized subset.
+    const { library: effective, provenance, findings: mergeFindings } = mergePackages(host, config.packages ?? []);
+    const materialized = materializeLibrary(effective);
     const report = {
         errors: [],
         warnings: [],
         advisories: config.usage === null
             ? [{ kind: 'usage-not-configured', message: USAGE_NOT_CONFIGURED_MESSAGE }]
             : [],
-        assetCount: Object.keys(library.assets).length,
-        manifestCount: Object.keys(library.manifests).length
+        assetCount: Object.keys(effective.assets).length,
+        manifestCount: Object.keys(effective.manifests).length
     };
-    // 1. Library validation (structure, parameters, raw pointers, references).
-    const issues = await store.validate(library);
+    // Merge findings: collisions/type-mismatches are hard errors; an active
+    // override is an auditable, non-fatal advisory.
+    for (const finding of mergeFindings) {
+        if (finding.kind === 'package-overridden') {
+            report.advisories.push({
+                kind: 'package-overridden',
+                message: finding.message,
+                assetId: finding.assetId
+            });
+        }
+        else {
+            report.errors.push({
+                kind: finding.kind,
+                message: finding.message,
+                assetId: finding.assetId
+            });
+        }
+    }
+    // 1. Library validation. Disk/host checks run on the host library; flat-space
+    // checks (id/type/parameters/membership/appearance/references + module
+    // collisions) run over the effective library.
+    const issues = [
+        ...(await store.validate(host, { flatSpace: false })),
+        ...flatLibraryIssues(effective, descriptorsByType(registry)),
+        ...manifestModuleCollisionIssues(effective.manifests)
+    ];
     const validationKeys = new Set();
     for (const issue of issues) {
         const key = `${issue.assetId ?? ''}|${issue.message}`;
@@ -51,16 +80,24 @@ export async function runCheck(projectRoot, registry = serverPluginsByType) {
         });
     }
     const descriptors = Object.values(registry).map((plugin) => plugin.descriptor);
-    const raw = await classifyRawDirectory(config.rawDir, library, (path) => typesForFileName(path, descriptors).length > 0);
-    report.errors.push(...rawCheckFindings(library, raw, registry, issues));
+    const raw = await classifyRawDirectory(config.rawDir, host, (path) => typesForFileName(path, descriptors).length > 0);
+    report.errors.push(...rawCheckFindings(host, raw, registry, issues));
+    // Delivered set + membership over the effective library, so delivered slots
+    // are analysed and cross-Package references resolve.
+    const referencesByAsset = collectAllReferences(effective, descriptorsByType(registry));
+    const membership = computeLibraryMembership(effective, referencesByAsset);
+    const delivered = allDeliveredAssetIds(membership);
+    report.errors.push(...packageSlotFindings(effective, provenance, membership));
     // 2. Proxies: every delivered asset's expected proxy exists (staleness is a
-    // name check), and the proxy directory holds no orphans.
-    const delivered = deliveredAssetIds(library, registry);
+    // name check), and the proxy directory holds no orphans. Raw-less delivered
+    // slots are covered by the slot findings above and skipped here.
     const expectedProxyPaths = new Set();
     const proxies = {};
     let proxiesComplete = true;
     for (const assetId of [...delivered].sort(compareCodeUnits)) {
-        const record = library.assets[assetId];
+        const record = materialized.assets[assetId];
+        if (!record)
+            continue;
         let proxy;
         try {
             proxy = await readCurrentProxy(assetId, record, config, registry);
@@ -108,12 +145,12 @@ export async function runCheck(projectRoot, registry = serverPluginsByType) {
     // regeneration. Only meaningful when validation passed and every proxy
     // exists — otherwise regeneration is impossible and already reported.
     if (report.errors.length === 0 && proxiesComplete) {
-        await checkGeneratedModules(report, library, config, proxies, registry);
-        await checkStrayModules(report, library, config);
+        await checkGeneratedModules(report, materialized, config, proxies, registry);
+        await checkStrayModules(report, materialized, config);
     }
     // 4. Advisory warnings. Raw drift is always a hard CI failure.
-    collectUnreachableAssets(report, library, delivered);
-    collectPotentialImageDuplicates(report, await new ImageDuplicateDetector().find(library, config.rawDir));
+    collectUnreachableAssets(report, effective, provenance, delivered);
+    collectPotentialImageDuplicates(report, await new ImageDuplicateDetector().find(host, config.rawDir));
     report.errors.sort((left, right) => compareCodeUnits(`${left.fileName ?? ''}|${left.assetId ?? ''}|${left.kind}|${left.message}`, `${right.fileName ?? ''}|${right.assetId ?? ''}|${right.kind}|${right.message}`));
     report.warnings.sort((left, right) => compareCodeUnits(`${left.assetId ?? ''}|${left.kind}|${left.message}`, `${right.assetId ?? ''}|${right.kind}|${right.message}`));
     return report;
@@ -254,15 +291,66 @@ async function checkStrayModules(report, library, config) {
  * no explicit membership AND no passive membership in any manifest. An asset
  * that is only passively delivered (referenced by a delivered asset) is fine.
  */
-function collectUnreachableAssets(report, library, delivered) {
+function collectUnreachableAssets(report, library, provenance, delivered) {
+    for (const [assetId, record] of Object.entries(library.assets)) {
+        if (record.manifests.length !== 0 || delivered.has(assetId))
+            continue;
+        // An inert, unfilled Package slot is not a host mistake — a Package ships
+        // a superset of slots and the app delivers a subset. Only host/override
+        // assets (and filled slots) warn.
+        if (record.raw === undefined && provenance[assetId]?.source === 'package')
+            continue;
+        report.warnings.push({
+            kind: 'unreachable-asset',
+            message: 'In no manifest and not referenced by any delivered asset — ' +
+                'nothing is processed or generated for it.',
+            assetId
+        });
+    }
+}
+/**
+ * The delivered-slot contract: a Package slot that is delivered (explicit member
+ * or in a delivered manifest's reference closure) but has no host-supplied bytes
+ * must be filled. A slot with an `importSource` is `slot-unmaterialized` (run
+ * import); a slot with nothing is `slot-unfilled`. Inert (undelivered) slots
+ * produce no finding.
+ */
+export function packageSlotFindings(library, provenance, membership) {
+    const deliveringManifests = new Map();
+    for (const [name, manifestMembership] of Object.entries(membership)) {
+        for (const assetId of manifestMembership.deliveredAssetIds) {
+            const names = deliveringManifests.get(assetId) ?? [];
+            names.push(name);
+            deliveringManifests.set(assetId, names);
+        }
+    }
+    const findings = [];
     for (const [assetId, record] of Object.entries(library.assets)) {
-        if (record.manifests.length === 0 && !delivered.has(assetId)) {
-            report.warnings.push({
-                kind: 'unreachable-asset',
-                message: 'In no manifest and not referenced by any delivered asset — ' +
-                    'nothing is processed or generated for it.',
-                assetId
+        if (record.raw !== undefined)
+            continue;
+        const names = deliveringManifests.get(assetId);
+        if (!names || names.length === 0)
+            continue;
+        const originRecord = provenance[assetId];
+        const origin = originRecord && originRecord.source !== 'host' ? originRecord.origin : 'a package';
+        const deliveredBy = [...names]
+            .sort(compareCodeUnits)
+            .map((name) => `"${name}"`)
+            .join(', ');
+        if (record.importSource !== undefined) {
+            findings.push({
+                kind: 'slot-unmaterialized',
+                assetId,
+                message: `Slot "${assetId}" (from ${origin}) has an import source but no bytes yet — run import to fill it. Delivered by: ${deliveredBy}.`
+            });
+        }
+        else {
+            findings.push({
+                kind: 'slot-unfilled',
+                assetId,
+                message: `Slot "${assetId}" (from ${origin}) has no bytes, import source, or host override. Delivered by: ${deliveredBy}.`
             });
         }
     }
+    return findings;
 }

package/dist/server/cli-commands.d.ts

@@ -6,8 +6,8 @@ export declare const ASSET_HELP = "fundus asset \u2014 inspect and mutate assets
 export declare const ASSET_LIST_HELP: string;
 export declare const ASSET_SHOW_HELP = "fundus asset show \u2014 one asset in detail\n\nUsage: fundus asset show <id> [--json]\n\nPrints the asset's raw file, content hash, parameters, explicit +\npassive manifest memberships, proxy status, reference edges (outgoing\nand incoming), and warnings.\n\nFlags:\n  --json   print {\"ok\": true, \"asset\": <AssetStateDto>}\n  --help   this help\n\nRead-only: nothing is processed or written.\n\nExample:\n  fundus asset show navigationPanel --json\n";
 export declare const ASSET_INGEST_HELP: string;
-export declare const ASSET_REIMPORT_HELP = "fundus asset reimport \u2014 refresh an asset from its saved source\n\nUsage: fundus asset reimport <id> [--json]\n       fundus asset reimport <id> --figma-link <selection-link> [--scale <1|2|3|4>] [--json]\n       fundus asset reimport <id> --scale <1|2|3|4> [--json]\n\nWithout overrides, re-materializes the persisted importer source. Figma\noverrides may update the link, scale, or both; omitted values are preserved.\nAsset type, parameters, folder, manifests, and id remain unchanged. Raw-file\ndrift or concurrent changes abort without overwriting local edits.\n\nFlags:\n  --figma-link <link>  replace the persisted Figma file/node selection\n  --scale <1|2|3|4>    replace the persisted Figma export scale\n  --json               print {\"ok\": true, \"asset\": <AssetStateDto>, \"issues\": [\u2026]}\n  --help               this help\n\nExample:\n  fundus asset reimport navigationPanel\n  fundus asset reimport navigationPanel --figma-link '<new-selection-link>'\n  fundus asset reimport navigationPanel --scale 4\n  fundus asset reimport navigationPanel --figma-link '<new-selection-link>' --scale 4 --json\n";
-export declare const ASSET_REPLACE_HELP = "fundus asset replace \u2014 replace an asset's raw file\n\nUsage: fundus asset replace <id> <file|figma-selection-link>\n                            [--from <file|figma>] [--scale <1|2|3|4>] [--json]\n\nReplaces the stored raw file and content hash while preserving the asset's\nid, type, folder, parameters, references, and manifest memberships. The new\nsource must be accepted by the existing asset type. File replacement remains\nthe default and disconnects any saved source. Figma replacement stores the new\nselection as a repeatable source. Runs the full autosave chain, so delivered\nassets are reprocessed and manifests regenerated.\n\nFlags:\n  --from <file|figma> replacement source; default: file\n  --scale <1|2|3|4>   Figma export scale; default:\n                      import.figma.defaults.scale from fundus.config.ts\n  --json              print {\"ok\": true, \"asset\": <AssetStateDto>, \"issues\": [\u2026]}\n  --help              this help\n\nExample:\n  fundus asset replace navigationPanel ./exports/navigation_panel_v2.png --json\n  fundus asset replace navigationPanel \\\n    'https://www.figma.com/design/abc/UI?node-id=12-34' --from figma --scale 3 --json\n";
+export declare const ASSET_REIMPORT_HELP = "fundus asset reimport \u2014 refresh an asset from its saved source\n\nUsage: fundus asset reimport <id> [--json]\n       fundus asset reimport <id> --figma-link <selection-link> [--scale <1|2|3|4>] [--json]\n       fundus asset reimport <id> --figma-tag <newTag> [--figma-file <key|link>] [--scale <1|2|3|4>] [--json]\n       fundus asset reimport <id> --figma-file <key|link> [--scale <1|2|3|4>] [--json]\n       fundus asset reimport <id> --scale <1|2|3|4> [--json]\n\nWithout overrides, re-materializes the persisted importer source (a Figma tag\nasset re-scans its file for the tagged node, self-healing after node moves).\nA Figma override may update the source or scale; omitted values are preserved.\nAsset type, parameters, folder, and manifests remain unchanged. Raw-file drift\nor concurrent changes abort without overwriting local edits.\n\nNode vs tag assets accept different overrides. A node asset takes --figma-link\n(and --scale); --figma-tag and --figma-file are rejected. A tag asset takes\n--figma-tag to change its tag, --figma-file to re-point in place to another\ndocument, and --scale; --figma-link is rejected. Because the tag IS the asset\nid, changing it with --figma-tag renames the asset to the new tag (the new id\nmust be valid and unused).\n\nFlags:\n  --figma-link <link>  node asset only: replace the persisted file/node selection\n  --figma-tag <newTag> tag asset only: change the tag, renaming the asset to the\n                       new tag (the tag is the asset id)\n  --figma-file <key|link>\n                       tag asset only: re-point in place to another file (raw\n                       key or a Figma link)\n  --scale <1|2|3|4>    replace the persisted Figma export scale\n  --json               print {\"ok\": true, \"asset\": <AssetStateDto>, \"issues\": [\u2026]}\n  --help               this help\n\nExample:\n  fundus asset reimport navigationPanel\n  fundus asset reimport navigationPanel --figma-link '<new-selection-link>'\n  fundus asset reimport navigationPanel --figma-tag mainNavigationPanel\n  fundus asset reimport navigationPanel --figma-file def456\n  fundus asset reimport navigationPanel --scale 4\n  fundus asset reimport navigationPanel --figma-link '<new-selection-link>' --scale 4 --json\n";
+export declare const ASSET_REPLACE_HELP = "fundus asset replace \u2014 replace an asset's raw file\n\nUsage: fundus asset replace <id> <file|figma-selection-link>\n                            [--from <file|figma>] [--scale <1|2|3|4>] [--json]\n       fundus asset replace <id> --from figma --figma-tag <tag>\n                            [--figma-file <key|link>] [--scale <1|2|3|4>] [--json]\n\nReplaces the stored raw file and content hash while preserving the asset's\nid, type, folder, parameters, references, and manifest memberships. The new\nsource must be accepted by the existing asset type. File replacement remains\nthe default and disconnects any saved source. Figma replacement stores the new\nselection (node mode) or tag (tag mode) as a repeatable source. A tag\nreplacement must resolve to the asset's own id, so it can only re-point the\nsame asset's own tag. Runs the full autosave chain, so delivered assets are\nreprocessed and manifests regenerated.\n\nFlags:\n  --from <file|figma> replacement source; default: file\n  --figma-tag <tag>   Figma tag mode: replace from the node tagged with this\n                       Fundus asset id (takes no positional link)\n  --figma-file <key|link>\n                       fileKey for tag mode as a raw key or a Figma link;\n                       defaults to import.figma.defaultFileKey from\n                       fundus.config.ts\n  --scale <1|2|3|4>   Figma export scale; default:\n                      import.figma.defaults.scale from fundus.config.ts\n  --json              print {\"ok\": true, \"asset\": <AssetStateDto>, \"issues\": [\u2026]}\n  --help              this help\n\nExample:\n  fundus asset replace navigationPanel ./exports/navigation_panel_v2.png --json\n  fundus asset replace navigationPanel \\\n    'https://www.figma.com/design/abc/UI?node-id=12-34' --from figma --scale 3 --json\n  fundus asset replace navigationPanel --from figma \\\n    --figma-tag navigationPanel --figma-file abc --scale 3 --json\n";
 export declare const ASSET_SET_HELP = "fundus asset set \u2014 update an asset's parameters and/or memberships\n\nUsage: fundus asset set <id> [--parameters <json>] [--manifests <a,b>]\n                             [--compression-x <0-100>] [--compression-y <0-100>] [--json]\n\nAt least one change flag is required. Runs the full autosave chain\n(write library \u2192 process \u2192 regenerate manifest modules).\n\nFlags:\n  --parameters <json>  SHALLOW MERGE at the top level onto the current\n                       parameters, then plugin validation:\n                         {\"preset\": \"webp-hq\"}        sets one field,\n                                                      keeps the others\n                         {\"chromaKey\": {\u2026}}           replaces the whole\n                                                      chromaKey object\n                         {\"mask\": null}               clears an optional\n                                                      field\n                         {\"mask\": {\"$asset\": \"someImage\"}}\n                                                      sets an asset\n                                                      reference\n  --manifests <a,b>    REPLACES the explicit membership set (declarative,\n                       idempotent); --manifests \"\" clears it\n  --compression-x <0-100>\n  --compression-y <0-100>\n                       set one Slice stretch-compression axis while preserving\n                       the omitted axis; setting both axes to 0 removes\n                       compression. These values override compression supplied\n                       through --parameters in the same invocation\n  --json               print {\"ok\": true, \"asset\": <AssetStateDto>, \"issues\": [\u2026]}\n  --help               this help\n\nThe mutation is validated first and rejected (exit 1, nothing written)\nif it would leave the library invalid \u2014 e.g. a reference to a missing\nasset, a reference cycle, or an unknown manifest name. Ingest reference\ntargets before pointing at them.\n\nExample:\n  fundus asset set navigationPanel --compression-x 75 --compression-y 25 --json\n  fundus asset set characterIdle \\\n    --parameters '{\"mask\": {\"$asset\": \"characterIdleMask\"}}' --json\n";
 export declare const ASSET_RENAME_HELP = "fundus asset rename \u2014 rename an asset id\n\nUsage: fundus asset rename <id> <newId> [--json]\n\nRenames the asset's id (the raw file keeps its name \u2014 ids are the\nstable key) and re-hashes its proxy under the new id via the autosave\nchain. Fails if another asset references <id> \u2014 update the referrers\nfirst \u2014 or if <newId> is taken or invalid.\n\nFlags:\n  --json   print {\"ok\": true, \"asset\": <AssetStateDto>, \"issues\": [\u2026]}\n  --help   this help\n\nExample:\n  fundus asset rename sidebarPanel navigationPanel --json\n";
 export declare const ASSET_DELETE_HELP = "fundus asset delete \u2014 delete an asset\n\nUsage: fundus asset delete <id> [--json]\n\nDeletes the library record, its raw file, and its proxies, then\nregenerates the affected manifest modules. Fails if another asset\nreferences it \u2014 remove the references first.\n\nFlags:\n  --json   print {\"ok\": true, \"deletedAssetId\": \"<id>\", \"issues\": [\u2026]}\n  --help   this help\n\nExample:\n  fundus asset delete obsoleteBanner --json\n";