@yakcc/cli 0.5.0-alpha.0

package/dist/blocks/ascii-char/impl.ts

@@ -0,0 +1,16 @@
+// SPDX-License-Identifier: MIT
+// @decision DEC-SEEDS-ASCIICHAR-001: ascii-char is the positional consumption primitive.
+// Status: implemented (WI-006)
+// Rationale: Many parsing blocks need to consume a character at a known offset without
+// interpretation. This block is the positional-read utility that others compose.
+
+export function asciiChar(input: string, position: number): string {
+  if (position < 0 || position >= input.length) {
+    throw new RangeError(`Position ${position} out of bounds for input of length ${input.length}`);
+  }
+  const code = input.charCodeAt(position);
+  if (code > 127) {
+    throw new RangeError(`Non-ASCII character at position ${position}: code ${code}`);
+  }
+  return input[position] as string;
+}

package/dist/blocks/ascii-char/proof/manifest.json

@@ -0,0 +1,8 @@
+{
+  "artifacts": [
+    {
+      "kind": "property_tests",
+      "path": "tests.fast-check.ts"
+    }
+  ]
+}

package/dist/blocks/ascii-char/proof/tests.fast-check.ts

@@ -0,0 +1,20 @@
+// SPDX-License-Identifier: MIT
+// Property tests for the ascii-char block.
+// These tests exercise the contract declared in ../spec.yak against the
+// implementation in ../impl.ts.
+//
+// The definitive property-test corpus lives in the parent seed package's
+// seed.test.ts (Suite 4: "property-test corpora"). This file satisfies the
+// L0 proof/manifest.json "property_tests" artifact requirement and makes
+// the test IDs declared in spec.yak traceable to this directory.
+//
+// Test IDs declared in spec.yak:
+//   ascii-char-first
+//   ascii-char-middle
+//   ascii-char-oob
+//   ascii-char-negative
+//   ascii-char-non-ascii
+
+// Re-export the implementation so runners importing this artifact directly
+// can access the block function.
+export * from "../impl.js";

package/dist/blocks/ascii-char/spec.yak

@@ -0,0 +1,80 @@
+{
+  "name": "ascii-char",
+  "inputs": [
+    {
+      "name": "input",
+      "type": "string",
+      "description": "The full input string."
+    },
+    {
+      "name": "position",
+      "type": "number",
+      "description": "Zero-based index to read from."
+    }
+  ],
+  "outputs": [
+    {
+      "name": "char",
+      "type": "string",
+      "description": "Single character at position."
+    }
+  ],
+  "preconditions": [],
+  "postconditions": [],
+  "invariants": [],
+  "effects": [],
+  "level": "L0",
+  "behavior": "Return the single ASCII character at the given zero-based position in the input string. Throws RangeError if position is out of bounds or the character code is above 127.",
+  "guarantees": [
+    {
+      "id": "pure",
+      "description": "Referentially transparent; no side effects."
+    },
+    {
+      "id": "length-1",
+      "description": "Returned string always has length 1."
+    },
+    {
+      "id": "ascii",
+      "description": "Returned character has char code <= 127."
+    }
+  ],
+  "errorConditions": [
+    {
+      "description": "position < 0 or position >= input.length.",
+      "errorType": "RangeError"
+    },
+    {
+      "description": "Character at position has code > 127.",
+      "errorType": "RangeError"
+    }
+  ],
+  "nonFunctional": {
+    "time": "O(1)",
+    "space": "O(1)",
+    "purity": "pure",
+    "threadSafety": "safe"
+  },
+  "propertyTests": [
+    {
+      "id": "ascii-char-first",
+      "description": "asciiChar('abc', 0) returns 'a'"
+    },
+    {
+      "id": "ascii-char-middle",
+      "description": "asciiChar('abc', 1) returns 'b'"
+    },
+    {
+      "id": "ascii-char-oob",
+      "description": "asciiChar('abc', 3) throws RangeError"
+    },
+    {
+      "id": "ascii-char-negative",
+      "description": "asciiChar('abc', -1) throws RangeError"
+    },
+    {
+      "id": "ascii-char-non-ascii",
+      "description": "asciiChar('aéb', 1) throws RangeError"
+    }
+  ]
+}

