@greenpandastudios/aug-cli 0.19.0

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

@@ -0,0 +1,29 @@
+/** 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)

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

@@ -0,0 +1,141 @@
+<!-- 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.
+
+<a id="symbol-RangeError"></a>
+
+## `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.
+
+<a id="symbol-Positive"></a>
+
+## `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 id="symbol-Positive.around"></a>
+
+### `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`.
+
+<a id="symbol-double"></a>
+
+## `double`
+
+[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.
+
+<a id="symbol-test double"></a>
+
+## `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`
+
+[source](numbers.aug#L23)
+
+- 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`.
+
+## 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/examples/approved-design/main.aug

@@ -0,0 +1,26 @@
+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")

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

@@ -0,0 +1,108 @@
+<!-- Generated by aug spec. Edit the August source, then regenerate. -->
+
+# `main.aug` 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`](.aug-spec/august/0.19.0/io/contracts.aug.md#symbol-SystemConsole) when `Console` is requested. Reuse one instance.
+- Provide [`ApplicationImpl`](domain/app.aug.md#symbol-ApplicationImpl) when `Application` is requested. Reuse one instance. Required dependencies: `Console`.
+- Include the providers from [`Counters`](counters.aug.md#symbol-Counters) before execution.
+
+## Startup, in source order
+
+- Set `app` to the instance provided for `Application`.
+- Call [`Application.start`](domain/app.aug.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.aug.md#symbol-Fruit) with `code` = `code`; `name` = `label`, call [`Fruit`](domain/models.aug.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.aug.md#symbol-Counter.increment) on `counter`.
+  - Call `print` with `value` = call [`Counter.value`](counters.aug.md#symbol-Counter.value) on `counter`.
+- Try these operations:
+  - Call `print` with `value` = call [`double`](domain/numbers.aug.md#symbol-double) with `amount` = `7`.
+  - Call [`double`](domain/numbers.aug.md#symbol-double) with `amount` = `-1`.
+- If they fail with [`RangeError`](domain/numbers.aug.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`](.aug-spec/august/0.19.0/io/contracts.aug.md#symbol-SystemConsole)
+
+Class from `august.io`.
+
+Used as a type or provider.
+
+### [`Counter`](counters.aug.md#symbol-Counter)
+
+Interface from `counters`.
+
+- [`Counter.increment`](counters.aug.md#symbol-Counter.increment) (no caller inputs) → `void`; changes `self`.
+- [`Counter.value`](counters.aug.md#symbol-Counter.value) (no caller inputs) → `int`.
+
+### [`Counters`](counters.aug.md#symbol-Counters)
+
+Composition from `counters`.
+
+Used as a type or provider.
+
+### [`Application`](domain/app.aug.md#symbol-Application)
+
+Interface from `domain`.
+
+- [`Application.start`](domain/app.aug.md#symbol-Application.start) (no caller inputs) → `void`; uses [`Console.write`](.aug-spec/august/0.19.0/io/contracts.aug.md#symbol-Console.write).
+
+### [`ApplicationImpl`](domain/app.aug.md#symbol-ApplicationImpl)
+
+Class from `domain`.
+
+Used as a type or provider.
+
+### [`Fruit`](domain/models.aug.md#symbol-Fruit)
+
+Record from `domain`.
+
+- Construct with `code`: `int`, `name`: `string` → [`Fruit`](domain/models.aug.md#symbol-Fruit).
+
+### [`RangeError`](domain/numbers.aug.md#symbol-RangeError)
+
+Class from `domain`.
+
+Used as a type or provider.
+
+### [`double`](domain/numbers.aug.md#symbol-double)
+
+Function from `domain`.
+
+- [`double`](domain/numbers.aug.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/examples/approved-design/main.yaml

@@ -0,0 +1,8 @@
+block_style: indent
+indentation: tabs
+assignment: to
+lint:
+  - architecture
+module_dependencies:
+  - ".: domain"
+  - "domain:"

package/examples/benchmark/.aug-spec/manifest.json

@@ -0,0 +1,7 @@
+{
+  "format": 1,
+  "files": [
+    "main.aug.md"
+  ],
+  "digest": "4179cb6d189b3c491e75fa38ee2d1c982f6c3b8fc83309e923606b2a51e4ad45"
+}

package/examples/benchmark/main.aug

@@ -0,0 +1,17 @@
+// 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())

package/examples/benchmark/main.aug.md

@@ -0,0 +1,43 @@
+<!-- Generated by aug spec. Edit the August source, then regenerate. -->
+
+# `main.aug` 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.

package/examples/benchmark/main.yaml

@@ -0,0 +1 @@
+optimization: release

package/examples/cli-args/.aug-spec/manifest.json

@@ -0,0 +1,7 @@
+{
+  "format": 1,
+  "files": [
+    "main.aug.md"
+  ],
+  "digest": "436feb0daa7b3ed51ce239af6888c680ef6e692c6e5d6f00503a32bc5869d03d"
+}

package/examples/cli-args/main.aug

@@ -0,0 +1,15 @@
+try {
+    args = arguments()
+    print(value=args.length())
+    if args.length() > 0 {
+        print(value=args.get(index=0))
+    }
+    numbers = List<int>(1, 2)
+    borrow numbers {
+        numbers.append(value=3)
+    }
+    print(value=numbers.get(index=2))
+}
+catch IndexError error {
+    print(value="unexpected index failure")
+}

package/examples/cli-args/main.aug.md

@@ -0,0 +1,38 @@
+<!-- Generated by aug spec. Edit the August source, then regenerate. -->
+
+# `main.aug` specification
+
+August 0.19.0. This document is compiled from checked code with deterministic wording guided by Simplified Technical English.
+
+## In this file
+
+- Run startup operations with checked error recovery.
+
+## Startup, in source order
+
+- Try these operations:
+  - Set `args` to call `arguments`.
+  - Call `print` with `value` = call `length` on `args`.
+  - If call `length` on `args` is greater than `0`:
+    - Call `print` with `value` = call `get` on `args` with `index` = `0`.
+  - Set `numbers` to a list of `int` containing `1`, `2`.
+  - Grant exclusive mutable access to `numbers` for this block, then end the borrow:
+    - Call `append` on `numbers` with `value` = `3`.
+  - Call `print` with `value` = call `get` on `numbers` with `index` = `2`.
+- If they fail with `IndexError`, name the failure `error` and recover:
+  - Call `print` with `value` = `"unexpected index failure"`.
+
+## Built-in operations used by this file
+
+- `List<int>.append` (`value`: `int`) → `void`: Append an element with exclusive mutable access. Read-only and owned aliases cannot be stored here. Changes the receiver.
+- `List<int>.get` (`index`: `int`) → `int`: Read a zero-based position. An invalid index raises checked IndexError. Reference results grant reading. Can fail with `IndexError`.
+- `List<string>.get` (`index`: `int`) → `string`: Read a zero-based position. An invalid index raises checked IndexError. Reference results grant reading. Can fail with `IndexError`.
+- `List<string>.length` (no inputs) → `int`: Read the number of elements.
+- `arguments` (no inputs) → `List<string>`: Composition arguments. Other callables receive the Arguments capability.
+- `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/examples/collections/.aug-spec/manifest.json

@@ -0,0 +1,7 @@
+{
+  "format": 1,
+  "files": [
+    "main.aug.md"
+  ],
+  "digest": "8acdc38ecfcc6e5eb277e44abe6700f536bc46235bafbeb0a3c5e7dcdfd21624"
+}

package/examples/collections/main.aug

@@ -0,0 +1,18 @@
+try {
+    numbers = List<int>(2, 4)
+    borrow numbers {
+        numbers.append(value=6)
+    }
+    print(value=numbers.length())
+    print(value=numbers.get(index=1))
+    scores = Map<string, int>()
+    borrow scores {
+        scores.set(value=42, key="ada")
+    }
+    print(value=scores.contains(key="ada"))
+    print(value=scores.get(key="ada"))
+    print(value=scores.length())
+}
+catch IndexError error {
+    print(value="unexpected index failure")
+}

package/examples/collections/main.aug.md

@@ -0,0 +1,43 @@
+<!-- Generated by aug spec. Edit the August source, then regenerate. -->
+
+# `main.aug` specification
+
+August 0.19.0. This document is compiled from checked code with deterministic wording guided by Simplified Technical English.
+
+## In this file
+
+- Run startup operations with checked error recovery.
+
+## Startup, in source order
+
+- Try these operations:
+  - Set `numbers` to a list of `int` containing `2`, `4`.
+  - Grant exclusive mutable access to `numbers` for this block, then end the borrow:
+    - Call `append` on `numbers` with `value` = `6`.
+  - Call `print` with `value` = call `length` on `numbers`.
+  - Call `print` with `value` = call `get` on `numbers` with `index` = `1`.
+  - Set `scores` to an empty map from `string` to `int`.
+  - Grant exclusive mutable access to `scores` for this block, then end the borrow:
+    - Call `set` on `scores` with `value` = `42`; `key` = `"ada"`.
+  - Call `print` with `value` = call `contains` on `scores` with `key` = `"ada"`.
+  - Call `print` with `value` = call `get` on `scores` with `key` = `"ada"`.
+  - Call `print` with `value` = call `length` on `scores`.
+- If they fail with `IndexError`, name the failure `error` and recover:
+  - Call `print` with `value` = `"unexpected index failure"`.
+
+## Built-in operations used by this file
+
+- `List<int>.append` (`value`: `int`) → `void`: Append an element with exclusive mutable access. Read-only and owned aliases cannot be stored here. Changes the receiver.
+- `List<int>.get` (`index`: `int`) → `int`: Read a zero-based position. An invalid index raises checked IndexError. Reference results grant reading. Can fail with `IndexError`.
+- `List<int>.length` (no inputs) → `int`: Read the number of elements.
+- `Map<string, int>.contains` (`key`: `string`) → `bool`: Check for a key, including entries whose value is null.
+- `Map<string, int>.get` (`key`: `string`) → `optional int`: Read a value by key; an absent key returns null. contains distinguishes an absent key from a stored null.
+- `Map<string, int>.length` (no inputs) → `int`: Read the number of elements.
+- `Map<string, int>.set` (`key`: `string`, `value`: `int`) → `void`: Insert or replace an entry with exclusive mutable access. Changes the receiver.
+- `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/examples/developer-workflow/.aug-spec/august/0.19.0/io/contracts.aug

@@ -0,0 +1,36 @@
+// Generated by aug spec. This is a copy of the installed dependency source.
+/** Permission to write to a console, provided by an explicitly selected adapter. */
+capability Console:
+    /** Write one line of text. @param value Text to display. */
+    write<T>(T value) uses Console.write
+
+/** The native standard-output adapter. Construction performs no output. */
+SystemConsole() implements Console:
+    write<T>(T value):
+        print(value=value)
+
+/** Read UTF-8 text through an explicitly selected filesystem adapter. */
+capability FileReader:
+    /** Read text. @param path File path. @throws FileError The file could not be read. */
+    read(string path) returns string uses FileReader.read unless FileError
+
+/** Write UTF-8 text through an explicitly selected filesystem adapter. */
+capability FileWriter:
+    /** Write text. @param path File path. @param content Text. @throws FileError Writing failed. */
+    write(string path, string content) uses FileWriter.write unless FileError
+
+/** Native files. Operations are explicit; construction opens no files. */
+LocalFiles() implements FileReader, FileWriter:
+    read(string path) returns string unless FileError:
+        return read_file(path=path)
+    write(string path, string content) unless FileError:
+        write_file(path=path, content=content)
+
+/** Read command-line input through an explicit dependency. */
+capability Arguments:
+    read() returns List<string> uses Arguments.read
+
+/** Native command-line arguments. */
+ProcessArguments() implements Arguments:
+    read() returns List<string>:
+        return arguments()