@greenpandastudios/aug-cli 0.19.0

package/examples/approved-design/.aug-spec/august/0.19.0/io/contracts.aug.md

@@ -0,0 +1,316 @@
+<!-- Generated by aug spec. Edit the August source, then regenerate. -->
+
+# `contracts.aug` specification
+
+August 0.19.0. This document is compiled from checked code with deterministic wording guided by Simplified Technical English.
+
+## In this file
+
+- [`Console`](contracts.aug.md#symbol-Console) is a capability interface.
+- [`SystemConsole`](contracts.aug.md#symbol-SystemConsole) is a class implementing `Console`.
+- [`FileReader`](contracts.aug.md#symbol-FileReader) is a capability interface.
+- [`FileWriter`](contracts.aug.md#symbol-FileWriter) is a capability interface.
+- [`LocalFiles`](contracts.aug.md#symbol-LocalFiles) is a class implementing `FileReader`, `FileWriter`.
+- [`Arguments`](contracts.aug.md#symbol-Arguments) is a capability interface.
+- [`ProcessArguments`](contracts.aug.md#symbol-ProcessArguments) is a class implementing `Arguments`.
+
+<a id="symbol-Console"></a>
+
+## `Console`
+
+[source](contracts.aug#L3)
+
+Capability interface.
+
+**Author documentation**
+
+Permission to write to a console, provided by an explicitly selected adapter.
+
+<a id="symbol-Console.write"></a>
+
+### `Console.write`
+
+[source](contracts.aug#L5)
+
+Type parameters: `T`.
+
+**Inputs**
+
+- `value` (`T`) — required labeled input.
+
+Returns: no value.
+
+Capabilities: [`Console.write`](contracts.aug.md#symbol-Console.write).
+
+Interface contract. A selected implementation supplies the behavior.
+
+**Author documentation**
+
+Write one line of text.
+
+**Parameters**
+- `value`: Text to display.
+
+<a id="symbol-SystemConsole"></a>
+
+## `SystemConsole`
+
+[source](contracts.aug#L8)
+
+Behavioral class.
+
+Satisfies [`Console`](contracts.aug.md#symbol-Console).
+
+**Author documentation**
+
+The native standard-output adapter. Construction performs no output.
+
+<a id="symbol-SystemConsole.write"></a>
+
+### `SystemConsole.write`
+
+[source](contracts.aug#L9)
+
+Type parameters: `T`.
+
+**Inputs**
+
+- `value` (`T`) — required labeled input.
+
+Returns: no value.
+
+Capabilities: [`Console.write`](contracts.aug.md#symbol-Console.write).
+
+**What it does**
+
+- Call `print` with `value` = `value`.
+
+**Author documentation**
+
+Write one line of text.
+
+**Parameters**
+- `value`: Text to display.
+
+<a id="symbol-FileReader"></a>
+
+## `FileReader`
+
+[source](contracts.aug#L13)
+
+Capability interface.
+
+**Author documentation**
+
+Read UTF-8 text through an explicitly selected filesystem adapter.
+
+<a id="symbol-FileReader.read"></a>
+
+### `FileReader.read`
+
+[source](contracts.aug#L15)
+
+**Inputs**
+
+- `path` (`string`) — required labeled input.
+
+Returns: `string`.
+
+Capabilities: [`FileReader.read`](contracts.aug.md#symbol-FileReader.read).
+
+Can fail with `FileError`. Callers must catch or propagate these errors.
+
+Interface contract. A selected implementation supplies the behavior.
+
+**Author documentation**
+
+Read text.
+
+**Parameters**
+- `path`: File path.
+
+**Throws**
+- `FileError`: The file could not be read.
+
+<a id="symbol-FileWriter"></a>
+
+## `FileWriter`
+
+[source](contracts.aug#L18)
+
+Capability interface.
+
+**Author documentation**
+
+Write UTF-8 text through an explicitly selected filesystem adapter.
+
+<a id="symbol-FileWriter.write"></a>
+
+### `FileWriter.write`
+
+[source](contracts.aug#L20)
+
+**Inputs**
+
+- `path` (`string`) — required labeled input.
+- `content` (`string`) — required labeled input.
+
+Returns: no value.
+
+Capabilities: [`FileWriter.write`](contracts.aug.md#symbol-FileWriter.write).
+
+Can fail with `FileError`. Callers must catch or propagate these errors.
+
+Interface contract. A selected implementation supplies the behavior.
+
+**Author documentation**
+
+Write text.
+
+**Parameters**
+- `path`: File path.
+- `content`: Text.
+
+**Throws**
+- `FileError`: Writing failed.
+
+<a id="symbol-LocalFiles"></a>
+
+## `LocalFiles`
+
+[source](contracts.aug#L23)
+
+Behavioral class.
+
+Satisfies [`FileReader`](contracts.aug.md#symbol-FileReader), [`FileWriter`](contracts.aug.md#symbol-FileWriter).
+
+**Author documentation**
+
+Native files. Operations are explicit; construction opens no files.
+
+<a id="symbol-LocalFiles.read"></a>
+
+### `LocalFiles.read`
+
+[source](contracts.aug#L24)
+
+**Inputs**
+
+- `path` (`string`) — required labeled input.
+
+Returns: `string`.
+
+Capabilities: [`FileReader.read`](contracts.aug.md#symbol-FileReader.read).
+
+Can fail with `FileError`. Callers must catch or propagate these errors.
+
+**What it does**
+
+- Return call `read_file` with `path` = `path`.
+
+**Author documentation**
+
+Read text.
+
+**Parameters**
+- `path`: File path.
+
+**Throws**
+- `FileError`: The file could not be read.
+
+<a id="symbol-LocalFiles.write"></a>
+
+### `LocalFiles.write`
+
+[source](contracts.aug#L26)
+
+**Inputs**
+
+- `path` (`string`) — required labeled input.
+- `content` (`string`) — required labeled input.
+
+Returns: no value.
+
+Capabilities: [`FileWriter.write`](contracts.aug.md#symbol-FileWriter.write).
+
+Can fail with `FileError`. Callers must catch or propagate these errors.
+
+**What it does**
+
+- Call `write_file` with `path` = `path`; `content` = `content`.
+
+**Author documentation**
+
+Write text.
+
+**Parameters**
+- `path`: File path.
+- `content`: Text.
+
+**Throws**
+- `FileError`: Writing failed.
+
+<a id="symbol-Arguments"></a>
+
+## `Arguments`
+
+[source](contracts.aug#L30)
+
+Capability interface.
+
+**Author documentation**
+
+Read command-line input through an explicit dependency.
+
+<a id="symbol-Arguments.read"></a>
+
+### `Arguments.read`
+
+[source](contracts.aug#L31)
+
+Returns: `List<string>`.
+
+Capabilities: [`Arguments.read`](contracts.aug.md#symbol-Arguments.read).
+
+Interface contract. A selected implementation supplies the behavior.
+
+<a id="symbol-ProcessArguments"></a>
+
+## `ProcessArguments`
+
+[source](contracts.aug#L34)
+
+Behavioral class.
+
+Satisfies [`Arguments`](contracts.aug.md#symbol-Arguments).
+
+**Author documentation**
+
+Native command-line arguments.
+
+<a id="symbol-ProcessArguments.read"></a>
+
+### `ProcessArguments.read`
+
+[source](contracts.aug#L35)
+
+Returns: `List<string>`.
+
+Capabilities: [`Arguments.read`](contracts.aug.md#symbol-Arguments.read).
+
+**What it does**
+
+- Return call `arguments`.
+
+## Built-in operations used by this file
+
+- `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.
+- `read_file` (`path`: `string`) → `string`: Root-only UTF-8 text input. Other callables receive FileReader. Invalid Unicode and NUL raise FileError. Can fail with `FileError`.
+- `write_file` (`path`: `string`, `content`: `string`) → `void`: Root-only UTF-8 text output. Other callables receive FileWriter. Can fail with `FileError`.
+
+[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/.aug-spec/manifest.json

@@ -0,0 +1,14 @@
+{
+  "format": 1,
+  "files": [
+    ".aug-spec/august/0.19.0/io/contracts.aug",
+    ".aug-spec/august/0.19.0/io/contracts.aug.md",
+    "counters.aug.md",
+    "domain/app.aug.md",
+    "domain/export.aug.md",
+    "domain/models.aug.md",
+    "domain/numbers.aug.md",
+    "main.aug.md"
+  ],
+  "digest": "17b8a92022fe0e3becdd73b3eb31493a9cebe7ddeb63b1e76596c612ed728d88"
+}

package/examples/approved-design/counters.aug

@@ -0,0 +1,22 @@
+/** Reading state has no mutation effect. */
+interface State:
+	read() returns int
+_Initial() implements State:
+	read() returns int:
+		return 0
+_Updated(int count) implements State:
+	read() returns int:
+		return count
+/** A mutable counter with an explicit transition contract. */
+interface Counter:
+	increment() changes self
+	value() returns int
+_Counter(resolve mutable State initial to _state) implements Counter:
+	increment() changes self:
+		_state to _Updated(count=_state.read() + 1)
+	value() returns int:
+		return _state.read()
+/** The complete counter composition; its mutable state belongs to each scope. */
+composition Counters:
+	implement State with _Initial
+	implement Counter with _Counter scoped mutable

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

@@ -0,0 +1,177 @@
+<!-- Generated by aug spec. Edit the August source, then regenerate. -->
+
+# `counters.aug` specification
+
+August 0.19.0. This document is compiled from checked code with deterministic wording guided by Simplified Technical English.
+
+## In this file
+
+- [`State`](counters.aug.md#symbol-State) is an interface.
+- [`_Initial`](counters.aug.md#symbol-_Initial) is a class implementing `State`.
+- [`_Updated`](counters.aug.md#symbol-_Updated) is a class implementing `State`.
+- [`Counter`](counters.aug.md#symbol-Counter) is an interface.
+- [`_Counter`](counters.aug.md#symbol-_Counter) is a class implementing `Counter`.
+- [`Counters`](counters.aug.md#symbol-Counters) declares 2 providers.
+
+<a id="symbol-State"></a>
+
+## `State`
+
+[source](counters.aug#L2)
+
+Interface.
+
+**Author documentation**
+
+Reading state has no mutation effect.
+
+<a id="symbol-State.read"></a>
+
+### `State.read`
+
+[source](counters.aug#L3)
+
+Returns: `int`.
+
+Interface contract. A selected implementation supplies the behavior.
+
+<a id="symbol-Counter"></a>
+
+## `Counter`
+
+[source](counters.aug#L11)
+
+Interface.
+
+**Author documentation**
+
+A mutable counter with an explicit transition contract.
+
+<a id="symbol-Counter.increment"></a>
+
+### `Counter.increment`
+
+[source](counters.aug#L12)
+
+Returns: no value.
+
+May change: `self`.
+
+Interface contract. A selected implementation supplies the behavior.
+
+<a id="symbol-Counter.value"></a>
+
+### `Counter.value`
+
+[source](counters.aug#L13)
+
+Returns: `int`.
+
+Interface contract. A selected implementation supplies the behavior.
+
+<a id="symbol-Counters"></a>
+
+## `Counters`
+
+[source](counters.aug#L20)
+
+**Author documentation**
+
+The complete counter composition; its mutable state belongs to each scope.
+
+This composition declares these providers before startup:
+
+- Provide [`_Initial`](counters.aug.md#symbol-_Initial) when `State` is requested. Reuse one instance.
+- Provide [`_Counter`](counters.aug.md#symbol-_Counter) when `Counter` is requested. Reuse one instance per explicit scope. Permit explicit shared mutation. Required dependencies: `State`.
+
+<a id="symbol-_Initial"></a>
+
+## `_Initial`
+
+[source](counters.aug#L4)
+
+Behavioral class, private to this file.
+
+Satisfies [`State`](counters.aug.md#symbol-State).
+
+<a id="symbol-_Initial.read"></a>
+
+### `_Initial.read`
+
+[source](counters.aug#L5)
+
+Returns: `int`.
+
+**What it does**
+
+- Return `0`.
+
+<a id="symbol-_Updated"></a>
+
+## `_Updated`
+
+[source](counters.aug#L7)
+
+Behavioral class, private to this file.
+
+Satisfies [`State`](counters.aug.md#symbol-State).
+
+**Inputs**
+
+- `count` (`int`) — required labeled input — stored as `count` and read-only after initialization.
+
+<a id="symbol-_Updated.read"></a>
+
+### `_Updated.read`
+
+[source](counters.aug#L8)
+
+Returns: `int`.
+
+**What it does**
+
+- Return `count`.
+
+<a id="symbol-_Counter"></a>
+
+## `_Counter`
+
+[source](counters.aug#L14)
+
+Behavioral class, private to this file.
+
+Satisfies [`Counter`](counters.aug.md#symbol-Counter).
+
+**Inputs**
+
+- `initial` ([`State`](counters.aug.md#symbol-State)) — injected; callers omit it — stored as `_state` (private) and mutable.
+
+<a id="symbol-_Counter.increment"></a>
+
+### `_Counter.increment`
+
+[source](counters.aug#L15)
+
+Returns: no value.
+
+May change: `self`.
+
+**What it does**
+
+- Set `_state` to call [`_Updated`](counters.aug.md#symbol-_Updated) with `count` = (call [`State.read`](counters.aug.md#symbol-State.read) on `_state` plus `1`).
+
+<a id="symbol-_Counter.value"></a>
+
+### `_Counter.value`
+
+[source](counters.aug#L17)
+
+Returns: `int`.
+
+**What it does**
+
+- Return call [`State.read`](counters.aug.md#symbol-State.read) on `_state`.
+
+## Shared language rules
+
+See the [language reference](https://greenpandastudios.github.io/augscript/reference) for numeric, equality, ownership, and task rules.

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

@@ -0,0 +1,12 @@
+import Console from august.io
+import Fruit from models
+/** The application's explicit startup operation. */
+interface Application:
+	/** Writes the fruit names through the selected console. */
+	start() uses Console.write
+/** Construction stores dependencies; start performs the visible external work. */
+ApplicationImpl(resolve Console console) implements Application:
+	start() uses console.write:
+		fruit to [Fruit(code=1, name="apple"), Fruit(name="pear", code=2)]
+		for item in fruit:
+			console.write(value=item.name)

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

@@ -0,0 +1,97 @@
+<!-- Generated by aug spec. Edit the August source, then regenerate. -->
+
+# `app.aug` specification
+
+August 0.19.0. This document is compiled from checked code with deterministic wording guided by Simplified Technical English.
+
+## In this file
+
+- [`Application`](app.aug.md#symbol-Application) is an interface.
+- [`ApplicationImpl`](app.aug.md#symbol-ApplicationImpl) is a class implementing `Application`.
+
+<a id="symbol-Application"></a>
+
+## `Application`
+
+[source](app.aug#L4)
+
+Interface.
+
+**Author documentation**
+
+The application's explicit startup operation.
+
+<a id="symbol-Application.start"></a>
+
+### `Application.start`
+
+[source](app.aug#L6)
+
+Returns: no value.
+
+Capabilities: [`Console.write`](../.aug-spec/august/0.19.0/io/contracts.aug.md#symbol-Console.write).
+
+Interface contract. A selected implementation supplies the behavior.
+
+**Author documentation**
+
+Writes the fruit names through the selected console.
+
+<a id="symbol-ApplicationImpl"></a>
+
+## `ApplicationImpl`
+
+[source](app.aug#L8)
+
+Behavioral class.
+
+Satisfies [`Application`](app.aug.md#symbol-Application).
+
+**Author documentation**
+
+Construction stores dependencies; start performs the visible external work.
+
+**Inputs**
+
+- `console` ([`Console`](../.aug-spec/august/0.19.0/io/contracts.aug.md#symbol-Console)) — injected; callers omit it — stored as `console` and read-only after initialization.
+
+<a id="symbol-ApplicationImpl.start"></a>
+
+### `ApplicationImpl.start`
+
+[source](app.aug#L9)
+
+Returns: no value.
+
+Capabilities: [`console.write`](../.aug-spec/august/0.19.0/io/contracts.aug.md#symbol-Console.write).
+
+**What it does**
+
+- Set `fruit` to a list containing call [`Fruit`](models.aug.md#symbol-Fruit) with `code` = `1`; `name` = `"apple"`, call [`Fruit`](models.aug.md#symbol-Fruit) with `name` = `"pear"`; `code` = `2`.
+- For each `item` in a snapshot of `fruit`, in iteration order:
+  - Call [`Console.write`](../.aug-spec/august/0.19.0/io/contracts.aug.md#symbol-Console.write) on `console` with `value` = `name` of `item`.
+
+**Author documentation**
+
+Writes the fruit names through the selected console.
+
+## Dependencies used by this file
+
+Only referenced types and operations appear here. Each name links to its complete specification.
+
+### [`Console`](../.aug-spec/august/0.19.0/io/contracts.aug.md#symbol-Console)
+
+Capability interface from `august.io`.
+
+- [`Console.write`](../.aug-spec/august/0.19.0/io/contracts.aug.md#symbol-Console.write)<`T`> (`value`: `T`) → `void`.
+
+### [`Fruit`](models.aug.md#symbol-Fruit)
+
+Record from `models`.
+
+- Construct with `code`: `int`, `name`: `string` → [`Fruit`](models.aug.md#symbol-Fruit).
+- Read `name` (`string`).
+
+## Shared language rules
+
+See the [language reference](https://greenpandastudios.github.io/augscript/reference) for numeric, equality, ownership, and task rules.

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

@@ -0,0 +1,5 @@
+export Application from app
+export ApplicationImpl from app
+export Fruit from models
+export double from numbers
+export RangeError from numbers

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

@@ -0,0 +1,25 @@
+<!-- Generated by aug spec. Edit the August source, then regenerate. -->
+
+# `export.aug` specification
+
+August 0.19.0. This document is compiled from checked code with deterministic wording guided by Simplified Technical English.
+
+## In this file
+
+- Export `Application` from this folder.
+- Export `ApplicationImpl` from this folder.
+- Export `Fruit` from this folder.
+- Export `double` from this folder.
+- Export `RangeError` from this folder.
+
+## Folder exports
+
+- Export the declaration `Application` from [`app.aug`](app.aug.md#symbol-Application).
+- Export the declaration `ApplicationImpl` from [`app.aug`](app.aug.md#symbol-ApplicationImpl).
+- Export the declaration `Fruit` from [`models.aug`](models.aug.md#symbol-Fruit).
+- Export the declaration `double` from [`numbers.aug`](numbers.aug.md#symbol-double).
+- Export the declaration `RangeError` from [`numbers.aug`](numbers.aug.md#symbol-RangeError).
+
+## Shared language rules
+
+See the [language reference](https://greenpandastudios.github.io/augscript/reference) for numeric, equality, ownership, and task rules.

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

@@ -0,0 +1,2 @@
+/** Immutable fruit data, with public construction labels and structural equality. */
+record Fruit(int code, string name)

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

@@ -0,0 +1,30 @@
+<!-- Generated by aug spec. Edit the August source, then regenerate. -->
+
+# `models.aug` specification
+
+August 0.19.0. This document is compiled from checked code with deterministic wording guided by Simplified Technical English.
+
+## In this file
+
+- [`Fruit`](models.aug.md#symbol-Fruit) is an immutable record.
+
+<a id="symbol-Fruit"></a>
+
+## `Fruit`
+
+[source](models.aug#L2)
+
+Immutable record.
+
+**Author documentation**
+
+Immutable fruit data, with public construction labels and structural equality.
+
+**Inputs**
+
+- `code` (`int`) — required labeled input — stored as `code` and read-only after initialization.
+- `name` (`string`) — required labeled input — stored as `name` 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.