Files
coder/scripts/docsredirectscheck/rules.go
T
Nick Vigilante 35b3052ea8 ci(scripts/docsredirectscheck): reject redirects an earlier rule swallows (#30383)
## Summary

Redirects apply in file order and the first match wins, so rules have to
run from most specific to least.
Nothing enforced that, so a wildcard placed above a narrower rule inside
its subtree silently swallowed it.

## Problem

Given these two rules in that order, the second never applies:

```json
[
  { "source": "/docs/retired/:section(.*)", "destination": "/docs/reference/:section" },
  { "source": "/docs/retired/foo",          "destination": "/docs/about" }
]
```

A reader asking for `/docs/retired/foo` is sent to `/docs/reference/foo`
instead of `/docs/about`.
If `/docs/reference/foo` happens to exist, every existing check passes:
the destination resolves, there is no duplicate source, no chain, and no
loop.
The rule is simply dead, and the only symptom is readers landing on the
wrong page.

`docs/redirects.json` is empty today, so this adds the guard before the
file gets its first wildcard rather than after.

## Fix

Compare each rule against the ones before it and fail when an earlier
source matches every URL a later source would.

Coverage is decided on path boundaries, not string prefixes, so
`/docs/retired/:path*` does not cover `/docs/retired-too/page`.
Two cases stay legal on purpose:

- An exact rule above a wildcard on the same prefix, which claims the
bare prefix and leaves the subtree to the wildcard.
- A regex wildcard above an exact rule on its bare prefix, since
`/:name(.*)` never matches the prefix itself.

Rules that share a source are still reported as duplicates, not as
unreachable, so one mistake produces one message.

## Changes

- `rules.go`: add `pattern.covers` and `checkOrder`, called from
`checkAcrossRules`.
- `README.md`: document the ordering requirement and the new failure.
- `main_test.go`: 11 cases covering each pattern pairing, both
orderings, the path-boundary case, reporting once against the first
coverer, and the duplicate interaction.

## Testing

- `go test ./scripts/docsredirectscheck/` passes;
`TestCheckRedirectsOrder` runs all 11 subtests.
- `make lint/docs-redirects` passes against the committed
`docs/redirects.json`.
- `gofmt -l` and `go vet` are clean on the package.
- Ran the binary against the example above: it fails with
`unreachable: rule [0] (source "/docs/retired/:section(.*)") comes first
and matches every URL this rule would; order rules from most specific to
least`,
  exits 1, and passes with exit 0 once the two rules are swapped.

<details>
<summary>Why this check, and what it is a prerequisite for</summary>

`docs/redirects.json` is validated in CI and triggers a docs rebuild,
but no site reads it yet.
The redirects actually served live in two other hand-maintained files:
`coder.com/redirects.json` (297 rules, 173 under `/docs`) and
`docs-engine`'s `apps/router/redirects.json` (221 rules).

The plan is to make `docs/redirects.json` the single authored source and
have docs-engine compile it per version, so `apps/router/redirects.json`
becomes generated output.
Classifying the router's 221 rules showed all of them are same-version
moves once the version prefix is stripped, and that expanding them into
this file's narrow grammar yields 279 authored rules.

That expansion is what makes this check necessary now.
Collapsing many exact rules into wildcards is an engine optimization,
and the authored file will carry both wildcards and exact rules in the
same subtree, which is exactly the shape that can silently swallow a
rule.
Adding the guard while the file is still empty means the migration
cannot introduce an unreachable rule without CI saying so.

</details>

---

Resolves DOCS-1188.

Opened by Coder Agents on behalf of @nickvigilante.

<details>
<summary>CI note: one unrelated flake</summary>

`test-go-pg (ubuntu-latest)` failed on `coderd/x/chatd
TestChatTurnStopsAtStepLimit/Default`.
This PR changes three files under `scripts/docsredirectscheck` and
nothing in `coderd/`, so the failure is unrelated to the diff.
`lint`, `gen`, `fmt`, `check-build`, `test-go-race-pg`, `test-go-pg-17`,
`test-e2e`, and `test-go-pg` on macOS and Windows all pass.

The first run of this PR also had `changes`, `cla`, and `release-labels`
cancelled rather than failed, all three at exactly 15m03s, which skipped
the Go jobs entirely. A `--failed` rerun produced the results above.

</details>
2026-10-08 12:26:20 -04:00

580 lines
18 KiB
Go

package main
import (
"bytes"
"cmp"
"encoding/json"
"errors"
"fmt"
"net/url"
"regexp"
"slices"
"strings"
)
type patternKind int
const (
// kindExact matches one path.
kindExact patternKind = iota
// kindWildcard is "/prefix/:name*". It matches the prefix itself and
// everything beneath it.
kindWildcard
// kindRegexWildcard is "/prefix/:name(.*)". It matches everything beneath
// the prefix but not the bare prefix.
kindRegexWildcard
)
// pattern is a source or destination path in the small subset of Next.js
// path syntax the docs website accepts.
type pattern struct {
kind patternKind
// prefix is the static part of the path with no trailing slash. For an
// exact pattern it is the whole path.
prefix string
// param is the parameter name of a wildcard pattern, empty for exact.
param string
}
func (p pattern) matches(path string) bool {
path = normalizePath(path)
switch p.kind {
case kindWildcard:
return path == p.prefix || strings.HasPrefix(path, p.prefix+"/")
case kindRegexWildcard:
return strings.HasPrefix(path, p.prefix+"/")
default:
return path == p.prefix
}
}
// key identifies a source for duplicate detection. The parameter name is left
// out because two patterns that differ only by it match the same paths.
func (p pattern) key() string {
return fmt.Sprintf("%d %s", p.kind, p.prefix)
}
// covers reports whether every path q matches is also matched by p, which
// makes q unreachable when p is earlier in the file. Redirects are applied in
// order and the first matching rule wins, so a broad pattern placed above a
// narrower rule swallows it.
//
// An exact p never covers anything but an identical exact q, which the
// duplicate check already reports. In particular an exact rule above a
// wildcard on the same prefix is deliberate: it claims the bare prefix and
// leaves the subtree to the wildcard.
func (p pattern) covers(q pattern) bool {
switch p.kind {
case kindWildcard:
// p matches its prefix and everything beneath it, and q only ever
// matches paths at or beneath its own prefix.
return q.prefix == p.prefix || strings.HasPrefix(q.prefix, p.prefix+"/")
case kindRegexWildcard:
// p matches everything strictly beneath its prefix, so it covers q
// only when q's paths are all strictly beneath it too.
if strings.HasPrefix(q.prefix, p.prefix+"/") {
return true
}
// On the same prefix, p misses the bare prefix that a wildcard q
// matches, so it covers only another regex wildcard.
return q.prefix == p.prefix && q.kind == kindRegexWildcard
default:
return false
}
}
type destination struct {
external bool
// raw is the destination as written, for messages.
raw string
// pattern is the path part of an internal destination. The query string
// and fragment are dropped because they do not change which page it is.
pattern pattern
// valid is false when the destination could not be parsed, in which case
// no cross-rule check uses it.
valid bool
}
// rule is one validated entry of docs/redirects.json.
type rule struct {
index int
source string
destination string
src pattern
dst destination
}
func (r rule) matches(path string) bool {
return r.src.matches(path)
}
// problem is one thing wrong with docs/redirects.json. index is the position
// of the offending rule in the array, or -1 for a problem with the whole file.
type problem struct {
index int
source string
message string
}
func formatProblem(file string, p problem) string {
switch {
case p.index < 0:
return fmt.Sprintf("%s: %s", file, p.message)
case p.source != "":
return fmt.Sprintf("%s[%d] (source %q): %s", file, p.index, p.source, p.message)
default:
return fmt.Sprintf("%s[%d]: %s", file, p.index, p.message)
}
}
var (
// staticSegment is one literal path segment.
staticSegment = regexp.MustCompile(`^[A-Za-z0-9._~%+-]+$`)
// versionSegment is a literal "@ref" segment. The docs website adds the
// version to a URL itself, so rules are written without it.
versionSegment = regexp.MustCompile(`^@[A-Za-z0-9._~%+-]+$`)
// sourceWildcard matches ":name*".
sourceWildcard = regexp.MustCompile(`^:([A-Za-z_][A-Za-z0-9_]*)\*$`)
// sourceRegexWildcard matches ":name(.*)".
sourceRegexWildcard = regexp.MustCompile(`^:([A-Za-z_][A-Za-z0-9_]*)\(\.\*\)$`)
// destinationParam matches ":name" and ":name*".
destinationParam = regexp.MustCompile(`^:([A-Za-z_][A-Za-z0-9_]*)\*?$`)
)
// normalizePath drops trailing slashes so "/docs/a/" and "/docs/a" compare
// equal, the way the website routes them.
func normalizePath(p string) string {
return strings.TrimRight(p, "/")
}
// pathRole says whether a path is being parsed as a rule's source or its
// destination, because the two accept different pattern syntax.
type pathRole int
const (
roleSource pathRole = iota
roleDestination
)
// parsePath parses a /docs/... path. Sources allow an exact path, a trailing
// "/:name*" and a trailing "/:name(.*)". Destinations allow an exact path and
// a trailing "/:name" or "/:name*". It returns a message describing the
// problem when the path is outside that subset.
func parsePath(path string, role pathRole) (pattern, string) {
segments := strings.Split(strings.TrimPrefix(path, "/"), "/")
last := len(segments) - 1
unsupported := func(why string) string {
if role == roleDestination {
return fmt.Sprintf("unsupported destination %q (%s): use an exact path or a trailing /:name or /:name*", path, why)
}
return fmt.Sprintf("unsupported source %q (%s): use an exact path, a trailing /:name*, or a trailing /:name(.*)", path, why)
}
for _, seg := range segments[:last] {
if err := checkStaticSegment(seg, path, unsupported); err != "" {
return pattern{}, err
}
}
lastSeg := segments[last]
prefix := "/" + strings.Join(segments[:last], "/")
if last == 0 {
prefix = ""
}
if role == roleDestination {
if m := destinationParam.FindStringSubmatch(lastSeg); m != nil && last > 0 {
return pattern{kind: kindWildcard, prefix: prefix, param: m[1]}, ""
}
} else {
if m := sourceWildcard.FindStringSubmatch(lastSeg); m != nil && last > 0 {
return pattern{kind: kindWildcard, prefix: prefix, param: m[1]}, ""
}
if m := sourceRegexWildcard.FindStringSubmatch(lastSeg); m != nil && last > 0 {
return pattern{kind: kindRegexWildcard, prefix: prefix, param: m[1]}, ""
}
}
if err := checkStaticSegment(lastSeg, path, unsupported); err != "" {
return pattern{}, err
}
return pattern{kind: kindExact, prefix: "/" + strings.Join(segments, "/")}, ""
}
func checkStaticSegment(seg, path string, unsupported func(string) string) string {
switch {
case seg == "":
return unsupported("empty path segment")
case versionSegment.MatchString(seg):
return fmt.Sprintf("%q contains a version segment (%s): the docs website adds /@<ref> itself, so write the path without it", path, seg)
case !staticSegment.MatchString(seg):
return unsupported(fmt.Sprintf("segment %q", seg))
}
return ""
}
func parseSource(raw string) (pattern, string) {
s := normalizePath(raw)
if !strings.HasPrefix(s, docsRoot+"/") {
return pattern{}, "source must start with /docs/ (write the full site path, for example /docs/admin/old-page)"
}
return parsePath(s, roleSource)
}
func parseDestination(raw string) (destination, string) {
d := destination{raw: raw}
if strings.HasPrefix(raw, "http://") || strings.HasPrefix(raw, "https://") {
u, err := url.Parse(raw)
if err != nil || u.Host == "" {
return d, fmt.Sprintf("destination %q is an invalid URL", raw)
}
d.external = true
d.valid = true
return d, ""
}
p := raw
if i := strings.IndexAny(p, "?#"); i >= 0 {
p = p[:i]
}
p = normalizePath(p)
if p != docsRoot && !strings.HasPrefix(p, docsRoot+"/") {
return d, fmt.Sprintf("destination %q is not valid: destination must be a /docs/ path or an http(s) URL", raw)
}
pat, msg := parsePath(p, roleDestination)
if msg != "" {
return d, msg
}
d.pattern = pat
d.valid = true
return d, ""
}
// checkRedirects validates the contents of docs/redirects.json against the set
// of live docs routes. It returns the rules whose source could be parsed, which
// the advisory check uses to see whether a removed route is already covered,
// and every problem it found, ordered by rule.
func checkRedirects(data []byte, live map[string]bool) ([]rule, []problem) {
var entries []json.RawMessage
if err := json.Unmarshal(data, &entries); err != nil {
var typeErr *json.UnmarshalTypeError
if errors.As(err, &typeErr) {
// Valid JSON, but an object or scalar rather than an array.
return nil, []problem{{index: -1, message: "must be a JSON array of rules"}}
}
return nil, []problem{{index: -1, message: fmt.Sprintf("is not valid JSON: %v", err)}}
}
if entries == nil {
// A JSON null decodes to a nil slice without an error.
return nil, []problem{{index: -1, message: "must be a JSON array of rules"}}
}
var (
rules []rule
problems []problem
)
for i, entry := range entries {
r, ps := checkEntry(i, entry, live)
problems = append(problems, ps...)
if r != nil {
rules = append(rules, *r)
}
}
problems = append(problems, checkAcrossRules(rules)...)
slices.SortStableFunc(problems, func(a, b problem) int { return cmp.Compare(a.index, b.index) })
return rules, problems
}
const entryShape = `must be an object with "source", "destination" and optional "permanent"`
// checkEntry validates one array element on its own. It returns the rule when
// the source parsed, so that cross-rule checks can still use it.
func checkEntry(i int, entry json.RawMessage, live map[string]bool) (*rule, []problem) {
if bytes.Equal(bytes.TrimSpace(entry), []byte("null")) {
return nil, []problem{{index: i, message: entryShape}}
}
var fields map[string]json.RawMessage
if err := json.Unmarshal(entry, &fields); err != nil {
return nil, []problem{{index: i, message: entryShape}}
}
var problems []problem
add := func(source, msg string) {
problems = append(problems, problem{index: i, source: source, message: msg})
}
keys := make([]string, 0, len(fields))
for k := range fields {
keys = append(keys, k)
}
slices.Sort(keys)
for _, k := range keys {
switch k {
case "source", "destination", "permanent":
default:
add("", fmt.Sprintf("unknown field %q (allowed: source, destination, permanent)", k))
}
}
source, sourceOK := stringField(fields, "source")
if !sourceOK {
add("", `"source" is required and must be a non-empty string`)
}
dest, destOK := stringField(fields, "destination")
if !destOK {
add(source, `"destination" is required and must be a non-empty string`)
}
if raw, ok := fields["permanent"]; ok {
var b bool
if bytes.Equal(bytes.TrimSpace(raw), []byte("null")) || json.Unmarshal(raw, &b) != nil {
add(source, `"permanent" must be a boolean`)
}
}
if !sourceOK {
return nil, problems
}
src, msg := parseSource(source)
if msg != "" {
add(source, msg)
return nil, problems
}
r := &rule{index: i, source: source, destination: dest, src: src}
if destOK {
d, msg := parseDestination(dest)
r.dst = d
if msg != "" {
add(source, msg)
} else {
for _, m := range checkDestination(d, src, live) {
add(source, m)
}
}
}
if m := checkShadowing(src, live); m != "" {
add(source, m)
}
return r, problems
}
func stringField(fields map[string]json.RawMessage, name string) (string, bool) {
raw, ok := fields[name]
if !ok {
return "", false
}
var s string
if err := json.Unmarshal(raw, &s); err != nil || strings.TrimSpace(s) == "" {
return "", false
}
return s, true
}
// checkDestination verifies that an internal destination lands on a page that
// exists and that any parameter it uses is one the source defines.
func checkDestination(d destination, src pattern, live map[string]bool) []string {
if d.external {
return nil
}
var msgs []string
pat := d.pattern
if pat.kind == kindExact {
if !live[pat.prefix] {
msgs = append(msgs, fmt.Sprintf("destination %q is not a page in docs/manifest.json; point it at an existing page", d.raw))
}
return msgs
}
if src.param != pat.param {
msgs = append(msgs, fmt.Sprintf("destination uses :%s, which the source does not define; the source's parameter is %s", pat.param, describeParam(src)))
}
if !prefixHasPages(pat.prefix, live) {
msgs = append(msgs, fmt.Sprintf("no docs page exists under %q; point the destination at an existing section", pat.prefix))
}
return msgs
}
func describeParam(p pattern) string {
if p.param == "" {
return "absent (the source is an exact path)"
}
return ":" + p.param
}
// prefixHasPages reports whether a pattern destination with this static
// prefix can land on a page: the prefix is a page or a section of pages.
func prefixHasPages(prefix string, live map[string]bool) bool {
if prefix == docsRoot || live[prefix] {
return true
}
for route := range live {
if strings.HasPrefix(route, prefix+"/") {
return true
}
}
return false
}
// checkShadowing reports a source that matches live docs pages. Redirects are
// applied before pages, so such a rule would hide a page readers can reach.
func checkShadowing(src pattern, live map[string]bool) string {
var hidden []string
for route := range live {
if src.matches(route) {
hidden = append(hidden, route)
}
}
if len(hidden) == 0 {
return ""
}
slices.Sort(hidden)
more := ""
if len(hidden) > 1 {
more = fmt.Sprintf(" (and %d more)", len(hidden)-1)
}
return fmt.Sprintf("source hides a live docs page: %s%s; remove the redirect, or remove the page from docs/manifest.json first", hidden[0], more)
}
// checkOrder reports rules that can never apply because an earlier rule
// already matches every URL they would. The website applies redirects in file
// order and the first match wins, so rules have to run from most specific to
// least: a trailing wildcard above a rule inside its subtree swallows it.
//
// Each unreachable rule is reported once, against the first rule that covers
// it. Pairs with the same source are left to the duplicate check.
func checkOrder(rules []rule) []problem {
var problems []problem
for j, later := range rules {
for _, earlier := range rules[:j] {
if earlier.src.key() == later.src.key() {
continue
}
if !earlier.src.covers(later.src) {
continue
}
problems = append(problems, problem{
index: later.index,
source: later.source,
message: fmt.Sprintf(
"unreachable: rule [%d] (source %q) comes first and matches every URL this rule would; order rules from most specific to least",
earlier.index, earlier.source,
),
})
break
}
}
return problems
}
// checkAcrossRules finds duplicate sources, unreachable rules, chains, and
// loops.
func checkAcrossRules(rules []rule) []problem {
var problems []problem
seen := make(map[string]int, len(rules))
for _, r := range rules {
k := r.src.key()
if first, dup := seen[k]; dup {
problems = append(problems, problem{
index: r.index,
source: r.source,
message: fmt.Sprintf("duplicate of rule [%d]: two rules with the same source; remove one", first),
})
continue
}
seen[k] = r.index
}
problems = append(problems, checkOrder(rules)...)
// next[i] is the rule whose source the destination of rule i lands on.
// Only exact internal destinations are followed. Where a pattern
// destination ends up depends on the URL being redirected, so chains
// through one are not checked.
next := make(map[int]int, len(rules))
byIndex := make(map[int]rule, len(rules))
for _, r := range rules {
byIndex[r.index] = r
}
for _, r := range rules {
if !r.dst.valid || r.dst.external || r.dst.pattern.kind != kindExact {
continue
}
for _, other := range rules {
if other.matches(r.dst.pattern.prefix) {
next[r.index] = other.index
break
}
}
}
for _, r := range rules {
if _, ok := next[r.index]; !ok {
continue
}
path, cycleStart, cyclic := followRedirects(r.index, next)
switch {
case cyclic && cycleStart == 0:
cycle := path
// Report a loop once, on its lowest-numbered rule.
if r.index != slices.Min(cycle) {
continue
}
problems = append(problems, problem{index: r.index, source: r.source, message: describeLoop(cycle, byIndex)})
case cyclic:
// Leads into a loop it is not part of.
problems = append(problems, problem{
index: r.index,
source: r.source,
message: fmt.Sprintf("redirect chain into a loop: destination %q is the source of rule [%d], which never reaches a page", r.dst.raw, path[1]),
})
default:
last := byIndex[path[len(path)-1]]
problems = append(problems, problem{
index: r.index,
source: r.source,
message: fmt.Sprintf(
"redirect chain: destination %q is the source of rule [%d], which redirects to %q; point this rule at %q directly",
r.dst.raw, path[1], last.dst.raw, last.dst.raw,
),
})
}
}
return problems
}
// followRedirects walks next from start. It returns the rules visited in
// order, and when the walk revisits a rule, cyclic is true and cycleStart is
// the position in path where that rule first appeared.
func followRedirects(start int, next map[int]int) (path []int, cycleStart int, cyclic bool) {
pos := map[int]int{start: 0}
path = []int{start}
cur := start
for {
n, ok := next[cur]
if !ok {
return path, 0, false
}
if at, seen := pos[n]; seen {
return path, at, true
}
pos[n] = len(path)
path = append(path, n)
cur = n
}
}
func describeLoop(cycle []int, byIndex map[int]rule) string {
if len(cycle) == 1 {
return "redirects to itself; remove the rule or point it at a different page"
}
parts := make([]string, 0, len(cycle)+1)
for _, idx := range cycle {
parts = append(parts, fmt.Sprintf("rule [%d] %q", idx, byIndex[idx].source))
}
parts = append(parts, fmt.Sprintf("rule [%d]", cycle[0]))
return "redirect loop: " + strings.Join(parts, " -> ") + "; break the loop by pointing one rule at a real page"
}