@jhlagado/azm 0.1.0

package/README.md

@@ -0,0 +1,142 @@
+# AZM
+
+AZM is a Z80 assembler in the ASM80 tradition: plain assembly input, predictable
+object output, and modern safety tooling for projects that still want to see the
+machine.
+
+The project goal is a good assembler, not a high-level language. AZM keeps
+labels, directives, instructions, branches, data bytes, register effects, and
+generated metadata visible in source and artifacts.
+
+## Product boundary
+
+AZM keeps:
+
+- ASM80-style `.asm` / `.z80` source as the input baseline
+- `.asmi` external interface files for register-care contracts
+- textual `.include`
+- directive aliases for importing common assembler spellings
+- register-care analysis, compact AZMDoc comments, and `.asmi` external
+  contracts
+- AST-level `op` extensions
+- enums as constant namespaces
+- `.type` / `.union` layout metadata
+- compile-time layout constants such as `sizeof(...)`, `offset(...)`, scalar
+  layout sizes, and constant-only layout casts
+- assembler data directives including `.db`, `.dw`, `.ds`, `.cstr`, `.pstr`,
+  and `.istr`
+
+AZM `.asm` and `.z80` source rejects old ZAX high-level features such as
+modules/imports, `func`, formal arguments, locals, typed assignment/storage
+lowering, structured control, generated frames, typed storage blocks, and named
+section blocks. Those inherited paths are removal work, not product
+compatibility.
+
+## Install
+
+Requires Node.js 20+.
+
+```sh
+npm install -g @jhlagado/azm
+azm path/to/program.z80
+```
+
+From a checkout, use the local CLI after building:
+
+```sh
+npm ci
+npm run build
+npm run azm -- examples/hello.asm
+```
+
+Output files for each compiled source:
+
+| Extension  | Contents                  |
+| ---------- | ------------------------- |
+| `.hex`     | Intel HEX                 |
+| `.bin`     | Flat binary               |
+| `.lst`     | Byte dump plus symbols    |
+| `.z80`     | Plain Z80 source emission |
+| `.d8.json` | Debug80 map               |
+
+Small input example:
+
+```asm
+        ORG 0100H
+START:
+        LD A,42
+        RET
+```
+
+Compile a binary and listing:
+
+```sh
+azm --type bin --output build/start.bin start.asm
+```
+
+```text
+azm [options] <entry.asm|entry.z80>
+
+Options:
+  -o, --output <file>   Primary output path (must match --type extension)
+  -t, --type <type>     Primary output type: hex|bin (default: hex)
+  -n, --nolist          Suppress .lst
+      --nobin           Suppress .bin
+      --nohex           Suppress .hex
+      --nod8m           Suppress .d8.json
+      --asm80           Emit assembler-valid lowered source (.z80)
+      --case-style <m>  Case-style lint mode: off|upper|lower|consistent
+      --rc <m>            Register-care mode: off|audit|warn|error|strict
+      --reg-report       Emit .regcare.txt report
+      --reg-interface    Emit inferred register-care interface (.asmi)
+      --fix             Apply conservative register-care source fixes
+      --contracts       Update source AZM contract blocks in place
+      --accept-out <r:c> Promote inferred output candidate while annotating
+      --interface <file> Load register-care interface contracts
+      --reg-profile <p> Register-care profile: mon3
+      --aliases <file>  Load project directive alias JSON (repeatable)
+  -I, --include <dir>   Add include search path (repeatable)
+  -V, --version         Print version
+  -h, --help            Show help
+```
+
+## Programmatic API
+
+`@jhlagado/azm` exposes Node entry points for tools:
+
+- `@jhlagado/azm`
+- `@jhlagado/azm/tooling`
+- `@jhlagado/azm/compile`
+
+Minimal compile example:
+
+```ts
+import { compile, defaultFormatWriters } from '@jhlagado/azm/compile';
+
+const result = await compile(
+  '/abs/path/to/main.asm',
+  { outputType: 'hex' },
+  { formats: defaultFormatWriters },
+);
+
+console.log(result.diagnostics);
+```
+
+See [docs/reference/cli.md](docs/reference/cli.md) for the full CLI reference
+and [docs/reference/tooling-api.md](docs/reference/tooling-api.md) for the
+current API notes.
+
+## Verification
+
+Useful local verification lanes:
+
+```sh
+npm run build
+npm run test:azm:alpha
+npm run test:azm:corpus
+npm test
+```
+
+## License
+
+GPL-3.0-only. See [LICENSE](LICENSE).

