@greenpandastudios/aug-cli 0.19.0 → 0.21.0

package/docs/examples/interceptors/main.md

@@ -31,6 +31,7 @@ pageClass: aug-example-page
 ::: code-group
 
 ```aug [Indentation]
+// aug-spec: "main.aug.md" explains this file. Read it before changes; refresh with aug spec.
 import Console and SystemConsole from august.io
 implement Console with SystemConsole
 import Logger from logging
@@ -52,6 +53,7 @@ catch ValidationError error:
 ```
 
 ```aug [Braces]
+// aug-spec: "main.aug.md" explains this file. Read it before changes; refresh with aug spec.
 import Console and SystemConsole from august.io
 implement Console with SystemConsole
 import Logger from logging
@@ -84,78 +86,21 @@ catch ValidationError error {
 
 ## Compiled specification {#specification}
 
-August 0.19.0. This document is compiled from checked code with deterministic wording guided by Simplified Technical English.
+### Providers
 
-### In this file
+`Console` is provided by [`SystemConsole`](dependencies/august/0.21.0/io/contracts.md#symbol-SystemConsole). The same instance is shared. `Logger` is provided by [`ConsoleLogger`](logging.md#symbol-ConsoleLogger). The same instance is shared.
 
-- Register 2 dependency providers before startup.
-- Run startup operations with checked error recovery.
-- Run 2 other startup steps in source order.
+### Startup
 
-### Dependency providers
+It prints [`describe`](app.md#symbol-describe) with `label` `"value"` and `x` `6` using injected `Logger` for `logger` and `Console` for `console`. If this work raises [`ValidationError`](interceptors.md#symbol-ValidationError), it prints `"rejected"`. It sets `greeter` to a [`Greeter`](app.md#symbol-Greeter) with `name` `"AugScript"` using injected `Logger` for `_logger`. It prints [`greeter.greet`](app.md#symbol-Greeter.greet) using injected `Logger` for `logger` and `Console` for `console`.
 
-Register these providers before startup. Their declaration order does not set initialization order; shared instances initialize in dependency order.
+It tries to call [`describe`](app.md#symbol-describe) with `x` `-1` and `label` `"invalid"` using injected `Logger` for `logger` and `Console` for `console`. If this work raises [`ValidationError`](interceptors.md#symbol-ValidationError), it prints `"rejected"`.
 
-- Provide [`SystemConsole`](dependencies/august/0.19.0/io/contracts.md#symbol-SystemConsole) when `Console` is requested. Reuse one instance.
-- Provide [`ConsoleLogger`](logging.md#symbol-ConsoleLogger) when `Logger` is requested. Reuse one instance.
+### Dependencies
 
-### Startup, in source order
+It uses [`SystemConsole`](dependencies/august/0.21.0/io/contracts.md#symbol-SystemConsole) from `august.io`. It uses [`Greeter`](app.md#symbol-Greeter) ([`greet`](app.md#symbol-Greeter.greet)) and [`describe`](app.md#symbol-describe) from `app`. It uses [`ValidationError`](interceptors.md#symbol-ValidationError) from `interceptors`. It uses [`ConsoleLogger`](logging.md#symbol-ConsoleLogger) from `logging`.
 
-- Try these operations:
-  - Call `print` with `value` = call [`describe`](app.md#symbol-describe) with `label` = `"value"`; `x` = `6`; inject `logger` from `Logger`, `console` from `Console`.
-- If they fail with [`ValidationError`](interceptors.md#symbol-ValidationError), name the failure `error` and recover:
-  - Call `print` with `value` = `"rejected"`.
-- Set `greeter` to call [`Greeter`](app.md#symbol-Greeter) with `name` = `"AugScript"`; inject `_logger` from `Logger`.
-- Call `print` with `value` = call [`Greeter.greet`](app.md#symbol-Greeter.greet) on `greeter`; inject `logger` from `Logger`, `console` from `Console`.
-- Try these operations:
-  - Call [`describe`](app.md#symbol-describe) with `x` = `-1`; `label` = `"invalid"`; inject `logger` from `Logger`, `console` from `Console`.
-- If they fail with [`ValidationError`](interceptors.md#symbol-ValidationError), name the failure `error` and recover:
-  - Call `print` with `value` = `"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.
-
-#### [`Greeter`](app.md#symbol-Greeter)
-
-Class from `app`.
-
-- Construct with `name`: `string` → [`Greeter`](app.md#symbol-Greeter).
-- [`Greeter.greet`](app.md#symbol-Greeter.greet) (no caller inputs) → `string`; inject `logger`: [`Logger`](logging.md#symbol-Logger), `console`: [`Console`](dependencies/august/0.19.0/io/contracts.md#symbol-Console); uses [`Console.write`](dependencies/august/0.19.0/io/contracts.md#symbol-Console.write).
-
-#### [`describe`](app.md#symbol-describe)
-
-Function from `app`.
-
-- [`describe`](app.md#symbol-describe) (`x`: `int`, `label`: `string`) → `string`; inject `logger`: [`Logger`](logging.md#symbol-Logger), `console`: [`Console`](dependencies/august/0.19.0/io/contracts.md#symbol-Console); uses [`Console.write`](dependencies/august/0.19.0/io/contracts.md#symbol-Console.write); can fail with `ValidationError`.
-
-#### [`ValidationError`](interceptors.md#symbol-ValidationError)
-
-Class from `interceptors`.
-
-Used as a type or provider.
-
-#### [`ConsoleLogger`](logging.md#symbol-ConsoleLogger)
-
-Class from `logging`.
-
-Used as a type or provider.
-
-### 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/json-benchmark/data.md

@@ -29,10 +29,12 @@ pageClass: aug-example-page
 ::: code-group
 
 ```aug [Indentation]
+// aug-spec: "data.aug.md" explains this file. Read it before changes; refresh with aug spec.
 record Payload(int id, string message, List<int> values)
 ```
 
 ```aug [Braces]
+// aug-spec: "data.aug.md" explains this file. Read it before changes; refresh with aug spec.
 record Payload(int id, string message, List<int> values)
 ```
 
@@ -44,27 +46,9 @@ record Payload(int id, string message, List<int> values)
 
 ## Compiled specification {#specification}
 
-August 0.19.0. This document is compiled from checked code with deterministic wording guided by Simplified Technical English.
+### `Payload` · immutable record · [source](data.md#code) {#symbol-Payload}
 
-### In this file
-
-- [`Payload`](data.md#symbol-Payload) is an immutable record.
-
-### `Payload` {#symbol-Payload}
-
-[source](data.md#code)
-
-Immutable record.
-
-**Inputs**
-
-- `id` (`int`) — required labeled input — stored as `id` and read-only after initialization.
-- `message` (`string`) — required labeled input — stored as `message` and read-only after initialization.
-- `values` (`List<int>`) — required labeled input — stored as `values` 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.
+It takes `id` as an integer, kept read-only, `message` as a string, kept read-only, and `values` as `List<int>`, kept read-only.
 
 ::::
 

package/docs/examples/json-benchmark/dependencies/packages/@git/url_2d3c37c690c0fa115be1/0.0.0-git.a39fc582565d4fca40be4f75fa304d71adc69301/contracts.md

@@ -0,0 +1,67 @@
+---
+title: "packages/@git/url_2d3c37c690c0fa115be1/0.0.0-git.a39fc582565d4fca40be4f75fa304d71adc69301/contracts.aug · JSON benchmark"
+generated: true
+source: "benchmarks/json/.aug-spec/packages/@git/url_2d3c37c690c0fa115be1/0.0.0-git.a39fc582565d4fca40be4f75fa304d71adc69301/contracts.aug"
+editLink: false
+prev: false
+next: false
+outline: [2, 3]
+search: false
+pageClass: aug-example-page
+---
+
+# `packages/@git/url_2d3c37c690c0fa115be1/0.0.0-git.a39fc582565d4fca40be4f75fa304d71adc69301/contracts.aug`
+
+[JSON benchmark](../../../../../index.md) · Dependency source and specification
+
+This is the exact dependency version used by this example.
+
+::::: example-compare
+
+:::: example-code
+
+## Code {#code}
+
+::: code-group
+
+```aug [Indentation]
+extern C value pure _aug_json_parse(string input) returns Json unless JsonError
+/** Parse strict UTF-8 JSON. Duplicate keys, invalid Unicode, oversized integers, and nesting beyond 64 levels raise JsonError. */
+parse(string input) returns Json unless JsonError:
+    unsafe:
+        return _aug_json_parse(input)
+```
+
+```aug [Braces]
+extern C value pure _aug_json_parse(string input) returns Json unless JsonError
+/** Parse strict UTF-8 JSON. Duplicate keys, invalid Unicode, oversized integers, and nesting beyond 64 levels raise JsonError. */
+parse(string input) returns Json unless JsonError {
+    unsafe {
+        return _aug_json_parse(input)
+    }
+}
+```
+
+:::
+
+::::
+
+:::: example-spec
+
+## Compiled specification {#specification}
+
+### `parse` · [source](contracts.md#code) {#symbol-parse}
+
+Parse strict UTF-8 JSON. Duplicate keys, invalid Unicode, oversized integers, and nesting beyond 64 levels raise JsonError. It takes `input` as a string. Failures can raise `JsonError`.
+
+Within an unsafe block, it returns [`_aug_json_parse`](contracts.md#symbol-_aug_json_parse) with `input`. Native operations must satisfy their declared C contracts.
+
+### `_aug_json_parse` · [source](contracts.md#code) {#symbol-_aug_json_parse}
+
+It is private to its defining scope. It takes `input` as a string. It returns `Json`. Failures can raise `JsonError`.
+
+Native C implementation; only its declared contract is visible here.
+
+::::
+
+:::::

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

@@ -12,22 +12,24 @@ outline: [2, 3]
 
 Parse, decode, and serialize a typed record 5,000 times.
 
-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
 
 - [`main.aug`](main.md)
 - [`data.aug`](data.md)
 
+- [`main.yaml`](main-yaml.md)
 
 ## Try this project
 
-From a repository checkout with August installed:
+[Download this project](/downloads/json-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/json
-aug spec benchmarks/json
-aug run benchmarks/json
+cd json-benchmark
+aug check .
+aug spec .
+aug run .
 ```
 
 See [the performance page](../../performance.md) for measurements, input sizes, and reproduction steps.

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

@@ -0,0 +1,20 @@
+---
+title: "main.yaml · JSON benchmark"
+generated: true
+source: "benchmarks/json/main.yaml"
+editLink: false
+prev: false
+next: false
+outline: [2, 3]
+---
+
+# `main.yaml`
+
+[JSON benchmark](index.md) · Project configuration
+
+```yaml
+
+
+packages:
+  json: "https://github.com/GreenPandaStudios/augscript/src/stdlib/json#v0.19.0"
+```

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

@@ -29,7 +29,8 @@ pageClass: aug-example-page
 ::: code-group
 
 ```aug [Indentation]
-import parse from august.json
+// aug-spec: "main.aug.md" explains this file. Read it before changes; refresh with aug spec.
+import parse from json
 import Payload from data
 int checksum = 0
 int index = 0
@@ -46,7 +47,8 @@ catch JsonError error:
 ```
 
 ```aug [Braces]
-import parse from august.json
+// aug-spec: "main.aug.md" explains this file. Read it before changes; refresh with aug spec.
+import parse from json
 import Payload from data
 int checksum = 0
 int index = 0
@@ -73,58 +75,17 @@ catch JsonError error {
 
 ## 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 sets `checksum` and `index` separately, each to `0`. While `index` is less than `5000`, it sets `document` to [`parse`](dependencies/packages/%40git/url_2d3c37c690c0fa115be1/0.0.0-git.a39fc582565d4fca40be4f75fa304d71adc69301/contracts.md#symbol-parse) with `input` `"{\"id\":7,\"message\":\"hello\",\"values\":[1,2,3]}"`. It sets `payload` to `document.decode` for [`Payload`](data.md#symbol-Payload). It sets `encoded` to `stringify` on a `Json` with `value` from `payload`.
 
-- Run startup operations with checked error recovery.
-- Run 2 other startup steps in source order.
+It sets `checksum` to (`checksum` plus `payload.id`) plus the byte length of `encoded`. It increases `index` by `1`. After the loop, it prints `checksum`. If this work raises `JsonError`, it calls `exit` with `status` `1`.
 
-### Startup, in source order
+### Dependencies
 
-- Set `checksum` of type `int` to `0`.
-- Set `index` of type `int` to `0`.
-- Try these operations:
-  - While `index` is less than `5000`, repeat:
-    - Set `document` to call [`parse`](dependencies/august/0.19.0/json/contracts.md#symbol-parse) with `input` = `"{\"id\":7,\"message\":\"hello\",\"values\":[1,2,3]}"`.
-    - Set `payload` to call `decode` on `document` with type arguments [`Payload`](data.md#symbol-Payload).
-    - Set `encoded` to call `stringify` on call `Json` with `value` = `payload`.
-    - Set `checksum` to (`checksum` plus `id` of `payload`) plus call `length` on `encoded`.
-    - Set `index` to `index` plus `1`.
-    - Check the condition again before the next iteration.
-  - Call `print` with `value` = `checksum`.
-- If they fail with `JsonError`, name the failure `error` and recover:
-  - Call `exit` with `status` = `1`.
+It uses [`parse`](dependencies/packages/%40git/url_2d3c37c690c0fa115be1/0.0.0-git.a39fc582565d4fca40be4f75fa304d71adc69301/contracts.md#symbol-parse) from `json`. It uses [`Payload`](data.md#symbol-Payload) (`id`) from `data`.
 
-### Dependencies used by this file
-
-Only referenced types and operations appear here. Each name links to its complete specification.
-
-#### [`parse`](dependencies/august/0.19.0/json/contracts.md#symbol-parse)
-
-Function from `august.json`.
-
-- [`parse`](dependencies/august/0.19.0/json/contracts.md#symbol-parse) (`input`: `string`) → `Json`; can fail with `JsonError`.
-
-#### [`Payload`](data.md#symbol-Payload)
-
-Record from `data`.
-
-- Read `id` (`int`).
-
-### Built-in operations used by this file
-
-- `Json.decode` (no inputs) → `Payload`: Decode a checked record or data type: json.decode<Profile>(). Unknown fields, type mismatches, and validation errors are rejected. Can fail with `JsonError`.
-- `Json.stringify` (no inputs) → `string`: Serialize this JSON value with checked UTF-8 escaping and exact int64 values. Can fail with `JsonError`.
-- `exit` (`status`: `int`) → `void`: Exit from main with a status from 0 to 255 after cancellation and cleanup.
-- `print` (`value`: `any`) → `void`: Composition and test output. Other callables receive Console and declare uses console.write.
-- `string.length` (no inputs) → `int`: Read the number of UTF-8 bytes. Unicode text is preserved losslessly.
-
-[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/list-benchmark/index.md

@@ -0,0 +1,35 @@
+---
+title: "List traversal benchmark"
+generated: true
+source: "benchmarks/list"
+editLink: false
+prev: false
+next: false
+outline: [2, 3]
+---
+
+# List traversal benchmark
+
+Grow a list and sum its snapshot values.
+
+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/list-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 list-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/list-benchmark/main.md

@@ -0,0 +1,78 @@
+---
+title: "main.aug · List traversal benchmark"
+generated: true
+source: "benchmarks/list/main.aug"
+editLink: false
+prev: false
+next: false
+outline: [2, 3]
+pageClass: aug-example-page
+---
+
+# `main.aug`
+
+[List traversal 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 = 100000
+own List<int> values = []
+int index = 0
+while index < iterations:
+    values.append(value=index * 3)
+    index = index + 1
+int checksum = 0
+for value in values:
+    checksum = checksum + value
+print(value=checksum)
+```
+
+```aug [Braces]
+// aug-spec: "main.aug.md" explains this file. Read it before changes; refresh with aug spec.
+int iterations = 100000
+own List<int> values = []
+int index = 0
+while index < iterations {
+    values.append(value=index * 3)
+    index = index + 1
+}
+int checksum = 0
+for value in values {
+    checksum = checksum + value
+}
+print(value=checksum)
+```
+
+:::
+
+::::
+
+:::: example-spec
+
+## Compiled specification {#specification}
+
+### Startup
+
+It sets `iterations` to `100000`. It sets `values` of type `List<int>` to a list with no items. `values` of type `List<int>` owns this value. It sets `index` to `0`.
+
+While `index` is less than `iterations`, it appends `index` times `3` to `values`; then it increases `index` by `1`. After the loop, it sets `checksum` to `0`. For each `value` in a snapshot of `values`, it increases `checksum` by `value`. After the loop, it prints `checksum`.
+
+Built-in operations follow the [language reference](https://greenpandastudios.github.io/augscript/language-constructs).
+
+::::
+
+:::::

package/docs/examples/map-churn-benchmark/index.md

@@ -0,0 +1,35 @@
+---
+title: "Map deletion benchmark"
+generated: true
+source: "benchmarks/map-churn"
+editLink: false
+prev: false
+next: false
+outline: [2, 3]
+---
+
+# Map deletion benchmark
+
+Delete, replace and reinsert entries, then check values and insertion order.
+
+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/map-churn-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 map-churn-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/map-churn-benchmark/main.md

@@ -0,0 +1,106 @@
+---
+title: "main.aug · Map deletion benchmark"
+generated: true
+source: "benchmarks/map-churn/main.aug"
+editLink: false
+prev: false
+next: false
+outline: [2, 3]
+pageClass: aug-example-page
+---
+
+# `main.aug`
+
+[Map deletion 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 = 4000
+own Map<int,int> entries = {}
+int index = 0
+while index < iterations:
+    entries.set(key=index, value=index * 3)
+    index = index + 1
+index = 0
+while index < iterations:
+    entries.take(key=index)
+    index = index + 2
+index = 0
+while index < iterations:
+    entries.set(key=index, value=index * 7)
+    index = index + 1
+int checksum = 0
+int position = 1
+for (key, value) in entries:
+    checksum = checksum + key * position + value
+    position = position + 1
+print(value=checksum)
+print(value=entries.length())
+```
+
+```aug [Braces]
+// aug-spec: "main.aug.md" explains this file. Read it before changes; refresh with aug spec.
+int iterations = 4000
+own Map<int,int> entries = {}
+int index = 0
+while index < iterations {
+    entries.set(key=index, value=index * 3)
+    index = index + 1
+}
+index = 0
+while index < iterations {
+    entries.take(key=index)
+    index = index + 2
+}
+index = 0
+while index < iterations {
+    entries.set(key=index, value=index * 7)
+    index = index + 1
+}
+int checksum = 0
+int position = 1
+for (key, value) in entries {
+    checksum = checksum + key * position + value
+    position = position + 1
+}
+print(value=checksum)
+print(value=entries.length())
+```
+
+:::
+
+::::
+
+:::: example-spec
+
+## Compiled specification {#specification}
+
+### Startup
+
+It sets `iterations` to `4000`. It sets `entries` of type `Map<int,int>` to a context-typed empty collection with no items. `entries` of type `Map<int,int>` owns this value. It sets `index` to `0`.
+
+While `index` is less than `iterations`, it stores `index` times `3` in `entries` under `index`; then it increases `index` by `1`. After the loop, it sets `index` to `0`. While `index` is less than `iterations`, it removes the key `index` from `entries`; then it increases `index` by `2`. After the loop, it sets `index` to `0`.
+
+While `index` is less than `iterations`, it stores `index` times `7` in `entries` under `index`; then it increases `index` by `1`. After the loop, it sets `checksum` to `0`. It sets `position` to `1`. For each `key` and `value` in a snapshot of `entries`, it sets `checksum` to (`checksum` plus (`key` times `position`)) plus `value`; then it increases `position` by `1`.
+
+After the loop, it prints `checksum`. It prints the number of elements in `entries`.
+
+Built-in operations follow the [language reference](https://greenpandastudios.github.io/augscript/language-constructs).
+
+::::
+
+:::::