@danmoisan/drm-copilot-mcp 1.0.21 → 1.0.23

package/resources/claude-customizations/.claude/lib/bash/parallel-items-validate.sh

@@ -0,0 +1,244 @@
+#!/usr/bin/env bash
+# parallel-items-validate.sh: sourceable bash port of the shared work-item
+# validators in scripts/dev_tools/_parallel_state_common.py -- validate_items,
+# validate_item_record, _validate_merge_status, and validate_blast_radius_block.
+# It reads the node table populated by parallel-yaml-emit.sh and appends errors
+# to the PC_ERRORS accumulator owned by parallel-common.sh.
+#
+# Message order is part of the contract, not an implementation detail. Within
+# one item the order is issue_num, feature_folder, state, kind (when required),
+# merge_status, then the blast-radius block in field order. Across items the
+# order is positional, and every duplicate issue_num is reported after the
+# whole per-entry pass, in ascending key order, so the sequence is reproducible
+# regardless of the order the entries appeared in.
+#
+# The Python module remains the repository authority; this file must reproduce
+# its output byte for byte for every fixture in tests/fixtures/parallel_manifest_bash.
+
+# Resolve this file's own directory so its dependencies source regardless of
+# the caller's working directory.
+PI_LIB_DIR=$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)
+# shellcheck source=.claude/lib/bash/parallel-common.sh
+# shellcheck disable=SC1091
+source "$PI_LIB_DIR/parallel-common.sh"
+# shellcheck source=.claude/lib/bash/parallel-yaml-emit.sh
+# shellcheck disable=SC1091
+source "$PI_LIB_DIR/parallel-yaml-emit.sh"
+
+pi_repr_at() {
+	# Echo the Python repr of the value stored at a node path.
+	#
+	# Args: $1 = node path. An unknown path renders as None, matching the
+	# Python code's mapping.get default.
+	local path="$1" type value
+	type=$(yp_type_of "$path")
+	value=$(yp_value_of "$path")
+	pc_repr "$type" "$value"
+}
+
+pi_is_string_list() {
+	# Return 0 when a node is a sequence whose every entry is a non-empty string.
+	#
+	# An empty sequence satisfies the predicate: every blast-radius collection
+	# other than paths is legitimately empty. Mirrors is_string_list.
+	#
+	# Args: $1 = node path.
+	local path="$1"
+	[[ $(yp_type_of "$path") == seq ]] || return 1
+	local count index entry_type entry_value
+	count=$(yp_count_of "$path")
+	# A single blank entry fails the whole list, because it would silently
+	# widen a radius and under-report contention.
+	for ((index = 0; index < count; index++)); do
+		entry_type=$(yp_type_of "${path}[${index}]")
+		entry_value=$(yp_value_of "${path}[${index}]")
+		pc_is_non_empty_string "$entry_type" "$entry_value" || return 1
+	done
+	return 0
+}
+
+pi_validate_blast_radius_block() {
+	# Validate one blast_radius block against spec invariant 9.
+	#
+	# Args: $1 = node path of the block, $2 = item-scoped context prefix.
+	local path="$1" context="$2"
+	if [[ $(yp_type_of "$path") != map ]]; then
+		pc_error_add "$context blast_radius must be an object."
+		return 0
+	fi
+	local field
+	local -a radius_fields=()
+	read -ra radius_fields <<<"$PC_BLAST_RADIUS_LIST_FIELDS"
+	# Report every malformed collection field rather than stopping at the
+	# first, so one validation pass tells the author everything to fix.
+	for field in "${radius_fields[@]}"; do
+		if ! pi_is_string_list "${path}.${field}"; then
+			pc_error_add "$context blast_radius.$field must be a list of non-empty strings."
+		fi
+	done
+
+	local source_type source_value
+	source_type=$(yp_type_of "${path}.source")
+	source_value=$(yp_value_of "${path}.source")
+	if [[ $source_type != str ]] || ! pc_enum_members_contains "$PC_VALID_SOURCES" "$source_value"; then
+		pc_error_add "$(pc_enum_error "$context" "blast_radius.source" "$PC_VALID_SOURCES" "$(pi_repr_at "${path}.source")")"
+	fi
+
+	local computed_type computed_value
+	computed_type=$(yp_type_of "${path}.computed_at")
+	computed_value=$(yp_value_of "${path}.computed_at")
+	if ! pc_is_non_empty_string "$computed_type" "$computed_value"; then
+		pc_error_add "$context blast_radius.computed_at must be a non-empty string."
+	fi
+}
+
+pi_validate_merge_status() {
+	# Validate merge_status membership and its agreement with item state.
+	#
+	# Absence is the backward-compatible case: an item with no merge_status is
+	# treated as not_started and yields no error, so the check is presence
+	# gated rather than requirement gated.
+	#
+	# Args: $1 = item node path, $2 = item-scoped context, $3 = state repr,
+	# $4 = raw state value.
+	local path="$1" context="$2" state_repr="$3" state_value="$4"
+	yp_has "${path}.merge_status" || return 0
+	local status_type status_value
+	status_type=$(yp_type_of "${path}.merge_status")
+	status_value=$(yp_value_of "${path}.merge_status")
+	# An out-of-enum value short-circuits the consistency rule, because
+	# agreement with state is meaningless for a value that is not a status.
+	if [[ $status_type != str ]] || ! pc_enum_members_contains "$PC_VALID_MERGE_STATUS" "$status_value"; then
+		pc_error_add "$(pc_enum_error "$context" "merge_status" "$PC_VALID_MERGE_STATUS" "$(pi_repr_at "${path}.merge_status")")"
+		return 0
+	fi
+
+	# Invariant 8 pins the two terminal families to their item states; every
+	# other status places no constraint on state.
+	if pc_contains_word "$PC_MERGED_MERGE_STATUSES" "$status_value" && [[ $state_value != merged ]]; then
+		pc_error_add "$context merge_status $(pc_repr_string "$status_value") requires state 'merged'; found: $state_repr."
+		return 0
+	fi
+	if pc_contains_word "$PC_BLOCKED_MERGE_STATUSES" "$status_value" && [[ $state_value != blocked ]]; then
+		pc_error_add "$context merge_status $(pc_repr_string "$status_value") requires state 'blocked'; found: $state_repr."
+	fi
+}
+
+pi_validate_item_record() {
+	# Validate one work-item record against spec invariants 5 through 9.
+	#
+	# Args: $1 = item node path, $2 = item-scoped context prefix, $3 = 1 when
+	# kind is required (the manifest and planner surfaces carry it).
+	local path="$1" context="$2" require_kind="$3"
+	if [[ $(yp_type_of "$path") != map ]]; then
+		pc_error_add "$context must be an object."
+		return 0
+	fi
+
+	local issue_type issue_value
+	issue_type=$(yp_type_of "${path}.issue_num")
+	issue_value=$(yp_value_of "${path}.issue_num")
+	if ! pc_is_positive_integer "$issue_type" "$issue_value"; then
+		pc_error_add "$context issue_num must be a positive integer; found: $(pi_repr_at "${path}.issue_num")."
+	fi
+
+	local folder_type folder_value
+	folder_type=$(yp_type_of "${path}.feature_folder")
+	folder_value=$(yp_value_of "${path}.feature_folder")
+	if ! pc_is_non_empty_string "$folder_type" "$folder_value"; then
+		pc_error_add "$context feature_folder must be a non-empty string."
+	fi
+
+	local state_type state_value state_repr
+	state_type=$(yp_type_of "${path}.state")
+	state_value=$(yp_value_of "${path}.state")
+	state_repr=$(pi_repr_at "${path}.state")
+	if [[ $state_type != str ]] || ! pc_enum_members_contains "$PC_VALID_ITEM_STATES" "$state_value"; then
+		pc_error_add "$(pc_enum_error "$context" "state" "$PC_VALID_ITEM_STATES" "$state_repr")"
+	fi
+
+	if ((require_kind == 1)); then
+		local kind_type kind_value
+		kind_type=$(yp_type_of "${path}.kind")
+		kind_value=$(yp_value_of "${path}.kind")
+		if [[ $kind_type != str ]] || ! pc_enum_members_contains "$PC_VALID_KINDS" "$kind_value"; then
+			pc_error_add "$(pc_enum_error "$context" "kind" "$PC_VALID_KINDS" "$(pi_repr_at "${path}.kind")")"
+		fi
+	fi
+
+	pi_validate_merge_status "$path" "$context" "$state_repr" "$state_value"
+	pi_validate_blast_radius_block "${path}.blast_radius" "$context"
+}
+
+pi_validate_items() {
+	# Validate the items collection, including issue_num uniqueness.
+	#
+	# Args: $1 = node path of the items collection, $2 = surface prefix,
+	# $3 = 1 when kind is required on every entry.
+	local path="$1" context="$2" require_kind="$3"
+	if [[ $(yp_type_of "$path") != seq ]]; then
+		pc_error_add "$context items must be a list."
+		return 0
+	fi
+
+	local count index entry_path item_ctx issue_type issue_value
+	local seen=""
+	local -a duplicates=()
+	count=$(yp_count_of "$path")
+	# Validate each entry in place, and in the same pass accumulate the primary
+	# keys so uniqueness is decided without a second traversal.
+	for ((index = 0; index < count; index++)); do
+		entry_path="${path}[${index}]"
+		item_ctx=$(pc_item_context "$context" "$index")
+		pi_validate_item_record "$entry_path" "$item_ctx" "$require_kind"
+		[[ $(yp_type_of "$entry_path") == map ]] || continue
+		issue_type=$(yp_type_of "${entry_path}.issue_num")
+		issue_value=$(yp_value_of "${entry_path}.issue_num")
+		[[ $issue_type == int ]] || continue
+		if pc_contains_word "$seen" "$issue_value"; then
+			duplicates+=("$issue_value")
+		fi
+		seen="$seen $issue_value"
+	done
+
+	((${#duplicates[@]} > 0)) || return 0
+	# Report duplicates in ascending numeric order, de-duplicated, so a key
+	# repeated three times still yields exactly one message.
+	local ordered duplicate
+	ordered=$(printf '%s\n' "${duplicates[@]}" | sort -n -u)
+	while IFS= read -r duplicate; do
+		[[ -n $duplicate ]] || continue
+		pc_error_add "$context has duplicate items[].issue_num: $duplicate."
+	done <<<"$ordered"
+}
+
+pi_scan_prohibited_keys() {
+	# Reject prohibited keys per manifest invariant M7.
+	#
+	# Args: $1 = surface prefix, $2 = space-separated keys rejected at any
+	# nesting level, $3 = space-separated keys rejected at the document root
+	# only. Deep results come first, in document order, then the top-level
+	# results in the order the third argument lists them.
+	local context="$1" deep_keys="$2" top_keys="$3"
+	local index path key total=${#YP_ORDER[@]}
+	# Walk the node table in document order so the message sequence reproduces
+	# Python's depth-first, insertion-ordered traversal exactly.
+	for ((index = 0; index < total; index++)); do
+		path="${YP_ORDER[index]}"
+		key="${YP_KEY[$path]-}"
+		[[ -n $key ]] || continue
+		if pc_contains_word "$deep_keys" "$key"; then
+			pc_error_add "$context carries prohibited key '$key' at ${YP_PARENT[$path]}."
+		fi
+	done
+
+	# The shallow pass exists because manifest M7 bans integration_branch at
+	# the top level only, where a nested occurrence is legitimate child data.
+	local -a top_key_list=()
+	read -ra top_key_list <<<"$top_keys"
+	for key in "${top_key_list[@]}"; do
+		if yp_has "$key"; then
+			pc_error_add "$context carries prohibited key '$key' at $PC_ROOT_PATH."
+		fi
+	done
+}

package/resources/claude-customizations/.claude/lib/bash/parallel-manifest-validate.sh

@@ -0,0 +1,187 @@
+#!/usr/bin/env bash
+# parallel-manifest-validate.sh: sourceable bash port of
+# scripts/dev_tools/parallel_manifest_contract.py. Validates a parallel-run
+# manifest document against invariants M1 through M7 and exposes the two
+# default-resolving accessors that every consumer uses instead of reading
+# `mode` and `max_concurrency` directly.
+#
+# Section order is load-bearing and mirrors the Python module exactly: the M1
+# frontmatter checks short-circuit with a single error; then run identity
+# (M2 parallel, M3 mode, M4 max_concurrency, M5 created_at) in schema field
+# order; then the M7 prohibited-key scan, deep results in document order
+# followed by the top-level results; then the M6 items collection.
+#
+# Every error string begins with the literal prefix `Parallel manifest` and
+# ends with a period. The Python module remains the repository authority.
+#
+# Out-of-subset input. When the YAML scanner refuses a construct it does not
+# model, this module returns exit status 2 with the refusal detail in
+# PM_SUBSET_DETAIL and emits no validation errors. Refusing to answer is
+# deliberate: a guessed parse could disagree with the Python authority
+# silently, whereas an explicit refusal is visible to the caller.
+#
+# shellcheck disable=SC2034
+# SC2034 is disabled file-wide because PM_SUBSET_DETAIL is written here and
+# read by the entry point validate-parallel-manifest.sh, which shellcheck
+# analyses as a separate file and therefore cannot see the use.
+
+# Resolve this file's own directory so its dependencies source regardless of
+# the caller's working directory.
+PM_LIB_DIR=$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)
+# shellcheck source=.claude/lib/bash/parallel-items-validate.sh
+# shellcheck disable=SC1091
+source "$PM_LIB_DIR/parallel-items-validate.sh"
+
+# Literal context prefix for every error this module and its helpers emit.
+PM_CONTEXT="Parallel manifest"
+
+# Documented default run mode when the manifest omits `mode` (invariant M3).
+PM_DEFAULT_MODE="closed"
+
+# Documented default fan-out when the manifest omits `max_concurrency` (M4).
+PM_DEFAULT_MAX_CONCURRENCY=4
+
+# Inclusive bounds on a present `max_concurrency` (invariant M4, A7).
+PM_MIN_CONCURRENCY=1
+PM_MAX_CONCURRENCY=8
+
+# Keys the manifest rejects at any nesting level (invariant M7).
+PM_DEEP_PROHIBITED_KEYS="depends_on"
+
+# Keys the manifest rejects at the document root only (invariant M7).
+PM_TOP_LEVEL_PROHIBITED_KEYS="integration_branch"
+
+# Detail recorded when the parser refuses an out-of-subset construct.
+PM_SUBSET_DETAIL=""
+
+pm_parse_manifest() {
+	# Parse manifest text into the shared node table (invariant M1).
+	#
+	# Args: $1 = raw manifest document text.
+	# Returns 0 when the frontmatter parsed into a mapping. Returns 1 after
+	# appending the single M1 error to PC_ERRORS for a missing, unterminated,
+	# unparseable, or non-mapping block. Returns 2 without appending anything
+	# when the document uses a construct outside the supported subset.
+	local text="$1"
+	if ! yp_extract_frontmatter_body "$text" "$PM_CONTEXT"; then
+		pc_error_add "$YP_FENCE_ERROR"
+		return 1
+	fi
+	if yp_parse_body; then
+		return 0
+	fi
+	# Routing table for the three parser failure modes: a sequence or empty
+	# root is M1's non-mapping case, a malformed line is M1's YAML-error case,
+	# and an unsupported construct makes the module refuse to answer.
+	case "$YP_STATUS" in
+	not_a_mapping)
+		pc_error_add "$PM_CONTEXT frontmatter must be a mapping."
+		return 1
+		;;
+	yaml_error)
+		pc_error_add "$PM_CONTEXT frontmatter is not valid YAML: $YP_DETAIL."
+		return 1
+		;;
+	*)
+		PM_SUBSET_DETAIL="$YP_DETAIL"
+		return 2
+		;;
+	esac
+}
+
+pm_validate_identity() {
+	# Validate run identity fields against invariants M2 through M5.
+	#
+	# The mode and max_concurrency checks are presence gated because both keys
+	# are optional: absence is the documented authoring shape that the
+	# accessors resolve, so it must contribute no error.
+	local slug_type slug_value
+	slug_type=$(yp_type_of "parallel")
+	slug_value=$(yp_value_of "parallel")
+	if ! pc_is_non_empty_string "$slug_type" "$slug_value"; then
+		pc_error_add "$PM_CONTEXT parallel must be a non-empty string."
+	fi
+
+	if yp_has "mode"; then
+		local mode_type mode_value
+		mode_type=$(yp_type_of "mode")
+		mode_value=$(yp_value_of "mode")
+		if [[ $mode_type != str ]] || ! pc_enum_members_contains "$PC_VALID_MODES" "$mode_value"; then
+			pc_error_add "$(pc_enum_error "$PM_CONTEXT" "mode" "$PC_VALID_MODES" "$(pi_repr_at "mode")")"
+		fi
+	fi
+
+	if yp_has "max_concurrency"; then
+		local cap_type cap_value
+		cap_type=$(yp_type_of "max_concurrency")
+		cap_value=$(yp_value_of "max_concurrency")
+		if ! pc_in_bounded_range "$cap_type" "$cap_value" "$PM_MIN_CONCURRENCY" "$PM_MAX_CONCURRENCY"; then
+			pc_error_add "$PM_CONTEXT max_concurrency must be an integer from $PM_MIN_CONCURRENCY through $PM_MAX_CONCURRENCY; found: $(pi_repr_at "max_concurrency")."
+		fi
+	fi
+
+	local created_type created_value
+	created_type=$(yp_type_of "created_at")
+	created_value=$(yp_value_of "created_at")
+	if ! pc_is_non_empty_string "$created_type" "$created_value"; then
+		pc_error_add "$PM_CONTEXT created_at must be a non-empty string."
+	fi
+}
+
+pm_validate_text() {
+	# Validate a manifest document against invariants M1 to M7.
+	#
+	# Args: $1 = raw manifest document text, authored with LF, CRLF, or CR
+	# line endings.
+	# Returns 0 after populating PC_ERRORS with the complete error list, which
+	# is empty for a valid manifest. Returns 2 without populating PC_ERRORS
+	# when the document uses a construct outside the supported subset.
+	local text="$1" parse_status=0
+	pc_errors_reset
+	PM_SUBSET_DETAIL=""
+	pm_parse_manifest "$text" || parse_status=$?
+	# An out-of-subset refusal propagates so the caller can distinguish it from
+	# a validation verdict; an M1 failure returns the single-element error list
+	# already accumulated, because no field check is meaningful without a
+	# mapping to read fields from.
+	if ((parse_status == 2)); then
+		return 2
+	fi
+	if ((parse_status != 0)); then
+		return 0
+	fi
+
+	pm_validate_identity
+	pi_scan_prohibited_keys "$PM_CONTEXT" "$PM_DEEP_PROHIBITED_KEYS" "$PM_TOP_LEVEL_PROHIBITED_KEYS"
+	# The manifest carries `kind` on every item, unlike the orchestrator
+	# checkpoint, so the shared item validator is asked to require it (S1).
+	pi_validate_items "items" "$PM_CONTEXT" 1
+	return 0
+}
+
+pm_manifest_mode() {
+	# Echo the run mode declared by the parsed manifest (invariant M3).
+	#
+	# A present but non-string value resolves to the default so this accessor
+	# always returns a mode; the malformed value is reported separately by
+	# pm_validate_text.
+	if [[ $(yp_type_of "mode") == str ]]; then
+		yp_value_of "mode"
+	else
+		printf '%s' "$PM_DEFAULT_MODE"
+	fi
+}
+
+pm_manifest_max_concurrency() {
+	# Echo the fan-out cap declared by the parsed manifest (invariant M4).
+	#
+	# A present but non-integer value resolves to the default so this accessor
+	# always returns an integer; the malformed value is reported separately by
+	# pm_validate_text. Booleans are classified as `bool` by the scanner and
+	# therefore never satisfy the integer test.
+	if [[ $(yp_type_of "max_concurrency") == int ]]; then
+		yp_value_of "max_concurrency"
+	else
+		printf '%s' "$PM_DEFAULT_MAX_CONCURRENCY"
+	fi
+}