@neocompose/cli 0.86.0 → 0.87.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neocompose/cli",
-  "version": "0.86.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.86.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.86.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
@@ -400,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
@@ -430,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
@@ -711,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
@@ -330,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
@@ -383,6 +409,39 @@ 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` stores whole numbers and division truncates toward zero. Ordinary integer
@@ -753,30 +812,48 @@ 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