@redpanda-data/docs-extensions-and-macros 5.51.1 → 5.52.0

package/extensions/modify-connect-tag-playbook.js

@@ -1,29 +1,195 @@
 'use strict';
 
+// Sources the Redpanda Connect reference partials from the connect repo.
+//
+// A playbook lists the connect repo as a content source:
+//
+//   - url: https://github.com/redpanda-data/connect
+//     tags: latest        # replaced with the latest release tag at build time
+//     start_path: docs
+//
+// The extension does two things:
+//
+// 1. Pins the source to the latest connect release tag, so the docs never
+//    show fields from unreleased code on connect's main branch.
+// 2. Filters what the source contributes: only the generated
+//    modules/components/partials and modules/components/examples trees of the
+//    `connect` component are kept, and any file another source (rp-connect-docs)
+//    already provides is dropped. Antora fails the build on a duplicate page or
+//    partial, so this makes it safe to add the source to a playbook before or
+//    after rp-connect-docs stops committing its own generated copies, and it
+//    ignores the full pages that older connect tags still carry.
+//
+// It also shares the tag it resolves (util/connect-catalog), so
+// generate-rp-connect-info reads info.csv from the same ref as the reference
+// content.
+
 const { raiseListenerLimit } = require('./util/raise-listener-limit')
+const getLatestConnectTag = require('./version-fetcher/get-latest-connect')
+const { getGitHubApiToken } = require('../cli-utils/github-token')
+const { isConnectSource, isConnectOrigin, githubRepoOf, setResolvedConnectRef } = require('./util/connect-catalog')
+
+const OWNER = 'redpanda-data'
+const REPO = 'connect'
+const COMPONENT = 'connect'
+const KEPT_PATHS = ['modules/components/partials/', 'modules/components/examples/']
+
+// HTTPS, SSH (ssh://), and scp-style (git@host:owner/repo) URLs are all
+// remote content sources in Antora.
+function isRemote (url) {
+  return /^(https?|ssh):\/\//.test(url || '') || /^[\w.-]+@[\w.-]+:/.test(url || '')
+}
+
+// Only the redpanda-data/connect remote resolves to its own latest release.
+// A fork with the same repo name would otherwise be pinned to a tag looked up
+// on redpanda-data/connect.
+function isUpstreamConnect (url) {
+  const repo = githubRepoOf(url)
+  return !!repo && repo.owner === OWNER && repo.repo === REPO
+}
+
+// Removes user info from every URL in the text, so credentials embedded in a
+// content-source URL never reach the build log.
+function redact (text) {
+  return String(text || '').replace(/([a-z][a-z+.-]*:\/\/)[^@/\s]*@/gi, '$1')
+}
+
+// Highest stable vX.Y.Z tag from `git ls-remote` output. Used when the GitHub
+// API is unavailable, for example when an unauthenticated build is rate limited.
+function highestStableTag (lsRemoteOutput) {
+  const newer = (a, b) => a[0] - b[0] || a[1] - b[1] || a[2] - b[2]
+  let best = null
+  for (const line of String(lsRemoteOutput || '').split('\n')) {
+    const m = line.match(/refs\/tags\/(v(\d+)\.(\d+)\.(\d+))$/)
+    if (!m) continue
+    const v = m.slice(2, 5).map(Number)
+    if (!best || newer(v, best.v) > 0) best = { tag: m[1], v }
+  }
+  return best && best.tag
+}
+
+function latestTagFromGit (url) {
+  const { execFileSync } = require('child_process')
+  return highestStableTag(execFileSync('git', ['ls-remote', '--tags', '--refs', url], { encoding: 'utf8', timeout: 60000 }))
+}
+
+function toTag (tagName) {
+  if (!tagName) return null
+  return tagName.startsWith('v') ? tagName : `v${tagName}`
+}
 
