codoc 0.1.0

Unified documentation parser for Ruby and TypeScript codebases
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136

//! Source code parsers for Ruby and TypeScript.

pub mod doc_comment;
pub mod ruby;
pub mod typescript;

use crate::error::Result;
use crate::schema::{Document, Entity, Language, Metadata, SymbolEntry};
use std::path::Path;

/// Parser configuration.
#[derive(Debug, Clone)]
pub struct ParserConfig {
    /// Project name.
    pub name: String,

    /// Project version.
    pub version: Option<String>,

    /// Source root directory.
    pub source_root: String,

    /// ID prefix for all entities.
    pub id_prefix: Option<String>,

    /// Source language.
    pub language: Language,
}

impl ParserConfig {
    /// Creates a new parser configuration.
    pub fn new(name: impl Into<String>, language: Language) -> Self {
        Self {
            name: name.into(),
            version: None,
            source_root: ".".to_string(),
            id_prefix: None,
            language,
        }
    }

    /// Sets the project version.
    pub fn with_version(mut self, version: impl Into<String>) -> Self {
        self.version = Some(version.into());
        self
    }

    /// Sets the source root.
    pub fn with_source_root(mut self, root: impl Into<String>) -> Self {
        self.source_root = root.into();
        self
    }

    /// Sets the ID prefix.
    pub fn with_id_prefix(mut self, prefix: impl Into<String>) -> Self {
        self.id_prefix = Some(prefix.into());
        self
    }
}

/// Trait for source code parsers.
pub trait Parser {
    /// Returns the language this parser handles.
    fn language(&self) -> Language;

    /// Parses a single file and returns its entities.
    fn parse_file(&mut self, path: &Path, content: &str) -> Result<Vec<Entity>>;

    /// Generates symbol entries from entities.
    fn generate_symbols(&self, entities: &[Entity], parent: Option<&str>) -> Vec<SymbolEntry>;
}

/// Context for parsing operations.
pub struct ParseContext {
    /// Parser configuration.
    pub config: ParserConfig,

    /// Collected entities.
    pub entities: Vec<Entity>,

    /// Collected symbols.
    pub symbols: Vec<SymbolEntry>,

    /// Parsed files.
    pub files: Vec<String>,
}

impl ParseContext {
    /// Creates a new parse context.
    pub fn new(config: ParserConfig) -> Self {
        Self {
            config,
            entities: Vec::new(),
            symbols: Vec::new(),
            files: Vec::new(),
        }
    }

    /// Builds the final document.
    pub fn into_document(self) -> Document {
        let metadata = Metadata {
            name: self.config.name,
            version: self.config.version,
            language: self.config.language,
            generated_at: chrono::Utc::now().to_rfc3339(),
            source_root: Some(self.config.source_root),
            id_prefix: self.config.id_prefix,
            files: self.files,
            external_links: Default::default(),
        };

        Document {
            schema: crate::SCHEMA_VERSION.to_string(),
            metadata,
            entities: self.entities,
            symbols: self.symbols,
            unresolved_references: Vec::new(),
        }
    }

    /// Prefixes an ID with the configured prefix.
    pub fn prefix_id(&self, id: &str) -> String {
        match &self.config.id_prefix {
            Some(prefix) => format!("{}{}", prefix, id),
            None => id.to_string(),
        }
    }
}

/// Utility to get relative path from source root.
pub fn relative_path(path: &Path, source_root: &Path) -> String {
    path.strip_prefix(source_root)
        .unwrap_or(path)
        .to_string_lossy()
        .to_string()
}