<!-- .slide: class="center" -->

<div class="eyebrow">Internal Tooling Initiative</div>

# Architect Language Tools

Enabling quality automation, developer assistance, and pipeline enforcement for Acurity Architect

<div class="stats">
  <div><div class="stat-num">15</div><div class="stat-lbl">Validation rule engines</div></div>
  <div><div class="stat-num">300+</div><div class="stat-lbl">Built-in function signatures</div></div>
  <div><div class="stat-num">90+</div><div class="stat-lbl">Automated test scenarios</div></div>
</div>

---

<!-- .slide: class="center divider" data-background-color="#1e40af" -->

<div class="divider-num">Section 1 of 3</div>

# The Project

Problem · Solution · Outcomes · Roadmap

---

## The Problem — Architect's limited tooling ecosystem

- **Coding Standards**
  - Efforts have been made to manually enforce .
  - Automation/tooling to support this is very limited.
- **Legacy Codebase**
  - Standards haven't always been followed.
  - We need to support workflows that recognises this.
  - A '1 line change' shouldn't result in the author being responsible for all prior tech debt.
- **Lack of AI Readiness**
  - AI has seen limited usage within the Acurity Development community.
  - Partly this is due to lack of tooling that is "Acurity Architect aware".


> What might a solution look like?

---

## Summary — What does the solution look like?

| Component            | What it does                                                     | Value delivered                                |
| -------------------- | ---------------------------------------------------------------- | ---------------------------------------------- |
| Language Parser      | Foundational item for system to understand Architect code syntax |                                                |
| Syntax Test Suite    | 90+ TDD specs. Intentionally written as Architect code. Defines coding standards. | Trust, regression safety, living specification. Collaborative oversight.  |
| Diagnostic Catalogue | Reference guide that explains every rule, severity, and suppression path. Provides traceability to tests.  | Team alignment and governance. |
| Validators (×15)     | Rules across type, scope, naming, patterns, docs                 | Catch errors + standards violations before they ship. |
| Headless CLI         | Pipeline validation — JSON report, exit codes, surface filtering | Automated quality gate. IDE agnostic.          |
| IDE Extension        | Real-time feedback, hover, quick fixes, navigation               | Faster, more confident authoring               |
| AI-assisted workflow | Spec generation and validator scaffolding from annotated code    | Accelerated rule development                   |

---

Proposed Architecture

<!-- Tooling sits outside of the existing Architect repo. -->
<!-- Interaction with the existing Architect repo is via CI/CD, w/ pinned versioning. -->

<img src="architecture.drawio.svg" style="display: block; max-height: 600px; width: auto; margin: 0 auto;" />

---

## The Solution — A language-aware tooling ecosystem

| Component             | What it does                                                                                                                           |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| **IDE Extension**     | Real-time error highlighting, function signature guidance, quick-fix suggestions, and code navigation — in VS Code as developers write |
| **Validation Engine** | 15 independent validators covering type safety, naming conventions, scope, patterns, and documentation                                 |
| **Headless CLI**      | The same engine packaged as a command-line tool — runs in any CI/CD pipeline without VS Code, producing a structured JSON report       |

> **One shared engine, two surfaces.** The IDE and the pipeline enforce identical rules. Developers cannot pass CI/CD with code their IDE told them was correct.

---

## Business Outcomes

- **Errors caught earlier** — defects flagged at the moment of authoring cost a fraction of what they cost in testing or production

- **Consistent standards** — standards are enforced by tooling, not individual reviewers; code review shifts from catching style violations to reviewing intent

- **Automated quality gates** — the CLI integrates with Azure DevOps branch policies; non-compliant code cannot merge to main regardless of which team authored it

- **Faster onboarding** — new team members receive guidance directly in the editor: functions available, argument signatures, conventions — without needing to ask a colleague

---

## Roadmap

