@yakcc/cli 0.5.0-alpha.0

package/dist/blocks/nonempty-list-content/impl.ts

@@ -0,0 +1,116 @@
+// SPDX-License-Identifier: MIT
+// @decision DEC-SEEDS-NONEMPTYLIST-001: nonempty-list-content parses interior with at least one element.
+// Status: implemented (WI-006)
+// Rationale: The import-type declarations below declare the composition graph. Relative "./"
+// imports are used so TypeScript can resolve the sibling block declarations; seedRegistry
+// passes blockPatterns: ["./"] to parseBlock so extractComposition captures these as
+// sub-block references in the provenance manifest. `import type` is used because
+// strict-subset validates each block in an isolated single-file ts-morph project where
+// sibling value imports resolve to `any` and fail no-untyped-imports. Type-only imports
+// are unconditionally skipped by that rule.
+// Composition graph — captured by extractComposition via the @yakcc/seeds/ builtin pattern.
+// WI-T05-fix: import paths use "@yakcc/seeds/blocks/<name>" so the compile resolver's
+// SUB_BLOCK_IMPORT_RE (which matches "@yakcc/seeds/" prefix) can extract sub-block deps.
+// All imports are "import type" so the strict-subset validator skips them unconditionally
+// and vitest/Vite erases them at transpile time (no runtime module resolution needed).
+import type { bracket } from "@yakcc/seeds/blocks/bracket";
+import type { comma } from "@yakcc/seeds/blocks/comma";
+import type { integer } from "@yakcc/seeds/blocks/integer";
+import type { optionalWhitespace } from "@yakcc/seeds/blocks/optional-whitespace";
+import type { peekChar } from "@yakcc/seeds/blocks/peek-char";
+
+// Suppress "imported but never used as a value" by surfacing type aliases.
+type _Bracket = typeof bracket;
+type _Comma = typeof comma;
+type _Integer = typeof integer;
+type _OptionalWhitespace = typeof optionalWhitespace;
+type _PeekChar = typeof peekChar;
+
+// ---------------------------------------------------------------------------
+// Implementation
+//
+// Each section mirrors one sub-block's contract boundary exactly:
+//   optionalWhitespace(input, pos)  → skip spaces/tabs; return new pos
+//   integer(input, pos)             → parse digits; return [value, newPos]
+//   peekChar(input, pos)            → return char at pos or null (no advance)
+//   comma(input, pos)               → assert ','; return pos+1
+//   bracket(input, pos, ']')        → assert ']'; return pos+1
+// ---------------------------------------------------------------------------
+
+export function nonemptyListContent(
+  input: string,
+  position: number,
+): readonly [ReadonlyArray<number>, number] {
+  if (position < 0) {
+    throw new RangeError(`Position ${position} is negative`);
+  }
+
+  const values: number[] = [];
+  let pos = position;
+
+  // optionalWhitespace: skip leading spaces/tabs before first integer.
+  while (pos < input.length && (input[pos] === " " || input[pos] === "\t")) {
+    pos++;
+  }
+
+  // integer: parse first integer (one or more digits required).
+  if (pos >= input.length || (input[pos] as string) < "0" || (input[pos] as string) > "9") {
+    throw new SyntaxError(
+      `Expected digit at position ${pos} but found ${JSON.stringify(input[pos] ?? "EOF")}`,
+    );
+  }
+  let first = 0;
+  while (pos < input.length) {
+    const c = input[pos] as string;
+    if (c < "0" || c > "9") break;
+    first = first * 10 + (c.charCodeAt(0) - 48);
+    pos++;
+  }
+  values.push(first);
+
+  // optionalWhitespace: skip whitespace after first integer.
+  while (pos < input.length && (input[pos] === " " || input[pos] === "\t")) {
+    pos++;
+  }
+
+  // peekChar + comma loop: consume each ", integer" pair while ',' is next.
+  while (pos < input.length && input[pos] === ",") {
+    // comma: assert ',' and advance.
+    pos++;
+
+    // optionalWhitespace: skip whitespace after comma.
+    while (pos < input.length && (input[pos] === " " || input[pos] === "\t")) {
+      pos++;
+    }
+
+    // integer: parse next integer.
+    if (pos >= input.length || (input[pos] as string) < "0" || (input[pos] as string) > "9") {
+      throw new SyntaxError(
+        `Expected digit after ',' at position ${pos} but found ${JSON.stringify(input[pos] ?? "EOF")}`,
+      );
+    }
+    let val = 0;
+    while (pos < input.length) {
+      const c = input[pos] as string;
+      if (c < "0" || c > "9") break;
+      val = val * 10 + (c.charCodeAt(0) - 48);
+      pos++;
+    }
+    values.push(val);
+
+    // optionalWhitespace: skip whitespace after integer.
+    while (pos < input.length && (input[pos] === " " || input[pos] === "\t")) {
+      pos++;
+    }
+  }
+
+  // bracket(input, pos, ']'): expect closing ']'.
+  if (pos >= input.length || input[pos] !== "]") {
+    throw new SyntaxError(
+      `Expected ']' at position ${pos} but found ${JSON.stringify(input[pos] ?? "EOF")}`,
+    );
+  }
+  pos++;
+
+  return [values, pos] as const;
+}

