# Acurity Language Server – Executive Overview

> **Audience:** Technology / Architecture leadership
> **Purpose:** Illustrate the role of this project, its key components, and how they integrate into a developer workflow.

---

## What problem does this solve?

Architect is a proprietary scripting language used across the organisation. Because it is not a mainstream language, standard developer tooling — linters, type checkers, IDE assistants — does not exist for it out of the box.

The **Acurity Language Server** closes that gap. It provides a full, language-aware understanding of Architect code and uses that understanding to:

- Catch errors and standard violations **before they reach production**
- Assist developers **directly in the IDE** with real-time feedback and automated fixes
- Enforce team standards **consistently**, whether working locally or in an automated pipeline

---

## Ecosystem View

Where this project sits in the developer lifecycle.

```mermaid
flowchart TD
    Dev(["Developer"])
    ArchCode[("Architect Codebase")]

    subgraph Core["@acurity/core — Shared Validation Engine"]
        Parser["Language Parser<br/>Tokeniser · Scope model · Include graph"]
        Registry["Built-in Registry<br/>300+ function signatures &amp; types"]
        Validators["Validators — 15 rule engines<br/>Type · Naming · Scope · Functions<br/>Patterns · Documentation · More"]
        Parser --> Validators
        Registry --> Validators
    end

    subgraph IDELayer["VS Code Extension"]
        Write["Writes Architect Code"]
        Enhancements["IDE Enhancements<br/>Highlights · Hover · Quick Fixes<br/>Completions · Navigation · Templates"]
    end

    subgraph CLILayer["@acurity/cli — Headless Validator"]
        CLINode["acurity-validate<br/>Reads files · Runs Core · JSON report<br/>Exits non-zero on threshold breach"]
    end

    subgraph QualityGates["Quality Gates"]
        CICD["CI/CD Pipeline / Git Hook<br/>Blocks non-compliant code from merging"]
        Review["Code Review<br/>Violations visible before PR approval"]
    end

    subgraph Knowledge["Knowledge and Governance"]
        Catalogue["Diagnostic Catalogue<br/>Explains every error and warning<br/>Suppression guidance · Quick fix mapping"]
        SyntaxTests["Syntax Tests — TDD<br/>Architect code fixtures<br/>Define what validators must catch"]
    end

    Dev --> Write
    ArchCode --> Write
    ArchCode --> CLINode

    Write --> Core
    Core --> Enhancements
    Enhancements --> Dev

    CLINode --> Core
    CLINode --> CICD
    CICD --> Review

    SyntaxTests --> Validators
    Validators --> Catalogue

    style CLILayer fill:#f0fdf4,stroke:#16a34a
    style Core     fill:#fefce8,stroke:#ca8a04
    style IDELayer fill:#f0f9ff,stroke:#0284c7
```

---

## Project Structure

The codebase is organised into three top-level folders that mirror the three deployment targets:

```
vs-code-acurity/
├── core/src/               ← Pure Node.js engine — no VS Code dependency
│   ├── analysis/           │   Parser output interpretation, scope analysis
│   ├── builtins/           │   300+ built-in function signatures and registry
│   ├── diagnostics/        │   Diagnostic factory, catalogue, quick-fix catalogue
│   ├── includeResolver/    │   Cross-file dependency graph
│   ├── validators/         │   15 independent rule engines
│   ├── parser.js           │   Tokeniser and structural model
│   ├── constants.js        │   Language keywords, types, IDs
│   └── plainTextDocument.js│   Headless document adapter (CLI-facing)
│
├── vscode-extension/src/   ← VS Code host integration
│   ├── commands/           │   acurity.validateTxtFolder, setup wizard, …
│   ├── config/             │   Rule severity mapped from VS Code settings
│   ├── diagnostics/        │   Scheduling, debounce, collection management
│   ├── diagnostics.js      │   collectDiagnostics() — orchestrates all validators
│   ├── hoverProvider.js
│   ├── completionProvider.js
│   ├── codeActionProvider.js
│   └── …
│
├── cli/                    ← Headless entry point
│   ├── index.js            │   acurity-validate CLI — file scan, JSON report, exit code
│   └── vscode-shim.js      │   Provides vscode-compatible types without the host
│
├── test/syntax-tests/      ← TDD fixture files (Architect code)
└── dev-docs/               ← Architecture docs and diagnostic catalogue
```

