@greenpandastudios/aug-cli 0.19.0

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

@@ -0,0 +1,248 @@
+---
+title: "domain/numbers.aug · Modules and composition"
+generated: true
+source: "examples/approved-design/domain/numbers.aug"
+editLink: false
+prev: false
+next: false
+outline: [2, 3]
+pageClass: aug-example-page
+---
+
+# `domain/numbers.aug`
+
+[Modules and composition](../index.md) · Source and specification
+
+::: details Files in this project
+
+- [`main.aug`](../main.md)
+- [`counters.aug`](../counters.md)
+- [`domain/app.aug`](app.md)
+- [`domain/export.aug`](export.md)
+- [`domain/models.aug`](models.md)
+- [`domain/numbers.aug`](numbers.md)
+
+:::
+
+::::: example-compare
+
+:::: example-code
+
+## Code {#code}
+
+::: code-group
+
+```aug [Indentation]
+/** 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:
+        if amount < 0:
+            throw RangeError(value=amount)
+        return next()
+/**
+* Double a nonnegative amount.
+* @param amount Integer to double.
+* @return Twice the amount, with defined integer wrapping.
+* @throws RangeError A validation layer rejected a negative input.
+*/
+[Positive]
+double(int amount) returns int:
+    return amount * 2
+test double:
+    when "positive":
+        it "doubles" for (input, expected) in [(0, 0), (3, 6), (7, 14)]:
+            assert(double(amount=input) == expected)
+        it "rejects_negative":
+            bool rejected to false
+            try:
+                double(amount=-1)
+            catch RangeError error:
+                rejected to error.value == -1
+            assert(rejected)
+```
+
+```aug [Braces]
+/** 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 {
+        if amount < 0 {
+            throw RangeError(value=amount)
+        }
+        return next()
+    }
+}
+/**
+* Double a nonnegative amount.
+* @param amount Integer to double.
+* @return Twice the amount, with defined integer wrapping.
+* @throws RangeError A validation layer rejected a negative input.
+*/
+[Positive]
+double(int amount) returns int {
+    return amount * 2
+}
+test double {
+    when "positive" {
+        it "doubles" for (input, expected) in [(0, 0), (3, 6), (7, 14)] {
+            assert(double(amount=input) == expected)
+        }
+        it "rejects_negative" {
+            bool rejected to false
+            try {
+                double(amount=-1)
+            }
+            catch RangeError error {
+                rejected to error.value == -1
+            }
+            assert(rejected)
+        }
+    }
+}
+```
+
+:::
+
+::::
+
+:::: example-spec
+
+## Compiled specification {#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.md#symbol-RangeError) is a class implementing `Error`.
+- [`Positive`](numbers.md#symbol-Positive) is an interceptor.
+- [`double`](numbers.md#symbol-double) is a function returning `int`.
+- [`test double`](numbers.md#symbol-test-20-double) is a same-file test suite.
+
+### `RangeError` {#symbol-RangeError}
+
+[source](numbers.md#code)
+
+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.
+
+### `Positive` {#symbol-Positive}
+
+[source](numbers.md#code)
+
+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.
+
+#### `Positive.around` {#symbol-Positive.around}
+
+[source](numbers.md#code)
+
+**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.md#symbol-RangeError) with `value` = `amount`. Transfer control to a matching catch or propagate the failure.
+- Return call `next`.
+
+### `double` {#symbol-double}
+
+[source](numbers.md#code)
+
+**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.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.
+
+### `test double` {#symbol-test-20-double}
+
+[source](numbers.md#code)
+
+Same-file function tests for [`double`](numbers.md#symbol-double). Each case gets isolated setup and dependency bindings.
+
+#### Group `positive`
+
+##### `doubles`
+
+[source](numbers.md#code)
+
+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.md#symbol-double) with `amount` = `input` equals `expected`).
+
+##### `rejects_negative`
+
+[source](numbers.md#code)
+
+- Set `rejected` of type `bool` to `false`.
+- Try these operations:
+  - Call [`double`](numbers.md#symbol-double) with `amount` = `-1`.
+- If they fail with [`RangeError`](numbers.md#symbol-RangeError), name the failure `error` and recover:
+  - Set `rejected` to `value` of `error` equals `-1`.
+- Call `assert` with `rejected` = `rejected`.
+
+### Built-in operations used by this file
+
+- `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.
+
+[Full built-in reference](https://greenpandastudios.github.io/augscript/language-constructs).
+
+### Shared language rules
+
+See the [language reference](https://greenpandastudios.github.io/augscript/reference) for numeric, equality, ownership, and task rules.
+
+::::
+
+:::::

package/docs/examples/approved-design/index.md

@@ -0,0 +1,39 @@
+---
+title: "Modules and composition"
+generated: true
+source: "examples/approved-design"
+editLink: false
+prev: false
+next: false
+outline: [2, 3]
+---
+
+# Modules and composition
+
+Combine domain modules, generic values, explicit capabilities, and scoped providers.
+
+Read a file below to see its highlighted source and the Markdown produced by `aug spec`. Choose **Indentation** or **Braces** above the code. Both views describe the same checked program; your choice is kept when you open another file.
+
+## Project files
+
+- [`main.aug`](main.md)
+- [`counters.aug`](counters.md)
+- [`domain/app.aug`](domain/app.md)
+- [`domain/export.aug`](domain/export.md)
+- [`domain/models.aug`](domain/models.md)
+- [`domain/numbers.aug`](domain/numbers.md)
+
+- [`main.yaml`](main-yaml.md)
+
+## Try this project
+
+From a repository checkout with August installed:
+
+```sh
+aug check examples/approved-design
+aug spec examples/approved-design
+aug test examples/approved-design
+aug run examples/approved-design
+```
+
+[Browse all examples](../index.md)

package/docs/examples/approved-design/main-yaml.md

@@ -0,0 +1,24 @@
+---
+title: "main.yaml · Modules and composition"
+generated: true
+source: "examples/approved-design/main.yaml"
+editLink: false
+prev: false
+next: false
+outline: [2, 3]
+---
+
+# `main.yaml`
+
+[Modules and composition](index.md) · Project configuration
+
+```yaml
+block_style: indent
+indentation: tabs
+assignment: to
+lint:
+  - architecture
+module_dependencies:
+  - ".: domain"
+  - "domain:"
+```

package/docs/examples/approved-design/main.md

@@ -0,0 +1,215 @@
+---
+title: "main.aug · Modules and composition"
+generated: true
+source: "examples/approved-design/main.aug"
+editLink: false
+prev: false
+next: false
+outline: [2, 3]
+pageClass: aug-example-page
+---
+
+# `main.aug`
+
+[Modules and composition](index.md) · Source and specification
+
+::: details Files in this project
+
+- [`main.aug`](main.md)
+- [`counters.aug`](counters.md)
+- [`domain/app.aug`](domain/app.md)
+- [`domain/export.aug`](domain/export.md)
+- [`domain/models.aug`](domain/models.md)
+- [`domain/numbers.aug`](domain/numbers.md)
+
+:::
+
+::::: example-compare
+
+:::: example-code
+
+## Code {#code}
+
+::: code-group
+
+```aug [Indentation]
+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
+implement Console with SystemConsole
+implement Application with ApplicationImpl
+include Counters
+resolve Application to app
+app.start()
+names to {1: "apple", 2: "pear"}
+match names.get(key=2):
+    when null:
+        print(value="missing fruit")
+    when some name:
+        print(value=name)
+(code, label) to (3, "plum")
+print(value={Fruit(code=code, name=label), Fruit(name=label, code=code)}.length())
+scope:
+    resolve Counter to counter
+    borrow counter:
+        counter.increment()
+    print(value=counter.value())
+try:
+    print(value=double(amount=7))
+    double(amount=-1)
+catch RangeError error:
+    print(value="negative amount rejected")
+```
+
+```aug [Braces]
+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
+implement Console with SystemConsole
+implement Application with ApplicationImpl
+include Counters
+resolve Application to app
+app.start()
+names to {1: "apple", 2: "pear"}
+match names.get(key=2) {
+    when null {
+        print(value="missing fruit")
+    }
+    when some name {
+        print(value=name)
+    }
+}
+(code, label) to (3, "plum")
+print(value={Fruit(code=code, name=label), Fruit(name=label, code=code)}.length())
+scope {
+    resolve Counter to counter
+    borrow counter {
+        counter.increment()
+    }
+    print(value=counter.value())
+}
+try {
+    print(value=double(amount=7))
+    double(amount=-1)
+}
+catch RangeError error {
+    print(value="negative amount rejected")
+}
+```
+
+:::
+
+::::
+
+:::: example-spec
+
+## Compiled specification {#specification}
+
+August 0.19.0. This document is compiled from checked code with deterministic wording guided by Simplified Technical English.
+
+### In this file
+
+- Include providers from `Counters`.
+- Register 2 dependency providers before startup.
+- Run startup operations with checked error recovery.
+- Run 7 other startup steps in source order.
+
+### Dependency providers
+
+Register these providers before startup. Their declaration order does not set initialization order; shared instances initialize in dependency order.
+
+- Provide [`SystemConsole`](dependencies/august/0.19.0/io/contracts.md#symbol-SystemConsole) when `Console` is requested. Reuse one instance.
+- Provide [`ApplicationImpl`](domain/app.md#symbol-ApplicationImpl) when `Application` is requested. Reuse one instance. Required dependencies: `Console`.
+- Include the providers from [`Counters`](counters.md#symbol-Counters) before execution.
+
+### Startup, in source order
+
+- Set `app` to the instance provided for `Application`.
+- Call [`Application.start`](domain/app.md#symbol-Application.start) on `app`.
+- Set `names` to a map with `1` mapped to `"apple"`; `2` mapped to `"pear"`.
+- Select the matching case for call `get` on `names` with `key` = `2`:
+  - A null value, including omitted optional input:
+    - Call `print` with `value` = `"missing fruit"`.
+  - A present, non-null value, named `name`:
+    - Call `print` with `value` = `name`.
+- Split a tuple containing `3`, `"plum"` into `code`, `label`, in that order.
+- Call `print` with `value` = call `length` on a set containing call [`Fruit`](domain/models.md#symbol-Fruit) with `code` = `code`; `name` = `label`, call [`Fruit`](domain/models.md#symbol-Fruit) with `name` = `label`; `code` = `code`.
+- Create a dependency and task scope. Join its child tasks and release scoped values before leaving:
+  - Set `counter` to the instance provided for `Counter`.
+  - Grant exclusive mutable access to `counter` for this block, then end the borrow:
+    - Call [`Counter.increment`](counters.md#symbol-Counter.increment) on `counter`.
+  - Call `print` with `value` = call [`Counter.value`](counters.md#symbol-Counter.value) on `counter`.
+- Try these operations:
+  - Call `print` with `value` = call [`double`](domain/numbers.md#symbol-double) with `amount` = `7`.
+  - Call [`double`](domain/numbers.md#symbol-double) with `amount` = `-1`.
+- If they fail with [`RangeError`](domain/numbers.md#symbol-RangeError), name the failure `error` and recover:
+  - Call `print` with `value` = `"negative amount rejected"`.
+
+### Dependencies used by this file
+
+Only referenced types and operations appear here. Each name links to its complete specification.
+
+#### [`SystemConsole`](dependencies/august/0.19.0/io/contracts.md#symbol-SystemConsole)
+
+Class from `august.io`.
+
+Used as a type or provider.
+
+#### [`Counter`](counters.md#symbol-Counter)
+
+Interface from `counters`.
+
+- [`Counter.increment`](counters.md#symbol-Counter.increment) (no caller inputs) → `void`; changes `self`.
+- [`Counter.value`](counters.md#symbol-Counter.value) (no caller inputs) → `int`.
+
+#### [`Counters`](counters.md#symbol-Counters)
+
+Composition from `counters`.
+
+Used as a type or provider.
+
+#### [`Application`](domain/app.md#symbol-Application)
+
+Interface from `domain`.
+
+- [`Application.start`](domain/app.md#symbol-Application.start) (no caller inputs) → `void`; uses [`Console.write`](dependencies/august/0.19.0/io/contracts.md#symbol-Console.write).
+
+#### [`ApplicationImpl`](domain/app.md#symbol-ApplicationImpl)
+
+Class from `domain`.
+
+Used as a type or provider.
+
+#### [`Fruit`](domain/models.md#symbol-Fruit)
+
+Record from `domain`.
+
+- Construct with `code`: `int`, `name`: `string` → [`Fruit`](domain/models.md#symbol-Fruit).
+
+#### [`RangeError`](domain/numbers.md#symbol-RangeError)
+
+Class from `domain`.
+
+Used as a type or provider.
+
+#### [`double`](domain/numbers.md#symbol-double)
+
+Function from `domain`.
+
+- [`double`](domain/numbers.md#symbol-double) (`amount`: `int`) → `int`; can fail with `RangeError`.
+
+### Built-in operations used by this file
+
+- `Map<int, string>.get` (`key`: `int`) → `optional string`: Read a value by key; an absent key returns null. contains distinguishes an absent key from a stored null.
+- `Set<Fruit>.length` (no inputs) → `int`: Read the number of elements.
+- `print` (`value`: `any`) → `void`: Composition and test output. Other callables receive Console and declare uses console.write.
+
+[Full built-in reference](https://greenpandastudios.github.io/augscript/language-constructs).
+
+### Shared language rules
+
+See the [language reference](https://greenpandastudios.github.io/augscript/reference) for numeric, equality, ownership, and task rules.
+
+::::
+
+:::::

package/docs/examples/benchmark/index.md

@@ -0,0 +1,33 @@
+---
+title: "A finite benchmark"
+generated: true
+source: "examples/benchmark"
+editLink: false
+prev: false
+next: false
+outline: [2, 3]
+---
+
+# A finite benchmark
+
+Measure a deterministic arithmetic workload with aug bench.
+
+Read a file below to see its highlighted source and the Markdown produced by `aug spec`. Choose **Indentation** or **Braces** above the code. Both views describe the same checked program; your choice is kept when you open another file.
+
+## Project files
+
+- [`main.aug`](main.md)
+
+- [`main.yaml`](main-yaml.md)
+
+## Try this project
+
+From a repository checkout with August installed:
+
+```sh
+aug check examples/benchmark
+aug spec examples/benchmark
+aug run examples/benchmark
+```
+
+[Browse all examples](../index.md)

package/docs/examples/benchmark/main-yaml.md

@@ -0,0 +1,17 @@
+---
+title: "main.yaml · A finite benchmark"
+generated: true
+source: "examples/benchmark/main.yaml"
+editLink: false
+prev: false
+next: false
+outline: [2, 3]
+---
+
+# `main.yaml`
+
+[A finite benchmark](index.md) · Project configuration
+
+```yaml
+optimization: release
+```

package/docs/examples/benchmark/main.md

@@ -0,0 +1,117 @@
+---
+title: "main.aug · A finite benchmark"
+generated: true
+source: "examples/benchmark/main.aug"
+editLink: false
+prev: false
+next: false
+outline: [2, 3]
+pageClass: aug-example-page
+---
+
+# `main.aug`
+
+[A finite benchmark](index.md) · Source and specification
+
+::: details Files in this project
+
+- [`main.aug`](main.md)
+
+:::
+
+::::: example-compare
+
+:::: example-code
+
+## Code {#code}
+
+::: code-group
+
+```aug [Indentation]
+// A deterministic native workload: arithmetic and 20,000 hash entries.
+own Map<int,int> values = {}
+own Set<int> unique = {}
+int index = 0
+while index < 20000:
+    values.set(key=index, value=index * 3)
+    unique.add(value=index)
+    index = index + 1
+int checksum = 0
+for (key, value) in values:
+    if unique.contains(value=key):
+        checksum = checksum + value
+print(value=checksum)
+print(value=values.length() == unique.length())
+```
+
+```aug [Braces]
+// A deterministic native workload: arithmetic and 20,000 hash entries.
+own Map<int,int> values = {}
+own Set<int> unique = {}
+int index = 0
+while index < 20000 {
+    values.set(key=index, value=index * 3)
+    unique.add(value=index)
+    index = index + 1
+}
+int checksum = 0
+for (key, value) in values {
+    if unique.contains(value=key) {
+        checksum = checksum + value
+    }
+}
+print(value=checksum)
+print(value=values.length() == unique.length())
+```
+
+:::
+
+::::
+
+:::: example-spec
+
+## Compiled specification {#specification}
+
+August 0.19.0. This document is compiled from checked code with deterministic wording guided by Simplified Technical English.
+
+### In this file
+
+- Run 8 other startup steps in source order.
+
+### Startup, in source order
+
+- Set `values` of type `Map<int,int>` to a context-typed empty collection with no items.
+- This variable owns the value.
+- Set `unique` of type `Set<int>` to a context-typed empty collection with no items.
+- This variable owns the value.
+- Set `index` of type `int` to `0`.
+- While `index` is less than `20000`, repeat:
+  - Call `set` on `values` with `key` = `index`; `value` = (`index` times `3`).
+  - Call `add` on `unique` with `value` = `index`.
+  - Set `index` to `index` plus `1`.
+  - Check the condition again before the next iteration.
+- Set `checksum` of type `int` to `0`.
+- For each `key` and `value` in a snapshot of `values`, in iteration order:
+  - If call `contains` on `unique` with `value` = `key` is true:
+    - Set `checksum` to `checksum` plus `value`.
+- Call `print` with `value` = `checksum`.
+- Call `print` with `value` = (call `length` on `values` equals call `length` on `unique`).
+
+### Built-in operations used by this file
+
+- `Map<int, int>.length` (no inputs) → `int`: Read the number of elements.
+- `Map<int, int>.set` (`key`: `int`, `value`: `int`) → `void`: Insert or replace an entry with exclusive mutable access. Changes the receiver.
+- `Set<int>.add` (`value`: `int`) → `void`: Insert a unique element with exclusive mutable access. Changes the receiver.
+- `Set<int>.contains` (`value`: `int`) → `bool`: Test structural or identity equality with a stored element.
+- `Set<int>.length` (no inputs) → `int`: Read the number of elements.
+- `print` (`value`: `any`) → `void`: Composition and test output. Other callables receive Console and declare uses console.write.
+
+[Full built-in reference](https://greenpandastudios.github.io/augscript/language-constructs).
+
+### Shared language rules
+
+See the [language reference](https://greenpandastudios.github.io/augscript/reference) for numeric, equality, ownership, and task rules.
+
+::::
+
+:::::