fix(docs): isolate command inventory helpers

package.json

@@ -92,8 +92,8 @@
     "check:hooks": "node scripts/fleet/check.mts --category=hooks",
     "check:native-package": "node scripts/repo/build/sea/check.mts",
     "check:paths": "node scripts/fleet/check/paths-are-valid.mts",
-    "docs:commands:check": "node scripts/repo/check/docs-commands.mts",
-    "docs:commands:test": "node scripts/fleet/test.mts test/repo/unit/check/docs-command-inventory.test.mts test/repo/unit/check/docs-commands.test.mts",
+    "docs:commands:check": "node scripts/repo/check/docs-commands-are-complete.mts",
+    "docs:commands:test": "node scripts/fleet/test.mts test/repo/unit/docs/commands/inventory.test.mts test/repo/unit/check/docs-commands-are-complete.test.mts",
     "check:test": "node scripts/fleet/commands/run.mts check test",
     "check:test-budget-headroom": "node scripts/fleet/check/test-budget-headroom.mts",
     "check:types": "node scripts/fleet/check.mts --category=types",

scripts/repo/check/docs-commands.mts → scripts/repo/check/docs-commands-are-complete.mts

@@ -6,17 +6,18 @@ import { fromMarkdown } from 'mdast-util-from-markdown'
 import { gfmFromMarkdown } from 'mdast-util-gfm'
 import { gfm } from 'micromark-extension-gfm'
 
-import { extractCommandInventory } from './docs-command-inventory.mts'
+import { extractCommandInventory } from '../docs/commands/inventory.mts'
 import { REPO_ROOT } from '../../fleet/paths.mts'
 import { isMainModule } from '../../fleet/process/is-main-module.mts'
 import { runMain } from '../../fleet/process/main/run.mts'
 
