web

Documentation

Overview

Package web is the server-rendered public website: landing page, Compatibility Explorer, sample/seeder pages, install scripts and SEO surface (plan P6.1–P6.3, goal.md §14.5/§14.6).

Everything is read-only and snapshot-backed: pages consume the Store interface below, which returns materialized snapshot/stats JSON — the site never aggregates raw evidence at request time.

All assets are embedded; the pages reference no external host, so the site works over plain http, behind Caddy, and offline.

Index

• Variables
• func RecordEnvironmentMatches(env domain.EnvironmentFingerprint, osName, runtime string) bool
• func RecordEnvironmentOS(env domain.EnvironmentFingerprint) string
• func RecordEnvironmentRuntime(env domain.EnvironmentFingerprint) string
• func RecordEnvironmentSummary(env domain.EnvironmentFingerprint) string
• func Register(mux *http.ServeMux, d Deps)
• type CoverageDisclosure
• type CoverageRow
• type DependencyEdge
• type Deps
• type DerivedFinding
• type PackageCodeCount
• type PackageDep
• type PackageHit
• type ParsedRecordQuery
  • func ParseRecordQuery(raw string) ParsedRecordQuery
  • func (q ParsedRecordQuery) MatchPackage(name string) (match, exact, prefix bool)
• type RecordFilter
• type SampleListItem
• type SampleMeta
• type Store
• type WantedItem
• type WantedRollupRow
• type WantedRow

Variables

var AllCapabilityLevels = []string{"A0", "A1", "A2", "A3", "A4"}

AllCapabilityLevels is the fixed A0–A4 column set of the matrix.

Functions

func RecordEnvironmentMatches

func RecordEnvironmentMatches(env domain.EnvironmentFingerprint, osName, runtime string) bool

RecordEnvironmentMatches applies the /records environment buckets to one recorded fingerprint. It is exported for the production Store adapter; keeping the normalization here makes test and production matching agree.

func RecordEnvironmentOS

func RecordEnvironmentOS(env domain.EnvironmentFingerprint) string

func RecordEnvironmentRuntime

func RecordEnvironmentRuntime(env domain.EnvironmentFingerprint) string

environmentRuntime returns a filter bucket from facts actually recorded in the fingerprint. It does not infer Python from PyPI, Ruby from RubyGems, and so on: ecosystem is not an execution environment.

func RecordEnvironmentSummary

func RecordEnvironmentSummary(env domain.EnvironmentFingerprint) string

environmentSummary is deliberately compact enough for a finding card. It only joins fields that exist in the recorded fingerprint.

func Register

func Register(mux *http.ServeMux, d Deps)

Register mounts every website route on mux.

Types

type CoverageDisclosure

type CoverageDisclosure struct {
	Rows []CoverageRow
	// Overlap is the total ObservedProven across every cell. When it is zero
	// the two halves of the instrument have never met, and the page says so
	// in those words rather than leaving a reader to compute it.
	Overlap int
	// ObservedTotal and ProvenTotal size the two halves being compared.
	ObservedTotal int
	ProvenTotal   int
	// Unreachable names the (platform, ecosystem) pairs that can never be
	// proven, so a zero there is not a backlog. macOS has no container
	// runtime at all and npm publishes no Windows image; a cell that cannot
	// be filled must not be presented as one nobody got to.
	Unreachable []string
	// SelectionNote is true when every recorded verification passed. That
	// looks like a perfect record and is not one: a sample is published
	// because it passed, so the pass rate on our own axis measures our
	// publishing rule and not the ecosystem.
	SelectionNote bool
}

CoverageDisclosure is the instrument describing its own shape.

An integrity system's failure is "we claimed something false". An observatory's is "our coverage was skewed and we never said so", and this network is skewed to an extreme that has to be published rather than discovered: every observation it holds is from Windows and every proof it holds is from Linux, so the overlap between what it sees used and what it has proven is zero.

type CoverageRow

type CoverageRow struct {
	OS             string
	Ecosystem      string
	Observed       int
	Measured       int
	Proven         int
	ObservedProven int
}

