@yakcc/cli 0.5.0-alpha.0

package/dist/blocks/queue-drain/impl.ts

@@ -0,0 +1,74 @@
+// SPDX-License-Identifier: MIT
+//
+// @decision DEC-V0-B4-SEED-queue-drain-001
+// @title queue-drain: BFS drain primitive for Kahn's topological sort
+// @status accepted
+// @rationale
+//   The dependency-resolver B4 task requires a topological sort as its core
+//   algorithm. Kahn's algorithm (1962) is the standard BFS-based approach:
+//   maintain a queue of zero-in-degree nodes, drain it while decrementing
+//   successor in-degrees, enqueue newly-zero successors. This atom is the
+//   inner drain loop, extracted so the caller handles initialisation (computing
+//   initial in-degrees and seeding the queue with zero-in-degree nodes).
+//
+//   Design decisions:
+//   (A) MUTATION CONTRACT: queue, inDegree are mutated in-place. The caller
+//       owns these data structures and passes them in. This avoids allocating
+//       a copy of potentially large structures inside the atom, keeping the
+//       space complexity O(1) additional beyond what the caller already holds.
+//
+//   (B) CALLBACK VISITOR: onVisit is a callback rather than accumulating a
+//       result array. This lets callers choose their own output structure
+//       (array push, string concat, direct emit) without forcing an allocation
+//       inside the atom. It also makes the atom composable with streaming
+//       consumers.
+//
+//   (C) VISIT COUNT RETURN: Returning visitCount rather than a boolean lets the
+//       caller determine whether a cycle exists (visitCount < |V|) AND how many
+//       nodes were processed, both of which may be useful.
+//
+//   (D) ADJACENCY MAP OPTIONAL LOOKUP: adjacency.get(node) may return undefined
+//       if the node has no outgoing edges. The guard `?? []` handles this
+//       without requiring every leaf node to have an explicit empty-array entry.
+//
+//   Reference: Kahn, A.B. (1962). "Topological sorting of large networks."
+//   Communications of the ACM, 5(11), 558-562.
+
+/**
+ * Drain a BFS queue using Kahn's topological sort algorithm.
+ *
+ * Processes every node currently in queue and any nodes whose in-degree drops
+ * to zero as a result. Mutates both queue and inDegree in-place.
+ *
+ * @param queue     - Initial zero-in-degree nodes. Consumed and extended in-place.
+ * @param inDegree  - In-degree for every node. Decremented as predecessors are visited.
+ * @param adjacency - Outgoing neighbour lists. Missing entries treated as empty.
+ * @param onVisit   - Called once per visited node in topological order.
+ * @returns Number of nodes visited. Less than |V| iff the graph has a cycle.
+ */
+export function queueDrain(
+  queue: string[],
+  inDegree: Map<string, number>,
+  adjacency: Map<string, string[]>,
+  onVisit: (node: string) => void,
+): number {
+  let visitCount = 0;
+
+  while (queue.length > 0) {
+    // shift() removes from the front -- FIFO BFS order
+    const node = queue.shift() as string;
+    onVisit(node);
+    visitCount++;
+
+    const neighbours = adjacency.get(node) ?? [];
+    for (const v of neighbours) {
+      const deg = (inDegree.get(v) ?? 0) - 1;
+      inDegree.set(v, deg);
+      if (deg === 0) {
+        queue.push(v);
+      }
+    }
+  }
+
+  return visitCount;
+}

package/dist/blocks/queue-drain/proof/manifest.json

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

package/dist/blocks/queue-drain/proof/tests.fast-check.ts

@@ -0,0 +1,16 @@
+// SPDX-License-Identifier: MIT
+// Property tests for the queue-drain block.
+// These tests exercise the contract declared in ../spec.yak against the
+// implementation in ../impl.ts.
+//
+// Test IDs declared in spec.yak:
+//   queue-drain-linear
+//   queue-drain-empty
+//   queue-drain-single
+//   queue-drain-diamond
+//   queue-drain-cycle-detected
+//   queue-drain-parallel
+
+// Re-export implementation so runners importing this artifact directly
+// can access the block functions.
+export * from "../impl.js";

