@greenpandastudios/aug-cli 0.19.0 → 0.21.0

package/docs/example-projects.json

@@ -1,26 +1,240 @@
 [
-  {"path":"examples/hello","title":"Hello world with dependencies","group":"Start here","description":"A greeter, a logger, narrow folder exports, and explicit application bindings."},
-  {"path":"examples/new-syntax","title":"Labeled calls and injection","group":"Start here","description":"Constructor injection, named inputs, ordinary functions, and same-file tests."},
-  {"path":"examples/developer-workflow","title":"A small tested application","group":"Start here","description":"A calculator module with logging, fixtures, groups, and parameterized tests."},
-  {"path":"examples/cli-args","title":"Command-line arguments","group":"Start here","description":"Read arguments, inspect collections, and return a process exit status."},
-  {"path":"examples/collections","title":"Lists, tuples, sets, and maps","group":"Values and errors","description":"Create typed collections and update them through checked mutable access."},
-  {"path":"examples/generics","title":"Generic contracts","group":"Values and errors","description":"Write reusable records, interfaces, classes, and functions with type parameters."},
-  {"path":"examples/generic-di","title":"Generic dependency injection","group":"Values and errors","description":"Bind a generic interface and resolve a class that uses it."},
-  {"path":"examples/errors","title":"Checked failures","group":"Values and errors","description":"Declare errors with unless, catch them, and run cleanup."},
-  {"path":"examples/ownership","title":"Read access and mutable borrows","group":"State and lifetime","description":"Share a reference for reading and grant explicit access for mutation."},
-  {"path":"examples/ownership-transfer","title":"Move ownership","group":"State and lifetime","description":"Transfer an owned resource between labeled calls."},
-  {"path":"examples/drop","title":"Resource cleanup","group":"State and lifetime","description":"Release an owned resource when its lifetime ends."},
-  {"path":"examples/visibility","title":"Private state and helpers","group":"State and lifetime","description":"Keep underscore-prefixed implementation details inside their scope."},
-  {"path":"examples/approved-design","title":"Modules and composition","group":"Modules and packages","description":"Combine domain modules, generic values, explicit capabilities, and scoped providers."},
-  {"path":"examples/interceptors","title":"Function and constructor middleware","group":"Modules and packages","description":"Layer interceptors, map inputs, and keep logging dependencies explicit."},
-  {"path":"examples/packages/math","title":"Create a package","group":"Modules and packages","description":"Publish a small arithmetic library through export.aug and test its public surface."},
-  {"path":"examples/packages/app","title":"Use a package","group":"Modules and packages","description":"Install the neighboring arithmetic package and import it through a local alias."},
-  {"path":"examples/ffi","title":"A native C boundary","group":"Native applications","description":"Declare a C operation and call it inside an unsafe block."},
-  {"path":"examples/benchmark","title":"A finite benchmark","group":"Native applications","description":"Measure a deterministic arithmetic workload with aug bench."},
-  {"path":"examples/oidc-login","title":"OpenID Connect login application","group":"Web applications","description":"A login page, provider, client, session JWT, and logout flow in one August project."},
-  {"path":"benchmarks/startup","title":"Startup benchmark","group":"Measured programs","description":"The small program used to measure process startup."},
-  {"path":"benchmarks/cpu","title":"CPU benchmark","group":"Measured programs","description":"Two million dependent integer steps with a checked result."},
-  {"path":"benchmarks/collections","title":"Map and Set benchmark","group":"Measured programs","description":"Insert, find, and iterate over 20,000 collection entries."},
-  {"path":"benchmarks/json","title":"JSON benchmark","group":"Measured programs","description":"Parse, decode, and serialize a typed record 5,000 times."},
-  {"path":"benchmarks/http","title":"HTTP benchmark","group":"Measured programs","description":"Serve the typed JSON endpoint used in the throughput measurements."}
+  {
+    "path": "examples/native-pytorch",
+    "title": "CPU tensors with PyTorch",
+    "group": "Native libraries (LLVM preview)",
+    "description": "Import real LibTorch from its public August package, add CPU tensors, and verify the elements and sum. Owned tensors are released when their scope ends."
+  },
+  {
+    "path": "examples/native-sqlite",
+    "title": "A database with SQLite",
+    "group": "Native libraries (LLVM preview)",
+    "description": "Create an in-memory database, insert a labeled bound value, and query it through the real SQLite implementation. Mutation requires a borrow; scope exit closes the database."
+  },
+  {
+    "path": "examples/native-zlib",
+    "title": "Compression with zlib",
+    "group": "Native libraries (LLVM preview)",
+    "description": "Compress a buffer with zlib and verify the restored bytes. A fixed output limit bounds decompression."
+  },
+  {
+    "path": "examples/native-blake3",
+    "title": "Hashing with Rust BLAKE3",
+    "group": "Native libraries (LLVM preview)",
+    "description": "Import a Rust implementation through an ordinary August package and verify a published BLAKE3 hash vector."
+  },
+  {
+    "path": "examples/hello",
+    "title": "Hello world with dependencies",
+    "group": "Start here",
+    "description": "The application prints a greeting through an injected logger. Its entry point selects the providers, and each folder exposes a small public surface.",
+    "walkthrough": [
+      {
+        "file": "main.aug",
+        "explanation": "Startup binds the console, logger, and application, then resolves the greeter and calls it."
+      },
+      {
+        "file": "app/greeter.aug",
+        "explanation": "The greeter receives its logger in the header and delegates the greeting to it. The interface states the console effect."
+      },
+      {
+        "file": "logging/export.aug",
+        "explanation": "This is the logging folder's public surface. Callers can import the exported contract and provider."
+      },
+      {
+        "file": "logging/logger.aug",
+        "explanation": "The contract describes the log operation and its output capability; the console provider implements it."
+      }
+    ]
+  },
+  {
+    "path": "examples/weather-api",
+    "title": "Weather API",
+    "group": "Web applications",
+    "description": "Serve five simulated forecasts as typed JSON. The record, endpoint, and tests share a file; main.aug starts the listener and main.yaml enables OpenAPI.",
+    "walkthrough": [
+      {
+        "file": "main.aug",
+        "explanation": "Import the forecast endpoint and serve it on port 8787."
+      },
+      {
+        "file": "forecasts.aug",
+        "explanation": "Read the response record, five fixed forecasts, and cases that exercise the endpoint pipeline."
+      }
+    ]
+  },
+  {
+    "path": "examples/new-syntax",
+    "title": "Labeled calls and injection",
+    "group": "Start here",
+    "description": "Constructor injection, named inputs, ordinary functions, and same-file tests."
+  },
+  {
+    "path": "examples/developer-workflow",
+    "title": "A small tested application",
+    "group": "Start here",
+    "description": "A calculator logs each addition. Its nearby tests replace the logger and verify both labeled inputs and fresh setup.",
+    "walkthrough": [
+      {
+        "file": "main.aug",
+        "explanation": "Startup supplies providers, uses collections, invokes the calculator, and catches a simulated load failure."
+      },
+      {
+        "file": "calculator.aug",
+        "explanation": "Read the arithmetic contract, the injected logger, and the same-file cases together. The private silent adapter keeps tests independent of output."
+      },
+      {
+        "file": "logging/logger.aug",
+        "explanation": "This is the contract used by both the production logger and the test adapter."
+      }
+    ]
+  },
+  {
+    "path": "examples/cli-args",
+    "title": "Command-line arguments",
+    "group": "Start here",
+    "description": "Read arguments, inspect collections, and return a process exit status."
+  },
+  {
+    "path": "examples/collections",
+    "title": "Lists, tuples, sets, and maps",
+    "group": "Values and errors",
+    "description": "Create typed collections and update them through checked mutable access."
+  },
+  {
+    "path": "examples/generics",
+    "title": "Generic contracts",
+    "group": "Values and errors",
+    "description": "Write reusable records, interfaces, classes, and functions with type parameters."
+  },
+  {
+    "path": "examples/generic-di",
+    "title": "Generic dependency injection",
+    "group": "Values and errors",
+    "description": "Bind a generic interface and resolve a class that uses it."
+  },
+  {
+    "path": "examples/errors",
+    "title": "Checked failures",
+    "group": "Values and errors",
+    "description": "Declare errors with unless, catch them, and run cleanup."
+  },
+  {
+    "path": "examples/ownership",
+    "title": "Read access and mutable borrows",
+    "group": "State and lifetime",
+    "description": "Share a reference for reading and grant explicit access for mutation."
+  },
+  {
+    "path": "examples/ownership-transfer",
+    "title": "Move ownership",
+    "group": "State and lifetime",
+    "description": "Transfer an owned resource between labeled calls."
+  },
+  {
+    "path": "examples/drop",
+    "title": "Resource cleanup",
+    "group": "State and lifetime",
+    "description": "Release an owned resource when its lifetime ends."
+  },
+  {
+    "path": "examples/visibility",
+    "title": "Private state and helpers",
+    "group": "State and lifetime",
+    "description": "Keep underscore-prefixed implementation details inside their scope."
+  },
+  {
+    "path": "examples/approved-design",
+    "title": "Modules and composition",
+    "group": "Modules and packages",
+    "description": "Startup combines narrow domain exports with a scoped counter provider. Records and validation keep data and checked failures visible.",
+    "walkthrough": [
+      {
+        "file": "main.aug",
+        "explanation": "Follow the domain imports, provider choices, explicit scope, and checked failure before opening the implementation files."
+      },
+      {
+        "file": "domain/export.aug",
+        "explanation": "The export file gives callers the folder's deliberate public API."
+      },
+      {
+        "file": "domain/numbers.aug",
+        "explanation": "The validation interceptor rejects a negative input. Tests cover successful doubling and recovery from that failure."
+      }
+    ]
+  },
+  {
+    "path": "examples/interceptors",
+    "title": "Function and constructor middleware",
+    "group": "Modules and packages",
+    "description": "Layer interceptors, map inputs, and keep logging dependencies explicit."
+  },
+  {
+    "path": "examples/packages/math",
+    "title": "Create a package",
+    "group": "Modules and packages",
+    "description": "Publish a small arithmetic library through export.aug and test its public surface."
+  },
+  {
+    "path": "examples/packages/app",
+    "title": "Use a package",
+    "group": "Modules and packages",
+    "description": "Install the neighboring arithmetic package and import it through a local alias."
+  },
+  {
+    "path": "examples/ffi",
+    "title": "A native C boundary",
+    "group": "Native applications",
+    "description": "Declare a C operation and call it inside an unsafe block."
+  },
+  {
+    "path": "examples/benchmark",
+    "title": "A finite benchmark",
+    "group": "Native applications",
+    "description": "Measure a deterministic arithmetic workload with aug bench."
+  },
+  {
+    "path": "examples/oidc-login",
+    "title": "OpenID Connect login application",
+    "group": "Web applications",
+    "description": "One executable hosts a login page, an OpenID Connect provider and client, session JWTs, and logout. Accounts, keys, and sessions are held in memory for this development demonstration."
+  },
+  {
+    "path": "benchmarks/startup",
+    "title": "Startup benchmark",
+    "group": "Measured programs",
+    "description": "The small program used to measure process startup."
+  },
+  {"path":"benchmarks/float","title":"Floating-point benchmark","group":"Measured programs","description":"Accumulate exact binary fractions and check the final value."},
+  {"path":"benchmarks/calls","title":"Function-call benchmark","group":"Measured programs","description":"Call a labeled function repeatedly with a dependent integer result."},
+  {"path":"benchmarks/list","title":"List traversal benchmark","group":"Measured programs","description":"Grow a list and sum its snapshot values."},
+  {"path":"benchmarks/strings","title":"String processing benchmark","group":"Measured programs","description":"Split text into parts and sum their byte lengths."},
+  {"path":"benchmarks/map-churn","title":"Map deletion benchmark","group":"Measured programs","description":"Delete, replace and reinsert entries, then check values and insertion order."},
+  {"path":"benchmarks/errors","title":"Checked-error benchmark","group":"Measured programs","description":"Interleave successful calls and caught checked failures."},
+  {"path":"benchmarks/records","title":"Record allocation benchmark","group":"Measured programs","description":"Retain immutable records and sum their fields."},
+  {"path":"benchmarks/tasks","title":"Task scheduling benchmark","group":"Measured programs","description":"Start and join two tasks in each bounded scope."},
+  {
+    "path": "benchmarks/cpu",
+    "title": "CPU benchmark",
+    "group": "Measured programs",
+    "description": "Two million dependent integer steps with a checked result."
+  },
+  {
+    "path": "benchmarks/collections",
+    "title": "Map and Set benchmark",
+    "group": "Measured programs",
+    "description": "Insert, find, and iterate over 20,000 collection entries."
+  },
+  {
+    "path": "benchmarks/json",
+    "title": "JSON benchmark",
+    "group": "Measured programs",
+    "description": "Parse, decode, and serialize a typed record 5,000 times."
+  },
+  {
+    "path": "benchmarks/http",
+    "title": "HTTP benchmark",
+    "group": "Measured programs",
+    "description": "Serve the typed JSON endpoint used in the throughput measurements."
+  }
 ]

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

