@greenpandastudios/aug-cli 0.19.0 → 0.21.0

package/docs/examples/packages-math/src/arithmetic.md

@@ -29,8 +29,9 @@ pageClass: aug-example-page
 ::: code-group
 
 ```aug [Indentation]
+// aug-spec: "arithmetic.aug.md" explains this file. Read it before changes; refresh with aug spec.
 /** Add two integers. @param left First value. @param right Second value. @return Their sum. */
-add(int left, int right) returns int:
+add(int left, int right):
     return left + right
 test add:
     when "addition":
@@ -39,8 +40,9 @@ test add:
 ```
 
 ```aug [Braces]
+// aug-spec: "arithmetic.aug.md" explains this file. Read it before changes; refresh with aug spec.
 /** Add two integers. @param left First value. @param right Second value. @return Their sum. */
-add(int left, int right) returns int {
+add(int left, int right) {
     return left + right
 }
 test add {
@@ -60,61 +62,21 @@ test add {
 
 ## Compiled specification {#specification}
 
-August 0.19.0. This document is compiled from checked code with deterministic wording guided by Simplified Technical English.
+### `add` · [source](arithmetic.md#code) {#symbol-add}
 
-### In this file
+Add two integers. It takes `left` as an integer (First value) and `right` as an integer (Second value). It returns `int` — Their sum. It returns `left` plus `right`.
 
-- [`add`](arithmetic.md#symbol-add) is a function returning `int`.
-- [`test add`](arithmetic.md#symbol-test-20-add) is a same-file test suite.
+### `test add` · [source](arithmetic.md#code) {#symbol-test-20-add}
 
-### `add` {#symbol-add}
+Tests [`add`](arithmetic.md#symbol-add). Each case gets fresh setup and dependencies.
 
-[source](arithmetic.md#code)
+#### `addition`
 
-**Inputs**
+##### `adds_two_integers` · [source](arithmetic.md#code)
 
-- `left` (`int`) — required labeled input.
-- `right` (`int`) — required labeled input.
+The test requires [`add`](arithmetic.md#symbol-add) with `left` `2` and `right` `3` equals `5`.
 
-Returns: `int`.
-
-**What it does**
-
-- Return `left` plus `right`.
-
-**Author documentation**
-
-Add two integers.
-
-**Returns** Their sum.
-
-**Parameters**
-- `left`: First value.
-- `right`: Second value.
-
-### `test add` {#symbol-test-20-add}
-
-[source](arithmetic.md#code)
-
-Same-file function tests for [`add`](arithmetic.md#symbol-add). Each case gets isolated setup and dependency bindings.
-
-#### Group `addition`
-
-##### `adds_two_integers`
-
-[source](arithmetic.md#code)
-
-- Call `assert` with (call [`add`](arithmetic.md#symbol-add) with `left` = `2`; `right` = `3` equals `5`).
-
-### 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.
+Built-in operations follow the [language reference](https://greenpandastudios.github.io/augscript/language-constructs).
 
 ::::
 

package/docs/examples/packages-math/src/export.md

@@ -29,10 +29,12 @@ pageClass: aug-example-page
 ::: code-group
 
 ```aug [Indentation]
+// aug-spec: "export.aug.md" explains this file. Read it before changes; refresh with aug spec.
 export add from arithmetic
 ```
 
 ```aug [Braces]