CoverageRow is one (platform, ecosystem) cell of the network's own coverage, counted in distinct public packages.

Observed comes from developer machines; Measured and Proven come from the verifier fleet. ObservedProven is the overlap — the only one of the four that answers "have we proven what we see used".

type DependencyEdge

type DependencyEdge struct {
	ParentName    string
	ParentVersion string
	ChildName     string
	ChildVersion  string
	// int64 so the template's number formatter takes it directly. A mismatch
	// here does not fail loudly: html/template aborts mid-render and the page
	// simply stops, which looks like a missing item rather than an error.
	Projects int64
}

DependencyEdge is one "this package pulled that version" relationship, as the machine holding the lockfile saw it.

VersionCoresidence says two versions were installed together; this says who wanted each, which is the half a person can act on.

type Deps

type Deps struct {
	Store     Store
	PublicURL string // canonical origin, e.g. https://codesamplex.dev; "" ⇒ derive from request
	// Build is the identity of the server process rendering the page. It is
	// resolved from the stamps the deployment put on this artifact, never
	// from a string written into a template: a hand-maintained version is
	// exactly the thing that keeps saying the old number after a rollback.
	Build   buildinfo.Info
	DistDir string // directory with release binaries served under /dl/; "" ⇒ /dl 404s
}

Deps wires the site to the rest of the server.

type DerivedFinding

type DerivedFinding struct {
	Ecosystem string
	Subject   string // "axios@1.12.0", from the first package purl
	Believed  string // Case.Believed, written by the sample's author
	Measured  string // the contract line that contradicts it
	SampleID  string
	// OS and Runtime come from the sample manifest's recorded environment.
	// They are empty when the manifest did not establish that dimension;
	// the findings page never guesses them from the ecosystem.
	OS          string
	Runtime     string
	Environment string
}

DerivedFinding is a finding the network produced rather than one a person wrote: a published sample whose case declares what was believed, paired with the contract line that measured otherwise.

The hand-written lists in findings.go are the reason this exists. They are good entries, but they are twenty-nine entries in a Go literal, and the storehouse they are drawn from passed three hundred samples and is aimed at ten thousand. The most persuasive page on the site was the only one that could not grow on its own.

type PackageCodeCount

type PackageCodeCount struct {
	Version string
	Symbol  string
	Samples int64
}

PackageCodeCount is one authoritative code-availability aggregate. An empty Symbol is the whole-release count; a non-empty Symbol is one API.

type PackageDep

type PackageDep struct {
	Library string
	Version string
	// Href is that library at that exact version. The row already names the
	// coordinate; making the reader go and find it is a step it was holding
	// the answer to.
	Href string
}

PackageDep is one first-level dependency of ONE release, at the version that release resolved it to.

type PackageHit

type PackageHit struct {
	Ecosystem     string
	Name          string
	LatestVersion string
	Symbols       int
	EvidenceCount int64
	// UpdatedAt is when this package's compatibility snapshot was last
	// materialized — the date the records inventory orders by and prints.
	// "Most symbols first" answered "what does the network know most
	// about"; a log of measurements is read newest first.
	UpdatedAt string
	// Filter dimensions are populated by test stores and are not rendered.
	// The production adapter matches the same dimensions directly against
	// snapshot rows before it builds a PackageHit.
	OperatingSystems []string
	Runtimes         []string
	EvidenceBases    []string
}

PackageHit is one package search/hot result.

type ParsedRecordQuery

type ParsedRecordQuery struct {
	// contains filtered or unexported fields
}

ParsedRecordQuery turns the record search box into a small batch query. Package names are ORed: "react axios lodash" finds all three instead of looking for that impossible literal phrase in one package name.

func ParseRecordQuery

func ParseRecordQuery(raw string) ParsedRecordQuery

func (ParsedRecordQuery) MatchPackage

func (q ParsedRecordQuery) MatchPackage(name string) (match, exact, prefix bool)

MatchPackage reports a union match and two ranking hints. Exact package names lead prefix matches, which lead other substring matches.

type RecordFilter

