Docs(feat[autodoc]): Implement sidecar introspection schema

tony · tony · commit 93922a1dd864 · 2026-01-04T13:00:58.000-06:00
why: Provide real runtime introspection data for API docs and docstring rendering.
what:
- add sidecar introspection helpers with signatures, members, and docstring HTML
- expand introspection schema and wire annotation format options
- update sidecar CLI and schema tests; add docutils dependency
diff --git a/astro/packages/py-introspect/src/index.ts b/astro/packages/py-introspect/src/index.ts
@@ -6,6 +6,7 @@ import { type PyIntrospectPayload, PyIntrospectPayloadSchema } from '@libtmux/sc
 export type IntrospectOptions = {
   root?: string
   includePrivate?: boolean
+  annotationFormat?: 'string' | 'value'
   pythonCommand?: PythonCommand
   env?: NodeJS.ProcessEnv
   cwd?: string
@@ -37,6 +38,10 @@ export const introspectModule = async (
     args.push('--include-private')
   }
 
+  if (options.annotationFormat) {
+    args.push('--annotation-format', options.annotationFormat)
+  }
+
   const payload = await runPythonJson(args, {
     pythonCommand: options.pythonCommand,
     cwd: options.cwd ?? sidecarRoot,
@@ -62,6 +67,10 @@ export const introspectPackage = async (
     args.push('--include-private')
   }
 
+  if (options.annotationFormat) {
+    args.push('--annotation-format', options.annotationFormat)
+  }
+
   const payload = await runPythonJson(args, {
     pythonCommand: options.pythonCommand,
     cwd: options.cwd ?? sidecarRoot,
diff --git a/astro/packages/schema/src/py-introspect.ts b/astro/packages/schema/src/py-introspect.ts
@@ -1,12 +1,88 @@
 import { z } from 'zod'
 import { ProtocolVersionSchema } from './common.ts'
+import { PyParameterKindSchema } from './py-parse.ts'
 
-export const PyIntrospectModuleSchema = z.object({}).passthrough()
+const DocstringFormatSchema = z.enum(['rst', 'markdown', 'plain', 'unknown'])
+
+const DocstringFieldsSchema = z.object({
+  docstringRaw: z.string().nullable(),
+  docstringFormat: DocstringFormatSchema,
+  docstringHtml: z.string().nullable(),
+  summary: z.string().nullable(),
+})
+
+const AnnotationFieldsSchema = z.object({
+  annotationText: z.string().nullable(),
+  annotationValue: z.string().nullable(),
+})
+
+export const PyIntrospectParameterSchema = z
+  .object({
+    name: z.string(),
+    kind: PyParameterKindSchema,
+    default: z.string().nullable(),
+  })
+  .merge(AnnotationFieldsSchema)
+
+export const PyIntrospectFunctionSchema = z
+  .object({
+    kind: z.enum(['function', 'method']),
+    name: z.string(),
+    qualname: z.string(),
+    module: z.string(),
+    signature: z.string(),
+    parameters: z.array(PyIntrospectParameterSchema),
+    returns: AnnotationFieldsSchema,
+    isAsync: z.boolean(),
+    isPrivate: z.boolean(),
+  })
+  .merge(DocstringFieldsSchema)
+
+export const PyIntrospectVariableSchema = z
+  .object({
+    kind: z.literal('variable'),
+    name: z.string(),
+    qualname: z.string(),
+    module: z.string(),
+    value: z.string().nullable(),
+    isPrivate: z.boolean(),
+  })
+  .merge(AnnotationFieldsSchema)
+  .merge(DocstringFieldsSchema)
+
+export const PyIntrospectClassSchema = z
+  .object({
+    kind: z.literal('class'),
+    name: z.string(),
+    qualname: z.string(),
+    module: z.string(),
+    bases: z.array(z.string()),
+    methods: z.array(PyIntrospectFunctionSchema),
+    attributes: z.array(PyIntrospectVariableSchema),
+    isPrivate: z.boolean(),
+  })
+  .merge(DocstringFieldsSchema)
+
+export const PyIntrospectModuleSchema = z
+  .object({
+    kind: z.literal('module'),
+    name: z.string(),
+    qualname: z.string(),
+    classes: z.array(PyIntrospectClassSchema),
+    functions: z.array(PyIntrospectFunctionSchema),
+    variables: z.array(PyIntrospectVariableSchema),
+    isPrivate: z.boolean(),
+  })
+  .merge(DocstringFieldsSchema)
 
 export const PyIntrospectPayloadSchema = z.object({
   protocolVersion: ProtocolVersionSchema,
   modules: z.array(PyIntrospectModuleSchema),
 })
 
+export type PyIntrospectParameter = z.infer<typeof PyIntrospectParameterSchema>
+export type PyIntrospectFunction = z.infer<typeof PyIntrospectFunctionSchema>
+export type PyIntrospectVariable = z.infer<typeof PyIntrospectVariableSchema>
+export type PyIntrospectClass = z.infer<typeof PyIntrospectClassSchema>
 export type PyIntrospectModule = z.infer<typeof PyIntrospectModuleSchema>
 export type PyIntrospectPayload = z.infer<typeof PyIntrospectPayloadSchema>
diff --git a/astro/packages/schema/tests/py-introspect.test.ts b/astro/packages/schema/tests/py-introspect.test.ts
@@ -10,4 +10,27 @@ describe('PyIntrospectPayloadSchema', () => {
 
     expect(() => PyIntrospectPayloadSchema.parse(payload)).not.toThrow()
   })
+
+  it('accepts a minimal module payload', () => {
+    const payload = {
+      protocolVersion: 1,
+      modules: [
+        {
+          kind: 'module',
+          name: 'demo',
+          qualname: 'demo',
+          isPrivate: false,
+          classes: [],
+          functions: [],
+          variables: [],
+          docstringRaw: null,
+          docstringFormat: 'unknown',
+          docstringHtml: null,
+          summary: null,
+        },
+      ],
+    }
+
+    expect(() => PyIntrospectPayloadSchema.parse(payload)).not.toThrow()
+  })
 })
diff --git a/astro/python/pyautodoc_sidecar/pyproject.toml b/astro/python/pyautodoc_sidecar/pyproject.toml
@@ -3,7 +3,9 @@ name = "pyautodoc-sidecar"
 version = "0.0.1"
 description = "Python sidecar for the libtmux autodoc pipeline."
 requires-python = ">=3.10"
-dependencies = []
+dependencies = [
+  "docutils",
+]
 
 [build-system]
 requires = ["hatchling"]
diff --git a/astro/python/pyautodoc_sidecar/src/pyautodoc_sidecar/cli.py b/astro/python/pyautodoc_sidecar/src/pyautodoc_sidecar/cli.py
@@ -7,6 +7,7 @@
 import pathlib
 import typing as t
 
+from pyautodoc_sidecar.introspect import introspect_module, introspect_package
 from pyautodoc_sidecar.parse import scan_paths
 
 PROTOCOL_VERSION = 1
@@ -60,13 +61,23 @@ def main(argv: list[str] | None = None) -> int:
     intro_module.add_argument("--module", required=True)
     intro_module.add_argument("--root")
     intro_module.add_argument("--include-private", action="store_true")
+    intro_module.add_argument(
+        "--annotation-format",
+        choices=["string", "value"],
+        default="string",
+    )
 
     intro_package = subparsers.add_parser(
         "introspect-package", help="Introspect a package."
     )
     intro_package.add_argument("--package", required=True)
     intro_package.add_argument("--root")
     intro_package.add_argument("--include-private", action="store_true")
+    intro_package.add_argument(
+        "--annotation-format",
+        choices=["string", "value"],
+        default="string",
+    )
 
     args = parser.parse_args(argv)
     payload: dict[str, t.Any]
@@ -76,8 +87,26 @@ def main(argv: list[str] | None = None) -> int:
         paths = [pathlib.Path(item) for item in args.paths]
         modules = scan_paths(root, paths, args.include_private)
         payload = {"protocolVersion": PROTOCOL_VERSION, "modules": modules}
-    elif args.command in {"introspect-module", "introspect-package"}:
-        payload = {"protocolVersion": PROTOCOL_VERSION, "modules": []}
+    elif args.command == "introspect-module":
+        root = pathlib.Path(args.root) if args.root else None
+        modules = [
+            introspect_module(
+                args.module,
+                root=root,
+                include_private=args.include_private,
+                annotation_format=args.annotation_format,
+            )
+        ]
+        payload = {"protocolVersion": PROTOCOL_VERSION, "modules": modules}
+    elif args.command == "introspect-package":
+        root = pathlib.Path(args.root) if args.root else None
+        modules = introspect_package(
+            args.package,
+            root=root,
+            include_private=args.include_private,
+            annotation_format=args.annotation_format,
+        )
+        payload = {"protocolVersion": PROTOCOL_VERSION, "modules": modules}
     else:
         raise ValueError(f"Unsupported command: {args.command}")
 
diff --git a/astro/python/pyautodoc_sidecar/src/pyautodoc_sidecar/introspect.py b/astro/python/pyautodoc_sidecar/src/pyautodoc_sidecar/introspect.py