+// aug-spec: "export.aug.md" explains this file. Read it before changes; refresh with aug spec.
 export add from arithmetic
 ```
 
@@ -44,19 +46,9 @@ export add from arithmetic
 
 ## Compiled specification {#specification}
 
-August 0.19.0. This document is compiled from checked code with deterministic wording guided by Simplified Technical English.
+### Exports
 
-### In this file
-
-- Export `add` from this folder.
-
-### Folder exports
-
-- Export the declaration `add` from [`arithmetic.aug`](arithmetic.md#symbol-add).
-
-### Shared language rules
-
-See the [language reference](https://greenpandastudios.github.io/augscript/reference) for numeric, equality, ownership, and task rules.
+Export the declaration `add` from [`arithmetic.aug`](arithmetic.md#symbol-add).
 
 ::::
 

package/docs/examples/records-benchmark/data.md

@@ -0,0 +1,55 @@
+---
+title: "data.aug · Record allocation benchmark"
+generated: true
+source: "benchmarks/records/data.aug"
+editLink: false
+prev: false
+next: false
+outline: [2, 3]
+pageClass: aug-example-page
+---
+
+# `data.aug`
+
+[Record allocation benchmark](index.md) · Source and specification
+
+::: details Files in this project
+
+- [`main.aug`](main.md)
+- [`data.aug`](data.md)
+
+:::
+
+::::: example-compare
+
+:::: example-code
+
+## Code {#code}
+
+::: code-group
+
+```aug [Indentation]
+// aug-spec: "data.aug.md" explains this file. Read it before changes; refresh with aug spec.
+record Item(int id, string name)
+```
+
+```aug [Braces]
+// aug-spec: "data.aug.md" explains this file. Read it before changes; refresh with aug spec.
+record Item(int id, string name)
+```
+
+:::
+
+::::
+
+:::: example-spec
+
+## Compiled specification {#specification}
+
+### `Item` · immutable record · [source](data.md#code) {#symbol-Item}
+
+It takes `id` as an integer, kept read-only and `name` as a string, kept read-only.
+
+::::
+
+:::::

package/docs/examples/records-benchmark/index.md

@@ -0,0 +1,36 @@
+---
+title: "Record allocation benchmark"
+generated: true
+source: "benchmarks/records"
+editLink: false
+prev: false
+next: false
+outline: [2, 3]
+---
+
+# Record allocation benchmark
+
+Retain immutable records and sum their fields.
+
+Open a file to read its source beside the explanation produced by `aug spec`. **Indentation** and **Braces** display the same checked program; your choice carries across file pages.
+
+## Project files
+
+- [`main.aug`](main.md)
+- [`data.aug`](data.md)
+
+
+## Try this project
+
+[Download this project](/downloads/records-benchmark.zip), then extract the archive in an empty working folder. It contains the checked source, configuration, and generated specs. [Install August](../../getting-started.md) once, then run these commands. Native libraries are prepared automatically when needed:
+
+```sh
+cd records-benchmark
+aug check .
+aug spec .
+aug run .
+```
+
+See [the performance page](../../performance.md) for measurements, input sizes, and reproduction steps.
+
+[Browse all examples](../index.md)

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

@@ -0,0 +1,85 @@
+---
+title: "main.aug · Record allocation benchmark"
+generated: true
+source: "benchmarks/records/main.aug"
+editLink: false
+prev: false
+next: false
+outline: [2, 3]
+pageClass: aug-example-page
+---
+
+# `main.aug`
+
+[Record allocation benchmark](index.md) · Source and specification
+
+::: details Files in this project
+
+- [`main.aug`](main.md)
+- [`data.aug`](data.md)
+
+:::
+
+::::: example-compare
+
+:::: example-code
+
+## Code {#code}
+
+::: code-group
+
+```aug [Indentation]
+// aug-spec: "main.aug.md" explains this file. Read it before changes; refresh with aug spec.
+import Item from data
+int iterations = 50000
+own List<Item> values = []
+int index = 0
+while index < iterations:
+    values.append(value=Item(id=index, name="August"))
+    index = index + 1
+int checksum = 0
+for item in values:
+    checksum = checksum + item.id
+print(value=checksum)
+```
+
+```aug [Braces]
+// aug-spec: "main.aug.md" explains this file. Read it before changes; refresh with aug spec.
+import Item from data
+int iterations = 50000
+own List<Item> values = []
+int index = 0
+while index < iterations {
+    values.append(value=Item(id=index, name="August"))
+    index = index + 1
+}
+int checksum = 0
+for item in values {
+    checksum = checksum + item.id
+}
+print(value=checksum)
+```
+
+:::
+
+::::
+
+:::: example-spec
+
+## Compiled specification {#specification}
+
+### Startup
+
+It sets `iterations` to `50000`. It sets `values` of type `List<Item>` to a list with no items. `values` of type `List<Item>` owns this value. It sets `index` to `0`.
+
+While `index` is less than `iterations`, it appends an [`Item`](data.md#symbol-Item) with `id` from `index` and `name` `"August"` to `values`; then it increases `index` by `1`. After the loop, it sets `checksum` to `0`. For each `item` in a snapshot of `values`, it increases `checksum` by `item.id`. After the loop, it prints `checksum`.
+
+### Dependencies
+
+It uses [`Item`](data.md#symbol-Item) (`id`) from `data`.
+
+Built-in operations follow the [language reference](https://greenpandastudios.github.io/augscript/language-constructs).
+
+::::
+
+:::::

package/docs/examples/startup-benchmark/index.md

@@ -12,7 +12,7 @@ outline: [2, 3]
 
 The small program used to measure process startup.
 
-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.
+Open a file to read its source beside the explanation produced by `aug spec`. **Indentation** and **Braces** display the same checked program; your choice carries across file pages.
 
 ## Project files
 
@@ -21,12 +21,13 @@ Read a file below to see its highlighted source and the Markdown produced by `au
 
 ## Try this project
 