This separation means:
- **`core/`** can be tested, published, and consumed without any VS Code installation
- **`vscode-extension/`** is the thin adapter that makes core output visible in the IDE
- **`cli/`** is the thin adapter that makes core output available to pipelines

---

## Component Breakdown

### 1 · Language Parser

The parser is the foundation of the system. Rather than applying regular expressions to raw text, it fully tokenises and builds a structural model of each Architect file.

**What it understands:**
- Variable declarations, types (`STRING`, `LONG`, `DATE`, …), and scope boundaries
- Function definitions and call sites — both user-defined and built-in
- Block structure (`IF/ENDIF`, `DO/ENDDO`, `FUNCTION/ENDFUNCTION`, etc.)
- Macro declarations and invocations
- `INCLUDE` directives and the dependency graph they create across files
- Code sections vs. output sections (hash mode)
- Inline suppression comments (`// @rule-ignore ACU-XXX-NNN`)

This contextual depth is what makes intelligent validation and IDE assistance possible — behaviours that simple text-search tooling cannot achieve.

---

### 2 · Validators

Validators consume the parser's output and apply rules. There are **15 independent rule engines**, each covering a specific domain:

| Domain | What it checks |
|--------|---------------|
| **Function signatures** | Argument count, types, and known built-in behaviour |
| **Type compatibility** | Assignment and parameter type mismatches |
| **Naming conventions** | Variable prefixes, casing rules |
| **Keyword capitalisation** | Language keyword and type keyword casing |
| **Variable scope & usage** | Undeclared variables, scope violations |
| **String interpolation** | `^variable^` syntax and referenced variable existence |
| **Block structure** | Matched `IF/ENDIF`, `DO/ENDDO`, etc. |
| **Include files** | Missing files, circular dependencies, cross-file scope |
| **Macros** | Duplicate names, call-site validation |
| **Argument strings** | Literal string arguments (dates, directions, table synonyms) |
| **Usage patterns** | Index usage, structural anti-patterns |
| **Documentation** | Robodoc comment completeness |
| **Hash mode** | Output section state tracking |
| **REQUIRE statements** | Dependency declarations |
| **Code annotations** | TODO / FIXME / HACK tags |

Each validator produces diagnostics with a **stable, namespaced ID** (e.g. `ACU-FNC-003`). These IDs are the shared vocabulary between the tooling, the test suite, and the Diagnostic Catalogue.

> **Implemented:** The validators run independently of VS Code via the `@acurity/cli` headless entry point (`cli/index.js`). They can be invoked directly from CI/CD pipelines and Git hooks without requiring the editor to be open.

---

### 3 · Syntax Tests

Syntax tests are the **test-driven development (TDD) layer** for the validators.

Each test is written as real Architect code, annotated with expectations about which diagnostics should (or should not) be produced. This approach means:

- Tests are readable by anyone familiar with Architect — not just developers of this tooling
- Edge cases are captured as executable, regression-safe specifications
- New rules are defined by writing a failing test first, then implementing the validator

There are currently **35+ test scenarios** covering all major validator domains.

---

### 4 · IDE Enhancements

The IDE enhancements are the user-facing layer — the part developers interact with directly in VS Code.

```mermaid
flowchart LR
    Dev(["Developer"])

    subgraph Feedback["Passive Feedback"]
        Squiggles["Error and Warning Highlights<br/>Squiggly underlines with message and rule ID"]
        Hover["Hover Cards<br/>Variable type · Function signature<br/>Rule explanation for suppression IDs"]
    end

    subgraph Actions["Active Assistance"]
        QuickFix["Quick Fixes<br/>One-click auto-corrections"]
        GoToDef["Go to Definition<br/>Navigate to declarations across include files"]
        Completions["Completions<br/>Macro name suggestions with parameter hints"]
        Templates["File Templates<br/>New report and include file scaffolds"]
    end

    Dev --> Feedback
    Dev --> Actions
```

