@neocompose/cli 0.23.2 → 0.24.0

package/CHANGELOG.md

@@ -1,5 +1,44 @@
 # Changelog
 
+## [0.24.0] - 2026-08-06
+
+### Added
+
+- Add local NeoScript unit testing with colocated `*.spec.neo` files,
+  `neo test` file/name selection, human and JSON reporting, typed assertions,
+  and fail-closed native/NeoScript function mocks. Tests compile the complete
+  unpushed project through the same offline local-candidate preparation used
+  by push and keep their build metadata under `.neo/test-build/`.
+- Add independent `prePushHook` and `prePushDryRunHook` commands in `neo.json`.
+  They run after successful local preparation but before authentication or
+  network activity, abort on failure, and can be bypassed explicitly with
+  `neo push --no-verify`.
+- Add stable `neo test` process outcomes for automation: 0 for success, 1 for
+  test/preparation/compilation failure, 2 for usage or runner failure, and 130
+  for SIGINT. JSON output is written on every one of those paths when an
+  `--outputFile` is configured.
+
+### Changed
+
+- Classify `*.spec.neo` as a fourth, test-only project-source kind shared by
+  CLI discovery, project analysis, Monaco, and the VS Code language server.
+  Specs never enter status, source identity, pull/reset, or push.
+- Project discovery now shares generated/private directory exclusions and
+  honors applicable `.gitignore` rules.
+- `neo doctor` now compiles every discovered `*.spec.neo` file against the
+  offline local candidate and exits nonzero for spec diagnostics. Specs remain
+  excluded from production push inputs, so this does not make test-source
+  diagnostics a push blocker.
+- Neo test build artifacts use a versioned manifest, sweep abandoned temporary
+  writes, and enforce a 512 MiB least-recently-used cache ceiling while
+  protecting the candidate currently being consumed by a push hook.
+
+### Fixed
+
+- Dialogue dry-runs continue treating unavailable device-native actions as
+  warnings after the evaluator diagnostic wording change by matching the
+  native-unavailable error type instead of its message text.
+
 ## [0.23.2] - 2026-08-06
 
 ### Fixed

package/README.md

@@ -71,13 +71,16 @@ neo/
   DialogueGroups/
   Dialogues/*.neoflow
   Migrations/*.neo
+  **/*.spec.neo                   # colocated local-only NeoScript tests
   .neo/
     state.json                     # private merge/CAS bases; never hand-edit
     conflicts/
+    test-build/                    # local test compilation metadata
 ```
 
-All non-hidden `.neo`, `.neoflow`, and supported managed binaries are tracked.
-`.neo/` is ignored private state. There is no schema `.csproj`, C# authoring
+Production `.neo`, `.neoflow`, and supported managed binaries are tracked.
+Colocated `.spec.neo` files are test-only: they never enter status, source
+identity, pull/reset, or push. `.neo/` is ignored private state. There is no schema `.csproj`, C# authoring
 tree, Roslyn compiler, generated authoring DLL, per-function sidecar tree, or
 checked-in dialogue JSON.
 
@@ -356,6 +359,58 @@ neo files add Files/Images/Sword.png --template PixelArt
 neo dialogue new CapitolColdBoot --primary Outpost=Assets.Capitol --group CapitolDialogues
 ```
 
+## NeoScript unit tests
+
+Place `*.spec.neo` files anywhere beside project source. They see the complete
+locally prepared production graph—including unpushed declarations, values, and
+function bodies—plus a test-only typed prelude. Production source never sees
+test globals.
+
+```neo
+describe("Player.TakeDamage", () => {
+  test("rejects negative damage", () => {
+    var player = new Player();
+    expect(() => { player.TakeDamage(-1); }).toThrow("negative");
+  });
+});
+```
+
+Run all tests, narrow by file/directory, or filter the full test name with a
+JavaScript regular expression:
+
+```sh
+neo test
+neo test Classes/Player.spec.neo
+neo test -t "TakeDamage"
+neo test --reporter=json --outputFile=.neo/test-results.json
+```
+
+The JSON output file is written atomically. Test compilation metadata lives in
+`.neo/test-build/`; neither it nor test files are server records. A workspace
+must have been initialized or pulled once so `.neo/state.json` contains the
+offline project facts, but running tests performs no login or network request.
+
+Native functions cannot execute in the local evaluator and therefore fail
+closed unless mocked. Use `mock.native(Member)`, `mock.function(Member)`, or
+`spyOn(Member)`, then configure `returns`,
+`returnsOnce`, `throws`, `throwsOnce`, `doesNothing`, or `implementation`.
+Mocks and call history are isolated per test.
+
+To gate pushes, add either or both commands to `neo.json`:
+
+```json
+{
+  "prePushHook": "neo test",
+  "prePushDryRunHook": "neo test --reporter=json --outputFile=.neo/test-results.json"
+}
+```
+
+The real-push hook is intentionally not reused for dry runs: arbitrary hook
+commands may have side effects. Each applicable hook runs only after local
+candidate validation and before authentication/network activity; a non-zero
+exit aborts. `neo push --no-verify` is an explicit local bypass, not a server
+authorization boundary.
+
 ## Commands
 
 | Command                                                  | Purpose                                                                      |
@@ -365,7 +420,8 @@ neo dialogue new CapitolColdBoot --primary Outpost=Assets.Capitol --group Capito
 | `doctor`                                                 | Validate format/compiler/editor/source/file contracts; no .NET discovery.    |
 | `pull [--force\|--reset] [--regenerate-source-names]`    | Merge remote changes or regenerate canonical source, names, and binaries.    |
 | `status [--json]` / `diff [--json]`                      | Compile source and show semantic records, spans, digests, and upload intent. |
-| `push [--dry-run] [--accept-bump]`                       | Validate or commit one atomic compare-and-swap transaction.                  |
+| `push [--dry-run] [--accept-bump] [--no-verify]`         | Validate or commit one atomic compare-and-swap transaction.                  |
+| `test [file-or-dir ...] [-t pattern]`                    | Compile the unpushed local candidate and run `*.spec.neo` tests.             |
 | `dev [--push]`                                           | Watch remote/local changes; pushing remains opt-in.                          |
 | `resolve --mine\|--theirs`                               | Resolve all current source/binary conflicts with one side.                   |
 | `class new` / `value new` / `files add` / `dialogue new` | Create pending native source scaffolds.                                      |