Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 8 additions & 1 deletion Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -773,7 +773,7 @@ gen/docs-manifest: fmt/docs-manifest site/node_modules/.installed | _gen
# GitHub Actions linters are run in a separate CI job (lint-actions) that only
# triggers when workflow files change, so we skip them here when CI=true.
LINT_ACTIONS_TARGETS := $(if $(CI),,lint/actions/actionlint)
lint: lint/shellcheck lint/go lint/ts lint/examples lint/helm lint/site-icons lint/markdown lint/docs-html lint/docs-manifest lint/style-claims lint/check-scopes lint/migrations lint/bootstrap lint/architecture lint/emdash lint/agents lint/mise-versions $(LINT_ACTIONS_TARGETS)
lint: lint/shellcheck lint/go lint/ts lint/examples lint/helm lint/site-icons lint/markdown lint/docs-html lint/docs-manifest lint/style-claims lint/check-scopes lint/check-experiment-keys lint/migrations lint/bootstrap lint/architecture lint/emdash lint/agents lint/mise-versions $(LINT_ACTIONS_TARGETS)
.PHONY: lint

# Fast lint subset for lightweight hooks. Some targets use mise-managed tools.
Expand Down Expand Up @@ -845,6 +845,13 @@ lint/style-claims:
go run ./scripts/styleclaims
.PHONY: lint/style-claims

# Fails when documented --experiments and CODER_EXPERIMENTS values are not in
Comment thread
nickvigilante marked this conversation as resolved.
Resolved
# codersdk.ExperimentsKnown.
lint/check-experiment-keys:
echo "--- check documented experiment keys"
Comment thread
nickvigilante marked this conversation as resolved.
Resolved
go run ./scripts/checkexperimentkeys
.PHONY: lint/check-experiment-keys

