From 59691960ae0c5dfcbcb5c449bd30003680ecc67a Mon Sep 17 00:00:00 2001 From: Dandaedre Date: Wed, 16 Sep 2026 03:16:39 +0200 Subject: [PATCH] refactor: expose and format diagnostic tools --- README.md | 2 +- analyse-all.sh | 97 +++++++++++++++++++++++++++++++++++ tests/test.sh | 2 + tools/analyse-all.sh | 24 --------- tools/validate-all.sh | 43 +++++++++++++--- tools/validate.sh | 115 +++++++++++++++++++++++++++++++++++------- 6 files changed, 235 insertions(+), 48 deletions(-) create mode 100755 analyse-all.sh delete mode 100755 tools/analyse-all.sh diff --git a/README.md b/README.md index 89547bc..21c4064 100644 --- a/README.md +++ b/README.md @@ -19,7 +19,7 @@ and unmatched evidence marked `unanalysed`. ## Analyse everything in a directory ```bash -bash tools/analyse-all.sh /path/to/captures \ +./analyse-all.sh /path/to/captures \ --evidence-root /path/to/evidence \ --output-dir /path/to/diagnostics \ --reference-time 2026-09-15T12:00:00Z \ diff --git a/analyse-all.sh b/analyse-all.sh new file mode 100755 index 0000000..ab3d4b9 --- /dev/null +++ b/analyse-all.sh @@ -0,0 +1,97 @@ +#!/usr/bin/env bash +set -euo pipefail + +root=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P) + +usage() { + cat >&2 <&2 + exit 1 +} + +require_value() { + (($# >= 2)) || usage +} + +input_dir=${1:-} +[[ -n "$input_dir" ]] || usage +shift + +evidence_root= +output_dir= +reference_time= +producer_version= +force=false + +while (($#)); do + case $1 in + --evidence-root) + require_value "$@" + evidence_root=$2 + shift 2 + ;; + --output-dir) + require_value "$@" + output_dir=$2 + shift 2 + ;; + --reference-time) + require_value "$@" + reference_time=$2 + shift 2 + ;; + --producer-version) + require_value "$@" + producer_version=$2 + shift 2 + ;; + --force) + force=true + shift + ;; + *) + usage + ;; + esac +done + +for value in "$evidence_root" "$output_dir" "$reference_time" "$producer_version"; do + [[ -n "$value" ]] || usage +done + +input_dir=$(realpath "$input_dir") +mkdir -p "$output_dir" +output_dir=$(realpath "$output_dir") + +if [[ "$output_dir" == "$input_dir" || "$output_dir" == "$input_dir"/* ]]; then + fail "output directory must be outside the input tree" +fi + +count=0 +while IFS= read -r -d '' input; do + relative=${input#"$input_dir/"} + output="$output_dir/${relative%.json}.diagnostic.json" + mkdir -p "$(dirname "$output")" + + arguments=() + [[ "$force" == false ]] || arguments+=(--force) + + "$root/analyse.sh" "$input" --evidence-root "$evidence_root" --output "$output" \ + --reference-time "$reference_time" --producer-version "$producer_version" "${arguments[@]}" + + ((count += 1)) +done < <(find "$input_dir" -type f -name '*.json' -print0 | sort -z) + +((count > 0)) || fail "$input_dir: no JSON captures found" +echo "Analysed $count captures into $output_dir" diff --git a/tests/test.sh b/tests/test.sh index 7438c7a..027c3bd 100755 --- a/tests/test.sh +++ b/tests/test.sh @@ -1,6 +1,8 @@ #!/usr/bin/env bash set -euo pipefail + cd "$(dirname "${BASH_SOURCE[0]}")/.." + uv venv --python 3.11 --allow-existing .venv uv pip sync --python .venv/bin/python tests/requirements.txt .venv/bin/python -m unittest discover -s tests -p 'test_*.py' -v diff --git a/tools/analyse-all.sh b/tools/analyse-all.sh deleted file mode 100755 index af6087f..0000000 --- a/tools/analyse-all.sh +++ /dev/null @@ -1,24 +0,0 @@ -#!/usr/bin/env bash -set -euo pipefail -root=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd -P) -usage(){ echo "Usage: $0 INPUT_DIR --evidence-root DIR --output-dir DIR --reference-time TIME --producer-version VERSION [--force]" >&2; exit 2; } -input_dir=${1:-}; [[ -n "$input_dir" ]]||usage; shift -evidence_root= output_dir= reference_time= producer_version= force=false -while (($#)); do case $1 in - --evidence-root) (($# >= 2))||usage; evidence_root=$2; shift 2;; --output-dir) (($# >= 2))||usage; output_dir=$2; shift 2;; - --reference-time) (($# >= 2))||usage; reference_time=$2; shift 2;; --producer-version) (($# >= 2))||usage; producer_version=$2; shift 2;; - --force) force=true; shift;; *) usage;; esac; done -for value in "$evidence_root" "$output_dir" "$reference_time" "$producer_version"; do [[ -n "$value" ]]||usage; done -input_dir=$(realpath "$input_dir"); mkdir -p "$output_dir"; output_dir=$(realpath "$output_dir") -[[ "$output_dir" != "$input_dir" && "$output_dir" != "$input_dir"/* ]]||{ echo "output directory must be outside the input tree" >&2; exit 1; } -count=0 -while IFS= read -r -d '' input; do - relative=${input#"$input_dir/"}; output="$output_dir/${relative%.json}.diagnostic.json" - mkdir -p "$(dirname "$output")"; arguments=() - [[ "$force" == false ]]||arguments+=(--force) - "$root/analyse.sh" "$input" --evidence-root "$evidence_root" --output "$output" \ - --reference-time "$reference_time" --producer-version "$producer_version" "${arguments[@]}" - ((count+=1)) -done < <(find "$input_dir" -type f -name '*.json' -print0 | sort -z) -((count > 0))||{ echo "$input_dir: no JSON captures found" >&2; exit 1; } -echo "Analysed $count captures into $output_dir" diff --git a/tools/validate-all.sh b/tools/validate-all.sh index 88ec988..bfd97b5 100755 --- a/tools/validate-all.sh +++ b/tools/validate-all.sh @@ -1,13 +1,44 @@ #!/usr/bin/env bash set -euo pipefail + root=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd -P) -usage(){ echo "Usage: $0 INPUT_DIR [--evidence-root DIR]" >&2; exit 2; } -input_dir=${1:-}; [[ -n "$input_dir" ]]||usage; shift; evidence_root= -while (($#)); do case $1 in --evidence-root) (($# >= 2))||usage; evidence_root=$2; shift 2;; *) usage;; esac; done + +usage() { + echo "Usage: $0 INPUT_DIR [--evidence-root DIR]" >&2 + exit 2 +} + +fail() { + echo "error: $*" >&2 + exit 1 +} + +input_dir=${1:-} +[[ -n "$input_dir" ]] || usage +shift + +evidence_root= +while (($#)); do + case $1 in + --evidence-root) + (($# >= 2)) || usage + evidence_root=$2 + shift 2 + ;; + *) + usage + ;; + esac +done + count=0 while IFS= read -r -d '' input; do - arguments=(); [[ -z "$evidence_root" ]]||arguments+=(--evidence-root "$evidence_root") - "$root/tools/validate.sh" "$input" "${arguments[@]}"; ((count+=1)) + arguments=() + [[ -z "$evidence_root" ]] || arguments+=(--evidence-root "$evidence_root") + + "$root/tools/validate.sh" "$input" "${arguments[@]}" + ((count += 1)) done < <(find "$input_dir" -type f -name '*.json' -print0 | sort -z) -((count > 0))||{ echo "$input_dir: no JSON diagnostics found" >&2; exit 1; } + +((count > 0)) || fail "$input_dir: no JSON diagnostics found" echo "Validated $count diagnostics" diff --git a/tools/validate.sh b/tools/validate.sh index 5a38e94..2cd43f7 100755 --- a/tools/validate.sh +++ b/tools/validate.sh @@ -1,22 +1,103 @@ #!/usr/bin/env bash set -euo pipefail -usage(){ echo "Usage: $0 INPUT [--evidence-root DIR]" >&2; exit 2; }; fail(){ echo "error: $*" >&2; exit 1; } -sha256_file(){ if command -v sha256sum >/dev/null 2>&1; then sha256sum "$1"|awk '{print $1}'; elif command -v sha256 >/dev/null 2>&1; then sha256 -q "$1"; else openssl dgst -sha256 "$1"|awk '{print $NF}'; fi; } -json_string(){ local value=$1; [[ "$value" == \"*\" ]]||fail "Typst returned a non-string value"; value=${value:1:${#value}-2}; [[ "$value" != *\\* && "$value" != *\"* ]]||fail "unsupported escaped path"; printf '%s' "$value"; } -input=${1:-}; [[ -n "$input" ]]||usage; shift; evidence_root= -while (($#)); do case $1 in --evidence-root) (($#>=2))||usage; evidence_root=$2;shift 2;;*) usage;;esac; done -root=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd -P); input=$(realpath "$input") -stage=$(mktemp -d "${TMPDIR:-/tmp}/diagnostic-validate.XXXXXXXX"); trap 'rm -rf "$stage"' EXIT -cp "$input" "$stage/diagnostic.json"; cp "$root/tools/validate.typ" "$stage/validate.typ" -typst query --root "$stage" --input diagnostic=diagnostic.json "$stage/validate.typ" '' --one >/dev/null 2>&1||fail "invalid diagnostic v1: $input" + +root=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd -P) + +usage() { + echo "Usage: $0 INPUT [--evidence-root DIR]" >&2 + exit 2 +} + +fail() { + echo "error: $*" >&2 + exit 1 +} + +sha256_file() { + if command -v sha256sum >/dev/null 2>&1; then + sha256sum "$1" | awk '{print $1}' + elif command -v sha256 >/dev/null 2>&1; then + sha256 -q "$1" + else + openssl dgst -sha256 "$1" | awk '{print $NF}' + fi +} + +json_string() { + local value=$1 + [[ "$value" == \"*\" ]] || fail "Typst returned a non-string value" + + value=${value:1:${#value}-2} + [[ "$value" != *\\* && "$value" != *\"* ]] || fail "unsupported escaped path" + printf '%s' "$value" +} + +input=${1:-} +[[ -n "$input" ]] || usage +shift + +evidence_root= +while (($#)); do + case $1 in + --evidence-root) + (($# >= 2)) || usage + evidence_root=$2 + shift 2 + ;; + *) + usage + ;; + esac +done + +input=$(realpath "$input") +stage=$(mktemp -d "${TMPDIR:-/tmp}/diagnostic-validate.XXXXXXXX") +trap 'rm -rf "$stage"' EXIT + +cp "$input" "$stage/diagnostic.json" +cp "$root/tools/validate.typ" "$stage/validate.typ" + +typst query \ + --root "$stage" \ + --input diagnostic=diagnostic.json \ + "$stage/validate.typ" \ + '' \ + --one >/dev/null 2>&1 || fail "invalid diagnostic v1: $input" + if [[ -n "$evidence_root" ]]; then - artifact=$(json_string "$(typst query --root "$stage" --input diagnostic=diagnostic.json "$stage/validate.typ" '' --field value --one 2>/dev/null)") - expected=$(json_string "$(typst query --root "$stage" --input diagnostic=diagnostic.json "$stage/validate.typ" '' --field value --one 2>/dev/null)") - [[ "$artifact" != /* && "$artifact" != *..* ]]||fail "source artifact escapes evidence root" - source=$(realpath "$evidence_root/$artifact"); evidence_base=$(realpath "$evidence_root") - [[ "$source" == "$evidence_base"/* && -f "$source" ]]||fail "source artifact escapes evidence root" - [[ $(sha256_file "$source") == "$expected" ]]||fail "evidence checksum differs" - cp "$source" "$stage/raw.json"; cp "$root/tools/verify-evidence.typ" "$stage/verify-evidence.typ" - typst query --root "$stage" --input diagnostic=diagnostic.json --input raw=raw.json "$stage/verify-evidence.typ" '' --one >/dev/null 2>&1||fail "observation differs from referenced raw evidence" + artifact=$(json_string "$(typst query \ + --root "$stage" \ + --input diagnostic=diagnostic.json \ + "$stage/validate.typ" \ + '' \ + --field value \ + --one 2>/dev/null)") + + expected=$(json_string "$(typst query \ + --root "$stage" \ + --input diagnostic=diagnostic.json \ + "$stage/validate.typ" \ + '' \ + --field value \ + --one 2>/dev/null)") + + [[ "$artifact" != /* && "$artifact" != *..* ]] || fail "source artifact escapes evidence root" + + evidence_base=$(realpath "$evidence_root") + source=$(realpath "$evidence_root/$artifact") + [[ "$source" == "$evidence_base"/* && -f "$source" ]] || fail "source artifact escapes evidence root" + [[ $(sha256_file "$source") == "$expected" ]] || fail "evidence checksum differs" + + cp "$source" "$stage/raw.json" + cp "$root/tools/verify-evidence.typ" "$stage/verify-evidence.typ" + + typst query \ + --root "$stage" \ + --input diagnostic=diagnostic.json \ + --input raw=raw.json \ + "$stage/verify-evidence.typ" \ + '' \ + --one >/dev/null 2>&1 || fail "observation differs from referenced raw evidence" fi + echo "Valid diagnostic v1: $input"