package/dist/blocks/queue-drain/spec.yak

@@ -0,0 +1,119 @@
+{
+  "name": "queue-drain",
+  "inputs": [
+    {
+      "name": "queue",
+      "type": "string[]",
+      "description": "Mutable queue of node IDs to process. Consumed (shifted) in-place during the drain."
+    },
+    {
+      "name": "inDegree",
+      "type": "Map<string, number>",
+      "description": "Mutable in-degree map. Each processed node decrements successors; nodes reaching zero are enqueued."
+    },
+    {
+      "name": "adjacency",
+      "type": "Map<string, string[]>",
+      "description": "Adjacency list: adjacency.get(u) is the list of nodes that u points to (u -> v edges)."
+    },
+    {
+      "name": "onVisit",
+      "type": "(node: string) => void",
+      "description": "Called in topological order as each node is dequeued."
+    }
+  ],
+  "outputs": [
+    {
+      "name": "visitCount",
+      "type": "number",
+      "description": "Number of nodes visited. If visitCount < total nodes in graph, a cycle was detected."
+    }
+  ],
+  "preconditions": [
+    {
+      "description": "queue contains all nodes with initial in-degree 0."
+    },
+    {
+      "description": "inDegree maps every node in the graph to its current in-degree."
+    },
+    {
+      "description": "adjacency maps every node to its outgoing neighbour list (may be empty or absent)."
+    }
+  ],
+  "postconditions": [
+    {
+      "description": "queue is empty after the call."
+    },
+    {
+      "description": "onVisit was called once per visited node, in topological order."
+    },
+    {
+      "description": "visitCount equals the number of onVisit calls made."
+    }
+  ],
+  "invariants": [
+    {
+      "description": "A node is enqueued at most once (inDegree reaches 0 at most once per node)."
+    }
+  ],
+  "effects": [
+    {
+      "description": "Mutates queue (shifts elements, pushes newly-zero nodes)."
+    },
+    {
+      "description": "Mutates inDegree (decrements successor counts)."
+    },
+    {
+      "description": "Calls onVisit for each dequeued node."
+    }
+  ],
+  "level": "L0",
+  "behavior": "Drain the BFS queue using Kahn's algorithm for topological sort. While the queue is non-empty: dequeue the front node, call onVisit(node), then for each successor v in adjacency.get(node): decrement inDegree[v]; if inDegree[v] reaches 0, push v onto the queue. Return the total visit count. If the graph has a cycle, some nodes never reach in-degree 0 and visitCount will be less than the total node count.",
+  "guarantees": [
+    {
+      "id": "kahn-correct",
+      "description": "Produces a valid topological ordering for DAGs (Kahn 1962)."
+    },
+    {
+      "id": "cycle-detectable",
+      "description": "visitCount < |V| iff the graph contains at least one cycle."
+    },
+    {
+      "id": "each-node-once",
+      "description": "onVisit is called at most once per node."
+    }
+  ],
+  "errorConditions": [],
+  "nonFunctional": {
+    "time": "O(V + E) where V is vertices and E is edges",
+    "space": "O(1) additional (mutates caller-supplied structures)",
+    "purity": "impure (mutates queue, inDegree; calls onVisit)",
+    "threadSafety": "safe (single-threaded JS)"
+  },
+  "propertyTests": [
+    {
+      "id": "queue-drain-linear",
+      "description": "Linear chain A->B->C visits all 3 nodes in order A, B, C"
+    },
+    {
+      "id": "queue-drain-empty",
+      "description": "Empty queue returns visitCount 0 and calls onVisit zero times"
+    },
+    {
+      "id": "queue-drain-single",
+      "description": "Single node with no edges visits that node and returns 1"
+    },
+    {
+      "id": "queue-drain-diamond",
+      "description": "Diamond DAG visits all 4 nodes, visitCount === 4"
+    },
+    {
+      "id": "queue-drain-cycle-detected",
+      "description": "Graph with a cycle produces visitCount < total nodes"
+    },
+    {
+      "id": "queue-drain-parallel",
+      "description": "Two independent chains each process correctly (visitCount === total)"
+    }
+  ]
+}