lint/architecture:
./scripts/check_architecture.sh
.PHONY: lint/architecture
Expand Down
2 changes: 2 additions & 0 deletions codersdk/deployment.go
Original file line number Diff line number Diff line change
Expand Up @@ -5531,6 +5531,8 @@ func (e Experiment) DisplayName() string {
return "Workspace Usage Tracking"
case ExperimentMCPServerHTTP:
return "MCP HTTP Server Functionality"
case ExperimentMCPToolSearch:
return "MCP Tool Search"
case ExperimentWorkspaceBuildUpdates:
return "Workspace Build Updates Channel"
case ExperimentNoNATSPubsub:
Expand Down
37 changes: 37 additions & 0 deletions codersdk/deployment_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,43 @@ type exclusion struct {
yaml bool
}

// TestExperimentDisplayNames pins the display name of every known experiment.
// DisplayName falls back to a title-cased key, so an experiment missing its
// case renders a guess in the product UI instead of failing loudly. The length
// assertion forces a new experiment to be named here as well.
func TestExperimentDisplayNames(t *testing.T) {
t.Parallel()

expected := map[codersdk.Experiment]string{
codersdk.ExperimentExample: "Example Experiment",
codersdk.ExperimentAutoFillParameters: "Auto-fill Template Parameters",
codersdk.ExperimentNotifications: "SMTP and Webhook Notifications",
codersdk.ExperimentWorkspaceUsage: "Workspace Usage Tracking",
codersdk.ExperimentMCPServerHTTP: "MCP HTTP Server Functionality",
codersdk.ExperimentMCPToolSearch: "MCP Tool Search",
codersdk.ExperimentNoNATSPubsub: "No NATS Pubsub",
codersdk.ExperimentWorkspaceBuildUpdates: "Workspace Build Updates Channel",
codersdk.ExperimentWorkspaceCapableLicensing: "Workspace-Capable Licensing",
codersdk.ExperimentAIGatewaySeatExclusion: "AI Gateway Seat Exclusion",
codersdk.ExperimentAIGatewayReverseProxy: "AI Gateway Reverse Proxy",
codersdk.ExperimentChatProjects: "Chat Projects",
codersdk.ExperimentChatAdvisor: "Chat Advisor",
codersdk.ExperimentChatVirtualDesktop: "Chat Virtual Desktop",
codersdk.ExperimentAgentLifecycleHooks: "Agent Lifecycle Hooks",
codersdk.ExperimentChatInlineMCPServers: "Chat Inline MCP Servers",
codersdk.ExperimentEnableAIWorkspaceDebug: "AI Workspace Debugging",
codersdk.ExperimentChatBoard: "Chat Board",
codersdk.ExperimentChatStageMetrics: "Chat Stage Metrics",
}

require.Len(t, expected, len(codersdk.ExperimentsKnown))
for _, experiment := range codersdk.ExperimentsKnown {
displayName, ok := expected[experiment]
require.Truef(t, ok, "experiment %q has no expected display name", experiment)
require.Equal(t, displayName, experiment.DisplayName())
}
}

func TestDeploymentValues_HighlyConfigurable(t *testing.T) {
t.Parallel()

Expand Down
2 changes: 1 addition & 1 deletion docs/admin/integrations/oauth2-provider/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ title: OAuth2 provider
> [!NOTE]
> The OAuth2 provider is off by default.
> Set `CODER_OAUTH2_PROVIDER_ENABLE=true` to turn it on.
> The `oauth2` experiment has been removed, and setting `CODER_EXPERIMENTS=oauth2` now only logs a warning and does nothing.
> The `oauth2` experiment has been removed, and adding `oauth2` to `CODER_EXPERIMENTS` now only logs a warning and does nothing.
> Switch to `CODER_OAUTH2_PROVIDER_ENABLE=true` instead.

Coder can act as an OAuth2 authorization server, allowing third-party applications to authenticate users through Coder and access the Coder API on their behalf.
Expand Down
34 changes: 34 additions & 0 deletions scripts/checkexperimentkeys/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
# checkexperimentkeys

`checkexperimentkeys` validates experiment keys explicitly named in Markdown
under `docs/` against `codersdk.ExperimentsKnown`. It runs as
`make lint/check-experiment-keys`, which is part of `make lint`.

## Recognized forms

The check only recognizes explicit enablement examples:

- `--experiments=<key>`
- `CODER_EXPERIMENTS=<key>`
- comma-separated key lists in either form, such as
`--experiments=key-one,key-two`
- single- or double-quoted values, such as `CODER_EXPERIMENTS="key-one"`
- shell line continuations that start with one of the forms above

It deliberately does not try to infer bare identifiers from prose. The
placeholder values `*`, the documented illustrative pair `feature1` and
`feature2`, and any angle-bracketed value such as `<experiment-key>` or
`<key>` are ignored. Other `featureN` values are checked so a real stale key
is not treated as a placeholder.

Directory symlinks are not traversed. This keeps a directory scan contained to
the explicitly supplied tree and prevents a documentation checkout from
silently scanning Markdown outside it. A Markdown file supplied directly is
still scanned according to normal file access rules.

## Usage

```console
$ go run ./scripts/checkexperimentkeys # scans docs/
$ go run ./scripts/checkexperimentkeys path/to/file.md path/to/dir
```
175 changes: 175 additions & 0 deletions scripts/checkexperimentkeys/main.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,175 @@
// Command checkexperimentkeys validates experiment keys named in documentation.
//
// The check recognizes only explicit enablement forms: --experiments=<key-list>
// and CODER_EXPERIMENTS=<key-list>, where a key list is comma-separated. It
// deliberately does not infer bare identifiers from prose, which would make
// the check susceptible to false positives. Matching single- or double-quoted
// values are accepted. Placeholders are *, the documented feature1 and
// feature2 illustrative pair, and any angle-bracketed value.
//
// Usage:
//
// checkexperimentkeys [path ...]
//
// With no arguments it scans docs/. Arguments may be files or directories.
package main

import (
"fmt"
"io"
"io/fs"
"os"
"path/filepath"
"regexp"
"slices"
"sort"
"strings"

"github.com/coder/coder/v2/codersdk"
)

var (
experimentAssignment = regexp.MustCompile(`(?:--experiments|CODER_EXPERIMENTS)=(?:"([a-zA-Z0-9_*<>,-]+)"|'([a-zA-Z0-9_*<>,-]+)'|([a-zA-Z0-9_*<>,-]+))`)
shellContinuationAssignment = regexp.MustCompile(`(?:--experiments|CODER_EXPERIMENTS)=[a-zA-Z0-9_*<>,-]*\\$`)
)

type finding struct {
path string
line int
key string
}

func main() {
roots := os.Args[1:]
if len(roots) == 0 {
roots = []string{"docs"}
}
os.Exit(run(roots, os.Stderr))
}

// run scans roots, writes findings to stderr, and returns 0 for success, 1 for
// unknown keys, or 2 for I/O errors.
func run(roots []string, stderr io.Writer) int {
return runWithReadFile(roots, stderr, os.ReadFile)
}

func runWithReadFile(roots []string, stderr io.Writer, readFile func(string) ([]byte, error)) int {
files, err := collectMarkdown(roots)
if err != nil {
_, _ = fmt.Fprintf(stderr, "checkexperimentkeys: %v\n", err)
return 2
}

known := make(map[string]bool, len(codersdk.ExperimentsKnown))
for _, experiment := range codersdk.ExperimentsKnown {
known[string(experiment)] = true
}

var findings []finding
for _, path := range files {
src, err := readFile(path)
if err != nil {
_, _ = fmt.Fprintf(stderr, "checkexperimentkeys: %v\n", err)
return 2
}
findings = append(findings, checkSource(path, src, known)...)
}

for _, finding := range findings {
_, _ = fmt.Fprintf(stderr, "%s:%d: unknown experiment key %q; add it to codersdk.ExperimentsKnown or remove or update this documented enablement example.\n", finding.path, finding.line, finding.key)
}
if len(findings) > 0 {
_, _ = fmt.Fprintf(stderr, "\ncheckexperimentkeys: found %d documented experiment key(s) that are not in codersdk.ExperimentsKnown.\n", len(findings))
return 1
}

return 0
}

func checkSource(path string, src []byte, known map[string]bool) []finding {
var findings []finding
for _, line := range shellLogicalLines(string(src)) {
for _, match := range experimentAssignment.FindAllStringSubmatch(line.text, -1) {
for _, key := range strings.Split(experimentValue(match), ",") {
if key == "" || known[key] || isPlaceholder(key) {
continue
}
findings = append(findings, finding{path: path, line: line.number, key: key})
}
}
}
return findings
}

type logicalLine struct {
number int
text string
}

func shellLogicalLines(src string) []logicalLine {
physicalLines := strings.Split(src, "\n")
logicalLines := make([]logicalLine, 0, len(physicalLines))
for lineIndex := 0; lineIndex < len(physicalLines); lineIndex++ {
line := physicalLines[lineIndex]
logicalLine := logicalLine{number: lineIndex + 1, text: line}

// Markdown also uses a trailing backslash as a hard line break. Only join
// a line ending in an explicit, unquoted assignment the recognizer accepts.
if shellContinuationAssignment.MatchString(logicalLine.text) {
for lineIndex+1 < len(physicalLines) {
lineIndex++
logicalLine.text = strings.TrimSuffix(logicalLine.text, "\\") + physicalLines[lineIndex]
if !strings.HasSuffix(logicalLine.text, "\\") {
break
}
}
}
logicalLines = append(logicalLines, logicalLine)
}
return logicalLines
}

func experimentValue(match []string) string {
for _, value := range match[1:] {
if value != "" {
return value
}
}
return ""
}

func isPlaceholder(key string) bool {
return key == "*" || key == "feature1" || key == "feature2" ||
(strings.HasPrefix(key, "<") && strings.HasSuffix(key, ">"))
}

func collectMarkdown(roots []string) ([]string, error) {
Comment thread
nickvigilante marked this conversation as resolved.
Resolved
var files []string
for _, root := range roots {
info, err := os.Stat(root)
if err != nil {
return nil, err
}
if !info.IsDir() {
if filepath.Ext(root) == ".md" {
files = append(files, root)
}
continue
}
err = filepath.WalkDir(root, func(path string, entry fs.DirEntry, err error) error {
if err != nil {
return err
}
if entry.IsDir() || filepath.Ext(path) != ".md" {
return nil
}
files = append(files, path)
return nil
})
if err != nil {
return nil, err
}
}
sort.Strings(files)
return slices.Compact(files), nil
}
Loading
Loading