From bbda6954548ea3cea57edd17defee718bce4a2de Mon Sep 17 00:00:00 2001 From: ecuthiell Date: Sat, 25 Jul 2026 23:53:47 -0600 Subject: [PATCH] fix(scripts): remove Python from doc freshness checks (#4978) (#4979) Use strict pure-Bash proleptic-Gregorian validation and day numbering so the full 0001-01-01 through 9999-12-31 domain is independent of platform date parsing. Keep native date only as the default TODAY provider, with distinct provider-versus-override diagnostics. Mark the real-process suite integration-only, harden Git Bash discovery and its child environment, and require native Linux, macOS, and Windows boundaries in PR CI. Agent-Signature: codex-tui-gpt-5.6-sol-ultra on behalf of Ewen Cuthiell Co-authored-by: matt wilkie --- .github/workflows/pr.yml | 22 ++ scripts/check-doc-freshness.sh | 96 +++++- scripts/check_doc_freshness_test.go | 486 ++++++++++++++++++++++++++++ scripts/docs.md | 6 + 4 files changed, 597 insertions(+), 13 deletions(-) create mode 100644 scripts/check_doc_freshness_test.go diff --git a/.github/workflows/pr.yml b/.github/workflows/pr.yml index df19390d8..c02f94bfe 100644 --- a/.github/workflows/pr.yml +++ b/.github/workflows/pr.yml @@ -204,6 +204,25 @@ jobs: path: ${{ runner.temp }}/cli-docs-freshness.patch if-no-files-found: ignore + check-doc-freshness-platforms: + name: Check doc freshness (${{ matrix.os }}) + runs-on: ${{ matrix.os }} + timeout-minutes: 10 + strategy: + fail-fast: false + matrix: + os: [ubuntu-latest, macos-latest, windows-latest] + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v6 + + - name: Set up Go + uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0 + with: + go-version-file: 'go.mod' + + - name: Exercise native date and Bash process boundary + run: go test '-tags=integration,gms_pure_go' -count=1 -run '^TestDocFreshness' ./scripts + pr-preflight-platforms: name: PR preflight process (${{ matrix.os }}) runs-on: ${{ matrix.os }} @@ -767,6 +786,7 @@ jobs: - check-version-consistency - check-migration-hygiene - check-doc-flags + - check-doc-freshness-platforms - pr-preflight-platforms - check-no-beads-changes - detect-package-gates @@ -795,6 +815,7 @@ jobs: CHECK_VERSION_CONSISTENCY CHECK_MIGRATION_HYGIENE CHECK_DOC_FLAGS + CHECK_DOC_FRESHNESS_PLATFORMS PR_PREFLIGHT_PLATFORMS CHECK_NO_BEADS_CHANGES DETECT_PACKAGE_GATES @@ -815,6 +836,7 @@ jobs: CHECK_VERSION_CONSISTENCY: ${{ needs.check-version-consistency.result }} CHECK_MIGRATION_HYGIENE: ${{ needs.check-migration-hygiene.result }} CHECK_DOC_FLAGS: ${{ needs.check-doc-flags.result }} + CHECK_DOC_FRESHNESS_PLATFORMS: ${{ needs.check-doc-freshness-platforms.result }} PR_PREFLIGHT_PLATFORMS: ${{ needs.pr-preflight-platforms.result }} CHECK_NO_BEADS_CHANGES: ${{ needs.check-no-beads-changes.result }} DETECT_PACKAGE_GATES: ${{ needs.detect-package-gates.result }} diff --git a/scripts/check-doc-freshness.sh b/scripts/check-doc-freshness.sh index 7b07cdc2f..51e714f0e 100755 --- a/scripts/check-doc-freshness.sh +++ b/scripts/check-doc-freshness.sh @@ -13,7 +13,9 @@ set -euo pipefail SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" PROJECT_ROOT="$(dirname "$SCRIPT_DIR")" MAX_AGE_DAYS="${DOC_FRESHNESS_MAX_AGE_DAYS:-90}" -TODAY="${DOC_FRESHNESS_TODAY:-$(date +%F)}" +TODAY="${DOC_FRESHNESS_TODAY:-}" +TODAY_SOURCE="override" +TODAY_DAY="" ERRORS=0 DOCS=( @@ -27,21 +29,68 @@ DOCS=( "engdocs/design/otel/otel-data-model.md|internal/telemetry/;internal/storage/dolt/store.go;internal/compact/haiku.go;cmd/bd/find_duplicates.go;internal/hooks/" ) -echo "Checking reference doc freshness markers..." -echo "Max age: ${MAX_AGE_DAYS} days" -echo "Today: ${TODAY}" -echo "" +date_day_number() { + local value="$1" + local value_pattern='^([0-9]{4})-([0-9]{2})-([0-9]{2})$' + local year + local month + local day + local max_day + local adjusted_year + local era + local year_of_era + local month_prime + local day_of_year + local day_of_era + + [[ "$value" =~ $value_pattern ]] || return 1 + year=$((10#${BASH_REMATCH[1]})) + month=$((10#${BASH_REMATCH[2]})) + day=$((10#${BASH_REMATCH[3]})) + (( year >= 1 && year <= 9999 )) || return 1 + + case "$month" in + 1|3|5|7|8|10|12) + max_day=31 + ;; + 4|6|9|11) + max_day=30 + ;; + 2) + max_day=28 + if (( year % 400 == 0 || (year % 4 == 0 && year % 100 != 0) )); then + max_day=29 + fi + ;; + *) + return 1 + ;; + esac + (( day >= 1 && day <= max_day )) || return 1 + + # Map the proleptic Gregorian date to a monotonic day number. March is + # month zero, so leap day sits at the end of each transformed year. + adjusted_year=$year + if (( month <= 2 )); then + adjusted_year=$((adjusted_year - 1)) + fi + era=$((adjusted_year / 400)) + year_of_era=$((adjusted_year - era * 400)) + if (( month > 2 )); then + month_prime=$((month - 3)) + else + month_prime=$((month + 9)) + fi + day_of_year=$(((153 * month_prime + 2) / 5 + day - 1)) + day_of_era=$((year_of_era * 365 + year_of_era / 4 - year_of_era / 100 + day_of_year)) + printf '%s\n' "$((era * 146097 + day_of_era))" +} date_age_days() { - local reviewed="$1" - python3 - "$reviewed" "$TODAY" <<'PY' -import datetime -import sys + local reviewed_day -reviewed = datetime.date.fromisoformat(sys.argv[1]) -today = datetime.date.fromisoformat(sys.argv[2]) -print((today - reviewed).days) -PY + reviewed_day="$(date_day_number "$1")" || return 1 + printf '%s\n' "$((TODAY_DAY - reviewed_day))" } inventory_ref_for_doc() { @@ -61,6 +110,27 @@ path_exists_or_glob_matches() { fi } +if [[ -z "$TODAY" ]]; then + TODAY_SOURCE="provider" + if ! TODAY="$(date '+%Y-%m-%d' 2>/dev/null)"; then + echo "ERROR: check-doc-freshness could not determine today's date" >&2 + exit 2 + fi +fi +if ! TODAY_DAY="$(date_day_number "$TODAY")"; then + if [[ "$TODAY_SOURCE" == "provider" ]]; then + echo "ERROR: date returned an invalid current date: $TODAY" >&2 + else + echo "ERROR: invalid DOC_FRESHNESS_TODAY date: $TODAY" >&2 + fi + exit 2 +fi + +echo "Checking reference doc freshness markers..." +echo "Max age: ${MAX_AGE_DAYS} days" +echo "Today: ${TODAY}" +echo "" + for entry in "${DOCS[@]}"; do IFS='|' read -r doc sources <<<"$entry" doc_path="$PROJECT_ROOT/$doc" diff --git a/scripts/check_doc_freshness_test.go b/scripts/check_doc_freshness_test.go new file mode 100644 index 000000000..a0d397465 --- /dev/null +++ b/scripts/check_doc_freshness_test.go @@ -0,0 +1,486 @@ +//go:build integration + +package scripts_test + +import ( + "fmt" + "os" + "os/exec" + "path/filepath" + "runtime" + "strings" + "testing" +) + +var freshnessDocuments = []struct { + path string + sources []string +}{ + {"docs/reference/configuration.md", []string{"cmd/bd/main.go", "cmd/bd/config.go", "internal/configfile/"}}, + {"docs/getting-started/ide-setup.md", []string{"cmd/bd/setup*.go", "internal/recipes/"}}, + {"docs/integrations/azure-devops.md", []string{"cmd/bd/ado*.go", "internal/ado/"}}, + {"docs/reference/json-schema.md", []string{"cmd/bd/output.go", "cmd/bd/errors.go", "cmd/bd/protocol/json_contract_test.go"}}, + {"docs/recovery/init-safety.md", []string{"cmd/bd/init.go", "cmd/bd/init_safety.go", "cmd/bd/init_safety_test.go"}}, + {"engdocs/ERROR_HANDLING.md", []string{"cmd/bd/*.go", "cmd/bd/errors.go"}}, + {"engdocs/LINTING.md", []string{".golangci.yml"}}, + {"engdocs/design/otel/otel-data-model.md", []string{"internal/telemetry/", "internal/storage/dolt/store.go", "internal/compact/haiku.go", "cmd/bd/find_duplicates.go", "internal/hooks/"}}, +} + +type freshnessRun struct { + output string + err error + pythonInvoked bool + dateInvoked bool +} + +const pythonPoisonFunction = `python3() { + printf 'invoked\n' >"$PYTHON_POISON_MARKER" + return 97 +} +` + +const brokenDateFunction = ` +date() { + printf 'invoked\n' >"$DATE_BACKEND_MARKER" + return 69 +} +` + +const garbageDateFunction = ` +date() { + printf 'invoked\n' >"$DATE_BACKEND_MARKER" + printf 'garbage\n' +} +` + +const recordingNativeDateFunction = ` +date() { + printf 'invoked\n' >"$DATE_BACKEND_MARKER" + command date "$@" +} +` + +func TestDocFreshnessDoesNotRequirePython(t *testing.T) { + run := runDocFreshness(t, "2026-01-15", "2026-01-31", "90") + if run.err != nil { + t.Fatalf("check-doc-freshness failed without Python: %v\n%s", run.err, run.output) + } + if run.pythonInvoked { + t.Fatalf("check-doc-freshness invoked python3:\n%s", run.output) + } + for _, want := range []string{ + "PASS: Last reviewed marker is current: 2026-01-15 (16 days old)", + "PASSED: Reference doc freshness markers are current and checkable", + } { + if !strings.Contains(run.output, want) { + t.Fatalf("missing %q:\n%s", want, run.output) + } + } +} + +func TestDocFreshnessBashProbeIgnoresStartupEnvironment(t *testing.T) { + if runtime.GOOS != "windows" { + t.Skip("Git Bash discovery is Windows-specific") + } + + poison := filepath.Join(t.TempDir(), "poison.sh") + if err := os.WriteFile(poison, []byte("exit 97\n"), 0o600); err != nil { + t.Fatalf("write startup poison: %v", err) + } + t.Setenv("BASH_ENV", poison) + t.Setenv("ENV", poison) + + if bash := docFreshnessBash(t); bash == "" { + t.Fatal("docFreshnessBash returned an empty executable") + } +} + +func TestDocFreshnessPreservesDateDiagnostics(t *testing.T) { + tests := []struct { + name string + reviewed string + today string + maxAge string + want string + }{ + { + name: "invalid date", + reviewed: "2026-02-30", + today: "2026-03-01", + maxAge: "90", + want: "FAIL: invalid Last reviewed date: 2026-02-30", + }, + { + name: "year zero", + reviewed: "0000-01-01", + today: "2026-03-01", + maxAge: "90", + want: "FAIL: invalid Last reviewed date: 0000-01-01", + }, + { + name: "future date", + reviewed: "2026-03-02", + today: "2026-03-01", + maxAge: "90", + want: "FAIL: Last reviewed date is in the future: 2026-03-02", + }, + { + name: "stale date", + reviewed: "2025-01-01", + today: "2026-03-01", + maxAge: "30", + want: "FAIL: Last reviewed date is stale: 2025-01-01", + }, + } + + for _, test := range tests { + t.Run(test.name, func(t *testing.T) { + run := runDocFreshness(t, test.reviewed, test.today, test.maxAge) + if exitCode(run.err) != 1 { + t.Fatalf("exit = %d, want 1; error=%v\n%s", exitCode(run.err), run.err, run.output) + } + if run.pythonInvoked { + t.Fatalf("check-doc-freshness invoked python3:\n%s", run.output) + } + if !strings.Contains(run.output, test.want) { + t.Fatalf("missing %q:\n%s", test.want, run.output) + } + }) + } +} + +func TestDocFreshnessPreservesISODateBoundaries(t *testing.T) { + for _, value := range []string{"0001-01-01", "2000-02-29", "9999-12-31"} { + t.Run(value, func(t *testing.T) { + run := runDocFreshness(t, value, value, "90") + if run.err != nil { + t.Fatalf("check-doc-freshness rejected supported boundary %s: %v\n%s", value, run.err, run.output) + } + if !strings.Contains(run.output, "PASS: Last reviewed marker is current: "+value+" (0 days old)") { + t.Fatalf("missing boundary date result for %s:\n%s", value, run.output) + } + }) + } +} + +func TestDocFreshnessUsesProlepticGregorianLeapRules(t *testing.T) { + tests := []struct { + name string + reviewed string + today string + wantExit int + want string + }{ + { + name: "common century", + reviewed: "1900-02-28", + today: "1900-03-01", + wantExit: 0, + want: "PASS: Last reviewed marker is current: 1900-02-28 (1 days old)", + }, + { + name: "leap century", + reviewed: "2000-02-28", + today: "2000-03-01", + wantExit: 0, + want: "PASS: Last reviewed marker is current: 2000-02-28 (2 days old)", + }, + { + name: "ordinary leap year", + reviewed: "2024-02-28", + today: "2024-03-01", + wantExit: 0, + want: "PASS: Last reviewed marker is current: 2024-02-28 (2 days old)", + }, + { + name: "invalid common-century leap day", + reviewed: "1900-02-29", + today: "1900-03-01", + wantExit: 1, + want: "FAIL: invalid Last reviewed date: 1900-02-29", + }, + { + name: "invalid month zero", + reviewed: "2026-00-01", + today: "2026-03-01", + wantExit: 1, + want: "FAIL: invalid Last reviewed date: 2026-00-01", + }, + } + + for _, test := range tests { + t.Run(test.name, func(t *testing.T) { + run := runDocFreshness(t, test.reviewed, test.today, "90") + if exitCode(run.err) != test.wantExit { + t.Fatalf("exit = %d, want %d; error=%v\n%s", exitCode(run.err), test.wantExit, run.err, run.output) + } + if run.pythonInvoked { + t.Fatalf("check-doc-freshness invoked python3:\n%s", run.output) + } + if !strings.Contains(run.output, test.want) { + t.Fatalf("missing %q:\n%s", test.want, run.output) + } + }) + } +} + +func TestDocFreshnessUsesNativeDefaultTodayProvider(t *testing.T) { + run := runDocFreshnessWithDefaultToday(t, "0001-01-01", "4000000", recordingNativeDateFunction) + if run.err != nil { + t.Fatalf("check-doc-freshness failed with native default TODAY: %v\n%s", run.err, run.output) + } + if !run.dateInvoked { + t.Fatalf("check-doc-freshness did not invoke native date for the default TODAY value:\n%s", run.output) + } + if run.pythonInvoked { + t.Fatalf("check-doc-freshness invoked python3:\n%s", run.output) + } + if !strings.Contains(run.output, "PASSED: Reference doc freshness markers are current and checkable") { + t.Fatalf("missing successful default-TODAY result:\n%s", run.output) + } +} + +func TestDocFreshnessReportsUnavailableTodayProvider(t *testing.T) { + run := runDocFreshnessWithDefaultToday(t, "2026-01-15", "90", brokenDateFunction) + if exitCode(run.err) != 2 { + t.Fatalf("exit = %d, want 2; error=%v\n%s", exitCode(run.err), run.err, run.output) + } + if !run.dateInvoked { + t.Fatalf("check-doc-freshness did not invoke date for the default TODAY value:\n%s", run.output) + } + if !strings.Contains(run.output, "ERROR: check-doc-freshness could not determine today's date") { + t.Fatalf("missing explicit TODAY provider diagnostic:\n%s", run.output) + } + if strings.Contains(run.output, "invalid Last reviewed date") { + t.Fatalf("broken TODAY provider was mislabeled as document data:\n%s", run.output) + } +} + +func TestDocFreshnessReportsInvalidTodayProviderOutput(t *testing.T) { + run := runDocFreshnessWithDefaultToday(t, "2026-01-15", "90", garbageDateFunction) + if exitCode(run.err) != 2 { + t.Fatalf("exit = %d, want 2; error=%v\n%s", exitCode(run.err), run.err, run.output) + } + if !run.dateInvoked { + t.Fatalf("check-doc-freshness did not invoke date for the default TODAY value:\n%s", run.output) + } + if !strings.Contains(run.output, "ERROR: date returned an invalid current date: garbage") { + t.Fatalf("missing invalid-provider-output diagnostic:\n%s", run.output) + } + if strings.Contains(run.output, "DOC_FRESHNESS_TODAY") { + t.Fatalf("provider output was mislabeled as an override:\n%s", run.output) + } +} + +func TestDocFreshnessReportsInvalidTodayOverride(t *testing.T) { + run := runDocFreshness(t, "2026-01-15", "garbage", "90") + if exitCode(run.err) != 2 { + t.Fatalf("exit = %d, want 2; error=%v\n%s", exitCode(run.err), run.err, run.output) + } + if run.dateInvoked { + t.Fatalf("check-doc-freshness invoked date despite an explicit TODAY override:\n%s", run.output) + } + if !strings.Contains(run.output, "ERROR: invalid DOC_FRESHNESS_TODAY date: garbage") { + t.Fatalf("missing invalid-override diagnostic:\n%s", run.output) + } +} + +func runDocFreshness(t *testing.T, reviewed, today, maxAge string) freshnessRun { + t.Helper() + return runDocFreshnessWithDateFunction(t, reviewed, today, maxAge, "") +} + +func runDocFreshnessWithDateFunction(t *testing.T, reviewed, today, maxAge, dateFunction string) freshnessRun { + t.Helper() + return runDocFreshnessProcess(t, reviewed, &today, maxAge, dateFunction) +} + +func runDocFreshnessWithDefaultToday(t *testing.T, reviewed, maxAge, dateFunction string) freshnessRun { + t.Helper() + return runDocFreshnessProcess(t, reviewed, nil, maxAge, dateFunction) +} + +func runDocFreshnessProcess(t *testing.T, reviewed string, today *string, maxAge, dateFunction string) freshnessRun { + t.Helper() + bash := docFreshnessBash(t) + + root := newDocFreshnessFixture(t, reviewed) + markerDir := t.TempDir() + pythonMarker := filepath.Join(markerDir, "python-invoked") + dateMarker := filepath.Join(markerDir, "date-invoked") + bashEnvironment := filepath.Join(t.TempDir(), "bash-env.sh") + if err := os.WriteFile(bashEnvironment, []byte(pythonPoisonFunction+dateFunction), 0o600); err != nil { + t.Fatalf("write Python poison environment: %v", err) + } + + cmd := exec.Command( + bash, + "--noprofile", + "--norc", + msysPath(filepath.Join(root, "scripts", "check-doc-freshness.sh")), + ) + cmd.Dir = root + cmd.Env = []string{ + "PATH=/usr/bin:/bin", + "HOME=" + msysPath(t.TempDir()), + "LC_ALL=C", + "LANG=C", + "BASH_ENV=" + msysPath(bashEnvironment), + "ENV=", + "DATE_BACKEND_MARKER=" + msysPath(dateMarker), + "DOC_FRESHNESS_MAX_AGE_DAYS=" + maxAge, + "PYTHON_POISON_MARKER=" + msysPath(pythonMarker), + } + if today != nil { + cmd.Env = append(cmd.Env, "DOC_FRESHNESS_TODAY="+*today) + } + output, runErr := cmd.CombinedOutput() + return freshnessRun{ + output: string(output), + err: runErr, + pythonInvoked: docFreshnessMarkerExists(t, pythonMarker), + dateInvoked: docFreshnessMarkerExists(t, dateMarker), + } +} + +func docFreshnessBash(t *testing.T) string { + t.Helper() + + if runtime.GOOS != "windows" { + bash, err := exec.LookPath("bash") + if err != nil { + t.Fatalf("bash is required to exercise check-doc-freshness.sh: %v", err) + } + return bash + } + + git, err := exec.LookPath("git.exe") + if err != nil { + t.Fatalf("Git for Windows is required to exercise check-doc-freshness.sh: %v", err) + } + execPathCommand := exec.Command(git, "--exec-path") + execPathCommand.Env = docFreshnessProbeEnv() + execPathOutput, err := execPathCommand.CombinedOutput() + if err != nil { + t.Fatalf("locate the Git for Windows installation: %v: %s", err, strings.TrimSpace(string(execPathOutput))) + } + execPath := filepath.Clean(strings.TrimSpace(string(execPathOutput))) + if !filepath.IsAbs(execPath) { + t.Fatalf("Git for Windows returned a non-absolute exec path: %q", execPath) + } + gitRoot := filepath.Clean(filepath.Join(execPath, "..", "..", "..")) + candidates := []string{ + filepath.Join(gitRoot, "bin", "bash.exe"), + filepath.Join(gitRoot, "usr", "bin", "bash.exe"), + } + var diagnostics []string + for _, candidate := range candidates { + if _, err := os.Stat(candidate); err != nil { + diagnostics = append(diagnostics, fmt.Sprintf("%s: %v", candidate, err)) + continue + } + probe := exec.Command(candidate, "--noprofile", "--norc", "-c", ` +export BASH_ENV= +export ENV= +PATH=/usr/bin:/bin +export PATH +case "$(uname -s)" in + MINGW*|MSYS*) command -v date >/dev/null ;; + *) exit 1 ;; +esac +`) + probe.Env = docFreshnessProbeEnv() + if output, err := probe.CombinedOutput(); err == nil { + return candidate + } else { + diagnostics = append(diagnostics, fmt.Sprintf("%s: %v: %s", candidate, err, strings.TrimSpace(string(output)))) + } + } + + t.Fatalf("a working Git Bash date environment is required: %s", strings.Join(diagnostics, "; ")) + return "" +} + +func docFreshnessMarkerExists(t *testing.T, path string) bool { + t.Helper() + + _, err := os.Stat(path) + if err == nil { + return true + } + if !os.IsNotExist(err) { + t.Fatalf("inspect marker %s: %v", path, err) + } + return false +} + +func newDocFreshnessFixture(t *testing.T, reviewed string) string { + t.Helper() + + root := t.TempDir() + repoRoot := sourceRepoRoot(t) + script, err := os.ReadFile(filepath.Join(repoRoot, "scripts", "check-doc-freshness.sh")) + if err != nil { + t.Fatalf("read check-doc-freshness.sh: %v", err) + } + writeFixtureFile(t, root, "scripts/check-doc-freshness.sh", string(script)) + + var inventory strings.Builder + for _, document := range freshnessDocuments { + inventoryRef := strings.TrimPrefix(strings.TrimPrefix(document.path, "docs/"), "engdocs/") + fmt.Fprintf(&inventory, "- `%s`\n", inventoryRef) + writeFixtureFile(t, root, document.path, fmt.Sprintf( + "Last reviewed: %s\nFreshness source: %s\n", + reviewed, + strings.Join(document.sources, ";"), + )) + for _, source := range document.sources { + createFreshnessSource(t, root, source) + } + } + writeFixtureFile(t, root, "engdocs/DOC_INVENTORY.md", inventory.String()) + return root +} + +func createFreshnessSource(t *testing.T, root, source string) { + t.Helper() + + if strings.HasSuffix(source, "/") { + if err := os.MkdirAll(filepath.Join(root, filepath.FromSlash(source)), 0o755); err != nil { + t.Fatalf("create source directory %s: %v", source, err) + } + return + } + + source = strings.ReplaceAll(source, "*", "fixture") + source = strings.ReplaceAll(source, "?", "x") + writeFixtureFile(t, root, source, "") +} + +func writeFixtureFile(t *testing.T, root, relative, body string) { + t.Helper() + + path := filepath.Join(root, filepath.FromSlash(relative)) + if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil { + t.Fatalf("create parent for %s: %v", relative, err) + } + if err := os.WriteFile(path, []byte(body), 0o600); err != nil { + t.Fatalf("write %s: %v", relative, err) + } +} + +func docFreshnessProbeEnv() []string { + env := make([]string, 0, len(os.Environ())+3) + for _, entry := range os.Environ() { + key, _, ok := strings.Cut(entry, "=") + if !ok { + continue + } + upperKey := strings.ToUpper(key) + if upperKey == "BASH_ENV" || upperKey == "ENV" || strings.HasPrefix(upperKey, "GIT_") { + continue + } + env = append(env, entry) + } + return append(env, "BASH_ENV=", "ENV=", "GIT_EXEC_PATH=") +} diff --git a/scripts/docs.md b/scripts/docs.md index 358956959..71d4c94c2 100644 --- a/scripts/docs.md +++ b/scripts/docs.md @@ -50,6 +50,12 @@ make check-docs The script currently checks the reference docs named in `engdocs/DOC_INVENTORY.md`: `CONFIG.md`, `SETUP.md`, `ADO_CONFIG.md`, `JSON_SCHEMA.md`, `RECOVERY.md`, `ERROR_HANDLING.md`, `LINTING.md`, and `design/otel/otel-data-model.md`. Each doc must be listed in the inventory, include a recent `Last reviewed:` marker, include a `Freshness source:` marker, and name source paths or globs that exist in the repository. Set `DOC_FRESHNESS_MAX_AGE_DAYS` to override the default 90-day review window. Set `DOC_FRESHNESS_TODAY=YYYY-MM-DD` when testing date behaviour. +Date validation uses Bash integer arithmetic over the proleptic Gregorian +calendar, preserves the `0001-01-01` through `9999-12-31` ISO domain, and does +not require Python or platform-specific date parsing. The native `date` command +is used only to supply today's value when `DOC_FRESHNESS_TODAY` is unset. Pull +requests exercise the real process boundary on Linux, macOS, and Git Bash on +Windows. ### How it fits into the larger codebase