@waica/cli 0.4.2 → 0.5.0

package/dist/mcp/validation.js

@@ -1,7 +1,9 @@
 import { readFile } from 'node:fs/promises';
 import path from 'node:path';
 import { discoverArchetypes, pickArchetype } from './archetypes.js';
+import { classDefaults, objectRecord } from './component-metadata.js';
 import { PackageResolver, mixedSourceWarnings, provenanceRows, } from './package-resolver.js';
+import { loadProjectComponents } from './project-component-loader.js';
 import { directFiles, requireWaicaProject } from './project-path.js';
 function add(context, severity, code, message, file, ref) {
     context.findings.push({ severity, code, message, file, ...(ref ? { ref } : {}) });
@@ -45,10 +47,63 @@ function componentList(value) {
         return [];
     return value.filter((entry) => !!entry && typeof entry === 'object' && typeof entry.type === 'string');
 }
-function objectRecord(value) {
-    return value && typeof value === 'object' && !Array.isArray(value)
-        ? value
-        : {};
+function classMetadata(Class) {
+    // A throwing constructor has no observable defaults, matching list_components.
+    return { params: Class.params ?? {}, defaults: classDefaults(Class) };
+}
+/** Clip names declared by the sibling AnimatedSprite, or undefined when there is none (no animation contract to check). */
+function siblingClips(siblings) {
+    const animated = siblings.find((component) => component.type === 'AnimatedSprite');
+    return animated ? new Set(Object.keys(objectRecord(animated.props?.clips))) : undefined;
+}
+/** Whether `action` has at least one real binding — an own key, since bindings is keyed by an untrusted string. */
+function isBoundAction(bindings, action) {
+    return Object.hasOwn(bindings, action) && (bindings[action]?.length ?? 0) > 0;
+}
+function validateParamReferences(entries, siblings, file, context) {
+    const clips = siblingClips(siblings);
+    for (const { component, only } of entries) {
+        const metadata = context.componentMetadata.get(component.type);
+        if (!metadata)
+            continue;
+        const props = objectRecord(component.props);
+        for (const [param, spec] of Object.entries(metadata.params)) {
+            if (only && !only.has(param))
+                continue;
+            if (!spec.ref || spec.options !== undefined)
+                continue;
+            const value = Object.hasOwn(props, param) ? props[param] : metadata.defaults[param];
+            if (typeof value !== 'string' || value === '')
+                continue;
+            const field = `${component.type}.${param}`;
+            switch (spec.ref) {
+                case 'prefab':
+                    if (!context.prefabRefs.has(value)) {
+                        add(context, 'error', 'broken-prefab-ref', `Component "${component.type}" param "${param}" references missing prefab "${value}".`, file, field);
+                    }
+                    break;
+                case 'clip':
+                    if (clips && !clips.has(value)) {
+                        add(context, 'error', 'missing-clip', `Component "${component.type}" param "${param}" references missing animation clip "${value}".`, file, field);
+                    }
+                    break;
+                case 'action':
+                    if (!isBoundAction(context.bindings, value)) {
+                        add(context, 
+                        // Consistent with the pre-existing state-transition check for the
+                        // same condition (below): an unbound action is a real gap the
+                        // agent should look at, but not one that flips ok:false.
+                        'warning', 'input-action-unbound', `Component "${component.type}" param "${param}" references unbound input action "${value}".`, file, field);
+                    }
+                    break;
+                case 'stat':
+                    if (!context.declaredStats.has(value)) {
+                        add(context, 'warning', 'undeclared-stat', `Component "${component.type}" param "${param}" references undeclared stat "${value}"; runtime writes may still create it.`, file, field);
+                    }
+                    break;
+            }
+        }
+    }
 }
 function machineStates(component) {
     return objectRecord(component.props?.states);
@@ -85,10 +140,7 @@ function stateCodeExists(role, state, context) {
         (context.roleStateSources.get(role) ?? []).some((source) => roleSourceHasState(source, state)));
 }
 function validateStateMachines(components, file, ref, context) {
-    const animated = components.find((component) => component.type === 'AnimatedSprite');
-    const clips = animated
-        ? new Set(Object.keys(objectRecord(animated.props?.clips)))
-        : undefined;
+    const clips = siblingClips(components);
     for (const machine of components.filter((component) => component.type === 'StateMachine')) {
         const states = machineStates(machine);
         const realNames = Object.keys(states).filter((name) => name !== '*');
@@ -98,9 +150,15 @@ function validateStateMachines(components, file, ref, context) {
             : (realNames[0] ?? '');
         for (const name of realNames) {
             const definition = objectRecord(states[name]);
-            const clip = typeof definition.clip === 'string' ? definition.clip : name;
+            const explicitClip = typeof definition.clip === 'string' ? definition.clip : undefined;
+            const clip = explicitClip ?? name;
+            // No "empty means none" special case here: the runtime looks up
+            // `this.states[state]?.clip ?? state`, and '' survives that nullish
+            // coalesce, so an explicit empty clip is looked up literally and must
+            // be validated like any other explicit value (unlike Collectible.stat,
+            // which the runtime genuinely treats as unset).
             if (clips && !clips.has(clip)) {
-                add(context, 'warning', 'missing-clip', `State "${name}" uses missing animation clip "${clip}".`, file, ref ?? name);
+                add(context, explicitClip === undefined ? 'warning' : 'error', 'missing-clip', `State "${name}" uses missing animation clip "${clip}".`, file, explicitClip === undefined ? (ref ?? name) : `StateMachine.states.${name}.clip`);
             }
             const transitions = Array.isArray(definition.transitions) ? definition.transitions : [];
             for (const transition of transitions) {
@@ -145,6 +203,7 @@ function validatePrefab(prefab, file, ref, context) {
     const components = componentList(prefab.components);
     for (const component of components)
         checkComponent(component, file, ref, context);
+    validateParamReferences(components.map((component) => ({ component })), components, file, context);
     validateStateMachines(components, file, ref, context);
 }
 function validateScene(scene, file, prefabs, uiNames, context) {
@@ -186,6 +245,57 @@ function validateScene(scene, file, prefabs, uiNames, context) {
                 }
             }
         }
+        // Lazily resolved: only computed when a consumer below actually needs
+        // the merged prefab+override component list (an override that changes a
+        // ref param, a clip-context change, an inline ref:clip lookup that needs
+        // the effective sibling AnimatedSprite, or state-machine revalidation).
+        // A plain "prefab: ref" entity with no overrides and no inline
+        // components never pays for building it (restores the pre-typed-refs
+        // laziness that only ran this for state-behavior changes).
+        let cachedEffectiveComponents;
+        const effectiveComponents = () => {
+            cachedEffectiveComponents ??= resolvedEntityComponents(entity, prefab);
+            return cachedEffectiveComponents;
+        };
+        const hasRefKind = (type, kind) => Object.values(context.componentMetadata.get(type)?.params ?? {}).some((spec) => spec.ref === kind && spec.options === undefined);
+        // Undefined scope means "check every declared ref param" — correct for
+        // inline components (never validated elsewhere) and for a component a
+        // clip-context change forces a full recheck of. A Set scopes the check
+        // to only the override's changed params, so a prefab-level finding for
+        // a param the override never touched is not reported a second time
+        // under the scene file.
+        const referenceScopes = new Map();
+        for (const component of inline)
+            referenceScopes.set(component, undefined);
+        const inlineTypes = new Set(inline.map((component) => component.type));
+        for (const [type, rawPatch] of Object.entries(overrides)) {
+            if (inlineTypes.has(type))
+                continue;
+            const metadata = context.componentMetadata.get(type);
+            const patch = objectRecord(rawPatch);
+            const changedRefParams = new Set(Object.entries(metadata?.params ?? {})
+                .filter(([param, spec]) => spec.ref !== undefined && spec.options === undefined && Object.hasOwn(patch, param))
+                .map(([param]) => param));
+            if (changedRefParams.size === 0)
+                continue;
+            const effective = effectiveComponents().find((component) => component.type === type);
+            if (effective && !referenceScopes.has(effective))
+                referenceScopes.set(effective, changedRefParams);
+        }
+        const changesClipContext = inline.some((component) => component.type === 'AnimatedSprite') ||
+            Object.hasOwn(overrides, 'AnimatedSprite');
+        if (changesClipContext) {
+            for (const component of effectiveComponents()) {
+                // A clip-context change can affect params this component didn't
+                // itself change, so this always widens to a full check rather than
+                // narrowing an already-scoped entry from the override loop above.
+                if (hasRefKind(component.type, 'clip'))
+                    referenceScopes.set(component, undefined);
+            }
+        }
+        const needsSiblings = cachedEffectiveComponents !== undefined ||
+            [...referenceScopes.keys()].some((component) => hasRefKind(component.type, 'clip'));
+        validateParamReferences([...referenceScopes.entries()].map(([component, only]) => ({ component, only })), needsSiblings ? effectiveComponents() : [...referenceScopes.keys()], file, context);
         // Re-evaluate inherited state behavior only when this entity actually
         // changes a StateMachine or AnimatedSprite. Unrelated overrides keep the
         // prefab-level finding as the single source of truth.
@@ -193,7 +303,7 @@ function validateScene(scene, file, prefabs, uiNames, context) {
         const changesStateBehavior = inline.some((component) => stateTypes.has(component.type)) ||
             Object.keys(overrides).some((type) => stateTypes.has(type));
         if (changesStateBehavior) {
-            validateStateMachines(resolvedEntityComponents(entity, prefab), file, entityRef, context);
+            validateStateMachines(effectiveComponents(), file, entityRef, context);
         }
     }
 }
@@ -234,15 +344,30 @@ export async function validateProject(projectPath) {
             : null;
     const resolver = new PackageResolver(projectPath);
     const discoveryWarnings = [];
-    const [engine, behaviors, archetypes, projectComponents, roleStateSources] = await Promise.all([
+    const [engine, behaviors, archetypes, projectComponents, roleStateSources, loadedProjectComponents,] = await Promise.all([
         resolver.load('@waica/engine'),
         resolver.load('@waica/behaviors'),
         discoverArchetypes(projectPath, resolver, discoveryWarnings, activeId ? [activeId] : []),
         projectComponentCandidates(projectPath),
         projectRoleStateSources(projectPath),
+        loadProjectComponents(projectPath, resolver),
     ]);
+    for (const failure of loadedProjectComponents.failures) {
+        add({ findings }, 
+        // component-load-unsupported means Node's strip-only loader cannot run
+        // code that can still be perfectly valid in the project's Vite/browser
+        // toolchain (asset imports, TS enums, an old Node host) — that is not a
+        // project defect, so it must not flip a healthy project to ok:false.
+        failure.code === 'component-load-unsupported' ? 'info' : 'error', failure.code, `Cannot execute project module: ${failure.message}`, failure.file);
+    }
     const manifest = pickArchetype(archetypes, activeId, projectPath).manifest;
     const controls = objectRecord(objectRecord(fixed.get('src/controls.json')).bindings);
+    // Bound/unbound is decided from controls.json alone: the shipped runtime
+    // installs exactly controls.json's bindings (template main.ts passes
+    // controls.bindings raw; engine DEFAULT_BINDINGS is {}), so an action an
+    // archetype defines by default but controls.json drops is genuinely
+    // unbound at runtime even though discoverArchetypes never guarantees
+    // manifest.bindings exists (only manifest.id is validated).
     const bindings = {};
     for (const [name, value] of Object.entries(controls)) {
         if (Array.isArray(value) && value.every((entry) => typeof entry === 'string')) {
@@ -250,16 +375,22 @@ export async function validateProject(projectPath) {
         }
     }
     const stateFiles = new Set((await directFiles(path.join(projectPath, 'src/states'), '.ts')).map((file) => file.slice(0, -'.ts'.length)));
-    const context = {
-        findings,
-        manifest,
-        knownComponents: new Set(Object.keys(manifest.registry.components)),
-        projectComponents,
-        stateFiles,
-        roleStateSources,
-        bindings,
-    };
+    const declaredStats = new Set(Object.keys(objectRecord(objectRecord(fixed.get('src/stats.json')).stats)));
+    const componentMetadata = new Map(Object.entries(manifest.registry.components).map(([name, Class]) => [
+        name,
+        classMetadata(Class),
+    ]));
+    for (const [name, description] of Object.entries(loadedProjectComponents.components)) {
+        componentMetadata.set(name, {
+            params: description.params,
+            defaults: description.defaults,
+        });
+        projectComponents.add(name);
+    }
+    // Reconstruct the complete ref set before validating any prefab, so a
+    // lexically earlier file can refer to one discovered later in the tree.
     const prefabs = new Map();
+    const prefabFiles = [];
     for (const [directory, type] of [
         ['characters', 'character'],
         ['objects', 'object'],
@@ -274,12 +405,26 @@ export async function validateProject(projectPath) {
             const ref = `${directory}/${file.slice(0, -suffix.length)}`;
             const prefab = parsed;
             prefabs.set(ref, prefab);
-            validatePrefab(prefab, relative, ref, context);
+            prefabFiles.push({ prefab, relative, ref });
         }
     }
+    const context = {
+        findings,
+        manifest,
+        knownComponents: new Set(Object.keys(manifest.registry.components)),
+        projectComponents,
+        componentMetadata,
+        prefabRefs: new Set(prefabs.keys()),
+        declaredStats,
+        stateFiles,
+        roleStateSources,
+        bindings,
+    };
+    for (const { prefab, relative, ref } of prefabFiles) {
+        validatePrefab(prefab, relative, ref, context);
+    }
     const uiFiles = await directFiles(path.join(projectPath, 'src/ui'), '.html');
     const uiNames = new Set(uiFiles.map((file) => file.slice(0, -'.html'.length)));
-    const declaredStats = new Set(Object.keys(objectRecord(objectRecord(fixed.get('src/stats.json')).stats)));
     for (const file of uiFiles) {
         const relative = `src/ui/${file}`;
         const html = await readFile(path.join(projectPath, relative), 'utf8');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@waica/cli",
-  "version": "0.4.2",
+  "version": "0.5.0",
   "description": "Waica in one command — `npx @waica/cli` opens the editor, `waica mcp` serves the MCP server",
   "license": "MIT",
   "type": "module",
@@ -19,7 +19,7 @@
     "dist"
   ],
   "engines": {
-    "node": ">=20.19"
+    "node": ">=22.18"
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json && node bundle-editor.mjs && node bundle-mcp.mjs",