# アーキテクチャ構成図

## システム全体構成図

```mermaid
graph TB
    subgraph "Entry Points"
        CLI["coffee CLI<br/>(bin/coffee)"]
        CAKE["cake CLI<br/>(bin/cake)"]
        NodeAPI["Node.js API<br/>(index.coffee)"]
        BrowserAPI["Browser API<br/>(browser.coffee)"]
    end

    subgraph "Compiler Core"
        CS["CoffeeScript<br/>(coffeescript.coffee)"]
    end

    subgraph "Compilation Pipeline"
        LEXER["Lexer<br/>(lexer.coffee)"]
        REWRITER["Rewriter<br/>(rewriter.coffee)"]
        PARSER["Parser<br/>(parser.js)"]
        GRAMMAR["Grammar<br/>(grammar.coffee)"]
        NODES["Nodes<br/>(nodes.coffee)"]
        SCOPE["Scope<br/>(scope.litcoffee)"]
    end

    subgraph "Support Modules"
        HELPERS["Helpers<br/>(helpers.coffee)"]
        SOURCEMAP["SourceMap<br/>(sourcemap.litcoffee)"]
        OPTPARSE["OptionParser<br/>(optparse.coffee)"]
    end

    subgraph "Runtime"
        REPL["REPL<br/>(repl.coffee)"]
        REGISTER["Register<br/>(register.coffee)"]
    end

    subgraph "External Dependencies"
        JISON["Jison"]
        BABEL["Babel<br/>(optional)"]
        NODEJS["Node.js"]
        BROWSER["Browser"]
    end

    CLI --> CS
    CAKE --> CS
    NodeAPI --> CS
    BrowserAPI --> CS

    CS --> LEXER
    LEXER --> REWRITER
    REWRITER --> PARSER
    GRAMMAR -.->|generates| PARSER
    PARSER --> NODES
    NODES --> SCOPE

    CS --> SOURCEMAP
    CS --> HELPERS

    CLI --> OPTPARSE
    CAKE --> OPTPARSE

    REPL --> CS
    REGISTER --> CS

    GRAMMAR --> JISON
    CS -.->|transpile| BABEL

    NodeAPI --> NODEJS
    BrowserAPI --> BROWSER
    REGISTER --> NODEJS
```

## コンパイルパイプライン詳細図

```mermaid
flowchart LR
    subgraph Input
        SOURCE["CoffeeScript<br/>Source Code"]
    end

    subgraph "Lexical Analysis"
        TOKENIZE["Tokenize<br/>(lexer.coffee)"]
        REWRITE["Rewrite<br/>(rewriter.coffee)"]
    end

    subgraph "Syntactic Analysis"
        PARSE["Parse<br/>(parser.js)"]
    end

    subgraph "Code Generation"
        AST["AST<br/>(nodes.coffee)"]
        COMPILE["Compile to<br/>Fragments"]
        GENERATE["Generate<br/>JavaScript"]
    end

    subgraph Output
        JS["JavaScript<br/>Output"]
        SMAP["Source Map<br/>(optional)"]
    end

    SOURCE --> TOKENIZE
    TOKENIZE -->|Token Stream| REWRITE
    REWRITE -->|Normalized Tokens| PARSE
    PARSE -->|AST| AST
    AST --> COMPILE
    COMPILE -->|CodeFragments| GENERATE
    GENERATE --> JS
    GENERATE -.-> SMAP
```

## モジュール依存関係図

```mermaid
graph TD
    subgraph "Entry Layer"
        command["command.coffee"]
        index["index.coffee"]
        browser["browser.coffee"]
        cake["cake.coffee"]
    end

    subgraph "Core Layer"
        coffeescript["coffeescript.coffee"]
    end

    subgraph "Analysis Layer"
        lexer["lexer.coffee"]
        rewriter["rewriter.coffee"]
        grammar["grammar.coffee"]
        parser["parser.js"]
    end

    subgraph "Generation Layer"
        nodes["nodes.coffee"]
        scope["scope.litcoffee"]
    end

    subgraph "Support Layer"
        helpers["helpers.coffee"]
        sourcemap["sourcemap.litcoffee"]
        optparse["optparse.coffee"]
    end

    subgraph "Runtime Layer"
        repl["repl.coffee"]
        register["register.coffee"]
    end

    command --> coffeescript
    command --> optparse
    command --> helpers

    index --> coffeescript
    browser --> coffeescript
    cake --> coffeescript
    cake --> optparse

    coffeescript --> lexer
    coffeescript --> parser
    coffeescript --> helpers
    coffeescript --> sourcemap

    lexer --> rewriter
    lexer --> helpers

    rewriter --> helpers

    parser --> nodes
    grammar -.-> parser

    nodes --> scope
    nodes --> helpers

    scope --> helpers

    repl --> coffeescript
    repl --> helpers
    repl --> nodes

    register --> coffeescript
    register --> helpers
```