-From a repository checkout with August installed:
+[Download this project](/downloads/startup-benchmark.zip), then extract the archive in an empty working folder. It contains the checked source, configuration, and generated specs. [Install August](../../getting-started.md) once, then run these commands. Native libraries are prepared automatically when needed:
 
 ```sh
-aug check benchmarks/startup
-aug spec benchmarks/startup
-aug run benchmarks/startup
+cd startup-benchmark
+aug check .
+aug spec .
+aug run .
 ```
 
 See [the performance page](../../performance.md) for measurements, input sizes, and reproduction steps.

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

@@ -28,10 +28,12 @@ pageClass: aug-example-page
 ::: code-group
 
 ```aug [Indentation]
+// aug-spec: "main.aug.md" explains this file. Read it before changes; refresh with aug spec.
 print(value=7)
 ```
 
 ```aug [Braces]
+// aug-spec: "main.aug.md" explains this file. Read it before changes; refresh with aug spec.
 print(value=7)
 ```
 
@@ -43,25 +45,11 @@ print(value=7)
 
 ## Compiled specification {#specification}
 
-August 0.19.0. This document is compiled from checked code with deterministic wording guided by Simplified Technical English.
+### Startup
 
-### In this file
+It prints `7`.
 
-- Run 1 other startup step in source order.
-
-### Startup, in source order
-
-- Call `print` with `value` = `7`.
-
-### Built-in operations used by this file
-
-- `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.
+Built-in operations follow the [language reference](https://greenpandastudios.github.io/augscript/language-constructs).
 
 ::::
 

package/docs/examples/strings-benchmark/index.md

@@ -0,0 +1,35 @@
+---
+title: "String processing benchmark"
+generated: true
+source: "benchmarks/strings"
+editLink: false
+prev: false
+next: false
+outline: [2, 3]
+---
+
+# String processing benchmark
+
+Split text into parts and sum their byte lengths.
+
+Open a file to read its source beside the explanation produced by `aug spec`. **Indentation** and **Braces** display the same checked program; your choice carries across file pages.
+
+## Project files
+
+- [`main.aug`](main.md)
+
+
+## Try this project
+
+[Download this project](/downloads/strings-benchmark.zip), then extract the archive in an empty working folder. It contains the checked source, configuration, and generated specs. [Install August](../../getting-started.md) once, then run these commands. Native libraries are prepared automatically when needed:
+
+```sh
+cd strings-benchmark
+aug check .
+aug spec .
+aug run .
+```
+
+See [the performance page](../../performance.md) for measurements, input sizes, and reproduction steps.
+
+[Browse all examples](../index.md)

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

@@ -0,0 +1,76 @@
+---
+title: "main.aug · String processing benchmark"
+generated: true
+source: "benchmarks/strings/main.aug"
+editLink: false
+prev: false
+next: false
+outline: [2, 3]
+pageClass: aug-example-page
+---
+
+# `main.aug`
+
+[String processing 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]
+// aug-spec: "main.aug.md" explains this file. Read it before changes; refresh with aug spec.
+int iterations = 20000
+int index = 0
+int checksum = 0
+while index < iterations:
+    parts = "August,clear,local,checked".split(separator=",")
+    for part in parts:
+        checksum = checksum + part.length()
+    index = index + 1
+print(value=checksum)
+```
+
+```aug [Braces]
+// aug-spec: "main.aug.md" explains this file. Read it before changes; refresh with aug spec.
+int iterations = 20000
+int index = 0
+int checksum = 0
+while index < iterations {
+    parts = "August,clear,local,checked".split(separator=",")
+    for part in parts {
+        checksum = checksum + part.length()
+    }
+    index = index + 1
+}
+print(value=checksum)
+```
+
+:::
+
+::::
+
+:::: example-spec
+
+## Compiled specification {#specification}
+
+### Startup
+
+It sets `iterations` to `20000`. It sets `index` and `checksum` separately, each to `0`. While `index` is less than `iterations`, it sets `parts` to `split` on `"August,clear,local,checked"` with `separator` `","`. For each `part` in a snapshot of `parts`, it increases `checksum` by the byte length of `part`.
+
+After the loop, it increases `index` by `1`. After the loop, it prints `checksum`.
+
+Built-in operations follow the [language reference](https://greenpandastudios.github.io/augscript/language-constructs).
+
+::::
+
+:::::

package/docs/examples/tasks-benchmark/index.md

@@ -0,0 +1,36 @@
+---
+title: "Task scheduling benchmark"
+generated: true
+source: "benchmarks/tasks"
+editLink: false
+prev: false
+next: false
+outline: [2, 3]
+---
+
+# Task scheduling benchmark
+
+Start and join two tasks in each bounded scope.
+
+Open a file to read its source beside the explanation produced by `aug spec`. **Indentation** and **Braces** display the same checked program; your choice carries across file pages.
+
+## Project files
+
+- [`main.aug`](main.md)
+- [`operations.aug`](operations.md)
+
+
+## Try this project
+
+[Download this project](/downloads/tasks-benchmark.zip), then extract the archive in an empty working folder. It contains the checked source, configuration, and generated specs. [Install August](../../getting-started.md) once, then run these commands. Native libraries are prepared automatically when needed:
+
+```sh
+cd tasks-benchmark
+aug check .
+aug spec .
+aug run .
+```
+
+See [the performance page](../../performance.md) for measurements, input sizes, and reproduction steps.
+
+[Browse all examples](../index.md)

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

@@ -0,0 +1,89 @@
+---
+title: "main.aug · Task scheduling benchmark"
+generated: true
+source: "benchmarks/tasks/main.aug"
+editLink: false
+prev: false
+next: false
+outline: [2, 3]
+pageClass: aug-example-page
+---
+
+# `main.aug`
+
+[Task scheduling benchmark](index.md) · Source and specification
+
+::: details Files in this project
+
+- [`main.aug`](main.md)
+- [`operations.aug`](operations.md)
+
+:::
+
+::::: example-compare
+
+:::: example-code
+
+## Code {#code}
+
+::: code-group
+
+```aug [Indentation]
+// aug-spec: "main.aug.md" explains this file. Read it before changes; refresh with aug spec.
+import compute from operations
+int iterations = 2000
+int index = 0
+int checksum = 0
+while index < iterations:
+    scope:
+        first = start compute(value=index)
+        second = start compute(value=index + 1)
+        (left, right) = wait for first and second
+        checksum = checksum + left + right
+    index = index + 1
+print(value=checksum)
+```
+
+```aug [Braces]
+// aug-spec: "main.aug.md" explains this file. Read it before changes; refresh with aug spec.
+import compute from operations
+int iterations = 2000
+int index = 0
+int checksum = 0
+while index < iterations {
+    scope {
+        first = start compute(value=index)
+        second = start compute(value=index + 1)
+        (left, right) = wait for first and second
+        checksum = checksum + left + right
+    }
+    index = index + 1
+}
+print(value=checksum)
+```
+
+:::
+
+::::
+
+:::: example-spec
+
+## Compiled specification {#specification}
+
+### Startup
+
+It sets `iterations` to `2000`. It sets `index` and `checksum` separately, each to `0`. While `index` is less than `iterations`, within a task and ownership scope, it sets `first` to a child task running [`compute`](operations.md#symbol-compute) with `value` from `index` with its inputs captured now. It sets `second` to a child task running [`compute`](operations.md#symbol-compute) with `value` from `index` plus `1` with its inputs captured now.
+
+It splits the result of waiting for `first` and `second` in input order; propagate failures into `left` and `right` in order. It sets `checksum` to (`checksum` plus `left`) plus `right`. On leaving this scope, join its child tasks and release its local values. It increases `index` by `1`.
+
+After the loop, it prints `checksum`.
+
+### Dependencies
+
+It uses [`compute`](operations.md#symbol-compute) from `operations`.
+
+Built-in operations follow the [language reference](https://greenpandastudios.github.io/augscript/language-constructs).
+
+::::
+
+:::::

package/docs/examples/tasks-benchmark/operations.md

@@ -0,0 +1,58 @@
+---
+title: "operations.aug · Task scheduling benchmark"
+generated: true
+source: "benchmarks/tasks/operations.aug"
+editLink: false
+prev: false
+next: false
+outline: [2, 3]
+pageClass: aug-example-page
+---
+
+# `operations.aug`
+
+[Task scheduling benchmark](index.md) · Source and specification
+
+::: details Files in this project
+
+- [`main.aug`](main.md)
+- [`operations.aug`](operations.md)
+
+:::
+
+::::: example-compare
+
+:::: example-code
+
+## Code {#code}
+
+::: code-group
+
+```aug [Indentation]
+// aug-spec: "operations.aug.md" explains this file. Read it before changes; refresh with aug spec.
+compute(int value) returns int:
+    return value * 3 + 1
+```
+
+```aug [Braces]
+// aug-spec: "operations.aug.md" explains this file. Read it before changes; refresh with aug spec.
+compute(int value) returns int {
+    return value * 3 + 1
+}
+```
+
+:::
+
+::::
+
+:::: example-spec
+
+## Compiled specification {#specification}
+
+### `compute` · [source](operations.md#code) {#symbol-compute}
+
+It takes `value` as an integer. It returns (`value` times `3`) plus `1`.
+
+::::
+
+:::::