For Developers

# Architect Language Tools

IDE assistance, real-time validation, and automated quality gates
for Architect scripting

This is the developer-focused version of the pitch. Focus on the "what do I get" angle.
The Status Quo

## Writing Architect without tooling

#### What you face today

- No error highlighting — typos and undefined variables are invisible until runtime
- No function signature guidance — argument counts and types must be looked up manually
- No cross-file awareness — `INCLUDE` chains are opaque
- Standards inconsistencies flagged in code review — slowing down merges
- Bugs that are trivial to detect statically reaching test or production

#### With the language tools

- Errors underlined in red as you type — before the file is saved
- Hover over any function to see its signature, parameters, and return type
- Go-to-definition navigates across include files instantly
- Standards violations caught automatically — code review focuses on logic
- Quick-fix suggestions for common errors — one click to resolve

Let the contrast speak for itself. The right column should feel like obvious improvements, not magic.
Feature: Real-time Validation

## Errors highlighted as you write

VAR STRING lsCustomerName
VAR LONG llOrderCount
// Undefined variable — red squiggle
SET lsCustomerNane = "Smith"
▲ lsCustomerNane is not defined [ACU-VAR-001]
// Wrong argument count — red squiggle
SET llOrderCount = LEFT("hello", 3, "extra")
▲ LEFT expects 2 arguments, got 3 [ACU-FNC-006]
// Naming convention — yellow squiggle
VAR LONG sOrderCount
▲ Prefix suggests STRING but declared LONG [ACU-NMG-003]

Every diagnostic includes a stable rule ID (e.g. `ACU-VAR-001`). You can look up any ID in the Diagnostic Catalogue to understand:

- What the rule means and why it exists
- Example code that triggers and clears it
- Whether it can be suppressed with `// @rule-ignore`

Diagnostics are categorised by severity: error (red), warning (yellow), information (blue). Errors should always be resolved; warnings indicate convention drift.

The code example is illustrative — the actual squiggle rendering is done by VS Code. The key point is that the rule ID makes it look-up-able, not just a cryptic message.
Feature: Hover Cards

## Function signatures and rule explanations on hover

#### Hover over a built-in function

See the full signature: parameter names, types, return type, and a brief description. No more counting commas in documentation.

#### Hover over a variable

See its declared type, the line it was declared on, and whether it has been set. Cross-file includes are resolved transparently.

#### Hover over a squiggly underline

See the rule ID, the diagnostic message, and a brief explanation of what the rule checks — inline, without leaving the editor.

// Hover over LEFT:
SET lsResult = LEFT(lsInput, 5)
LEFT ( string , length: LONG ) → STRING
Returns the leftmost length characters of string.
Hover cards reduce the context-switching cost of looking things up in documentation or asking colleagues.
Feature: Quick Fixes

## One-click corrections for common errors

Many diagnostic categories have an automated fix. Click the lightbulb (or press `Ctrl+.`) on a highlighted issue to apply it instantly.

- Keyword or function name capitalisation — corrected to the exact expected casing
- Missing suppression comment — inserts the correct `// @rule-ignore ACU-XXX-NNN` format
- Incorrect variable prefix — suggests the correctly-prefixed name

Quick fixes only exist where the correction is unambiguous. The tooling never modifies your code without your explicit action.

// Before
if llCount > 0
// After quick fix: "Capitalize keyword"
IF llCount > 0
// Suppressing a known acceptable case
// Quick fix: "Suppress ACU-NMG-002 on this line"
VAR STRING lsLegacyName // @rule-ignore ACU-NMG-002
Quick fixes are particularly valuable for the capitalisation rules — these are tedious to fix manually and trivial to fix automatically.
Feature: Navigation & Completions

## Navigate and author with confidence

#### Go to Definition (`F12`)

Jump to the declaration of any variable, function, or macro — including those defined in included files. The include graph is resolved automatically.

#### Completions

As you type a macro name or function call, completions suggest matching candidates with their parameter signatures. Tab to accept.

#### File Templates

New Architect report and include file scaffolds — correct structure and Robodoc comment blocks pre-populated, ready to fill in.

Navigation is especially valuable in large codebases with deep include chains, where manually tracing a symbol back to its declaration is time-consuming.
Feature: Pipeline Consistency

## The same rules, everywhere

You write code
VS Code IDE
→
IDE squiggles
Instant feedback
→
Commit & push
→
Pipeline validates
Same engine, same rules
→
PR review
→
Merge

No surprises: if the IDE shows no errors, the pipeline will not fail on the same errors. The validation engine is shared — not two separate implementations.

Surface filtering: the pipeline can be configured to only report correctness errors (not style warnings), so CI/CD fails fast on real bugs without noise from convention hints.

The --surface flag (just implemented) is what enables the pipeline/IDE split. Mention this if relevant to the audience.
Getting Started

## Up and running in minutes

- 1
  Install the VS Code extension — distributed as a `.vsix` file via your internal tools channel. Install with Extensions → Install from VSIX.
- 2
  Open your Architect codebase folder — the extension activates automatically for `.txt` files in the workspace. No configuration required to start.
- 3
  Open any Architect file — diagnostics appear immediately. Hover over any underlined item, or press `Ctrl+.` to see available quick fixes.
- 4
  Configure severity thresholds (optional) — VS Code settings let you adjust which rules are errors vs. warnings for your project. A standards profile can be selected (default, legacy-compatible, strict-modern).

Keep this slide brief. The install is genuinely simple — resist the urge to over-explain it.
Summary

## What you get

#### Catch errors instantly

Undefined variables, wrong argument counts, type mismatches — flagged as you type, not at runtime.

#### Write with guidance

Hover cards, completions, and go-to-definition across include files. 300+ built-in signatures at your fingertips.

#### Fix with one click

Quick fixes for capitalisation, suppression comments, and naming corrections. No manual editing of trivial issues.

#### Standards on autopilot

Conventions are enforced automatically. Code review focuses on logic and intent, not style.

#### Consistent with CI/CD

The IDE and the pipeline share the same engine. No surprises when your code hits the build.

#### TDD-tested rules

Every validator is covered by automated syntax tests. When a rule changes, the test suite catches it.

Leave this up during questions.