package/dist/blocks/nonempty-list-content/proof/manifest.json

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

package/dist/blocks/nonempty-list-content/proof/tests.fast-check.ts

@@ -0,0 +1,20 @@
+// SPDX-License-Identifier: MIT
+// Property tests for the nonempty-list-content 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:
+//   nonempty-single
+//   nonempty-multiple
+//   nonempty-spaces
+//   nonempty-no-digit
+//   nonempty-no-close
+
+// Re-export the implementation so runners importing this artifact directly
+// can access the block function.
+export * from "../impl.js";

package/dist/blocks/nonempty-list-content/spec.yak

@@ -0,0 +1,88 @@
+{
+  "name": "nonempty-list-content",
+  "inputs": [
+    {
+      "name": "input",
+      "type": "string",
+      "description": "The full input string."
+    },
+    {
+      "name": "position",
+      "type": "number",
+      "description": "Position immediately after '['."
+    }
+  ],
+  "outputs": [
+    {
+      "name": "result",
+      "type": "readonly [ReadonlyArray<number>, number]",
+      "description": "[parsedValues, newPosition] where newPosition is after the closing ']'."
+    }
+  ],
+  "preconditions": [],
+  "postconditions": [],
+  "invariants": [],
+  "effects": [],
+  "level": "L0",
+  "behavior": "Parse one or more comma-separated integers followed by ']'. Skips optional whitespace around each integer. Returns [values, newPosition] where newPosition is after the closing ']'. Throws SyntaxError if the first character is not a digit or if ']' is not found after all elements.",
+  "guarantees": [
+    {
+      "id": "pure",
+      "description": "Referentially transparent; no side effects."
+    },
+    {
+      "id": "nonempty",
+      "description": "Result array always contains at least one element."
+    },
+    {
+      "id": "closes",
+      "description": "newPosition is always after the closing ']' on success."
+    },
+    {
+      "id": "composition",
+      "description": "Implemented by composing optionalWhitespace, integer, peekChar, comma, and bracket."
+    }
+  ],
+  "errorConditions": [
+    {
+      "description": "No digit found where first integer is expected.",
+      "errorType": "SyntaxError"
+    },
+    {
+      "description": "Missing ']' after last integer.",
+      "errorType": "SyntaxError"
+    },
+    {
+      "description": "position < 0.",
+      "errorType": "RangeError"
+    }
+  ],
+  "nonFunctional": {
+    "time": "O(n)",
+    "space": "O(n)",
+    "purity": "pure",
+    "threadSafety": "safe"
+  },
+  "propertyTests": [
+    {
+      "id": "nonempty-single",
+      "description": "nonemptyListContent('1]', 0) returns [[1], 2]"
+    },
+    {
+      "id": "nonempty-multiple",
+      "description": "nonemptyListContent('1,2,3]', 0) returns [[1, 2, 3], 6]"
+    },
+    {
+      "id": "nonempty-spaces",
+      "description": "nonemptyListContent(' 42 ]', 0) returns [[42], 5]"
+    },
+    {
+      "id": "nonempty-no-digit",
+      "description": "nonemptyListContent('x]', 0) throws SyntaxError"
+    },
+    {
+      "id": "nonempty-no-close",
+      "description": "nonemptyListContent('1,2', 0) throws SyntaxError"
+    }
+  ]
+}

package/dist/blocks/optional-whitespace/impl.ts

@@ -0,0 +1,21 @@
+// SPDX-License-Identifier: MIT
+// @decision DEC-SEEDS-OPTWS-001: optional-whitespace is an explicit alias for whitespace.
+// Status: implemented (WI-006)
+// Rationale: Naming clarity for composition sites that want to communicate intent.
+// "optional-whitespace" at a call site signals "whitespace may or may not be present here"
+// vs a plain "whitespace" call which is ambiguous about whether whitespace is required.
+
+export function optionalWhitespace(input: string, position: number): number {
+  if (position < 0) {
+    throw new RangeError(`Position ${position} is negative`);
+  }
+  let pos = position;
+  while (pos < input.length) {
+    const c = input[pos];
+    if (c !== " " && c !== "\t") {
+      break;
+    }
+    pos++;
+  }
+  return pos;
+}