package/dist/src/analysis.d.ts

@@ -0,0 +1,11 @@
+import type { Diagnostic } from './diagnosticTypes.js';
+import type { LoadedProgram } from './sourceLoader.js';
+import type { CompilerOptions } from './pipeline.js';
+import { type CompileEnv } from './semantics/env.js';
+export interface AnalyzeProgramOptions extends Pick<CompilerOptions, 'caseStyle' | 'requireMain'> {
+}
+export interface AnalyzeProgramResult {
+    diagnostics: Diagnostic[];
+    env?: CompileEnv;
+}
+export declare function analyzeLoadedProgram(loadedProgram: LoadedProgram, options?: AnalyzeProgramOptions): AnalyzeProgramResult;

package/dist/src/analysis.js

@@ -0,0 +1,41 @@
+import { hasErrors } from './compileShared.js';
+import { DiagnosticIds } from './diagnosticTypes.js';
+import { lintCaseStyle } from './lintCaseStyle.js';
+import { buildEnv } from './semantics/env.js';
+function hasMainEntryLabel(program) {
+    return program.files.some((sourceFile) => sourceFile.items.some((item) => item.kind === 'AsmLabel' && item.name.toLowerCase() === 'main'));
+}
+export function analyzeLoadedProgram(loadedProgram, options = {}) {
+    const diagnostics = [];
+    const { program, sourceTexts } = loadedProgram;
+    const hasProgramItems = program.files.some((sourceFile) => sourceFile.items.length > 0);
+    if (!hasProgramItems) {
+        diagnostics.push({
+            id: DiagnosticIds.SemanticsError,
+            severity: 'error',
+            message: 'Program contains no declarations or instruction streams.',
+            file: program.entryFile,
+            ...(program.span?.start
+                ? { line: program.span.start.line, column: program.span.start.column }
+                : {}),
+        });
+        return { diagnostics };
+    }
+    if ((options.requireMain ?? false) && !hasMainEntryLabel(program)) {
+        diagnostics.push({
+            id: DiagnosticIds.SemanticsError,
+            severity: 'error',
+            message: 'Program must define a "main" entry label.',
+            file: program.entryFile,
+            ...(program.span?.start
+                ? { line: program.span.start.line, column: program.span.start.column }
+                : {}),
+        });
+        return { diagnostics };
+    }
+    lintCaseStyle(program, sourceTexts, options.caseStyle ?? 'off', diagnostics);
+    const env = buildEnv(program, diagnostics);
+    if (hasErrors(diagnostics))
+        return { diagnostics };
+    return { diagnostics, env };
+}

package/dist/src/api-compile.d.ts

@@ -0,0 +1,8 @@
+export { compile } from './compile.js';
+export type { CaseStyleMode, CompileFn, CompileResult, CompilerOptions, PipelineDeps, } from './pipeline.js';
+export { defaultFormatWriters } from './formats/index.js';
+export type { Artifact, FormatWriters } from './formats/types.js';
+export type { Diagnostic, DiagnosticId, DiagnosticSeverity } from './diagnosticTypes.js';
+export { DiagnosticIds } from './diagnosticTypes.js';
+export type { DirectiveAliasProfile } from './frontend/directiveAliases.js';
+export type { RegisterCareMode } from './registerCare/types.js';

package/dist/src/api-compile.js

@@ -0,0 +1,3 @@
+export { compile } from './compile.js';
+export { defaultFormatWriters } from './formats/index.js';
+export { DiagnosticIds } from './diagnosticTypes.js';

package/dist/src/api-tooling.d.ts