package/dist/blocks/semver-component-parser/impl.ts

@@ -0,0 +1,115 @@
+// SPDX-License-Identifier: MIT
+//
+// @decision DEC-V0-B4-SEED-semver-component-parser-001
+// @title semver-component-parser: version-string parser for MAJOR.MINOR.PATCH[-pre][+build]
+// @status accepted
+// @rationale
+//   The semver-range-satisfies B4 task requires parsing version strings into
+//   their numeric and string components before any range comparison. This atom
+//   implements the parsing primitive so the range-comparison logic can operate
+//   on structured data rather than raw strings.
+//
+//   Design decisions:
+//   (A) SPLIT THEN PARSE: The implementation splits the input string rather
+//       than using a hand-rolled character-position parser. The split approach
+//       is more readable and the O(n) allocation cost is acceptable for version
+//       strings, which are short (typically < 30 chars). A position-based
+//       parser would save zero allocations in practice at the cost of
+//       significant code complexity.
+//
+//   (B) BUILD BEFORE PRERELEASE: The '+' (build metadata) separator is handled
+//       AFTER splitting on '-' (prerelease). If the patch field contains '+',
+//       we split again. This correctly handles '1.0.0-beta+sha' where '-beta'
+//       is prerelease and 'sha' is build metadata appended to the patch field.
+//       Order matters: split on '-' first, then on '+'.
+//
+//   (C) NO SEMANTIC VALIDATION OF IDENTIFIERS: Prerelease and build identifier
+//       characters are not validated (the spec only requires capturing them as
+//       strings). Full validation per semver.org spec section 9-10 would add
+//       complexity without benefit for the B4 task's comparator use-case.
+//
+//   (D) EXPLICIT GUARD FOR ARRAY INDEXING: After verifying parts.length === 3
+//       via SyntaxError throw, TypeScript still types parts[n] as
+//       string | undefined. We use explicit string coercion ("" fallback via
+//       ?? "") to satisfy the type checker while maintaining the invariant
+//       that the value is always defined at this point in the code.
+//
+//   Reference: Semantic Versioning 2.0.0 specification (semver.org),
+//   sections 2-10. Tom Preston-Werner, original author.
+
+/** Parsed components of a semver version string. */
+export interface SemverComponents {
+  readonly major: number;
+  readonly minor: number;
+  readonly patch: number;
+  readonly prerelease: string | null;
+  readonly build: string | null;
+}
+
+/**
+ * Parse a semver version string into its numeric and string components.
+ *
+ * Handles the full MAJOR.MINOR.PATCH[-PRERELEASE][+BUILD] grammar.
+ * Prerelease and build identifiers are captured as raw strings without
+ * further validation.
+ *
+ * @param input - Version string to parse.
+ * @returns Parsed SemverComponents.
+ * @throws SyntaxError if input does not match MAJOR.MINOR.PATCH structure.
+ */
+export function parseSemver(input: string): SemverComponents {
+  if (input.length === 0) {
+    throw new SyntaxError("parseSemver: empty input");
+  }
+
+  // Separate prerelease suffix (everything after first '-')
+  let prerelease: string | null = null;
+  let build: string | null = null;
+
+  // Find build metadata first ('+' in the original string)
+  const plusIndex = input.indexOf("+");
+  let versionWithPre = input;
+  if (plusIndex !== -1) {
+    build = input.slice(plusIndex + 1);
+    versionWithPre = input.slice(0, plusIndex);
+  }
+
+  // Find prerelease ('-' in the version-without-build string)
+  const dashIndex = versionWithPre.indexOf("-");
+  let coreVersion = versionWithPre;
+  if (dashIndex !== -1) {
+    prerelease = versionWithPre.slice(dashIndex + 1);
+    coreVersion = versionWithPre.slice(0, dashIndex);
+  }
+
+  // Parse MAJOR.MINOR.PATCH
+  const parts = coreVersion.split(".");
+  if (parts.length !== 3) {
+    throw new SyntaxError(
+      `parseSemver: expected MAJOR.MINOR.PATCH, got ${JSON.stringify(coreVersion)}`,
+    );
+  }
+
+  // After the length guard above, parts[0..2] are always defined.
+  // The ?? "" fallback satisfies TypeScript's string | undefined narrowing
+  // while being unreachable in practice.
+  const majorStr = parts[0] ?? "";
+  const minorStr = parts[1] ?? "";
+  const patchStr = parts[2] ?? "";
+
+  const major = Number.parseInt(majorStr, 10);
+  const minor = Number.parseInt(minorStr, 10);
+  const patch = Number.parseInt(patchStr, 10);
+
+  if (Number.isNaN(major) || major < 0) {
+    throw new SyntaxError(`parseSemver: invalid MAJOR component ${JSON.stringify(majorStr)}`);
+  }
+  if (Number.isNaN(minor) || minor < 0) {
+    throw new SyntaxError(`parseSemver: invalid MINOR component ${JSON.stringify(minorStr)}`);
+  }
+  if (Number.isNaN(patch) || patch < 0) {
+    throw new SyntaxError(`parseSemver: invalid PATCH component ${JSON.stringify(patchStr)}`);
+  }
+
+  return { major, minor, patch, prerelease, build };
+}

