@greenpandastudios/aug-cli 0.20.1 → 0.21.0

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).
+
+::::
+
+:::::

package/docs/examples/native-blake3/dependencies/packages/@greenpandastudios/aug-blake3/0.1.3/api.md

@@ -0,0 +1,104 @@
+---
+title: "packages/@greenpandastudios/aug-blake3/0.1.3/api.aug · Hashing with Rust BLAKE3"
+generated: true
+source: "examples/native-blake3/.aug-spec/packages/@greenpandastudios/aug-blake3/0.1.3/api.aug"
+editLink: false
+prev: false
+next: false
+outline: [2, 3]
+search: false
+pageClass: aug-example-page
+---
+
+# `packages/@greenpandastudios/aug-blake3/0.1.3/api.aug`
+
+[Hashing with Rust BLAKE3](../../../../../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]
+// aug-spec: "api.aug.md" explains this file. Read it before changes; refresh with aug spec.
+import HashError from contracts
+extern C _hash(Bytes input) returns string unless HashError
+/** Return a lowercase 64-character BLAKE3 digest, computed by the Rust crate. */
+hash(Bytes input) returns string:
+    unsafe:
+        return _hash(input)
+test hash:
+    when "vectors":
+        it "hashes_abc":
+            Bytes input = "abc".bytes()
+            assert(
+                hash(input) == "6437b3ac38465133ffb63b75273a8db548c558465d79db03fd359c6cd5bd9d85"
+            )
+```
+
+```aug [Braces]
+// aug-spec: "api.aug.md" explains this file. Read it before changes; refresh with aug spec.
+import HashError from contracts
+extern C _hash(Bytes input) returns string unless HashError
+/** Return a lowercase 64-character BLAKE3 digest, computed by the Rust crate. */
+hash(Bytes input) returns string {
+    unsafe {
+        return _hash(input)
+    }
+}
+test hash {
+    when "vectors" {
+        it "hashes_abc" {
+            Bytes input = "abc".bytes()
+            assert(
+                hash(input) == "6437b3ac38465133ffb63b75273a8db548c558465d79db03fd359c6cd5bd9d85"
+            )
+        }
+    }
+}
+```
+
+:::
+
+::::
+
+:::: example-spec
+
+## Compiled specification {#specification}
+
+### `hash` · [source](api.md#code) {#symbol-hash}
+
+Return a lowercase 64-character BLAKE3 digest, computed by the Rust crate. It takes `input` as `Bytes`. Failures can raise [`HashError`](contracts.md#symbol-HashError).
+
+Within an unsafe block, it returns [`_hash`](api.md#symbol-_hash) with `input`. Native operations must satisfy their declared C contracts.
+
+### `_hash` · [source](api.md#code) {#symbol-_hash}
+
+It is private to its defining scope. It takes `input` as `Bytes`. It returns `string`. Failures can raise [`HashError`](contracts.md#symbol-HashError).
+
+Native implementation: `@greenpandastudios/aug-blake3@0.1.3`, `1.8.7`. Supported targets: linux arm64 glibc 2.36+, linux x64 glibc 2.36+, macos arm64 14.0+. Binding contract: [`native.abi.json`](native.abi-json.md) (SHA-256 `3bf8dea97cde70a03021bf77ea08314d6d37fe7b4935ff16030b2ab929c21279`). It calls `aug_blake3_hash_v1` through the C ABI on the caller thread; a blocking native call blocks that thread. August copies the returned buffer, then calls `aug_blake3_text_release_v1` to release it. The compiler checks the provider, descriptor digest, signature and ownership at August call sites. The native author promises not to retain inputs, enter August from foreign threads, or unwind across the C boundary; internal native workers may run. The compiler does not prove those promises.
+
+### `test hash` · [source](api.md#code) {#symbol-test-20-hash}
+
+Tests [`hash`](api.md#symbol-hash). Each case gets fresh setup and dependencies.
+
+#### `vectors`
+
+##### `hashes_abc` · [source](api.md#code)
+
+It sets `input` of type `Bytes` to `bytes` on `"abc"`. The test requires [`hash`](api.md#symbol-hash) with `input` equals `"6437b3ac38465133ffb63b75273a8db548c558465d79db03fd359c6cd5bd9d85"`.
+
+### Dependencies
+
+It uses [`HashError`](contracts.md#symbol-HashError) from `contracts`.
+
+Built-in operations follow the [language reference](https://greenpandastudios.github.io/augscript/language-constructs).
+
+::::
+
+:::::

package/docs/examples/native-blake3/dependencies/packages/@greenpandastudios/aug-blake3/0.1.3/contracts.md

@@ -0,0 +1,54 @@
+---
+title: "packages/@greenpandastudios/aug-blake3/0.1.3/contracts.aug · Hashing with Rust BLAKE3"
+generated: true
+source: "examples/native-blake3/.aug-spec/packages/@greenpandastudios/aug-blake3/0.1.3/contracts.aug"
+editLink: false
+prev: false
+next: false
+outline: [2, 3]
+search: false
+pageClass: aug-example-page
+---
+
+# `packages/@greenpandastudios/aug-blake3/0.1.3/contracts.aug`
+
+[Hashing with Rust BLAKE3](../../../../../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]
+// aug-spec: "contracts.aug.md" explains this file. Read it before changes; refresh with aug spec.
+HashError(int code, string message) implements Error:
+    pass
+```
+
+```aug [Braces]
+// aug-spec: "contracts.aug.md" explains this file. Read it before changes; refresh with aug spec.
+HashError(int code, string message) implements Error {
+    pass
+}
+```
+
+:::
+
+::::
+
+:::: example-spec
+
+## Compiled specification {#specification}
+
+### `HashError` · class · [source](contracts.md#code) {#symbol-HashError}
+
+It implements `Error`. It takes `code` as an integer, kept read-only and `message` as a string, kept read-only.
+
+::::
+
+:::::

