docs: sync bounded ACL diagnostics

Author: RoyLin

apps/docs/content/docs/cn/acl/index.mdx

@@ -18,7 +18,7 @@ Rust crate 与 Node.js/TypeScript SDK，可以把 ACL 文本解析成 AST，也
 | 领域 | 当前能力 |
 | --- | --- |
 | 语法 | ACL attributes、带 label 的 blocks、nested blocks、lists、objects、strings、numbers、booleans、null、function calls、comments，以及 `=` / `:` assignments。 |
-| Lexer/parser | Bounded parsing、stable diagnostic codes、UTF-8 byte spans、comment skipping、string escapes、negative numbers 和 scientific notation。 |
+| Lexer/parser | Bounded parsing 和 multi-diagnostic collection、stable diagnostic codes、UTF-8 byte spans、comment skipping、string escapes、negative numbers 和 scientific notation。 |
 | 函数 | 支持把 `env(...)`、`concat(...)` 和自定义函数名表示为 first-class call values。 |
 | AST | `Document`、`Block`、typed values、builders、value constructors 和 `Value` accessors。 |
 | 生成 | Native ACL output、block-header labels、sorted attributes 和 objects、type-stable strings，以及 map generation。 |
@@ -29,8 +29,8 @@ Rust crate 与 Node.js/TypeScript SDK，可以把 ACL 文本解析成 AST，也
 
 - [Syntax](/cn/docs/acl/syntax) 说明 blocks、attributes、values、calls、
   comments 和 parser boundaries。
-- [Rust API](/cn/docs/acl/rust-api) 覆盖 bounded parsing、diagnostics、canonical
-  digests、generation、builders 和 AST value helpers。
+- [Rust API](/cn/docs/acl/rust-api) 覆盖 bounded parsing、multi-diagnostic
+  collection、canonical digests、generation、builders 和 AST value helpers。
 - [Node SDK](/cn/docs/acl/node-sdk) 覆盖 JavaScript/TypeScript parser、
   native ACL generator、canonical APIs 和 builders。
 - [Generation And Boundaries](/cn/docs/acl/generation-boundaries) 说明 stable

apps/docs/content/docs/cn/acl/node-sdk.mdx

@@ -1,6 +1,6 @@
 ---
 title: Node SDK
-description: "@a3s-lab/acl 的 JavaScript/TypeScript bounded parsing、native ACL generation、canonical digests 和 builders。"
+description: "@a3s-lab/acl 的 JavaScript/TypeScript bounded parsing、multi-diagnostics、native ACL generation、canonical digests 和 builders。"
 ---
 
 # Node SDK
@@ -44,8 +44,9 @@ const generated = generate(new DocumentBuilder().block(provider).build());
 | API | 作用 |
 | --- | --- |
 | `parse(input, limits?)` | 使用默认或显式 resource limits，把 ACL text 解析成 `Document`。 |
-| `DEFAULT_PARSE_LIMITS` | Document bytes、nesting、collection items 和 token bytes 的 shared immutable defaults。 |
-| `ParseError`、`DIAGNOSTIC_CODES` | Stable codes、complete spans、UTF-8 byte offsets 和 redacted messages。 |
+| `collectDiagnostics(input, limits?)` | 在不构造 partial AST 的前提下收集 bounded diagnostics。 |
+| `DEFAULT_PARSE_LIMITS` | Document bytes、nesting、collection items、token bytes 和 diagnostic count 的 shared immutable defaults。 |
+| `ParseError`、`DIAGNOSTIC_CODES`、`DiagnosticReport` | Stable codes、complete spans、UTF-8 byte offsets、redacted messages 和明确的 truncation state。 |
 | `generate(doc)` | 生成 labels 位于 block headers 的 native ACL text。 |
 | `canonicalBytes(doc)`、`canonicalDigest(doc)` | 生成 stable cross-SDK bytes 和带 algorithm prefix 的 SHA-256 digest。 |
 | `CanonicalError` | 对 non-finite numbers、non-scalar strings 和 non-portable identifiers 返回不回显值的错误。 |