-import type { CommandInventory } from './docs-command-inventory.mts'
+import type { CommandInventory } from '../docs/commands/inventory.mts'
 import type { ScriptMeta } from '../../fleet/process/main/run.mts'
 
 export const SCRIPT_META: ScriptMeta = {
   describe: 'Check the exact CLI command and alias inventory in its reference.',
   help: 'Usage: pnpm run docs:commands:check',
+  json: 'result',
 }
 
 interface MarkdownNode {
@@ -54,14 +55,14 @@ function textContent(node: MarkdownNode): string {
 }
 
 function inlineCode(node: MarkdownNode | undefined): string | undefined {
-  if (
-    node?.type === 'tableCell' &&
-    nodeChildren(node).length === 1 &&
-    nodeChildren(node)[0]?.type === 'inlineCode'
-  ) {
-    return textContent(nodeChildren(node)[0])
+  if (node?.type !== 'tableCell') {
+    return undefined
   }
-  return undefined
+  const children = nodeChildren(node)
+  const child = children[0]
+  return children.length === 1 && child?.type === 'inlineCode'
+    ? textContent(child)
+    : undefined
 }
 
 function linkTarget(node: MarkdownNode | undefined): string | undefined {
@@ -118,6 +119,8 @@ function sectionRows(
   const headerCells = header.children
   if (
     headerCells.length !== 2 ||
+    headerCells[0] === undefined ||
+    headerCells[1] === undefined ||
     textContent(headerCells[0]) !== headers[0] ||
     textContent(headerCells[1]) !== headers[1]
   ) {
@@ -153,7 +156,7 @@ function uniqueRows(
     }
     result.set(row.name, row)
   }
-  return { __proto__: null, rows: result, problems }
+  return { rows: result, problems }
 }
 
 function validGuide(

scripts/repo/check/docs-command-custom-routes.mts → scripts/repo/docs/commands/custom-routes.mts

@@ -5,13 +5,9 @@ import {
   parseModule,
   stringLiteral,
   visitAst,
-} from './docs-command-inventory-lib.mts'
+} from './util.mts'
 
-import type {
-  AstNode,
-  ParsedModule,
-  SourceReader,
-} from './docs-command-inventory-lib.mts'
+import type { AstNode, ParsedModule, SourceReader } from './util.mts'
 
 export type CustomRouteKind = 'patch' | 'sfw'
 
@@ -256,7 +252,11 @@ function firewallCaModes(sourceReader: SourceReader): string[] {
     ) {
       return
     }
-    if (!isPositionalsFirstFallback(node.arguments[0])) {
+    const argumentsList = node['arguments']
+    if (
+      !Array.isArray(argumentsList) ||
+      !isPositionalsFirstFallback(argumentsList[0])
+    ) {
       return
     }
     allowlistValidated = true

scripts/repo/check/docs-command-inventory.mts → scripts/repo/docs/commands/inventory.mts

@@ -5,18 +5,13 @@ import {
   objectProperties,
   parseModule,
   sourceError,
-  staticPropertyKey,
   stringLiteral,
-} from './docs-command-inventory-lib.mts'
-import { extractCustomRoutes } from './docs-command-custom-routes.mts'
+} from './util.mts'
+import { extractCustomRoutes } from './custom-routes.mts'
 
-import type { CustomRouteKind } from './docs-command-custom-routes.mts'
+import type { CustomRouteKind } from './custom-routes.mts'
 
-import type {
-  AstNode,
-  ParsedModule,
-  SourceReader,
-} from './docs-command-inventory-lib.mts'
+import type { AstNode, ParsedModule, SourceReader } from './util.mts'
 
 export interface CommandAlias {
   alias: string
@@ -187,8 +182,9 @@ function subcommandConfig(
     }
   }
   findCalls(body)
-  if (calls.length > 1) {
-    throw sourceError(module.path, calls[1], 'multiple subcommand routers')
+  const secondCall = calls[1]
+  if (secondCall !== undefined) {
+    throw sourceError(module.path, secondCall, 'multiple subcommand routers')
   }
   const call = calls[0]
   if (call === undefined) {

scripts/repo/check/docs-command-inventory-lib.mts → scripts/repo/docs/commands/util.mts

@@ -5,6 +5,33 @@ import { parseAst } from 'rolldown/parseAst'
 
 export interface AstNode extends Record<string, unknown> {
   type: string
+  arguments?: unknown | undefined
+  body?: unknown | undefined
+  callee?: unknown | undefined
+  computed?: unknown | undefined
+  consequent?: unknown | undefined
+  declaration?: unknown | undefined
+  declarations?: unknown | undefined
+  elements?: unknown | undefined
+  id?: unknown | undefined
+  imported?: unknown | undefined
+  init?: unknown | undefined
+  key?: unknown | undefined
+  kind?: unknown | undefined
+  left?: unknown | undefined
+  local?: unknown | undefined
+  loc?: unknown | undefined
+  name?: unknown | undefined
+  object?: unknown | undefined
+  operator?: unknown | undefined
+  properties?: unknown | undefined
+  property?: unknown | undefined
+  right?: unknown | undefined
+  source?: unknown | undefined
+  specifiers?: unknown | undefined
+  start?: unknown | undefined
+  test?: unknown | undefined
+  value?: unknown | undefined
 }
 
 export type SourceReader = (sourcePath: string) => string
@@ -20,7 +47,7 @@ export interface ParsedModule {
 export const isRecord = isPlainObject
 
 export function isNode(value: unknown): value is AstNode {
-  return isRecord(value) && typeof value.type === 'string'
+  return isRecord(value) && typeof value['type'] === 'string'
 }
 
 export function nodeArray(value: unknown, message: string): AstNode[] {
@@ -95,8 +122,10 @@ export function sourceError(
   reason: string,
 ): Error {
   const loc =
-    isRecord(node.loc) && isRecord(node.loc.start) ? node.loc.start : undefined
-  const line = loc && typeof loc.line === 'number' ? loc.line : 1
+    isRecord(node.loc) && isRecord(node.loc['start'])
+      ? node.loc['start']
+      : undefined
+  const line = loc && typeof loc['line'] === 'number' ? loc['line'] : 1
   return new Error(`${sourcePath}:${line}: ${reason}`)
 }
 
@@ -165,9 +194,9 @@ function annotateSourceLocations(root: AstNode, source: string): void {
   visitAst(root, node => {
     const loc = isRecord(node.loc) ? node.loc : undefined
     const start =
-      loc !== undefined && isRecord(loc.start) ? loc.start : undefined
+      loc !== undefined && isRecord(loc['start']) ? loc['start'] : undefined
     if (
-      (start !== undefined && typeof start.line === 'number') ||
+      (start !== undefined && typeof start['line'] === 'number') ||
       typeof node.start !== 'number'
     ) {
       return

test/integration/cli/cmd-config-auto.test.mts

@@ -59,6 +59,7 @@ describe('socket config auto', async () => {
                - apiToken -- The Socket API token required to access most Socket API endpoints
                - defaultOrg -- The default org slug to use; usually the org your Socket API token has access to. When set, all orgSlug arguments are implied to be this value.
                - enforcedOrgs -- Orgs in this list have their security policies enforced on this machine
+               - oauthSession -- The selected Socket OAuth issuer and client
                - org -- Alias for defaultOrg
                - skipAskToPersistDefaultOrg -- This flag prevents the Socket CLI from asking you to persist the org slug when you selected one interactively"
       `)

test/repo/unit/check/docs-commands.test.mts → test/repo/unit/check/docs-commands-are-complete.test.mts

@@ -1,6 +1,6 @@
 import { describe, expect, it } from 'vitest'
 
-import { checkCommandDocumentation } from '../../../../scripts/repo/check/docs-commands.mts'
+import { checkCommandDocumentation } from '../../../../scripts/repo/check/docs-commands-are-complete.mts'
 
 const inventory = {
   commands: ['alpha', 'alpha child', 'patch list'],

test/repo/unit/check/docs-command-inventory.test.mts → test/repo/unit/docs/commands/inventory.test.mts

@@ -1,8 +1,8 @@
 import { describe, expect, it } from 'vitest'
 
-import { extractCommandInventory } from '../../../../scripts/repo/check/docs-command-inventory.mts'
-import { extractCustomRoutes } from '../../../../scripts/repo/check/docs-command-custom-routes.mts'
-import { checkCommandDocumentation } from '../../../../scripts/repo/check/docs-commands.mts'
+import { extractCommandInventory } from '../../../../../scripts/repo/docs/commands/inventory.mts'
+import { extractCustomRoutes } from '../../../../../scripts/repo/docs/commands/custom-routes.mts'
+import { checkCommandDocumentation } from '../../../../../scripts/repo/check/docs-commands-are-complete.mts'
 
 function sourceReader(
   files: Record<string, string>,