package/docs/examples/native-blake3/dependencies/packages/@greenpandastudios/aug-blake3/0.1.3/native.abi-json.md

@@ -0,0 +1,48 @@
+---
+title: "Native binding contract · Hashing with Rust BLAKE3"
+generated: true
+source: "examples/native-blake3/.aug-spec/packages/@greenpandastudios/aug-blake3/0.1.3/native.abi.json"
+editLink: false
+prev: false
+next: false
+outline: [2, 3]
+search: false
+---
+
+# Native binding contract
+
+[Hashing with Rust BLAKE3](../../../../../index.md)
+
+This is the exact descriptor checked for this dependency. It records native symbols, ownership, errors, and ABI boundaries. The compiler checks August declarations against it; foreign implementations remain the native author’s responsibility.
+
+```json
+{
+  "format": 1,
+  "profile": "aug-native-abi-1",
+  "resources": [],
+  "functions": [
+    {
+      "module": "api",
+      "name": "_hash",
+      "symbol": "aug_blake3_hash_v1",
+      "params": [
+        {
+          "name": "input",
+          "kind": "bytes"
+        }
+      ],
+      "result": {
+        "kind": "utf8",
+        "release": "aug_blake3_text_release_v1"
+      },
+      "error": "contracts.HashError",
+      "callingConvention": "C",
+      "status": "i32",
+      "uses": [],
+      "changes": [],
+      "thread": "caller",
+      "retainsInputs": false
+    }
+  ]
+}
+```

package/docs/examples/native-blake3/hashing.md

