Skip to main content

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 compiler:install && 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 (including await outside the compiler's experimental subset, nested functions, inline classes, IIFEs, rest/spread cases, and 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 ruleCompiler code
no-await-expressionHS-1032
no-unsupported-string-methodsHS-1048, HS-1109
no-conditional-compilation-elseHS-1091
no-mixed-conditional-compilationHS-1011
no-basic-type-binary-comparisonHS-1019, HS-1054, HS-1058, HS-1118
no-any-unknown-equality-unsafeHS-1118
no-unsigned-right-shiftHS-1119
no-callfunc-too-many-argumentsHS-1120
no-member-assignment-on-callable-referenceHS-1121

The experimental compiler flag transpileOptions.enableAsyncAwait does not automatically configure ESLint. Approved pilot files must scope @hosanna-eslint/no-await-expression: off in ESLint while the compiler enforces HS-1150 through HS-1156 for unsupported async forms. Do not turn the rule off repository-wide. See Experimental Async/Await on Roku.

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.

The compiler also supports persistent diagnostic config in global ~/.hsc/config.json or project-local .hsc/config.json. Use this when a diagnostic should have a different default severity for a user or project without editing every hsconfig.

For example, to demote HS-1138 to a hint:

{
  "diagnosticSeverityOverrides": {
    "HS-1138": "hint"
  }
}

With the default diagnosticLevel of warn, demoted hints do not appear in normal build output. Run hsc --diagnosticLevel hint to include them. See Hosanna Compiler for config paths, precedence, and supported fields.

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.

Talk to us