FS FormScript
Package@formscript/cli
Specification6.4, 11, 14, 15.1, 18
Depends ona11y, analyzer, ast, conformance, engine, errors, evaluator, i18n, lexer, parser, runtime, spec-lint, types, validation

@formscript/cli

The command-line interface to the **FormScript Language Specification 1.0.0 ** reference implementation.

Every command is a thin shell over a package: the CLI formats, the packages decide. Nothing here re-implements a rule of the specification.

Commands

bash
npm run formscript -- <command> [options]
Command What it does
lint <file...> Lex, parse and analyse a document; print every diagnostic with its location
ast <file> Print the parsed document as JSON
run <file> [p=v ...] Evaluate a form and print its output document
conformance [spec.md] Run the conformance suite of §18 against the specification
spec-lint [spec.md] Lint the specification document itself
errors List the error catalogue of §14, by category
level Declare the conformance level of §15.1, with its evidence
help Print the usage
Option Effect
--all Report every diagnostic, not only the earliest stage's errors (Spec-2.5)
--state Print the state of every field as well as the output
--json Print the output document as indented JSON
Exit code Meaning
0 Success
1 The document has errors, or the transaction did not commit
2 The command line or the input file could not be used

Examples

bash
# A clean document, and one with an undefined reference.
npm run formscript -- lint examples/demo.forms
npm run formscript -- lint examples/demo.forms --all

# Evaluate a form. The values are raw text, so the engine applies the
# coercions of Spec-5.16 to them rather than to a JavaScript value.
npm run formscript -- run examples/demo.forms name=Ada age=36

# The conformance suite and the specification lint.
npm run formscript -- conformance
npm run formscript -- spec-lint

# The declared conformance level of §15.1, with its evidence.
npm run formscript -- level

The conformance level

level prints the implementation's declared level and checks it. The declaration is read from conformance.json at the repository root, and the check re-reads §6.4 from the specification and compares its builtin list with the evaluator's — so a builtin added to the specification without an implementation turns the command red.

The exit code is 1 when the declared level is not supported by the evidence.

The output document

A run prints the output document as one JSON object. Numbers appear as strings holding their canonical decimal text, because the engine returns a JavaScript value tree rather than JSON text and a JSON number cannot carry a canonical decimal (Spec-4.36). A number or integer is therefore emitted as its canonical form — "36", "1.5", "1E+21".

Public API

The CLI is also a library, so the commands can be embedded or tested:

ts
import { runCli, BufferedIo } from '@formscript/cli';

const io = new BufferedIo();
const code = runCli(['lint', 'form.forms'], io);
console.log(code, io.outText);

runCli(argv, io) returns the exit code and never touches process itself, so it is safe to call from a test.

Not implemented

  • conformance and spec-lint default to the specification file in the repository root; they do not search for it.
  • The run command applies input assignments only. It does not mutate a repeat, drive an action, or fetch a source — those belong to §11 and to the runtime, not to the engine's input transaction.

Public API

22 exported symbols.

astFile function

Parses one document and writes its AST as JSON.

BufferedIo re-export
CliIo interface

Where the CLI writes. Injectable so the commands can be tested.

conformance function

Runs the conformance suite of §18 against the specification document.

consoleIo re-export
errorCatalogue function

Lists the error catalogue of §14.

formatDiagnostic re-export
LevelDeclaration interface
levelReport re-export
LevelReport interface
LevelRequirement interface
lintFile function

Lints one document and writes its diagnostics. Returns the number of errors, so the caller can set the exit code.

LintOptions interface
missingBuiltins re-export
parseAssignment re-export
readDeclaration re-export
REPO_ROOT const

The repository root, relative to this file rather than to the working directory.

runCli function

Runs one command and returns the process exit code.

runFile function

Evaluates a form with the given assignments and writes the result.

RunOptions interface
specBuiltinNames re-export
specLint function

Lints the specification document itself.