| Phase                               | Status     | Scope                                                                                        |
| ----------------------------------- | ---------- | -------------------------------------------------------------------------------------------- |
| IDE integration & validation engine | ✅ Done    | Real-time feedback in VS Code. 15 validators. 90+ test scenarios.                            |
| Headless CLI                        | ✅ Done    | Same engine without VS Code. JSON report. Exit-code pipeline integration. Surface filtering. |
| Package & publish                   | 🔜 Next   | Formal npm packages on Azure Artifacts. Pipelines install via `npm install`.                 |
| Pipeline integration                | 🔜 Next   | Azure Pipelines YAML in the Architect codebase repo. Validation on every commit and PR.      |
| Branch policy enforcement           | 🔜 Next   | Non-compliant PRs blocked from merging. Standards become a hard gate, not a guideline.       |
| Governance & distribution           | 🔮 Future | Private VSIX distribution. Marketplace restriction policy. Controlled rollout.               |

---

<!-- .slide: class="center divider" data-background-color="#1e40af" -->

<div class="divider-num">Section 2 of 3</div>

# Developer Experience

IDE features · Test suite · TDD workflow · AI assistance

---

## What do we want our tools to do?

- **Foster good coding styles** — guide conventions as you write, not after review
- **Help us avoid writing bad code** — catch mistakes at the moment they're made, not at runtime
- **Let us see bugs faster** — errors surfaced immediately in the editor, not in test or production
- **Let us write code faster** — function signatures, completions, and navigation on hand without leaving the IDE
- **Help us better understand what our code is doing** — hover cards, type information, and cross-file scope at a glance
- **Help us better collaborate as a team** — shared, enforced standards mean everyone's code looks and behaves consistently

---

## Coding standards — what and why

<div class="cols">
<div>

Good coding standards define how code should be written, not just what it should do:

- **Readability** — code is read far more often than it is written; consistent style reduces cognitive load
- **Maintainability** — predictable conventions make it easier to modify, extend, and debug code safely
- **Onboarding** — new team members orient faster when the codebase follows consistent patterns
- **Quality** — many classes of bug are prevented by convention: naming rules, structural rules, scope rules

</div>
<div>

> For Architect specifically, the case is stronger still. There is no compiler, no external linter, and no community tooling to fall back on. The language's correctness guarantees are entirely in the hands of the team writing it.

<blockquote class="callout-red">
Without enforced standards, every developer effectively defines their own dialect. The cost of that inconsistency compounds over time.
</blockquote>

</div>
</div>

---

## The legacy codebase challenge

<div class="cols">
<div>

Most real-world Architect codebases were written before formal standards existed. Retrofitting standards creates a specific problem:

- A large volume of pre-existing violations makes new standards feel arbitrary and unfair
- Developers making small, legitimate changes find themselves flagged for issues they didn't introduce
- **A one-line change shouldn't make you responsible for an entire report**
- If the tooling is seen as punishing contributors for inherited debt, adoption collapses

</div>
<div>

> **The answer is not lower standards — it is smarter enforcement.**

<blockquote class="callout-green">
<strong>Diff-aware validation</strong> — restrict reported diagnostics to lines changed in the current branch. The author is accountable for what they wrote, not for what was already there.
</blockquote>

<blockquote class="callout-green">
<strong>Incremental improvement</strong> — new code meets the standard from day one; existing violations are addressed deliberately, on their own schedule.
</blockquote>

</div>
</div>

---

## The politics of standards

<div class="cols">
<div>

Introducing enforced coding standards into an existing team is rarely purely technical. Some dynamics to anticipate:

- **Standards feel personal** — it can feel like being told you've been doing it wrong for years
- **Who decides?** — standards without legitimacy don't stick; the process matters as much as the rules
- **Selective enforcement** — if standards apply to some developers but not others, trust erodes quickly
- **The reviewer dynamic** — enforcement person-to-person is subject to relationship, mood, and consistency

</div>
<div>

> **A tool is a neutral arbiter.** The linter flagged it — not your colleague. This depersonalises the conversation and makes it easier to have.

<blockquote class="callout-green">
<strong>Suppression is a safety valve, not a loophole.</strong> The ability to <code>// @rule-ignore</code> a specific line, with a visible record in the code, allows reasoned exceptions without undermining the standard.
</blockquote>

