@neocompose/cli 0.85.0 → 0.87.0

package/package.json

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

package/skills/neocompose-cli/SKILL.md

@@ -9,7 +9,7 @@ description: >-
   `@neocompose/cli` or `node cli/bin/neo.mjs` in the neo-compose repository.
 ---
 
-<!-- reviewed-through-cli: 0.85.0 -->
+<!-- reviewed-through-cli: 0.87.0 -->
 
 # Neo Compose CLI
 

package/skills/neocompose-cli/references/cli-development.md

@@ -129,7 +129,7 @@ wrappers.
 The marker near the top of `SKILL.md` must exactly match the package version:
 
 ```html
-<!-- reviewed-through-cli: 0.85.0 -->
+<!-- reviewed-through-cli: 0.87.0 -->
 ```
 
 The quoted version above is checked too, so this instruction cannot go stale

package/skills/neocompose-cli/references/declarations-and-construction.md

@@ -8,6 +8,7 @@ constructors, and construction-time settlement.
 - Declaration rules
 - Annotations and settings
 - Member and relation rules
+- Function overloads
 - Computed initializers and declared constructors
 - Required constructors and settlement
 - Inheritance construction
@@ -61,6 +62,13 @@ it may extend another class but cannot be extended, cannot also be abstract,
 and can only be sealed while it has no subclasses. Interfaces can declare type
 parameters and pass arguments to the interfaces they extend; see Interface
 members.
+A `closed` class is implicitly abstract and defines an exhaustive subtype
+family within the project version. Do not combine `closed` with `abstract` or
+`sealed`. Descendants remain open unless explicitly sealed or closed. Every
+generic parameter of a direct subclass must appear in its base construction.
+Changing the family requires recompilation of its switch-expression consumers.
+Generated Unity C# uses an abstract class; C# 15 is not required.
+
 A read-only override may narrow a class or interface contract to an assignable
 class or derived interface, including a non-null value for a nullable contract.
 Generated Unity C# keeps the inherited property type for Mono compatibility;
@@ -393,6 +401,11 @@ empty set.
 public NeoAction<int> OnDamaged = [PlayHitFlash, ApplyDamage];
 ```
 
+A nested field initializer such as `Watcher = new() { OnTally = [Handle] }`
+can target an inherited generic method on its enclosing instance. The listener
+uses that owning instance, including when declaration defaults are materialized.
+Explicit receiver targets keep their captured instance.
+
 An instance-bound listener reachable through a stable project root keeps its
 receiver path, for example `public NeoAction<int> OnDamaged =
 [root.Assets.OnDamage];`. Pull refuses a bound receiver that has no
@@ -423,6 +436,44 @@ For world layer links, instantiate a project-authored descendant of
 `targetLayer` relation. The relation is the complete binding; do not add
 value-level target metadata.
 
+### Function overloads
+
+A class may declare several functions with one name when their parameter
+types differ:
+
+```neo
+class Inventory {
+  public int Add(Item item) { return 1; }
+  public int Add(Item item, int count) { return count; }
+  public int Add(List<Item> items) { return items.Count; }
+}
+```
+
+A class's overload set for a name holds every function of that name it
+declares or inherits. A derived class adding `Add(Item item, int count)` next
+to an inherited `Add(Item item)` overloads it. Static and instance functions,
+NSFunctions and native functions, and generic and non-generic functions mix
+freely.
+
+Every two functions in a set need different parameter types after dropping
+nullability, substituting base type arguments, and renaming function type
+parameters by position. So `Add(Item)` and `Add(Item?)` collide, and so do
+`F()` and `F<T>()`. A `Find<T = Item>(T value)` occupies `Find(Item)`.
+
+At most one function per name and class may be dispatched: `abstract`,
+`virtual`, `override`, or an interface implementation. Overrides target that
+one function. Interfaces can't overload, so an interface declares each
+function name once. When several class functions share an interface
+function's name, the one whose parameters match implements it.
+
+`Equals` and names a platform class or interface declares, such as
+`OnTriggerEnter2D` and lifecycle hooks, can't be overloaded. A function still
+can't share a name with a field, property, getter, or action.
+
+Overloads generate C# overloads with the same name. A plain overload stores
+under the key `Name#<memberId>`. A dispatched or lone function keeps the key
+`Name`, so a project without overloads stores exactly what it did before.
+
 ## Computed initializers and declared constructors
 
 Inherited member initializers read parameters from the constructor that declared
