@jhlagado/azm 0.1.0

package/docs/reference/tooling-api.md

@@ -0,0 +1,248 @@
+# AZM Tooling API
+
+`@jhlagado/azm` exposes a stable programmatic surface for Node tooling. Use
+these imports instead of deep paths under `dist/src`.
+
+Install the package once, then import from the public entry points:
+
+```sh
+npm install @jhlagado/azm
+```
+
+## Stable entry points
+
+- `@jhlagado/azm`
+  Re-exports the stable public surface.
+- `@jhlagado/azm/tooling`
+  Layer A/B APIs for parsing, loading, diagnostics, spans, and semantics-only analysis.
+- `@jhlagado/azm/compile`
+  Layer C compile API and default format writers.
+
+## Debug80 Integration Path
+
+Debug80 should link through the public package entry points, not internal
+`dist/src/...` paths.
+
+Use this path when Debug80 needs editor-style diagnostics, symbols, or
+register-care information without writing files:
+
+```ts
+import { analyzeProgram, analyzeRegisterCareForTools, loadProgram } from '@jhlagado/azm/tooling';
+
+const loaded = await loadProgram({
+  entryFile: '/abs/path/to/main.asm',
+  includeDirs: ['/abs/path/to/includes'],
+});
+
+if (!loaded.loadedProgram) {
+  return loaded.diagnostics;
+}
+
+const analysis = analyzeProgram(loaded.loadedProgram, {
+  caseStyle: 'consistent',
+  requireMain: false,
+});
+
+const registerCare = analyzeRegisterCareForTools(loaded.loadedProgram, {
+  mode: 'audit',
+  profile: 'mon3',
+});
+```
+
+Use this path when Debug80 needs assembled bytes and debugger metadata:
+
+```ts
+import { compile, defaultFormatWriters } from '@jhlagado/azm/compile';
+
+const result = await compile(
+  '/abs/path/to/main.asm',
+  {
+    includeDirs: ['/abs/path/to/includes'],
+    outputType: 'hex',
+    emitBin: true,
+    emitHex: true,
+    emitD8m: true,
+    emitListing: true,
+    registerCare: 'audit',
+    registerCareInterfaces: ['/abs/path/to/mon3.asmi'],
+  },
+  { formats: defaultFormatWriters },
+);
+
+const diagnostics = result.diagnostics;
+const d8m = result.artifacts.find((artifact) => artifact.kind === 'd8m');
+const binary = result.artifacts.find((artifact) => artifact.kind === 'bin');
+```
+
+The integration contract is:
+
+- source entries are `.asm` or `.z80`
+- external register-care contracts are `.asmi`
+- include search paths are supplied explicitly with `includeDirs`
+- directive alias JSON files are supplied explicitly with `directiveAliasFiles`
+- `compile()` returns artifacts in memory; the CLI is only responsible for
+  writing those artifacts to disk
+- Debug80 should consume the `d8m` artifact for source/address metadata and the
+  `bin` or `hex` artifact for loadable bytes
+- diagnostics are data objects and should be displayed directly rather than
+  parsed from CLI text
+
+## Layer A: Load and Parse
+
+Use `loadProgram()` when you need the same AST, spans, and diagnostics that the compiler uses, but without lowering or writing artifacts.
+
+```ts
+import { loadProgram } from '@jhlagado/azm/tooling';
+
+const result = await loadProgram({
+  entryFile: '/abs/path/to/main.asm',
+  includeDirs: ['/abs/path/to/includes'],
+  preloadedText: 'ORG 0100H\\nSTART:\\n    RET\\n',
+});
+
+if (result.loadedProgram) {
+  console.log(result.loadedProgram.program.kind); // "Program"
+}
+
+for (const diagnostic of result.diagnostics) {
+  console.log(diagnostic.id, diagnostic.message);
+}
+```
+
+Notes:
+
+- `preloadedText` applies to the entry file only. This is intended for unsaved editor buffers.
+- `signal?: AbortSignal` is accepted for best-effort cancellation of stale editor work.
+- `parseEntryOnly` is not part of v1. Use `loadProgram()` and debounce at the caller when needed.
+
+## Layer B: Analyze Without Emitting
+
+Use `analyzeProgram()` after `loadProgram()` to run the current non-codegen semantic checks:
+
+- entry contract validation such as `requireMain`
+- case-style linting
+- environment building
+- instruction acceptance checks that do not require lowering
+
+```ts
+import { analyzeProgram, loadProgram } from '@jhlagado/azm/tooling';
+
+const loaded = await loadProgram({ entryFile: '/abs/path/to/main.asm' });
+if (!loaded.loadedProgram) {
+  throw new Error('Parse/load failed');
+}
+
+const analysis = analyzeProgram(loaded.loadedProgram, {
+  caseStyle: 'consistent',
+  requireMain: true,
+});
+
+console.log(analysis.diagnostics);
+```
+
+`analysis.env` is returned only when semantic analysis completes without errors.
+
+## Register-Care Tooling
+
+Use `analyzeRegisterCareForTools()` after `loadProgram()` when an editor, lint runner, or future LSP server needs register-care diagnostics without parsing report text. The function returns the same inferred output candidates used by the CLI report, plus ready-to-apply quick-fix metadata for confirming intent at the call site.
+
+```ts
+import { analyzeRegisterCareForTools, loadProgram } from '@jhlagado/azm/tooling';
+
+const loaded = await loadProgram({ entryFile: '/abs/path/to/main.z80' });
+if (!loaded.loadedProgram) {
+  throw new Error('Parse/load failed');
+}
+
+const registerCare = analyzeRegisterCareForTools(loaded.loadedProgram, {
+  mode: 'audit',
+  profile: 'mon3',
+});
+
+for (const diagnostic of registerCare.candidateDiagnostics) {
+  console.log(diagnostic.file, diagnostic.line, diagnostic.message);
+  console.log(diagnostic.autoFixable); // true when CLI --fix can safely add the hint
+  console.log(diagnostic.codeAction.edit.text); // "; expects out A\n"
+}
+```
+
+Candidate diagnostics use `kind: "register-care-output-candidate"` and `severity: "info"`.
+The `autoFixable` flag distinguishes direct continuation reads that `--fix` may
+confirm automatically from cases that need programmer review. Code actions are
+intentionally simple text insertions: insert the supplied newline-terminated
+`text` at column 1 of the supplied `line`, so the hint is inserted above the call
+instruction. This keeps CLI, editor light-bulbs, and future LSP integrations
+aligned around one inference source.
+
+## Layer C: Full Compile
+
+Use `compile()` when you want assembly plus output artifacts.
+
+```ts
+import { compile, defaultFormatWriters } from '@jhlagado/azm/compile';
+
+const result = await compile(
+  '/abs/path/to/main.asm',
+  { outputType: 'hex', emitAsm80: true },
+  { formats: defaultFormatWriters },
+);
+```
+
+The compiler accepts flat `.asm` / `.z80` source, retained AZM assembler
+features, and the same output writers used by the CLI. External register-care
+interfaces are `.asmi` metadata files, not compile entry files.
+
+Retained AZM features include the ASM80 baseline, compact AZMDoc `;!` comments,
+directive aliases, AST `op` declarations, enums, `.type` / `.union`, `sizeof`,
+`offset`, constant-only layout casts, and scalar type shorthand in `.ds` and
+`.field`.
+
+High-level ZAX constructs such as modules/imports, `func`, locals, formal args,
+typed assignment/storage lowering, named sections, structured control, and
+generated frames are outside this API contract for AZM source.
+
+## Public Types
+
+The public tooling surface includes:
+
+- `Diagnostic`, `DiagnosticIds`, severity/id types
+- `SourcePosition`, `SourceSpan`
+- `ProgramNode`, `SourceFileNode`, `SourceItemNode`
+- `LoadedProgram`
+- `CompileEnv`
+- `RegisterCareCandidateDiagnostic`, `RegisterCareCodeAction`, `RegisterCareOutputCandidate`
+
+In v1, the AST exported from `src/frontend/ast.ts` is part of the public contract. Additive fields are minor-version changes; breaking shape changes are major-version changes.
+
+## Syntax Highlighting Example
+
+Syntax colouring is an example consumer of the tooling API:
+
+1. Call `loadProgram()` with the file path and optional unsaved buffer text.
+2. Walk `ProgramNode` and inspect `node.kind` plus `node.span`.
+3. Map those spans to TextMate scopes or semantic token kinds in the editor.
+4. Fall back to regex/TextMate-only colouring if parsing fails or the editor needs a cheaper fast path.
+
+The same spans and node kinds also support outline views, hover preparation, diagnostics, and navigation features.
+
+## Migration From Deep Imports
+
+Replace unstable imports such as:
+
+```ts
+import { loadProgram } from '@jhlagado/azm/dist/src/sourceLoader.js';
+```
+
+with:
+
+```ts
+import { loadProgram } from '@jhlagado/azm/tooling';
+```
+
+Likewise, prefer `@jhlagado/azm/compile` over `@jhlagado/azm/dist/src/compile.js`.
+
+## Semver Policy
+
+- Patch: bug fixes that preserve the intent of exported APIs and types
+- Minor: additive exports, additive AST fields, new optional options
+- Major: breaking changes to exported types, AST node shapes, or public function behavior