</div>
</div>

---

## A collaborative standard, not an imposed one

<div class="cols">
<div>

> As a relative newcomer to the team, I want to be clear about intent: this is not about arriving with a ruleset and enforcing it. It is about introducing a model that allows the team to **build, extend, discuss, and adapt the standard together** — over time.

**The key enabler: the rules are written in Architect**

The standard is not hidden inside tooling code that only a JavaScript developer can read. Every rule is defined by a syntax test — a plain `.TXT` file written in Architect.

</div>
<div>

- Any developer who can read Architect can read what the standard says
- Any developer can propose a change — by writing or modifying a test
- Disagreements about a rule become conversations about a concrete code example, not abstract debates about style
- The test suite is the living record of what the team has agreed, and why

<blockquote class="callout-green">
The standard belongs to the team. The tooling just makes it enforceable.
</blockquote>

</div>
</div>

---

## Limitations of current approaches

- **Manual code review** — the primary mechanism today; inconsistent by nature: what gets flagged depends on the reviewer, the day, and the relationship

- **Grep and text search** — no understanding of the language; cannot reason about scope, types, block structure, or cross-file dependencies

- **Documentation** — standards written in a document are invisible at the point where they matter most: when the code is being written

- **Individual IDE plugins** — where they exist at all, configured per-developer, inconsistently applied, not shared

- **Convention by example** — learning standards by reading existing code works until the existing code itself doesn't follow the standard

> The gap is not awareness — most developers know roughly what good code looks like. The gap is **enforcement at the right moment**, applied **consistently**, by something **the whole team shares**.

---

## Disparate IDE usage

<div class="cols">
<div>

The team uses a range of editors — Notepad++, VS Code, JEdit, and the Acurity Code Editor. This creates an immediate challenge:

- Real-time validation, hover cards, and quick fixes all require deep IDE integration
- Today that integration exists for **VS Code only**
- Tooling that only benefits VS Code users risks being seen as favouring one part of the team
- Standards enforcement that depends on IDE choice is, by definition, inconsistent

> The goal is consistent quality across the whole team — not just those using a particular editor.

</div>
<div>

**What about developers not using VS Code?**

<blockquote class="callout-green">
<strong>Today — the CLI as a shared baseline.</strong> Any developer, regardless of editor, benefits from pipeline validation on every push and PR, and can run <code>acurity-validate --folder .</code> as a local pre-flight check.
</blockquote>

<blockquote class="callout-blue">
<strong>Future — Language Server Protocol (LSP).</strong> The validation engine is already decoupled from VS Code. Exposing it as an LSP server would make it connectable to any LSP-capable editor.
</blockquote>

> The honest near-term position: non-VS Code users benefit from pipeline enforcement and the CLI. Broader IDE support is a credible future direction, not a current commitment.

</div>
</div>

---

## IDE: Errors highlighted as you write

<div class="cols">
<div>

```text
VAR STRING lsCustomerName
VAR LONG   llOrderCount

// Undefined variable — red squiggle
SET lsCustomerNane = "Smith"
//  ^^^^^^^^^^^^^^ not defined [ACU-VAR-001]

// Wrong argument count — red squiggle
SET llOrderCount = LEFT("hello", 3, "extra")
//                 ^^^^ expects 2 args [ACU-FNC-006]

// Naming convention — yellow squiggle
VAR LONG sOrderCount
//       ^^^^^^^^^^^^ prefix suggests STRING [ACU-NMG-003]
```

</div>
<div>

Every diagnostic includes a **stable rule ID** (e.g. `ACU-VAR-001`). Look up any ID in the Diagnostic Catalogue to understand what the rule means and whether it can be suppressed.

> Diagnostics are categorised by severity: **error** (red), **warning** (yellow), **information** (blue).

> Inline suppression: `// @rule-ignore ACU-NMG-003` on the relevant line. Suppressions are deliberate and visible in code review.

</div>
</div>

---

## IDE: Hover cards, quick fixes, and navigation

<div class="cols">
<div>

