From 1dd5aab6173f49f4e818b6a42ee2f3051fe24c70 Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 14 Nov 2026 16:54:30 +0000 Subject: [PATCH 1/2] docs(src): fix two Agda citations that name no echo-types lemma A section comment called EchoNoSectionGeneric a generalisation of `no-section`, but echo-types declares no lemma of that name; the residue result it means is `no-section-collapse-to-residue` (EchoResidue.agda:63). A second comment set the prose label "audience-facing" in backticks, which reads as a lemma name. Found by checking every cited name against echo-types dedda75. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_0136P7ZnB2Fzqf8br8DGDD4k --- src/EchoTypes.jl | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/EchoTypes.jl b/src/EchoTypes.jl index 600a1a9..37c0d1f 100644 --- a/src/EchoTypes.jl +++ b/src/EchoTypes.jl @@ -581,7 +581,7 @@ function injective_fibres_proj_unique(f, domain) end # ====================================================================== -# EchoNoSectionGeneric.agda — generalisation of `no-section` +# EchoNoSectionGeneric.agda — generalisation of `no-section-collapse-to-residue` (EchoResidue.agda) # # For ANY `lower : A → R` with two distinct elements collapsing to the # same residue, no section exists. The existing @@ -790,7 +790,7 @@ end # Echo carries the lost tag, the residue lowering forgets it. The # audience-side framing differs; the formalism is one shape. Each # Julia record + theorem set below mirrors a named Agda module — -# names match the Agda `audience-facing` headlines exactly so the +# names match the Agda audience-facing headlines exactly so the # Julia↔Agda lookup remains 1:1. # # Security uses a different shape: per-region `exit : Resource → From 1c50d5f3ae9cbc51ae78af5e0740df475b7005a0 Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 14 Nov 2026 16:54:30 +0000 Subject: [PATCH 2/2] test: check every cited Agda lemma against echo-types EchoTypes cites the echo-types lemmas it mirrors as backticked names, and nothing checked that those names exist. A backticked hyphenated name cannot be a Julia identifier, so each one is taken to be an Agda name. - test/agda-citations.txt records the 62 cited names and the echo-types commit they were checked against (dedda75). - A new testset (offline) fails when src/ cites a name that the fixture does not list, or the fixture lists a name src/ no longer cites. - scripts/check-agda-citations.sh verify also checks that each name is declared in an .agda file; the new agda-citations workflow runs it against echo-types at the pinned commit. The check is name-level: it proves each cited lemma exists, not that the Julia shadow agrees with it. Pkg.test(): 306 pass. Negative controls: an unlisted citation fails both the testset and the script, and a renamed fixture entry fails the script. actionlint is clean on the workflow. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_0136P7ZnB2Fzqf8br8DGDD4k --- .github/workflows/agda-citations.yml | 42 +++++++++++++++ scripts/check-agda-citations.sh | 80 ++++++++++++++++++++++++++++ test/agda-citations.txt | 69 ++++++++++++++++++++++++ test/runtests.jl | 24 +++++++++ 4 files changed, 215 insertions(+) create mode 100644 .github/workflows/agda-citations.yml create mode 100755 scripts/check-agda-citations.sh create mode 100644 test/agda-citations.txt diff --git a/.github/workflows/agda-citations.yml b/.github/workflows/agda-citations.yml new file mode 100644 index 0000000..f8cb0df --- /dev/null +++ b/.github/workflows/agda-citations.yml @@ -0,0 +1,42 @@ +# SPDX-License-Identifier: MPL-2.0 +# Checks that every echo-types lemma cited in src/ (test/agda-citations.txt) +# is still declared in hyperpolymath/echo-types at the pinned commit. The +# Julia suite checks the fixture against src/ offline; this job adds the +# check against the Agda source. Bump the pin in the fixture to re-check +# against a newer echo-types. +name: "Agda citation check" +on: + push: + branches: [main] + pull_request: + workflow_dispatch: +permissions: + contents: read +concurrency: + group: agda-citations-${{ github.ref }} + cancel-in-progress: true +jobs: + citations: + runs-on: ubuntu-24.04 + timeout-minutes: 10 + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + - name: Read the pinned echo-types commit + id: pin + run: | + commit=$(sed -n 's/^# echo-types-commit: \([0-9a-f]\{40\}\)$/\1/p' test/agda-citations.txt) + if [ -z "$commit" ]; then + echo "test/agda-citations.txt has no '# echo-types-commit: <40-hex sha>' line" >&2 + exit 1 + fi + echo "commit=$commit" >> "$GITHUB_OUTPUT" + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + repository: hyperpolymath/echo-types + ref: ${{ steps.pin.outputs.commit }} + path: echo-types + persist-credentials: false + - name: Check the cited names against echo-types + run: sh scripts/check-agda-citations.sh verify echo-types diff --git a/scripts/check-agda-citations.sh b/scripts/check-agda-citations.sh new file mode 100755 index 0000000..d611b90 --- /dev/null +++ b/scripts/check-agda-citations.sh @@ -0,0 +1,80 @@ +#!/bin/sh +# SPDX-License-Identifier: MPL-2.0 +# +# check-agda-citations.sh: keep EchoTypes' Agda citations true. +# +# The Julia docstrings and comments cite the echo-types lemmas they mirror as +# backticked names, for example `echo-intro`. A backticked name that contains +# a hyphen cannot be a Julia identifier, so it is taken to be an Agda name. +# test/agda-citations.txt records every such name and the echo-types commit +# they were checked against. +# +# Usage: +# scripts/check-agda-citations.sh extract +# Print the cited names found in src/, one per line, sorted. +# scripts/check-agda-citations.sh verify +# Check that the fixture matches src/, and that every name in it is +# declared in an .agda file of the checkout. Exit 0 when both hold, +# 1 when either fails, 2 on a setup error. +# +# Scope: ASCII names only (letters, digits, hyphens). Names with Unicode or +# other symbols are not checked. The check is name-level: it proves the cited +# lemma exists, not that the Julia shadow agrees with it. +set -eu + +ROOT=$(CDPATH= cd -- "$(dirname -- "$0")/.." && pwd) +FIXTURE="$ROOT/test/agda-citations.txt" + +extract() { + grep -ohE '`[A-Za-z][A-Za-z0-9]*(-[A-Za-z0-9]+)+`' "$ROOT"/src/*.jl \ + | tr -d '`' | LC_ALL=C sort -u +} + +fixture_names() { + grep -vE '^[[:space:]]*(#|$)' "$FIXTURE" | LC_ALL=C sort -u +} + +case "${1:-}" in + extract) + extract + ;; + verify) + AGDA_DIR="${2:-}" + if [ -z "$AGDA_DIR" ] || [ ! -d "$AGDA_DIR" ]; then + echo "check-agda-citations: give an echo-types checkout directory" >&2 + exit 2 + fi + if [ ! -f "$FIXTURE" ]; then + echo "check-agda-citations: missing $FIXTURE" >&2 + exit 2 + fi + fail=0 + tmp_src=$(mktemp); tmp_fix=$(mktemp) + trap 'rm -f "$tmp_src" "$tmp_fix"' EXIT + extract >"$tmp_src" + fixture_names >"$tmp_fix" + if ! diff -u "$tmp_fix" "$tmp_src" >/dev/null; then + echo "FAIL: test/agda-citations.txt does not match the names cited in src/:" >&2 + diff -u "$tmp_fix" "$tmp_src" | sed -n '3,$p' | grep -E '^[+-]' >&2 || true + fail=1 + fi + missing=0 + while IFS= read -r name; do + if ! grep -rqE "^[[:space:]]*${name}[[:space:]]+:" --include='*.agda' "$AGDA_DIR"; then + echo "MISSING in echo-types: $name" >&2 + missing=$((missing + 1)) + fi + done <"$tmp_fix" + total=$(wc -l <"$tmp_fix" | tr -d ' ') + if [ "$missing" -ne 0 ]; then + echo "FAIL: $missing of $total cited Agda names are not declared in $AGDA_DIR" >&2 + fail=1 + fi + [ "$fail" -eq 0 ] && echo "PASS: $total cited Agda names match the fixture and are declared in echo-types" + exit "$fail" + ;; + *) + echo "usage: $0 extract | verify " >&2 + exit 2 + ;; +esac diff --git a/test/agda-citations.txt b/test/agda-citations.txt new file mode 100644 index 0000000..b188c76 --- /dev/null +++ b/test/agda-citations.txt @@ -0,0 +1,69 @@ +# SPDX-License-Identifier: MPL-2.0 +# Agda names cited in src/ (backticked, hyphenated), one per line. +# Checked against hyperpolymath/echo-types at the commit below by +# scripts/check-agda-citations.sh; CI re-checks it on every change. +# Regenerate the list with: scripts/check-agda-citations.sh extract +# echo-types-commit: dedda7505e8418d81742a588060044e31395ea1f + +Echo-comp-iso-from +Echo-comp-iso-to +FiberSize-fin +aggregate-values +aggregation-as-fold +audit-no-recovery-at +bennett-reversible +blur-collapses-perturbations-at +bool-indexed-nat-sampling +bool-over-nat-provenance +bool-perturbed-nat-sensitivity +cancel-iso-from +cancel-iso-to +const-fibre-section +echo-carries-perturbation +echo-carries-which-index +echo-false +echo-intro +echo-to-residue +echo-true +echoes-distinguish-tag +entropy-shadow +entropy-shadow-blind +equiv-fibre-center +equiv-fibre-proj-unique +equiv-implies-injective +exit-collapses-at +f-inv +fiber-erasure-bound +gap-paired +identity-l +identity-r +injective-fibres-proj-unique +inv-f +landauer-bound +landauer-collapse +ll-encoding-gap +map-over +map-over-comp +map-over-id +mode-equality-strictly-finer-at-linear +no-canonical-disaggregation-of +no-section-collapse-to-residue +no-section-of-collapsing-map +no-section-weaken +no-section-when-non-injective-at-y +ofs-witness +pairSum-collapses +pairSum-is-fold +pairSum-non-injective +projection-fibre-iso +provenance-collapses-at +region-exit-audit-instance +residue-collapses-tags +residue-loses-index +residue-loses-perturbation +shannon-shadow +source-no-section +strict-weakening-collapse +support-collapses-at +trivial-encoding +trivial-encoding-has-section diff --git a/test/runtests.jl b/test/runtests.jl index c1cefb8..ccf18f0 100644 --- a/test/runtests.jl +++ b/test/runtests.jl @@ -536,4 +536,28 @@ using Test # exhibit, so the witness correctly does not fire. @test !no_canonical_disaggregation_of(identity, ledger1(), ledger2()) end + + @testset "Agda citations: every cited lemma is recorded (test/agda-citations.txt)" begin + # A backticked, hyphenated name in src/ cannot be a Julia identifier, + # so it is an echo-types lemma. Each one must be listed in the fixture, + # which CI checks against echo-types (scripts/check-agda-citations.sh). + # This offline half fails when a citation is added or removed without + # updating the fixture. + cite = r"`([A-Za-z][A-Za-z0-9]*(?:-[A-Za-z0-9]+)+)`" + srcdir = joinpath(@__DIR__, "..", "src") + cited = Set{String}() + for f in readdir(srcdir; join = true) + endswith(f, ".jl") || continue + for m in eachmatch(cite, read(f, String)) + push!(cited, m.captures[1]) + end + end + lines = readlines(joinpath(@__DIR__, "agda-citations.txt")) + recorded = Set(strip(l) for l in lines + if !isempty(strip(l)) && !startswith(strip(l), "#")) + @test !isempty(cited) + @test sort(collect(setdiff(cited, recorded))) == String[] + @test sort(collect(setdiff(recorded, cited))) == String[] + @test any(l -> startswith(l, "# echo-types-commit: "), lines) + end end