-const GetLatestConnectTag = require('./version-fetcher/get-latest-connect');
+// The upstream connect source asks to be pinned with `tags: latest` as its
+// only ref. A source with any other refs, such as a fork or a PR branch used
+// to preview a connect change, keeps what the playbook says.
+function wantsLatest (source) {
+  if (!isRemote(source.url) || !isConnectSource(source.url) || !isUpstreamConnect(source.url)) return false
+  const tags = Array.isArray(source.tags) ? source.tags : [source.tags]
+  const branches = source.branches == null ? [] : [].concat(source.branches)
+  return tags.length === 1 && tags[0] === 'latest' && branches.length === 0
+}
+
+// Rewrites the connect content sources that ask for the latest release to
+// use `tag`. Returns true when a source was updated.
+function pinConnectSource (playbook, tag) {
+  const sources = playbook && playbook.content && playbook.content.sources
+  if (!Array.isArray(sources) || !tag) return false
+  let updated = false
+  for (const source of sources) {
+    if (!wantsLatest(source)) continue
+    source.tags = [tag]
+    // Without this, Antora's default branch patterns also pull in main.
+    source.branches = []
+    updated = true
+  }
+  return updated
+}
+
+// Removes connect-sourced files that must not be published. Mutates the
+// content aggregate and returns what it dropped.
+function filterConnectContent (contentAggregate) {
+  const report = { kept: 0, outsideGenerated: 0, providedElsewhere: 0, otherComponents: 0 }
+  const fromConnect = (f) => isConnectOrigin(f.src && f.src.origin)
+  for (const bucket of contentAggregate) {
+    const files = bucket.files || []
+    if (!files.some(fromConnect)) continue
+    if (bucket.name !== COMPONENT) {
+      // Older connect tags name the component redpanda-connect and ship full
+      // pages. None of it belongs on the site.
+      report.otherComponents += files.filter(fromConnect).length
+      bucket.files = files.filter((f) => !fromConnect(f))
+      continue
+    }
+    const provided = new Set(files.filter((f) => !fromConnect(f)).map((f) => f.path))
+    bucket.files = files.filter((f) => {
+      if (!fromConnect(f)) return true
+      if (!KEPT_PATHS.some((p) => f.path.startsWith(p))) {
+        report.outsideGenerated++
+        return false
+      }
+      if (provided.has(f.path)) {
+        report.providedElsewhere++
+        return false
+      }
+      report.kept++
+      return true
+    })
+  }
+  // A bucket left with no files (an older connect tag's own component) would
+  // still register an empty component.
+  for (let i = contentAggregate.length - 1; i >= 0; i--) {
+    const b = contentAggregate[i]
+    if (!(b.files || []).length && (b.origins || []).every(isConnectOrigin)) contentAggregate.splice(i, 1)
+  }
+  return report
+}
 
-module.exports.register = function ({ config }) {
+module.exports.register = function () {
   raiseListenerLimit(this)
-  const logger = this.getLogger('modify-connect-tag-playbook-extension');
+  const logger = this.getLogger('modify-connect-tag-playbook-extension')
 
   this.on('contextStarted', async ({ playbook }) => {
+    const sources = (playbook && playbook.content && playbook.content.sources) || []
+    // Clear a ref left over from an earlier build in the same process.
+    setResolvedConnectRef(null)
+    const source = sources.find(wantsLatest)
+    if (!source) return
+    let tag = null
     try {
-      // Fetch the latest release tag for redpanda-data/connect
-      const sourceUrl = 'https://github.com/redpanda-data/connect';
-      if (playbook && playbook.content && playbook.content.sources) {
-        const source = playbook.content.sources.find(source => source.url === sourceUrl);
-        if (source) {
-          const latestTag = await GetLatestConnectTag();
-          if (latestTag) {
-            source.tags[0] = `v${latestTag}`;
-            this.updateVariables({ playbook });
-          }
-        }
-      }
+      const { Octokit } = await import('@octokit/rest')
+      const { retry } = await import('@octokit/plugin-retry')
+      const token = getGitHubApiToken()
+      const github = new (Octokit.plugin(retry))({ userAgent: 'Redpanda Docs', auth: token || undefined, retry: { doNotRetry: [403, 404, 429] } })
+      tag = toTag(await getLatestConnectTag(github, OWNER, REPO, logger))
     } catch (error) {
-      logger.error('Failed to update playbook with the latest Redpanda Connect tag:', error);
+      logger.warn(`GitHub API lookup of the latest Redpanda Connect release failed: ${error.message}`)
+    }
+    if (!tag) {
+      try {
+        tag = latestTagFromGit(source.url)
+        if (tag) logger.info(`Resolved the latest Redpanda Connect release from git tags: ${tag}`)
+      } catch (error) {
+        logger.warn(redact(`git ls-remote of ${source.url} failed: ${error.message}`))
+      }
     }
-  });
+    if (!tag) {
+      // Guessing would let Antora's default branch patterns pull in connect's
+      // branches, whose docs are unreleased or missing, so stop the build.
+      throw new Error('Could not resolve the latest Redpanda Connect release tag for the connect content source. Set a GitHub token or check network access.')
+    }
+    pinConnectSource(playbook, tag)
+    setResolvedConnectRef(tag)
+    this.updateVariables({ playbook })
+    logger.info(`Sourcing Redpanda Connect reference content from ${tag}`)
+  })
+
+  this.on('contentAggregated', ({ contentAggregate }) => {
+    const r = filterConnectContent(contentAggregate)
+    if (r.kept + r.outsideGenerated + r.providedElsewhere + r.otherComponents === 0) return
+    logger.info(
+      `Redpanda Connect content: kept ${r.kept} generated files; skipped ${r.providedElsewhere} already provided by another source, ` +
+      `${r.outsideGenerated} outside the generated partials and examples, and ${r.otherComponents} from other components`
+    )
+  })
 }