package/dist/blocks/semver-component-parser/proof/manifest.json

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

package/dist/blocks/semver-component-parser/proof/tests.fast-check.ts

@@ -0,0 +1,19 @@
+// SPDX-License-Identifier: MIT
+// Property tests for the semver-component-parser block.
+// These tests exercise the contract declared in ../spec.yak against the
+// implementation in ../impl.ts.
+//
+// Test IDs declared in spec.yak:
+//   semver-simple
+//   semver-prerelease
+//   semver-build
+//   semver-prerelease-and-build
+//   semver-zeros
+//   semver-large-numbers
+//   semver-invalid-no-dots
+//   semver-invalid-non-numeric
+//   semver-empty
+
+// Re-export implementation so runners importing this artifact directly
+// can access the block functions.
+export * from "../impl.js";

package/dist/blocks/semver-component-parser/spec.yak

@@ -0,0 +1,109 @@
+{
+  "name": "semver-component-parser",
+  "inputs": [
+    {
+      "name": "input",
+      "type": "string",
+      "description": "A semver version string of the form MAJOR.MINOR.PATCH[-PRERELEASE][+BUILD]."
+    }
+  ],
+  "outputs": [
+    {
+      "name": "result",
+      "type": "{ major: number; minor: number; patch: number; prerelease: string | null; build: string | null }",
+      "description": "Parsed semver components. prerelease is null when no '-' suffix is present. build is null when no '+' suffix is present."
+    }
+  ],
+  "preconditions": [],
+  "postconditions": [
+    {
+      "description": "result.major >= 0 and is the integer parsed from the MAJOR field."
+    },
+    {
+      "description": "result.minor >= 0 and is the integer parsed from the MINOR field."
+    },
+    {
+      "description": "result.patch >= 0 and is the integer parsed from the PATCH field (before any pre-release or build suffix)."
+    }
+  ],
+  "invariants": [],
+  "effects": [],
+  "level": "L0",
+  "behavior": "Parse a semver version string into its numeric components (major, minor, patch) and optional string suffixes (prerelease, build). Parsing stops at the first '-' for prerelease and the first '+' for build metadata. No semantic validation of prerelease or build identifiers is performed -- they are captured as raw strings. Throws SyntaxError for strings that do not match the MAJOR.MINOR.PATCH structure.",
+  "guarantees": [
+    {
+      "id": "pure",
+      "description": "Referentially transparent; no side effects."
+    },
+    {
+      "id": "numeric-components",
+      "description": "major, minor, patch are non-negative integers parsed from the first three dot-separated fields."
+    },
+    {
+      "id": "prerelease-captured",
+      "description": "prerelease is the raw string after the first '-' and before any '+'; null if absent."
+    },
+    {
+      "id": "build-captured",
+      "description": "build is the raw string after the first '+'; null if absent."
+    }
+  ],
+  "errorConditions": [
+    {
+      "description": "Input does not contain exactly two dots in the MAJOR.MINOR.PATCH prefix (e.g. '1.2' or '1.2.3.4').",
+      "errorType": "SyntaxError"
+    },
+    {
+      "description": "MAJOR, MINOR, or PATCH component is not a non-negative integer.",
+      "errorType": "SyntaxError"
+    },
+    {
+      "description": "Input is an empty string.",
+      "errorType": "SyntaxError"
+    }
+  ],
+  "nonFunctional": {
+    "time": "O(n) where n is input.length",
+    "space": "O(n) for substrings",
+    "purity": "pure",
+    "threadSafety": "safe"
+  },
+  "propertyTests": [
+    {
+      "id": "semver-simple",
+      "description": "parseSemver('1.2.3') returns { major:1, minor:2, patch:3, prerelease:null, build:null }"
+    },
+    {
+      "id": "semver-prerelease",
+      "description": "parseSemver('1.0.0-alpha.1') returns prerelease 'alpha.1'"
+    },
+    {
+      "id": "semver-build",
+      "description": "parseSemver('1.0.0+build.42') returns build 'build.42'"
+    },
+    {
+      "id": "semver-prerelease-and-build",
+      "description": "parseSemver('1.2.3-beta+exp.sha.5114f85') captures both prerelease and build"
+    },
+    {
+      "id": "semver-zeros",
+      "description": "parseSemver('0.0.0') returns { major:0, minor:0, patch:0, prerelease:null, build:null }"
+    },
+    {
+      "id": "semver-large-numbers",
+      "description": "parseSemver('100.200.300') returns major=100, minor=200, patch=300"
+    },
+    {
+      "id": "semver-invalid-no-dots",
+      "description": "parseSemver('1') throws SyntaxError"
+    },
+    {
+      "id": "semver-invalid-non-numeric",
+      "description": "parseSemver('a.b.c') throws SyntaxError"
+    },
+    {
+      "id": "semver-empty",
+      "description": "parseSemver('') throws SyntaxError"
+    }
+  ]
+}

