#selfdoc.extractors.typescript

#selfdoc.extractors.typescript

TypeScript/JavaScript source extractor -- resolves directives by extracting from .ts/.js files.

Uses regex-based parsing (no external dependencies). Handles:

• :::module -- extract module-level JSDoc, exported functions/classes/interfaces/types
• :::test -- extract test blocks (describe/it/test) by name
• :::schema -- extract interface/type fields as table
• :::cli -- extract help/usage strings or module-level JSDoc
• :::config -- extract JSON/JSONC/TOML config files as tables

#TypeScriptExtractor

TypeScript/JavaScript language extractor implementing LanguageExtractor protocol.

#name

def name(self) -> str

#detect

def detect(self, dir_path: str) -> bool

#resolve_path

def resolve_path(self, path_arg: str, source_paths: list[str], base_dir: str) -> str | None

#extract

def extract(self, directive_name: str, attrs: dict[str, str], body: list[str], source_paths: list[str], base_dir: str) -> str

#file_extensions

def file_extensions(self) -> list[str]

#public_symbols

def public_symbols(self, file_path: str) -> list[str]

Extract exported symbols from a TypeScript/JavaScript file.

Skips lines inside // and / / comments.

#_resolve_file_path

def _resolve_file_path(arg, source_paths, base_dir)

Resolve a file path argument to an actual TS/JS file on disk.

Tries the arg as-is (relative to base_dir and each source path), then with common extensions appended.

#_parse_jsdoc_text

def _parse_jsdoc_text(raw_jsdoc)

Parse raw JSDoc content (the lines between /* and /).

Returns a dict with: - description: the main description text - params: list of {name, description} - returns: return description or None - tags: list of {tag, name, description} for other tags

#_find_jsdoc_before

def _find_jsdoc_before(source, pos)

Find the JSDoc block that ends right before pos in the source.

Looks backwards from pos for a / that's part of a / ... / block, allowing only whitespace between the end of the JSDoc and pos.

#_format_jsdoc_as_markdown

def _format_jsdoc_as_markdown(jsdoc)

Format a parsed JSDoc dict as markdown text.

#_handle_module

def _handle_module(arg, body, source_paths, base_dir, attrs)

Extract module-level JSDoc and exported declarations from a TS/JS file.

#_extract_module_jsdoc

def _extract_module_jsdoc(source)

Extract the first JSDoc block that appears before any declaration.

A module-level JSDoc is a /* / block at the top of the file, before any import/export/declaration.

#_extract_exports

def _extract_exports(source)

Extract all exported declarations with their JSDoc and signatures.

Returns a list of dicts with: name, signature, jsdoc (parsed or None).

#_extract_name_from_signature

def _extract_name_from_signature(sig)

Extract the declaration name from an export signature string.

#_handle_test

def _handle_test(arg, body, source_paths, base_dir, attrs)

Extract test source code from a test file.

arg format: [TestName]

For TS/JS test files, looks for describe("TestName", ...), it("TestName", ...), or test("TestName", ...) blocks.

#_extract_test_block

def _extract_test_block(source, target_name)

Find a describe/it/test block by name and extract its source.

Searches for patterns like: describe("Name", ... it("Name", ... test("Name", ... Then tracks brace depth to find the end of the block.

#_handle_schema

def _handle_schema(arg, body, source_paths, base_dir, attrs)

Extract interface or type definition fields as a markdown table.

arg format: - path/to/file.json -> render JSON keys as table - path/to/file.ts TypeName -> extract interface/type fields - path/to/file.ts -> if only one interface, extract it

#_schema_from_ts

def _schema_from_ts(source, type_name, display_path)

Extract interface or type fields from TypeScript source as a markdown table.

#_extract_brace_block

def _extract_brace_block(source, open_brace_pos)

Extract the content between matched braces starting at open_brace_pos.

Returns the content between { and } (exclusive), or None if unmatched.

#_parse_interface_fields

def _parse_interface_fields(body)

Parse fields from an interface/type body string.

Each field looks like: fieldName: Type; fieldName?: Type; Possibly preceded by a JSDoc comment or inline comment.

#_find_inline_comment

def _find_inline_comment(line)

Find the position of an inline // comment, ignoring those inside strings.

Returns the index of the // or None if no inline comment found.

#_handle_cli

def _handle_cli(arg, body, source_paths, base_dir, attrs)

Extract CLI help/usage information from a TS/JS file.

Looks for:

• Module-level JSDoc comment
• const help = "..." or const usage = "..." string constants
• yargs/commander setup patterns

#_handle_config

def _handle_config(arg, body, source_paths, base_dir, attrs)

Extract config file contents as a documented table.

Supports JSON, JSONC (strips // and / / comments), and TOML.

#_config_from_jsonc

def _config_from_jsonc(full_path, display_path, exclude_keys: set[str] | None=None)

Parse JSONC config (strip comments) and render as a key-value table.

#_strip_jsonc_comments

def _strip_jsonc_comments(text)

Strip // and / / comments from JSONC text, respecting strings.

#_handle_prose_desc

def _handle_prose_desc(arg, body, source_paths, base_dir, attrs)

Extract only the module-level JSDoc as prose markdown.

Unlike :::module which also lists exported declarations, this directive returns just the module-level JSDoc description.