psyq-asm 0.0.1

package/CHANGELOG.md

@@ -0,0 +1,65 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses
+[Semantic Versioning](https://semver.org/).
+
+Fidelity changes, which alter the words `assemble` emits for some input without
+changing the API, are listed under **Fidelity**, separately from API changes.
+A fidelity fix is not a breaking change even when it changes output.
+
+## [Unreleased]
+
+### Added
+
+- `assemble(source, options)`: PsyQ 4.4 `cc1psx` output to the words ASPSX 2.81
+  produces, with sections, relocations carrying field masks, symbols, function
+  ranges, small-data classification, and provenance for every word. Input
+  problems are diagnostics; only caller mistakes throw.
+- `decode`, `encode`, and `format`: one instruction table covering the MIPS I
+  integer set, coprocessor 0 and GTE register moves, `lwc2`/`swc2`, raw GTE
+  commands, `rfe`, `break`, and `syscall`.
+- `decodeWords` and `formatProgram`: a program view with labelled branch targets
+  that re-assembles to its words.
+- The `psyq-asm` command line: listings, JSON output, and decoding.
+- A demo page, published to GitHub Pages.
+- Tests: unit, property, the ASPSX 2.81 ground truth, ported maspsx tests,
+  compiler fixtures, VERIFY probes, three browsers, and packaging with Node,
+  TypeScript, Vite, bare browser ESM, and Pages consumers.
+- A differential oracle (`scripts/oracle.mjs`, `npm run test:differential`):
+  compares matched decompiled code with its original executable, keeps every
+  name in the ignored `tmp/` directory, and commits only an aggregate summary.
+  `scripts/oracle-manifest.rb` writes manifests from a symbol list; a synthetic
+  pipeline test runs in CI, and the real comparison runs on demand on a
+  self-hosted runner.
+- Tooling for the real assembler: `scripts/aspsx-oracle.rb` runs ASPSX 2.81
+  under wine, locally or in an x86-64 Docker container
+  (`scripts/aspsx-wine.Dockerfile`), first replaying the 15 ground-truth
+  fixtures, then recording words for the VERIFY probes and compiler fixtures;
+  objects are read with `scripts/psyq-object.mjs`, and tests require any
+  recorded words exactly.
+
+### Fidelity
+
+- The initial rule set, [docs/ASPSX-2.81.md](docs/ASPSX-2.81.md): all 15 ASPSX
+  2.81 ground-truth fixtures are word-exact.
+- A relocation against a symbol leaves its field 0 and carries the addend in the
+  relocation, as the `lwlw` fixture shows for `lw $2,Savemap+2944`.
+- `break` carries two 10-bit codes. A single source code is split as maspsx does;
+  the divide traps are `break 7,0` and `break 6,0`.
+- Checked against real ASPSX 2.81, run in Docker by `scripts/aspsx-oracle.rb`:
+  all 40 compiler fixtures and all 19 probes match word for word, settling 17
+  verification items (VERIFY-1, 6 to 20, and 22). The rest of this list is what
+  changed as a result.
+- Relocated fields against local labels hold 0: `j $L9`, `%lo($LC1)`, and
+  jump-table `.word $L15` entries no longer carry the label's offset.
+- `.extern sym,size` no longer makes a symbol small data;
+  `experimental.externSmallData` now defaults to false.
+- A load made under `.set noreorder` gets no delay nop.
+- The multiply gap: a load between `mflo`/`mfhi` and `mult`/`div` no longer
+  cancels the gap nop, and that one nop also serves as the load delay; a
+  multi-word expansion between them fills the gap.
+- `b label` assembles as `bgez $0,label`, and `subu rd,rs,-32768` as a single
+  `addiu rd,rs,-0x8000`.
+
+[Unreleased]: https://github.com/jaysonvirissimo/psyq-asm/commits/main

package/LICENSE

@@ -0,0 +1,56 @@
+MIT License
+
+Copyright (c) 2026 Jayson Virissimo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+-------------------------------------------------------------------------------
+
+Third-party material
+
+The ground-truth fixtures in test/fixtures/aspsx/ (assembly sources and the
+words real ASPSX binaries produce for them), the unit tests in
+test/unit/maspsx/, and the behaviour rules they document in docs/ASPSX-2.81.md
+are derived from maspsx (https://github.com/mkst/maspsx), used under the
+following license:
+
+MIT License
+
+Copyright (c) 2023 Mark Street
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+No Sony software, SDK material, or game data is included in this package or
+this repository.

package/README.md

@@ -0,0 +1,220 @@
+# psyq-asm
+
+An ASPSX 2.81-compatible assembler and R3000 encoder/decoder in TypeScript, for
+PlayStation 1 matching-decompilation tooling in the browser and Node.js.
+
+[psyq-wasm](https://github.com/jaysonvirissimo/psyq-wasm) produces the exact
+assembly text the PsyQ 4.4 compiler (`cc1psx`) emits. That text is not what a
+PlayStation executable contains. Sony's assembler, ASPSX, expands macro
+instructions such as `li` and `div`, inserts `nop`s for delay slots and hardware
+hazards, and addresses small data through `$gp`. `psyq-asm` reproduces that step,
+so a page or a build tool can turn compiler output into the machine words a
+matching decompilation compares against.
+
+It is synchronous, has no runtime dependencies, and uses no WebAssembly, no
+worker, and no network. Every word it emits says where it came from: a source
+instruction, a macro expansion, or a nop inserted for a stated reason.
+
+```
+C source ──psyq-wasm──▶ cc1psx assembly ──psyq-asm──▶ R3000 words + relocations + provenance
+```
+
+> **Status:** unreleased. See [the fidelity contract](#the-fidelity-contract) for
+> what is verified.
+
+## Install
+
+```sh
+npm install psyq-asm
+```
+
+Node.js 22 or later, or any current browser. ESM only.
+
+## Usage
+
+### Assembling
+
+```js
+import { assemble } from 'psyq-asm';
+
+const result = assemble(asmText, { gpSize: 8 });
+if (!result.success) {
+  for (const d of result.diagnostics) console.error(`${d.file}:${d.line}: ${d.message}`);
+} else {
+  const text = result.object.sections.find((s) => s.name === '.text');
+  text.words; // Uint32Array of little-endian words
+  text.relocations; // [{ offset, kind: 'HI16', fieldMask: 0xffff, target, fieldValue }, ...]
+  text.provenance; // [{ line: 21, kind: 'load-delay-nop', note: '$3 is written by lw and read by sll' }, ...]
+  result.object.functions; // [{ name: 'glob', section: '.text', start: 6, end: 11 }, ...]
+}
+```
+
+`source` may be a string or a `Uint8Array` (decoded as UTF-8); CRLF and LF line
+endings give the same result. `gpSize` is the `-G` value of the build being
+reproduced and is required: PsyQ projects use 0 or 8.
+
+Straight from psyq-wasm:
+
+```js
+import { createCompiler } from 'psyq-wasm';
+import { assemble } from 'psyq-asm';
+
+const compiler = await createCompiler();
+const compiled = await compiler.compilePreprocessed(preprocessedC, {
+  gpSize: 8,
+  filename: 'codec.i',
+  rawFlags: ['-O2', '-g0', '-Wall'],
+});
+if (compiled.success) {
+  const result = assemble(compiled.asm, { gpSize: 8, filename: 'codec.s' });
+}
+```
+
+### Comparing with target words
+
+Assembled words hold relocation addends where a linked executable holds
+addresses, so compare the bits outside each relocation's `fieldMask`:
+
+```js
+function matches(section, target) {
+  const masks = new Map();
+  for (const r of section.relocations)
+    masks.set(r.offset, (masks.get(r.offset) ?? 0) | r.fieldMask);
+  return [...section.words].every((word, i) => {
+    const keep = ~(masks.get(i * 4) ?? 0) >>> 0;
+    return (word & keep) >>> 0 === (target[i] & keep) >>> 0;
+  });
+}
+```
+
+### Single instructions
+
+```js
+import { decode, encode, format } from 'psyq-asm';
+
+const instruction = decode(0x27bdffa8);
+format(instruction); // 'addiu $sp,$sp,-0x58'
+format(instruction, { registers: 'numeric', hex: false }); // 'addiu $29,$29,-88'
+instruction.reads; // [29]
+encode(instruction); // 0x27bdffa8
+format(decode(0x00000000), { pseudo: true }); // 'nop'
+decode(0xffffffff); // { mnemonic: '.word', word: 0xffffffff, reason: 'unknown opcode 0x3F' }
+```
+
+### Programs
+
+`decodeWords` decodes a run of words and labels the branch targets inside it;
+`formatProgram` prints assembly that `assemble` accepts:
+
+```js
+import { decodeWords, formatProgram } from 'psyq-asm';
+
+const program = decodeWords([0x2442ffff, 0x1440fffe, 0x00000000, 0x03e00008]);
+formatProgram(program);
+// .set noreorder
+// L_0:
+//   addiu $v0,$v0,-0x1
+//   bne $v0,$zero,L_0
+//   sll $zero,$zero,0
+//   jr $ra
+```
+
+Pass `{ baseAddress: 0x800c56c0 }` to name labels by address and resolve `j`/`jal`
+targets. Re-assembling the text reproduces the words whenever ASPSX would insert
+no nop into them (no loads, `mflo`/`mfhi`, or `mfc2`/`cfc2` followed by a reader).
+
+## The fidelity contract
+
+`psyq-asm` emulates one version pair: PsyQ 4.4 `cc1psx` output assembled by
+ASPSX 2.81, invoked as `aspsx -q -G <n>`. The rule set is
+[docs/ASPSX-2.81.md](docs/ASPSX-2.81.md), with the evidence for every rule.
+
+What is verified today:
+
+- all 15 ASPSX 2.81 ground-truth word lists from
+  [maspsx](https://github.com/mkst/maspsx) assemble word for word;
+- the 2.81-applicable unit tests of maspsx are ported and pass;
+- all 40 psyq-wasm compiler fixtures (t01 to t20 at `-G 0` and `-G 8`) and all
+  19 verification probes match, word for word, what real ASPSX 2.81 emits for
+  them (recorded with `scripts/aspsx-oracle.rb`), with provenance for every word;
+- property tests: every instruction encodes and decodes symmetrically, decoded
+  programs re-assemble to their words, output is deterministic, and no input
+  makes `assemble` throw.
+
+What is not verified yet: two items, VERIFY-5 (how `.comm` allocations are laid
+out in data sections) and VERIFY-21 (where debugging labels bind next to an
+inserted nop, invisible at `-g0`). Both are listed at the end of the rule set,
+with the 17 items real ASPSX 2.81 has settled. The switches in
+`options.experimental` default to what ASPSX 2.81 does. A differential oracle,
+which compares assembled words with an already-matched decompilation's original
+executable, is in place (`scripts/oracle.mjs`).
+
+## Options
+
+| Option                         | Default     | Meaning                                                             |
+| ------------------------------ | ----------- | ------------------------------------------------------------------- |
+| `gpSize`                       | required    | The `-G` small-data threshold: a non-negative integer.              |
+| `aspsxVersion`                 | `'2.81'`    | The only accepted value.                                            |
+| `partialDivExpansion`          | `false`     | Reproduce `ASPSX -0`: `div`/`rem` without trap checks.              |
+| `filename`                     | `'input.s'` | The name diagnostics use. A single path segment.                    |
+| `experimental.externSmallData` | `false`     | Address small `.extern` symbols through `$gp`; ASPSX 2.81 does not. |
+| `experimental.copMoveDelayNop` | `true`      | A nop after `mfc2`/`cfc2` before a reader, as ASPSX 2.81 inserts.   |
+
+## Output model
+
+| Field                | Contents                                                                                                                                                                                                         |
+| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `object.sections[]`  | `name`, `kind` (`code`, `data`, `bss`), `bytes`, `size`, `relocations`; code sections also `words` and `provenance`. First-appearance order; `.comm` allocations create `.sbss`/`.bss` last.                     |
+| `relocations[]`      | `offset` (bytes), `kind` (`HI16`, `LO16`, `GPREL16`, `MIPS26`, `WORD32`), `fieldMask`, `target` (a symbol and addend, or a section offset for a local label), and `fieldValue`.                                  |
+| `provenance[]`       | One per word: source `line`, `kind` (`instruction`, `macro`, `branch-delay-nop`, `load-delay-nop`, `hilo-gap-nop`, `cop-delay-nop`, `align`, `data`), the `macro` that expanded, and a `note` for inserted nops. |
+| `object.symbols[]`   | `name`, `binding` (`global`, `local`, `extern`, `common`), `section`, `offset`, `size`.                                                                                                                          |
+| `object.functions[]` | From `.ent`/`.end`: `name`, `start` and `end` word indices, `frame`, `mask`, `fmask`.                                                                                                                            |
+| `object.smallData[]` | The symbols addressed through `$gp`, with the reason.                                                                                                                                                            |
+
+## Errors
+
+Problems in the assembly are diagnostics in a failed result (`success: false`),
+each with a `code` such as `unknown-mnemonic`, `undefined-label`,
+`immediate-out-of-range`, or `unsupported-syntax`. Nothing that looks like an
+instruction is ever skipped silently. Exceptions are reserved for caller
+mistakes:
+
+| Error                     | `code`                | Thrown when                                                                     |
+| ------------------------- | --------------------- | ------------------------------------------------------------------------------- |
+| `InvalidOptionsError`     | `invalid-options`     | `options` or `style` is malformed, or `source` is not a string or `Uint8Array`. |
+| `InvalidInstructionError` | `invalid-instruction` | `encode` gets an operand that cannot be encoded, or `decode` a non-integer.     |
+
+Both extend `PsyqAsmError`, and `code` narrows to the subclass.
+
+## Command line
+
+```sh
+psyq-asm -G 8 codec.s                     # listing: offset, word, instruction, why
+psyq-asm -G 8 --json codec.json codec.s   # the whole object as JSON
+psyq-asm --decode --base 0x800C56C0 words.txt
+```
+
+Decoding reads every eight-digit hexadecimal word in the file, so `dw 0x27BDFFA8`
+lines work as they are.
+
+## Demo
+
+`npm run build && npm run serve`, then open <http://127.0.0.1:4173/demo/>: paste
+compiler output and see the words with the reason for each, or paste words and
+see the program. The same page is published to GitHub Pages.
+
+## Stability
+
+Semantic versioning covers the exported functions, types, options, and error
+codes. A change to the words emitted for some input is a fidelity fix, not a
+breaking change, and is listed under **Fidelity** in the
+[changelog](CHANGELOG.md). The defaults of `experimental` switches may change in
+any release.
+
+## License and credits
+
+MIT; see [LICENSE](LICENSE). The ASPSX ground truth, the ported unit tests, and
+much of the rule set come from [maspsx](https://github.com/mkst/maspsx) by Mark
+Street (MIT). The compiler fixtures come from
+[psyq-wasm](https://github.com/jaysonvirissimo/psyq-wasm) (MIT). No Sony software
+or game data is included.

package/bin/psyq-asm.mjs

@@ -0,0 +1,149 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: MIT
+/**
+ * psyq-asm command line.
+ *
+ *   psyq-asm -G <n> [--partial-div] [--json <out.json>] <input.s>
+ *   psyq-asm --decode [--base <address>] [--numeric] [--pseudo] <words.txt>
+ *
+ * Assembling prints a listing (offset, word, instruction, and why the word
+ * exists) or, with --json, writes the whole object. Diagnostics go to stderr.
+ * Decoding reads every 8-digit hexadecimal word in the file (`0x27BDFFA8`,
+ * `dw 0x27BDFFA8`, or `27BDFFA8`) and prints assembly that re-assembles.
+ *
+ * Exit status: 0 on success, 1 when the input has errors, 2 for usage errors.
+ */
+import { readFileSync, writeFileSync } from 'node:fs';
+import { basename } from 'node:path';
+import {
+  PsyqAsmError,
+  assemble,
+  decode,
+  decodeWords,
+  format,
+  formatProgram,
+} from '../dist/index.js';
+
+const USAGE = `usage: psyq-asm -G <n> [--partial-div] [--json <out.json>] <input.s>
+       psyq-asm --decode [--base <address>] [--numeric] [--pseudo] <words.txt>`;
+
+function usage(message) {
+  console.error(`psyq-asm: ${message}`);
+  console.error(USAGE);
+  process.exit(2);
+}
+
+function parseArgs(argv) {
+  const options = { decode: false, partialDiv: false, numeric: false, pseudo: false };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    const value = () => {
+      const next = argv[++i];
+      if (next === undefined) usage(`${arg} needs a value.`);
+      return next;
+    };
+    if (arg === '-h' || arg === '--help') {
+      console.log(USAGE);
+      process.exit(0);
+    } else if (arg === '-G') options.gpSize = value();
+    else if (/^-G\d+$/.test(arg)) options.gpSize = arg.slice(2);
+    else if (arg === '--partial-div') options.partialDiv = true;
+    else if (arg === '--json') options.json = value();
+    else if (arg === '--decode') options.decode = true;
+    else if (arg === '--base') options.base = value();
+    else if (arg === '--numeric') options.numeric = true;
+    else if (arg === '--pseudo') options.pseudo = true;
+    else if (arg.startsWith('-')) usage(`unknown option ${arg}.`);
+    else if (options.input === undefined) options.input = arg;
+    else usage(`unexpected argument ${arg}.`);
+  }
+  if (options.input === undefined) usage('no input file.');
+  return options;
+}
+
+const hex8 = (value) => `0x${(value >>> 0).toString(16).toUpperCase().padStart(8, '0')}`;
+
+function toJson(object) {
+  return {
+    ...object,
+    sections: object.sections.map((section) => ({
+      name: section.name,
+      kind: section.kind,
+      size: section.size,
+      bytes: Buffer.from(section.bytes).toString('hex'),
+      ...(section.words === undefined ? {} : { words: [...section.words].map(hex8) }),
+      relocations: section.relocations,
+      ...(section.provenance === undefined ? {} : { provenance: section.provenance }),
+    })),
+  };
+}
+
+function printListing(object) {
+  for (const section of object.sections) {
+    if (section.words === undefined) continue;
+    console.log(`${section.name}:`);
+    const relocations = new Map(section.relocations.map((r) => [r.offset, r]));
+    [...section.words].forEach((word, index) => {
+      const origin = section.provenance[index];
+      const text = format(decode(word), { pseudo: true });
+      const why = [origin.kind, origin.macro, origin.note].filter(Boolean).join(': ');
+      console.log(
+        `  ${hex8(index * 4)}  ${hex8(word)}  ${text.padEnd(28)} ; line ${String(origin.line)} ${why}`,
+      );
+      const relocation = relocations.get(index * 4);
+      if (relocation !== undefined) {
+        const target =
+          relocation.target.kind === 'symbol'
+            ? `${relocation.target.name}${relocation.target.addend === 0 ? '' : `+${String(relocation.target.addend)}`}`
+            : `${relocation.target.section}+${hex8(relocation.target.offset)}`;
+        console.log(`  ${' '.repeat(22)}${relocation.kind} ${target}`);
+      }
+    });
+  }
+}
+
+function runAssemble(options) {
+  if (options.gpSize === undefined) usage('-G <n> is required: PsyQ builds use -G 0 or -G 8.');
+  const result = assemble(readFileSync(options.input), {
+    gpSize: Number(options.gpSize),
+    partialDivExpansion: options.partialDiv,
+    filename: basename(options.input),
+  });
+  for (const d of result.diagnostics) {
+    const at = d.column === undefined ? String(d.line) : `${String(d.line)}:${String(d.column)}`;
+    console.error(`${d.file}:${at}: ${d.severity}: ${d.message} [${d.code}]`);
+  }
+  if (!result.success) process.exit(1);
+  if (options.json === undefined) printListing(result.object);
+  else writeFileSync(options.json, `${JSON.stringify(toJson(result.object), null, 2)}\n`);
+}
+
+function runDecode(options) {
+  const text = readFileSync(options.input, 'utf8');
+  const words = [...text.matchAll(/\b(?:0x)?([0-9a-f]{8})\b/gi)].map((m) =>
+    Number.parseInt(m[1], 16),
+  );
+  const program = decodeWords(
+    words,
+    options.base === undefined ? {} : { baseAddress: Number(options.base) },
+  );
+  process.stdout.write(
+    formatProgram(program, {
+      registers: options.numeric ? 'numeric' : 'abi',
+      pseudo: options.pseudo,
+    }),
+  );
+}
+
+const options = parseArgs(process.argv.slice(2));
+try {
+  if (options.decode) runDecode(options);
+  else runAssemble(options);
+} catch (error) {
+  if (error instanceof PsyqAsmError) usage(error.message);
+  if (error?.code === 'ENOENT') {
+    console.error(`psyq-asm: cannot read ${options.input}.`);
+    process.exit(2);
+  }
+  throw error;
+}

package/dist/asm/assemble.d.ts

@@ -0,0 +1,10 @@
+import type { AssembleOptions, AssembleResult } from '../public-types.js';
+/**
+ * Assemble PsyQ 4.4 `cc1psx` output into the words ASPSX 2.81 produces.
+ *
+ * Problems in the input are reported as diagnostics in a failed result; this
+ * function throws only `InvalidOptionsError`, for a malformed `options` or a
+ * `source` that is neither a string nor a `Uint8Array`.
+ */
+export declare function assemble(source: string | Uint8Array, options: AssembleOptions): AssembleResult;
+//# sourceMappingURL=assemble.d.ts.map

package/dist/asm/assemble.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assemble.d.ts","sourceRoot":"","sources":["../../src/asm/assemble.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAS1E;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,EAAE,OAAO,EAAE,eAAe,GAAG,cAAc,CA6B9F"}

package/dist/asm/assemble.js

@@ -0,0 +1,42 @@
+// SPDX-License-Identifier: MIT
+import { decodeSource, validateAssembleOptions } from '../options.js';
+import { Diagnostics } from './diagnostics.js';
+import { expand } from './expand.js';
+import { insertNops } from './hazards.js';
+import { layout } from './layout.js';
+import { buildObject } from './object.js';
+import { parse } from './parser.js';
+import { classifySmallData, collectSymbols } from './symbols.js';
+/**
+ * Assemble PsyQ 4.4 `cc1psx` output into the words ASPSX 2.81 produces.
+ *
+ * Problems in the input are reported as diagnostics in a failed result; this
+ * function throws only `InvalidOptionsError`, for a malformed `options` or a
+ * `source` that is neither a string nor a `Uint8Array`.
+ */
+export function assemble(source, options) {
+    const normalized = validateAssembleOptions(options);
+    const text = decodeSource(source);
+    const diagnostics = new Diagnostics(normalized.filename);
+    const statements = parse(text, diagnostics);
+    const symbols = collectSymbols(statements, diagnostics);
+    const smallData = classifySmallData(symbols, normalized.gpSize, normalized.experimental.externSmallData);
+    const items = expand(statements, {
+        gpSize: normalized.gpSize,
+        smallData,
+        partialDivExpansion: normalized.partialDivExpansion,
+        diagnostics,
+    });
+    const withNops = insertNops(items, {
+        copMoveDelayNop: normalized.experimental.copMoveDelayNop,
+    });
+    const laidOut = layout(withNops, symbols, normalized.gpSize, diagnostics);
+    if (diagnostics.hasErrors)
+        return { success: false, diagnostics: diagnostics.sorted() };
+    return {
+        success: true,
+        object: buildObject(normalized, laidOut, symbols, smallData),
+        diagnostics: diagnostics.sorted(),
+    };
+}
+//# sourceMappingURL=assemble.js.map

package/dist/asm/assemble.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"assemble.js","sourceRoot":"","sources":["../../src/asm/assemble.ts"],"names":[],"mappings":"AAAA,+BAA+B;AAC/B,OAAO,EAAE,YAAY,EAAE,uBAAuB,EAAE,MAAM,eAAe,CAAC;AAEtE,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AACpC,OAAO,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAEjE;;;;;;GAMG;AACH,MAAM,UAAU,QAAQ,CAAC,MAA2B,EAAE,OAAwB;IAC5E,MAAM,UAAU,GAAG,uBAAuB,CAAC,OAAO,CAAC,CAAC;IACpD,MAAM,IAAI,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC;IAClC,MAAM,WAAW,GAAG,IAAI,WAAW,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC;IAEzD,MAAM,UAAU,GAAG,KAAK,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC;IAC5C,MAAM,OAAO,GAAG,cAAc,CAAC,UAAU,EAAE,WAAW,CAAC,CAAC;IACxD,MAAM,SAAS,GAAG,iBAAiB,CACjC,OAAO,EACP,UAAU,CAAC,MAAM,EACjB,UAAU,CAAC,YAAY,CAAC,eAAe,CACxC,CAAC;IACF,MAAM,KAAK,GAAG,MAAM,CAAC,UAAU,EAAE;QAC/B,MAAM,EAAE,UAAU,CAAC,MAAM;QACzB,SAAS;QACT,mBAAmB,EAAE,UAAU,CAAC,mBAAmB;QACnD,WAAW;KACZ,CAAC,CAAC;IACH,MAAM,QAAQ,GAAG,UAAU,CAAC,KAAK,EAAE;QACjC,eAAe,EAAE,UAAU,CAAC,YAAY,CAAC,eAAe;KACzD,CAAC,CAAC;IACH,MAAM,OAAO,GAAG,MAAM,CAAC,QAAQ,EAAE,OAAO,EAAE,UAAU,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IAE1E,IAAI,WAAW,CAAC,SAAS;QAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,WAAW,CAAC,MAAM,EAAE,EAAE,CAAC;IACxF,OAAO;QACL,OAAO,EAAE,IAAI;QACb,MAAM,EAAE,WAAW,CAAC,UAAU,EAAE,OAAO,EAAE,OAAO,EAAE,SAAS,CAAC;QAC5D,WAAW,EAAE,WAAW,CAAC,MAAM,EAAE;KAClC,CAAC;AACJ,CAAC"}

package/dist/asm/diagnostics.d.ts

@@ -0,0 +1,22 @@
+import type { Diagnostic, DiagnosticCode } from '../public-types.js';
+/** Where a diagnostic points: any statement or item carries these. */
+export interface Position {
+    readonly line: number;
+    readonly column?: number;
+}
+/** Collects the diagnostics of one `assemble` call. */
+export declare class Diagnostics {
+    private readonly file;
+    private readonly entries;
+    private readonly onceKeys;
+    constructor(file: string);
+    error(at: Position, code: DiagnosticCode, message: string): void;
+    warning(at: Position, code: DiagnosticCode, message: string): void;
+    /** A warning reported only for the first occurrence of `key` in the file. */
+    warnOnce(key: string, at: Position, code: DiagnosticCode, message: string): void;
+    get hasErrors(): boolean;
+    /** All diagnostics, sorted by line (stable within a line). */
+    sorted(): readonly Diagnostic[];
+    private push;
+}
+//# sourceMappingURL=diagnostics.d.ts.map

package/dist/asm/diagnostics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics.d.ts","sourceRoot":"","sources":["../../src/asm/diagnostics.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAErE,sEAAsE;AACtE,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,uDAAuD;AACvD,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAoB;IAC5C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAqB;gBAElC,IAAI,EAAE,MAAM;IAIxB,KAAK,CAAC,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI;IAIhE,OAAO,CAAC,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI;IAIlE,6EAA6E;IAC7E,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI;IAMhF,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED,8DAA8D;IAC9D,MAAM,IAAI,SAAS,UAAU,EAAE;IAI/B,OAAO,CAAC,IAAI;CAeb"}

package/dist/asm/diagnostics.js

@@ -0,0 +1,40 @@
+/** Collects the diagnostics of one `assemble` call. */
+export class Diagnostics {
+    file;
+    entries = [];
+    onceKeys = new Set();
+    constructor(file) {
+        this.file = file;
+    }
+    error(at, code, message) {
+        this.push('error', at, code, message);
+    }
+    warning(at, code, message) {
+        this.push('warning', at, code, message);
+    }
+    /** A warning reported only for the first occurrence of `key` in the file. */
+    warnOnce(key, at, code, message) {
+        if (this.onceKeys.has(key))
+            return;
+        this.onceKeys.add(key);
+        this.warning(at, code, message);
+    }
+    get hasErrors() {
+        return this.entries.some((d) => d.severity === 'error');
+    }
+    /** All diagnostics, sorted by line (stable within a line). */
+    sorted() {
+        return [...this.entries].sort((a, b) => a.line - b.line);
+    }
+    push(severity, at, code, message) {
+        this.entries.push({
+            severity,
+            file: this.file,
+            line: at.line,
+            ...(at.column === undefined ? {} : { column: at.column }),
+            code,
+            message,
+        });
+    }
+}
+//# sourceMappingURL=diagnostics.js.map

package/dist/asm/diagnostics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics.js","sourceRoot":"","sources":["../../src/asm/diagnostics.ts"],"names":[],"mappings":"AASA,uDAAuD;AACvD,MAAM,OAAO,WAAW;IACL,IAAI,CAAS;IACb,OAAO,GAAiB,EAAE,CAAC;IAC3B,QAAQ,GAAG,IAAI,GAAG,EAAU,CAAC;IAE9C,YAAY,IAAY;QACtB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;IAED,KAAK,CAAC,EAAY,EAAE,IAAoB,EAAE,OAAe;QACvD,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;IACxC,CAAC;IAED,OAAO,CAAC,EAAY,EAAE,IAAoB,EAAE,OAAe;QACzD,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,EAAE,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;IAC1C,CAAC;IAED,6EAA6E;IAC7E,QAAQ,CAAC,GAAW,EAAE,EAAY,EAAE,IAAoB,EAAE,OAAe;QACvE,IAAI,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC;YAAE,OAAO;QACnC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACvB,IAAI,CAAC,OAAO,CAAC,EAAE,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;IAClC,CAAC;IAED,IAAI,SAAS;QACX,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,OAAO,CAAC,CAAC;IAC1D,CAAC;IAED,8DAA8D;IAC9D,MAAM;QACJ,OAAO,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC;IAC3D,CAAC;IAEO,IAAI,CACV,QAAgC,EAChC,EAAY,EACZ,IAAoB,EACpB,OAAe;QAEf,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC;YAChB,QAAQ;YACR,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,IAAI,EAAE,EAAE,CAAC,IAAI;YACb,GAAG,CAAC,EAAE,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC,MAAM,EAAE,CAAC;YACzD,IAAI;YACJ,OAAO;SACR,CAAC,CAAC;IACL,CAAC;CACF"}