@@ -704,3 +755,19 @@ A semicolon after `Main = ...` inside the initializer is invalid. Editor and CLI
 diagnostics highlight that separator in the authored file, including global,
 static member, and protected root initializers. Statement semicolons inside
 function or delegate bodies remain valid.
+
+## Stored tuples
+
+Declare fixed positions with ordinary types and optional labels:
+
+```neo
+public (int Count, bool Enabled) State = (3, true);
+public (int, (string Label, int Count))? Detail = null;
+```
+
+Each position has a derived member descriptor. Do not author descriptor IDs.
+Changing a label preserves its position and identity. Changing arity or moving
+stored positions requires migrating existing values. A required tuple without
+a default must be supplied during construction; it has no automatic zero tuple.
+Owned class and collection elements keep the ordinary single-owner rule. Use
+an explicit reference or clone when another stored value already owns them.

package/skills/neocompose-cli/references/neoscript.md

@@ -7,7 +7,9 @@ runtime ownership, evaluation, and migrations.
 
 - Inline bodies and snippets
 - Nullability and ownership
+- Tuples and destructuring
 - References
+- Overloaded calls
 - Numeric builtins
 - Collection builtins
 - Conditional and logical operators
@@ -148,16 +150,17 @@ Functions, natives and interface functions can declare their own type
 parameters after the name, each with an optional constraint and default:
 
 ```neo
-public static T? FirstOf<T extends Item = Item>(List<Item> items) {
-    foreach (Item item in items) {
-        if (item is T match) return match;
-    }
-    return null;
-}
+public static T? FirstOf<T extends Item = Item>(List<T> items) => items.FirstOrDefault();
 ```
 
 A call writes every type argument or omits the defaulted tail
-(`FirstOf<Seed>(items)`, `FirstOf(items)`); nothing is inferred. Function type
+(`FirstOf<Seed>(items)`, `FirstOf(items)`). When `<...>` is omitted, supplied
+arguments infer the function's type arguments. Lambda inputs bind first so their
+returns can infer output parameters, as in `Map(seed, (value) => value.Price)`.
+Defaults fill parameters with no inference evidence. The destination/expected
+return type does not provide evidence. Explicit `<...>` keeps explicit/default
+binding and does not infer omitted trailing arguments. Conflicting types require
+explicit arguments; inference does not invent a shared ancestor for siblings. Function type
 parameters take no `@id`, and an override declares the same count, constraints
 and defaults, though it may rename them.
 
@@ -329,6 +332,30 @@ Save, Session, Setter, or otherwise writable. A constructor writes only its
 `this` instance. A writable structured-leaf field still inherits the receiver's
 effective storage restrictions.
 
+## Tuples and destructuring
+
+A tuple has at least two ordered elements. Labels are optional and explicit;
+`Item1`, `Item2`, and later positional aliases always work. Labels do not affect
+type identity. Slots are immutable, so replace a whole tuple to change a value.
+Referenced objects retain their normal permissions and identity.
+
+```neo
+(int Row, int Col) position = (Row: 2, Col: 3);
+var (row, col) = position;
+(int first, (bool enabled, int _)) = (1, (true, 9));
+var score = positions.Select(((r, c)) => r + c);
+foreach (var (key, value) in weights) { Debug.Log(key); }
+```
+
+`((r, c)) =>` accepts one tuple; `(r, c) =>` accepts two parameters. Recursive
+patterns work in declarations, loop bindings, and tuple lambda parameters. `_`
+discards a position. Assignment deconstruction is not supported.
+
+Tuple equality compares corresponding values recursively. Decimal scale does
+not affect equality. Classes, collections, and explicit references compare by
+identity. `Contains`, `IndexOf`, `Remove`, and `ToSet` use the same rule.
+Nullable tuples use `(int, int)?`; nullable elements use `(int?, int)`.
+
 ## References
 
 `Reference<T>` names one stored row. `T` can be any value type, including