package/dist/blocks/signed-integer/impl.ts

@@ -0,0 +1,40 @@
+// SPDX-License-Identifier: MIT
+// @decision DEC-SEEDS-SIGNEDINT-001: signed-integer extends integer with optional leading minus.
+// Status: implemented (WI-006)
+// Rationale: A common extension of unsigned integer parsing. Demonstrates contract refinement:
+// signed-integer has a strictly wider input domain than integer but same output type contract.
+
+export function signedInteger(input: string, position: number): readonly [number, number] {
+  if (position < 0) {
+    throw new RangeError(`Position ${position} is negative`);
+  }
+  if (position >= input.length) {
+    throw new SyntaxError(`Expected digit or '-' at position ${position} but reached end of input`);
+  }
+
+  let pos = position;
+  let sign = 1;
+
+  if (input[pos] === "-") {
+    sign = -1;
+    pos++;
+    if (pos >= input.length) {
+      throw new SyntaxError(`Expected digit after '-' at position ${pos} but reached end of input`);
+    }
+  }
+
+  const c = input[pos] as string;
+  if (c < "0" || c > "9") {
+    throw new SyntaxError(`Expected digit at position ${pos} but found ${JSON.stringify(c)}`);
+  }
+
+  let value = 0;
+  while (pos < input.length) {
+    const ch = input[pos] as string;
+    if (ch < "0" || ch > "9") break;
+    value = value * 10 + (ch.charCodeAt(0) - 48);
+    pos++;
+  }
+
+  return [sign * value, pos] as const;
+}