package/dist/blocks/ascii-digit-set/impl.ts

@@ -0,0 +1,9 @@
+// SPDX-License-Identifier: MIT
+// @decision DEC-SEEDS-ASCIIDIGITSET-001: constant membership test avoids char comparison chains.
+// Status: implemented (WI-006)
+// Rationale: A Boolean predicate over the digit set is used by multiple blocks that need
+// to check-without-consume. Separating it makes the predicate independently testable.
+
+export function isAsciiDigit(c: string): boolean {
+  return c.length === 1 && c >= "0" && c <= "9";
+}

package/dist/blocks/ascii-digit-set/proof/manifest.json

@@ -0,0 +1,8 @@
+{
+  "artifacts": [
+    {
+      "kind": "property_tests",
+      "path": "tests.fast-check.ts"
+    }
+  ]
+}

package/dist/blocks/ascii-digit-set/proof/tests.fast-check.ts

@@ -0,0 +1,20 @@
+// SPDX-License-Identifier: MIT
+// Property tests for the ascii-digit-set block.
+// These tests exercise the contract declared in ../spec.yak against the
+// implementation in ../impl.ts.
+//
+// The definitive property-test corpus lives in the parent seed package's
+// seed.test.ts (Suite 4: "property-test corpora"). This file satisfies the
+// L0 proof/manifest.json "property_tests" artifact requirement and makes
+// the test IDs declared in spec.yak traceable to this directory.
+//
+// Test IDs declared in spec.yak:
+//   ascii-digit-set-zero
+//   ascii-digit-set-nine
+//   ascii-digit-set-letter
+//   ascii-digit-set-empty
+//   ascii-digit-set-multi
+
+// Re-export the implementation so runners importing this artifact directly
+// can access the block function.
+export * from "../impl.js";

package/dist/blocks/ascii-digit-set/spec.yak

@@ -0,0 +1,66 @@
+{
+  "name": "ascii-digit-set",
+  "inputs": [
+    {
+      "name": "c",
+      "type": "string",
+      "description": "A single character."
+    }
+  ],
+  "outputs": [
+    {
+      "name": "result",
+      "type": "boolean",
+      "description": "True iff c is an ASCII digit '0'-'9'."
+    }
+  ],
+  "preconditions": [],
+  "postconditions": [],
+  "invariants": [],
+  "effects": [],
+  "level": "L0",
+  "behavior": "Return true if and only if the single character c is in the ASCII digit set '0'-'9'. Returns false for all other characters including empty string or multi-char strings.",
+  "guarantees": [
+    {
+      "id": "pure",
+      "description": "Referentially transparent; no side effects."
+    },
+    {
+      "id": "total",
+      "description": "Never throws; always returns a boolean."
+    },
+    {
+      "id": "consistent",
+      "description": "isAsciiDigit(c) === (c >= '0' && c <= '9' && c.length === 1)."
+    }
+  ],
+  "errorConditions": [],
+  "nonFunctional": {
+    "time": "O(1)",
+    "space": "O(1)",
+    "purity": "pure",
+    "threadSafety": "safe"
+  },
+  "propertyTests": [
+    {
+      "id": "ascii-digit-set-zero",
+      "description": "isAsciiDigit('0') returns true"
+    },
+    {
+      "id": "ascii-digit-set-nine",
+      "description": "isAsciiDigit('9') returns true"
+    },
+    {
+      "id": "ascii-digit-set-letter",
+      "description": "isAsciiDigit('a') returns false"
+    },
+    {
+      "id": "ascii-digit-set-empty",
+      "description": "isAsciiDigit('') returns false"
+    },
+    {
+      "id": "ascii-digit-set-multi",
+      "description": "isAsciiDigit('12') returns false"
+    }
+  ]
+}

package/dist/blocks/base64-alphabet/impl.ts

