# Architect Language Tools

A language server, IDE extension, and CLI validator for the **Architect** scripting language.

## Repo topology

This repository has two tiers:

- **Product layer** — `architect-language-tools/` — the adoptable artefact. Clean, stable,
  suitable for handover to the organisation. No AI-specific scaffolding inside it.
- **Experimental layer** — everything else (`ai-workspace/`, `planning/`, `CLAUDE.md`,
  `.claude/`) — skunkworks coordination tooling for the single developer building this.
  Not part of the product.

All source lives under `architect-language-tools/`.

> **Trademark note:** "Acurity" is a potentially proprietary term — treat it as internal-only
> until formal sign-off. Avoid using it in public-facing artefact names (npm packages, VSIX
> display names, pipeline badges).

---

## Tech Stack

- **Language:** JavaScript (Node.js 20, ES Modules (`import`/`export`))
- **IDE integration:** VS Code Extension API
- **Test runner:** Custom syntax-test harness (plain Node)
- **CI/CD:** Azure DevOps (primary); Bitbucket Pipelines (legacy reference)
- **Package management:** npm (no runtime dependencies beyond VS Code itself — keep it that way)

---

## Workspaces

| Folder | Purpose | Read before working here |
|---|---|---|
| `architect-language-tools/core/` | Parser, validators, registries — pure Node, no VS Code dependency | `core/DEVELOPMENT.md` |
| `architect-language-tools/vscode-extension/` | VS Code host: providers, commands, activation | `vscode-extension/DEVELOPMENT.md` |
| `architect-language-tools/cli/` | Headless CLI validator + VS Code shim | `cli/DEVELOPMENT.md` |
| `architect-language-tools/test/` | Syntax-test suite (TDD specs in Architect code) | `test/DEVELOPMENT.md` |
| `architect-language-tools/dev-docs/` | Language spec and diagnostics reference (product docs only) | — |
| `ai-workspace/` | Stable reference material — strategy docs, feature guides, raw data | `ai-workspace/DEVELOPMENT.md` |
| `planning/` | Active work-in-progress — decisions being made, specs for upcoming features | `planning/DEVELOPMENT.md` |

---

## Routing

| Task | Go to | Read |
|---|---|---|
| Add or modify a validator rule | `core/src/validators/` | `core/DEVELOPMENT.md` |
| Add a built-in function / constant | `core/src/builtins/` | `core/DEVELOPMENT.md` |
| Add an IDE feature (hover, completion, quick fix) | `vscode-extension/src/` | `vscode-extension/DEVELOPMENT.md` |
| Modify CLI flags or report output | `cli/` | `cli/DEVELOPMENT.md` |
| Write a new syntax test | `test/syntax-tests/` | `test/DEVELOPMENT.md` |
| Update stable reference or strategy docs | `ai-workspace/docs/` | — |
| Spec or plan an upcoming feature / decision | `planning/specs/` or `planning/decisions/` | `planning/DEVELOPMENT.md` |
| Diagnose a specific rule | `architect-language-tools/dev-docs/DIAGNOSTICS_COMPREHENSIVE_REFERENCE.md` | — |
| Reference the language specification | `architect-language-tools/dev-docs/acurity_architect_language_specification.md` | — |

---

## Graduation rule

When a `planning/` item concludes:
- **Decision made / feature shipped** → promote to `ai-workspace/docs/`, delete from `planning/`
- **Abandoned** → delete, do not promote
- **Still in progress** → leave in `planning/` until all phases complete

---

## Non-Negotiable Rules

1. **`core/` must never `import` from `vscode`** — this is enforced structurally; violations undo the CI/CD decoupling.
2. **No new `dependencies` in `package.json` without explicit review** — zero runtime deps is a security asset.
3. **Every new validator rule needs a syntax test** — write the test first (TDD).
4. **Stable diagnostic IDs** — format is `ACU-XXX-NNN` (e.g. `ACU-FNC-003`). Never renumber existing IDs.
5. **Plain Node only** — no bundlers, no transpilers, no TypeScript. Maximises readability for non-JS reviewers.
6. **ES Modules throughout** — all `.js` files use `import`/`export`. The Jest config is `jest.config.cjs` (CJS required because `"type": "module"` is set). Tests run via `node --experimental-vm-modules`. When a test needs to mock a module, use `jest.unstable_mockModule()` with `await import()`, not `jest.mock()`.

## Bash Command Style
Never chain commands with "&&" or ";" operators.
Run them as separate bash calls instead.
When running git commands, make use of the "-C" parameter to avoid "&&" or ";".
Also note that "cd" commands are often unnecessary.