**Hover over any built-in function**
See the full signature — parameter names, types, return type — inline, without leaving the editor. Covers 300+ Architect built-ins.

**Hover over a variable**
See its declared type and declaration line. Works across `INCLUDE` chains.

**Quick fixes** (`Ctrl+.`)
One-click corrections for keyword capitalisation, naming prefix suggestions, and suppression comment insertion. Nothing is changed without explicit developer action.

</div>
<div>

**Go to Definition** (`F12`)
Jump to the declaration of any variable, function, or macro — including those in included files.

**Completions**
As you type a function or macro name, completions suggest matching candidates with parameter signatures.

**File templates**
New report and include file scaffolds with correct structure and Robodoc comment blocks pre-populated.

> **No surprises at merge:** standards violations are visible during authoring, not revealed for the first time when a PR fails the build.

</div>
</div>

---

## The syntax-test suite — how validators are specified

<div class="cols">
<div>

Every validator rule is defined and verified by a file pair in `test/syntax-tests/`:

```text
test/syntax-tests/
  block-structure/
    0001.TXT             ← Architect source (the input)
    0001.test-spec.json  ← what must be produced
  code-actions/
    0001.TXT             ← code before fix
    0001.FIXED.TXT       ← expected result after fix
    0001.test-spec.json
  included-files/
    0001.TXT             ← entry point
    0001.INCLUDE1.TXT    ← included file
    0001.test-spec.json
```

</div>
<div>

The `.TXT` file is **real Architect code** — readable by anyone familiar with the language. It documents the scenario in the language itself.

> Tests are the **living specification** for every validator. They define what the rule must catch, what it must not catch, and the exact diagnostic output — line, severity, and parameters.

> Currently **90+ scenarios** across 20+ categories. The runner exits non-zero on any failure — suitable as a CI/CD check in its own right.

</div>
</div>

---

## TDD workflow — write the test first

<div class="cols">
<div>

1. **Write `0001.TXT`** — Architect code that demonstrates the scenario. Make it readable as documentation.
2. **Write `0001.test-spec.json`** — declare what diagnostics the validator _should_ produce, with exact IDs, lines, and parameters.
3. **Run `npm run test:syntax`** — the test fails because the validator doesn't exist yet. This is correct and expected.
4. **Implement the validator** in `core/src/validators/` until the test passes.
5. **Add `unexpected-messages`** — assert which diagnostics must _never_ appear, guarding against false positives.

</div>
<div>

`block-structure/0001.TXT`:
```text
// Line 4: Unexpected ENDIF without opening IF
ENDIF

// Valid IF block — no diagnostic expected
IF zTest = "hello"
    >> Output
ENDIF

// Line 12: Unexpected ENDDO
ENDDO
```

`0001.test-spec.json`:
```json
{
  "expected-messages": [
    {
      "id": "ACU-BLK-001",
      "line": 4,
      "severity": "error",
      "params": { "closeKeyword": "ENDIF" }
    }
  ]
}
```

</div>
</div>

---

## AI assistance — generating test specifications

<div class="cols">
<div>

The spec format is structured JSON with exact IDs, line numbers, and parameter assertions — highly suitable for AI generation.

Given a **well-annotated Architect code snippet**, an AI assistant can:

- Identify which diagnostic rules should fire at which lines
- Generate the complete `expected-messages` array with correct IDs and params
- Suggest `unexpected-messages` for adjacent rules that should _not_ fire
- Write the `test-name` and `description` fields

<blockquote class="callout-purple">
<strong>The developer's role:</strong> annotate the snippet with intent comments, review the generated spec for correctness, and commit the pair.
</blockquote>

</div>
<div>

Developer annotates the snippet:

```text
VAR STRING lsName

// EXPECT: ACU-VAR-001 on next line
// (lsNme is not defined)
SET lsResult = lsNme

// EXPECT: ACU-FNC-006 on next line
// (LEFT takes 2 args, not 3)
SET x = LEFT("a", 1, "b")
```

The AI reads the annotations alongside the diagnostic catalogue and generates the complete `.test-spec.json` — a task that would otherwise take 10–15 minutes of manual spec-writing.