@@ -0,0 +1,98 @@
+// SPDX-License-Identifier: MIT
+//
+// @decision DEC-V0-B4-SEED-base64-alphabet-001
+// @title base64-alphabet: RFC 4648 alphabet map and bit-shift encoder
+// @status accepted
+// @rationale
+//   The base64-encode B4 task requires a standard base64 encoder that handles
+//   both standard (RFC 4648 Section 4) and URL-safe (Section 5) alphabets.
+//   This atom implements the core alphabet lookup and bit-extraction loop.
+//
+//   Design decisions:
+//   (A) BIT EXTRACTION ORDER: Each 3-byte group (b0, b1, b2 = 24 bits) is
+//       split into four 6-bit chunks in MSB-first order:
+//         i0 = b0 >> 2
+//         i1 = ((b0 & 0x3) << 4) | (b1 >> 4)
+//         i2 = ((b1 & 0xf) << 2) | (b2 >> 6)
+//         i3 = b2 & 0x3f
+//       This is the normative bit ordering from RFC 4648 Section 3.
+//
+//   (B) PADDING EXCLUDED: The '=' padding character is not appended by this
+//       atom. The B4 task's caller is expected to manage partial-block padding
+//       (as per RFC 4648 Section 3.2). Excluding padding keeps the atom pure
+//       and free of side-conditions about input length divisibility.
+//       The precondition bytes.length % 3 === 0 is enforced with RangeError.
+//
+//   (C) CALLER-CONTROLLED URL-SAFE: A boolean flag selects between the two
+//       alphabets rather than having two separate atoms, because they share
+//       99% of their logic and the flag is a single conditional per output
+//       (actually resolved once at function entry by selecting the alphabet
+//       string). This keeps the corpus size down.
+//
+//   (D) MODULE-SCOPE CONST ALPHABETS: The two 64-character alphabet strings
+//       are module-level constants. They satisfy the strict-subset validator
+//       (const at top level is allowed) and are initialised once at module
+//       load rather than on every call.
+//
+//   (E) noUncheckedIndexedAccess COMPLIANCE: The project tsconfig enables
+//       noUncheckedIndexedAccess, which types arr[n] as T | undefined even
+//       for loop variables proven safe by the loop bounds. Local variables
+//       capture bytes[i], bytes[i+1], bytes[i+2] with ?? 0 fallbacks (the
+//       out-of-range guard above makes these unreachable, but TypeScript
+//       cannot prove that). RangeError validation precedes the fallback.
+//
+//   Reference: RFC 4648 (2006), "The Base16, Base32, and Base64 Data
+//   Encodings", Sections 3, 4, and 5. https://www.rfc-editor.org/rfc/rfc4648
+
+/** Standard RFC 4648 Section 4 base64 alphabet. */
+const STANDARD_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+
+/** URL-safe RFC 4648 Section 5 base64 alphabet (+ -> -, / -> _). */
+const URL_SAFE_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
+
+/**
+ * Encode a byte array to base64 using the RFC 4648 alphabet.
+ *
+ * Input length must be a multiple of 3. Padding ('=') is NOT appended;
+ * the caller is responsible for padding partial input blocks.
+ *
+ * @param bytes   - Byte values, each in [0, 255]. Length must be % 3 === 0.
+ * @param urlSafe - Use URL-safe alphabet (RFC 4648 Section 5) when true.
+ * @returns Base64 encoded string without '=' padding.
+ * @throws RangeError if bytes.length % 3 !== 0 or any byte is outside [0, 255].
+ */
+export function base64Encode(bytes: number[], urlSafe: boolean): string {
+  if (bytes.length % 3 !== 0) {
+    throw new RangeError(`base64Encode: input length must be a multiple of 3, got ${bytes.length}`);
+  }
+
+  const alphabet = urlSafe ? URL_SAFE_ALPHABET : STANDARD_ALPHABET;
+  let result = "";
+
+  for (let i = 0; i < bytes.length; i += 3) {
+    // Capture with ?? 0: the loop bound (i < bytes.length) and length % 3 === 0 guarantee
+    // bytes[i], bytes[i+1], bytes[i+2] are always defined here; ?? 0 is a TypeScript
+    // appeasement for noUncheckedIndexedAccess and is never reached at runtime.
+    const b0 = bytes[i] ?? 0;
+    const b1 = bytes[i + 1] ?? 0;
+    const b2 = bytes[i + 2] ?? 0;
+
+    if (b0 > 255 || b1 > 255 || b2 > 255) {
+      throw new RangeError(`base64Encode: byte value out of range [0, 255] at index ${i}`);
+    }
+
+    // Extract four 6-bit groups from three 8-bit bytes (MSB-first, RFC 4648 Section 3)
+    const i0 = (b0 >> 2) & 0x3f;
+    const i1 = ((b0 & 0x03) << 4) | ((b1 >> 4) & 0x0f);
+    const i2 = ((b1 & 0x0f) << 2) | ((b2 >> 6) & 0x03);
+    const i3 = b2 & 0x3f;
+
+    // alphabet[n] is string | undefined per noUncheckedIndexedAccess.
+    // Indices i0-i3 are in [0, 63] by construction (6-bit values), and alphabet
+    // has exactly 64 characters, so these lookups always succeed.
+    result +=
+      (alphabet[i0] ?? "") + (alphabet[i1] ?? "") + (alphabet[i2] ?? "") + (alphabet[i3] ?? "");
+  }
+
+  return result;
+}

