@8bitscript/compiler 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 8BitScript contributors
+
+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.

package/index.mjs

@@ -0,0 +1,91 @@
+// @8bitscript/compiler — the public surface other packages consume.
+//
+// The dependency direction is one-way and load-bearing: the CLI and the
+// language server both depend on this package, and this package knows nothing
+// about either of them, or about any editor. Analysis lives here so that
+// `8bs check`, the editor, and CI all report the same errors from the same
+// implementation.
+import { tokenize } from './src/lexer/index.mjs';
+import { parse } from './src/parser/index.mjs';
+import { check } from './src/checker/index.mjs';
+import { foldCompileTime } from './src/fold/index.mjs';
+import { lower } from './src/ir/index.mjs';
+import { resolveImports } from './src/resolver/index.mjs';
+
+export { tokenize, TokenKind, KEYWORDS, TYPE_NAMES } from './src/lexer/index.mjs';
+export { parse } from './src/parser/index.mjs';
+export { NodeType, walk } from './src/ast/index.mjs';
+export { check } from './src/checker/index.mjs';
+export { foldCompileTime, DURATION_CLOCKS, DURATION_UNITS, SYSTEMS } from './src/fold/index.mjs';
+export {
+  FACTS, PROGRAM_FACTS, factConstName, factPlaceholder, factProblems,
+  requiresProblems, unmetRequirements,
+} from './src/fold/facts.mjs';
+export { lower, entryOf } from './src/ir/index.mjs';
+export { link, memoryOf } from './src/linker/index.mjs';
+export {
+  MACHINES, findImports, isVariantPath, resolveImports, resolveSpecifier, variantOf, tagsOf,
+} from './src/resolver/index.mjs';
+export { Codes, diagnostic, positionAt } from './src/diagnostics/index.mjs';
+export {
+  PRIMITIVE_INTEGER_TYPES,
+  INTEGER_TYPE_NAMES,
+  INTEGER_RANGES,
+  resolveIntegerType,
+  storageBytes,
+} from './src/types/index.mjs';
+export { getHoverInfo, getCompletions } from './src/intellisense/index.mjs';
+
+/**
+ * Analyse one source file and return every diagnostic it produces.
+ *
+ * This is the single entry point for "what is wrong with this file". It never
+ * throws: source is assumed to be mid-edit, and a dependency on disk is assumed
+ * to be possibly broken.
+ *
+ * Import resolution is opt-in because it is the only part that touches the
+ * filesystem, and it needs a real absolute path to resolve against. Callers
+ * working with an unsaved buffer leave it off.
+ *
+ * Lowering runs too, and its diagnostics are part of the answer: "this
+ * construct is not compilable yet" is exactly what someone needs to see
+ * while typing, not at the end of a build. It is a pure AST-to-IR pass with
+ * no filesystem in it, so the only thing it cannot report on its own is
+ * anything that needs the other modules — an unresolved name, a namespace
+ * member that doesn't exist — which the linker reports at build time.
+ *
+ * @param {string} text
+ * @param {string} file
+ * @param {{ resolveImports?: boolean, frameRate?: number, machine?: string, facts?: object }} [options]
+ *   `machine` is the target when one is known; without it `#system()` and
+ *   `#fact(...)` fold to placeholders and are valid-but-target-dependent,
+ *   as a `.<machine>.8bs` import is. `facts` is the machine's hardware
+ *   fact sheet, wanted whenever `machine` is given and a fact is read. `frameRate` (default 60) is the project's logical frame rate — see
+ *   8bs.config.ts — that every `#frames(...)` call folds against, mirroring
+ *   link()'s option of the same name so `8bs check`/the editor and a real
+ *   build agree on what a duration means.
+ * @returns {object[]} diagnostics, in source order
+ */
+export function analyze(text, file = '<unknown>', options = {}) {
+  const { tokens, diagnostics: lexical } = tokenize(text, file);
+  const { ast, diagnostics: syntax } = parse(tokens, text, file);
+
+  // Folding runs before check(), same ordering as the linker: a
+  // #frames(...) call needs to already be a plain IntegerLiteral by the
+  // time the width-fit rule walks the tree.
+  const folding = foldCompileTime(ast, file, { frameRate: options.frameRate, machine: options.machine, facts: options.facts });
+  const all = [...lexical, ...syntax, ...folding, ...check(ast, file, text)];
+  // A few rules — the template layout above all — are deliberately run by
+  // both check() and lower(), so that `check()` alone is a complete
+  // AST-level answer and `lower()` alone can never drop a construct
+  // silently. One problem is still reported once (the linker dedupes the
+  // same way for the same reason).
+  const seen = new Set(all.map((d) => `${d.code}@${d.start}+${d.length}`));
+  for (const d of lower(ast, file, text).diagnostics) {
+    if (!seen.has(`${d.code}@${d.start}+${d.length}`)) all.push(d);
+  }
+  // Import resolution stays on tokens rather than the AST, deliberately: a
+  // syntax error on line 30 should not stop line 1's import from being checked.
+  if (options.resolveImports) all.push(...resolveImports(tokens, file));
+  return all.sort((a, b) => a.start - b.start);
+}

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@8bitscript/compiler",
+  "version": "0.1.0",
+  "description": "Internal: the 8BitScript front end — lexer, checker, and diagnostics.",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=26"
+  },
+  "main": "./index.mjs",
+  "exports": {
+    ".": "./index.mjs",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "index.mjs",
+    "src"
+  ],
+  "devDependencies": {
+    "@8bitscript/text": "0.1.0",
+    "@8bitscript/vic20": "0.1.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "node --test"
+  }
+}