@@ -33,23 +33,24 @@ pageClass: aug-example-page
 ::: code-group
 
 ```aug [Indentation]
+// aug-spec: "counters.aug.md" explains this file. Read it before changes; refresh with aug spec.
 /** Reading state has no mutation effect. */
 interface State:
     read() returns int
 _Initial() implements State:
-    read() returns int:
+    read():
         return 0
 _Updated(int count) implements State:
-    read() returns int:
+    read():
         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:
+    increment():
         _state to _Updated(count=_state.read() + 1)
-    value() returns int:
+    value():
         return _state.read()
 /** The complete counter composition; its mutable state belongs to each scope. */
 composition Counters:
@@ -58,17 +59,18 @@ composition Counters:
 ```
 
 ```aug [Braces]
+// aug-spec: "counters.aug.md" explains this file. Read it before changes; refresh with aug spec.
 /** Reading state has no mutation effect. */
 interface State {
     read() returns int
 }
 _Initial() implements State {
-    read() returns int {
+    read() {
         return 0
     }
 }
 _Updated(int count) implements State {
-    read() returns int {
+    read() {
         return count
     }
 }
@@ -78,10 +80,10 @@ interface Counter {
     value() returns int
 }
 _Counter(resolve mutable State initial to _state) implements Counter {
-    increment() changes self {
+    increment() {
         _state to _Updated(count=_state.read() + 1)
     }
-    value() returns int {
+    value() {
         return _state.read()
     }
 }
@@ -100,153 +102,59 @@ composition Counters {
 
 ## Compiled specification {#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.md#symbol-State) is an interface.
-- [`_Initial`](counters.md#symbol-_Initial) is a class implementing `State`.
-- [`_Updated`](counters.md#symbol-_Updated) is a class implementing `State`.
-- [`Counter`](counters.md#symbol-Counter) is an interface.
-- [`_Counter`](counters.md#symbol-_Counter) is a class implementing `Counter`.
-- [`Counters`](counters.md#symbol-Counters) declares 2 providers.
-
-### `State` {#symbol-State}
-
-[source](counters.md#code)
-
-Interface.
-
-**Author documentation**
+### `State` · interface · [source](counters.md#code) {#symbol-State}
 
 Reading state has no mutation effect.
 
-#### `State.read` {#symbol-State.read}
-
-[source](counters.md#code)
-
-Returns: `int`.
-
-Interface contract. A selected implementation supplies the behavior.
-
-### `Counter` {#symbol-Counter}
-
-[source](counters.md#code)
+#### `State.read` · [source](counters.md#code) {#symbol-State.read}
 
-Interface.
+It returns `int`.
 
-**Author documentation**
+### `Counter` · interface · [source](counters.md#code) {#symbol-Counter}
 
 A mutable counter with an explicit transition contract.
 
-#### `Counter.increment` {#symbol-Counter.increment}
+#### `Counter.increment` · [source](counters.md#code) {#symbol-Counter.increment}
 
-[source](counters.md#code)
+It may change `self`.
 
-Returns: no value.
+#### `Counter.value` · [source](counters.md#code) {#symbol-Counter.value}
 
-May change: `self`.
+It returns `int`.
 
-Interface contract. A selected implementation supplies the behavior.
-
-#### `Counter.value` {#symbol-Counter.value}
-
-[source](counters.md#code)
-
-Returns: `int`.
-
-Interface contract. A selected implementation supplies the behavior.
-
-### `Counters` {#symbol-Counters}
-
-[source](counters.md#code)
-
-**Author documentation**
+### `Counters` · [source](counters.md#code) {#symbol-Counters}
 
 The complete counter composition; its mutable state belongs to each scope.
 
-This composition declares these providers before startup:
-
-- Provide [`_Initial`](counters.md#symbol-_Initial) when `State` is requested. Reuse one instance.
-- Provide [`_Counter`](counters.md#symbol-_Counter) when `Counter` is requested. Reuse one instance per explicit scope. Permit explicit shared mutation. Required dependencies: `State`.
-
-### `_Initial` {#symbol-_Initial}
-
-[source](counters.md#code)
-
-Behavioral class, private to this file.
-
-Satisfies [`State`](counters.md#symbol-State).
-
-#### `_Initial.read` {#symbol-_Initial.read}
-
-[source](counters.md#code)
-
-Returns: `int`.
-
-**What it does**
-
-- Return `0`.
-
-### `_Updated` {#symbol-_Updated}
-
-[source](counters.md#code)
-
-Behavioral class, private to this file.
-
-Satisfies [`State`](counters.md#symbol-State).
-
-**Inputs**
-
-- `count` (`int`) — required labeled input — stored as `count` and read-only after initialization.
-
-#### `_Updated.read` {#symbol-_Updated.read}
-
-[source](counters.md#code)
-
-Returns: `int`.
-
-**What it does**
-
-- Return `count`.
-
-### `_Counter` {#symbol-_Counter}
-
-[source](counters.md#code)
-
-Behavioral class, private to this file.
-
-Satisfies [`Counter`](counters.md#symbol-Counter).
-
-**Inputs**
+These providers are registered before startup. `State` is provided by [`_Initial`](counters.md#symbol-_Initial). The same instance is shared. `Counter` is provided by [`_Counter`](counters.md#symbol-_Counter). Each scope shares one instance. Shared mutation is allowed. It requires bindings for `State`.
 
-- `initial` ([`State`](counters.md#symbol-State)) — injected; callers omit it — stored as `_state` (private) and mutable.
+### `_Initial` · class · [source](counters.md#code) {#symbol-_Initial}
 
-#### `_Counter.increment` {#symbol-_Counter.increment}
+It implements [`State`](counters.md#symbol-State). It is private to this file.
 
-[source](counters.md#code)
+#### `_Initial.read` · [source](counters.md#code) {#symbol-_Initial.read}
 
-Returns: no value.
+It returns `0`.
 
-May change: `self`.
+### `_Updated` · class · [source](counters.md#code) {#symbol-_Updated}
 
-**What it does**
+It implements [`State`](counters.md#symbol-State). It is private to this file. It takes `count` as an integer, kept read-only.
 
-- Set `_state` to call [`_Updated`](counters.md#symbol-_Updated) with `count` = (call [`State.read`](counters.md#symbol-State.read) on `_state` plus `1`).
+#### `_Updated.read` · [source](counters.md#code) {#symbol-_Updated.read}
 
-#### `_Counter.value` {#symbol-_Counter.value}
+It returns `count`.
 
-[source](counters.md#code)
+### `_Counter` · class · [source](counters.md#code) {#symbol-_Counter}
 
-Returns: `int`.
+It implements [`Counter`](counters.md#symbol-Counter). It is private to this file. The `_state` dependency is injected as [`State`](counters.md#symbol-State) and stored mutably and privately.
 
-**What it does**
+#### `_Counter.increment` · [source](counters.md#code) {#symbol-_Counter.increment}
 
-- Return call [`State.read`](counters.md#symbol-State.read) on `_state`.
+It may change `self`. It sets `_state` to a [`_Updated`](counters.md#symbol-_Updated) with `count` from [`_state.read`](counters.md#symbol-State.read) plus `1`.
 
-### Shared language rules
+#### `_Counter.value` · [source](counters.md#code) {#symbol-_Counter.value}
 
-See the [language reference](https://greenpandastudios.github.io/augscript/reference) for numeric, equality, ownership, and task rules.
+It returns [`_state.read`](counters.md#symbol-State.read).
 
 ::::