+
+module.exports._internal = { isRemote, isUpstreamConnect, redact, isConnectSource, isConnectOrigin, toTag, highestStableTag, wantsLatest, pinConnectSource, filterConnectContent }

package/extensions/util/connect-catalog.js

@@ -0,0 +1,153 @@
+'use strict'
+
+// Shared Redpanda Connect catalog helpers.
+//
+// The connect repo publishes its reference content (partials and examples)
+// through a content source that modify-connect-tag-playbook pins to the latest
+// release tag. Catalog data (support level, deprecation, Cloud availability)
+// must come from the same ref, or the badges and catalog drift from the
+// reference content as soon as connect's main branch changes a flag before a
+// release. This module carries that ref between the extensions and turns the
+// generated partials/platforms/catalog.json into rows shaped like the
+// translated info.csv rows the macros already consume.
+
+// Matches the GitHub URL (with or without .git) and a local clone whose
+// directory is named connect, which is how the source looks in local builds.
+function isConnectSource (url) {
+  return typeof url === 'string' && /(^|[/:])(redpanda-data\/)?connect(\.git)?\/?$/.test(url)
+}
+
+function isConnectOrigin (origin) {
+  return !!origin && (isConnectSource(origin.url) || isConnectSource(origin.worktree))
+}
+
+// The connect ref that modify-connect-tag-playbook resolved for this build.
+// Module state, because both extensions run in the same Antora process and
+// Antora gives extensions no other channel that survives from contextStarted
+// to contentClassified without mutating the playbook.
+let resolvedConnectRef = null
+
+function setResolvedConnectRef (ref) {
+  resolvedConnectRef = ref || null
+}
+
+function getResolvedConnectRef () {
+  return resolvedConnectRef
+}
+
+// The GitHub owner and repo of a connect origin URL, so a playbook that
+// previews a fork reads that fork's info.csv. Null for non-GitHub URLs.
+function githubRepoOf (url) {
+  const m = String(url || '').match(/github\.com[/:]([^/]+)\/([^/]+?)(\.git)?\/?$/)
+  return m ? { owner: m[1], repo: m[2] } : null
+}
+
+// The ref of the connect content source as Antora aggregated it. Only refs
+// that exist on the remote count: a tag, or a branch fetched from the remote.
+// A branch of a local clone may exist only on disk, so it is not used.
+function connectOriginRef (contentCatalog) {
+  if (!contentCatalog || typeof contentCatalog.findBy !== 'function') return null
+  for (const file of contentCatalog.findBy({ component: 'connect' })) {
+    const origin = file.src && file.src.origin
+    if (!isConnectOrigin(origin)) continue
+    const repo = githubRepoOf(origin.url)
+    if (origin.tag || origin.reftype === 'tag') {
+      return { ref: origin.tag || origin.refname, ...(repo || {}) }
+    }
+    if (!origin.worktree && (origin.branch || origin.refname)) {
+      return { ref: origin.branch || origin.refname, ...(repo || {}) }
+    }
+  }
+  return null
+}
+
+const CATALOG_RELATIVE = 'platforms/catalog.json'
+
+// The generated catalog.json in the content catalog, preferring the copy
+// from the connect content source over one another source provides.
+function findConnectCatalogFile (contentCatalog) {
+  if (!contentCatalog || typeof contentCatalog.findBy !== 'function') return null
+  const candidates = contentCatalog
+    .findBy({ component: 'connect', module: 'components', family: 'partial' })
+    .filter((f) => f.src && f.src.relative === CATALOG_RELATIVE)
+  return candidates.find((f) => isConnectOrigin(f.src.origin)) || candidates[0] || null
+}
+
+// Page directories and data rows name some types differently: pages live in
+// metrics/ and rate_limits/, while info.csv and the schema say metric and
+// rate_limit. Normalize to the singular data form for lookups.
+function normalizeType (type) {
+  const t = String(type || '').trim().toLowerCase().replace(/-/g, '_')
+  return t.endsWith('s') ? t.slice(0, -1) : t
+}
+
+const PAGE_TYPE_DIRS = ['inputs', 'outputs', 'processors', 'caches', 'rate_limits', 'buffers', 'metrics', 'tracers', 'scanners']
+
+// The component type of a connector page from its path, for example
+// inputs/kafka.adoc -> input. Null for pages outside the type directories.
+function typeFromRelative (relative) {
+  const m = String(relative || '').match(/(?:^|\/)([a-z_]+)\/[^/]+\.adoc$/)
+  return m && PAGE_TYPE_DIRS.includes(m[1]) ? normalizeType(m[1]) : null
+}
+
+const yn = (value) => (value === true || String(value || '').trim().toLowerCase() === 'y' ? 'y' : 'n')
+
+// Converts catalog.json entries into rows with the raw info.csv column names,
+// so they go through the same translation as rows parsed from info.csv. The
+// catalog adds status, categories, cgo_only, and the full commercial name list.
+function catalogEntriesToCsvRows (entries) {
+  if (!Array.isArray(entries)) throw new Error('catalog.json is not a JSON array')
+  return entries
+    .filter((e) => e && e.name && e.type)
+    .map((e) => {
+      const commercialNames = Array.isArray(e.commercial_names) ? e.commercial_names.filter(Boolean) : []
+      const status = String(e.status || '').trim().toLowerCase()
+      return {
+        name: e.name,
+        type: e.type,
+        commercial_name: commercialNames[0] || e.name,
+        commercial_names: commercialNames,
+        support: e.support || '',
+        deprecated: status === 'deprecated' ? 'y' : 'n',
+        cloud: yn(e.cloud),
+        cloud_with_gpu: yn(e.cloud_ai),
+        status,
+        version: e.version || '',
+        categories: Array.isArray(e.categories) ? e.categories : [],
+        cgo_only: yn(e.cgo_only),
+        summary: e.summary || ''
+      }
+    })
+}
+
+// Cloud availability of a translated row. Cloud has two pipeline flavors:
+// standard (info.csv `cloud`) and GPU (info.csv `cloud_with_gpu`, catalog
+// `cloud_ai`). A component in either one has a Cloud page.
+function isCloudAvailable (row) {
+  return !!row && (row.is_cloud_supported === 'y' || row.cloud_ai === 'y')
+}
+
+// gpu_only: only in GPU pipelines (for example the ollama processors).
+// no_gpu: in standard pipelines but not in GPU pipelines (for example jira).
+function gpuFlags (cloud, cloudAi) {
+  return {
+    gpu_only: cloud !== 'y' && cloudAi === 'y' ? 'y' : 'n',
+    no_gpu: cloud === 'y' && cloudAi !== 'y' ? 'y' : 'n'
+  }
+}
+
+module.exports = {
+  CATALOG_RELATIVE,
+  isConnectSource,
+  isConnectOrigin,
+  setResolvedConnectRef,
+  getResolvedConnectRef,
+  githubRepoOf,
+  connectOriginRef,
+  findConnectCatalogFile,
+  normalizeType,
+  typeFromRelative,
+  catalogEntriesToCsvRows,
+  isCloudAvailable,
+  gpuFlags
+}