@@ -0,0 +1,25 @@
+import type { Diagnostic } from './diagnosticTypes.js';
+import { type AnalyzeProgramOptions, type AnalyzeProgramResult } from './analysis.js';
+import { type LoadedProgram, type LoadProgramOptions } from './sourceLoader.js';
+export type { Diagnostic, DiagnosticId, DiagnosticSeverity } from './diagnosticTypes.js';
+export { DiagnosticIds } from './diagnosticTypes.js';
+export type { BaseNode, SourceFileNode, SourceItemNode, ProgramNode, SourcePosition, SourceSpan, } from './frontend/ast.js';
+export type { CompileEnv } from './semantics/env.js';
+export type { LoadedProgram, LoadProgramOptions, AnalyzeProgramOptions, AnalyzeProgramResult };
+export { analyzeRegisterCareForTools, codeActionForOutputCandidate, diagnosticForOutputCandidate, } from './registerCare/tooling.js';
+export type { AnalyzeRegisterCareForToolsOptions, AnalyzeRegisterCareForToolsResult, RegisterCareCandidateDiagnostic, RegisterCareCodeAction, RegisterCareTextEdit, } from './registerCare/tooling.js';
+export type { RegisterCareMode, RegisterCareOutputCandidate, RegisterCareUnit, } from './registerCare/types.js';
+export interface ToolingLoadProgramResult {
+    diagnostics: Diagnostic[];
+    loadedProgram?: LoadedProgram;
+}
+/**
+ * Layer A: expand textual includes and parse without emitting artifacts.
+ */
+export declare function loadProgram(options: LoadProgramOptions & {
+    entryFile: string;
+}): Promise<ToolingLoadProgramResult>;
+/**
+ * Layer B: run semantic checks without lowering or writing output artifacts.
+ */
+export declare function analyzeProgram(loadedProgram: LoadedProgram, options?: AnalyzeProgramOptions): AnalyzeProgramResult;

package/dist/src/api-tooling.js

@@ -0,0 +1,21 @@
+import { analyzeLoadedProgram, } from './analysis.js';
+import { loadProgram as loadProgramInternal, } from './sourceLoader.js';
+export { DiagnosticIds } from './diagnosticTypes.js';
+export { analyzeRegisterCareForTools, codeActionForOutputCandidate, diagnosticForOutputCandidate, } from './registerCare/tooling.js';
+/**
+ * Layer A: expand textual includes and parse without emitting artifacts.
+ */
+export async function loadProgram(options) {
+    const diagnostics = [];
+    const loadedProgram = await loadProgramInternal(options.entryFile, diagnostics, options);
+    return {
+        diagnostics,
+        ...(loadedProgram ? { loadedProgram } : {}),
+    };
+}
+/**
+ * Layer B: run semantic checks without lowering or writing output artifacts.
+ */
+export function analyzeProgram(loadedProgram, options = {}) {
+    return analyzeLoadedProgram(loadedProgram, options);
+}

package/dist/src/cli.d.ts

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+import type { CaseStyleMode } from './pipeline.js';
+import type { RegisterCareMode } from './registerCare/types.js';
+type CliExit = {
+    code: number;
+};
+type CliOptions = {
+    entryFile: string;
+    outputPath?: string;
+    outputType: 'hex' | 'bin';
+    emitBin: boolean;
+    emitHex: boolean;
+    emitD8m: boolean;
+    emitListing: boolean;
+    emitAsm80: boolean;
+    caseStyle: CaseStyleMode;
+    includeDirs: string[];
+    directiveAliasFiles: string[];
+    registerCare: RegisterCareMode;
+    emitRegisterReport: boolean;
+    emitRegisterInterface: boolean;
+    annotateRegisterContracts: boolean;
+    fixRegisterContracts: boolean;
+    acceptRegisterOutputCandidates: string[];
+    registerCareProfile?: 'mon3';
+    registerCareInterfaces: string[];
+};
+export declare function parseCliArgs(argv: string[]): CliOptions | CliExit;
+export declare function runCli(argv: string[]): Promise<number>;
+export {};