package/src/ast/index.mjs

@@ -0,0 +1,90 @@
+// AST node shapes.
+//
+// Every node carries `start` and `length`, the same span a diagnostic uses.
+// That is not incidental: positions recorded at parse time are what let a
+// checker error land on the exact characters that caused it, in the terminal
+// and under the cursor, without anything downstream re-deriving a location.
+//
+// Nodes are plain objects. There is no class hierarchy and no visitor
+// framework: a `type` string and a switch is enough at this size, and it keeps
+// the tree trivially serialisable for tests.
+
+export const NodeType = {
+  Program: 'Program',
+
+  ImportDeclaration: 'ImportDeclaration',
+  VariableDeclaration: 'VariableDeclaration',
+  FunctionDeclaration: 'FunctionDeclaration',
+  NamespaceDeclaration: 'NamespaceDeclaration',
+  Parameter: 'Parameter',
+
+  BlockStatement: 'BlockStatement',
+  IfStatement: 'IfStatement',
+  WhileStatement: 'WhileStatement',
+  ForStatement: 'ForStatement',
+  ReturnStatement: 'ReturnStatement',
+  BreakStatement: 'BreakStatement',
+  ContinueStatement: 'ContinueStatement',
+  ExpressionStatement: 'ExpressionStatement',
+  AsmBlock: 'AsmBlock',
+
+  Identifier: 'Identifier',
+  IntegerLiteral: 'IntegerLiteral',
+  // A decimal fraction (`0.5`) — legal only as the first argument to the
+  // `#frames(...)` compile-time duration builtin (packages/compiler/src/
+  // fold), which consumes and removes every valid one before anything else
+  // sees the tree; one surviving to `check()` means it was used somewhere
+  // else, which is always a diagnostic (the language has no other float
+  // semantics).
+  DecimalLiteral: 'DecimalLiteral',
+  BooleanLiteral: 'BooleanLiteral',
+  StringLiteral: 'StringLiteral',
+  // A backtick string with `${...}` fields: `TICK ${ticks % 10:1}`. `parts`
+  // is an ordered array of TemplateText and TemplateField nodes — real
+  // nodes, so walk() reaches every field expression and the fold pass and
+  // checker see them like any other expression.
+  TemplateLiteral: 'TemplateLiteral',
+  TemplateText: 'TemplateText',
+  // `${expression}` or `${expression:width}` — `width` an IntegerLiteral or
+  // null when the field left it to the expression's type.
+  TemplateField: 'TemplateField',
+  // `[1, 2, 3]`: the initialiser of an `array<T, N>`. Elements are
+  // expressions in the tree (so hover and the fold pass reach them), but
+  // lowering only accepts compile-time values there — the data is laid
+  // out before the program runs.
+  ArrayLiteral: 'ArrayLiteral',
+
+  AssignmentExpression: 'AssignmentExpression',
+  BinaryExpression: 'BinaryExpression',
+  UnaryExpression: 'UnaryExpression',
+  UpdateExpression: 'UpdateExpression',
+  CallExpression: 'CallExpression',
+  MemberExpression: 'MemberExpression',
+  IndexExpression: 'IndexExpression',
+
+  TypeReference: 'TypeReference',
+  Decorator: 'Decorator',
+};
+
+/** Build a node with its span. */
+export function node(type, start, end, props = {}) {
+  return { type, start, length: end - start, ...props };
+}
+
+/**
+ * Walk every node in a tree, parents before children.
+ *
+ * @param {object} root
+ * @param {(node: object, parent: object|null) => void} visit
+ */
+export function walk(root, visit, parent = null) {
+  if (!root || typeof root.type !== 'string') return;
+  visit(root, parent);
+  for (const value of Object.values(root)) {
+    if (Array.isArray(value)) {
+      for (const item of value) walk(item, visit, root);
+    } else if (value && typeof value === 'object' && typeof value.type === 'string') {
+      walk(value, visit, root);
+    }
+  }
+}