package/macros/rp-connect-components.js

@@ -1,6 +1,7 @@
 'use strict';
 const { posix: path } = require('path')
 const logger = require('@antora/logger')('rp-connect-components-macro')
+const { isCloudAvailable, typeFromRelative } = require('../extensions/util/connect-catalog')
 
 /**
  * Registers macros for use in Redpanda Connect contexts in the Redpanda documentation.
@@ -220,8 +221,9 @@ module.exports.register = function (registry, context) {
    */
   function processConnectors(parsedData) {
     return parsedData.data.reduce((connectors, row) => {
-      const { connector, commercial_name, type, support_level, is_cloud_supported, is_licensed, redpandaConnectUrl, redpandaCloudUrl } = row;
-      const isCloudSupported = is_cloud_supported === 'y';
+      const { connector, commercial_name, type, support_level, is_licensed, redpandaConnectUrl, redpandaCloudUrl } = row;
+      // Available in standard or GPU Cloud pipelines
+      const isCloudSupported = isCloudAvailable(row);
 
       // Initialize the connector if it's not already in the map
       if (!connectors[connector]) {
@@ -245,7 +247,9 @@ module.exports.register = function (registry, context) {
             redpandaCloudUrl: redpandaCloudUrl || ''
           },
           supportLevel: support_level,
-          isCloudSupported: isCloudSupported
+          isCloudSupported: isCloudSupported,
+          gpuOnly: row.gpu_only === 'y',
+          noGpu: row.no_gpu === 'y'
         };
       }
 
@@ -301,8 +305,8 @@ module.exports.register = function (registry, context) {
     };
 
     parsedData.data.forEach(row => {
-      const { connector: driverName, commercial_name, support_level, is_cloud_supported } = row;
-      const isCloudSupported = is_cloud_supported === 'y';
+      const { connector: driverName, commercial_name, support_level } = row;
+      const isCloudSupported = isCloudAvailable(row);
       const supportLevel = support_level.toLowerCase();
 
       // Only process SQL drivers
@@ -463,10 +467,20 @@ module.exports.register = function (registry, context) {
         const firstCloudSupportedType = Array.from(types.entries())
           .map(([_, commercialNames]) => Object.values(commercialNames).find(({ isCloudSupported }) => isCloudSupported))
           .find(entry => entry);
+        // Say which Cloud pipelines when every Cloud-available type agrees:
+        // the ollama processors run only in GPU pipelines, and jira only outside them.
+        const cloudEntries = Array.from(types.values())
+          .flatMap(commercialNames => Object.values(commercialNames))
+          .filter(({ isCloudSupported }) => isCloudSupported);
+        const pipelineNote = cloudEntries.length && cloudEntries.every(e => e.gpuOnly)
+          ? ' (GPU pipelines only)'
+          : cloudEntries.length && cloudEntries.every(e => e.noGpu)
+            ? ' (not in GPU pipelines)'
+            : '';
         const cloudLinkDisplay = firstCloudSupportedType
           ? firstCloudSupportedType.urls.redpandaCloudUrl
-            ? `<a href="${firstCloudSupportedType.urls.redpandaCloudUrl}">Yes</a>`
-          : `Yes`
+            ? `<a href="${firstCloudSupportedType.urls.redpandaCloudUrl}">Yes</a>${pipelineNote}`
+          : `Yes${pipelineNote}`
         : 'No';
 
         const firstUrl = getFirstUrlFromTypesArray(Array.from(types.entries()), isCloud);
@@ -1018,7 +1032,8 @@ module.exports.register = function (registry, context) {
       const attributes = parent.getDocument().getAttributes();
       const component = attributes['page-component-title'];  // Current component (for example, 'Redpanda Cloud' or 'Redpanda Connect')
       const name = attributes['doctitle'];
-      const type = attributes['type'];
+      // Drafted pages no longer freeze :type:, so fall back to the page's directory.
+      const type = attributes['type'] || typeFromRelative(attributes['page-relative-src-path']);
       if (!name || !type) {
         return self.createBlock(parent, 'pass', '');
       }

package/package.json

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

package/tools/lint-strings/diff.js

@@ -33,7 +33,10 @@ 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\// },
+  // Redpanda Connect publishes strings from component packages, the helper
+  // packages they share (internal/httpclient, internal/retries, ...), the
+  // public schema and the `rpk connect` CLI, plus config templates.
+  { surface: 'connect', pattern: /^(?:internal|public|cmd)\/(?!(?:.*\/)?testdata\/)(?:.*(?<!_test)\.go|.*\.tmpl\.ya?ml)$/ },
   // 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/.

package/tools/lint-strings/engine.js

@@ -36,6 +36,7 @@ const SEVERITIES = ['error', 'warning', 'info']
  *   - runOnUnverifiable: also run when decl.meta.unverifiable is set
  *     (all other rules are skipped for unverifiable declarations, so a
  *     non-literal source string can never produce an error)
+ *   A declaration skips any rule named in decl.meta.skip_rules.
  * @param {Object} options - { skipRules: [names], onlyRules: [names] }
  * @returns {Object} { findings, summary: { byRule, bySurface } }
  */
@@ -55,6 +56,10 @@ function runRules (declarations, rules, options = {}) {
       // Unverifiable declarations (for example, a metric description built
       // with fmt::format) only run rules that opt in; they must never error.
       if (decl.meta && decl.meta.unverifiable && !rule.runOnUnverifiable) continue
+      // A surface can opt one declaration out of a rule whose premise does
+      // not hold for it (connect's CLI help is not AsciiDoc, though the
+      // rest of the surface is).
+      if (decl.meta && Array.isArray(decl.meta.skip_rules) && decl.meta.skip_rules.includes(rule.name)) continue
 
       try {
         for (const issue of rule.check(decl) || []) {

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

@@ -53,7 +53,7 @@ func fixtureConfigFields() []*service.ConfigField {
 			Description("Poll interval."),
 		// Deprecated fields are exempt from the missing-description rule.
 		service.NewStringField("old_token").Deprecated().Default(""),
-		// Dynamic description: skipped silently, never guessed at.
+		// Dynamic description: reported with a placeholder, never guessed at.
 		service.NewStringField("dynamic_field").
 			Description(dynamicDescription()),
 	}

package/tools/lint-strings/fixtures/connect/repo/go.mod.txt

@@ -0,0 +1,5 @@
+module github.com/redpanda-data/connect/v4
+
+go 1.22
+
+require github.com/redpanda-data/benthos/v4 v4.81.0

package/tools/lint-strings/fixtures/connect/repo/internal/cli/lint.go

@@ -0,0 +1,19 @@
+package cli
+
+import "github.com/urfave/cli/v2"
+
+var lintCommand = &cli.Command{
+	Name:        "lint",
+	Usage:       "Parse configs and report any linting errors",
+	Description: "Exits with a status code 1 if any linting errors are detected.",
+	Flags: []cli.Flag{
+		&cli.BoolFlag{
+			Name:  "deprecated",
+			Usage: "Print linting errors for the presence of deprecated fields.",
+		},
+		&cli.StringFlag{
+			Name:  "format",
+			Usage: "Output format",
+		},
+	},
+}

package/tools/lint-strings/fixtures/connect/repo/internal/impl/azure/common.go

@@ -0,0 +1,20 @@
+// Package azure is a lint-strings fixture mirroring connect's Azure package:
+// specs start from a helper constructor and share parameterized fields.
+package azure
+
+import "github.com/redpanda-data/benthos/v4/public/service"
+
+const azureFieldAccount = "storage_account"
+
+// azureComponentSpec builds the spec every Azure component starts from.
+func azureComponentSpec() *service.ConfigSpec {
+	return service.NewConfigSpec().
+		Categories("Services", "Azure")
+}
+
+// accountField is called once per component, with a different product.
+func accountField(product string) *service.ConfigField {
+	return service.NewStringField(azureFieldAccount).
+		Description("The storage account to access for " + product + ".").
+		ShortDescription("The `storage account` to access.")
+}

package/tools/lint-strings/fixtures/connect/repo/internal/impl/azure/docs.go

@@ -0,0 +1,8 @@
+package azure
+
+// A constant and a helper in another file of the package.
+const thingProduct = "Azure Thing Storage"
+
+func thingDescription() string {
+	return "Reads every thing in a container. See xref:components:outputs/azure_thing.adoc[the output] and xref:outputs/azure_thing.adoc[the output again]."
+}

package/tools/lint-strings/fixtures/connect/repo/internal/impl/azure/input_thing.go

@@ -0,0 +1,32 @@
+package azure
+
+import (
+	"github.com/redpanda-data/benthos/v4/public/service"
+
+	"github.com/redpanda-data/connect/v4/internal/retries"
+)
+
+func thingInputSpec() *service.ConfigSpec {
+	spec := azureComponentSpec().
+		Summary("Reads things from " + thingProduct + ".").
+		Description(thingDescription()).
+		Footnotes("== Throughput\n\nThe input reads one page of things per request.").
+		Example("Read every thing", "Reads each thing once and stops.", `input: {}`).
+
+		// A blank line and a comment inside the chain do not end it.
+		Field(accountField("Azure Thing input")).
+		Fields(retries.CommonRetryBackOffFields(3, "1s", "5s", "30s")...)
+	spec = spec.Field(service.NewStringAnnotatedEnumField("mode", map[string]string{
+		"once":   "Reads each thing once.",
+		"follow": "Keeps reading new things as they arrive.",
+	}))
+	// Documented by reassignment: not a missing description.
+	f := service.NewStringField("prefix")
+	f = f.Description("Only things whose name starts with this prefix are read.")
+	spec = spec.Field(f)
+	return spec
+}
+
+func init() {
+	service.MustRegisterInput("azure_thing", thingInputSpec(), nil)
+}

package/tools/lint-strings/fixtures/connect/repo/internal/impl/azure/output_thing.go

@@ -0,0 +1,12 @@
+package azure
+
+import "github.com/redpanda-data/benthos/v4/public/service"
+
+func init() {
+	conf := azureComponentSpec().
+		Summary("Writes things to " + thingProduct + ".")
+	conf = conf.Field(accountField("Azure Thing output"))
+	// A field added in place, without reassignment.
+	conf.Field(service.NewStringField("container").Description("The container to write things to."))
+	service.MustRegisterOutput("azure_thing", conf, nil)
+}

package/tools/lint-strings/fixtures/connect/repo/internal/impl/widget/bloblang.go

@@ -0,0 +1,21 @@
+package widget
+
+import "github.com/redpanda-data/benthos/v4/public/bloblang"
+
+func init() {
+	spec := bloblang.NewPluginSpec().
+		Category("Encoding").
+		Description("Encodes a widget as a string.").
+		Param(bloblang.NewStringParam("format").Description("The format to encode the widget in.")).
+		Example("Encode a widget as JSON.", `root = this.encode_widget("json")`, [2]string{`{}`, `"{}"`})
+	bloblang.MustRegisterMethodV2("encode_widget", spec, nil)
+}
+
+type note struct{}
+
+// Description on a type that is not a benthos spec.
+func (n note) Description(s string) note { return n }
+
+func init() {
+	_ = note{}.Description("Not a published string.")
+}

package/tools/lint-strings/fixtures/connect/repo/internal/impl/widget/scanner.go

@@ -0,0 +1,12 @@
+package widget
+
+import "github.com/redpanda-data/benthos/v4/public/service"
+
+func linesScannerSpec() *service.ConfigSpec {
+	return service.NewConfigSpec().
+		Summary("Splits a widget stream into lines.")
+}
+
+func init() {
+	service.MustRegisterBatchScannerCreator("widget_lines", linesScannerSpec(), nil)
+}

package/tools/lint-strings/fixtures/connect/repo/internal/plugins/info.csv

@@ -0,0 +1,3 @@
+name           ,type      ,commercial_name ,support    ,deprecated ,cloud ,cloud_with_gpu ,cloud_unsupported_reason
+azure_thing    ,input     ,Azure Thing     ,certified  ,n          ,y     ,n              ,
+azure_thing    ,output    ,Azure Thing     ,community  ,n          ,n     ,n              ,needs local disk

package/tools/lint-strings/fixtures/connect/repo/internal/retries/retries.go

@@ -0,0 +1,13 @@
+// Package retries is a helper package outside internal/impl whose fields
+// appear on every component that calls it.
+package retries
+
+import "github.com/redpanda-data/benthos/v4/public/service"
+
+// CommonRetryBackOffFields returns the common retry fields.
+func CommonRetryBackOffFields(defaultMaxRetries int, initial, maxInterval, maxElapsed string) []*service.ConfigField {
+	return []*service.ConfigField{
+		service.NewIntField("max_retries").
+			Description("The maximum number of retries before giving up on the request."),
+	}
+}