docs: add dnstraverse reference spec, rework design, and golden tooling

Reconstructed behaviour spec of dns.squish.net / Ruby dnstraverse 0.1.14
(inputs, traversal semantics, probability model, verbatim output formats,
sourced from the live site, Wayback captures, and the Ruby source), the
engine rework design that maps it onto Go, a point-in-time codebase review,
golden reference captures, and tools/golden/run-reference.sh for running
the reference Ruby engine locally (clone is gitignored, GPL-3 dev-only).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
Gary Hansen
2026-07-07 21:41:47 +10:00
co-authored by Claude Fable 5
parent c74b218349
commit af15c9c2d4
18 changed files with 2842 additions and 0 deletions
+17
View File
@@ -0,0 +1,17 @@
#!/bin/sh
# Run the reference Ruby dnstraverse — the exact engine behind dns.squish.net.
# Used to generate golden outputs for comparing ExploreDNS behaviour.
#
# Setup (one-time, no sudo needed):
# gem install dnsruby -v 1.72.4 --user-install --no-document
# gem install logger -v 1.6.6 --user-install --no-document
#
# The tools/dnstraverse-ruby clone is gitignored (GPL-3, dev-only). If missing:
# git clone https://github.com/squish/dnstraverse tools/dnstraverse-ruby
# then comment out the `require 'rdoc/usage'` line in bin/dnstraverse
# (rdoc/usage was removed from Ruby after 1.8).
#
# Usage: tools/golden/run-reference.sh [dnstraverse options] DOMAIN
set -eu
DIR="$(cd "$(dirname "$0")/../dnstraverse-ruby" && pwd)"
exec ruby -I"$DIR/lib" "$DIR/bin/dnstraverse" "$@"