@danmoisan/drm-copilot-mcp 1.0.21 → 1.0.23

package/resources/claude-customizations/.claude/lib/bash/parallel-cohorts.sh

@@ -0,0 +1,330 @@
+#!/usr/bin/env bash
+# parallel-cohorts.sh: sourceable bash port of
+# scripts/dev_tools/parallel_cohort_computation.py. Partitions an item-key set
+# into execution cohorts by deterministic greedy graph coloring in Welsh-Powell
+# order, and chunks one cohort into concurrency-capped batches.
+#
+# Determinism is the objective, not optimality. Every ordering decision is made
+# by an explicit numeric sort under LC_ALL=C: the Welsh-Powell visit order comes
+# from `sort -k1,1nr -k2,2n` over `<degree> <item_key>` lines, which is the
+# composite key (-degree, item_key) ascending; cohort membership and batch
+# contents come from `sort -n`. Associative arrays are used for adjacency
+# membership, degree counting, and index assignment only, and their iteration
+# order never reaches output.
+#
+# Error messages reproduce the Python module's four literal failure messages
+# byte for byte, including the tuple repr `(a, b)` with its comma and space.
+# The caller reads PCOH_ERROR after a non-zero return.
+#
+# The Python module remains the repository authority.
+#
+# shellcheck disable=SC2034
+# SC2034 is disabled file-wide because PCOH_ERROR and PCOH_RESULT are
+# written here and read by the entry points compute-cohorts.sh and
+# compute-concurrency-batches.sh, which shellcheck analyses separately.
+
+# Resolve this file's own directory so its dependencies source regardless of
+# the caller's working directory.
+PCOH_LIB_DIR=$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)
+# shellcheck source=.claude/lib/bash/parallel-common.sh
+# shellcheck disable=SC1091
+source "$PCOH_LIB_DIR/parallel-common.sh"
+
+# Adjacency membership flags keyed by `a,b`; never iterated into output.
+declare -gA PCOH_ADJACENT=()
+
+# Distinct-neighbor degree per item key; never iterated into output.
+declare -gA PCOH_DEGREE=()
+
+# Space-separated neighbor list per item key; never iterated into output.
+declare -gA PCOH_NEIGHBORS=()
+
+# Assigned cohort index per item key; never iterated into output.
+declare -gA PCOH_INDEX_OF=()
+
+# The failure message set by the most recent non-zero return.
+PCOH_ERROR=""
+
+# The compact JSON array-of-arrays produced by the most recent success.
+PCOH_RESULT=""
+
+# Scratch array populated by pcoh_split_words.
+PCOH_WORDS=()
+
+pcoh_split_words() {
+	# Populate PCOH_WORDS by splitting a space-separated string.
+	#
+	# Args: $1 = the string to split. An empty or whitespace-only string yields
+	# an empty array, which is the empty-graph and empty-cohort case. `read -ra`
+	# is used rather than an unquoted expansion so a token is never subjected to
+	# pathname expansion.
+	PCOH_WORDS=()
+	read -ra PCOH_WORDS <<<"${1-}"
+}
+
+pcoh_fail() {
+	# Record a failure message and return 1.
+	#
+	# Args: $1 = the complete, literal failure message.
+	PCOH_ERROR="$1"
+	return 1
+}
+
+pcoh_validate_item_keys() {
+	# Reject duplicate item keys, walking the supplied order.
+	#
+	# Duplicates break the uniqueness assumption behind the total-order sort
+	# key (-degree, item_key), so they are rejected rather than deduplicated.
+	#
+	# Args: $1 = space-separated item keys.
+	# Returns 0 when every key is distinct, 1 with PCOH_ERROR otherwise.
+	local key seen=""
+	pcoh_split_words "$1"
+	local -a key_items=("${PCOH_WORDS[@]}")
+	# Walk in the supplied order so the first repeat encountered is the key
+	# reported, which keeps the message stable for a given input.
+	for key in "${key_items[@]}"; do
+		if pc_contains_word "$seen" "$key"; then
+			pcoh_fail "Duplicate item key $key in item_keys; item keys must be unique because cohort ordering relies on key uniqueness."
+			return 1
+		fi
+		seen="$seen $key"
+	done
+	return 0
+}
+
+pcoh_record_edge() {
+	# Record one validated edge on both endpoints, ignoring repeats.
+	#
+	# Storing a membership flag per ordered pair normalizes the edge list by
+	# construction: an edge supplied as (a, b), as (b, a), or supplied
+	# repeatedly collapses to the same single neighbor entry on both sides.
+	#
+	# Args: $1 = first endpoint, $2 = second endpoint.
+	local first="$1" second="$2"
+	[[ -z ${PCOH_ADJACENT["$first,$second"]-} ]] || return 0
+	PCOH_ADJACENT["$first,$second"]=1
+	PCOH_ADJACENT["$second,$first"]=1
+	PCOH_NEIGHBORS["$first"]="${PCOH_NEIGHBORS["$first"]} $second"
+	PCOH_NEIGHBORS["$second"]="${PCOH_NEIGHBORS["$second"]} $first"
+	PCOH_DEGREE["$first"]=$((PCOH_DEGREE["$first"] + 1))
+	PCOH_DEGREE["$second"]=$((PCOH_DEGREE["$second"] + 1))
+}
+
+pcoh_build_adjacency() {
+	# Build symmetric adjacency, normalizing edge direction and duplicates.
+	#
+	# Args: $1 = space-separated item keys, $2 = space-separated `a:b` edges.
+	# Populates PCOH_DEGREE and PCOH_NEIGHBORS. Returns 0 on success, 1 with
+	# PCOH_ERROR when an edge is a self-loop or names an undeclared endpoint.
+	local keys="$1" key edge first second
+	PCOH_DEGREE=()
+	PCOH_NEIGHBORS=()
+	PCOH_ADJACENT=()
+	pcoh_split_words "$keys"
+	local -a key_list=("${PCOH_WORDS[@]}")
+	# Seed every declared key so an isolated vertex survives into the coloring
+	# step; inferring vertices from the edge list alone would drop it.
+	for key in "${key_list[@]}"; do
+		PCOH_DEGREE["$key"]=0
+		PCOH_NEIGHBORS["$key"]=""
+	done
+
+	pcoh_split_words "${2-}"
+	local -a edge_list=("${PCOH_WORDS[@]}")
+	# Validate then record each conflict. Validation order is part of the
+	# contract: the self-loop check precedes the endpoint-membership check, and
+	# the first endpoint is checked before the second.
+	for edge in "${edge_list[@]}"; do
+		first="${edge%%:*}"
+		second="${edge#*:}"
+		if [[ $first == "$second" ]]; then
+			pcoh_fail "Self-loop edge on item key $first; the conflict relation is defined over distinct items, so an item cannot conflict with itself."
+			return 1
+		fi
+		if ! pc_contains_word "$keys" "$first"; then
+			pcoh_fail "Conflict edge ($first, $second) names item key $first, which is not a member of item_keys; every edge endpoint must be a declared item key."
+			return 1
+		fi
+		if ! pc_contains_word "$keys" "$second"; then
+			pcoh_fail "Conflict edge ($first, $second) names item key $second, which is not a member of item_keys; every edge endpoint must be a declared item key."
+			return 1
+		fi
+		pcoh_record_edge "$first" "$second"
+	done
+	return 0
+}
+
+pcoh_welsh_powell_order() {
+	# Echo the item keys in Welsh-Powell visit order, one per line.
+	#
+	# The composite key (-degree, item_key) is a total order because item keys
+	# are unique. That is the single load-bearing determinism guard: the visit
+	# order depends on the graph alone, never on the caller's input order. The
+	# ordering is delegated to sort so no bash-side comparison logic can drift
+	# from the Python sort key.
+	#
+	# Args: $1 = space-separated item keys.
+	local key
+	pcoh_split_words "$1"
+	local -a key_items=("${PCOH_WORDS[@]}")
+	for key in "${key_items[@]}"; do
+		printf '%s %s\n' "${PCOH_DEGREE["$key"]}" "$key"
+	done | LC_ALL=C sort -k1,1nr -k2,2n | cut -d' ' -f2
+}
+
+pcoh_lowest_free_index() {
+	# Echo the smallest cohort index not held by any assigned neighbor.
+	#
+	# Args: $1 = the item key being placed.
+	local key="$1" neighbor taken="" candidate=0
+	pcoh_split_words "${PCOH_NEIGHBORS["$key"]}"
+	local -a neighbors=("${PCOH_WORDS[@]}")
+	# Collecting neighbor indices into a membership string is order
+	# insensitive, so reading the neighbor list here cannot affect the outcome.
+	for neighbor in "${neighbors[@]}"; do
+		if [[ -n ${PCOH_INDEX_OF["$neighbor"]-} ]]; then
+			taken="$taken ${PCOH_INDEX_OF["$neighbor"]}"
+		fi
+	done
+	# Scan upward from zero for the first free index. An isolated vertex and
+	# the first-visited vertex both land in cohort 0.
+	while pc_contains_word "$taken" "$candidate"; do
+		candidate=$((candidate + 1))
+	done
+	printf '%s' "$candidate"
+}
+
+pcoh_assign_cohort_indices() {
+	# Assign each vertex the lowest cohort index free among its neighbors.
+	#
+	# Args: $1 = space-separated item keys. Populates PCOH_INDEX_OF. A vertex
+	# never takes an index already held by a neighbor, so each index class is
+	# an independent set of the conflict graph.
+	local ordered key
+	PCOH_INDEX_OF=()
+	ordered=$(pcoh_welsh_powell_order "$1")
+	[[ -n $ordered ]] || return 0
+	# Visit vertices in Welsh-Powell order; each takes the smallest index its
+	# already-assigned neighbors have not taken.
+	while IFS= read -r key; do
+		[[ -n $key ]] || continue
+		PCOH_INDEX_OF["$key"]=$(pcoh_lowest_free_index "$key")
+	done <<<"$ordered"
+	return 0
+}
+
+pcoh_render_cohorts() {
+	# Echo the compact JSON array-of-arrays for the current assignment.
+	#
+	# Args: $1 = space-separated item keys. List position is the cohort index
+	# and each inner list holds that cohort's keys sorted ascending.
+	local key index highest=-1 ordered
+	pcoh_split_words "$1"
+	local -a key_items=("${PCOH_WORDS[@]}")
+	for key in "${key_items[@]}"; do
+		index="${PCOH_INDEX_OF["$key"]}"
+		((index > highest)) && highest=$index
+	done
+	if ((highest < 0)); then
+		printf '[]'
+		return 0
+	fi
+
+	local -a buckets=()
+	for ((index = 0; index <= highest; index++)); do
+		buckets+=("")
+	done
+	ordered=$(printf '%s\n' "${key_items[@]}" | LC_ALL=C sort -n)
+	# Walk the ascending key order rather than any hash order, so each cohort's
+	# keys come out ascending regardless of how the caller ordered its input.
+	while IFS= read -r key; do
+		[[ -n $key ]] || continue
+		index="${PCOH_INDEX_OF["$key"]}"
+		if [[ -z ${buckets[index]} ]]; then
+			buckets[index]="$key"
+		else
+			buckets[index]="${buckets[index]},$key"
+		fi
+	done <<<"$ordered"
+
+	local rendered=""
+	for ((index = 0; index <= highest; index++)); do
+		[[ -z $rendered ]] || rendered="$rendered,"
+		rendered="${rendered}[${buckets[index]}]"
+	done
+	printf '[%s]' "$rendered"
+}
+
+pcoh_compute_cohorts() {
+	# Partition item keys into cohorts by deterministic greedy graph coloring.
+	#
+	# Args: $1 = space-separated item keys, $2 = space-separated `a:b` edges.
+	# On success returns 0 with PCOH_RESULT holding the compact JSON output.
+	# On malformed input returns 1 with PCOH_ERROR holding the exact Python
+	# message. All validation runs before any coloring work.
+	local keys="$1" edges="${2-}"
+	PCOH_ERROR=""
+	PCOH_RESULT=""
+	pcoh_validate_item_keys "$keys" || return 1
+	pcoh_build_adjacency "$keys" "$edges" || return 1
+	pcoh_assign_cohort_indices "$keys"
+	PCOH_RESULT=$(pcoh_render_cohorts "$keys")
+	return 0
+}
+
+pcoh_compute_concurrency_batches() {
+	# Chunk one cohort into concurrency-capped batches in ascending key order.
+	#
+	# The cohort's keys are sorted inside this function rather than trusting
+	# the caller's ordering, so determinism does not depend on caller
+	# discipline. Every batch is exactly max_concurrency long except a possibly
+	# smaller final batch.
+	#
+	# Args: $1 = space-separated cohort item keys, $2 = the fan-out cap.
+	# On success returns 0 with PCOH_RESULT holding the compact JSON output;
+	# on a cap below 1 returns 1 with PCOH_ERROR holding the exact message.
+	local cap="$2" key sorted
+	PCOH_ERROR=""
+	PCOH_RESULT=""
+	# A cap below 1 would admit no items into any batch, so the cohort could
+	# never drain; reject it rather than returning an unusable schedule.
+	if ((cap < 1)); then
+		pcoh_fail "max_concurrency must be >= 1; received $cap."
+		return 1
+	fi
+
+	pcoh_split_words "$1"
+	local -a supplied=("${PCOH_WORDS[@]}")
+	local -a ordered=()
+	if ((${#supplied[@]} > 0)); then
+		sorted=$(printf '%s\n' "${supplied[@]}" | LC_ALL=C sort -n)
+		while IFS= read -r key; do
+			[[ -n $key ]] || continue
+			ordered+=("$key")
+		done <<<"$sorted"
+	fi
+
+	local total=${#ordered[@]}
+	if ((total == 0)); then
+		PCOH_RESULT="[]"
+		return 0
+	fi
+
+	local start end position rendered="" batch
+	# Walk the sorted keys in fixed-size strides so slot filling follows
+	# ascending key order and the batch boundaries are reproducible.
+	for ((start = 0; start < total; start += cap)); do
+		end=$((start + cap))
+		((end > total)) && end=$total
+		batch=""
+		for ((position = start; position < end; position++)); do
+			[[ -z $batch ]] || batch="$batch,"
+			batch="$batch${ordered[position]}"
+		done
+		[[ -z $rendered ]] || rendered="$rendered,"
+		rendered="${rendered}[$batch]"
+	done
+	PCOH_RESULT="[$rendered]"
+	return 0
+}

package/resources/claude-customizations/.claude/lib/bash/parallel-common.sh

@@ -0,0 +1,238 @@
+#!/usr/bin/env bash
+# parallel-common.sh: sourceable bash port of the shared predicates, enum
+# vocabularies, and error-string builders that back the parallel-surface
+# validators. This is the bash counterpart of
+# scripts/dev_tools/_parallel_state_common.py; the Python module remains the
+# repository authority and this file must reproduce its output byte for byte.
+#
+# Scope. Pure string and arithmetic helpers only: nothing here reads a file,
+# starts a process, reads the clock, or mutates global state other than the
+# PC_ERRORS accumulator its own reset/add functions own. The enum tuples are
+# consumed from .claude/rules/parallel-orchestration.md and are never extended
+# here; member order is load-bearing because pc_enum_error renders it.
+#
+# Locale. Every entry point that sources this file calls pc_enforce_c_locale
+# before doing any work, so sorting and character classification are byte
+# ordered and independent of the destination workspace's environment.
+#
+# shellcheck disable=SC2034
+# SC2034 is disabled file-wide because every constant below is consumed by a
+# sibling file of this library -- parallel-items-validate.sh,
+# parallel-manifest-validate.sh, and parallel-cohorts.sh -- which shellcheck
+# analyses separately and therefore cannot see the use.
+
+# Item lifecycle states, in canonical order (schema S4).
+PC_VALID_ITEM_STATES="proposed, admitted, prepared, scheduled, in_flight, merged, withdrawn, blocked"
+
+# Per-item merge lifecycle, in canonical order (schema S4).
+PC_VALID_MERGE_STATUS="not_started, worktree_created, pr_open, ci_green, merged, worktree_removed, blocked_drift, blocked_ci_loop_limit"
+
+# Blast-radius confidence sources, in canonical order (schema S4).
+PC_VALID_SOURCES="derived, declared, observed"
+
+# Work-item kinds carried by the manifest (schema S4).
+PC_VALID_KINDS="feature, bug"
+
+# Run modes; closed is the documented default (schema S4).
+PC_VALID_MODES="closed, open"
+
+# Merge-status values meaning the item reached a terminal merged outcome.
+PC_MERGED_MERGE_STATUSES="merged worktree_removed"
+
+# Merge-status values meaning the item is blocked.
+PC_BLOCKED_MERGE_STATUSES="blocked_drift blocked_ci_loop_limit"
+
+# The four blast_radius collection fields, in serialization order.
+PC_BLAST_RADIUS_LIST_FIELDS="paths modules shared_surfaces contracts"
+
+# Path label for the document root in prohibited-key error strings.
+PC_ROOT_PATH="<root>"
+
+# Accumulated validation errors, in emission order.
+PC_ERRORS=()
+
+pc_enforce_c_locale() {
+	# Pin the byte-ordered C locale for the remainder of the process.
+	#
+	# Determinism countermeasure R9: every numeric sort, glob expansion, and
+	# character class in this library must behave identically regardless of the
+	# destination workspace's locale settings.
+	export LC_ALL=C
+}
+
+pc_errors_reset() {
+	# Discard any accumulated errors so a fresh validation starts empty.
+	PC_ERRORS=()
+}
+
+pc_error_add() {
+	# Append one error string to the accumulator.
+	#
+	# Args: $1 = the complete error string, already fully rendered.
+	PC_ERRORS+=("$1")
+}
+
+pc_errors_count() {
+	# Echo the number of accumulated errors.
+	printf '%s' "${#PC_ERRORS[@]}"
+}
+
+pc_errors_print() {
+	# Print every accumulated error, one per line, in emission order.
+	#
+	# Prints nothing for an empty accumulator, which is the valid-artifact case.
+	((${#PC_ERRORS[@]} > 0)) || return 0
+	local entry
+	# Emit in accumulation order: message sequence is part of the parity
+	# contract, so the accumulator is never sorted or de-duplicated.
+	for entry in "${PC_ERRORS[@]}"; do
+		printf '%s\n' "$entry"
+	done
+}
+
+pc_repr_string() {
+	# Echo the Python repr of a string, including Python's quote selection.
+	#
+	# Python prefers single quotes and switches to double quotes only when the
+	# string contains a single quote and no double quote. Backslashes are
+	# escaped first so a later escape's own backslash is not doubled, then the
+	# three printable control escapes, then the active quote character.
+	#
+	# Args: $1 = the raw string value.
+	local value="$1"
+	local quote="'"
+	# Quote selection: only a string carrying an apostrophe but no double quote
+	# switches Python to double quotes.
+	if [[ $value == *"'"* && $value != *'"'* ]]; then
+		quote='"'
+	fi
+	local body=${value//\\/\\\\}
+	body=${body//$'\n'/\\n}
+	body=${body//$'\r'/\\r}
+	body=${body//$'\t'/\\t}
+	# Escape whichever quote is active. Under double quoting the escape is a
+	# no-op by the selection rule above; under single quoting it fires only for
+	# a string that carries both quote characters.
+	if [[ $quote == "'" ]]; then
+		body=${body//\'/\\\'}
+	else
+		body=${body//\"/\\\"}
+	fi
+	printf '%s%s%s' "$quote" "$body" "$quote"
+}
+
+pc_repr() {
+	# Echo the Python repr of a lexically typed value.
+	#
+	# Args: $1 = type tag (absent, null, bool, int, float, str), $2 = raw value.
+	# An absent key reads as None, matching Python's mapping.get default.
+	local type="$1"
+	local value="${2-}"
+	# Routing table: the five scalar types the manifest subset can carry, plus
+	# the absent-key case that Python renders as None.
+	case "$type" in
+	absent | null)
+		printf 'None'
+		;;
+	bool)
+		if [[ $value == true ]]; then
+			printf 'True'
+		else
+			printf 'False'
+		fi
+		;;
+	int | float)
+		printf '%s' "$value"
+		;;
+	str)
+		pc_repr_string "$value"
+		;;
+	*)
+		# A container reaching repr would be a caller defect; render the tag so
+		# the failure is visible rather than silently producing a bare value.
+		printf '<%s>' "$type"
+		;;
+	esac
+}
+
+pc_is_non_empty_string() {
+	# Return 0 when a typed value is a string carrying a non-space character.
+	#
+	# Args: $1 = type tag, $2 = raw value. Mirrors is_non_empty_string.
+	[[ $1 == str ]] || return 1
+	local stripped="${2-}"
+	# A left strip is sufficient: a value that is entirely whitespace becomes
+	# empty, which is exactly what Python's two-sided strip would report.
+	stripped=${stripped#"${stripped%%[![:space:]]*}"}
+	[[ -n $stripped ]]
+}
+
+pc_is_integer() {
+	# Return 0 when a typed value is a genuine integer rather than a boolean.
+	#
+	# Args: $1 = type tag. The parser classifies booleans as `bool`, never as
+	# `int`, so the boolean exclusion that Python needs is structural here.
+	[[ $1 == int ]]
+}
+
+pc_is_positive_integer() {
+	# Return 0 when a typed value is an integer greater than zero.
+	#
+	# Args: $1 = type tag, $2 = raw value.
+	[[ $1 == int ]] || return 1
+	local number="$2"
+	((number > 0))
+}
+
+pc_is_non_negative_integer() {
+	# Return 0 when a typed value is an integer of zero or more.
+	#
+	# Args: $1 = type tag, $2 = raw value.
+	[[ $1 == int ]] || return 1
+	local number="$2"
+	((number >= 0))
+}
+
+pc_in_bounded_range() {
+	# Return 0 when a typed value is an integer inside an inclusive range.
+	#
+	# Args: $1 = type tag, $2 = raw value, $3 = minimum, $4 = maximum.
+	[[ $1 == int ]] || return 1
+	local number="$2" minimum="$3" maximum="$4"
+	((number >= minimum && number <= maximum))
+}
+
+pc_enum_error() {
+	# Echo the standard out-of-enum error string for a field.
+	#
+	# Args: $1 = context prefix, $2 = dotted field name, $3 = comma-and-space
+	# joined member list in canonical order, $4 = the already-rendered repr of
+	# the offending value. Mirrors enum_error so the wording cannot drift.
+	printf '%s %s must be one of %s; found: %s.' "$1" "$2" "$3" "$4"
+}
+
+pc_item_context() {
+	# Echo the context prefix for one items[] entry.
+	#
+	# Args: $1 = surface prefix, $2 = zero-based entry index. The positional
+	# index is used rather than issue_num because it exists for every entry,
+	# including one whose issue_num is missing.
+	printf '%s items[%s]' "$1" "$2"
+}
+
+pc_contains_word() {
+	# Return 0 when a space-separated list contains an exact word.
+	#
+	# Args: $1 = space-separated haystack, $2 = needle. Used for the enum
+	# membership tests whose member lists are stored space separated.
+	local haystack=" $1 "
+	[[ $haystack == *" $2 "* ]]
+}
+
+pc_enum_members_contains() {
+	# Return 0 when a comma-and-space joined enum list contains an exact member.
+	#
+	# Args: $1 = the rendered member list, $2 = candidate member.
+	local haystack="${1//, / }"
+	pc_contains_word "$haystack" "$2"
+}