routetable

package
v0.1.21 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Aug 21, 2026 License: Apache-2.0 Imports: 6 Imported by: 0

Documentation

Overview

Package routetable exposes the route table ghtmx derives from Go source, so a consuming project can assert in its own tests that the routes the toolchain believes in are the routes its framework really serves (FR-064).

`ghtmx generate -check` verifies template-versus-generated-code drift. It does not — and cannot — verify annotation-versus-reality drift: once a project takes the //ghtmx:route escape hatch and registers routes outside routeScope, nothing checks that the annotated paths still match what the framework serves. Load reads the same table `ghtmx routes` prints, and Diff compares it against a list the consumer dumps from their own router, which turns that invariant back into a test.

This package is for build- and test-time tooling. Application code renders through the root package and an adapter and never needs it.

Index

Constants

View Source
const AnyVerb = "*"

AnyVerb is the verb of a route registered without one — a net/http pattern carrying no method, which serves every verb. It is rendered as "*", matching `ghtmx routes -json`.

Variables

This section is empty.

Functions

func NormalizePath

func NormalizePath(path string, style ParamStyle) (string, []string)

NormalizePath converts a router-flavoured pattern to the normalized form the table uses, returning the path and its ordered parameter names (wildcards suffixed with "..."). It is the toolchain's own normalizer, so a consumer comparing framework paths against Load's output cannot drift from it.

func Report

func Report(ms []Mismatch) string

Report renders mismatches as a newline-terminated block suitable for a test failure message. It returns "" when there are none.

Types

type Mismatch

type Mismatch struct {
	Kind MismatchKind
	Verb string
	Path string
	// Declared and Actual are the routes from each side; the one absent
	// for the kind is nil.
	Declared *Route
	Actual   *Route
}

Mismatch is one disagreement, carrying whichever side(s) exist.

func Diff

func Diff(declared, actual []Route) []Mismatch

Diff compares the route table ghtmx derived (declared — from Load, or from `ghtmx routes -json`) against the routes a framework really serves (actual — dumped by the consumer from its own router, then passed through Normalize). Routes are matched on verb and normalized path.

The result is sorted by path then verb, so a failing test prints the same report every run. An empty result means the two agree.

A handler comparison is only made when the actual side names one: most routers report paths and not Go symbols, so an empty HandlerName on the actual side means "not reported", never "different".

func (Mismatch) String

func (m Mismatch) String() string

String renders a mismatch as a single reviewable line.

type MismatchKind

type MismatchKind string

MismatchKind classifies one disagreement between two route lists.

const (
	// KindMissing: declared holds a route actual does not — the
	// toolchain believes in a route the router never serves, so its
	// template bindings generate URLs that 404.
	KindMissing MismatchKind = "missing"
	// KindUnexpected: actual holds a route declared does not — the
	// router serves a route the toolchain cannot see, so no template can
	// bind it.
	KindUnexpected MismatchKind = "unexpected"
	// KindHandler: both hold the verb and path, but disagree on the
	// handler symbol.
	KindHandler MismatchKind = "handler"
)

type ParamStyle

type ParamStyle int

ParamStyle is a router flavour's path-parameter syntax.

const (
	// BraceStyle is net/http and chi: /users/{id}, /files/{path...}.
	BraceStyle ParamStyle = ParamStyle(routes.BraceStyle)
	// ColonStyle is echo, gin, and fiber: /users/:id, /files/*.
	ColonStyle ParamStyle = ParamStyle(routes.ColonStyle)
)

type Route

type Route struct {
	// Verb is the HTTP method, or "*" for a route serving every verb.
	Verb string `json:"verb"`
	// Path is the normalized pattern, using {name} and {name...}
	// regardless of the source router's flavour.
	Path string `json:"path"`
	// OriginalPath preserves the registering router's own syntax.
	OriginalPath string `json:"originalPath"`
	// Params are the ordered path parameter names, wildcards suffixed
	// with "...".
	Params []string `json:"params,omitempty"`
	// HandlerPkg is the import path of the handler's package.
	HandlerPkg string `json:"handlerPackage"`
	// HandlerName is the handler symbol's name.
	HandlerName string `json:"handlerName"`
	// Origin is "discovered" or "declared" (by a //ghtmx:route
	// annotation).
	Origin string `json:"origin"`
	// Recognizer names the router flavour that produced the route:
	// nethttp, chi, echo, gin, fiber, or annotation.
	Recognizer string `json:"recognizer"`
	// Source is the registration or declaration site, "file:line:col".
	Source string `json:"source"`
	// NavOnly reports the route as navigation-only (the annotation's
	// trailing "nav" marker), exempting it from GHTMX-W0104.
	NavOnly bool `json:"navOnly,omitempty"`
}

Route is one entry of the route table. The JSON tags are the schema `ghtmx routes -json` emits, so its output unmarshals into []Route directly.

func FromTable

func FromTable(table *routes.Table) []Route

FromTable converts an internal route table. It is the single place the public shape is built, so `ghtmx routes -json` and this package cannot describe the same route differently.

func Load

func Load(dir string) ([]Route, error)

Load runs route discovery over the module rooted at dir — the same analysis `ghtmx routes` performs, honouring that project's ghtmx.json (routeScope in particular) — and returns the table in the order the command prints it: by path, then verb.

Discovery diagnostics are not returned: a project whose table this reports on has already seen them from `ghtmx generate`. An error means the packages could not be loaded at all.

func Normalize

func Normalize(rs []Route, style ParamStyle) []Route

Normalize returns a copy of rs with every Path normalized from style, keeping the input pattern in OriginalPath. Use it on a list dumped from a framework router — whose paths are in that router's own syntax — before handing it to Diff.

func (Route) Handler

func (r Route) Handler() string

Handler returns the fully qualified handler symbol, matching the text output of `ghtmx routes`.

func (Route) Key

func (r Route) Key() string

Key is the identity Diff compares on: verb and normalized path.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL