@waica/cli 0.4.2 → 0.6.0

package/dist/mcp/validation.js

@@ -1,7 +1,10 @@
+import { resolveComponentUpdateSchedule, } from '@waica/engine';
 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 +48,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 { Class, 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 +141,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 +151,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) {
@@ -113,7 +172,7 @@ function validateStateMachines(components, file, ref, context) {
                 }
                 if (typeof on === 'string' && on.startsWith('input:')) {
                     const action = on.slice('input:'.length);
-                    if (!context.bindings[action]?.length) {
+                    if (!isBoundAction(context.bindings, action)) {
                         add(context, 'warning', 'input-action-unbound', `Input action "${action}" has no bindings.`, file, action);
                     }
                 }
@@ -141,11 +200,63 @@ function resolvedEntityComponents(entity, prefab) {
     }));
     return [...inherited, ...componentList(entity.components)];
 }
+function componentUpdateIssueKey(issue) {
+    switch (issue.code) {
+        case 'duplicate-component':
+            return `${issue.code}:${issue.componentName}:${issue.count}`;
+        case 'invalid-update-constraint':
+            return `${issue.code}:${issue.reason}:${issue.declarer}:${issue.target ?? ''}`;
+        case 'component-update-cycle':
+            return `${issue.code}:${issue.componentNames.join('\0')}`;
+    }
+}
+function componentUpdateIssues(components, context) {
+    const result = resolveComponentUpdateSchedule(components.map((component) => component.type), context.componentRegistry);
+    return result.ok ? [] : [...result.issues];
+}
+function addComponentUpdateFinding(issue, file, ref, context) {
+    let findingFile = file;
+    let findingRef = ref;
+    if (issue.code === 'invalid-update-constraint') {
+        const source = context.componentMetadata.get(issue.declarer)?.sourceFile;
+        if (source) {
+            const key = `${source}:${componentUpdateIssueKey(issue)}`;
+            if (context.reportedClassConstraints.has(key))
+                return;
+            context.reportedClassConstraints.add(key);
+            findingFile = source;
+            findingRef = issue.declarer;
+        }
+    }
+    add(context, 'error', issue.code, issue.cause, findingFile, findingRef);
+}
+function validateComponentUpdateSchedule(components, file, ref, context, inheritedIssues = new Set()) {
+    for (const issue of componentUpdateIssues(components, context)) {
+        if (inheritedIssues.has(componentUpdateIssueKey(issue)))
+            continue;
+        addComponentUpdateFinding(issue, file, ref, context);
+    }
+}
+function validateComponentClassUpdateContracts(context) {
+    for (const componentName of Object.keys(context.componentRegistry).sort()) {
+        const metadata = context.componentMetadata.get(componentName);
+        const result = resolveComponentUpdateSchedule([componentName], context.componentRegistry);
+        if (result.ok)
+            continue;
+        for (const issue of result.issues) {
+            if (issue.code !== 'invalid-update-constraint')
+                continue;
+            addComponentUpdateFinding(issue, metadata?.sourceFile ?? 'package.json', componentName, context);
+        }
+    }
+}
 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);
+    validateComponentUpdateSchedule(components, file, ref, context);
 }
 function validateScene(scene, file, prefabs, uiNames, context) {
     const rawEntities = Array.isArray(scene.entities) ? scene.entities : [];
@@ -186,6 +297,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 +355,14 @@ 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);
+        }
+        // A plain prefab instance inherits the prefab-level result already emitted
+        // above. Inline components create a new effective composition; report only
+        // the issues they introduce, not every inherited issue again.
+        if (inline.length > 0) {
+            const inheritedIssues = new Set(componentUpdateIssues(componentList(prefab?.components), context).map(componentUpdateIssueKey));
+            validateComponentUpdateSchedule(effectiveComponents(), file, entityRef, context, inheritedIssues);
         }
     }
 }
@@ -211,7 +380,8 @@ function statBindings(html) {
     }
     return names;
 }
-export async function validateProject(projectPath) {
+export async function validateProject(projectPath, options = {}) {
+    options.signal?.throwIfAborted();
     const check = await requireWaicaProject(projectPath);
     const findings = [];
     const fixedPaths = [
@@ -234,15 +404,32 @@ 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),
+        options.componentLoader
+            ? options.componentLoader.load(projectPath, resolver, { signal: options.signal })
+            : loadProjectComponents(projectPath, resolver, { signal: options.signal }),
     ]);
+    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 +437,28 @@ 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 componentRegistry = {
+        ...manifest.registry.components,
     };
+    const componentMetadata = new Map(Object.entries(componentRegistry).map(([name, Class]) => [
+        name,
+        classMetadata(Class),
+    ]));
+    for (const [name, description] of Object.entries(loadedProjectComponents.components)) {
+        componentRegistry[name] = description.Class;
+        componentMetadata.set(name, {
+            Class: description.Class,
+            params: description.params,
+            defaults: description.defaults,
+            sourceFile: description.file,
+        });
+        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 +473,29 @@ 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,
+        componentRegistry,
+        reportedClassConstraints: new Set(),
+        prefabRefs: new Set(prefabs.keys()),
+        declaredStats,
+        stateFiles,
+        roleStateSources,
+        bindings,
+    };
+    validateComponentClassUpdateContracts(context);
+    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.6.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",
@@ -27,6 +27,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.30.0",
+    "playwright-core": "^1.62.1",
     "three": "^0.185.1"
   }
 }