@greenpandastudios/aug-cli 0.19.0 → 0.21.0

package/docs/grammar.md

@@ -1,6 +1,6 @@
 # Grammar and line boundaries
 
-This is the compact accepted grammar for 0.19. `Name` is an identifier, and bracketed grammar groups below are optional. These text blocks describe syntax rather than executable snippets.
+This is the compact accepted grammar for 0.21. `Name` is an identifier, and bracketed grammar groups below are optional. These text blocks describe syntax rather than executable snippets.
 
 ## Blocks and declarations
 
@@ -13,7 +13,7 @@ Function    := [Tags] ["fixture"] Name [Generics] "(" Parameters ")"
                ["uses" Paths] ["unless" Types] (Block | End)
 
 Class       := [Tags] Name [Generics] ["(" Fields ")"]
-               "implements" Type {"," Type} ClassBlock
+               ["unless" Types] "implements" Type {"," Type} ClassBlock
 ClassBlock  := BlockOfFieldsAndMethodsWithOptionalInitialize
 Initialize  := "initialize" Block
 
@@ -26,12 +26,12 @@ Interface   := ("interface" | "capability") Name [Generics]
 Interceptor := "interceptor" Name [Generics] ["(" ResolveFields ")"] Block
 Composition := "composition" Name BlockOfBindings
 Endpoint    := [Tags] "endpoint" HttpMethod String "as" Name "(" Parameters ")"
-               ("returns" Type | "streams" Type) ["uses" Paths]
+               ["returns" Type | "streams" Type] ["uses" Paths]
                ["unless" Type ["with status" Integer] {"and" Type ["with status" Integer]}]
                ["with status" Integer] Block
 ```
 
-An interface/class/interceptor block contains method declarations. A record ends after its header or validation block and has no behavior body. A function's absent returns clause means void. Its body is required for calls, except extern C. There is no class or function prefix.
+An interface/class/interceptor block contains method declarations. A record ends after its header or validation block and has no behavior body. An executable body infers an absent returns clause; no returned value means void. A bodyless signature defaults to void. Omitted changes, uses, and unless clauses are inferred from executable bodies; explicit clauses remain checked bounds. Its body is required for calls, except extern C. There is no class or function prefix.
 
 The implements clause identifies a class. Its initialize block appears inside the class before methods, and runs after field initialization. Records can contain one initialize block for validation. Nested function declarations are not supported. A root `counter()` statement is a call, not a declaration.
 
@@ -53,7 +53,7 @@ Variance is accepted only on interfaces; mutable storage applies to class header
 ## Imports, bindings, and calls
 
 ```text
-Import      := "import" (Name {"and" Name} | "everything") "from" DottedPath End
+Import      := "import" (Name {"and" Name} | "everything") "from" (DottedPath | RepositoryUrl {"." Name}) End
 Export      := "export" Name "from" SiblingName End
              | "export" "folder" ChildName End
 Binding     := "implement" Key ["<" Types ">"] "with" Type