@@ -0,0 +1,93 @@
+---
+title: "hashing.aug · Hashing with Rust BLAKE3"
+generated: true
+source: "examples/native-blake3/hashing.aug"
+editLink: false
+prev: false
+next: false
+outline: [2, 3]
+pageClass: aug-example-page
+---
+
+# `hashing.aug`
+
+[Hashing with Rust BLAKE3](index.md) · Source and specification
+
+::: details Files in this project
+
+- [`main.aug`](main.md)
+- [`hashing.aug`](hashing.md)
+
+:::
+
+::::: example-compare
+
+:::: example-code
+
+## Code {#code}
+
+::: code-group
+
+```aug [Indentation]
+// aug-spec: "hashing.aug.md" explains this file. Read it before changes; refresh with aug spec.
+import HashError and hash from "https://github.com/GreenPandaStudios/aug-blake3#v0.1.3"
+/** Hash UTF-8 text with the real Rust BLAKE3 implementation. */
+hashText(string value) returns string unless HashError:
+    return hash(input=value.bytes())
+test hashText:
+    when "vectors":
+        it "matches_the_published_abc_vector":
+            assert(
+                hashText(value="abc") == "6437b3ac38465133ffb63b75273a8db548c558465d79db03fd359c6cd5bd9d85"
+            )
+```
+
+```aug [Braces]
+// aug-spec: "hashing.aug.md" explains this file. Read it before changes; refresh with aug spec.
+import HashError and hash from "https://github.com/GreenPandaStudios/aug-blake3#v0.1.3"
+/** Hash UTF-8 text with the real Rust BLAKE3 implementation. */
+hashText(string value) returns string unless HashError {
+    return hash(input=value.bytes())
+}
+test hashText {
+    when "vectors" {
+        it "matches_the_published_abc_vector" {
+            assert(
+                hashText(value="abc") == "6437b3ac38465133ffb63b75273a8db548c558465d79db03fd359c6cd5bd9d85"
+            )
+        }
+    }
+}
+```
+
+:::
+
+::::
+
+:::: example-spec
+
+## Compiled specification {#specification}
+
+### `hashText` · [source](hashing.md#code) {#symbol-hashText}
+
+Hash UTF-8 text with the real Rust BLAKE3 implementation. It takes `value` as a string. Failures can raise [`HashError`](dependencies/packages/%40greenpandastudios/aug-blake3/0.1.3/contracts.md#symbol-HashError). It returns [`hash`](dependencies/packages/%40greenpandastudios/aug-blake3/0.1.3/api.md#symbol-hash) with `input` from the UTF-8 bytes of `value`.
+
+### `test hashText` · [source](hashing.md#code) {#symbol-test-20-hashText}
+
+Tests [`hashText`](hashing.md#symbol-hashText). Each case gets fresh setup and dependencies.
+
+#### `vectors`
+
+##### `matches_the_published_abc_vector` · [source](hashing.md#code)
+
+The test requires [`hashText`](hashing.md#symbol-hashText) with `value` `"abc"` equals `"6437b3ac38465133ffb63b75273a8db548c558465d79db03fd359c6cd5bd9d85"`.
+
+### Dependencies
+
+It uses [`hash`](dependencies/packages/%40greenpandastudios/aug-blake3/0.1.3/api.md#symbol-hash) and [`HashError`](dependencies/packages/%40greenpandastudios/aug-blake3/0.1.3/contracts.md#symbol-HashError) from `https://github.com/GreenPandaStudios/aug-blake3#v0.1.3`.
+
+Built-in operations follow the [language reference](https://greenpandastudios.github.io/augscript/language-constructs).
+
+::::
+
+:::::

package/docs/examples/native-blake3/index.md

@@ -0,0 +1,38 @@
+---
+title: "Hashing with Rust BLAKE3"
+generated: true
+source: "examples/native-blake3"
+editLink: false
+prev: false
+next: false
+outline: [2, 3]
+---
+
+# Hashing with Rust BLAKE3
+
+Import a Rust implementation through an ordinary August package and verify a published BLAKE3 hash vector.
+
+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.
+
+This project requires the August `0.21.0` LLVM preview on macOS 14+ with Apple Silicon, or Debian/Ubuntu GNU/Linux x64 or ARM64 with glibc 2.36+. The library archives are public; the matching compiler release is still being qualified.
+
+## Project files
+
+- [`main.aug`](main.md)
+- [`hashing.aug`](hashing.md)
+
+
+## Try this project
+
+[Download this project](/downloads/native-blake3.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 native-blake3
+aug install .
+aug check .
+aug spec .
+aug test .
+aug run .
+```
+
+[Browse all examples](../index.md)

package/docs/examples/native-blake3/main.md

@@ -0,0 +1,73 @@
+---
+title: "main.aug · Hashing with Rust BLAKE3"
+generated: true
+source: "examples/native-blake3/main.aug"
+editLink: false
+prev: false
+next: false
+outline: [2, 3]
+pageClass: aug-example-page
+---
+
+# `main.aug`
+
+[Hashing with Rust BLAKE3](index.md) · Source and specification
+
+::: details Files in this project
+
+- [`main.aug`](main.md)
+- [`hashing.aug`](hashing.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 hashText from hashing
+import HashError from "https://github.com/GreenPandaStudios/aug-blake3#v0.1.3"
+try:
+    print(value=hashText(value="abc"))
+catch HashError error:
+    print(value=error.message)
+```
+
+```aug [Braces]
+// aug-spec: "main.aug.md" explains this file. Read it before changes; refresh with aug spec.
+import hashText from hashing
+import HashError from "https://github.com/GreenPandaStudios/aug-blake3#v0.1.3"
+try {
+    print(value=hashText(value="abc"))
+}
+catch HashError error {
+    print(value=error.message)
+}
+```
+
+:::
+
+::::
+
+:::: example-spec
+
+## Compiled specification {#specification}
+
+### Startup
+
+It prints [`hashText`](hashing.md#symbol-hashText) with `value` `"abc"`. If this work raises [`HashError`](dependencies/packages/%40greenpandastudios/aug-blake3/0.1.3/contracts.md#symbol-HashError) as `error`, it prints `error.message`.
+
+### Dependencies
+
+It uses [`HashError`](dependencies/packages/%40greenpandastudios/aug-blake3/0.1.3/contracts.md#symbol-HashError) (`message`) from `https://github.com/GreenPandaStudios/aug-blake3#v0.1.3`. It uses [`hashText`](hashing.md#symbol-hashText) from `hashing`.
+
+Built-in operations follow the [language reference](https://greenpandastudios.github.io/augscript/language-constructs).
+
+::::
+
+:::::