type RecordFilter struct {
	Query     string
	Ecosystem string
	OS        string
	Runtime   string
	Basis     string // observed | verified | ""
}

RecordFilter is the user-visible slice of /records. Environment and evidence-basis dimensions are matched against materialized snapshot rows; an absent dimension does not count as a match.

type SampleListItem

type SampleListItem struct {
	SampleID string
	Goal     string
	Status   string
	License  string
	// Context is the execution context the sample was published from
	// ("node 22"), so a list row says which environment it answers for.
	Context   string
	CreatedAt string
	// Version is the package version this sample is about, and Symbols the
	// APIs it answers for. A sample answers one version of one API; without
	// these a package's list is an undifferentiated pile — uuid alone has
	// 96 published samples.
	Version string
	Symbols []string
	// Kind is the case kind: HOW | FIX | MIGRATION | CONFIG.
	Kind string
}

SampleListItem is one row of a published-samples list (a seeder's page, a package page, the sitemap).

type SampleMeta

type SampleMeta struct {
	SampleID     string
	Status       string // PUBLISHED | CROSS_PASS | MATRIX_PASS | STABLE | …
	License      string
	OriginSeeder string // "" ⇒ anonymous
	CreatedAt    string // RFC3339
	ManifestJSON string // csx.json content
	Files        []string
}

SampleMeta is the sample header the sample page renders.

type Store

type Store interface {
	// LatestStatsJSON returns the newest NetworkStats JSON, false when no
	// stats have been materialized yet.
	LatestStatsJSON(ctx context.Context) (string, bool)
	// SnapshotJSON returns the compatibility snapshot for (purl, symbol);
	// symbol "" addresses the package-level snapshot.
	SnapshotJSON(ctx context.Context, purl, symbol string) (string, bool)
	// PackageVersions lists known versions of a package, newest first.
	PackageVersions(ctx context.Context, ecosystem, name string) ([]string, error)
	// PackageSymbols lists symbol families with evidence for one version.
	PackageSymbols(ctx context.Context, ecosystem, name, version string) ([]string, error)
	// SymbolPackageSpread reports how many DISTINCT packages of one ecosystem
	// carry evidence for each symbol.
	//
	// One build's detected symbols are attributed to every package in its
	// closure, so commons-logging's page listed MockHttpServletRequest — a
	// Spring Test class — as its own API. 563 of the corpus's 4,165 symbols
	// are claimed by more than one package, worst case twenty-one. A count
	// above one means this evidence cannot say whose the symbol is.
	SymbolPackageSpread(ctx context.Context, ecosystem string, symbols []string) (map[string]int, error)
	// SampleMeta returns published-sample metadata by content id.
	SampleMeta(ctx context.Context, id string) (SampleMeta, bool)
	// SampleManifest returns only the stored manifest. Collection pages use
	// this instead of SampleMeta so they do not open and decompress the
	// artifact merely to learn its recorded environment.
	SampleManifest(ctx context.Context, id string) (manifestJSON string, ok bool)
	// SampleReceipts returns the verification-receipt JSON documents of a sample.
	SampleReceipts(ctx context.Context, id string) ([]string, error)
	// SeederSamples lists samples published under a seeder login.
	SeederSamples(ctx context.Context, login string) ([]SampleListItem, error)
	// ListSamples lists published samples, newest first, for the sitemap.
	// Quarantined samples must not appear.
	ListSamples(ctx context.Context, limit int) ([]SampleListItem, error)
	// PackageSamples lists published samples whose manifest names this
	// package, newest first. This is what puts a link to a sample page on
	// a page a crawler already reaches.
	PackageSamples(ctx context.Context, ecosystem, name string, limit int) ([]SampleListItem, error)
	// PackageCodeCounts returns exhaustive verified-sample counts by release
	// and API. It is deliberately separate from the bounded PackageSamples
	// display list: a newest-N page cannot prove that older code does not
	// exist.
	PackageCodeCounts(ctx context.Context, ecosystem, name string) ([]PackageCodeCount, error)
	// SearchPackages searches packages by name fragment.
	SearchPackages(ctx context.Context, q string, limit int) ([]PackageHit, error)
	// HotPackages returns the highest-traffic packages for sitemap use.
	HotPackages(ctx context.Context, limit int) ([]PackageHit, error)
	// RecordPackages returns one ranked page of the packages the network
	// has evidence for, plus the total so the page can be navigated.
	RecordPackages(ctx context.Context, filter RecordFilter, offset, limit int) (hits []PackageHit, total int, err error)
	// FailureClusters returns failure-cluster JSON documents for a package.
	// FailureClusters returns at most a page of clusters plus how many the
	// package actually has. pgx/v5 carries 133; rendering all of them was a
	// wall, and truncating without the total would read as "this is all".
	FailureClusters(ctx context.Context, ecosystem, name string) (clusters []string, total int, err error)
	// TopWanted lists the most-asked packages the network still has no
	// sample for, most wanted first.
	TopWanted(ctx context.Context, limit int) ([]WantedRow, error)
	// Coverage reports the network's own coverage per (platform, ecosystem).
	// A nil slice is not an error: the section simply does not render, which
	// is honest — an instrument that cannot describe itself should say
	// nothing rather than imply completeness.
	Coverage(ctx context.Context) ([]CoverageRow, error)
	// WantedRows returns one searchable, ranked page plus the number of
	// unanswered rows matching that query.
	WantedRows(ctx context.Context, query string, offset, limit int) (rows []WantedRow, total int, err error)
	WantedForPackage(ctx context.Context, ecosystem, name string) ([]WantedRow, error)
	// Dependencies lists what shipped ALONGSIDE each version of one package —
	// its first-level children, which is all anyone needs: the version that
	// moved under an upgrade is the one that broke the build.
	Dependencies(ctx context.Context, ecosystem, name string) ([]DependencyEdge, error)
	// DerivedFindings returns published samples that state the belief they
	// correct, newest first. These grow the /findings page without anyone
	// editing Go source.
	DerivedFindings(ctx context.Context, limit int) ([]DerivedFinding, error)
}

Store is the website's own consumer-side view of server data. The real serverstore is adapted to this interface by the integrator; tests use an in-memory fake. All snapshot/stats payloads arrive as JSON strings exactly as materialized (goal.md §14.5: web reads snapshots only).

type WantedItem

type WantedItem struct {
	Ecosystem string
	Name      string
	Version   string
	Asks      int64
	AsksText  string
	// DetailText says what the fold covered — how many distinct APIs were
	// asked about and on which platforms. Without it the board hid the fact
	// that four separate questions had been reported.
	DetailText string
	RankText   string
	Href       string
}

WantedItem is one unanswered coordinate on the board, with the separate questions asked about it folded in behind.

type WantedRollupRow

type WantedRollupRow struct {
	Ecosystem string
	Name      string
	Version   string
	Asks      int64
	// SymbolNames is kept, not just counted: with one distinct API asked
	// about, its name is far more use to a reader than "1 API". The count is
	// what rescues the four-rows-of-the-same-package case, not a replacement
	// for knowing what was asked.
	SymbolNames []string
	Symbols     int
	Platforms   []string
	HasPage     bool
}

WantedRollupRow is one package version as a reader recognises it, with the separate questions asked about it folded in behind.

The stored row is a WORK unit — package, version, symbol, platform — and it has to stay that fine-grained, because a Windows report and a Linux report about the same release are different questions and a proof of one does not answer the other. Rendered raw, though, the board repeated one package four times with "1" beside each, and a reader concluded the page was broken rather than that four distinct APIs had been asked about.

type WantedRow

type WantedRow struct {
	Ecosystem string
	Name      string
	Version   string
	Symbol    string
	Asks      int64
	// TargetOS is the platform the miss was reported from, empty when the
	// reporter named none. A report about a platform is a different question
	// from a report about the package, which is why it is part of the row
	// rather than a note beside it.
	TargetOS string
	// HasPage reports whether an explorer page exists for this package.
	// A wanted package usually has neither sample nor evidence, so linking
	// every row made a board of 404s.
	HasPage bool
}

WantedRow is one unanswered question: a package people asked about that nothing in the network answers yet.