@@ -64,6 +64,8 @@ Assignment  := [["own" | "borrow"] Type] Target ("=" | "to") Expression End
 Resolve     := "resolve" Key ["<" Types ">"] "to" Name End
 ```
 
+A quoted public repository URL declares a source dependency. A URL can select a tag or commit with #REVISION. See [packages](packages.md) for aliases and commit locks.
+
 The formatter uses implement/with and resolve/to, and preserves wildcard imports. Assignment style remains a project preference. Repeated paths/errors can use and or comma; canonical error clauses use and. Collection constructor elements are positional because their order carries meaning. Assert also accepts its single bool positionally.
 
 ## Control flow and tests

package/docs/guides/change-a-module.md

@@ -0,0 +1,64 @@
+# Change an unfamiliar module
+
+A change request is easier to review when you can trace its inputs, dependencies, and observable behavior. This guide follows the repository's tested calculator application. It uses the same process for a human developer and a coding agent; the checks establish specific program properties, while you still review whether the change meets the request.
+
+## Establish a working baseline
+
+Download [the tested calculator project](../examples/developer-workflow/index.md#try-this-project), extract it, and prepare [the native dependencies](../packages.md#npm-registry). From the folder containing the extracted project:
+
+```sh
+cd developer-workflow
+npx @greenpandastudios/aug-cli@next check .
+npx @greenpandastudios/aug-cli@next test .
+npx @greenpandastudios/aug-cli@next spec .
+```
+
+Open [the application's entry point](../examples/developer-workflow/main.md). It selects the console and logger, constructs the calculator, and calls its addition operation. Then open [the calculator and its compiled spec](../examples/developer-workflow/calculator.md). Its interface describes addition and console output. The class receives a logger. The tests supply a private silent logger and check the returned sums.
+
+The private test adapter implements the public logging contract. It keeps these cases independent of console messages. Test setup chooses its own providers; application startup does not run during a case.
+
+## Trace only what the change needs
+
+Suppose the request is: **also verify addition with a negative operand**. Read the `Arithmetic.add` contract, `Calculator.add`, and the `addition` test group. Follow [the logging contract](../examples/developer-workflow/logging/logger.md) if you need to understand its effect. The dependency section of the compiled spec links to the used surfaces; it does not repeat every dependency implementation.
+
+For a bounded context report:
+
+```sh
+npx @greenpandastudios/aug-cli@next explain . --file calculator.aug --name Calculator
+npx @greenpandastudios/aug-cli@next context . --file calculator.aug --name Calculator --budget 6000
+```
+
+The report gives checked contracts and related context. It helps you choose which files to read; it does not establish that the requested behavior is correct. A bounded result can be truncated. Check its `truncated` flag and increase the budget or follow the source links when the required contract is absent.
+
+## Make and check the change
+
+Add a case to the existing `addition` group. The following is a fragment, not a standalone file:
+
+```text
+it "adds a negative operand" {
+    assert(calculator.add(left=-2, right=5) == 3)
+}
+```
+
+The existing group setup supplies the calculator and its dependencies. Run `check` and `test` again. The new case should pass without changing the implementation: the current operation already adds integers. If your change needs a new error, dependency, or mutation, update the public contract and its callers deliberately; those decisions belong in the review.
+
+## Review the explanation with the patch
+
+Regenerate specs after the change:
+
+```sh
+npx @greenpandastudios/aug-cli@next spec .
+npx @greenpandastudios/aug-cli@next spec . --check
+```
+
+Compare the edited files with the originals, using your editor or source control. The source change adds a behavior case. The spec change should describe that case. Review both and confirm that neither adds an unexpected public export, effect, or dependency. Generated explanations describe checked source; handwritten comments explain domain intent. A passing test covers its exercised inputs, and a current spec is still subject to reader review.
+
+## Give a coding agent the same starting point
+
+A useful instruction is:
+
+> Read `calculator.aug.md` first and follow its linked contracts. Inspect the August source and tests before editing. Add a case that verifies addition with a negative operand. Run `aug check` and `aug test`, regenerate with `aug spec`, and review the source and spec diffs. Report the checks that passed and any limits.
+
+Give the agent an explicit instruction to use the neighboring spec and verify its work. This workflow demonstrates the tools; it makes no comparative productivity claim.
+
+For a larger boundary example, explore [modules and composition](../examples/approved-design/index.md). For a different task, return to the [guides](index.md).

package/docs/guides/index.md

@@ -0,0 +1,27 @@
+# Guides
+
+Choose a guide for the task you are doing. If you are learning August for the first time, start with [the book](../learn/index.md); it introduces the language in order.
+
+## Understand and change a project
+
+| Task | Guide |
+| --- | --- |
+| Review unfamiliar code or an agent's change | [Change a module](change-a-module.md) |
+| Generate and check the neighboring explanations | [Compiled specifications](../specifications.md) |
+| Verify behavior and substitute test dependencies | [Unit tests](../testing.md) |
+| Inspect a diagnostic or find a fix | [Diagnostics](../diagnostics.md) |
+| Use completion, navigation, context, or native builds | [VS Code](../editor.md) and [CLI](../tooling.md) |
+
+## Build and distribute an application
+
+| Task | Guide |
+| --- | --- |
+| Build your first HTTP service | [Weather API](../weather-api.md) |
+| Add endpoints, pages, streams, or crypto | [Web applications](../web.md) |
+| Create or consume a source library | [Packages](../packages.md#author-a-package) |
+| Build and deploy a Linux application image | [Docker](../docker.md) |
+| Edit, run, and test inside a container | [VS Code Dev Containers](../dev-containers.md) |
+| Measure execution time or HTTP throughput | [Performance](../performance.md) |
+| Assess a trial deployment | [Production readiness](../production-readiness.md) |
+
+For exact syntax and contracts, consult the [language reference](../reference.md) and library API pages. [Complete projects](../examples/index.md) show the files, formatted source, and compiled specs together.