@@ -382,14 +409,73 @@ The target row decides every write. Writing an asset-owned target errors, and a
 `OnChanged` listeners fire when it rebinds and when its target's value changes.
 Inside a generic body, `Reference<T>` takes the category of `T`'s binding.
 
+## Overloaded calls
+
+A call to an overloaded function picks one overload at compile time from its
+arguments. Candidates are every overload the receiver's type sees, across all
+inheritance levels; a type qualifier takes static ones, an instance receiver
+instance ones. An overload applies when the argument count fits its required
+and default parameters and each argument converts to its parameter. Lambdas,
+method groups, `null`, collection literals, and `.North` apply by shape.
+
+Among applicable overloads, the one whose parameters are closer to the
+argument types wins: an exact type beats a conversion, and `Bag` beats `Item`
+when `Bag : Item`. On a tie, the overload filling no defaults wins, then the
+non-generic one. Otherwise the call is ambiguous: `Scale(float)` and
+`Scale(decimal)` can't take an `int`, so write `2.0` or `2m`. A generic
+overload takes explicit type arguments, or infers them from the arguments the
+way a lone generic call does, with defaults filling parameters nothing infers.
+An overload whose type arguments can't be inferred isn't a candidate: beside
+`F(int a, string b)`, `F<T>(T a, T b)` takes `F(1, 2)` but not `F(1, "a")`.
+
+A method group picks the overload whose parameters match the target delegate
+type exactly, in assignments, `+=`, `OnChanged`, `@listeners`, and delegate
+arguments. `var f = Read` is an error when `Read` is overloaded; give `f` a
+delegate type.
+
+Pass the delegate type to mock or spy on an overloaded function:
+
+```neo
+var quote = mock.function<NeoDelegate<int, Item, int>>(Pricing.Quote);
+```
+
+Script evaluation selects an overload with a signature:
+`neo script eval --function "Inventory.Add(Item, int)"`.
+
 ## Numeric types
 
-`int` is a 32-bit integer and `float` is a 32-bit float, matching C#. Float
-literals, stored values, and every arithmetic step round to 32 bits, so
-`0.1f + 0.2f` behaves like Unity. `int` division truncates toward zero.
+`int` stores whole numbers and division truncates toward zero. Ordinary integer
+arithmetic retains the precision of the stored number. `float` literals, stored
+values, and every float arithmetic step round to 32 bits, matching Unity.
 `decimal` is exact base-10 and is the only type to use for currency or other
 values that must not drift.
 
+## Bitwise integer operators
+
+Use `~`, `&`, `^`, `|`, `<<`, `>>`, and `>>>` with non-nullable `int` operands.
+The compound forms are `&=`, `^=`, `|=`, `<<=`, `>>=`, and `>>>=`.
+Enums, bools, float literals such as `1.0`, and decimals are not accepted.
+Use `Set<Enum>` for enum membership.
+
+```neo
+int mask = (region << 8) | (tile & 255);
+bool hasEast = (mask & 2) != 0;
+mask &= ~2;
+```
+
+Each operand wraps modulo 2^32 into signed int32 at the bitwise boundary.
+Every result is signed int32. Ordinary integer arithmetic is unchanged.
+Shift counts use their low five bits: 32 means 0, 33 means 1, and -1 means 31.
+`>>` extends the sign bit; `>>>` fills with zero but still returns a signed
+result. Thus `-1 >>> 1` is 2147483647 and `-1 >>> 0` is -1.
+Operands evaluate once, left to right. A compound assignment captures its
+target and reads its old value before evaluating the right operand.
+
+Precedence from tightest to loosest: unary, switch expressions, multiplication/division/remainder,
+addition/subtraction, shifts, comparisons, equality and `is`, `&`, `^`, `|`,
+`&&`, `||`, `??`, then `?:`. Binary bitwise operators associate left to right.
+Keep shift characters contiguous: `x >> 1` is valid; `x > > 1` is not.
+
 ## Numeric builtins
 
 Use the `Math` namespace for numeric utilities with C# names and C# semantics:
