# femadevspace/femascript-lang architecture

> Architecture diagram of the GitHub repository femadevspace/femascript-lang, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/femadevspace/femascript-lang
- Repository: https://github.com/femadevspace/femascript-lang

## Overview

FemaScript Lang is a Visual Studio Code language-support extension for an educational Portugol-inspired language. The principal workflow is an editor document entering the extension, being parsed for syntax feedback or formatted into a text edit. The grammar spans lexing and parsing; formatting uses a CST visitor and style rules. The README also documents syntax highlighting and snippets, but the supplied tree shows no snippets implementation. Edges are limited to relationships visible in excerpts, the source index, or README; unsampled internals are not assumed.

Main entry points: [`src/features/formatting.ts`](https://github.com/femadevspace/femascript-lang/blob/main/src/features/formatting.ts) (Format provider), [`src/features/semantics.ts`](https://github.com/femadevspace/femascript-lang/blob/main/src/features/semantics.ts) (Syntax checking), [`src/formatter/formatter-helper.ts`](https://github.com/femadevspace/femascript-lang/blob/main/src/formatter/formatter-helper.ts) (Format engine), [`src/features/index.ts`](https://github.com/femadevspace/femascript-lang/blob/main/src/features/index.ts) (Feature registry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_editor["Editor integration"]
  node_extension["Extension entry<br/>[extension.ts]"]
  node_features["Feature registry<br/>[index.ts]"]
  node_diagnostics["Diagnostics<br/>[diagnostics.ts]"]
  node_semantics["Syntax checking<br/>[semantics.ts]"]
  node_format_provider["Format provider<br/>[formatting.ts]"]
  node_highlight["Syntax highlighting<br/>[textmate.ts]"]
end

subgraph group_language["Language grammar"]
  node_grammar["Grammar exports<br/>[index.ts]"]
  node_lexer["Lexer<br/>[lexer.ts]"]
  node_token_definitions["Token definitions<br/>[keywords.ts]"]
  node_parser["Parser<br/>[parser.ts]"]
end

subgraph group_format["Formatting"]
  node_formatter_api["Format engine"]
  node_format_visitor["CST visitor<br/>[formatter.ts]"]
  node_control_visitors["Control-flow visitors"]
  node_format_rules["Layout rules<br/>[breaklines.ts]"]
  node_format_settings["Format settings<br/>[settings.ts]"]
  node_rule_helpers["Rule helpers<br/>[rules.ts]"]
end

subgraph group_shared["Shared utilities"]
  node_comment_processing["Comment processing<br/>[index.ts]"]
  node_globals["Language globals<br/>[globals.ts]"]
  node_safe["Safe results<br/>[safe.ts]"]
end

node_vscode(("VS Code"))

node_vscode -.->|"activates"| node_extension
node_extension -->|"registers"| node_features
node_features -->|"registers"| node_diagnostics
node_features -->|"registers"| node_format_provider
node_features -->|"registers"| node_semantics
node_vscode -->|"requests formatting"| node_format_provider
node_format_provider -->|"formats text"| node_formatter_api
node_format_provider -->|"loads defaults"| node_format_settings
node_semantics -->|"parses input"| node_grammar
node_semantics -->|"reports errors"| node_diagnostics
node_semantics -->|"uses language ID"| node_globals
node_semantics -->|"checks result"| node_safe
node_grammar -->|"exports"| node_lexer
node_grammar -->|"exports"| node_parser
node_parser -->|"gets tokens"| node_lexer
node_parser -->|"consumes tokens"| node_token_definitions
node_parser -->|"uses comment types"| node_comment_processing
node_formatter_api -->|"parses input"| node_grammar
node_formatter_api -->|"visits CST"| node_format_visitor
node_formatter_api -->|"applies defaults"| node_format_settings
node_formatter_api -->|"flattens rules"| node_rule_helpers
node_format_visitor -->|"prints comments"| node_comment_processing
node_control_visitors -->|"uses layout rules"| node_format_rules
node_control_visitors -->|"separates rules"| node_rule_helpers
node_format_provider -->|"uses language ID"| node_globals
node_format_provider -->|"checks result"| node_safe
node_vscode -.->|"uses highlighting"| node_highlight

click node_extension "https://github.com/femadevspace/femascript-lang/blob/main/src/extension.ts"
click node_features "https://github.com/femadevspace/femascript-lang/blob/main/src/features/index.ts"
click node_diagnostics "https://github.com/femadevspace/femascript-lang/blob/main/src/features/diagnostics.ts"
click node_semantics "https://github.com/femadevspace/femascript-lang/blob/main/src/features/semantics.ts"
click node_format_provider "https://github.com/femadevspace/femascript-lang/blob/main/src/features/formatting.ts"
click node_highlight "https://github.com/femadevspace/femascript-lang/blob/main/src/utils/textmate.ts"
click node_grammar "https://github.com/femadevspace/femascript-lang/blob/main/src/grammar/index.ts"
click node_lexer "https://github.com/femadevspace/femascript-lang/blob/main/src/grammar/lexer/lexer.ts"
click node_token_definitions "https://github.com/femadevspace/femascript-lang/blob/main/src/grammar/lexer/tokens/keywords.ts"
click node_parser "https://github.com/femadevspace/femascript-lang/blob/main/src/grammar/parser/parser.ts"
click node_comment_processing "https://github.com/femadevspace/femascript-lang/blob/main/src/utils/comments/index.ts"
click node_formatter_api "https://github.com/femadevspace/femascript-lang/blob/main/src/formatter/formatter-helper.ts"
click node_format_visitor "https://github.com/femadevspace/femascript-lang/blob/main/src/formatter/formatter.ts"
click node_control_visitors "https://github.com/femadevspace/femascript-lang/blob/main/src/formatter/visitors/statements-control-flow.ts"
click node_format_rules "https://github.com/femadevspace/femascript-lang/blob/main/src/formatter/rules/breaklines.ts"
click node_format_settings "https://github.com/femadevspace/femascript-lang/blob/main/src/formatter/settings.ts"
click node_rule_helpers "https://github.com/femadevspace/femascript-lang/blob/main/src/formatter/utils/rules.ts"
click node_globals "https://github.com/femadevspace/femascript-lang/blob/main/src/utils/globals.ts"
click node_safe "https://github.com/femadevspace/femascript-lang/blob/main/src/utils/safe.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_extension,node_features,node_diagnostics,node_semantics,node_format_provider,node_highlight toneBlue
class node_grammar,node_lexer,node_token_definitions,node_parser toneAmber
class node_formatter_api,node_format_visitor,node_control_visitors,node_format_rules,node_format_settings,node_rule_helpers toneMint
class node_comment_processing,node_globals,node_safe toneRose
class node_vscode toneIndigo
```

## Components

### Editor integration

- [Extension entry](https://github.com/femadevspace/femascript-lang/blob/main/src/extension.ts): `src/extension.ts`
- [Feature registry](https://github.com/femadevspace/femascript-lang/blob/main/src/features/index.ts): `src/features/index.ts`
- [Diagnostics](https://github.com/femadevspace/femascript-lang/blob/main/src/features/diagnostics.ts): `src/features/diagnostics.ts`
- [Syntax checking](https://github.com/femadevspace/femascript-lang/blob/main/src/features/semantics.ts): `src/features/semantics.ts`
- [Format provider](https://github.com/femadevspace/femascript-lang/blob/main/src/features/formatting.ts): `src/features/formatting.ts`
- [Syntax highlighting](https://github.com/femadevspace/femascript-lang/blob/main/src/utils/textmate.ts): `src/utils/textmate.ts`

### Language grammar

- [Grammar exports](https://github.com/femadevspace/femascript-lang/blob/main/src/grammar/index.ts): `src/grammar/index.ts`
- [Lexer](https://github.com/femadevspace/femascript-lang/blob/main/src/grammar/lexer/lexer.ts): `src/grammar/lexer/lexer.ts`
- [Token definitions](https://github.com/femadevspace/femascript-lang/blob/main/src/grammar/lexer/tokens/keywords.ts): `src/grammar/lexer/tokens/keywords.ts`
- [Parser](https://github.com/femadevspace/femascript-lang/blob/main/src/grammar/parser/parser.ts): `src/grammar/parser/parser.ts`

### Formatting

- [Format engine](https://github.com/femadevspace/femascript-lang/blob/main/src/formatter/formatter-helper.ts): `src/formatter/formatter-helper.ts`
- [CST visitor](https://github.com/femadevspace/femascript-lang/blob/main/src/formatter/formatter.ts): `src/formatter/formatter.ts`
- [Control-flow visitors](https://github.com/femadevspace/femascript-lang/blob/main/src/formatter/visitors/statements-control-flow.ts): `src/formatter/visitors/statements-control-flow.ts`
- [Layout rules](https://github.com/femadevspace/femascript-lang/blob/main/src/formatter/rules/breaklines.ts): `src/formatter/rules/breaklines.ts`
- [Format settings](https://github.com/femadevspace/femascript-lang/blob/main/src/formatter/settings.ts): `src/formatter/settings.ts`
- [Rule helpers](https://github.com/femadevspace/femascript-lang/blob/main/src/formatter/utils/rules.ts): `src/formatter/utils/rules.ts`

### Shared utilities

- [Comment processing](https://github.com/femadevspace/femascript-lang/blob/main/src/utils/comments/index.ts): `src/utils/comments/index.ts`
- [Language globals](https://github.com/femadevspace/femascript-lang/blob/main/src/utils/globals.ts): `src/utils/globals.ts`
- [Safe results](https://github.com/femadevspace/femascript-lang/blob/main/src/utils/safe.ts): `src/utils/safe.ts`

### Other components

- **VS Code**

## Connections

- VS Code → Extension entry: activates
- Extension entry → Feature registry: registers (evidence: `src/extension.ts`)
- Feature registry → Diagnostics: registers (evidence: `src/features/index.ts`)
- Feature registry → Format provider: registers (evidence: `src/features/index.ts`)
- Feature registry → Syntax checking: registers (evidence: `src/features/index.ts`)
- VS Code → Format provider: requests formatting (evidence: `src/features/formatting.ts`)
- Format provider → Format engine: formats text (evidence: `src/features/formatting.ts`)
- Format provider → Format settings: loads defaults (evidence: `src/features/formatting.ts`)
- Syntax checking → Grammar exports: parses input (evidence: `src/features/semantics.ts`)
- Syntax checking → Diagnostics: reports errors (evidence: `src/features/semantics.ts`)
- Syntax checking → Language globals: uses language ID (evidence: `src/features/semantics.ts`)
- Syntax checking → Safe results: checks result (evidence: `src/features/semantics.ts`)
- Grammar exports → Lexer: exports (evidence: `src/grammar/index.ts`)
- Grammar exports → Parser: exports (evidence: `src/grammar/index.ts`)
- Parser → Lexer: gets tokens (evidence: `src/grammar/parser/parser.ts`)
- Parser → Token definitions: consumes tokens (evidence: `src/grammar/parser/parser.ts`)
- Parser → Comment processing: uses comment types (evidence: `src/grammar/parser/parser.ts`)
- Format engine → Grammar exports: parses input (evidence: `src/formatter/formatter-helper.ts`)
- Format engine → CST visitor: visits CST (evidence: `src/formatter/formatter-helper.ts`)
- Format engine → Format settings: applies defaults (evidence: `src/formatter/formatter-helper.ts`)
- Format engine → Rule helpers: flattens rules (evidence: `src/formatter/formatter-helper.ts`)
- CST visitor → Comment processing: prints comments (evidence: `src/formatter/formatter.ts`)
- Control-flow visitors → Layout rules: uses layout rules (evidence: `src/formatter/visitors/statements-control-flow.ts`)
- Control-flow visitors → Rule helpers: separates rules (evidence: `src/formatter/visitors/statements-control-flow.ts`)
- Format provider → Language globals: uses language ID (evidence: `src/features/formatting.ts`)
- Format provider → Safe results: checks result (evidence: `src/features/formatting.ts`)
- VS Code → Syntax highlighting: uses highlighting (evidence: `README.md`)
