@8bitscript/compiler 0.1.0

package/src/diagnostics/index.mjs

@@ -0,0 +1,179 @@
+// The diagnostic record every part of the toolchain speaks.
+//
+// One shape, produced in one place, consumed by both `8bs check` and the
+// language server. That is the whole point: the error you see in the editor and
+// the error CI fails on are the same object, not two implementations that drift.
+
+/**
+ * @typedef {object} Diagnostic
+ * @property {string} code     Stable identifier, e.g. "8BS1021".
+ * @property {string} message  Human-readable text, no trailing period.
+ * @property {string} file     Path or URI the diagnostic belongs to.
+ * @property {number} start    Zero-based offset into the source text.
+ * @property {number} length   Length of the offending span, in characters.
+ * @property {'error'|'warning'} severity
+ */
+
+/**
+ * Diagnostic codes.
+ *
+ * 1000s are lexical and syntax problems — things findable without knowing what
+ * any name refers to. 2000s are resolution and type errors (resolution is
+ * implemented; type errors wait on a binder). 3000s are target limits: the
+ * construct is valid but the compiler cannot lower it yet, it is not available
+ * on the requested target, or the target refuses it as a hardware hazard.
+ */
+export const Codes = {
+  UNTERMINATED_STRING: '8BS1002',
+  UNEXPECTED_CHARACTER: '8BS1003',
+  UNMATCHED_BRACKET: '8BS1004',
+  UNCLOSED_BRACKET: '8BS1005',
+  UNTERMINATED_BLOCK_COMMENT: '8BS1006',
+  UNTERMINATED_ASM_BLOCK: '8BS1007',
+  INVALID_NUMBER: '8BS1008',
+  // A decimal literal (`0.5`) used anywhere other than as the first argument
+  // to a duration clock call, `#frames(...)` — the only place the language
+  // has any float-shaped syntax. foldDurations() (packages/compiler/src/fold) consumes and
+  // removes every valid one before check() ever runs, so any that survive
+  // to be walked here were misplaced.
+  MISPLACED_DECIMAL_LITERAL: '8BS1009',
+  SYNTAX_ERROR: '8BS1101',
+  VALUE_OUT_OF_RANGE: '8BS1021',
+  // `#frames(...)`'s argument shape is wrong — not one integer-or-decimal
+  // literal followed by the bare unit word it is measured in (see
+  // foldDurations()). The unit is required: `#frames(30)` is this.
+  INVALID_DURATION_ARGUMENT: '8BS1022',
+  // A `#frames(...)` call folded to zero frames at the project's configured
+  // frameRate — always a bug, not a benign rounding nicety: it would wrap a
+  // countdown like `let ticks: utinyint = #frames(...); ... ticks = ticks - 1;`
+  // straight through 0 instead of ticking.
+  ZERO_DURATION: '8BS1023',
+  // A `#frames(...)` call didn't fold to an exact frame count at the
+  // project's configured frameRate — reported so a rate change (e.g. 60 to
+  // 50) that silently nudges a duration's real-world length is never
+  // invisible.
+  INEXACT_DURATION: '8BS1024',
+  // `#frames(...)`'s second argument names a unit the fold doesn't know —
+  // the only one so far is `seconds` (see the fold pass's DURATION_UNITS).
+  // Reported at the identifier itself, not the whole call.
+  UNKNOWN_DURATION_UNIT: '8BS1025',
+  // A string literal (or the text of a template) holds a character outside
+  // the portable set — space, `0`-`9`, `A`-`Z`, and `! , - . : ?` — the
+  // characters every target's character set can show (the NES ships its own
+  // font with exactly these; the Commodore machines are switched to their
+  // upper-case set). Reported where the string becomes program data
+  // (packages/compiler/src/ir), never for an import specifier.
+  UNPORTABLE_CHARACTER: '8BS1026',
+  // A string literal longer than 255 bytes: strings are length-prefixed
+  // with one byte, and no screen this compiles for has that many cells in
+  // a row anyway.
+  STRING_TOO_LONG: '8BS1027',
+  // A template string (`\`TICK ${ticks}\``) somewhere other than the second
+  // argument of a namespace's `print(cell, ...)` — the one place the
+  // compiler expands one — or with the wrong shape around it.
+  MISPLACED_TEMPLATE: '8BS1028',
+  // A `${...}` field the compiler cannot lay out: its width was not given
+  // and could not be taken from the expression's type (an imported name, a
+  // call across modules), or the value is not something a number field can
+  // show (signed, or wider than 16 bits).
+  UNPRINTABLE_FIELD: '8BS1029',
+  // `#name` — the compile-time spelling — naming a function the compiler
+  // doesn't evaluate (`#frames` is the only one), or a compile-time function
+  // used without being called (`#frames` on its own).
+  UNKNOWN_COMPILE_TIME_FUNCTION: '8BS1030',
+  // Assignment (or `++`/`--`) to a `const`: a compile-time constant, inlined
+  // wherever it is read, has no storage on the target to assign to. The
+  // checker reports a module's own consts; the linker, an imported one.
+  ASSIGN_TO_CONST: '8BS1031',
+  // `a[7]` on an `array<T, 4>`: a literal index at or past the array's
+  // length. Only a literal (or a const) can be checked at compile time; a
+  // runtime index is the program's own responsibility, as on the machine.
+  INDEX_OUT_OF_RANGE: '8BS1032',
+  // `[1, 2, 3]` for an `array<T, 4>`: an array initialiser has exactly as
+  // many elements as the type says — the length is part of the type, and
+  // the data is laid out at compile time, so nothing can pad or truncate.
+  ARRAY_SIZE_MISMATCH: '8BS1033',
+  // Names say which side of the compile-time rule they are on: a `const`
+  // is UPPER_SNAKE (`OPTION_COUNT`, `BorderColor.BLUE`), a variable starts
+  // with a lower-case letter. So a reader knows `LIMIT` is resolved by
+  // 8bitscript and `limit` is storage on the machine, without looking up
+  // the declaration.
+  NAME_CASE: '8BS1034',
+  // A call with more arguments than the function has parameters, or fewer
+  // than the parameters without a default. A default (`border: utinyint =
+  // BorderColor.BLACK`) is a compile-time value 8bitscript fills in at the
+  // call, so every call the machine sees is complete.
+  WRONG_ARGUMENT_COUNT: '8BS1035',
+  // `#system(...)` called with arguments: it takes none (see the fold pass).
+  SYSTEM_TAKES_NO_ARGUMENTS: '8BS1036',
+  // `#fact(...)` of a key the sheet does not have, or with no key at all
+  // (see the fold pass and fold/facts.mjs for the keys).
+  UNKNOWN_FACT: '8BS1037',
+  // `#fact(...)` in a build that knows its machine but was handed no
+  // hardware facts: the fold will not guess a sheet for a real build.
+  NO_HARDWARE_FACTS: '8BS1038',
+
+  UNRESOLVED_PACKAGE: '8BS2001',
+  NOT_AN_8BS_PACKAGE: '8BS2002',
+  MISSING_PACKAGE_ENTRY: '8BS2003',
+  UNRESOLVED_RELATIVE_IMPORT: '8BS2004',
+  NO_SUCH_EXPORT: '8BS2005',
+  DUPLICATE_BINDING: '8BS2006',
+  UNRESOLVED_NAME: '8BS2007',
+  MISSING_NATIVE_SOURCE: '8BS2008',
+  // A declaration or import named after a builtin — `waitFrame`
+  // (packages/compiler/src/ir). Compile-time functions (`#frames`) need no
+  // reservation: their `#` spelling is a different token from any name. A user binding by that name would otherwise
+  // be silently reinterpreted as the builtin rather than getting a clear
+  // diagnostic.
+  RESERVED_BUILTIN_NAME: '8BS2009',
+  // The entry module must export exactly one thing — a function taking no
+  // parameters — and that is the program: what a 6502 target's synthesised
+  // C `main` calls and what the web host's worker calls. Zero exports, a
+  // second export, an exported global or namespace, or a parameterised entry
+  // are all this diagnostic. Other modules (packages, libraries) may export
+  // whatever they like.
+  ENTRY_EXPORTS: '8BS2010',
+  // A package subpath — `@scope/name/thing` — that the package's
+  // `"8bitscript".exports` map has no entry for (packages/compiler/src/
+  // resolver). The package itself is fine; the import asks it for something
+  // it does not offer, which is a different failure from a missing entry
+  // file (8BS2003) or a package that is not 8BitScript at all (8BS2002).
+  NO_SUCH_SUBPATH: '8BS2011',
+
+  NOT_COMPILABLE: '8BS3001',
+  NOT_ON_THIS_TARGET: '8BS3002',
+  // Two of a build's hardware tags each have their own version of a file,
+  // and nothing says which wins (see the resolver's chooseVariant).
+  AMBIGUOUS_VARIANT: '8BS3004',
+  // A write the requested target's own documentation says can damage the
+  // machine — the PET's "killer poke" ($E842 with bit 5 set) is the one
+  // entry (packages/compiler/src/linker/hazards.mjs). Reported by the
+  // linker, which alone knows the machine and has every const inlined; so
+  // it is a build-time diagnostic, not one `8bs check` or the editor show.
+  HARDWARE_HAZARD: '8BS3003',
+};
+
+/** @returns {Diagnostic} */
+export function diagnostic(code, message, file, start, length, severity = 'error') {
+  return { code, message, file, start, length, severity };
+}
+
+/**
+ * Convert an offset into 1-based line and column, for terminal output.
+ *
+ * @param {string} text
+ * @param {number} offset
+ * @returns {{ line: number, column: number }}
+ */
+export function positionAt(text, offset) {
+  let line = 1;
+  let lastBreak = -1;
+  for (let i = 0; i < offset && i < text.length; i += 1) {
+    if (text[i] === '\n') {
+      line += 1;
+      lastBreak = i;
+    }
+  }
+  return { line, column: offset - lastBreak };
+}

