@redpanda-data/docs-extensions-and-macros 5.31.0 → 5.35.1

package/bin/doc-tools-mcp.js

@@ -446,7 +446,7 @@ const tools = [
         },
         surface: {
           type: 'string',
-          description: 'Comma-separated surfaces to lint: properties, metrics, rpk, helm, crd, connect (optional, defaults to all)'
+          description: `Comma-separated surfaces to lint: ${Object.keys(require('../tools/lint-strings').SURFACES).join(', ')} (optional, defaults to all)`
         },
         diff: {
           type: 'string',

package/bin/doc-tools.js

@@ -122,9 +122,9 @@ programCli
  * - A GitHub token with access to redpanda-data/streaming-enterprise, which is
  *   private. Redpanda releases are published there now, and the old public repo
  *   is frozen, so this command exits rather than report a stale version when it
- *   has no token. Resolved from GIT_CREDENTIALS, REDPANDA_GITHUB_TOKEN,
- *   ACTIONS_BOT_TOKEN, GITHUB_TOKEN, VBOT_GITHUB_API_TOKEN, or GH_TOKEN, in
- *   that priority order
+ *   has no token. Resolved from REDPANDA_GITHUB_TOKEN, ACTIONS_BOT_TOKEN,
+ *   GITHUB_TOKEN, VBOT_GITHUB_API_TOKEN, GH_TOKEN, or GIT_CREDENTIALS, in that
+ *   priority order (an API call, so the git credential is the last resort)
  */
 programCli
   .command('get-redpanda-version')
@@ -1908,7 +1908,7 @@ automation
  *
  * @requirements
  * - GitHub token with access to redpanda-data/cloudv2-infra repository
- * - Token is resolved from GIT_CREDENTIALS, REDPANDA_GITHUB_TOKEN, ACTIONS_BOT_TOKEN, GITHUB_TOKEN, VBOT_GITHUB_API_TOKEN, or GH_TOKEN, in that priority order
+ * - Token is resolved from REDPANDA_GITHUB_TOKEN, ACTIONS_BOT_TOKEN, GITHUB_TOKEN, VBOT_GITHUB_API_TOKEN, GH_TOKEN, or GIT_CREDENTIALS, in that priority order (an API call, so the git credential is the last resort)
  * - Internet connection to access GitHub API
  */
 automation
@@ -1925,7 +1925,7 @@ automation
   .option('--dry-run', 'Print output to stdout instead of writing file')
   .action(async (options, command) => {
     const { generateCloudRegions } = require('../tools/cloud-regions/generate-cloud-regions.js')
-    const { getGitHubToken } = require('../cli-utils/github-token')
+    const { getGitHubApiToken } = require('../cli-utils/github-token')
 
     try {
       // The default output path holds the unfiltered table, so a filtered run
@@ -1947,7 +1947,7 @@ automation
       const absOutput = options.dryRun
         ? undefined
         : resolveInsideRepo(repoRoot, options.output, '--output')
-      const token = getGitHubToken()
+      const token = getGitHubApiToken()
       if (!token) {
         throw new Error('GitHub token is required to fetch from private cloudv2-infra repo.')
       }
@@ -2622,7 +2622,9 @@ programCli
   .command('lint-strings')
   .description('Lint user-facing doc strings embedded in engineering source code (properties, metrics, ...)')
   .requiredOption('--repo <path>', 'Path to an existing engineering checkout (for example, a local redpanda clone). Nothing is cloned.')
-  .option('--surface <list>', 'Comma-separated surfaces to lint (default: all registered). Registered: properties, metrics, rpk, helm, crd, connect')
+  // Read off the registry rather than restated here: a hardcoded list silently
+  // went stale the moment a surface was added.
+  .option('--surface <list>', `Comma-separated surfaces to lint (default: all registered). Registered: ${Object.keys(require('../tools/lint-strings').SURFACES).join(', ')}`)
   .option('--diff <base>', 'Declaration-anchored diff mode: lint only declarations whose full span intersects lines changed in <base>...HEAD')
   .option('--format <format>', 'Output format: human or json', 'human')
   .option('--skip-rules <list>', 'Comma-separated rule ids to skip')

package/bin/mcp-tools/lint-doc-strings.js

@@ -16,7 +16,8 @@ const DOC_TOOLS_BIN = path.resolve(__dirname, '..', 'doc-tools.js');
  * Lint user-facing doc strings embedded in engineering source code
  * @param {Object} args - Arguments
  * @param {string} args.repo - Path to the engineering checkout (required)
- * @param {string} [args.surface] - Comma-separated surfaces (properties, metrics, rpk, helm, crd, connect)
+ * @param {string} [args.surface] - Comma-separated surfaces; see the SURFACES
+ *   registry in tools/lint-strings/index.js for the current list
  * @param {string} [args.diff] - Base ref for declaration-anchored diff mode
  * @param {string} [args.skip_rules] - Comma-separated rule ids to skip
  * @param {string} [args.only_rules] - Comma-separated rule ids to run exclusively

package/cli-utils/enterprise-sources.js

@@ -12,7 +12,7 @@
 
 const fs = require('fs')
 const path = require('path')
-const { getGitHubToken } = require('./github-token')
+const { getGitHubApiToken } = require('./github-token')
 
 const RAW = 'https://raw.githubusercontent.com'
 
@@ -62,7 +62,7 @@ async function discardBody (resp) {
  * check runs on a weekly cron where nobody is watching live.
  *
  * @param {object} [deps]
- * @param {string|null} [deps.token] - GitHub token (defaults to getGitHubToken())
+ * @param {string|null} [deps.token] - GitHub token (defaults to getGitHubApiToken())
  * @param {Function} [deps.fetchImpl] - fetch implementation (defaults to global fetch)
  * @param {Function} [deps.warn] - warning sink (defaults to console.warn)
  * @param {Function} [deps.sleep] - delay implementation, for tests
@@ -72,7 +72,7 @@ async function discardBody (resp) {
  *   check that never ran. Failures without a sourceName throw instead.
  */
 function createSourceFetcher (deps = {}) {
-  const ghToken = deps.token !== undefined ? deps.token : getGitHubToken()
+  const ghToken = deps.token !== undefined ? deps.token : getGitHubApiToken()
   const fetchImpl = deps.fetchImpl || ((...args) => fetch(...args))
   const warn = deps.warn || ((msg) => console.warn(msg))
   const sleep = deps.sleep || ((ms) => new Promise((resolve) => setTimeout(resolve, ms)))

package/cli-utils/github-token.js

@@ -47,9 +47,25 @@ function getTokenFromGitCredentials(credentials = process.env.GIT_CREDENTIALS) {
   return null;
 }
 
+const API_TOKEN_VARS = [
+  'REDPANDA_GITHUB_TOKEN',
+  'ACTIONS_BOT_TOKEN',
+  'GITHUB_TOKEN',
+  'VBOT_GITHUB_API_TOKEN',
+  'GH_TOKEN'
+];
+
+function firstApiTokenVar() {
+  for (const name of API_TOKEN_VARS) {
+    if (process.env[name]) return process.env[name];
+  }
+  return null;
+}
+
 /**
- * Get GitHub token from environment variables
- * Checks multiple common variable names in priority order:
+ * Get the GitHub token for git operations (clone, fetch, authenticated URLs).
+ *
+ * Checks, in priority order:
  * 1. GIT_CREDENTIALS - Antora's credential store contents (github.com entry)
  * 2. REDPANDA_GITHUB_TOKEN - Custom Redpanda token
  * 3. ACTIONS_BOT_TOKEN - GitHub Actions bot token
@@ -57,21 +73,44 @@ function getTokenFromGitCredentials(credentials = process.env.GIT_CREDENTIALS) {
  * 5. VBOT_GITHUB_API_TOKEN - Legacy bot token
  * 6. GH_TOKEN - GitHub CLI default
  *
- * Note: this resolver feeds both git clone/fetch auth and GitHub API clients
- * (Octokit). Wherever GIT_CREDENTIALS is set (for example, Antora builds on
- * Netlify), API calls authenticate with that same token, whose API scopes may
- * differ from the token env vars it outranks.
+ * GIT_CREDENTIALS wins here on purpose: it is the credential Antora itself
+ * clones the content repos with, so anything else that clones in the same
+ * build should use the same identity. It is a git credential, not an API
+ * one; for REST calls use getGitHubApiToken().
  *
  * @returns {string|null} GitHub token or null if not found
  */
 function getGitHubToken() {
-  return getTokenFromGitCredentials() ||
-         process.env.REDPANDA_GITHUB_TOKEN ||
-         process.env.ACTIONS_BOT_TOKEN ||
-         process.env.GITHUB_TOKEN ||
-         process.env.VBOT_GITHUB_API_TOKEN ||
-         process.env.GH_TOKEN ||
-         null;
+  return getTokenFromGitCredentials() || firstApiTokenVar();
+}
+
+/**
+ * Get the GitHub token for REST API calls (Octokit, api.github.com,
+ * raw.githubusercontent.com).
+ *
+ * Same variables as getGitHubToken(), but GIT_CREDENTIALS comes LAST:
+ *
+ * 1. REDPANDA_GITHUB_TOKEN
+ * 2. ACTIONS_BOT_TOKEN
+ * 3. GITHUB_TOKEN
+ * 4. VBOT_GITHUB_API_TOKEN
+ * 5. GH_TOKEN
+ * 6. GIT_CREDENTIALS
+ *
+ * Why the different order: on the Netlify Antora sites GIT_CREDENTIALS holds
+ * a token scoped only to cloning the private docs content repos. Letting it
+ * outrank REDPANDA_GITHUB_TOKEN meant the release lookup against the private
+ * streaming-enterprise repo authenticated with a token that cannot see that
+ * repo, got a 404, and every latest-redpanda-* attribute went unset in the
+ * production build even though a token with access was sitting right there.
+ * An explicitly named API token always beats the git credential; the git
+ * credential remains a fallback so a build with only GIT_CREDENTIALS still
+ * authenticates.
+ *
+ * @returns {string|null} GitHub token or null if not found
+ */
+function getGitHubApiToken() {
+  return firstApiTokenVar() || getTokenFromGitCredentials();
 }
 
 /**
@@ -106,6 +145,7 @@ function hasGitHubToken() {
 
 module.exports = {
   getGitHubToken,
+  getGitHubApiToken,
   getTokenFromGitCredentials,
   getAuthenticatedGitHubUrl,
   hasGitHubToken

package/cli-utils/octokit-client.js

@@ -1,7 +1,7 @@
 'use strict'
 
 const { Octokit } = require('@octokit/rest')
-const { getGitHubToken } = require('./github-token')
+const { getGitHubApiToken } = require('./github-token')
 
 /**
  * Shared Octokit client instance for GitHub API access
@@ -14,7 +14,7 @@ const { getGitHubToken } = require('./github-token')
  */
 
 // Get authentication token from environment
-const token = getGitHubToken()
+const token = getGitHubApiToken()
 
 // Configure Octokit options
 const octokitOptions = {

package/cli-utils/self-managed-docs-branch.js

@@ -1,6 +1,6 @@
 const yaml = require('js-yaml');
 const { spawnSync } = require('child_process');
-const { getGitHubToken } = require('./github-token');
+const { getGitHubApiToken } = require('./github-token');
 
 const ANTORA_URL = 'https://raw.githubusercontent.com/redpanda-data/docs/main/antora.yml'
 
@@ -23,7 +23,7 @@ const REJECTED_HINT = ' A GitHub token was sent but rejected, so it may be expir
  */
 async function fetchRemoteAntoraVersion(deps = {}) {
   const fetchImpl = deps.fetchImpl || fetch
-  const ghToken = 'token' in deps ? deps.token : getGitHubToken()
+  const ghToken = 'token' in deps ? deps.token : getGitHubApiToken()
 
   let resp = await fetchImpl(ANTORA_URL, ghToken ? { headers: { Authorization: `Bearer ${ghToken}` } } : undefined)
   const hint = ghToken ? REJECTED_HINT : TOKEN_HINT

package/extensions/version-fetcher/set-latest-version.js

@@ -10,10 +10,13 @@ module.exports.register = function ({ config }) {
   const GetLatestConnectVersion = require('./get-latest-connect');
   const logger = this.getLogger('set-latest-version-extension');
 
-  const { getGitHubToken } = require('../../cli-utils/github-token');
+  const { getGitHubApiToken } = require('../../cli-utils/github-token');
   // Shared with tools/bundle-openapi.js so there is one major.minor derivation.
   const { toShortVersion } = require('../../cli-utils/version');
-  const token = getGitHubToken();
+  // API token, not the git one: GIT_CREDENTIALS (Antora's clone credential)
+  // is only a last resort here, because on Netlify it is scoped to the docs
+  // content repos and cannot see streaming-enterprise.
+  const token = getGitHubApiToken();
 
   if (!token) {
     // Unauthenticated requests still work for the public repos this
@@ -21,7 +24,7 @@ module.exports.register = function ({ config }) {
     // version now comes from the private streaming-enterprise repo, whose
     // API 404s without a token -- the latest-redpanda-* attributes are then
     // left unset and pages fall back to their antora.yml values.
-    logger.warn('GitHub token not set (GIT_CREDENTIALS, REDPANDA_GITHUB_TOKEN, GITHUB_TOKEN, or GH_TOKEN). The Redpanda version lookup against the private streaming-enterprise repo will fail and leave latest-redpanda-* attributes unset; other lookups proceed unauthenticated.');
+    logger.warn('GitHub token not set (REDPANDA_GITHUB_TOKEN, GITHUB_TOKEN, GH_TOKEN, or GIT_CREDENTIALS). The Redpanda version lookup against the private streaming-enterprise repo will fail and leave latest-redpanda-* attributes unset; other lookups proceed unauthenticated.');
   }
 
   this.on('contentClassified', async ({ contentCatalog }) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@redpanda-data/docs-extensions-and-macros",
-  "version": "5.31.0",
+  "version": "5.35.1",
   "description": "Antora extensions and macros developed for Redpanda documentation.",
   "keywords": [
     "antora",

package/tools/get-redpanda-version.js

@@ -2,7 +2,7 @@
 
 const GetLatestRedpandaVersion = require('../extensions/version-fetcher/get-latest-redpanda-version.js');
 const { getPrereleaseFromAntora } = require('../cli-utils/antora-utils.js');
-const { getGitHubToken } = require('../cli-utils/github-token');
+const { getGitHubApiToken } = require('../cli-utils/github-token');
 
 /**
  * Fetches and prints the latest Redpanda version and Docker repository.
@@ -20,7 +20,7 @@ module.exports = async function getRedpandaVersion({ beta = false, fromAntora =
   const owner = 'redpanda-data';
   const repo = 'streaming-enterprise';
 
-  if (!getGitHubToken()) {
+  if (!getGitHubApiToken()) {
     console.error(`❌ redpanda-data/${repo} is a private repository.`);
     console.error('   Set GH_TOKEN, REDPANDA_GITHUB_TOKEN, or GITHUB_TOKEN to a token with access.');
     process.exit(1);

package/tools/lint-strings/diff.js

@@ -26,7 +26,21 @@ const SURFACE_ROUTES = [
   // console) and charts/<name>/values.yaml (connectors).
   { surface: 'helm', pattern: /^charts\/[^/]+\/(chart\/)?values\.yaml$/ },
   { surface: 'crd', pattern: /^operator\/api\// },
-  { surface: 'connect', pattern: /^internal\/impl\// }
+  { surface: 'connect', pattern: /^internal\/impl\// },
+  // API protos, whose comments and openapiv2 option strings reach readers as
+  // OpenAPI descriptions. console holds the data plane and Console APIs under
+  // proto/redpanda/api/; cloudv2's control plane lives under proto/public/.
+  // Anchored on the api/ segment so cloudv2's proto/descriptors/ tree (private
+  // and internal) and every vendored proto/public/**/wellknown/ path stay out.
+  { surface: 'api', pattern: /^proto\/(?:redpanda\/api|public\/[^/]+\/redpanda\/api)\/.*\.proto$/ },
+  // Admin API v2, in the redpanda/streaming-enterprise repo. A different
+  // generator (protoc-gen-connect-openapi) and a third string form; see
+  // surfaces/api.js. These two directories are exactly what the api-docs
+  // bundler feeds into the published spec (tools/bundle-openapi.js):
+  // `admin/internal` and `core/testing` are excluded by that repo's buf.yaml
+  // and generate nothing, and `core/rest` generates a fragment that is never
+  // bundled, so none of them reach readers.
+  { surface: 'api', pattern: /^proto\/redpanda\/core\/(?:admin\/v2|common)\/.*\.proto$/ }
 ]
 
 /**

package/tools/lint-strings/fixtures/api/lint_admin_v2.proto

@@ -0,0 +1,114 @@
+// Copyright 2026 Redpanda Data, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+//
+// A license header is a leading comment on nothing. It must not attach itself
+// to the first declaration in the file.
+
+syntax = "proto3";
+
+package redpanda.core.admin.v2;
+
+import "proto/redpanda/core/pbgen/rpc.proto";
+
+option (pbgen.cpp_namespace) = "proto::fixture";
+
+service FixtureService {
+    // GetFixture
+    //
+    // Returns a single fixture.
+    rpc GetFixture(GetFixtureRequest) returns (GetFixtureResponse) {
+        option (pbgen.rpc) = {
+            authz: SUPERUSER
+        };
+    }
+
+    // CreateFixture
+    //
+    // Creates a fixture. The description can run over several comment
+    // lines, and the resolved prose joins them.
+    //
+    // A blank comment line inside the description is a paragraph break and
+    // stays part of the description.
+    rpc CreateFixture(CreateFixtureRequest)
+        returns (CreateFixtureResponse) {
+        option (pbgen.rpc) = {
+            authz: SUPERUSER
+        };
+    }
+
+    // Reports the collapsed case: with no blank line the generator uses this
+    // whole comment as BOTH the summary and the description, so the API
+    // reference's nav item becomes a paragraph.
+    rpc CollapsedFixture(CollapsedFixtureRequest)
+        returns (CollapsedFixtureResponse) {
+        option (pbgen.rpc) = {
+            authz: SUPERUSER
+        };
+    }
+
+    // DeleteFixture.
+    //
+    // Deletes a fixture.
+    rpc DeleteFixture(DeleteFixtureRequest) returns (DeleteFixtureResponse) {
+        option (pbgen.rpc) = {
+            authz: SUPERUSER
+        };
+    }
+
+    // ListFixtures
+    // over two lines
+    //
+    // Lists every fixture.
+    rpc ListFixtures(ListFixturesRequest) returns (ListFixturesResponse) {
+        option (pbgen.rpc) = {
+            authz: SUPERUSER
+        };
+    }
+
+    // BodylessFixture
+    //
+    // A body-less rpc opens no block, so it must not swallow the
+    // declarations that follow it.
+    rpc BodylessFixture(BodylessFixtureRequest) returns (BodylessFixtureResponse);
+
+    // WatchFixture
+    //
+    // Confirms the rpc after a body-less one is still found.
+    rpc WatchFixture(WatchFixtureRequest) returns (WatchFixtureResponse) {
+        option (pbgen.rpc) = {
+            authz: SUPERUSER
+        };
+    }
+}
+
+// The request for a single fixture.
+message GetFixtureRequest {
+    // The node ID for the fixture. If unset, the broker handling the RPC
+    // returns information about itself.
+    optional int32 node_id = 1;
+
+    // Fixture name
+    string name = 2;
+
+    int32 undocumented = 3;
+
+    // Partition ID
+    int32 partition_id = 4;
+
+    // The protocol versions the fixture supports. See
+    // https://kafka.apache.org/protocol.html#protocol_compatibility
+    repeated int32 api_versions = 5;
+}
+
+// Fixture mode
+//
+// - Not specified
+// - Runs fast
+enum FixtureMode {
+    FIXTURE_MODE_UNSPECIFIED = 0;
+    // Per-value comments are discarded by protoc-gen-connect-openapi, so they
+    // are not extracted and must not be reported as declarations.
+    FIXTURE_MODE_FAST = 1;
+}

package/tools/lint-strings/fixtures/api/lint_api.proto

@@ -0,0 +1,123 @@
+syntax = "proto3";
+
+package redpanda.api.fixture.v1;
+
+import "google/protobuf/descriptor.proto";
+import "protoc-gen-openapiv2/options/annotations.proto";
+
+// Extension fields are wire metadata, never published schema. The field
+// inside this block must not be extracted.
+extend google.protobuf.MethodOptions {
+  string fixture_extension = 60002;
+}
+
+// FixtureMode selects how the fixture behaves.
+enum FixtureMode {
+  FIXTURE_MODE_UNSPECIFIED = 0;
+  FIXTURE_MODE_FAST = 1;
+}
+
+// A fixture topic.
+message FixtureTopic {
+  // A topic-level config key (e.g. `segment.bytes`).
+  string name = 1;
+
+  // Whether the config is read-only, or is dynamic and can be altered.
+  bool read_only = 2;
+
+  // Wrapped option lists must be covered by the declaration span, so a
+  // suggestion block can replace the whole statement.
+  string wrapped = 3 [
+    (buf.validate.field).string.min_len = 1,
+    (buf.validate.field).string.max_len = 255
+  ];
+
+  // Sets default_topic_partitions when the topic is created.
+  int32 partitions = 4;
+
+  // A comment can wrap over several lines, and the resolved prose joins them
+  // rather than keeping only the first.
+  string wrapped_comment = 5;
+
+  string undocumented = 6;
+
+  // An openapiv2_field description OVERRIDES this comment, so the comment is
+  // dead text and the option's string is what must be linted.
+  string option_documented = 9 [
+    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+      description: "The string the generator actually publishes."
+      example: "\"ignored\""
+    }
+  ];
+
+  /*
+   * A field documented ONLY by an openapiv2_field option is not an
+   * undocumented field. 73 of console's fields are this shape and every one
+   * of them used to be reported as having no description.
+   *
+   * This note is a detached block comment, separated by a blank line, so that
+   * option_only genuinely has no leading comment of its own.
+   */
+
+  string option_only = 10 [
+    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+      description: "Documented by the option alone."
+    }
+  ];
+
+  // A oneof moves the brace depth without opening a message. Matching a bare
+  // closing brace here popped FixtureTopic and reported the sibling message
+  // below as nested inside it.
+  oneof selector {
+    // Selects by name.
+    string by_name = 7;
+    // Selects by id.
+    string by_id = 8;
+  }
+
+  // Nested messages are genuinely nested and should report a dotted path.
+  message Nested {
+    // The nested value.
+    string value = 1;
+  }
+}
+
+// A sibling of FixtureTopic, not a child of it.
+message FixtureSibling {
+  // The sibling name.
+  string name = 1;
+}
+
+service FixtureService {
+  rpc CreateFixture(FixtureTopic) returns (FixtureTopic) {
+    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      summary: "Create fixture."
+      description: "Create a [fixture](https://docs.redpanda.com/fixture/) with a `{prefix}` path."
+      responses: {
+        key: "200"
+        value: {description: "OK"}
+      }
+      responses: {
+        key: "201"
+        value: {description: "Fixture created"}
+      }
+    };
+  }
+
+  rpc ListFixtures(FixtureTopic) returns (FixtureTopic) {
+    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      summary: "List fixtures"
+      description: "Short one"
+    };
+  }
+
+  rpc JoinFixtures(FixtureTopic) returns (FixtureTopic) {
+    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      summary: "Join fixtures"
+      // Proto concatenates adjacent string literals like C++, so the resolved
+      // description is both halves, not just the first.
+      description: "Joins two fixtures together "
+                   "and returns the result."
+    };
+  }
+}

package/tools/lint-strings/fixtures/connect/lint_connect.go

@@ -28,7 +28,7 @@ This fixture exercises the ` + "`raw` + interpreted + `raw`" + ` concatenation i
 This heading and the table below are legitimate AsciiDoc:
 
 |===
-| kafka_key | The record key
+| `+"`kafka_key`"+` | The record key
 |===
 `).
 		Fields(fixtureConfigFields()...)

package/tools/lint-strings/fixtures/crd/lint_types.go

@@ -4,6 +4,7 @@ package v1alpha2
 
 import (
 	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+	"k8s.io/apimachinery/pkg/runtime"
 )
 
 // WidgetSpec defines the configuration of a fixture widget.
@@ -35,6 +36,75 @@ type WidgetReference struct {
 	Version int    `json:"version"`
 }
 
+// EmptyOnOneLine opens and closes on a single line. Assuming it opened a
+// struct body left the parser inside a type that had already ended, which
+// dropped every declaration below it in the file.
+type EmptyOnOneLine struct{}
+
+// ValueSource represents where a value can be pulled from.
+type ValueSource struct {
+	// The literal value.
+	Value string `json:"value,omitempty"`
+}
+
+// UndocumentedType has no doc comment of its own, so a field referencing it
+// has nothing to inherit and genuinely ships blank.
+type undocumentedTypeMarker int
+
+type UndocumentedTarget struct {
+	// The only field.
+	Only string `json:"only,omitempty"`
+}
+
+// InlinedValues is +hidefromdoc, but it is embedded with `json:",inline"`
+// below, so crd-ref-docs flattens its fields into the embedding type and
+// publishes every one of them. The marker suppresses this type's own section,
+// not its fields.
+// +hidefromdoc
+type InlinedValues struct {
+	ReplicaCount *int32 `json:"replicaCount,omitempty"`
+}
+
+// HiddenNotInlined is +hidefromdoc and embedded nowhere, so nothing it
+// declares is ever published.
+// +hidefromdoc
+type HiddenNotInlined struct {
+	NeverPublished string `json:"neverPublished,omitempty"`
+}
+
+// EmbeddingSpec inlines a hidden type.
+type EmbeddingSpec struct {
+	InlinedValues `json:",inline"`
+	// The name of the thing.
+	Name string `json:"name,omitempty"`
+}
+
+// StructuralSpec covers external types that controller-gen publishes with no
+// description of their own.
+type StructuralSpec struct {
+	// +optional
+	Config *runtime.RawExtension `json:"config,omitempty"`
+	// +optional
+	Expiration *metav1.Time `json:"expiration,omitempty"`
+}
+
+// FallbackSpec covers what an uncommented field actually publishes.
+type FallbackSpec struct {
+	// +optional
+	Inherited *ValueSource `json:"inherited,omitempty"`
+	// +optional
+	FromUndocumented *UndocumentedTarget `json:"fromUndocumented,omitempty"`
+	// +optional
+	Primitive string `json:"primitive,omitempty"`
+	// +optional
+	SliceOfDocumented []ValueSource `json:"sliceOfDocumented,omitempty"`
+	// +optional
+	External *metav1.Duration `json:"external,omitempty"`
+	// How long to wait before giving up on the widget.
+	// +optional
+	Both *ValueSource `json:"both,omitempty"`
+}
+
 // WidgetList is ignored via the config's ignoreTypes ('List$').
 type WidgetList struct {
 	metav1.TypeMeta `json:",inline"`