package/src/checker/index.mjs

@@ -0,0 +1,294 @@
+// The checker.
+//
+// Four rules so far: an integer literal has to fit the type it is assigned
+// to; the runtime builtin's name — `waitFrame` (packages/compiler/src/ir)
+// — is reserved; a string that becomes program data (a literal, or the
+// text of a template) holds only the portable character set, at most 255
+// of them; a template string sits where the compiler can lay it out
+// (`namespace.print(cell, \`...\`)` as a statement) with every field
+// sized — the same layout lowering performs (packages/compiler/src/
+// templates), run here so its diagnostics reach the editor; and a
+// top-level `const` — a compile-time constant with no storage — is never
+// assigned to.
+//
+// This used to pattern-match a fixed token shape because there was no tree to
+// walk. It now runs on the AST, which is what the parser bought: the rule finds
+// declarations anywhere — inside a function body, inside a `for` initialiser,
+// on an exported declaration — rather than only at the one shape a token scan
+// could recognise. The diagnostic code, the message, and the span are
+// unchanged, because a rule moving to a better home should not look different
+// to the person reading the error.
+//
+// Still deliberately narrow: the initialiser must be a literal, optionally
+// negated. `let x: u8 = 200 + 100` is not folded, because constant folding
+// belongs after a binder that knows what names mean.
+import { Codes, diagnostic } from '../diagnostics/index.mjs';
+import { NodeType, walk } from '../ast/index.mjs';
+import { resolveIntegerType } from '../types/index.mjs';
+import {
+  scanDeclaredTypes, parameterTypes, layoutTemplate, isTemplateCall, misplacedTemplate, resolveScalarType,
+} from '../templates/index.mjs';
+
+// The one runtime builtin that is a bare name: `waitFrame()` lowers to its
+// own IR kind that every backend emits in its own way
+// (packages/compiler/src/ir). It is closer to a keyword than to an ordinary
+// name, but implemented as a reserved identifier rather than a grammar
+// keyword — a call's *shape* is an ordinary call, and keywords are not
+// valid callees. Reserving the name here is what keeps a user's own
+// `waitFrame` from being silently reinterpreted as the builtin instead of
+// getting a clear diagnostic.
+//
+// Compile-time functions (`#frames(...)`, packages/compiler/src/fold) need
+// no reservation: their `#` spelling is its own token, so `let frames`
+// never collides. Nor does the unit word (`seconds` in
+// `#frames(0.5, seconds)`): that argument slot can never hold a variable,
+// so the fold recognises the word by spelling in place and
+// `let seconds: uint` anywhere else stays an ordinary declaration.
+const RESERVED_BUILTIN_NAMES = new Map([
+  ['waitFrame', 'the built-in frame wait, waitFrame()'],
+]);
+
+// What every target's character set can show: the NES ships its own font
+// (packages/nes/native/6502/font.s) with exactly these glyphs, and the
+// Commodore machines are switched to their upper-case set by putChar.
+// Anything else is a diagnostic here — not silently blanked on one machine
+// and shown on another. Import specifiers are StringLiteral nodes too and
+// are skipped: a module path is not screen text.
+const PORTABLE_CHARACTERS = /^[ 0-9A-Z!,\-.:?]*$/;
+const MAX_STRING_LENGTH = 255;
+
+function checkScreenText(n, file, diagnostics) {
+  if (n.unterminated) return; // the lexer reported it; whatever follows the quote is not the text
+  const value = n.value ?? '';
+  if (!PORTABLE_CHARACTERS.test(value)) {
+    const bad = [...value].find((ch) => !PORTABLE_CHARACTERS.test(ch));
+    const hint = /[a-z]/.test(bad) ? ' — upper case only' : '';
+    diagnostics.push(diagnostic(
+      Codes.UNPORTABLE_CHARACTER,
+      `'${bad}' is not in the portable character set (space, 0-9, A-Z, and ! , - . : ?)${hint}`,
+      file, n.start, n.length,
+    ));
+    return;
+  }
+  if (value.length > MAX_STRING_LENGTH) {
+    diagnostics.push(diagnostic(
+      Codes.STRING_TOO_LONG,
+      `a string holds at most ${MAX_STRING_LENGTH} characters; this one is ${value.length}`,
+      file, n.start, n.length,
+    ));
+  }
+}
+
+function reservedNameDiagnostic(nameNode, file) {
+  return diagnostic(
+    Codes.RESERVED_BUILTIN_NAME,
+    `'${nameNode.name}' is reserved for ${RESERVED_BUILTIN_NAMES.get(nameNode.name)}`,
+    file, nameNode.start, nameNode.length,
+  );
+}
+
+/**
+ * The constant value of an initialiser, or null when it is not a plain literal.
+ *
+ * @returns {{ value: number, node: object } | null}
+ */
+function literalValue(expression) {
+  if (!expression) return null;
+  if (expression.type === NodeType.IntegerLiteral) {
+    return { value: expression.value, node: expression };
+  }
+  if (
+    expression.type === NodeType.UnaryExpression &&
+    (expression.operator === '-' || expression.operator === '+') &&
+    expression.argument?.type === NodeType.IntegerLiteral
+  ) {
+    const magnitude = expression.argument.value;
+    return {
+      value: expression.operator === '-' ? -magnitude : magnitude,
+      node: expression,
+    };
+  }
+  return null;
+}
+
+// A const is UPPER_SNAKE; a variable starts with a lower-case letter. The
+// spelling is the compile-time signal: `LIMIT` is resolved by 8bitscript,
+// `limit` is storage on the machine. Namespace members count — `const`
+// inside `namespace BorderColor` is `BLUE` — and so does a local.
+const CONST_NAME = /^[A-Z][A-Z0-9_]*$/;
+const VARIABLE_NAME = /^[a-z_]/;
+
+/** `OptionCount` -> `OPTION_COUNT`, `borders` -> `BORDERS`: the spelling a const should have. */
+function constSpelling(name) {
+  return name.replace(/([a-z0-9])([A-Z])/g, '$1_$2').toUpperCase();
+}
+
+function checkNameCase(n, file, diagnostics) {
+  const name = n.name.name;
+  if (n.kind === 'const' && !CONST_NAME.test(name)) {
+    diagnostics.push(diagnostic(
+      Codes.NAME_CASE,
+      `a const is written in upper case, so a reader knows it is resolved by 8bitscript: ${constSpelling(name)}`,
+      file, n.name.start, n.name.length,
+    ));
+  } else if (n.kind === 'let' && !VARIABLE_NAME.test(name)) {
+    diagnostics.push(diagnostic(
+      Codes.NAME_CASE,
+      `a variable starts with a lower-case letter; an upper-case name is a const`,
+      file, n.name.start, n.name.length,
+    ));
+  }
+}
+
+/**
+ * The rules that need a function's scope. Templates: each one must be the
+ * second argument of a `namespace.print` call in statement position, and
+ * each of its fields must have a width the layout can determine — a field
+ * expression is typed in the scope of the parameters around it, and a
+ * template outside any function (a global initialiser) has nowhere to be
+ * laid out at all. Consts: this module's top-level `const`s are never
+ * assigned to or `++`/`--`ed, unless a parameter of the same name shadows
+ * one, which is ordinary lexical scoping.
+ */
+function checkFunctions(ast, file, source, diagnostics) {
+  const declared = scanDeclaredTypes(ast);
+  const consts = new Set(ast.body
+    .filter((n) => n.type === NodeType.VariableDeclaration && n.kind === 'const' && n.name)
+    .map((n) => n.name.name));
+  const constArrays = new Set([...declared.arrayTypes].filter(([, a]) => a.constant).map(([name]) => name));
+  // `HALF = 2` on a const, or `Table[0] = 2` on a const array (whose
+  // elements are data in the program). Either way the name is the span.
+  const assignedConst = (target, params) => {
+    const name = target?.type === NodeType.IndexExpression ? target.object : target;
+    if (name?.type !== NodeType.Identifier || params.has(name.name)) return null;
+    if (target.type === NodeType.IndexExpression) return constArrays.has(name.name) ? name : null;
+    return consts.has(name.name) ? name : null;
+  };
+  const visitFunction = (fn) => {
+    if (!fn.body) return; // a function whose body is still being typed
+    // Locals count with parameters here — function-scoped, an approximation
+    // of the block scoping lowering applies, enough to know a name is not
+    // the const or array it shadows and what type a field of it has.
+    const paramTypes = parameterTypes(fn);
+    walk(fn.body, (n) => {
+      if (n.type !== NodeType.VariableDeclaration || !n.name || n.kind !== 'let') return;
+      const type = n.typeAnnotation?.name && resolveScalarType(n.typeAnnotation.name);
+      if (type && !n.typeAnnotation.typeArguments?.length) paramTypes.set(n.name.name, type);
+    });
+    const scope = { ...declared, paramTypes };
+    // Parents are visited before children, so a template reached through
+    // its statement is claimed here before walk() descends to it.
+    const placed = new Set();
+    walk(fn.body, (n) => {
+      if (n.type === NodeType.ExpressionStatement && isTemplateCall(n.expression)) {
+        const template = n.expression.args[1];
+        placed.add(template);
+        diagnostics.push(...layoutTemplate(template, scope, file, source).diagnostics);
+        return;
+      }
+      if (n.type === NodeType.TemplateLiteral && !placed.has(n)) {
+        diagnostics.push(misplacedTemplate(n, file));
+        return;
+      }
+      const target = n.type === NodeType.AssignmentExpression ? n.left
+        : n.type === NodeType.UpdateExpression ? n.argument : null;
+      const name = target && assignedConst(target, paramTypes);
+      if (name) {
+        diagnostics.push(diagnostic(
+          Codes.ASSIGN_TO_CONST,
+          target.type === NodeType.IndexExpression
+            ? `'${name.name}' is a const array — data in the program, not RAM — and cannot be assigned to`
+            : `'${name.name}' is a const — a compile-time value with no storage — and cannot be assigned`,
+          file, name.start, name.length,
+        ));
+      }
+    });
+  };
+  for (const node of ast.body) {
+    if (node.type === NodeType.FunctionDeclaration) visitFunction(node);
+    if (node.type === NodeType.NamespaceDeclaration) {
+      for (const member of node.members ?? []) {
+        if (member?.type === NodeType.FunctionDeclaration) visitFunction(member);
+      }
+    }
+    if (node.type === NodeType.VariableDeclaration) {
+      walk(node.initializer, (n) => {
+        if (n.type === NodeType.TemplateLiteral) diagnostics.push(misplacedTemplate(n, file));
+      });
+    }
+  }
+}
+
+/**
+ * @param {object} ast   Program node from the parser.
+ * @param {string} file
+ * @param {string|null} [source]  The file's text, so a diagnostic can quote code back.
+ * @returns {object[]} diagnostics
+ */
+export function check(ast, file = '<unknown>', source = null) {
+  const diagnostics = [];
+  if (!ast) return diagnostics;
+
+  checkFunctions(ast, file, source, diagnostics);
+
+  walk(ast, (n, parent) => {
+    if (
+      (n.type === NodeType.StringLiteral && parent?.type !== NodeType.ImportDeclaration)
+      || n.type === NodeType.TemplateText
+    ) {
+      checkScreenText(n, file, diagnostics);
+      return;
+    }
+
+    if (n.type === NodeType.ImportDeclaration) {
+      for (const specifier of n.specifiers) {
+        if (RESERVED_BUILTIN_NAMES.has(specifier.name)) {
+          diagnostics.push(reservedNameDiagnostic(specifier, file));
+        }
+      }
+      return;
+    }
+
+    if (n.type === NodeType.FunctionDeclaration || n.type === NodeType.Parameter) {
+      if (n.name && RESERVED_BUILTIN_NAMES.has(n.name.name)) {
+        diagnostics.push(reservedNameDiagnostic(n.name, file));
+      }
+      return;
+    }
+
+    if (n.type !== NodeType.VariableDeclaration) return;
+
+    if (n.name && RESERVED_BUILTIN_NAMES.has(n.name.name)) {
+      diagnostics.push(reservedNameDiagnostic(n.name, file));
+    }
+    if (n.name) checkNameCase(n, file, diagnostics);
+
+    const typeName = n.typeAnnotation?.name;
+    // A type constructor such as ptr<u8> has type arguments and is not itself
+    // an integer, so it never resolves against the registry below.
+    if (n.typeAnnotation?.typeArguments?.length) return;
+    const resolved = typeName && resolveIntegerType(typeName);
+    if (!resolved) return;
+
+    const literal = literalValue(n.initializer);
+    if (!literal) return;
+
+    // The message keeps whatever the programmer actually wrote (`u8` or
+    // `utinyint`) even though both resolve to the same type: a diagnostic
+    // should point at the reader's own words, not a canonicalised rewrite.
+    const { min, max } = resolved;
+    if (literal.value < min || literal.value > max) {
+      diagnostics.push(
+        diagnostic(
+          Codes.VALUE_OUT_OF_RANGE,
+          `${literal.value} does not fit in ${typeName} (${min}..${max})`,
+          file,
+          literal.node.start,
+          literal.node.length,
+        ),
+      );
+    }
+  });
+
+  return diagnostics;
+}