## AST ノード階層図

```mermaid
classDiagram
    class Base {
        +compile(o, lvl)
        +compileToFragments(o, lvl)
        +compileNode(o)
        +traverseChildren(callback)
        +eachChild(callback)
    }

    class Root {
        +body: Block
    }

    class Block {
        +expressions: Array
        +push(node)
    }

    class Literal {
        +value: string
    }

    class Value {
        +base: Base
        +properties: Array
    }

    class Call {
        +variable: Value
        +args: Array
    }

    class Code {
        +params: Array
        +body: Block
        +bound: boolean
    }

    class Op {
        +operator: string
        +first: Base
        +second: Base
    }

    class Assign {
        +variable: Value
        +value: Base
    }

    class If {
        +condition: Base
        +body: Block
        +elseBody: Block
    }

    class For {
        +body: Block
        +source: Base
    }

    class While {
        +condition: Base
        +body: Block
    }

    class Class {
        +variable: Value
        +parent: Base
        +body: Block
    }

    Base <|-- Root
    Base <|-- Block
    Base <|-- Literal
    Base <|-- Value
    Base <|-- Call
    Base <|-- Code
    Base <|-- Op
    Base <|-- Assign
    Base <|-- If
    Base <|-- For
    Base <|-- While
    Base <|-- Class
```

## CLIコマンド処理フロー

```mermaid
flowchart TD
    START["coffee command<br/>invoked"]
    PARSE_OPTS["Parse CLI Options<br/>(optparse.coffee)"]

    HELP{help?}
    VERSION{version?}
    INTERACTIVE{interactive?}
    EVAL{eval?}
    STDIO{stdio?}
    WATCH{watch?}

    SHOW_HELP["Show Help"]
    SHOW_VERSION["Show Version"]
    START_REPL["Start REPL"]
    EVAL_CODE["Evaluate Code"]
    COMPILE_STDIN["Compile from STDIN"]

    COMPILE_PATH["Compile Path(s)"]
    WATCH_FILES["Watch Files"]

    OUTPUT_JS["Output JavaScript"]

    START --> PARSE_OPTS
    PARSE_OPTS --> HELP

    HELP -->|yes| SHOW_HELP
    HELP -->|no| VERSION

    VERSION -->|yes| SHOW_VERSION
    VERSION -->|no| INTERACTIVE

    INTERACTIVE -->|yes| START_REPL
    INTERACTIVE -->|no| EVAL

    EVAL -->|yes| EVAL_CODE
    EVAL -->|no| STDIO

    STDIO -->|yes| COMPILE_STDIN
    STDIO -->|no| COMPILE_PATH

    COMPILE_PATH --> WATCH
    WATCH -->|yes| WATCH_FILES
    WATCH -->|no| OUTPUT_JS

    WATCH_FILES -->|file changed| COMPILE_PATH
```

## ブラウザ統合フロー

```mermaid
sequenceDiagram
    participant Page as HTML Page
    participant CS as CoffeeScript (browser.coffee)
    participant Compiler as Compiler Core

    Page->>CS: DOMContentLoaded
    CS->>Page: Find script tags (text/coffeescript)

    loop For each script tag
        alt Has src attribute
            CS->>Page: XHR load script
            Page-->>CS: Script content
        else Inline script
            CS->>CS: Get innerHTML
        end
        CS->>Compiler: compile(code, options)
        Compiler-->>CS: JavaScript
        CS->>Page: eval(JavaScript)
    end
```

## ソースマップ生成フロー

```mermaid
flowchart TD
    subgraph "Compilation"
        COMPILE["Compile AST<br/>to Fragments"]
        TRACK["Track Source<br/>Positions"]
    end

    subgraph "SourceMap Generation"
        LINEMAP["Create LineMap<br/>for each line"]
        ADD["Add column<br/>mappings"]
        VLQ["Encode as<br/>Base64 VLQ"]
    end

    subgraph "Output"
        V3["Generate V3<br/>Source Map JSON"]
        INLINE["Inline as<br/>Data URL"]
        FILE["Write .js.map<br/>file"]
    end

    COMPILE --> TRACK
    TRACK --> LINEMAP
    LINEMAP --> ADD
    ADD --> VLQ
    VLQ --> V3
    V3 --> INLINE
    V3 --> FILE
```