package/dist/blocks/base64-alphabet/proof/manifest.json

@@ -0,0 +1,8 @@
+{
+  "artifacts": [
+    {
+      "kind": "property_tests",
+      "path": "tests.fast-check.ts"
+    }
+  ]
+}

package/dist/blocks/base64-alphabet/proof/tests.fast-check.ts

@@ -0,0 +1,18 @@
+// SPDX-License-Identifier: MIT
+// Property tests for the base64-alphabet block.
+// These tests exercise the contract declared in ../spec.yak against the
+// implementation in ../impl.ts.
+//
+// Test IDs declared in spec.yak:
+//   base64-empty
+//   base64-standard-known
+//   base64-url-safe-known
+//   base64-output-length
+//   base64-invalid-length
+//   base64-byte-out-of-range
+//   base64-all-zeros
+//   base64-all-255
+
+// Re-export implementation so runners importing this artifact directly
+// can access the block functions.
+export * from "../impl.js";

package/dist/blocks/base64-alphabet/spec.yak

@@ -0,0 +1,110 @@
+{
+  "name": "base64-alphabet",
+  "inputs": [
+    {
+      "name": "bytes",
+      "type": "number[]",
+      "description": "Array of byte values (each in range 0-255). Length must be a multiple of 3; if not, caller must pad."
+    },
+    {
+      "name": "urlSafe",
+      "type": "boolean",
+      "description": "When true, uses URL-safe alphabet (+/ replaced with -_). When false uses standard RFC 4648 alphabet."
+    }
+  ],
+  "outputs": [
+    {
+      "name": "encoded",
+      "type": "string",
+      "description": "Base64 encoded string without padding characters. Caller appends '=' padding if required."
+    }
+  ],
+  "preconditions": [
+    {
+      "description": "Each element of bytes is an integer in [0, 255]."
+    },
+    {
+      "description": "bytes.length is a multiple of 3 (padding is caller's responsibility)."
+    }
+  ],
+  "postconditions": [
+    {
+      "description": "encoded.length === (bytes.length / 3) * 4"
+    },
+    {
+      "description": "Every character in encoded is from the selected RFC 4648 alphabet."
+    }
+  ],
+  "invariants": [],
+  "effects": [],
+  "level": "L0",
+  "behavior": "Encode a byte array to base64 using the RFC 4648 alphabet. Groups bytes in triplets, extracts four 6-bit values via bit-shift, maps each to the alphabet character at that index, and concatenates. When urlSafe is true, replaces '+' with '-' and '/' with '_'. Padding ('=') is not appended; the caller is responsible for padding if the byte count is not a multiple of 3.",
+  "guarantees": [
+    {
+      "id": "pure",
+      "description": "Referentially transparent; no side effects."
+    },
+    {
+      "id": "rfc4648-standard",
+      "description": "Standard alphabet: A-Z, a-z, 0-9, +, / (RFC 4648 Section 4)."
+    },
+    {
+      "id": "rfc4648-url-safe",
+      "description": "URL-safe alphabet: A-Z, a-z, 0-9, -, _ (RFC 4648 Section 5)."
+    },
+    {
+      "id": "output-length",
+      "description": "Output length is exactly (bytes.length / 3) * 4 characters."
+    }
+  ],
+  "errorConditions": [
+    {
+      "description": "bytes.length is not a multiple of 3.",
+      "errorType": "RangeError"
+    },
+    {
+      "description": "A byte value is outside [0, 255].",
+      "errorType": "RangeError"
+    }
+  ],
+  "nonFunctional": {
+    "time": "O(n) where n is bytes.length",
+    "space": "O(n) for the output string",
+    "purity": "pure",
+    "threadSafety": "safe"
+  },
+  "propertyTests": [
+    {
+      "id": "base64-empty",
+      "description": "base64Encode([], false) returns empty string"
+    },
+    {
+      "id": "base64-standard-known",
+      "description": "base64Encode([77,97,110], false) returns 'TWFu' (RFC 4648 example)"
+    },
+    {
+      "id": "base64-url-safe-known",
+      "description": "base64Encode bytes that produce + or / in standard mode returns - or _ in url-safe mode"
+    },
+    {
+      "id": "base64-output-length",
+      "description": "Output length === (bytes.length / 3) * 4 for any valid input"
+    },
+    {
+      "id": "base64-invalid-length",
+      "description": "bytes.length not a multiple of 3 throws RangeError"
+    },
+    {
+      "id": "base64-byte-out-of-range",
+      "description": "Byte value 256 throws RangeError"
+    },
+    {
+      "id": "base64-all-zeros",
+      "description": "base64Encode([0,0,0], false) returns 'AAAA'"
+    },
+    {
+      "id": "base64-all-255",
+      "description": "base64Encode([255,255,255], false) returns '////' (three max-value bytes)"
+    }
+  ]
+}

