@greenpandastudios/aug-cli 0.19.0 → 0.20.1

package/examples/approved-design/counters.aug.md

@@ -1,177 +1,70 @@
 <!-- Generated by aug spec. Edit the August source, then regenerate. -->
 
-# `counters.aug` specification
-
-August 0.19.0. This document is compiled from checked code with deterministic wording guided by Simplified Technical English.
-
-## In this file
-
-- [`State`](counters.aug.md#symbol-State) is an interface.
-- [`_Initial`](counters.aug.md#symbol-_Initial) is a class implementing `State`.
-- [`_Updated`](counters.aug.md#symbol-_Updated) is a class implementing `State`.
-- [`Counter`](counters.aug.md#symbol-Counter) is an interface.
-- [`_Counter`](counters.aug.md#symbol-_Counter) is a class implementing `Counter`.
-- [`Counters`](counters.aug.md#symbol-Counters) declares 2 providers.
+# `counters.aug`
 
 <a id="symbol-State"></a>
-
-## `State`
-
-[source](counters.aug#L2)
-
-Interface.
-
-**Author documentation**
+## `State` · interface · [source](counters.aug#L3)
 
 Reading state has no mutation effect.
 
 <a id="symbol-State.read"></a>
+### `State.read` · [source](counters.aug#L4)
 
-### `State.read`
-
-[source](counters.aug#L3)
-
-Returns: `int`.
-
-Interface contract. A selected implementation supplies the behavior.
+It returns `int`.
 
 <a id="symbol-Counter"></a>
-
-## `Counter`
-
-[source](counters.aug#L11)
-
-Interface.
-
-**Author documentation**
+## `Counter` · interface · [source](counters.aug#L12)
 
 A mutable counter with an explicit transition contract.
 
 <a id="symbol-Counter.increment"></a>
+### `Counter.increment` · [source](counters.aug#L13)
 
-### `Counter.increment`
-
-[source](counters.aug#L12)
-
-Returns: no value.
-
-May change: `self`.
-
-Interface contract. A selected implementation supplies the behavior.
+It may change `self`.
 
 <a id="symbol-Counter.value"></a>
+### `Counter.value` · [source](counters.aug#L14)
 
-### `Counter.value`
-
-[source](counters.aug#L13)
-
-Returns: `int`.
-
-Interface contract. A selected implementation supplies the behavior.
+It returns `int`.
 
 <a id="symbol-Counters"></a>
-
-## `Counters`
-
-[source](counters.aug#L20)
-
-**Author documentation**
+## `Counters` · [source](counters.aug#L21)
 
 The complete counter composition; its mutable state belongs to each scope.
 
-This composition declares these providers before startup:
-
-- Provide [`_Initial`](counters.aug.md#symbol-_Initial) when `State` is requested. Reuse one instance.
-- Provide [`_Counter`](counters.aug.md#symbol-_Counter) when `Counter` is requested. Reuse one instance per explicit scope. Permit explicit shared mutation. Required dependencies: `State`.
+These providers are registered before startup. `State` is provided by [`_Initial`](counters.aug.md#symbol-_Initial). The same instance is shared. `Counter` is provided by [`_Counter`](counters.aug.md#symbol-_Counter). Each scope shares one instance. Shared mutation is allowed. It requires bindings for `State`.
 
 <a id="symbol-_Initial"></a>
+## `_Initial` · class · [source](counters.aug#L5)
 
-## `_Initial`
-
-[source](counters.aug#L4)
-
-Behavioral class, private to this file.
-
-Satisfies [`State`](counters.aug.md#symbol-State).
+It implements [`State`](counters.aug.md#symbol-State). It is private to this file.
 
 <a id="symbol-_Initial.read"></a>
+### `_Initial.read` · [source](counters.aug#L6)
 
-### `_Initial.read`
-
-[source](counters.aug#L5)
-
-Returns: `int`.
-
-**What it does**
-
-- Return `0`.
+It returns `0`.
 
 <a id="symbol-_Updated"></a>
+## `_Updated` · class · [source](counters.aug#L8)
 
-## `_Updated`
-
-[source](counters.aug#L7)
-
-Behavioral class, private to this file.
-
-Satisfies [`State`](counters.aug.md#symbol-State).
-
-**Inputs**
-
-- `count` (`int`) — required labeled input — stored as `count` and read-only after initialization.
+It implements [`State`](counters.aug.md#symbol-State). It is private to this file. It takes `count` as an integer, kept read-only.
 
 <a id="symbol-_Updated.read"></a>
+### `_Updated.read` · [source](counters.aug#L9)
 
-### `_Updated.read`
-
-[source](counters.aug#L8)
-
-Returns: `int`.
-
-**What it does**
-
-- Return `count`.
+It returns `count`.
 
 <a id="symbol-_Counter"></a>
+## `_Counter` · class · [source](counters.aug#L15)
 
-## `_Counter`
-
-[source](counters.aug#L14)
-
-Behavioral class, private to this file.
-
-Satisfies [`Counter`](counters.aug.md#symbol-Counter).
-
-**Inputs**
-
-- `initial` ([`State`](counters.aug.md#symbol-State)) — injected; callers omit it — stored as `_state` (private) and mutable.
+It implements [`Counter`](counters.aug.md#symbol-Counter). It is private to this file. The `_state` dependency is injected as [`State`](counters.aug.md#symbol-State) and stored mutably and privately.
 
 <a id="symbol-_Counter.increment"></a>
+### `_Counter.increment` · [source](counters.aug#L16)
 
-### `_Counter.increment`
-
-[source](counters.aug#L15)
-
-Returns: no value.
-
-May change: `self`.
-
-**What it does**
-
-- Set `_state` to call [`_Updated`](counters.aug.md#symbol-_Updated) with `count` = (call [`State.read`](counters.aug.md#symbol-State.read) on `_state` plus `1`).
+It may change `self`. It sets `_state` to a [`_Updated`](counters.aug.md#symbol-_Updated) with `count` from [`_state.read`](counters.aug.md#symbol-State.read) plus `1`.
 
 <a id="symbol-_Counter.value"></a>
+### `_Counter.value` · [source](counters.aug#L18)
 
-### `_Counter.value`
-
-[source](counters.aug#L17)
-
-Returns: `int`.
-
-**What it does**
-
-- Return call [`State.read`](counters.aug.md#symbol-State.read) on `_state`.
-
-## Shared language rules
-
-See the [language reference](https://greenpandastudios.github.io/augscript/reference) for numeric, equality, ownership, and task rules.
+It returns [`_state.read`](counters.aug.md#symbol-State.read).

package/examples/approved-design/domain/app.aug

@@ -1,3 +1,4 @@
+// aug-spec: "app.aug.md" explains this file. Read it before changes; refresh with aug spec.
 import Console from august.io
 import Fruit from models
 /** The application's explicit startup operation. */
@@ -6,7 +7,7 @@ interface Application:
 	start() uses Console.write
 /** Construction stores dependencies; start performs the visible external work. */
 ApplicationImpl(resolve Console console) implements Application:
-	start() uses console.write:
+	start() :
 		fruit to [Fruit(code=1, name="apple"), Fruit(name="pear", code=2)]
 		for item in fruit:
 			console.write(value=item.name)

package/examples/approved-design/domain/app.aug.md

@@ -1,97 +1,27 @@
 <!-- Generated by aug spec. Edit the August source, then regenerate. -->
 
-# `app.aug` specification
-
-August 0.19.0. This document is compiled from checked code with deterministic wording guided by Simplified Technical English.
-
-## In this file
-
-- [`Application`](app.aug.md#symbol-Application) is an interface.
-- [`ApplicationImpl`](app.aug.md#symbol-ApplicationImpl) is a class implementing `Application`.
+# `app.aug`
 
 <a id="symbol-Application"></a>
-
-## `Application`
-
-[source](app.aug#L4)
-
-Interface.
-
-**Author documentation**
+## `Application` · interface · [source](app.aug#L5)
 
 The application's explicit startup operation.
 
 <a id="symbol-Application.start"></a>
+### `Application.start` · [source](app.aug#L7)
 
-### `Application.start`
-
-[source](app.aug#L6)
-
-Returns: no value.
-
-Capabilities: [`Console.write`](../.aug-spec/august/0.19.0/io/contracts.aug.md#symbol-Console.write).
-
-Interface contract. A selected implementation supplies the behavior.
-
-**Author documentation**
-
-Writes the fruit names through the selected console.
+Writes the fruit names through the selected console. It can call [`Console.write`](../.aug-spec/august/0.20.1/io/contracts.aug.md#symbol-Console.write).
 
 <a id="symbol-ApplicationImpl"></a>
+## `ApplicationImpl` · class · [source](app.aug#L9)
 
-## `ApplicationImpl`
-
-[source](app.aug#L8)
-
-Behavioral class.
-
-Satisfies [`Application`](app.aug.md#symbol-Application).
-
-**Author documentation**
-
-Construction stores dependencies; start performs the visible external work.
-
-**Inputs**
-
-- `console` ([`Console`](../.aug-spec/august/0.19.0/io/contracts.aug.md#symbol-Console)) — injected; callers omit it — stored as `console` and read-only after initialization.
+Construction stores dependencies; start performs the visible external work. It implements [`Application`](app.aug.md#symbol-Application). The `console` dependency is injected as [`Console`](../.aug-spec/august/0.20.1/io/contracts.aug.md#symbol-Console) and stored read-only.
 
 <a id="symbol-ApplicationImpl.start"></a>
+### `ApplicationImpl.start` · [source](app.aug#L10)
 
-### `ApplicationImpl.start`
-
-[source](app.aug#L9)
-
-Returns: no value.
-
-Capabilities: [`console.write`](../.aug-spec/august/0.19.0/io/contracts.aug.md#symbol-Console.write).
-
-**What it does**
-
-- Set `fruit` to a list containing call [`Fruit`](models.aug.md#symbol-Fruit) with `code` = `1`; `name` = `"apple"`, call [`Fruit`](models.aug.md#symbol-Fruit) with `name` = `"pear"`; `code` = `2`.
-- For each `item` in a snapshot of `fruit`, in iteration order:
-  - Call [`Console.write`](../.aug-spec/august/0.19.0/io/contracts.aug.md#symbol-Console.write) on `console` with `value` = `name` of `item`.
-
-**Author documentation**
-
-Writes the fruit names through the selected console.
-
-## Dependencies used by this file
-
-Only referenced types and operations appear here. Each name links to its complete specification.
-
-### [`Console`](../.aug-spec/august/0.19.0/io/contracts.aug.md#symbol-Console)
-
-Capability interface from `august.io`.
-
-- [`Console.write`](../.aug-spec/august/0.19.0/io/contracts.aug.md#symbol-Console.write)<`T`> (`value`: `T`) → `void`.
-
-### [`Fruit`](models.aug.md#symbol-Fruit)
-
-Record from `models`.
-
-- Construct with `code`: `int`, `name`: `string` → [`Fruit`](models.aug.md#symbol-Fruit).
-- Read `name` (`string`).
+Writes the fruit names through the selected console. It sets `fruit` to a list containing a [`Fruit`](models.aug.md#symbol-Fruit) with `code` `1` and `name` `"apple"`, a [`Fruit`](models.aug.md#symbol-Fruit) with `name` `"pear"` and `code` `2`. For each `item` in a snapshot of `fruit`, it passes `item.name` to [`console.write`](../.aug-spec/august/0.20.1/io/contracts.aug.md#symbol-Console.write).
 
-## Shared language rules
+## Dependencies
 
-See the [language reference](https://greenpandastudios.github.io/augscript/reference) for numeric, equality, ownership, and task rules.
+It uses [`Console`](../.aug-spec/august/0.20.1/io/contracts.aug.md#symbol-Console) ([`write`](../.aug-spec/august/0.20.1/io/contracts.aug.md#symbol-Console.write)) from `august.io`. It uses [`Fruit`](models.aug.md#symbol-Fruit) (`name`) from `models`.

package/examples/approved-design/domain/export.aug

@@ -1,3 +1,4 @@
+// aug-spec: "export.aug.md" explains this file. Read it before changes; refresh with aug spec.
 export Application from app
 export ApplicationImpl from app
 export Fruit from models

package/examples/approved-design/domain/export.aug.md

@@ -1,25 +1,9 @@
 <!-- Generated by aug spec. Edit the August source, then regenerate. -->
 
-# `export.aug` specification
+# `export.aug`
 
-August 0.19.0. This document is compiled from checked code with deterministic wording guided by Simplified Technical English.
+## Exports
 
-## In this file
+Export the declaration `Application` from [`app.aug`](app.aug.md#symbol-Application). Export the declaration `ApplicationImpl` from [`app.aug`](app.aug.md#symbol-ApplicationImpl). Export the declaration `Fruit` from [`models.aug`](models.aug.md#symbol-Fruit). Export the declaration `double` from [`numbers.aug`](numbers.aug.md#symbol-double).
 
-- Export `Application` from this folder.
-- Export `ApplicationImpl` from this folder.
-- Export `Fruit` from this folder.
-- Export `double` from this folder.
-- Export `RangeError` from this folder.
-
-## Folder exports
-
-- Export the declaration `Application` from [`app.aug`](app.aug.md#symbol-Application).
-- Export the declaration `ApplicationImpl` from [`app.aug`](app.aug.md#symbol-ApplicationImpl).
-- Export the declaration `Fruit` from [`models.aug`](models.aug.md#symbol-Fruit).
-- Export the declaration `double` from [`numbers.aug`](numbers.aug.md#symbol-double).
-- Export the declaration `RangeError` from [`numbers.aug`](numbers.aug.md#symbol-RangeError).
-
-## Shared language rules
-
-See the [language reference](https://greenpandastudios.github.io/augscript/reference) for numeric, equality, ownership, and task rules.
+Export the declaration `RangeError` from [`numbers.aug`](numbers.aug.md#symbol-RangeError).

package/examples/approved-design/domain/models.aug

@@ -1,2 +1,3 @@
+// aug-spec: "models.aug.md" explains this file. Read it before changes; refresh with aug spec.
 /** Immutable fruit data, with public construction labels and structural equality. */
 record Fruit(int code, string name)

package/examples/approved-design/domain/models.aug.md

@@ -1,30 +1,8 @@
 <!-- Generated by aug spec. Edit the August source, then regenerate. -->
 
-# `models.aug` specification
-
-August 0.19.0. This document is compiled from checked code with deterministic wording guided by Simplified Technical English.
-
-## In this file
-
-- [`Fruit`](models.aug.md#symbol-Fruit) is an immutable record.
+# `models.aug`
 
 <a id="symbol-Fruit"></a>
+## `Fruit` · immutable record · [source](models.aug#L3)
 
-## `Fruit`
-
-[source](models.aug#L2)
-
-Immutable record.
-
-**Author documentation**
-
-Immutable fruit data, with public construction labels and structural equality.
-
-**Inputs**
-
-- `code` (`int`) — required labeled input — stored as `code` and read-only after initialization.
-- `name` (`string`) — required labeled input — stored as `name` and read-only after initialization.
-
-## Shared language rules
-
-See the [language reference](https://greenpandastudios.github.io/augscript/reference) for numeric, equality, ownership, and task rules.
+Immutable fruit data, with public construction labels and structural equality. It takes `code` as an integer, kept read-only and `name` as a string, kept read-only.

package/examples/approved-design/domain/numbers.aug

@@ -1,9 +1,10 @@
+// aug-spec: "numbers.aug.md" explains this file. Read it before changes; refresh with aug spec.
 /** Raised when an input is outside the operation's domain. */
 RangeError(int value) implements Error:
 	pass
 /** A pure validation layer, shared by any compatible callable. */
 interceptor Positive<T>():
-	around(int amount) returns T unless RangeError:
+	around(int amount) returns T :
 		if amount < 0:
 			throw RangeError(value=amount)
 		return next()
@@ -14,7 +15,7 @@ interceptor Positive<T>():
 * @throws RangeError A validation layer rejected a negative input.
 */
 [Positive]
-double(int amount) returns int:
+double(int amount) :
 	return amount * 2
 test double:
 	when "positive":

package/examples/approved-design/domain/numbers.aug.md

@@ -1,141 +1,44 @@
 <!-- Generated by aug spec. Edit the August source, then regenerate. -->
 
-# `numbers.aug` specification
-
-August 0.19.0. This document is compiled from checked code with deterministic wording guided by Simplified Technical English.
-
-## In this file
-
-- [`RangeError`](numbers.aug.md#symbol-RangeError) is a class implementing `Error`.
-- [`Positive`](numbers.aug.md#symbol-Positive) is an interceptor.
-- [`double`](numbers.aug.md#symbol-double) is a function returning `int`.
-- [`test double`](numbers.aug.md#symbol-test%20double) is a same-file test suite.
+# `numbers.aug`
 
 <a id="symbol-RangeError"></a>
+## `RangeError` · class · [source](numbers.aug#L3)
 
-## `RangeError`
-
-[source](numbers.aug#L2)
-
-Behavioral class.
-
-Satisfies `Error`.
-
-**Author documentation**
-
-Raised when an input is outside the operation's domain.
-
-**Inputs**
-
-- `value` (`int`) — required labeled input — stored as `value` and read-only after initialization.
+Raised when an input is outside the operation's domain. It implements `Error`. It takes `value` as an integer, kept read-only.
 
 <a id="symbol-Positive"></a>
+## `Positive` · interceptor · [source](numbers.aug#L6)
 
-## `Positive`
-
-[source](numbers.aug#L5)
-
-Function or constructor middleware.
-
-Type parameters: `T`.
-
-**Author documentation**
-
-A pure validation layer, shared by any compatible callable.
-
-Create a fresh interceptor for each invocation. Its around operation can delegate once, change selected inputs, or short-circuit with a compatible result or failure.
+A pure validation layer, shared by any compatible callable. The type parameters are `T`. Creates one interceptor per invocation. Its around operation may delegate once or finish early.
 
 <a id="symbol-Positive.around"></a>
+### `Positive.around` · [source](numbers.aug#L7)
 
-### `Positive.around`
-
-[source](numbers.aug#L6)
-
-**Inputs**
-
-- `amount` (`int`) — required labeled input.
-
-Returns: `T`.
-
-Can fail with `RangeError`. Callers must catch or propagate these errors.
-
-**What it does**
-
-- If `amount` is less than `0`:
-  - Fail with call [`RangeError`](numbers.aug.md#symbol-RangeError) with `value` = `amount`. Transfer control to a matching catch or propagate the failure.
-- Return call `next`.
+It takes `amount` as an integer. Failures can raise [`RangeError`](numbers.aug.md#symbol-RangeError). If `amount` is negative, it raises a [`RangeError`](numbers.aug.md#symbol-RangeError) with `value` from `amount`. It returns `next`.
 
 <a id="symbol-double"></a>
+## `double` · [source](numbers.aug#L18)
 
-## `double`
+Double a nonnegative amount. It takes `amount` as an integer (Integer to double). It returns `int` — Twice the amount, with defined integer wrapping. Failures can raise [`RangeError`](numbers.aug.md#symbol-RangeError) (A validation layer rejected a negative input).
 
-[source](numbers.aug#L17)
-
-**Inputs**
-
-- `amount` (`int`) — required labeled input.
-
-Returns: `int`.
-
-Can fail with `RangeError`. Callers must catch or propagate these errors.
-
-**Interceptors, in execution order**
-
-1. Call [`Positive.around`](numbers.aug.md#symbol-Positive.around). It can call the next layer or finish with its own result or failure. Unselected inputs pass through.
-
-The first layer wraps the remaining layers. HTTP policies run before wire decoding; custom interceptors run after decoding. Follow linked behavior to see its conditions, input changes, and calls to the next layer.
-
-**What it does**
-
-- Return `amount` times `2`.
-
-**Author documentation**
-
-Double a nonnegative amount.
-
-**Returns** Twice the amount, with defined integer wrapping.
-
-**Parameters**
-- `amount`: Integer to double.
-
-**Throws**
-- `RangeError`: A validation layer rejected a negative input.
+Layers run in the declared order. Call [`Positive.around`](numbers.aug.md#symbol-Positive.around). It returns `amount` times `2`.
 
 <a id="symbol-test double"></a>
+## `test double` · [source](numbers.aug#L20)
 
-## `test double`
-
-[source](numbers.aug#L19)
-
-Same-file function tests for [`double`](numbers.aug.md#symbol-double). Each case gets isolated setup and dependency bindings.
-
-### Group `positive`
-
-#### `doubles`
-
-[source](numbers.aug#L21)
-
-Run once for each row of a tuple containing `0`, `0`; a tuple containing `3`, `6`; a tuple containing `7`, `14`. Bind row positions to `input`, `expected`.
-
-- Call `assert` with (call [`double`](numbers.aug.md#symbol-double) with `amount` = `input` equals `expected`).
-
-#### `rejects_negative`
+Tests [`double`](numbers.aug.md#symbol-double). Each case gets fresh setup and dependencies.
 
-[source](numbers.aug#L23)
+### `positive`
 
-- Set `rejected` of type `bool` to `false`.
-- Try these operations:
-  - Call [`double`](numbers.aug.md#symbol-double) with `amount` = `-1`.
-- If they fail with [`RangeError`](numbers.aug.md#symbol-RangeError), name the failure `error` and recover:
-  - Set `rejected` to `value` of `error` equals `-1`.
-- Call `assert` with `rejected` = `rejected`.
+#### `doubles` · [source](numbers.aug#L22)
 
-## Built-in operations used by this file
+Run once for each row of a tuple containing `0`, `0`; a tuple containing `3`, `6`; a tuple containing `7`, `14`. Bind row positions to `input`, `expected`. The test requires [`double`](numbers.aug.md#symbol-double) with `amount` from `input` equals `expected`.
 
-- `assert` (`condition`: `bool`) → `void`: Assert a bool in a test case or its setup. Catching an assertion failure cannot make the case pass; every case must execute an assertion.
+#### `rejects_negative` · [source](numbers.aug#L24)
 
-[Full built-in reference](https://greenpandastudios.github.io/augscript/language-constructs).
+It sets `rejected` to `false`.
 
-## Shared language rules
+It tries to call [`double`](numbers.aug.md#symbol-double) with `amount` `-1`. If this work raises [`RangeError`](numbers.aug.md#symbol-RangeError) as `error`, it sets `rejected` to `error.value` equals `-1`. The test requires `rejected` is true.
 
-See the [language reference](https://greenpandastudios.github.io/augscript/reference) for numeric, equality, ownership, and task rules.
+Built-in operations follow the [language reference](https://greenpandastudios.github.io/augscript/language-constructs).

package/examples/approved-design/main.aug

@@ -1,3 +1,4 @@
+// aug-spec: "main.aug.md" explains this file. Read it before changes; refresh with aug spec.
 import Console and SystemConsole from august.io
 import Application and ApplicationImpl and Fruit and double and RangeError from domain
 import Counter and Counters from counters