@@ -692,33 +778,82 @@ switch (direction) {
 Permit `int`, `string`, `bool`, enum, and nullable forms. Stack labels when
 they share one body. End every reachable non-empty section with `break`,
 `return`, `throw`, or `continue` when a surrounding loop makes it valid.
-Do not use implicit fallthrough, switch expressions, pattern cases, guards, or
-`goto`.
+Do not use implicit fallthrough, pattern cases, guards, or `goto` in statement switches.
+
+### Switch expressions
+
+Use `value switch { pattern => result, ... }` to produce one value. Arms may
+use scalar/enum constants, `null`, type patterns (`Damage`), declaration
+patterns (`Damage damage`), or `_`. A declaration binding is scoped to its
+arm's optional `when` guard and result. Patterns and guards run in order; the
+selector runs once and only the chosen result runs.
+
+```neo
+closed class HitResult {}
+sealed class Miss : HitResult {}
+sealed class Damage : HitResult { public int Amount = 0; }
+class Combat {
+  public string Describe(HitResult result) => result switch {
+    Miss => "miss",
+    Damage damage when damage.Amount > 10 => "strong hit",
+    Damage damage => $"{damage.Amount}",
+  };
+}
+```
+
+Every switch expression must be exhaustive. Handle every bool/enum option or
+closed-class branch, plus null for nullable input. Other types require a
+covering type or `_` fallback. A guard contributes no exhaustive coverage
+unless it is literally `true`. Missing and unreachable cases are compile
+errors. Adding a new subtype recompiles affected consumers.
+
+Result arms must fit the expected type or have a common assignable type.
+Property, relational, list, and positional patterns are unsupported. Pattern
+cases in statement switches remain unsupported. Install the matching Unity
+SDK before exporting the new switch-expression IR; older SDKs reject it.
 
-## Try/catch
+## Structured errors and finally
 
-Catch the string-valued NeoScript runtime-error channel with ordered filters:
+Throw a required string or any `NeoError` subclass. String throws create
+`NeoError` values. Each error has a required read-only `Message`, including
+an empty message. Derive ordinary classes from `NeoError` to carry typed data.
 
 ```neo
 try {
   return GetUnsafe();
 }
-catch (string message) when (message == "1") {
-  return "Site moved";
-}
-catch (string message) {
+catch (NeoArgumentError error) when (error.Message != "") {
+  Report(error.Message);
   throw;
 }
+catch (NeoError error) {
+  return Fallback();
+}
+finally {
+  ReleaseResource();
+}
 ```
 
-Require braces and at least one `catch (string name)`. The catch binding is
-read-only and scoped to its filter/body. Put at most one unfiltered catch last.
-A false or failing filter continues matching the original error. Bare
-`throw;` is valid only inside a catch and rethrows the original message.
-
-Do not use typed exception classes, parameterless catch, `finally`, `using`,
-patterns, or host-exception recovery. Completed writes before an error are not
-rolled back.
+A try needs catches, a finally block, or both. Catch bindings are read-only.
+Typed catches match subclasses, and `catch (string message)` matches every
+ordinary error while binding its Message. An unfiltered base catch must follow
+all catches it covers. Filters run before any intervening finally blocks,
+including across calls. A false or failing filter continues the original search.
+Bare `throw;` rethrows the original payload from a catch.
+
+Finally runs on normal completion, return, break, continue, and ordinary errors.
+The return value is evaluated before cleanup. An error escaping cleanup replaces
+the pending error; an error caught inside cleanup does not. Return and loop
+transfers cannot escape a finally block. A nested loop may break or continue.
+Bare throw inside finally needs its own inner catch.
+
+Runtime failures use `NeoNullReferenceError`, `NeoIndexOutOfRangeError`,
+`NeoKeyNotFoundError`, `NeoArgumentError`, `NeoArithmeticError`, or
+`NeoInvalidOperationError`. Unexpected native failures become `NeoHostError`
+with Message `"Check logs for more details."`. Execution limits, unavailable
+preview natives, cancellation, and invalid compiled data are noncatchable.
+Suspended Unity calls retain cleanup until resumed; abandonment skips cleanup.
+Completed writes are not rolled back. Install the matching SDK for schema 45.
 
 ## Debug output