package/package.json

@@ -0,0 +1,98 @@
+{
+  "name": "@jhlagado/azm",
+  "version": "0.1.0",
+  "description": "AZM assembler for the Z80 family (Node.js CLI)",
+  "license": "GPL-3.0-only",
+  "engines": {
+    "node": ">=20"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "import": "./dist/src/index.js"
+    },
+    "./compile": {
+      "types": "./dist/src/api-compile.d.ts",
+      "import": "./dist/src/api-compile.js"
+    },
+    "./tooling": {
+      "types": "./dist/src/api-tooling.d.ts",
+      "import": "./dist/src/api-tooling.js"
+    },
+    "./cli": {
+      "types": "./dist/src/cli.d.ts",
+      "import": "./dist/src/cli.js",
+      "default": "./dist/src/cli.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "types": "dist/src/index.d.ts",
+  "bin": {
+    "azm": "dist/src/cli.js"
+  },
+  "files": [
+    "dist/src",
+    "docs/reference/cli.md",
+    "docs/reference/tooling-api.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jhlagado/AZM.git"
+  },
+  "bugs": {
+    "url": "https://github.com/jhlagado/AZM/issues"
+  },
+  "homepage": "https://github.com/jhlagado/AZM#readme",
+  "keywords": [
+    "assembler",
+    "z80",
+    "retro",
+    "8-bit",
+    "azm"
+  ],
+  "scripts": {
+    "clean": "rm -rf dist",
+    "build": "npm run clean && tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "lint": "eslint \"src/**/*.ts\" \"test/**/*.ts\"",
+    "lint:fix": "eslint \"src/**/*.ts\" \"test/**/*.ts\" --fix",
+    "fallow": "fallow",
+    "fallow:dead-code": "fallow dead-code",
+    "fallow:dupes": "fallow dupes",
+    "fallow:health": "fallow health",
+    "fallow:audit": "fallow audit --base main",
+    "pretest": "mkdir -p coverage/.tmp",
+    "test": "npm run test:azm:alpha",
+    "test:all": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "test:ci:slow-reliability": "vitest run --no-file-parallelism --maxWorkers=1 --minWorkers=1 --testTimeout=20000 --hookTimeout=300000 --passWithNoTests 'test/cli_*.test.ts' 'test/cli/**/*.test.ts'",
+    "test:azm:alpha": "node scripts/dev/run-azm-alpha-guardrails.mjs",
+    "test:azm:corpus": "node scripts/dev/run-azm-corpus-guardrails.mjs",
+    "test:package": "node scripts/dev/smoke-npm-package.mjs",
+    "test:asm80:baseline": "node scripts/dev/run-asm80-baseline.mjs",
+    "test:asm80:tetro": "AZM_RUN_TETRO_ACCEPTANCE=1 vitest run test/asm80/tetro_acceptance.test.ts",
+    "test:watch": "vitest",
+    "format": "prettier -w .",
+    "format:check": "prettier -c .",
+    "check:source-file-sizes": "node scripts/check-source-file-sizes.mjs",
+    "check:source-file-sizes:enforce": "node scripts/check-source-file-sizes.mjs --enforce-hard-cap",
+    "prepack": "npm run build",
+    "prepublishOnly": "npm run build",
+    "azm": "npm run build && node dist/src/cli.js"
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.1",
+    "@vitest/coverage-v8": "^2.1.9",
+    "eslint": "^10.1.0",
+    "fallow": "^2.54.2",
+    "globals": "^17.4.0",
+    "prettier": "^3.5.0",
+    "typescript": "^5.7.3",
+    "typescript-eslint": "^8.57.2",
+    "vitest": "^2.1.9"
+  }
+}