package/dist/blocks/signed-integer/proof/manifest.json

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

package/dist/blocks/signed-integer/proof/tests.fast-check.ts

@@ -0,0 +1,21 @@
+// SPDX-License-Identifier: MIT
+// Property tests for the signed-integer 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:
+//   signed-int-positive
+//   signed-int-negative
+//   signed-int-bare-minus
+//   signed-int-no-digit
+//   signed-int-eof
+//   signed-int-negative-pos
+
+// Re-export the implementation so runners importing this artifact directly
+// can access the block function.
+export * from "../impl.js";

package/dist/blocks/signed-integer/spec.yak

@@ -0,0 +1,84 @@
+{
+  "name": "signed-integer",
+  "inputs": [
+    {
+      "name": "input",
+      "type": "string",
+      "description": "The full input string."
+    },
+    {
+      "name": "position",
+      "type": "number",
+      "description": "Zero-based start position."
+    }
+  ],
+  "outputs": [
+    {
+      "name": "result",
+      "type": "readonly [number, number]",
+      "description": "[parsedValue, newPosition] where parsedValue may be negative."
+    }
+  ],
+  "preconditions": [],
+  "postconditions": [],
+  "invariants": [],
+  "effects": [],
+  "level": "L0",
+  "behavior": "Parse an optional '-' sign followed by one or more decimal digits. Returns [value, newPosition]. A bare '-' with no digits throws SyntaxError. Negative zero is represented as 0.",
+  "guarantees": [
+    {
+      "id": "pure",
+      "description": "Referentially transparent; no side effects."
+    },
+    {
+      "id": "greedy",
+      "description": "Consumes as many digits as possible after the optional sign."
+    }
+  ],
+  "errorConditions": [
+    {
+      "description": "No digit follows an optional '-' sign.",
+      "errorType": "SyntaxError"
+    },
+    {
+      "description": "No digit or '-' found at position.",
+      "errorType": "SyntaxError"
+    },
+    {
+      "description": "position < 0.",
+      "errorType": "RangeError"
+    }
+  ],
+  "nonFunctional": {
+    "time": "O(n)",
+    "space": "O(1)",
+    "purity": "pure",
+    "threadSafety": "safe"
+  },
+  "propertyTests": [
+    {
+      "id": "signed-int-positive",
+      "description": "signedInteger('42', 0) returns [42, 2]"
+    },
+    {
+      "id": "signed-int-negative",
+      "description": "signedInteger('-7', 0) returns [-7, 2]"
+    },
+    {
+      "id": "signed-int-bare-minus",
+      "description": "signedInteger('-x', 0) throws SyntaxError"
+    },
+    {
+      "id": "signed-int-no-digit",
+      "description": "signedInteger('abc', 0) throws SyntaxError"
+    },
+    {
+      "id": "signed-int-eof",
+      "description": "signedInteger('', 0) throws SyntaxError"
+    },
+    {
+      "id": "signed-int-negative-pos",
+      "description": "signedInteger('1', -1) throws RangeError"
+    }
+  ]
+}

package/dist/blocks/string-from-position/impl.ts

@@ -0,0 +1,18 @@
+// SPDX-License-Identifier: MIT
+// @decision DEC-SEEDS-STRFROMPOS-001: substring extraction at a position is a reusable primitive.
+// Status: implemented (WI-006)
+// Rationale: Multiple blocks need to extract substrings starting at a position. Centralising
+// bounds checking avoids each block duplicating the same guard logic.
+
+export function stringFromPosition(input: string, start: number, end: number): string {
+  if (start < 0 || end < 0) {
+    throw new RangeError(`Negative index: start=${start}, end=${end}`);
+  }
+  if (start > end) {
+    throw new RangeError(`start ${start} > end ${end}`);
+  }
+  if (end > input.length) {
+    throw new RangeError(`end ${end} exceeds input length ${input.length}`);
+  }
+  return input.slice(start, end);
+}

package/dist/blocks/string-from-position/proof/manifest.json

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