@neocompose/cli 0.11.1 → 0.12.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## [0.12.0] - 2026-07-28
+
+### Added
+
+- Warn on `neo push` when an animation clip's owning class is also
+  instantiated as a nested `Children` row. P41 lets the players skip a child
+  reference they cannot resolve instead of throwing, which would otherwise
+  make one real defect silent: a nested row's own children are re-lowered
+  copies, so a clip naming its owner's class-default rows resolves none of
+  them on that instance. The advisory names the clip and the nested use site
+  it found, and points at authored provenance for nested rows (P44) or a
+  constructor (P43) as the fix. It never blocks the push, and it is removed
+  when P44 lands. `neo push --json`, `neo status --json` and `neo diff --json`
+  carry the same text in a new `warnings` array, separate from the blocking
+  `diagnostics`.
+
 ## [0.11.1] - 2026-07-27
 
 ### Fixed

package/dist/neo.mjs

@@ -36062,6 +36062,14 @@ var init_world_system_classes_generated = __esm({
             defaultValue: { x: 1, y: 1, z: 0 },
             required: true,
             schemaKey: "Size"
+          },
+          {
+            memberId: "system_4858148e-1c42-449d-8a03-c1601da529bd",
+            memberKind: "bool",
+            defaultValue: true,
+            docsText: "When false, this object and its children are neither rendered nor collided with. The value stays live: member writes still apply and a running animation clip keeps playing. Disabling an object hides its whole subtree regardless of each child's own value, and re-enabling it restores exactly what was there.",
+            required: true,
+            schemaKey: "Enabled"
           }
         ],
         worldKind: "objectBase"
@@ -47699,6 +47707,24 @@ function assertAnimationClipDocumentValid(document) {
     context.validateClipMember(member);
   }
 }
