From ae332856b35d56af4a1d7fe309fe6f0ca65b9b26 Mon Sep 17 00:00:00 2001 From: alexander-yevsyukov Date: Fri, 24 Jul 2026 19:43:18 +0100 Subject: [PATCH 1/2] Fix silently-passing checkSamples code-embedding check `./gradlew checkSamples` was exiting 0 while verifying nothing, so CI's "Check Code Embedding" workflow stayed green regardless of embedding drift. Two compounding bugs: 1. Stale config: `docs/_settings/v1.embed-code.yml` set `docs-path` to `../content/docs/1`, a directory removed in the site restructure. The embed-code binary rejected it with an argument-validation error. 2. Swallowed failure: on argument-validation errors the embed-code binary prints an ERROR line but still exits 0, so `set -e` in `docs/_script/check-samples` had no non-zero status to trip on. Changes: - Repoint `docs-path` to `../content/docs` (top-level key and embed-mappings). - Harden `check-samples` to fail closed: the check now passes only when the binary exits 0 AND prints its success sentinel ("documentation files are up-to-date with code files"). An argument error (exit 0), a stale embedding, or any other silent-exit-0 failure is now reported and fails the build. Verified via `./gradlew :checkSamples` (what CI runs): passes on a clean tree, and now fails with exit 1 both on a deliberately stale embedding and on a bad `docs-path`. The embeddings themselves were already up to date, so no regeneration was needed. The root cause (exit 0 on argument errors) lives upstream in SpineEventEngine/embed-code-go; the guard protects this repo regardless. Co-Authored-By: Claude Fable 5 --- docs/_script/check-samples | 36 ++++++++++++++++++++++++++++++-- docs/_settings/v1.embed-code.yml | 4 ++-- 2 files changed, 36 insertions(+), 4 deletions(-) diff --git a/docs/_script/check-samples b/docs/_script/check-samples index 9b48ce1..4893fa9 100755 --- a/docs/_script/check-samples +++ b/docs/_script/check-samples @@ -1,6 +1,6 @@ #!/usr/bin/env bash # -# Copyright 2020, TeamDev. All rights reserved. +# Copyright 2026, TeamDev. All rights reserved. # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. @@ -52,4 +52,36 @@ else fi # Check code samples. -"$TOOL" -config-path="../_settings/v1.embed-code.yml" -mode="check" +# +# The embed-code binary is not a reliable exit-code citizen: on argument- +# validation errors (for example, a `docs-path` that does not exist) it prints +# an `ERROR` line but still exits 0. Relying on the exit code alone therefore +# let a misconfigured check pass silently — CI stayed green while checking +# nothing. See https://github.com/SpineEventEngine/embed-code-go. +# +# We fail closed: the check passes ONLY when the tool exits 0 AND prints its +# explicit success sentinel. Any other outcome — a non-zero exit (stale +# embeddings, a missing code file) or a zero exit without the sentinel (an +# argument error) — is treated as a failure. If a future embed-code release +# changes the success wording this guard will fail loudly rather than silently; +# update SUCCESS_SENTINEL below to match. +SUCCESS_SENTINEL="documentation files are up-to-date with code files" + +if OUTPUT="$("$TOOL" -config-path="../_settings/v1.embed-code.yml" -mode="check" 2>&1)"; then + STATUS=0 +else + STATUS=$? +fi + +echo "$OUTPUT" + +if [ "$STATUS" -ne 0 ] || ! printf '%s\n' "$OUTPUT" | grep -qF "$SUCCESS_SENTINEL"; then + echo "" >&2 + echo "ERROR: embed-code check did not confirm success (exit status ${STATUS})." >&2 + echo "Either the embedded code samples are out of date, or embed-code was" >&2 + echo "misconfigured (for example, an invalid path in" >&2 + echo "docs/_settings/v1.embed-code.yml)." >&2 + echo "Run './gradlew embedCode', review the changes per EMBEDDING.md, and" >&2 + echo "commit them; or fix the configuration." >&2 + exit 1 +fi diff --git a/docs/_settings/v1.embed-code.yml b/docs/_settings/v1.embed-code.yml index 09c5480..7cbb284 100644 --- a/docs/_settings/v1.embed-code.yml +++ b/docs/_settings/v1.embed-code.yml @@ -1,5 +1,5 @@ code-path: "../_code" -docs-path: "../content/docs/1" +docs-path: "../content/docs" embed-mappings: - code-path: "../_code" - docs-path: "../content/docs/1" + docs-path: "../content/docs" From fcbde1110d5cd6a72137b4d2da48d92d76e5ec35 Mon Sep 17 00:00:00 2001 From: alexander-yevsyukov Date: Fri, 24 Jul 2026 20:56:54 +0100 Subject: [PATCH 2/2] Keep v1 embed-code docs-path at ../content/docs/1 Reverts the docs-path change from the prior commit on this branch. Per the project's documentation versioning, the v1 embed-code config stays pointed at the `/1` subfolder, so the net change of this branch is just the fail-loud guard in check-samples. Because commit b184e4d ("Move the main documentation version to the root") moved v1 content to the root and no docs/content/docs/1 directory exists yet, checkSamples now fails loudly via that guard, reporting the missing path. Restoring `/1` is handled separately. Co-Authored-By: Claude Fable 5 --- docs/_settings/v1.embed-code.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/_settings/v1.embed-code.yml b/docs/_settings/v1.embed-code.yml index 7cbb284..09c5480 100644 --- a/docs/_settings/v1.embed-code.yml +++ b/docs/_settings/v1.embed-code.yml @@ -1,5 +1,5 @@ code-path: "../_code" -docs-path: "../content/docs" +docs-path: "../content/docs/1" embed-mappings: - code-path: "../_code" - docs-path: "../content/docs" + docs-path: "../content/docs/1"