rooibos-roku 5.16.6 → 5.17.0

package/CHANGELOG.md

@@ -6,6 +6,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 
 
+## [5.17.0](https://github.com/rokucommunity/rooibos/compare/5.16.6...v5.17.0) - 2026-10-06
+### Added
+ - Add Roku Cloud Emulator (RCE) support via CLI ([#447](https://github.com/rokucommunity/rooibos/pull/447))
+### Changed
+ - Istanbul HTML code coverage reports and improved coverage accuracy ([#275](https://github.com/rokucommunity/rooibos/pull/275))
+ - Security enhancements ([#444](https://github.com/rokucommunity/rooibos/pull/444), [#446](https://github.com/rokucommunity/rooibos/pull/446))
+
+
+
 ## [5.16.6](https://github.com/rokucommunity/rooibos/compare/5.16.5...v5.16.6) - 2026-10-01
 ### Changed
  - Process every test suite in a file, not just the first ([#441](https://github.com/rokucommunity/rooibos/pull/441))

package/audit-ci.jsonc

@@ -3,5 +3,13 @@
     // why each allowlisted entry is safe to defer.
     "$schema": "https://github.com/IBM/audit-ci/raw/main/docs/schema.json",
     "high": true,
-    "allowlist": []
+    "allowlist": [
+        {
+            "GHSA-vfj7-8cjw-p6xm": {
+                // Added: 2026-10-03
+                "active": true,
+                "notes": "`braces` <=3.0.3 (prod, via `brighterscript`/`roku-debug`/`roku-deploy`/`fast-glob`): stack exhaustion on deeply nested brace patterns. No patched version is published, so it cannot be upgraded or overridden. The only patterns reaching it are globs from the caller's own project config; no untrusted party supplies them, and a crash only affects the caller's own local process."
+            }
+        }
+    ]
 }

package/dist/cli.js

@@ -1,12 +1,27 @@
 #!/usr/bin/env node
 "use strict";
+var __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 const roku_debug_1 = require("roku-debug");
 const brighterscript_1 = require("brighterscript");
 const yargs = require("yargs");
 const roku_deploy_1 = require("roku-deploy");
 const fs = require("fs");
+const fsExtra = require("fs-extra");
 const path = require("path");
+const RooibosConfig_1 = require("./lib/rooibos/RooibosConfig");
+const resolveCliDevice_1 = require("./lib/rooibos/resolveCliDevice");
+const CoverageReporter_1 = require("./lib/rooibos/CoverageReporter");
 /**
  * Load simple `KEY=value` pairs from a .env file into process.env, without
  * overwriting variables that are already set in the real environment.
@@ -33,25 +48,34 @@ function loadDotEnv(envPath = '.env') {
     }
 }
 loadDotEnv();
+// Resolved once by the argument check below, so main() can rely on a valid target and password.
+let password;
+let target;
 let options = yargs
     .usage('$0', 'Rooibos: a simple, flexible, fun Brightscript test framework for Roku Scenegraph apps')
     .help('help', 'View help information about this tool.')
     .option('project', { type: 'string', description: 'Path to a bsconfig.json project file.' })
-    .option('host', { type: 'string', description: 'Host of the Roku device to connect to. Overrides value in bsconfig file.' })
-    .option('password', { type: 'string', description: 'Password of the Roku device to connect to. Overrides value in bsconfig file.' })
+    .option('host', { type: 'string', description: 'Host of the Roku device to connect to. Falls back to ROKU_HOST.' })
+    .option('esn', { type: 'string', description: 'ESN of a Roku Cloud Emulator device to run on. Requires --token or ROKU_RCE_TOKEN. Cannot be combined with --host or --instance-url.' })
+    .option('instance-url', { type: 'string', description: 'URL of a Roku Cloud Emulator instance to run on. Requires --token or ROKU_RCE_TOKEN. Cannot be combined with --host or --esn.' })
+    .option('token', { type: 'string', description: 'Roku Cloud Emulator access token (used with --esn or --instance-url). Falls back to the ROKU_RCE_TOKEN environment variable.' })
+    .option('password', { type: 'string', description: 'Password of the Roku device to connect to. Falls back to ROKU_PASSWORD.' })
     .option('log-level', { type: 'string', defaultDescription: '"log"', description: 'The log level. Value can be "error", "warn", "log", "info", "debug".' })
+    .option('coverage-dir', { type: 'string', default: './coverage', description: 'Directory to write coverage reports into when codeCoverage is on: lcov.info, coverage-final.json and an html/ report.' })
+    .option('code-coverage', { type: 'boolean', description: 'Turn code coverage on (or off with --no-code-coverage) for the CLI\'s build, overriding the rooibos block of the bsconfig. Has no effect with --no-build.' })
+    .option('staging-dir', { type: 'string', description: 'Path to the built package directory (staging output). With --no-build this is zipped and deployed as-is; otherwise it overrides where the build stages. Coverage models are read from here.' })
+    .option('build', { type: 'boolean', default: true, description: 'Pass --no-build to skip the internal bsc build and deploy an existing staging directory (from --staging-dir or the bsconfig). Assumes it was built with the rooibos plugin so coverage helpers are present.' })
     .check((argv) => {
-    var _a;
-    if (!argv.host && !process.env.ROKU_HOST) {
-        return new Error('You must provide a host. (--host, or ROKU_HOST in .env)');
-    }
-    if (!argv.password && !process.env.ROKU_PASSWORD) {
+    var _a, _b;
+    password = (_a = argv.password) !== null && _a !== void 0 ? _a : process.env.ROKU_PASSWORD;
+    if (!password) {
         return new Error('You must provide a password. (--password, or ROKU_PASSWORD in .env)');
     }
+    target = (0, resolveCliDevice_1.resolveCliDevice)({ host: argv.host, esn: argv.esn, instanceUrl: argv['instance-url'], token: argv.token }, process.env);
     if (!argv.project) {
         console.log('No project file specified. Using "./bsconfig.json"');
     }
-    let bsconfigPath = (_a = argv.project) !== null && _a !== void 0 ? _a : './bsconfig.json';
+    let bsconfigPath = (_b = argv.project) !== null && _b !== void 0 ? _b : './bsconfig.json';
     if (!fs.existsSync(bsconfigPath)) {
         return new Error(`Unable to load ${bsconfigPath}`);
     }
@@ -59,20 +83,74 @@ let options = yargs
 })
     .argv;
 async function main() {
-    var _a, _b, _c, _d, _e, _f;
+    var _a, _b;
     let currentErrorCode = 0;
     let bsconfigPath = (_a = options.project) !== null && _a !== void 0 ? _a : 'bsconfig.json';
     console.log(`Using bsconfig: ${bsconfigPath}`);
     const rawConfig = brighterscript_1.util.loadConfigFile(bsconfigPath);
     const bsConfig = brighterscript_1.util.normalizeConfig(rawConfig);
-    const host = (_c = (_b = options.host) !== null && _b !== void 0 ? _b : bsConfig.host) !== null && _c !== void 0 ? _c : process.env.ROKU_HOST;
-    const password = (_e = (_d = options.password) !== null && _d !== void 0 ? _d : bsConfig.password) !== null && _e !== void 0 ? _e : process.env.ROKU_PASSWORD;
-    const logLevel = (_f = brighterscript_1.LogLevel[options['log-level']]) !== null && _f !== void 0 ? _f : bsConfig.logLevel;
-    const builder = new brighterscript_1.ProgramBuilder();
-    builder.logger.logLevel = logLevel;
-    await builder.run(Object.assign(Object.assign({}, options), { retainStagingDir: true, createPackage: true }));
-    const device = { host: host };
+    const rooibosConfig = (0, RooibosConfig_1.resolveCliRooibosConfig)(rawConfig.rooibos, { codeCoverage: options['code-coverage'] });
+    if (options['code-coverage'] !== undefined && options.build === false) {
+        console.warn('[rooibos] --code-coverage/--no-code-coverage has no effect with --no-build: the existing package was already built, so its coverage setting is whatever it was built with');
+    }
+    const { device, label: deviceLabel } = target;
+    const logLevel = (_b = brighterscript_1.LogLevel[options['log-level']]) !== null && _b !== void 0 ? _b : bsConfig.logLevel;
+    // roku-deploy v4 and roku-debug 0.24 address the target via a device config (resolved
+    // by the argument check) rather than a bare `host` string.
     const rokuDeploy = new roku_deploy_1.RokuDeploy();
+    const skipBuild = options.build === false;
+    /**
+     * Ordered candidate locations for the built package contents: the --staging-dir
+     * override, then the bsconfig staging fields, then roku-deploy's default staging
+     * location (used when no staging dir is configured anywhere).
+     */
+    function stagingDirCandidates() {
+        const candidates = [];
+        if (options['staging-dir']) {
+            candidates.push(path.resolve(String(options['staging-dir'])));
+        }
+        for (const staging of [bsConfig.stagingDir, bsConfig.stagingFolderPath]) {
+            if (staging) {
+                candidates.push(path.resolve(String(staging)));
+            }
+        }
+        const outDir = bsConfig.outFile ? path.dirname(String(bsConfig.outFile)) : './out';
+        candidates.push(path.resolve(outDir, '.roku-deploy-staging'));
+        return candidates;
+    }
+    // Resolved path to the .zip we'll actually deploy when skipping the build. We zip the
+    // staging dir into out/rooibos-prebuilt.zip ourselves rather than handing the directory
+    // straight to sideload({ dir }), because that path does not forward file patterns and
+    // would drop the source-map exclusion below. A directory is required either way - the
+    // coverage model (components/rooibos/CodeCoverage.json) must be readable from it.
+    let deployZipPath;
+    if (skipBuild) {
+        const stagingDir = stagingDirCandidates().find((c) => fs.existsSync(c));
+        if (!stagingDir) {
+            console.error('[rooibos] --no-build requires an existing staging directory: pass --staging-dir or set one in the bsconfig');
+            process.exit(1);
+        }
+        if (!fs.statSync(stagingDir).isDirectory()) {
+            console.error(`[rooibos] the staging dir must be a directory, not a file: ${stagingDir}`);
+            process.exit(1);
+        }
+        const zipped = path.resolve('out/rooibos-prebuilt.zip');
+        fs.mkdirSync(path.dirname(zipped), { recursive: true });
+        console.log(`Zipping pre-built staging dir ${stagingDir} -> ${zipped}`);
+        // Exclude source maps - they're useful in the staging dir but shouldn't ship
+        // in the package (they bloat channel size and Roku has no use for them).
+        // roku-deploy v4 replaced zipFolder(src, out, logger, files) with zip({...});
+        // the file patterns still resolve relative to `dir`.
+        await rokuDeploy.zip({ dir: stagingDir, out: zipped, files: ['**/*', '!**/*.map'] });
+        deployZipPath = zipped;
+    }
+    else {
+        const builder = new brighterscript_1.ProgramBuilder();
+        builder.logger.logLevel = logLevel;
+        // --staging-dir (if given) flows into bsc as its stagingDir via the spread
+        const { token: _token, esn: _esn, 'instance-url': _instanceUrlKebab, instanceUrl: _instanceUrl } = options, buildOptions = __rest(options, ["token", "esn", 'instance-url', "instanceUrl"]);
+        await builder.run(Object.assign(Object.assign(Object.assign({}, buildOptions), (rooibosConfig ? { rooibos: rooibosConfig } : {})), { retainStagingDir: true, createPackage: true }));
+    }
     const deviceInfo = await rokuDeploy.getDeviceInfo({ device: device });
     const rendezvousTracker = new roku_debug_1.RendezvousTracker({ softwareVersion: deviceInfo['software-version'] }, { device: device, remotePort: 8085 });
     const telnet = new roku_debug_1.TelnetAdapter({ device: device }, rendezvousTracker);
@@ -81,7 +159,52 @@ async function main() {
     await telnet.connect();
     const failRegex = /\[Rooibos Result\]: (FAIL|PASS)/g;
     const endRegex = /\[Rooibos Shutdown\]/g;
+    const outputDir = path.resolve(options['coverage-dir']);
+    let capturingCounts = false;
+    let coverageBuffer = [];
+    let coverageReportPromise;
+    /**
+     * The bsc plugin writes the static coverage model (line/function/branch shape plus
+     * repo-relative source paths) into components/rooibos/CodeCoverage.json; read it back
+     * from wherever the deployed package contents live.
+     */
+    function findCoverageModel() {
+        for (const dir of stagingDirCandidates()) {
+            const candidate = path.join(dir, 'components', 'rooibos', 'CodeCoverage.json');
+            const model = (0, CoverageReporter_1.loadCoverageModel)(candidate);
+            if (model) {
+                console.log(`[rooibos] using coverage model from ${candidate}`);
+                return model;
+            }
+        }
+        return undefined;
+    }
+    /** Dumps the raw device stream into the output dir so a capture is never lost. */
+    function saveRawCapture(raw) {
+        const rawPath = path.join(outputDir, 'coverage-counts.raw');
+        fsExtra.outputFileSync(rawPath, raw);
+        console.error(`[rooibos] raw coverage output saved to ${rawPath}`);
+    }
+    /** The device printed the condensed hit-counts stream. */
+    function writeCoverageFromCounts(rawCounts) {
+        const model = findCoverageModel();
+        if (!model) {
+            console.error('[rooibos] the device sent condensed coverage counts but no components/rooibos/CodeCoverage.json was found in the package or staging dir - cannot build coverage reports');
+            saveRawCapture(rawCounts);
+            return;
+        }
+        coverageReportPromise = (0, CoverageReporter_1.writeCoverageReportsFromCounts)({
+            rawCounts: rawCounts,
+            model: model,
+            outputDir: outputDir
+        }).catch(e => {
+            console.error('[rooibos] failed to write coverage reports:', e);
+            saveRawCapture(rawCounts);
+        });
+    }
     async function doExit(emitAppExit = false) {
+        // don't kill the process while coverage reports are still being written
+        await coverageReportPromise;
         if (emitAppExit) {
             telnet.beginAppExit();
         }
@@ -90,6 +213,21 @@ async function main() {
     }
     telnet.on('console-output', (output) => {
         console.log(output);
+        for (const line of output.split('\n')) {
+            if (line.includes('+-=-coverage-counts:start')) {
+                capturingCounts = true;
+                coverageBuffer = [];
+                continue;
+            }
+            if (line.includes('+-=-coverage-counts:end')) {
+                capturingCounts = false;
+                writeCoverageFromCounts(coverageBuffer.join('\n'));
+                continue;
+            }
+            if (capturingCounts) {
+                coverageBuffer.push(line);
+            }
+        }
         //check for Fails or Crashes
         let failMatches = failRegex.exec(output);
         if (failMatches && failMatches.length > 0) {
@@ -122,12 +260,15 @@ async function main() {
     // Actually start the unit tests
     //deploy a .zip package of your project to a roku device
     async function deployBuiltFiles() {
-        const outFile = bsConfig.outFile;
-        console.log(`Deploying ${outFile} to ${host}`);
+        // With --no-build, deploy the staging dir we just zipped; otherwise fall back to the
+        // bsconfig-driven outFile that the rooibos build just produced.
+        const packagePath = deployZipPath !== null && deployZipPath !== void 0 ? deployZipPath : path.resolve(process.cwd(), bsConfig.outFile);
+        console.log(`Deploying ${packagePath} to ${deviceLabel}`);
+        // roku-deploy v4 replaced publish({ host, outDir, outFile }) with sideload({ device, zip }).
         await rokuDeploy.sideload({
             password: password,
             device: device,
-            zip: path.resolve(process.cwd(), outFile)
+            zip: packagePath
         });
     }
     await deployBuiltFiles();

package/dist/lib/framework/components/rooibos/CodeCoverage.brs

@@ -1,44 +1,119 @@
-' @ignore
 function init()
-    m.resolvedMap = {}
-    m.top.observeField("entry", "onEntryChange")
-    m.top.observeField("save", "onSave")
-    m.results = []
+    ' The coverage map ships as a JSON asset rather than an embedded literal: a real app's
+    ' map can exceed Roku's 2MiB-per-.brs-file compile limit (&hb9) when written into code.
+    m.coverageMap = ParseJson(ReadAsciiFile("pkg:/components/rooibos/CodeCoverage.json"))
+    m.port = createObject("roMessagePort")
+    m.top.observeFieldScoped("entry", m.port)
+    ' save arrives on the same port so the task thread can block on wait() instead of
+    ' polling m.top.save (a cross-thread rendezvous) on a sleep loop
+    m.top.observeFieldScoped("save", m.port)
+    m.top.functionName = "runTaskThread"
+    m.top.control = "RUN"
 end function
 
-' @ignore
-function setExpectedMap()
-    m.top.expectedMap = "#EXPECTED_MAP#"
-end function
+function runTaskThread() as void
+    ' Per-file line lookups keyed by line number, built lazily on first hit (on the task
+    ' thread, so the render thread never pays for index construction). The values are
+    ' references to the same line AAs as file.lines, so mutating them updates the model.
+    m.lineIndexByFile = {}
+    ' Entries whose ids don't resolve in the model. Any nonzero count means the package
+    ' mixes instrumentation passes (e.g. stale staged files from an earlier build whose
+    ' baked-in ids alias different files in this build's CodeCoverage.json) - skip and
+    ' tally rather than crash the task.
+    m.unmatchedEntries = 0
+    while true
+        events = []
+        saving = false
+        ' blocking wait: zero CPU and no cross-thread field reads while idle
+        message = wait(0, m.port)
+        if message.getField() = "save" then
+            saving = (message.getData() = true)
+        else
+            events.push(message)
+        end if
+        if saving = true then
+            ? "Saving unprocessed code cov events..."
+            'Drain all the unprocessed messages (3ms grace per message, then done)
+            while true
+                message = wait(3, m.port)
+                if message = invalid then
+                    exit while
+                else if message.getField() <> "save" then
+                    events.push(message)
+                end if
+            end while
 
-' @ignore
-function setFilePathMap()
-    m.top.filePathMap = "#FILE_PATH_MAP#"
-end function
+            ? "Found" events.count() " unprocessed events..."
+        end if
 
-' @ignore
-function onEntryChange()
-    entry = m.top.entry
-    ' defer till later
-    m.results.push(entry)
-end function
+        ' entry.r values below are force-substituted at build time from the TS
+        ' CodeCoverageLineType enum (FileFactory.createCoverageComponent keys on the
+        ' #LINE_TYPE_*# markers), so producer and consumer cannot drift. The literals
+        ' here only matter for parsing this template standalone.
 
-' @ignore
-function onSave()
-    ? "saving data"
-    for each entry in m.results
-        if entry <> invalid then
-            fileId = entry.f
-            lineMap = m.resolvedMap[fileId]
+        for each event in events
+            entry = event.getData()
+            if entry <> invalid then
+                file = m.coverageMap.files[entry.f]
+                if file = invalid then
+                    m.unmatchedEntries++
+                else if entry.r = 4 then ' #LINE_TYPE_FUNCTION#
+                    func = file.functions[entry.fn]
+                    if func <> invalid then
+                        if func.totalHit = 0 then
+                            file.functionTotalHit++
+                        end if
+                        func.totalHit++
+                    else
+                        m.unmatchedEntries++
+                    end if
+                else if entry.r = 3 then ' #LINE_TYPE_BRANCH#
+                    ' branch ids are assigned as array indexes at build time, so index directly
+                    block = file.blocks[entry.bl]
+                    branch = invalid
+                    if block <> invalid then
+                        branch = block.branches[entry.br]
+                    end if
+                    if branch <> invalid then
+                        if branch.totalHit = 0 then
+                            file.branchTotalHit++
+                        end if
+                        branch.totalHit++
+                    else
+                        m.unmatchedEntries++
+                    end if
+                else if entry.r = 1 then ' #LINE_TYPE_CODE#
+                    fileKey = stri(entry.f).trim()
+                    lineIndex = m.lineIndexByFile[fileKey]
+                    if lineIndex = invalid then
+                        lineIndex = {}
+                        for each line in file.lines
+                            lineIndex[stri(line.lineNumber).trim()] = line
+                        end for
+                        m.lineIndexByFile[fileKey] = lineIndex
+                    end if
+                    line = lineIndex[stri(entry.l).trim()]
+                    if line <> invalid then
+                        if line.totalHit = 0 then
+                            file.lineTotalHit++
+                        end if
+                        line.totalHit++
+                    else
+                        m.unmatchedEntries++
+                    end if
+                end if
+                ' no write-back needed: file and its members are references into m.coverageMap
+            end if
+        end for
 
-            if lineMap = invalid then
-                lineMap = {}
-                m.resolvedMap[fileId] = lineMap
+        if saving = true then
+            if m.unmatchedEntries > 0 then
+                ? "[rooibos coverage] WARNING: " ; stri(m.unmatchedEntries).trim() ; " coverage entries did not match the coverage model and were skipped."
+                ? "[rooibos coverage] This usually means the package mixes files from different builds - rebuild into a clean staging directory."
             end if
-            lineMap[entry.l] = entry.r
+            m.top.coverageResults = m.coverageMap
+            return
         end if
-    end for
-    m.top.resolvedMap = m.resolvedMap
-    setExpectedMap()
-    setFilePathMap()
+    end while
+
 end function

package/dist/lib/framework/components/rooibos/CodeCoverage.xml

@@ -1,11 +1,13 @@
-<component name="CodeCoverage" extends="ContentNode">
+<?xml version="1.0" encoding="UTF-8"?>
+<component name="CodeCoverage"
+           extends="Task"
+>
     <script type="text/brightscript" uri="CodeCoverage.brs" />
 
     <interface>
         <field id="entry" type="assocarray" />
+        <field id="coverageResults" type="assocarray" />
+
         <field id="save" type="boolean" />
-        <field id="expectedMap" type="assocarray" />
-        <field id="resolvedMap" type="assocarray" />
-        <field id="filePathMap" type="assocarray" />
     </interface>
 </component>