Adds `docsredirectscheck`, a lint for `docs/redirects.json`, the list of
redirects the documentation website applies for pages that have moved or
been removed. It runs as `make lint/docs-redirects`, part of `make lint`
and `make lint-light`, so a bad redirect is caught in the pull request
that adds it. The file does not exist yet, and the check passes while it
is absent, so this can merge before or after the file does.
## What it checks
It fails on:
- a file that is not a JSON array of well-formed rules (`source`,
`destination`, optional boolean `permanent`, no unknown fields);
- syntax outside the supported subset: a source under `/docs/`, written
as an exact path, a trailing `/:name*`, or a trailing `/:name(.*)`, with
no version segment such as `/@main`;
- an internal destination that is not a page in `docs/manifest.json`, or
a pattern destination that points into a section with no pages or uses a
parameter the source does not define;
- a source that matches a live page, which would hide it;
- duplicate sources, chains (a destination that is another rule's
source), and loops.
It warns, and never fails, when a pull request removes routes from
`docs/manifest.json` while `docs/redirects.json` is unchanged and does
not already cover them. Pages are sometimes removed on purpose. The
comparison is by route rather than by file, so a rename that keeps its
URL (for example `admin/foo/index.md` to `admin/foo.md`) does not warn.
In GitHub Actions the warning is an annotation on the manifest. The base
is the first parent of the PR merge commit, the same approach
`scripts/check_emdash.sh` uses, and the warning is skipped with a note
when it is not available.
Routes are derived from `docs/manifest.json` the way the docs website
derives them, including its plain-suffix stripping of `README.md`,
`index.md`, and `.md`, so the check and the site agree about which pages
exist. `scripts/docsredirectscheck/README.md` documents the rule format
and the limits.
## Testing
- 128 Go tests pass under Go 1.26.5: route derivation, every failing and
passing rule shape, the absent-file pass, exit codes, and the warning
logic through a fake git reader.
- I checked that the tests can fail by breaking the code 16 ways (for
example dropping the `index.md` suffix, disabling the shadow check,
reporting loops twice). All 16 were caught. That run found one gap, a
missing test for "redirects file changed", which is now covered.
- Ran against the repository's real `docs/manifest.json`: passes with no
redirects file, and a file with one of each failure class reports every
problem with the rule index, the source, and how to fix it.
- Ran the warning against real git history: it warns for an older base,
stays silent at `HEAD`, and skips with a note for an unknown revision.
- Lint: `golangci-lint` v2.0.2 built with Go 1.26.5 against the
repository config reports 0 issues. `paralleltestctx`, `intxcheck`,
`typos` 1.46.1, `gofumpt` and `gci` (through `make fmt/go`), and `go
vet` pass.
CI: `lint` (which runs this check), `fmt`, `title`, and the Go and
end-to-end test jobs pass. The `gen` job, and so `required`, fails on
this branch for a reason this PR does not touch: `main` is failing it
too. `docs/manifest/generated/cli.json` has not been regenerated for the
`coder sharing` commands that landed in the latest commit on `main`. It
should clear once `main` is fixed and merged into this branch.
Not run locally: the full `make lint` and `make pre-commit`. The local
hooks are opt-in and were off. The annotation output has been exercised
by unit tests and a local run with `GITHUB_ACTIONS=true`, but not yet on
a real pull request merge commit; this PR does not change the manifest,
so it will not exercise it either. No workflow change is needed, because
the `lint` job already runs `make lint` for any change that is not
offlinedocs-only.
---
🤖 Built with AI assistance.
170 lines
5.2 KiB
Go
170 lines
5.2 KiB
Go
// Command docsredirectscheck validates docs/redirects.json, the list of
|
|
// redirects the documentation website applies for pages that have moved or
|
|
// been removed.
|
|
//
|
|
// Each rule is {"source", "destination", "permanent"?}. Sources and internal
|
|
// destinations are full site paths starting with /docs/, written in the small
|
|
// subset of Next.js path syntax the website accepts: an exact path, a trailing
|
|
// "/:name*", or a trailing "/:name(.*)". A destination may also be an
|
|
// http(s) URL.
|
|
//
|
|
// It fails when:
|
|
//
|
|
// - the file is not a JSON array of well-formed rules;
|
|
// - a source or destination is outside the supported syntax;
|
|
// - an internal destination is not a page in docs/manifest.json;
|
|
// - a source is a live docs page, which would hide a page readers can reach;
|
|
// - two rules share a source, or rules form a chain or a loop.
|
|
//
|
|
// It also warns, without failing, when a pull request removes routes from
|
|
// docs/manifest.json and leaves docs/redirects.json alone, since pages are
|
|
// sometimes removed on purpose.
|
|
//
|
|
// A missing docs/redirects.json passes. Everything it checks about routes is
|
|
// derived from docs/manifest.json the same way the website derives it.
|
|
//
|
|
// Usage:
|
|
//
|
|
// docsredirectscheck [-manifest path] [-redirects path] [-base rev]
|
|
//
|
|
// Exit status is 0 when the file is valid or absent, 1 when it has problems,
|
|
// and 2 when the check itself could not run.
|
|
package main
|
|
|
|
import (
|
|
"errors"
|
|
"flag"
|
|
"fmt"
|
|
"io"
|
|
"io/fs"
|
|
"os"
|
|
"os/exec"
|
|
"strings"
|
|
|
|
"golang.org/x/xerrors"
|
|
)
|
|
|
|
type options struct {
|
|
manifestPath string
|
|
redirectsPath string
|
|
// base is the git revision the change under review started from. Empty
|
|
// means derive it from the environment.
|
|
base string
|
|
git gitReader
|
|
getenv func(string) string
|
|
stdout io.Writer
|
|
stderr io.Writer
|
|
}
|
|
|
|
// gitReader is the slice of git the advisory check needs, so tests can supply
|
|
// a fake repository.
|
|
type gitReader interface {
|
|
// HasRev reports whether rev resolves to a commit.
|
|
HasRev(rev string) bool
|
|
// Show returns the contents of path at rev.
|
|
Show(rev, path string) ([]byte, error)
|
|
// Changed reports whether path differs between rev and the working tree.
|
|
Changed(rev, path string) (bool, error)
|
|
}
|
|
|
|
type execGit struct{}
|
|
|
|
// validRev rejects a revision git could read as an option, so a value passed
|
|
// with -base cannot add flags to the git commands below. The commands run
|
|
// without a shell and path is always one of the fixed repository paths.
|
|
func validRev(rev string) bool {
|
|
return rev != "" && !strings.HasPrefix(rev, "-")
|
|
}
|
|
|
|
func (execGit) HasRev(rev string) bool {
|
|
if !validRev(rev) {
|
|
return false
|
|
}
|
|
return exec.Command("git", "rev-parse", "--verify", "--quiet", rev+"^{commit}").Run() == nil //nolint:gosec // rev is checked by validRev and no shell is involved.
|
|
}
|
|
|
|
func (execGit) Show(rev, path string) ([]byte, error) {
|
|
if !validRev(rev) {
|
|
return nil, xerrors.Errorf("invalid revision %q", rev)
|
|
}
|
|
return exec.Command("git", "show", rev+":"+path).Output() //nolint:gosec // rev is checked by validRev and no shell is involved.
|
|
}
|
|
|
|
func (execGit) Changed(rev, path string) (bool, error) {
|
|
if !validRev(rev) {
|
|
return false, xerrors.Errorf("invalid revision %q", rev)
|
|
}
|
|
err := exec.Command("git", "diff", "--quiet", rev, "--", path).Run() //nolint:gosec // rev is checked by validRev and no shell is involved.
|
|
if err == nil {
|
|
return false, nil
|
|
}
|
|
var exitErr *exec.ExitError
|
|
if errors.As(err, &exitErr) && exitErr.ExitCode() == 1 {
|
|
return true, nil
|
|
}
|
|
return false, err
|
|
}
|
|
|
|
func main() {
|
|
o := options{
|
|
git: execGit{},
|
|
getenv: os.Getenv,
|
|
stdout: os.Stdout,
|
|
stderr: os.Stderr,
|
|
}
|
|
flag.StringVar(&o.manifestPath, "manifest", manifestRepoPath, "path to the docs manifest")
|
|
flag.StringVar(&o.redirectsPath, "redirects", redirectsRepoPath, "path to the redirects file")
|
|
flag.StringVar(&o.base, "base", "", "git revision the change started from, for the removed-route warning (default: the pull request base in GitHub Actions)")
|
|
flag.Parse()
|
|
os.Exit(run(o))
|
|
}
|
|
|
|
func run(o options) int {
|
|
manifestData, err := os.ReadFile(o.manifestPath)
|
|
if err != nil {
|
|
_, _ = fmt.Fprintf(o.stderr, "cannot read manifest %s: %v\n", o.manifestPath, err)
|
|
return 2
|
|
}
|
|
m, err := parseManifest(manifestData)
|
|
if err != nil {
|
|
_, _ = fmt.Fprintf(o.stderr, "invalid manifest %s: %v\n", o.manifestPath, err)
|
|
return 2
|
|
}
|
|
live := liveRoutes(m)
|
|
|
|
var (
|
|
rules []rule
|
|
code int
|
|
)
|
|
redirectsData, err := os.ReadFile(o.redirectsPath)
|
|
switch {
|
|
case errors.Is(err, fs.ErrNotExist):
|
|
_, _ = fmt.Fprintf(o.stdout, "%s not found; nothing to validate\n", o.redirectsPath)
|
|
case err != nil:
|
|
_, _ = fmt.Fprintf(o.stderr, "cannot read %s: %v\n", o.redirectsPath, err)
|
|
return 2
|
|
default:
|
|
var problems []problem
|
|
rules, problems = checkRedirects(redirectsData, live)
|
|
if len(problems) > 0 {
|
|
for _, p := range problems {
|
|
_, _ = fmt.Fprintln(o.stderr, formatProblem(o.redirectsPath, p))
|
|
}
|
|
_, _ = fmt.Fprintf(o.stderr, "%s: %d %s found\n", o.redirectsPath, len(problems), plural(len(problems), "problem", "problems"))
|
|
code = 1
|
|
} else {
|
|
_, _ = fmt.Fprintf(o.stdout, "%s: %d %s OK\n", o.redirectsPath, len(rules), plural(len(rules), "rule", "rules"))
|
|
}
|
|
}
|
|
|
|
runAdvisory(o, live, rules)
|
|
return code
|
|
}
|
|
|
|
func plural(n int, one, many string) string {
|
|
if n == 1 {
|
|
return one
|
|
}
|
|
return many
|
|
}
|