Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
42 changes: 42 additions & 0 deletions .github/workflows/agda-citations.yml
Original file line number Diff line number Diff line change
@@ -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
80 changes: 80 additions & 0 deletions scripts/check-agda-citations.sh
Original file line number Diff line number Diff line change
@@ -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 <echo-types checkout>
# 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
Comment on lines +29 to +30

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Traverse nested source directories when extracting citations

When a cited lemma appears in a Julia file below a subdirectory such as src/foo/bar.jl, this glob never examines it. The offline test has the same limitation because it only iterates the immediate results of readdir(srcdir), so the fixture can omit that citation and both Pkg.test() and the workflow's verify command still pass. Recursively enumerate .jl files under src/ in both implementations.

Useful? React with 👍 / 👎.

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Confirmed. Both the script and the testset read only the top level of src/. This PR was merged before the review arrived, so the fix is in a follow-up PR: find in the script and walkdir in the testset. An unlisted citation in src/nested/control.jl now fails both checks.


Generated by Claude Code

}

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 <echo-types checkout>" >&2
exit 2
;;
esac
4 changes: 2 additions & 2 deletions src/EchoTypes.jl
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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 →
Expand Down
69 changes: 69 additions & 0 deletions test/agda-citations.txt
Original file line number Diff line number Diff line change
@@ -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
24 changes: 24 additions & 0 deletions test/runtests.jl
Original file line number Diff line number Diff line change
Expand Up @@ -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