# harsh-programming-language/harsh-lang architecture

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

- Interactive diagram: https://gitdiagram.com/harsh-programming-language/harsh-lang
- Repository: https://github.com/harsh-programming-language/harsh-lang

## Overview

Harsh is a Rust-oriented language toolchain: it transforms indentation-based `.hrs` source into Rust, then relies on Cargo and rustc for compilation. The main workflow runs through the `hrs` CLI and build driver; the driver coordinates tokenization, layout and syntax rewrites, Rust emission, and source maps. Separate tools convert Rust back to Harsh and remap compiler diagnostics. The README also documents formatting, project commands, linear-algebra runtime support, a language server, and editor integrations. Internal links follow excerpts, source-index references, or README statements; unsampled details are not inferred.

Main entry points: [`src/driver.rs`](https://github.com/harsh-programming-language/harsh-lang/blob/main/src/driver.rs) (Build driver), [`src/layout.rs`](https://github.com/harsh-programming-language/harsh-lang/blob/main/src/layout.rs) (Layout pass), [`src/emit.rs`](https://github.com/harsh-programming-language/harsh-lang/blob/main/src/emit.rs) (Rust emitter), [`src/lex.rs`](https://github.com/harsh-programming-language/harsh-lang/blob/main/src/lex.rs) (Lexer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_transpile["Transpilation"]
  node_lexer["Lexer<br/>[lex.rs]"]
  node_layout["Layout pass<br/>[layout.rs]"]
  node_juxtaposition["Juxtaposed calls<br/>[juxt.rs]"]
  node_macros["Harsh macros<br/>[mac.rs]"]
  node_rust_macros["Rust macro zones<br/>[rawzone.rs]"]
  node_dsl_zones["DSL macro holes<br/>[dslzone.rs]"]
  node_emitter["Rust emitter<br/>[emit.rs]"]
end

subgraph group_tooling["Project Tooling"]
  node_hrs["hrs CLI<br/>[main.rs]"]
  node_driver["Build driver<br/>[driver.rs]"]
  node_formatter["Formatter<br/>[fmt.rs]"]
  node_source_maps["Source maps<br/>[dist.rs]"]
  node_remapper["Diagnostic remapper<br/>[remap.rs]"]
  node_converter["Rust converter<br/>[unbrace.rs]"]
end

subgraph group_runtime["Language Runtime"]
  node_std_matrix["Matrix runtime<br/>[lib.rs]"]
  node_std_slicing["Matrix slicing<br/>[slicing.rs]"]
end

subgraph group_editors["Editor Support"]
  node_lsp["Language server<br/>[hrs-lsp.rs]"]
  node_tree_sitter["Harsh grammar<br/>[grammar.js]"]
  node_vscode["VS Code extension<br/>[extension.js]"]
  node_zed["Zed extension<br/>[lib.rs]"]
end

node_user(("Developer"))
node_cargo["Cargo / rustc"]

node_user -->|"invokes"| node_hrs
node_hrs -.->|"runs"| node_driver
node_driver -->|"uses"| node_lexer
node_driver -->|"uses"| node_layout
node_driver -->|"uses"| node_juxtaposition
node_driver -->|"expands"| node_macros
node_driver -->|"preserves"| node_rust_macros
node_driver -->|"processes"| node_dsl_zones
node_driver -->|"emits with"| node_emitter
node_driver -->|"writes"| node_source_maps
node_driver -->|"uses"| node_formatter
node_driver -->|"uses"| node_remapper
node_lexer -->|"tokenizes for"| node_layout
node_layout -->|"structures for"| node_emitter
node_emitter -->|"generates Rust for"| node_cargo
node_cargo -->|"diagnostics remapped by"| node_remapper
node_user -->|"converts Rust with"| node_converter
node_user -->|"formats with"| node_formatter
node_user -->|"requests on-type formatting"| node_lsp
node_vscode -.->|"integrates grammar"| node_tree_sitter
node_user -->|"uses matrix operations"| node_std_matrix
node_std_matrix -.->|"provides slicing"| node_std_slicing
node_user -.->|"uses Harsh support"| node_zed

click node_hrs "https://github.com/harsh-programming-language/harsh-lang/blob/main/src/main.rs"
click node_driver "https://github.com/harsh-programming-language/harsh-lang/blob/main/src/driver.rs"
click node_lexer "https://github.com/harsh-programming-language/harsh-lang/blob/main/src/lex.rs"
click node_layout "https://github.com/harsh-programming-language/harsh-lang/blob/main/src/layout.rs"
click node_juxtaposition "https://github.com/harsh-programming-language/harsh-lang/blob/main/src/juxt.rs"
click node_macros "https://github.com/harsh-programming-language/harsh-lang/blob/main/src/mac.rs"
click node_rust_macros "https://github.com/harsh-programming-language/harsh-lang/blob/main/src/rawzone.rs"
click node_dsl_zones "https://github.com/harsh-programming-language/harsh-lang/blob/main/src/dslzone.rs"
click node_emitter "https://github.com/harsh-programming-language/harsh-lang/blob/main/src/emit.rs"
click node_formatter "https://github.com/harsh-programming-language/harsh-lang/blob/main/src/fmt.rs"
click node_source_maps "https://github.com/harsh-programming-language/harsh-lang/blob/main/src/dist.rs"
click node_remapper "https://github.com/harsh-programming-language/harsh-lang/blob/main/src/remap.rs"
click node_converter "https://github.com/harsh-programming-language/harsh-lang/blob/main/src/unbrace.rs"
click node_lsp "https://github.com/harsh-programming-language/harsh-lang/blob/main/src/bin/hrs-lsp.rs"
click node_tree_sitter "https://github.com/harsh-programming-language/harsh-lang/blob/main/editors/tree-sitter-harsh/grammar.js"
click node_vscode "https://github.com/harsh-programming-language/harsh-lang/blob/main/editors/vscode-harsh/client/extension.js"
click node_zed "https://github.com/harsh-programming-language/harsh-lang/blob/main/editors/zed-harsh/src/lib.rs"
click node_std_matrix "https://github.com/harsh-programming-language/harsh-lang/blob/main/hrs_std/src/lib.rs"
click node_std_slicing "https://github.com/harsh-programming-language/harsh-lang/blob/main/hrs_std/src/slicing.rs"

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_lexer,node_layout,node_juxtaposition,node_macros,node_rust_macros,node_dsl_zones,node_emitter toneBlue
class node_hrs,node_driver,node_formatter,node_source_maps,node_remapper,node_converter toneAmber
class node_std_matrix,node_std_slicing toneMint
class node_lsp,node_tree_sitter,node_vscode,node_zed toneRose
class node_user,node_cargo toneIndigo
```

## Components

### Transpilation

- [Lexer](https://github.com/harsh-programming-language/harsh-lang/blob/main/src/lex.rs): `src/lex.rs`
- [Layout pass](https://github.com/harsh-programming-language/harsh-lang/blob/main/src/layout.rs): `src/layout.rs`
- [Juxtaposed calls](https://github.com/harsh-programming-language/harsh-lang/blob/main/src/juxt.rs): `src/juxt.rs`
- [Harsh macros](https://github.com/harsh-programming-language/harsh-lang/blob/main/src/mac.rs): `src/mac.rs`
- [Rust macro zones](https://github.com/harsh-programming-language/harsh-lang/blob/main/src/rawzone.rs): `src/rawzone.rs`
- [DSL macro holes](https://github.com/harsh-programming-language/harsh-lang/blob/main/src/dslzone.rs): `src/dslzone.rs`
- [Rust emitter](https://github.com/harsh-programming-language/harsh-lang/blob/main/src/emit.rs): `src/emit.rs`

### Project Tooling

- [hrs CLI](https://github.com/harsh-programming-language/harsh-lang/blob/main/src/main.rs): `src/main.rs`
- [Build driver](https://github.com/harsh-programming-language/harsh-lang/blob/main/src/driver.rs): `src/driver.rs`
- [Formatter](https://github.com/harsh-programming-language/harsh-lang/blob/main/src/fmt.rs): `src/fmt.rs`
- [Source maps](https://github.com/harsh-programming-language/harsh-lang/blob/main/src/dist.rs): `src/dist.rs`
- [Diagnostic remapper](https://github.com/harsh-programming-language/harsh-lang/blob/main/src/remap.rs): `src/remap.rs`
- [Rust converter](https://github.com/harsh-programming-language/harsh-lang/blob/main/src/unbrace.rs): `src/unbrace.rs`

### Language Runtime

- [Matrix runtime](https://github.com/harsh-programming-language/harsh-lang/blob/main/hrs_std/src/lib.rs): `hrs_std/src/lib.rs`
- [Matrix slicing](https://github.com/harsh-programming-language/harsh-lang/blob/main/hrs_std/src/slicing.rs): `hrs_std/src/slicing.rs`

### Editor Support

- [Language server](https://github.com/harsh-programming-language/harsh-lang/blob/main/src/bin/hrs-lsp.rs): `src/bin/hrs-lsp.rs`
- [Harsh grammar](https://github.com/harsh-programming-language/harsh-lang/blob/main/editors/tree-sitter-harsh/grammar.js): `editors/tree-sitter-harsh/grammar.js`
- [VS Code extension](https://github.com/harsh-programming-language/harsh-lang/blob/main/editors/vscode-harsh/client/extension.js): `editors/vscode-harsh/client/extension.js`
- [Zed extension](https://github.com/harsh-programming-language/harsh-lang/blob/main/editors/zed-harsh/src/lib.rs): `editors/zed-harsh/src/lib.rs`

### Other components

- **Developer**
- **Cargo / rustc**

## Connections

- Developer → hrs CLI: invokes (evidence: `README.md`)
- hrs CLI → Build driver: runs
- Build driver → Lexer: uses (evidence: `src/driver.rs`)
- Build driver → Layout pass: uses (evidence: `src/driver.rs`)
- Build driver → Juxtaposed calls: uses (evidence: `src/driver.rs`)
- Build driver → Harsh macros: expands (evidence: `src/driver.rs`)
- Build driver → Rust macro zones: preserves (evidence: `src/driver.rs`)
- Build driver → DSL macro holes: processes (evidence: `src/driver.rs`)
- Build driver → Rust emitter: emits with (evidence: `src/driver.rs`)
- Build driver → Source maps: writes (evidence: `src/driver.rs`)
- Build driver → Formatter: uses (evidence: `src/driver.rs`)
- Build driver → Diagnostic remapper: uses (evidence: `src/driver.rs`)
- Lexer → Layout pass: tokenizes for (evidence: `src/layout.rs`)
- Layout pass → Rust emitter: structures for (evidence: `src/emit.rs`)
- Rust emitter → Cargo / rustc: generates Rust for (evidence: `README.md`)
- Cargo / rustc → Diagnostic remapper: diagnostics remapped by (evidence: `README.md`)
- Developer → Rust converter: converts Rust with (evidence: `README.md`)
- Developer → Formatter: formats with (evidence: `README.md`)
- Developer → Language server: requests on-type formatting (evidence: `README.md`)
- VS Code extension → Harsh grammar: integrates grammar
- Developer → Matrix runtime: uses matrix operations (evidence: `README.md`)
- Matrix runtime → Matrix slicing: provides slicing (evidence: `hrs_std/src/lib.rs`)
- Developer → Zed extension: uses Harsh support
