ci: Restore ToC check for ADRs/RFCs (#9180)

* Import presubmit TOC check script from master and fix warning

Signed-off-by: Thane Thomson <connect@thanethomson.com>

* Fix misspelled ADR link discovered by presubmit script

Signed-off-by: Thane Thomson <connect@thanethomson.com>

* Restore docs-toc workflow

Signed-off-by: Thane Thomson <connect@thanethomson.com>

* Create makefile target for docs ToC check

Signed-off-by: Thane Thomson <connect@thanethomson.com>

* Use makefile target in CI workflow for docs ToC check

Signed-off-by: Thane Thomson <connect@thanethomson.com>

.github/workflows/docs-toc.yml

@@ -1,21 +1,20 @@
-# TODO(thane): Re-enable once we've pulled in the ADRs and RFCs from master.
 # Verify that important design docs have ToC entries.
-#name: Check documentation ToC
-#on:
-#  pull_request:
-#    push:
-#      branches:
-#        - main
-#
-#jobs:
-#  check:
-#    runs-on: ubuntu-latest
-#    steps:
-#      - uses: actions/checkout@v3
-#      - uses: technote-space/get-diff-action@v6
-#        with:
-#          PATTERNS: |
-#            docs/architecture/**
-#            docs/rfc/**
-#      - run: ./docs/presubmit.sh
-#        if: env.GIT_DIFF
+name: Check documentation ToC
+on:
+  pull_request:
+    push:
+      branches:
+        - main
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: technote-space/get-diff-action@v6
+        with:
+          PATTERNS: |
+            docs/architecture/**
+            docs/rfc/**
+      - run: make check-docs-toc
+        if: env.GIT_DIFF

Makefile

@@ -289,6 +289,11 @@ sync-docs:
 	aws cloudfront create-invalidation --distribution-id ${CF_DISTRIBUTION_ID} --profile terraform --path "/*" ;
 .PHONY: sync-docs
 
+# Verify that important design docs have ToC entries.
+check-docs-toc:
+	@./docs/presubmit.sh
+.PHONY: check-docs-toc
+
 ###############################################################################
 ###                            Docker image                                 ###
 ###############################################################################

docs/architecture/README.md

@@ -77,7 +77,7 @@ Note the context/background should be written in the present tense.
 - [ADR-006: Trust-Metric](./adr-006-trust-metric.md)
 - [ADR-024: Sign-Bytes](./adr-024-sign-bytes.md)
 - [ADR-035: Documentation](./adr-035-documentation.md)
-- [ADR-039: Peer-Behaviour](./adr-039-peer-behavior.md)
+- [ADR-039: Peer-Behaviour](./adr-039-peer-behaviour.md)
 - [ADR-060: Go-API-Stability](./adr-060-go-api-stability.md)
 - [ADR-061: P2P-Refactor-Scope](./adr-061-p2p-refactor-scope.md)
 - [ADR-065: Custom Event Indexing](./adr-065-custom-event-indexing.md)

docs/presubmit.sh

@@ -0,0 +1,39 @@
+#!/bin/bash
+#
+# This script verifies that each document in the docs and architecture
+# directory has a corresponding table-of-contents entry in its README file.
+#
+# This can be run manually from the command line.
+# It is also run in CI via the docs-toc.yml workflow.
+#
+set -euo pipefail
+
+readonly base="$(dirname $0)"
+cd "$base"
+
+readonly workdir="$(mktemp -d)"
+trap "rm -fr -- '$workdir'" EXIT
+
+checktoc() {
+    local dir="$1"
+    local tag="$2"'-*-*'
+    local out="$workdir/${dir}.out.txt"
+    (
+        cd "$dir" >/dev/null
+        find . -maxdepth 1 -type f -name "$tag" -not -exec grep -q "({})" README.md ';' -print
+    ) > "$out"
+    if [[ -s "$out" ]] ; then
+        echo "-- The following files in $dir lack a ToC entry:
+"
+        cat "$out"
+        return 1
+    fi
+}
+
+err=0
+
+# Verify that each RFC and ADR has a ToC entry in its README file.
+checktoc architecture adr || ((err++))
+checktoc rfc rfc || ((err++))
+
+exit $err