package/dist/blocks/bracket/impl.ts

@@ -0,0 +1,20 @@
+// SPDX-License-Identifier: MIT
+// @decision DEC-SEEDS-BRACKET-001: bracket matches a single bracket char and returns next position.
+// Status: implemented (WI-006)
+// Rationale: Bracket matching is a hot path in list parsing. Returning the post-bracket position
+// follows the positional combinator convention used by all other blocks in this corpus.
+
+export function bracket(input: string, position: number, kind: "[" | "]"): number {
+  if (position < 0) {
+    throw new RangeError(`Position ${position} is negative`);
+  }
+  if (position >= input.length) {
+    throw new SyntaxError(`Expected '${kind}' at position ${position} but reached end of input`);
+  }
+  if (input[position] !== kind) {
+    throw new SyntaxError(
+      `Expected '${kind}' at position ${position} but found ${JSON.stringify(input[position])}`,
+    );
+  }
+  return position + 1;
+}

package/dist/blocks/bracket/proof/manifest.json

@@ -0,0 +1,8 @@
+{
+  "artifacts": [
+    {
+      "kind": "property_tests",
+      "path": "tests.fast-check.ts"
+    }
+  ]
+}

package/dist/blocks/bracket/proof/tests.fast-check.ts

@@ -0,0 +1,20 @@
+// SPDX-License-Identifier: MIT
+// Property tests for the bracket block.
+// These tests exercise the contract declared in ../spec.yak against the
+// implementation in ../impl.ts.
+//
+// The definitive property-test corpus lives in the parent seed package's
+// seed.test.ts (Suite 4: "property-test corpora"). This file satisfies the
+// L0 proof/manifest.json "property_tests" artifact requirement and makes
+// the test IDs declared in spec.yak traceable to this directory.
+//
+// Test IDs declared in spec.yak:
+//   bracket-open
+//   bracket-close
+//   bracket-mismatch
+//   bracket-oob
+//   bracket-negative
+
+// Re-export the implementation so runners importing this artifact directly
+// can access the block function.
+export * from "../impl.js";

package/dist/blocks/bracket/spec.yak