package/dist/blocks/optional-whitespace/proof/manifest.json

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

package/dist/blocks/optional-whitespace/proof/tests.fast-check.ts

@@ -0,0 +1,20 @@
+// SPDX-License-Identifier: MIT
+// Property tests for the optional-whitespace 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:
+//   optws-none
+//   optws-space
+//   optws-tab
+//   optws-eof
+//   optws-negative
+
+// Re-export the implementation so runners importing this artifact directly
+// can access the block function.
+export * from "../impl.js";

package/dist/blocks/optional-whitespace/spec.yak

@@ -0,0 +1,76 @@
+{
+  "name": "optional-whitespace",
+  "inputs": [
+    {
+      "name": "input",
+      "type": "string",
+      "description": "The full input string."
+    },
+    {
+      "name": "position",
+      "type": "number",
+      "description": "Zero-based start position."
+    }
+  ],
+  "outputs": [
+    {
+      "name": "newPosition",
+      "type": "number",
+      "description": "Position after skipping any leading spaces or tabs."
+    }
+  ],
+  "preconditions": [],
+  "postconditions": [],
+  "invariants": [],
+  "effects": [],
+  "level": "L0",
+  "behavior": "Skip zero or more space (U+0020) or tab (U+0009) characters at position. Returns position unchanged if no whitespace is present. This is the same contract as whitespace but with an explicit name communicating optionality.",
+  "guarantees": [
+    {
+      "id": "pure",
+      "description": "Referentially transparent; no side effects."
+    },
+    {
+      "id": "monotonic",
+      "description": "Result is always >= position."
+    },
+    {
+      "id": "no-throw-on-eof",
+      "description": "Returns position unchanged when position >= input.length."
+    }
+  ],
+  "errorConditions": [
+    {
+      "description": "position < 0.",
+      "errorType": "RangeError"
+    }
+  ],
+  "nonFunctional": {
+    "time": "O(n)",
+    "space": "O(1)",
+    "purity": "pure",
+    "threadSafety": "safe"
+  },
+  "propertyTests": [
+    {
+      "id": "optws-none",
+      "description": "optionalWhitespace('abc', 0) returns 0"
+    },
+    {
+      "id": "optws-space",
+      "description": "optionalWhitespace('  x', 0) returns 2"
+    },
+    {
+      "id": "optws-tab",
+      "description": "optionalWhitespace('\\tx', 0) returns 1"
+    },
+    {
+      "id": "optws-eof",
+      "description": "optionalWhitespace('', 0) returns 0"
+    },
+    {
+      "id": "optws-negative",
+      "description": "optionalWhitespace('x', -1) throws RangeError"
+    }
+  ]
+}

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

@@ -0,0 +1,15 @@
+// SPDX-License-Identifier: MIT
+// @decision DEC-SEEDS-PEEKCHAR-001: peek-without-advance is a fundamental parser combinator primitive.
+// Status: implemented (WI-006)
+// Rationale: Many parsing decisions are made by inspecting the next character without consuming it.
+// Separating peek from consume avoids coupling lookahead to position advancement.
+
+export function peekChar(input: string, position: number): string | null {
+  if (position < 0) {
+    throw new RangeError(`Position ${position} is negative`);
+  }
+  if (position >= input.length) {
+    return null;
+  }
+  return input[position] as string;
+}

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

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

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

@@ -0,0 +1,20 @@
+// SPDX-License-Identifier: MIT
+// Property tests for the peek-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:
+//   peek-char-first
+//   peek-char-eof
+//   peek-char-negative
+//   peek-char-empty-input
+//   peek-char-last
+
+// Re-export the implementation so runners importing this artifact directly
+// can access the block function.
+export * from "../impl.js";

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

