Linter and Diagnostics

Hosanna uses both ESLint and compiler diagnostics to catch code that TypeScript can express but Roku/BrightScript or cross-platform runtimes cannot support safely.

The ESLint plugin reports issues early in the editor and in npm run lint. The Hosanna Compiler reports the same class of issues during hsc compilation. Many ESLint rule names are mapped to Hosanna HS-xxxx diagnostic codes so one suppression can intentionally quiet both tools.

Project Scripts

Current Hosanna app projects use scripts like:

{
  "lint": "eslint --config eslint.config.mjs ...",
  "lint:strict": "HOSANNA_ESLINT_STRICT=1 eslint --config eslint.config.mjs ...",
  "roku:build": "npx hst install:compiler && bin/hsc --project platforms/hsconfig-roku.json"
}

lint:strict enables stricter Hosanna checks, including strict Date usage reporting.

Rule Coverage

The linter covers common Roku/cross-platform hazards:

• unsupported JavaScript APIs (Promise, JSON, Object, String, Array, Math, Number, crypto, Buffer)
• unsupported language forms (await, nested functions, inline classes, IIFEs, rest/spread cases, unsupported compound assignment)
• unsafe equality and binary comparisons
• reserved words and unsupported regex flags
• invalid conditional compilation patterns
• AsyncFunctionPointer restrictions, including inline or bound callbacks
• AppConfig JSON validation
• generated import and Hosanna import-prefix discipline
• numeric literal and unsafe number parsing restrictions

Some folders intentionally relax Hosanna rules, such as build tooling, platform target shims, tests, and generated files.

Suppression Syntax

Prefer fixing the code. Suppress only when the code has been reviewed and the runtime behavior is intentional.

Compiler-native suppression:

// hs:disable-next-line HS-1019
const same = a === b;

Spacing is also accepted:

// hs: disable-next-line HS-1019
const same = a === b;

File-level suppression:

// hs:disable HS-1019

Block comments are accepted at file level:

/* hs:disable HS-1019, HS-1005 */

Re-enable after a file-level disable:

// hs:enable HS-1019

You can also use diagnostic names where supported:

// hs:disable ThisInNonArrowClosure

ESLint suppression can suppress the mapped compiler diagnostic:

// eslint-disable-next-line @hosanna-eslint/no-basic-type-binary-comparison
const same = a === b;

The compiler maps Hosanna ESLint rule names to HS codes. For example:

ESLint rule	Compiler code
no-await-expression	HS-1032
no-unsupported-string-methods	HS-1048, HS-1109
no-conditional-compilation-else	HS-1091
no-mixed-conditional-compilation	HS-1011
no-basic-type-binary-comparison	HS-1019, HS-1054, HS-1058, HS-1118
no-any-unknown-equality-unsafe	HS-1118
no-unsigned-right-shift	HS-1119
no-callfunc-too-many-arguments	HS-1120
no-member-assignment-on-callable-reference	HS-1121

Diagnostic Filters

Compiler config supports diagnosticFilters for broader project-level filtering. Use them sparingly because they hide diagnostics across a larger scope than a line comment.

Line comments are the preferred form for local, reviewed exceptions.

Platform Exclusion

For code that should not be compiled for Roku, use platform exclusions instead of suppressing every diagnostic:

// hs:exclude-from-platform roku
export function webOnlyHelper() {
  return window.location.href;
}

The directive works at file prefix and node/line level. Use this when a helper is genuinely web-only rather than Roku-compatible code with one local exception.