---

### 5 · Diagnostic Catalogue

**Location:** `dev-docs/DIAGNOSTICS_COMPREHENSIVE_REFERENCE.md`

The Diagnostic Catalogue is a living reference document that serves two purposes:

1. **Reference** — When a developer encounters a warning or error they don't understand, the catalogue explains what the rule means, shows the test cases that define it, and documents whether and when it is valid to suppress it.

2. **Governance forum** — Because rules are documented alongside their tests and suppression guidance, the catalogue becomes the natural place to discuss whether a rule is correctly defined, whether its severity should change, or whether a new rule is needed.

The catalogue is **generated automatically** from the codebase — it stays in sync with the actual validators and test suite at all times.

---

### 6 · Built-in Functions Registry

Architect ships with **300+ built-in functions** covering string manipulation, date handling, database access, and more. The Language Server maintains a registry of these functions — their names, parameter signatures, return types, and argument constraints.

This registry is what enables the function signature validator, hover cards for built-ins, and completions. Without it, the system could only validate user-defined functions; with it, the system enforces correct usage of the entire Architect standard library.

---

### 7 · Include Resolver

Architect programs are commonly split across multiple files using `INCLUDE` directives. The Include Resolver builds and traverses the **dependency graph** formed by these directives, enabling:

- Variable and function lookups that cross file boundaries
- Detection of circular include chains
- Correct scope resolution when the same symbol is defined in an included file

---

## Roadmap View

```mermaid
flowchart LR
    subgraph Today["Today"]
        IDE2["IDE Integration<br/>Real-time feedback while authoring"]
        Syntax2["Syntax Tests<br/>TDD validator coverage"]
        Catalogue2["Diagnostic Catalogue<br/>Reference and governance"]
        CLI2["Headless CLI<br/>core/ · vscode-extension/ · cli/<br/>Validators run without the IDE"]
    end

    subgraph Next["Next — Automated Gates"]
        CI2["CI/CD Pipeline Integration<br/>Validators run on every commit<br/>Publish to Azure Artifacts feed"]
        Hook2["Branch Policy<br/>Block non-compliant PRs at merge"]
    end

    subgraph Future["Future Possibilities"]
        Multi2["Multi-file Analysis<br/>Project-wide rule checks"]
        Metrics2["Quality Metrics<br/>Trend dashboards across the codebase"]
        Custom2["Custom Rule Profiles<br/>Team-specific severity configurations"]
    end

    Today --> Next --> Future
```

The validator engine is now decoupled from VS Code. The **next step** is publishing the CLI to an Azure Artifacts private feed and wiring it into a pipeline build policy on the Architect codebase repository — see [CICD_ARCHITECTURE.md](CICD_ARCHITECTURE.md) for the full integration plan.

---

## Summary

| Component | Purpose | Value |
|-----------|---------|-------|
| **Language Parser** | Deep structural understanding of Architect code | Foundation for all intelligence |
| **Validators (×15)** | Rule enforcement across type, naming, scope, patterns | Catch errors before they ship |
| **Syntax Tests** | TDD specs for validator behaviour | Trust and regression safety |
| **IDE Enhancements** | Real-time feedback, quick fixes, navigation | Faster, more confident authoring |
| **Diagnostic Catalogue** | Explanation and governance of every rule | Team alignment and discoverability |
| **Built-in Registry** | Signatures for 300+ Architect functions | Validates usage of the standard library |
| **Include Resolver** | Cross-file dependency and scope graph | Correctness across multi-file programs |
| **Headless CLI** | `acurity-validate` — runs validators without VS Code | Automated quality gates via CI/CD or Git hooks |