</div>
</div>

---

## AI assistance — scaffolding new validators

<div class="cols">
<div>

Validators follow a **consistent structural pattern**: receive parser output, traverse specific constructs, emit diagnostics via the factory. This regularity makes them well-suited to AI scaffolding.

Given:
- A failing test spec (the desired behaviour)
- The relevant diagnostic catalogue entries
- An existing similar validator as a template
- The parser output model

…an AI can draft the initial validator implementation. The test suite provides immediate, objective verification.

</div>
<div>

**AI is most effective for:**

**Initial scaffolding** — file structure, import patterns, the traversal loop. AI produces a correct shell; the developer fills in the rule logic.

**Edge case generation** — given a passing test, AI can suggest additional fixtures and `unexpected-messages` scenarios that test the boundaries of the rule.

<blockquote class="callout-purple">
<strong>The TDD contract:</strong> the test spec defines what "correct" means. The AI's draft is verified by the test runner — not by trust. The developer reviews, adjusts edge cases, and merges when green.
</blockquote>

</div>
</div>

---

<!-- .slide: class="center divider" data-background-color="#1e40af" -->

<div class="divider-num">Section 3 of 3</div>

# Trust & Security

What it is · Distribution controls · Agent permissions · Supply chain

---

## A static analyser — what it can and cannot do

<div class="cols">
<div>

The tooling is a **static code analyser** for Architect source files — the same class of tool as ESLint for JavaScript. It reads text and reports problems. It does not run the code.

Two components:
- **VS Code extension** — runs on the developer's workstation
- **Headless CLI** — runs in Azure Pipelines build agents, not on production servers

<blockquote class="callout-amber">
The closest analogy: a spell-checker for code. It reads the document and reports problems. It does not run the document.
</blockquote>

</div>
<div>

<blockquote class="callout-green">
<strong>Cannot execute Architect code.</strong> The engine tokenises text. It never invokes the Architect runtime.
</blockquote>

<blockquote class="callout-green">
<strong>Cannot connect to any database or system.</strong> No network calls, no database connections, no API calls at any point.
</blockquote>

<blockquote class="callout-green">
<strong>Cannot modify source files.</strong> Output is a read-only JSON report. Quick fixes require explicit developer action.
</blockquote>

<blockquote class="callout-green">
<strong>No telemetry or outbound communication.</strong> No update checker, no usage tracking, no external calls of any kind.
</blockquote>

</div>
</div>

---

## Distribution controls and agent permissions

<div class="cols">
<div>

**VS Code Extension**

- **Private VSIX — not the public Marketplace.** Distributed via an internal channel. Only IT-provisioned installs are possible.
- **Marketplace allowlist** (Azure AD + Intune) — prevents bypass via the public Marketplace.
- **Internal source** — every release is auditable before the VSIX is distributed.
- **VS Code Restricted Mode** — workspace trust enforceable via Group Policy.

</div>
<div>

**Pipeline agent permissions**

| Resource                    | Access   |
| --------------------------- | -------- |
| Source checkout             | ✅ Read  |
| Build staging dir           | ✅ Write |
| Azure Artifacts feed        | ✅ Read  |
| Production runtime          | ❌ None  |
| Production database         | ❌ None  |
| File shares / UNC           | ❌ None  |
| Internet (beyond Artifacts) | ❌ None  |

</div>
</div>

---

## Supply chain and dependency controls

- **Zero runtime dependencies** — the validation engine uses only Node.js built-ins and the VS Code extension API. No npm supply-chain attack surface from third-party transitive dependencies.

- **Private Azure Artifacts feed** — packages are published to an organisational feed. No package is downloaded from the public npm registry at pipeline runtime.

- **Exact version pinning** — all package references use exact versions, not semver ranges. No version is automatically promoted without a deliberate, reviewed change.

- **Internal source — no external contributors** — no open-source contributors, no PRs from unknown parties, no automatic dependency update bots.

> **These are not policy constraints — they are architectural ones.** The code does not contain network calls, database drivers, or file-write logic outside the explicit report output.

