Parsing & Source Analysis

Overview

The Parsing & Source Analysis feature is responsible for extracting structured information from source files, inferring types, and identifying key symbols (such as components, props, methods, and runtime features) for downstream documentation and code intelligence. It forms the backbone of DeepDoc's evidence assembly, enabling accurate, language-aware documentation generation and symbol indexing.

This module supports multi-language parsing, with specialized logic for Vue Single File Components (SFCs), JavaScript, and TypeScript. It detects business-relevant constructs (like Vue props, emits, composables, and runtime integrations) and normalizes them into a unified symbol model for further processing in the Pipeline & Generation Engine.

Files Covered

Main Workflows

The primary workflow for source parsing and analysis is as follows:

Data Flow Diagram

Participating Endpoints

This feature operates at the file parsing layer and does not expose direct API endpoints. However, its outputs are consumed by endpoints documented in Public API Endpoints and Runtime Services & Chatbot Engine, which serve parsed symbol data and documentation to clients.

Core Helpers & Business Rules

parse_vue() (deepdoc/parser/vue_parser.py:25)

• Purpose: Parses Vue SFCs, extracts script/template blocks, delegates JS/TS parsing, and infers Vue-specific constructs.
• Parameters: path: Path, content: str, language: str
• Returns: ParsedFile (deepdoc/parser/base.py:35)
• Branching Logic:
  • If no script block, returns a ParsedFile with only template/style info.
  • Determines effective language (typescript if lang is ts/tsx, else javascript).
  • If <script setup>, extracts Composition API constructs; else, extracts Options API constructs.
  • Always extracts runtime features and template info.
• Example Usage:

  parsed = parse_vue(path, content, language)

• Edge Cases:
  • If both <script setup> and <script> exist, <script setup> is preferred.
  • If component name is not found, falls back to filename stem.

_extract_script_block() (deepdoc/parser/vue_parser.py:86)

• Purpose: Extracts script content, language, and setup status from Vue SFC.
• Returns: (script_content, lang, is_setup)
• Branching Logic:
  • Prefers <script setup> over regular <script>.
  • Determines language from lang attribute.
• Example:

  script_content, script_lang, is_setup = _extract_script_block(content)

_extract_script_setup_constructs() (deepdoc/parser/vue_parser.py:138)

• Purpose: Extracts defineProps, defineEmits, defineExpose, defineModel, defineSlots, and reactivity primitives from <script setup>.
• Branching Logic:
  • If defineProps uses type parameter, extracts prop names from type.
  • If defineProps uses object parameter, extracts prop names from object keys.
  • If defineEmits uses type parameter or array, extracts event names.
  • If defineExpose is present, extracts exposed names.
  • If defineModel is present, extracts model name.
  • If defineSlots is present, extracts slot names.
  • Always extracts reactivity primitives (ref, reactive, computed, etc.).
• Example:

  _extract_script_setup_constructs(script_content, parsed.symbols)

_extract_options_api_constructs() (deepdoc/parser/vue_parser.py:300)

• Purpose: Extracts props, emits, and methods from Options API export default object.
• Branching Logic:
  • If props is object, extracts prop names from keys.
  • If props is array, extracts prop names from array values.
  • If emits is array, extracts event names.
  • If methods is object, extracts method names.
• Example:

  _extract_options_api_constructs(script_content, parsed.symbols)

_extract_template_info() (deepdoc/parser/vue_parser.py:383)

• Purpose: Extracts child component usage and slot info from template block.
• Branching Logic:
  • Detects PascalCase tags as child components.
  • Detects named slots and default slot.
• Example:

  _extract_template_info(template_content, parsed.symbols)

Symbol (deepdoc/parser/base.py:17)

• Purpose: Represents a named code symbol extracted from a file.
• Fields: name, kind, signature, docstring, fields, props, is_exported, etc.
• Example:

  symbol = Symbol(name="props", kind="constant", signature="defineProps()", docstring="Component props: ...")

ParsedFile (deepdoc/parser/base.py:35)

• Purpose: Structured representation of a parsed source file.
• Fields: path, language, symbols, imports, raw_content
• Example:

  parsed = ParsedFile(path=path, language="vue", symbols=symbols, imports=[], raw_content=content[:8000])

parse_js_ts() (deepdoc/parser/js_ts_parser.py:28)

• Purpose: Parses JS/TS files, infers symbols and imports, tags React constructs.
• Branching Logic:
  • Uses Tree-sitter parser if available; else, falls back to regex.
  • Tags React components/hooks by naming convention.
• Example:

  parsed = parse_js_ts(path, script_content, effective_lang)

State Transitions

The parsing process transforms raw source files into structured symbol representations. The state transitions are:

• RawFile: Initial state, raw source content.
• ScriptBlockExtracted: Script block and language extracted.
• ParsedSymbols: JS/TS symbols parsed.
• VueConstructsExtracted: Vue-specific constructs extracted.
• TemplateInfoExtracted: Template block analyzed for slots/components.
• ParsedFile: Final structured representation.

Integrations Involved

• Pipeline & Generation Engine: Consumes ParsedFile objects for evidence assembly and documentation generation. See Pipeline & Generation Engine.
• Frontend Site Builder: Uses parsed symbols for UI scaffolding and documentation rendering. See Site Generation & Frontend Integration Overview.

Configuration & Environment

No environment variables or config flags directly affect the parsing logic in the evidenced files.

Edge Cases & Failure Modes

• Missing Script Block: If a Vue SFC lacks a <script> block, parse_vue() returns a ParsedFile with only template/style info.
• Multiple Script Blocks: If both <script setup> and <script> exist, <script setup> is preferred.
• Malformed Blocks: If script/template blocks are malformed or missing, extraction functions return empty content, resulting in reduced symbol output.
• Unknown Component Name: If no explicit name is found, the filename stem is used as the component name.
• JS/TS Parser Fallback: If Tree-sitter is unavailable, parse_js_ts() falls back to regex-based parsing, which may be less accurate.

Diagrams

Data Flow Diagram

See above in "Main Workflows".

State Transition Diagram

See above in "State Transitions".

Quick Reference

Constants, Enums & Status Values

No enums or status constants directly affect runtime parsing behavior in the evidenced files. The Symbol and ParsedFile classes define type fields (kind, language) which are string values, e.g. "component", "constant", "method", "vue", "javascript", "typescript".

See Also

• Pipeline & Generation Engine
• Setup & Getting Started
• Site Generation & Frontend Integration Overview
• DeepDoc Architecture & System Overview