package/src/fold/facts.mjs

@@ -0,0 +1,209 @@
+// The fact sheet's keys: what a build knows about the machine it is for.
+//
+// A fact is a number or a flag with one meaning on every machine, keyed the
+// way the machine packages' hardware catalogs spell it (`video.columns`,
+// `memory.banked` — see docs/packages.md, "the hardware catalog"). The
+// compiler owns the *keys* and their types; the machine packages own the
+// *values*: each catalog's top-level `facts` is the stock machine's sheet
+// and each hardware value's `facts` is what choosing it changes, and the
+// CLI merges them for a build (packages/cli/src/hardware.mjs,
+// resolveHardware). `#fact(video.columns)` folds to the merged value, and
+// `@8bitscript/system` gives every key a const (`Video.COLUMNS`) so a
+// program never spells a key itself.
+//
+// Two rules the table enforces. A fact is never missing: every catalog
+// declares every key that is `program: true` (the CLI's catalog test holds
+// them to it), so a machine without hardware sprites says `video.sprites`
+// 0 and a program's branch on it folds away rather than failing to
+// compile. And a fact is the worst case that matters, not the brochure
+// figure: `video.spritesPerLine` is the number that decides whether a
+// scene works (8 on the NES, whose 64 per frame would mislead), and where
+// a chip has a cycle budget instead of a count (the X16), the package
+// states the sprite size the count assumes.
+//
+// `when` says when the fact is settled. `build`: fixed by the build — the
+// machine and the hardware it was built for — so the const is the truth on
+// every machine the binary runs on. `run`: hardware the machine may or
+// may not have when the program runs (a REU, a mouse in a port, banked
+// RAM), which one binary can detect and use; the const then means "this
+// build may use it" — the hardware was chosen for the build, so the
+// capability's detection code is compiled in — and whether it is really
+// there is the capability's runtime answer. A build that never asked for
+// the hardware carries no code for it. Which facts are `run` is the
+// machine's business as much as the key's: the table marks what is
+// detectable *somewhere*, and a package that cannot detect it on its
+// machine says so in its notes.
+//
+// `program: false` keys are the CLI's, not a program's: `video.frameRate`
+// is what a screenshot's frame count is timed against, and it is not on
+// the sheet because the level machines (packages/backend-6502, FRAME_SYNC)
+// detect NTSC or PAL at run time — one binary runs at both — so a
+// compile-time refresh rate would be a fact that is sometimes wrong.
+
+/**
+ * @typedef {object} Fact
+ * @property {'count'|'flag'} type  a number (folds to an IntegerLiteral) or
+ *   a yes/no (folds to a BooleanLiteral)
+ * @property {'build'|'run'} when   see above
+ * @property {boolean} program      on the program's sheet (`@8bitscript/system`)
+ * @property {string} doc           one line, for hover and the editor's panel
+ */
+
+const count = (when, doc, program = true) => ({ type: 'count', when, program, doc });
+const flag = (when, doc, program = true) => ({ type: 'flag', when, program, doc });
+
+/** Every fact key, in the order the sheet lists them. @type {Map<string, Fact>} */
+export const FACTS = new Map([
+  // Video: the text grid and what the display is made of.
+  ['video.columns', count('build', 'Cells across the text grid the portable text draws on.')],
+  ['video.rows', count('build', 'Cells down the text grid.')],
+  ['video.cellWidth', count('build', 'Pixels across one cell.')],
+  ['video.cellHeight', count('build', 'Pixels down one cell.')],
+  ['video.palette', count('build', 'Colours the display can show at once.')],
+  ['video.cellColors', count('build', 'Colours one cell can hold in the text mode the grid uses.')],
+  ['video.colorPerCell', flag('build', 'A program can set one cell\'s colour without changing its neighbours\'.')],
+  ['video.glyphs', count('build', 'Characters a program can redefine at run time; 0 where the font is fixed.')],
+  ['video.blockWidth', count('build', 'Pseudo-pixels across one cell from the fixed font\'s block glyphs; 0 where there are none.')],
+  ['video.blockHeight', count('build', 'Pseudo-pixels down one cell from the block glyphs; 0 where there are none.')],
+  ['video.bitmap', flag('build', 'A pixel-addressable mode exists.')],
+  ['video.layers', count('build', 'Independent background layers.')],
+  ['video.scroll', flag('build', 'Hardware fine scroll exists.')],
+  ['video.sprites', count('build', 'Hardware sprites in total; 0 where moving objects are drawn in software.')],
+  ['video.spritesPerLine', count('build', 'Hardware sprites one scanline can show — the number that decides whether a scene works.')],
+  ['video.spriteWidth', count('build', 'Pixels across the largest hardware sprite.')],
+  ['video.spriteHeight', count('build', 'Pixels down the largest hardware sprite.')],
+  ['video.spriteColors', count('build', 'Colours one hardware sprite can hold, not counting transparent.')],
+  ['video.frameRate', count('build', 'Display refreshes a second, for timing a screenshot; not on the sheet, the machine may be NTSC or PAL at run time.', false)],
+  // Audio: the chip's shape.
+  ['audio.voices', count('build', 'Voices the sound hardware plays at once.')],
+  ['audio.noise', flag('build', 'A noise voice exists.')],
+  ['audio.envelope', flag('build', 'Hardware volume envelopes (ADSR or similar) exist.')],
+  ['audio.filter', flag('build', 'A hardware filter exists.')],
+  ['audio.pcm', flag('build', 'Sample playback exists.')],
+  ['audio.volume', flag('build', 'Each voice has its own volume.')],
+  ['audio.entropy', flag('build', 'A hardware random source exists.')],
+  // Input: the ports and what is plugged into them.
+  ['input.keyboard', flag('build', 'A keyboard the program can read.')],
+  ['input.joysticks', count('build', 'Joystick ports.')],
+  ['input.pads', count('build', 'Console-style controller ports.')],
+  ['input.mouse', flag('run', 'A mouse this build may use; whether one is plugged in is the capability\'s answer at run time.')],
+  ['input.paddles', flag('run', 'Paddles this build may use; whether they are plugged in is the capability\'s answer at run time.')],
+  // Storage.
+  ['storage.save', flag('build', 'Somewhere this build can persist bytes: disk, SD card, battery RAM.')],
+  ['storage.kib', count('build', 'KiB that place holds — the medium\'s usable capacity, not its image size; 0 where there is nowhere to save. Where the route is a host directory or a card whose size is the owner\'s, it is the smallest real medium that route stands for, so a program that fits the fact fits the hardware. KiB rather than bytes because a disk does not fit in the 16 bits an 8-bit machine counts in — the same reason memory.bankedKib is KiB.')],
+  // Memory.
+  ['memory.ram', count('build', 'Bytes of RAM the program is linked to use, code and data together.')],
+  ['memory.banked', flag('run', 'RAM beyond the CPU\'s window this build may use (a REU, an MMU bank, VERA-style banks); whether it is there is the capability\'s answer at run time.')],
+  ['memory.bankedKib', count('run', 'KiB of that banked RAM the build was fitted with.')],
+]);
+
+/** The keys a program's sheet carries, in order. */
+export const PROGRAM_FACTS = [...FACTS].filter(([, fact]) => fact.program).map(([key]) => key);
+
+/**
+ * The name `@8bitscript/system` gives a key: `video.spritesPerLine` is
+ * `Video.SPRITES_PER_LINE`. The namespace is the key's first word
+ * capitalised; the const is the rest in upper snake case.
+ *
+ * @param {string} key
+ * @returns {{ namespace: string, name: string }}
+ */
+export function factConstName(key) {
+  const [group, ...rest] = key.split('.');
+  const member = rest.join('.');
+  return {
+    namespace: group[0].toUpperCase() + group.slice(1),
+    name: member.replace(/([a-z])([A-Z])/g, '$1_$2').toUpperCase(),
+  };
+}
+
+/**
+ * The value a fact has when nothing set it: 0 or false — the placeholder
+ * the fold uses with no machine in hand, and the value a catalog test
+ * compares against when it insists a key was declared on purpose.
+ *
+ * @param {string} key
+ */
+export function factPlaceholder(key) {
+  return FACTS.get(key)?.type === 'flag' ? false : 0;
+}
+
+/**
+ * Check a `requires` block against the table: what a program needs of the
+ * machine it is built for, before the machine is known.
+ *
+ * A count is a floor and a flag must be true — "at least this much RAM",
+ * "somewhere to save" — because that is the shape of every requirement a
+ * program actually has. A `when: 'run'` fact cannot be required: whether a
+ * mouse is plugged in is answered on the machine, not by the build, so a
+ * program that needs one asks the capability and says so itself.
+ *
+ * @param {object} requires
+ * @returns {string[]} the problems, in words; empty when clean
+ */
+export function requiresProblems(requires) {
+  const problems = [];
+  for (const [key, need] of Object.entries(requires ?? {})) {
+    const fact = FACTS.get(key);
+    if (!fact) {
+      problems.push(`'${key}' is not a fact — the keys are ${PROGRAM_FACTS.join(', ')}`);
+      continue;
+    }
+    if (!fact.program) {
+      problems.push(`'${key}' is not on a program's sheet, so a program cannot require it`);
+      continue;
+    }
+    if (fact.when === 'run') {
+      problems.push(
+        `'${key}' is settled on the machine, not by the build, so it cannot be required — `
+        + 'ask the capability at run time instead',
+      );
+      continue;
+    }
+    if (fact.type === 'flag' && need !== true) {
+      problems.push(`'${key}' is a flag: require it with true, or leave it out — not ${JSON.stringify(need)}`);
+    }
+    if (fact.type === 'count' && !(Number.isInteger(need) && need > 0)) {
+      problems.push(`'${key}' is a count: require a whole number above zero, not ${JSON.stringify(need)}`);
+    }
+  }
+  return problems;
+}
+
+/**
+ * What a `requires` block asks for that a build's facts do not give.
+ *
+ * @param {object} requires  already checked by requiresProblems
+ * @param {object} facts     the merged sheet for one build
+ * @returns {{ key: string, need: number|boolean, have: number|boolean }[]} empty when the build is enough
+ */
+export function unmetRequirements(requires, facts) {
+  const unmet = [];
+  for (const [key, need] of Object.entries(requires ?? {})) {
+    const have = facts?.[key] ?? factPlaceholder(key);
+    const met = FACTS.get(key)?.type === 'flag' ? have === true : have >= need;
+    if (!met) unmet.push({ key, need, have });
+  }
+  return unmet;
+}
+
+/**
+ * Check one facts object against the table: every key known, every value
+ * of its key's type. Returns the problems, in words; empty when clean.
+ *
+ * @param {object} facts
+ * @returns {string[]}
+ */
+export function factProblems(facts) {
+  const problems = [];
+  for (const [key, value] of Object.entries(facts ?? {})) {
+    const fact = FACTS.get(key);
+    if (!fact) {
+      problems.push(`'${key}' is not a fact — the keys are ${[...FACTS.keys()].join(', ')}`);
+      continue;
+    }
+    if (fact.type === 'flag' && typeof value !== 'boolean') problems.push(`'${key}' is a flag: true or false, not ${JSON.stringify(value)}`);
+    if (fact.type === 'count' && !(Number.isInteger(value) && value >= 0)) problems.push(`'${key}' is a count: a whole number, not ${JSON.stringify(value)}`);
+  }
+  return problems;
+}