@@ -0,0 +1,76 @@
+{
+  "name": "peek-char",
+  "inputs": [
+    {
+      "name": "input",
+      "type": "string",
+      "description": "The full input string."
+    },
+    {
+      "name": "position",
+      "type": "number",
+      "description": "Zero-based position to peek at."
+    }
+  ],
+  "outputs": [
+    {
+      "name": "char",
+      "type": "string | null",
+      "description": "Character at position, or null if at end of input."
+    }
+  ],
+  "preconditions": [],
+  "postconditions": [],
+  "invariants": [],
+  "effects": [],
+  "level": "L0",
+  "behavior": "Return the character at the given position without advancing. Returns null if position is at or beyond the end of input. Throws RangeError if position is negative.",
+  "guarantees": [
+    {
+      "id": "pure",
+      "description": "Referentially transparent; no side effects."
+    },
+    {
+      "id": "no-advance",
+      "description": "Does not modify position; caller position is unchanged."
+    },
+    {
+      "id": "null-at-eof",
+      "description": "Returns null exactly when position >= input.length."
+    }
+  ],
+  "errorConditions": [
+    {
+      "description": "position < 0.",
+      "errorType": "RangeError"
+    }
+  ],
+  "nonFunctional": {
+    "time": "O(1)",
+    "space": "O(1)",
+    "purity": "pure",
+    "threadSafety": "safe"
+  },
+  "propertyTests": [
+    {
+      "id": "peek-char-first",
+      "description": "peekChar('abc', 0) returns 'a'"
+    },
+    {
+      "id": "peek-char-eof",
+      "description": "peekChar('abc', 3) returns null"
+    },
+    {
+      "id": "peek-char-negative",
+      "description": "peekChar('abc', -1) throws RangeError"
+    },
+    {
+      "id": "peek-char-empty-input",
+      "description": "peekChar('', 0) returns null"
+    },
+    {
+      "id": "peek-char-last",
+      "description": "peekChar('abc', 2) returns 'c'"
+    }
+  ]
+}

package/dist/blocks/position-step/impl.ts

@@ -0,0 +1,21 @@
+// SPDX-License-Identifier: MIT
+// @decision DEC-SEEDS-POSSTEP-001: position advancement is an explicit operation, not implicit mutation.
+// Status: implemented (WI-006)
+// Rationale: Parser blocks work with immutable position values. positionStep returns
+// the new position rather than mutating any state, keeping all blocks pure.
+
+export function positionStep(position: number, n: number, inputLength: number): number {
+  if (position < 0) {
+    throw new RangeError(`position ${position} is negative`);
+  }
+  if (n < 0) {
+    throw new RangeError(`step ${n} is negative`);
+  }
+  const next = position + n;
+  if (next > inputLength) {
+    throw new RangeError(
+      `position ${position} + step ${n} = ${next} exceeds input length ${inputLength}`,
+    );
+  }
+  return next;
+}

package/dist/blocks/position-step/proof/manifest.json

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

package/dist/blocks/position-step/proof/tests.fast-check.ts

@@ -0,0 +1,20 @@
+// SPDX-License-Identifier: MIT
+// Property tests for the position-step 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:
+//   pos-step-basic
+//   pos-step-to-end
+//   pos-step-overrun
+//   pos-step-negative-n
+//   pos-step-zero
+
+// Re-export the implementation so runners importing this artifact directly
+// can access the block function.
+export * from "../impl.js";

package/dist/blocks/position-step/spec.yak

@@ -0,0 +1,85 @@
+{
+  "name": "position-step",
+  "inputs": [
+    {
+      "name": "position",
+      "type": "number",
+      "description": "Current zero-based position."
+    },
+    {
+      "name": "n",
+      "type": "number",
+      "description": "Number of characters to advance."
+    },
+    {
+      "name": "inputLength",
+      "type": "number",
+      "description": "Total input length for bounds check."
+    }
+  ],
+  "outputs": [
+    {
+      "name": "newPosition",
+      "type": "number",
+      "description": "position + n, validated against inputLength."
+    }
+  ],
+  "preconditions": [],
+  "postconditions": [],
+  "invariants": [],
+  "effects": [],
+  "level": "L0",
+  "behavior": "Return position + n after validating that the result does not exceed inputLength. Throws RangeError if n < 0, position < 0, or position + n > inputLength.",
+  "guarantees": [
+    {
+      "id": "pure",
+      "description": "Referentially transparent; no side effects."
+    },
+    {
+      "id": "monotonic",
+      "description": "Result is always >= position when n >= 0."
+    }
+  ],
+  "errorConditions": [
+    {
+      "description": "n < 0.",
+      "errorType": "RangeError"
+    },
+    {
+      "description": "position < 0.",
+      "errorType": "RangeError"
+    },
+    {
+      "description": "position + n > inputLength.",
+      "errorType": "RangeError"
+    }
+  ],
+  "nonFunctional": {
+    "time": "O(1)",
+    "space": "O(1)",
+    "purity": "pure",
+    "threadSafety": "safe"
+  },
+  "propertyTests": [
+    {
+      "id": "pos-step-basic",
+      "description": "positionStep(0, 3, 5) returns 3"
+    },
+    {
+      "id": "pos-step-to-end",
+      "description": "positionStep(2, 3, 5) returns 5"
+    },
+    {
+      "id": "pos-step-overrun",
+      "description": "positionStep(3, 3, 5) throws RangeError"
+    },
+    {
+      "id": "pos-step-negative-n",
+      "description": "positionStep(0, -1, 5) throws RangeError"
+    },
+    {
+      "id": "pos-step-zero",
+      "description": "positionStep(2, 0, 5) returns 2"
+    }
+  ]
+}