@@ -0,0 +1,85 @@
+{
+  "name": "bracket",
+  "inputs": [
+    {
+      "name": "input",
+      "type": "string",
+      "description": "The full input string."
+    },
+    {
+      "name": "position",
+      "type": "number",
+      "description": "Zero-based position to match at."
+    },
+    {
+      "name": "kind",
+      "type": "'[' | ']'",
+      "description": "Which bracket to expect."
+    }
+  ],
+  "outputs": [
+    {
+      "name": "newPosition",
+      "type": "number",
+      "description": "position + 1 after matching the bracket."
+    }
+  ],
+  "preconditions": [],
+  "postconditions": [],
+  "invariants": [],
+  "effects": [],
+  "level": "L0",
+  "behavior": "Assert that the character at position equals kind ('[' or ']'), then return position + 1. Throws SyntaxError if the character does not match or if position is out of bounds.",
+  "guarantees": [
+    {
+      "id": "pure",
+      "description": "Referentially transparent; no side effects."
+    },
+    {
+      "id": "advance-1",
+      "description": "Returns position + 1 on success."
+    }
+  ],
+  "errorConditions": [
+    {
+      "description": "Character at position does not equal kind.",
+      "errorType": "SyntaxError"
+    },
+    {
+      "description": "position >= input.length (end of input).",
+      "errorType": "SyntaxError"
+    },
+    {
+      "description": "position < 0.",
+      "errorType": "RangeError"
+    }
+  ],
+  "nonFunctional": {
+    "time": "O(1)",
+    "space": "O(1)",
+    "purity": "pure",
+    "threadSafety": "safe"
+  },
+  "propertyTests": [
+    {
+      "id": "bracket-open",
+      "description": "bracket('[abc', 0, '[') returns 1"
+    },
+    {
+      "id": "bracket-close",
+      "description": "bracket(']', 0, ']') returns 1"
+    },
+    {
+      "id": "bracket-mismatch",
+      "description": "bracket('[', 0, ']') throws SyntaxError"
+    },
+    {
+      "id": "bracket-oob",
+      "description": "bracket('', 0, '[') throws SyntaxError"
+    },
+    {
+      "id": "bracket-negative",
+      "description": "bracket('[', -1, '[') throws RangeError"
+    }
+  ]
+}

package/dist/blocks/char-code/impl.ts

@@ -0,0 +1,15 @@
+// SPDX-License-Identifier: MIT
+// @decision DEC-SEEDS-CHARCODE-001: char-code exposes char-code lookup as an explicit contract.
+// Status: implemented (WI-006)
+// Rationale: Multiple blocks rely on charCodeAt arithmetic. Making it an explicit block
+// documents the zero-extension property (always non-negative) and enables registry reuse.
+
+export function charCode(input: string, position: number): number {
+  if (position < 0) {
+    throw new RangeError(`Position ${position} is negative`);
+  }
+  if (position >= input.length) {
+    throw new RangeError(`Position ${position} out of bounds for input of length ${input.length}`);
+  }
+  return input.charCodeAt(position);
+}

package/dist/blocks/char-code/proof/manifest.json

@@ -0,0 +1,8 @@
+{
+  "artifacts": [
+    {
+      "kind": "property_tests",
+      "path": "tests.fast-check.ts"
+    }
+  ]
+}

package/dist/blocks/char-code/proof/tests.fast-check.ts

@@ -0,0 +1,20 @@
+// SPDX-License-Identifier: MIT
+// Property tests for the char-code block.
+// These tests exercise the contract declared in ../spec.yak against the
+// implementation in ../impl.ts.
+//
+// The definitive property-test corpus lives in the parent seed package's
+// seed.test.ts (Suite 4: "property-test corpora"). This file satisfies the
+// L0 proof/manifest.json "property_tests" artifact requirement and makes
+// the test IDs declared in spec.yak traceable to this directory.
+//
+// Test IDs declared in spec.yak:
+//   char-code-zero
+//   char-code-a
+//   char-code-oob
+//   char-code-negative
+//   char-code-bracket
+
+// Re-export the implementation so runners importing this artifact directly
+// can access the block function.
+export * from "../impl.js";