+function collectAnimationClipNestedOwnerWarnings(document) {
+  try {
+    return new AnimationValidationContext(
+      document
+    ).collectNestedOwnerWarnings();
+  } catch {
+    return [];
+  }
+}
+function compareNestedChildrenRowUseSites(left, right) {
+  if (left.ownerClassName !== right.ownerClassName) {
+    return left.ownerClassName < right.ownerClassName ? -1 : 1;
+  }
+  if (left.rowValueId !== right.rowValueId) {
+    return left.rowValueId < right.rowValueId ? -1 : 1;
+  }
+  return 0;
+}
 function isRecord3(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -48268,13 +48294,19 @@ var init_animation_clips = __esm({
         return typeof member.valueId === "string" ? this.valueById.get(member.valueId) ?? null : null;
       }
       memberRootNode(member) {
-        const value = member.defaultValue?.value;
+        const node = this.optionalMemberRootNode(member);
+        if (node === null) {
+          throw new Error(
+            `Animation clip "${member.name}" must have a composite default-value graph.`
+          );
+        }
+        return node;
+      }
+      /** {@link memberRootNode} without the throw, for diagnostics-only readers. */
+      optionalMemberRootNode(member) {
         if (member.defaultValue !== void 0) {
-          if (!isRecord3(value)) {
-            throw new Error(
-              `Animation clip "${member.name}" must have a composite default-value graph.`
-            );
-          }
+          const value = member.defaultValue.value;
+          if (!isRecord3(value)) return null;
           return {
             id: `member-default:${member.id}`,
             projectId: member.projectId,
@@ -48285,13 +48317,8 @@ var init_animation_clips = __esm({
           };
         }
         const valueId = member.valueId;
-        if (typeof valueId === "string") {
-          const stored = this.valueById.get(valueId);
-          if (stored !== void 0) return stored;
-        }
-        throw new Error(
-          `Animation clip "${member.name}" must have a composite default-value graph.`
-        );
+        if (typeof valueId !== "string") return null;
+        return this.valueById.get(valueId) ?? null;
       }
       optionalFieldNode(parent, classId, memberId) {
         const field = this.field(classId, memberId);
@@ -48315,35 +48342,45 @@ var init_animation_clips = __esm({
       }
       requireListField(parent, classId, memberId, label) {
         const field = this.requireField(classId, memberId, label);
+        const ids = this.listFieldIds(parent, field);
+        if (!Array.isArray(ids)) {
+          throw new Error(`${label} must be an ordered list.`);
+        }
+        const inferredClassId = this.listEntryClassId(field.member);
+        return ids.map((id2) => {
+          if (typeof id2 !== "string" || !this.valueById.has(id2)) {
+            throw new Error(`${label} references missing entry "${String(id2)}".`);
+          }
+          const entry = this.valueById.get(id2);
+          return typeof entry.classId === "string" || inferredClassId === void 0 ? entry : { ...entry, classId: inferredClassId };
+        });
+      }
+      /**
+       * The raw list payload behind a field: an explicit instance edge wins even
+       * when it is dangling, then the member default, then the legacy value row.
+       */
+      listFieldIds(parent, field) {
         const mapped = isRecord3(parent.value) ? parent.value[field.schemaKey] : null;
-        let ids;
         if (typeof mapped === "string") {
-          ids = this.valueById.get(mapped)?.value;
-        } else if (field.member.defaultValue !== void 0) {
-          ids = field.member.defaultValue.value;
-        } else {
-          ids = typeof field.member.valueId === "string" ? this.valueById.get(field.member.valueId)?.value : void 0;
+          return this.valueById.get(mapped)?.value;
         }
-        if (!Array.isArray(ids)) {
-          throw new Error(`${label} must be an ordered list.`);
+        if (field.member.defaultValue !== void 0) {
+          return field.member.defaultValue.value;
         }
+        return typeof field.member.valueId === "string" ? this.valueById.get(field.member.valueId)?.value : void 0;
+      }
+      /** Class a list's rows carry when a row omits its own `classId`. */
+      listEntryClassId(member) {
         const listMember = {
-          ...field.member,
-          ...resolveMember2(field.member, this.document.members)
+          ...member,
+          ...resolveMember2(member, this.document.members)
         };
         const entryMember = isMemberList(listMember) ? this.memberById.get(listMember.entryMemberId) : void 0;
         const resolvedEntryMember = entryMember === void 0 ? void 0 : {
           ...entryMember,
           ...resolveMember2(entryMember, this.document.members)
         };
-        const inferredClassId = isMemberClass(resolvedEntryMember) ? resolvedEntryMember.classId : void 0;
-        return ids.map((id2) => {
-          if (typeof id2 !== "string" || !this.valueById.has(id2)) {
-            throw new Error(`${label} references missing entry "${String(id2)}".`);
-          }
-          const entry = this.valueById.get(id2);
-          return typeof entry.classId === "string" || inferredClassId === void 0 ? entry : { ...entry, classId: inferredClassId };
-        });
+        return isMemberClass(resolvedEntryMember) ? resolvedEntryMember.classId : void 0;
       }
       requireSingleLookupField(parent, classId, memberId, label) {
         const value = this.scalarField(parent, classId, memberId);
@@ -48388,18 +48425,23 @@ var init_animation_clips = __esm({
         return node.classId;
       }
       requireClassBinding(member, paramId, label) {
+        const classId = this.optionalClassBinding(member, paramId);
+        if (classId === null) {
+          throw new Error(
+            `${label} must bind its target generic to a Class member.`
+          );
+        }
+        return classId;
+      }
+      /** {@link requireClassBinding} without the throw, for diagnostics-only readers. */
+      optionalClassBinding(member, paramId) {
         const binding = resolveInstanceEnv(
           member.classId,
           member.classArguments,
           this.document.classes
         ).get(paramId);
         const bindingMember = binding?.kind === "member" ? this.memberById.get(binding.memberId) : void 0;
-        if (!isMemberClass(bindingMember)) {
-          throw new Error(
-            `${label} must bind its target generic to a Class member.`
-          );
-        }
-        return bindingMember.classId;
+        return isMemberClass(bindingMember) ? bindingMember.classId : null;
       }
       requireClassMember(value) {
         if (!isMemberClass(value)) throw new Error("Expected Class member.");
@@ -48436,6 +48478,188 @@ var init_animation_clips = __esm({
         }
         return false;
       }
+      // ---------------------------------------------------------------------------
+      // P41 §2.3 SCAFFOLDING — DELETE EVERYTHING BELOW THIS BANNER WHEN P44 LANDS,
+      // together with `collectAnimationClipNestedOwnerWarnings` and its tests. See
+      // that function's doc block for why the check exists and why P44 retires it.
+      // ---------------------------------------------------------------------------
+      collectNestedOwnerWarnings() {
+        const useSiteByClassId = this.nestedChildrenRowUseSites();
+        if (useSiteByClassId.size === 0) return [];
+        const warnings = [];
+        for (const member of this.document.members) {
+          if (!isMemberClass(member)) continue;
+          if (!this.classHasWorldKind(member.classId, "animationClip")) continue;
+          const ownerClassId2 = this.optionalClassBinding(
+            member,
+            WORLD_ANIMATION_CLIP_TARGET_PARAM_ID
+          );
+          if (ownerClassId2 === null) continue;
+          const useSite = useSiteByClassId.get(ownerClassId2);
+          if (useSite === void 0) continue;
+          if (!this.clipDeclaresChildReferences(member)) continue;
+          const ownerClassName = this.classById.get(ownerClassId2)?.name ?? ownerClassId2;
+          const nestedRowClassName = this.classById.get(useSite.rowClassId)?.name ?? useSite.rowClassId;
+          const nesting = useSite.rowClassId === ownerClassId2 ? "which is also used as a nested Children row" : `whose subclass "${nestedRowClassName}" is used as a nested Children row`;
+          warnings.push({
+            clipName: member.name,
+            ownerClassName,
+            nestedOwnerClassName: useSite.ownerClassName,
+            nestedRowClassName,
+            nestedRowValueId: useSite.rowValueId,
+            message: `Animation clip "${member.name}" overrides or tracks children of "${ownerClassName}", ${nesting} (value "${useSite.rowValueId}" in class "${useSite.ownerClassName}"). A nested instance carries re-lowered copies of those rows, so the clip resolves none of them there. Give nested Children rows authored provenance (P44), or declare the child rows through a constructor (P43).`
+          });
+        }
+        return warnings;
+      }
+      /**
+       * Every class an authored `Children` list instantiates as a row, keyed by
+       * that class and each of its ancestors — a nested row of a subclass inherits
+       * the base class's clips, so the base is affected too.
+       *
+       * Both authoring shapes count. A class-default `Children` is one; a
+       * `Children` list authored on a row inside one is the other, and it is the
+       * shape P41 §3 itself writes — `CharacterBody.Children` holds a `HeadPart`
+       * row whose own `Children` holds the hat. Scanning only class defaults would
+       * miss every slot below the first level.
+       *
+       * A layer's directly placed objects hang off `NeoObjectLayerLink.Objects`, a
+       * different member, so a directly placed class is never collected here.
+       */
+      nestedChildrenRowUseSites() {
+        const declaringClasses = /* @__PURE__ */ new Map();
+        for (const schemaClass2 of this.document.classes) {
+          for (const [schemaKey, memberId] of Object.entries(schemaClass2.schema)) {
+            if (typeof memberId !== "string") continue;
+            if (declaringClasses.has(memberId)) continue;
+            declaringClasses.set(memberId, { schemaClass: schemaClass2, schemaKey });
+          }
+        }
+        const sites = [];
+        const pending = [];
+        for (const member of this.document.members) {
+          if (!this.memberDescendsFrom(member.id, WORLD_OBJECT_CHILDREN_MEMBER_ID)) {
+            continue;
+          }
+          const declaration = declaringClasses.get(member.id);
+          if (declaration === void 0) continue;
+          const node = this.resolveDefinitionChild(
+            null,
+            declaration.schemaKey,
+            member
+          );
+          pending.push(
+            ...this.childrenRowUseSites(node, member, declaration.schemaClass.name)
+          );
+        }
+        const visited = /* @__PURE__ */ new Set();
+        for (let index = 0; index < pending.length; index += 1) {
+          const site = pending[index];
+          if (site === void 0) continue;
+          if (visited.has(site.rowValueId)) continue;
+          visited.add(site.rowValueId);
+          sites.push(site);
+          const row = this.valueById.get(site.rowValueId);
+          if (row === void 0) continue;
+          const field = this.field(
+            site.rowClassId,
+            WORLD_OBJECT_CHILDREN_MEMBER_ID
+          );
+          if (field === null) continue;
+          const rowClassName = this.classById.get(site.rowClassId)?.name ?? site.rowClassId;
+          pending.push(
+            ...this.childrenRowUseSites(
+              { ...row, value: this.listFieldIds(row, field) },
+              field.member,
+              rowClassName
+            )
+          );
+        }
+        sites.sort(compareNestedChildrenRowUseSites);
+        const useSiteByClassId = /* @__PURE__ */ new Map();
+        for (const site of sites) {
+          if (useSiteByClassId.has(site.rowClassId)) continue;
+          useSiteByClassId.set(site.rowClassId, site);
+        }
+        for (const site of sites) {
+          for (const classId of this.classAndAncestorIds(site.rowClassId)) {
+            if (useSiteByClassId.has(classId)) continue;
+            useSiteByClassId.set(classId, site);
+          }
+        }
+        return useSiteByClassId;
+      }
+      /** The rows an authored `Children` list holds, as use sites of `ownerClassName`. */
+      childrenRowUseSites(node, listMember, ownerClassName) {
+        if (!Array.isArray(node?.value)) return [];
+        const entryClassId = this.listEntryClassId(listMember);
+        const sites = [];
+        for (const rowValueId of node.value) {
+          if (typeof rowValueId !== "string") continue;
+          const row = this.valueById.get(rowValueId);
+          const rowClassId = typeof row?.classId === "string" ? row.classId : entryClassId;
+          if (rowClassId === void 0) continue;
+          sites.push({ ownerClassName, rowValueId, rowClassId });
+        }
+        return sites;
+      }
+      /** True when the clip names at least one child through a track or override. */
+      clipDeclaresChildReferences(clipMember) {
+        const clipNode = this.optionalMemberRootNode(clipMember);
+        if (clipNode === null) return false;
+        const tracks = this.optionalListRows(
+          clipNode,
+          clipMember.classId,
+          WORLD_ANIMATION_CLIP_TRACKS_MEMBER_ID
+        );
+        if (tracks !== null && tracks.length > 0) return true;
+        const frames = this.optionalListRows(
+          clipNode,
+          clipMember.classId,
+          WORLD_ANIMATION_CLIP_FRAMES_MEMBER_ID
+        ) ?? [];
+        for (const frame of frames) {
+          if (typeof frame.classId !== "string") continue;
+          const childOverrides = this.optionalListRows(
+            frame,
+            frame.classId,
+            WORLD_ANIMATION_FRAME_CHILD_OVERRIDES_MEMBER_ID
+          );
+          if (childOverrides !== null && childOverrides.length > 0) return true;
+        }
+        return false;
+      }
+      /** {@link requireListField} without the throws, for diagnostics-only readers. */
+      optionalListRows(parent, classId, memberId) {
+        const field = this.field(classId, memberId);
+        if (field === null) return null;
+        const ids = this.listFieldIds(parent, field);
+        if (!Array.isArray(ids)) return null;
+        const inferredClassId = this.listEntryClassId(field.member);
+        const rows = [];
+        for (const id2 of ids) {
+          if (typeof id2 !== "string") return null;
+          const entry = this.valueById.get(id2);
+          if (entry === void 0) return null;
+          rows.push(
+            typeof entry.classId === "string" || inferredClassId === void 0 ? entry : { ...entry, classId: inferredClassId }
+          );
+        }
+        return rows;
+      }
+      /** The class itself followed by every ancestor it extends. */
+      classAndAncestorIds(classId) {
+        const ids = [];
+        const visited = /* @__PURE__ */ new Set();
+        let current = this.classById.get(classId);
+        if (current === void 0) return [classId];
+        while (current !== void 0 && !visited.has(current.id)) {
+          visited.add(current.id);
+          ids.push(current.id);
+          current = current.extendsClassId ? this.classById.get(current.extendsClassId) : void 0;
+        }
+        return ids;
+      }
     };
   }
 });
@@ -48714,6 +48938,7 @@ function compareWorkspacePaths(left, right) {
 function computeWorkspaceStatus(workspace, options = {}) {
   const conflictedFiles = [];
   const parseErrors = [];
+  const warnings = [];
   const migrationSources = [];
   const projectSources = [];
   const sourceEntries = options.virtualSourceFiles === void 0 ? listProjectSourceFilesV4(workspace.root).map((filePath) => ({
@@ -48743,6 +48968,7 @@ function computeWorkspaceStatus(workspace, options = {}) {
       changes: [],
       conflictedFiles,
       parseErrors,
+      warnings,
       reconstructed: /* @__PURE__ */ new Map(),
       staticValueSeeds: /* @__PURE__ */ new Map(),
       binaryChanges: [],
@@ -48791,6 +49017,7 @@ function computeWorkspaceStatus(workspace, options = {}) {
         changes: [],
         conflictedFiles,
         parseErrors,
+        warnings,
         reconstructed: /* @__PURE__ */ new Map(),
         staticValueSeeds,
         binaryChanges: [],
@@ -48815,6 +49042,7 @@ function computeWorkspaceStatus(workspace, options = {}) {
         changes: [],
         conflictedFiles,
         parseErrors,
+        warnings,
         reconstructed: /* @__PURE__ */ new Map(),
         staticValueSeeds,
         binaryChanges: [],
@@ -48862,6 +49090,7 @@ function computeWorkspaceStatus(workspace, options = {}) {
       changes: [],
       conflictedFiles,
       parseErrors,
+      warnings,
       reconstructed: /* @__PURE__ */ new Map(),
       staticValueSeeds: /* @__PURE__ */ new Map(),
       binaryChanges: [],
@@ -49078,15 +49307,16 @@ function computeWorkspaceStatus(workspace, options = {}) {
   )) {
     parseErrors.push(new SchemaSourceError(message, "<project-files>", 1, 1));
   }
+  let validatedAnimationRecords = null;
   try {
-    validateProspectiveAnimationRecordsV4(
-      prospectiveAnimationRecords(
-        workspace.state.records,
-        reconstructed3,
-        changes,
-        staticValueSeeds
-      )
+    const animationRecords = prospectiveAnimationRecords(
+      workspace.state.records,
+      reconstructed3,
+      changes,
+      staticValueSeeds
     );
+    validateProspectiveAnimationRecordsV4(animationRecords);
+    validatedAnimationRecords = animationRecords;
   } catch (error) {
     parseErrors.push(
       new SchemaSourceError(
@@ -49097,6 +49327,11 @@ function computeWorkspaceStatus(workspace, options = {}) {
       )
     );
   }
+  if (validatedAnimationRecords !== null) {
+    warnings.push(
+      ...collectProspectiveAnimationWarningsV4(validatedAnimationRecords)
+    );
+  }
   for (const binary of binaryChanges) {
     if (binary.action !== "missing-local") continue;
     parseErrors.push(
@@ -49112,6 +49347,7 @@ function computeWorkspaceStatus(workspace, options = {}) {
     changes,
     conflictedFiles,
     parseErrors,
+    warnings,
     reconstructed: reconstructed3,
     staticValueSeeds,
     binaryChanges,
@@ -49119,11 +49355,27 @@ function computeWorkspaceStatus(workspace, options = {}) {
   };
 }
 function validateProspectiveAnimationRecordsV4(records2) {
+  const document = prospectiveAnimationDocumentV4(records2);
+  if (document === null) return;
+  assertAnimationClipDocumentValid(document);
+}
+function collectProspectiveAnimationWarningsV4(records2) {
+  try {
+    const document = prospectiveAnimationDocumentV4(records2);
+    if (document === null) return [];
+    return collectAnimationClipNestedOwnerWarnings(document).map(
+      (warning) => warning.message
+    );
+  } catch {
+    return [];
+  }
+}
+function prospectiveAnimationDocumentV4(records2) {
   const candidates = [...records2];
   const hasAnimationSchema = candidates.some(
     (record3) => record3.recordKind === "class" && (Array.isArray(record3.data.constructorProjections) || isObjectRecord2(record3.data.system) && typeof record3.data.system.worldKind === "string" && record3.data.system.worldKind.startsWith("animation"))
   );
-  if (!hasAnimationSchema) return;
+  if (!hasAnimationSchema) return null;
   let project;
   const classes = [];
   const members = [];
@@ -49159,8 +49411,8 @@ function validateProspectiveAnimationRecordsV4(records2) {
       values.push(record3.data);
     }
   }
-  if (project === void 0) return;
-  assertAnimationClipDocumentValid({ project, classes, members, values });
+  if (project === void 0) return null;
+  return { project, classes, members, values };
 }
 function serverEnvelope(stored) {
   if (!isObjectRecord2(stored)) return {};
@@ -67829,6 +68081,9 @@ ${blockingErrors.map((error) => `  ${error.message}`).join("\n")}`
     changes: status.changes,
     binaryChanges: status.binaryChanges ?? []
   });
+  if (options.json !== true) {
+    for (const message of status.warnings) warn(message);
+  }
   if (status.changes.length === 0) {
     if (options.json === true) {
       console.log(
@@ -67837,7 +68092,8 @@ ${blockingErrors.map((error) => `  ${error.message}`).join("\n")}`
           dryRun: options.dryRun,
           changeCount: 0,
           staticValueSeedCount: 0,
-          changes: []
+          changes: [],
+          warnings: status.warnings
         })
       );
     } else {
@@ -67899,7 +68155,8 @@ ${blockingErrors.map((error) => `  ${error.message}`).join("\n")}`
           kind: change.kind,
           recordKind: change.recordKind,
           recordId: change.recordId
-        }))
+        })),
+        warnings: status.warnings
       })
     );
   } else {
@@ -70103,6 +70360,7 @@ function projectStatusJsonV4(status, options) {
       blocking: isBlockingSchemaSourceError(error),
       message: error.message
     })),
+    warnings: status.warnings,
     records: status.changes.map(
       (change) => recordChangeJsonV4(change, status, options)
     ),
@@ -70781,6 +71039,9 @@ async function main() {
       for (const error of status.parseErrors) {
         console.log(`${sym.warn} ${error.message}`);
       }
+      for (const message of status.warnings) {
+        console.log(`${sym.warn} ${message}`);
+      }
       for (const group of groupProjectStatusChangesV4(status)) {
         console.log(color.bold(group.source));
         for (const change of group.changes) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neocompose/cli",
-  "version": "0.11.1",
+  "version": "0.12.0",
   "description": "Neo Compose native project-source CLI with bidirectional sync.",
   "license": "MIT",
   "type": "module",