@@ -70,6 +71,7 @@ try {
     maxNestingDepth: 32,
     maxCollectionItems: 1_000,
     maxTokenBytes: 16 * 1024,
+    maxDiagnostics: 20,
   });
 } catch (error) {
   if (error instanceof ParseError) {
@@ -81,6 +83,22 @@ try {
 Document 和 token sizes 使用 UTF-8 bytes。Diagnostic messages 只标识 token
 kinds，不包含 source token values 或 snippets。
 
+Parse API 仍然是 fail-fast。CLI 和 editor integrations 可以使用 bounded
+budget 收集多个错误：
+
+```typescript
+import {collectDiagnostics} from '@a3s-lab/acl';
+
+const report = collectDiagnostics('first = ]\nsecond = ]', {
+  maxDiagnostics: 20,
+});
+```
+
+发生 syntax error 后，collection 会从下一 source line 继续。
+Resource-limit diagnostics 仍然是 fatal。Report 最多保存
+`maxDiagnostics` 个 errors，只有在继续观察到超出 budget 的 error 后才会把
+`truncated` 设为 true。
+
 ## Native And Canonical Output
 
 `generate` 只有一个 native ACL output contract。Labels 保留在 block headers；

apps/docs/content/docs/cn/acl/rust-api.mdx

@@ -1,6 +1,6 @@
 ---
 title: Rust API
-description: a3s-acl 的 Rust bounded parsing、diagnostics、canonical digests、native ACL generation、AST 和 builders。
+description: a3s-acl 的 Rust bounded parsing、multi-diagnostics、canonical digests、native ACL generation、AST 和 builders。
 ---
 
 # Rust API
@@ -34,8 +34,9 @@ Public crate exports：
 | API | 作用 |
 | --- | --- |
 | `parse` / `parse_acl` | 把 ACL text 解析成 `Document`。 |
-| `parse_with_limits`、`ParseLimits` | 使用显式 document、nesting、collection 和 token limits 解析 untrusted input。 |
-| `DiagnosticCode`、`ParseError` | 返回 stable codes、UTF-8 byte spans 和 redacted messages。 |
+| `parse_with_limits`、`ParseLimits` | 使用显式 document、nesting、collection、token 和 diagnostic limits 解析 untrusted input。 |
+| `collect_diagnostics`、`collect_diagnostics_with_limits` | 在不构造 partial AST 的前提下收集 bounded diagnostics。 |
+| `DiagnosticCode`、`ParseError`、`DiagnosticReport` | 返回 stable codes、UTF-8 byte spans、redacted messages 和明确的 truncation state。 |
 | `generate` / `generate_acl` | 从 `Document` 生成 ACL text。 |
 | `generate_from_map` | 从 `HashMap<String, Value>` 生成 ACL text。 |
 | `canonical_bytes`、`canonical_digest` | 生成 stable cross-SDK bytes 和带 algorithm prefix 的 SHA-256 digest。 |
@@ -55,6 +56,7 @@ let document = parse_with_limits(
         max_nesting_depth: 32,
         max_collection_items: 1_000,
         max_token_bytes: 16 * 1024,
+        max_diagnostics: 20,
     },
 )?;
 ```
@@ -64,6 +66,26 @@ Document 和 token sizes 使用 UTF-8 bytes。`ParseError` 提供 stable
 compatibility `line` / `column` fields。Messages 只标识 token kinds，不包含
 source token values 或 snippets。
 
+Parse APIs 仍然是 fail-fast。CLI 和 editor integrations 可以使用 bounded
+budget 收集多个错误：
+
+```rust
+use a3s_acl::{collect_diagnostics_with_limits, ParseLimits};
+
+let report = collect_diagnostics_with_limits(
+    "first = ]\nsecond = ]",
+    ParseLimits {
+        max_diagnostics: 20,
+        ..ParseLimits::default()
+    },
+);
+```
+
+发生 syntax error 后，collection 会从下一 source line 继续。
+Resource-limit diagnostics 仍然是 fatal。Report 最多保存
+`max_diagnostics` 个 errors，只有在继续观察到超出 budget 的 error 后才会把
+`truncated` 设为 true。
+
 ## AST
 
 | Type | Fields |

apps/docs/content/docs/en/acl/index.mdx

@@ -18,7 +18,7 @@ is `@a3s-lab/acl` `0.2.2`. The crate repository metadata points to
 | Area | Current capability |
 | --- | --- |
 | Syntax | ACL attributes, labeled blocks, nested blocks, lists, objects, strings, numbers, booleans, null, function calls, comments, and `=` / `:` assignments. |
-| Lexer/parser | Bounded parsing, stable diagnostic codes, UTF-8 byte spans, comment skipping, string escapes, negative numbers, and scientific notation. |
+| Lexer/parser | Bounded parsing and multi-diagnostic collection, stable diagnostic codes, UTF-8 byte spans, comment skipping, string escapes, negative numbers, and scientific notation. |
 | Functions | First-class call values such as `env(...)`, `concat(...)`, and custom function names. |
 | AST | `Document`, `Block`, typed values, builders, value constructors, and `Value` accessors. |
 | Generation | Native ACL output, block-header labels, sorted attributes and objects, type-stable strings, and map generation. |
@@ -29,8 +29,8 @@ is `@a3s-lab/acl` `0.2.2`. The crate repository metadata points to
 
 - [Syntax](/docs/acl/syntax) documents blocks, attributes, values, calls,
   comments, and parser boundaries.
-- [Rust API](/docs/acl/rust-api) covers bounded parsing, diagnostics, canonical
-  digests, generation, builders, and AST value helpers.
+- [Rust API](/docs/acl/rust-api) covers bounded parsing, multi-diagnostic
+  collection, canonical digests, generation, builders, and AST value helpers.
 - [Node SDK](/docs/acl/node-sdk) covers the JavaScript/TypeScript parser,
   native ACL generator, canonical APIs, and builders.
 - [Generation And Boundaries](/docs/acl/generation-boundaries) explains stable

apps/docs/content/docs/en/acl/node-sdk.mdx

@@ -1,6 +1,6 @@
 ---
 title: Node SDK
-description: JavaScript and TypeScript bounded parsing, native ACL generation, canonical digests, and builders in @a3s-lab/acl.
+description: JavaScript and TypeScript bounded parsing, multi-diagnostics, native ACL generation, canonical digests, and builders in @a3s-lab/acl.
 ---
 
 # Node SDK
@@ -44,8 +44,9 @@ const generated = generate(new DocumentBuilder().block(provider).build());
 | API | Role |
 | --- | --- |
 | `parse(input, limits?)` | Parse ACL text into a `Document` with default or explicit resource limits. |
-| `DEFAULT_PARSE_LIMITS` | Shared immutable defaults for document bytes, nesting, collection items, and token bytes. |
-| `ParseError`, `DIAGNOSTIC_CODES` | Stable codes, complete spans, UTF-8 byte offsets, and redacted messages. |
+| `collectDiagnostics(input, limits?)` | Collect bounded diagnostics without constructing a partial AST. |
+| `DEFAULT_PARSE_LIMITS` | Shared immutable defaults for document bytes, nesting, collection items, token bytes, and diagnostic count. |
+| `ParseError`, `DIAGNOSTIC_CODES`, `DiagnosticReport` | Stable codes, complete spans, UTF-8 byte offsets, redacted messages, and explicit truncation state. |
 | `generate(doc)` | Generate native ACL text with labels in block headers. |
 | `canonicalBytes(doc)`, `canonicalDigest(doc)` | Produce stable cross-SDK bytes and an algorithm-prefixed SHA-256 digest. |
 | `CanonicalError` | Report non-finite numbers, non-scalar strings, and non-portable identifiers without echoing values. |
@@ -70,6 +71,7 @@ try {
     maxNestingDepth: 32,
     maxCollectionItems: 1_000,
     maxTokenBytes: 16 * 1024,
+    maxDiagnostics: 20,
   });
 } catch (error) {
   if (error instanceof ParseError) {
@@ -81,6 +83,22 @@ try {
 Document and token sizes count UTF-8 bytes. Diagnostic messages identify token
 kinds but never include source token values or snippets.
 
+The parse API remains fail-fast. CLI and editor integrations can collect
+multiple errors with a bounded budget:
+
+```typescript
+import {collectDiagnostics} from '@a3s-lab/acl';
+
+const report = collectDiagnostics('first = ]\nsecond = ]', {
+  maxDiagnostics: 20,
+});
+```
+
+After a syntax error, collection resumes at the next source line.
+Resource-limit diagnostics remain fatal. A report stores at most
+`maxDiagnostics` errors and sets `truncated` only after observing another error
+beyond that budget.
+
 ## Native And Canonical Output
 
 `generate` has one native ACL output contract. Labels remain in block headers;

apps/docs/content/docs/en/acl/rust-api.mdx

@@ -1,6 +1,6 @@
 ---
 title: Rust API
-description: Rust bounded parsing, diagnostics, canonical digests, native ACL generation, AST, and builders for a3s-acl.
+description: Rust bounded parsing, multi-diagnostics, canonical digests, native ACL generation, AST, and builders for a3s-acl.
 ---
 
 # Rust API
@@ -34,8 +34,9 @@ The public crate exports:
 | API | Role |
 | --- | --- |
 | `parse` / `parse_acl` | Parse ACL text into a `Document`. |
-| `parse_with_limits`, `ParseLimits` | Parse untrusted input with explicit document, nesting, collection, and token limits. |
-| `DiagnosticCode`, `ParseError` | Return stable codes, UTF-8 byte spans, and redacted messages. |
+| `parse_with_limits`, `ParseLimits` | Parse untrusted input with explicit document, nesting, collection, token, and diagnostic limits. |
+| `collect_diagnostics`, `collect_diagnostics_with_limits` | Collect bounded diagnostics without constructing a partial AST. |
+| `DiagnosticCode`, `ParseError`, `DiagnosticReport` | Return stable codes, UTF-8 byte spans, redacted messages, and explicit truncation state. |
 | `generate` / `generate_acl` | Generate ACL text from a `Document`. |
 | `generate_from_map` | Build ACL text from a `HashMap<String, Value>`. |
 | `canonical_bytes`, `canonical_digest` | Produce stable cross-SDK bytes and an algorithm-prefixed SHA-256 digest. |
@@ -55,6 +56,7 @@ let document = parse_with_limits(
         max_nesting_depth: 32,
         max_collection_items: 1_000,
         max_token_bytes: 16 * 1024,
+        max_diagnostics: 20,
     },
 )?;
 ```
@@ -64,6 +66,26 @@ Document and token sizes count UTF-8 bytes. `ParseError` exposes a stable
 compatibility `line` / `column` fields. Messages identify token kinds without
 including source token values or snippets.
 
+The parse APIs remain fail-fast. CLI and editor integrations can collect
+multiple errors with a bounded budget:
+
+```rust
+use a3s_acl::{collect_diagnostics_with_limits, ParseLimits};
+
+let report = collect_diagnostics_with_limits(
+    "first = ]\nsecond = ]",
+    ParseLimits {
+        max_diagnostics: 20,
+        ..ParseLimits::default()
+    },
+);
+```
+
+After a syntax error, collection resumes at the next source line.
+Resource-limit diagnostics remain fatal. A report stores at most
+`max_diagnostics` errors and sets `truncated` only after observing another
+error beyond that budget.
+
 ## AST
 
 | Type | Fields |

compat/cloud-stack.acl

@@ -9,7 +9,7 @@ component "acl" {
   package = "a3s-acl"
   path = "crates/acl"
   repository = "git@github.com:A3S-Lab/ACL.git"
-  revision = "9e55b23f3659cea390fe51d911c53a26a6902ac5"
+  revision = "cef613ef945cff9ebbc5a36b983d1daaa1067fdb"
   source = "git"
   version = "0.2.2"
 }