28191818298

Committed 25 Jun 2026 06:29PM UTC coverage: 70.995% (+0.06%) from 70.938%

Build # 28191818298

Build Type

Pull #378

github

Committed by

web-flow

Commit Message

Merge 193653c0d into 456a8fdc5

Pull Request Pull Request #378: Add per-component-library option to disable file postfixing

Coverage Stats

3530 of 5249 branches covered (67.25%)

Branch coverage included in aggregate %.

15 of 15 new or added lines in 1 file covered. (100.0%)

1 existing line in 1 file now uncovered.

5727 of 7790 relevant lines covered (73.52%)

45.61 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

81.09

/src/managers/ProjectManager.ts

import * as fsExtra from 'fs-extra';
import * as path from 'path';
import { rokuDeploy, RokuDeploy, util as rokuDeployUtil } from 'roku-deploy';
import type { FileEntry } from 'roku-deploy';
import * as fastGlob from 'fast-glob';
import type { BreakpointManager } from './BreakpointManager';
import { fileUtils, standardizePath as s } from '../FileUtils';
import type { LocationManager, SourceLocation } from './LocationManager';
import { util } from '../util';
import { logger } from '../logging';
import { Cache } from 'brighterscript/dist/Cache';
import { BscProjectThreaded } from '../bsc/BscProjectThreaded';
import type { ScopeFunction } from '../bsc/BscProject';
import type { Position } from 'brighterscript';
import type { SourceMapPayload } from 'module';

// eslint-disable-next-line @typescript-eslint/no-var-requires, @typescript-eslint/no-require-imports
const replaceInFile = require('replace-in-file');

export const componentLibraryPostfix = '__lib';

/**
 * Staging info for a single project, used when describing all projects to a client.
 */
export interface ProjectStagingInfo {
    /**
     * The kind of project. `main` is the application project (always exactly one); `componentLibrary`
     * is a component library project.
     */
    type: 'main' | 'componentLibrary';
    /**
     * Absolute path to the project's staging directory.
     */
    stagingDir: string;
}

/**
 * Manages the collection of brightscript projects being used in a debug session.
 * Will contain the main project (in rootDir), as well as component libraries.
 */
export class ProjectManager {
    public constructor(
        options: {
            /**
             * A class that keeps track of all the breakpoints for a debug session.
             * It needs to be notified of any changes in breakpoints
             */
            breakpointManager: BreakpointManager;
            locationManager: LocationManager;
        }
    ) {
        this.breakpointManager = options.breakpointManager;
        this.locationManager = options.locationManager;
    }

    private breakpointManager: BreakpointManager;

    private locationManager: LocationManager;

    public launchConfiguration: {
        enableSourceMaps?: boolean;
        enableDebugProtocol?: boolean;
        packagePath: string;
    };

    public logger = logger.createLogger('[ProjectManager]');

    public mainProject: Project;
    public componentLibraryProjects = [] as ComponentLibraryProject[];

    public addComponentLibraryProject(project: ComponentLibraryProject) {
        this.componentLibraryProjects.push(project);
    }

    public getAllProjects() {
        return [
            ...(this.mainProject ? [this.mainProject] : []),
            ...(this.componentLibraryProjects ?? [])
        ];
    }

    /**
     * Get the list of staging folder paths from all projects
     */
    public getStagingDirs() {
        let projects = [
            ...(this.mainProject ? [this.mainProject] : []),
            ...(this.componentLibraryProjects ?? [])
        ];
        return projects.map(x => x.stagingDir);
    }

    /**
     * Get staging-dir info for every project. The main project is always first; component libraries
     * follow in order. This main-first ordering is a contract that clients rely on, so it is covered
     * by unit tests to guard against regressions.
     */
    public getProjectStagingInfo(): ProjectStagingInfo[] {
        return this.getAllProjects().map((project) => ({
            type: project instanceof ComponentLibraryProject ? 'componentLibrary' : 'main',
            stagingDir: project.stagingDir
        }));
    }

    /**
     * Get all of the functions avaiable for all scopes for this file.
     * @param pkgPath the device path of the file (probably with `pkg:` or `libpkg` or something...)
     * @returns
     */
    public async getScopeFunctionsForFile(pkgPath: string): Promise<Array<ScopeFunction>> {
        let completions: ScopeFunction[] = [];
        try {
            const fileInfo = await this.getStagingFileInfo(pkgPath);
            completions = await fileInfo?.project.getScopeFunctionsForFile(fileInfo.relativePath);
        } catch (error) {
            this.logger.error(`error loading completions for file ${pkgPath}`, error);
        }
        return completions;
    }

    /**
     * Get the range of the scope for the given position in the file
     * @param pkgPath the device path of the file (probably with `pkg:` or `libpkg` or something...)
     * @param position the position in the file to get the scope range for
     */
    public async getScopeRange(pkgPath: string, position: Position) {
        try {
            const fileInfo = await this.getStagingFileInfo(pkgPath);
            const parentFunctionRange = await fileInfo?.project.getScopeRange(fileInfo.relativePath, position);
            if (parentFunctionRange) {
                const [startPosition, endPosition] = await Promise.all([
                    this.getSourceLocation(pkgPath, parentFunctionRange.start.line + 1),
                    this.getSourceLocation(pkgPath, parentFunctionRange.end.line + 1)
                ]);
                return {
                    start: {
                        line: startPosition.lineNumber,
                        column: startPosition.columnIndex
                    },
                    end: {
                        line: endPosition.lineNumber,
                        column: endPosition.columnIndex
                    }
                };
            }
        } catch (error) {
            this.logger.error(`error loading scope range for file ${pkgPath}`, error);
        }
        return undefined;
    }

    /**
     * Given a debugger path and line number, compensate for the injected breakpoint line offsets
     * @param filePath - the path to the file that may or may not have breakpoints
     * @param debuggerLineNumber - the line number from the debugger
     */
    public getLineNumberOffsetByBreakpoints(filePath: string, debuggerLineNumber: number) {
        let breakpoints = this.breakpointManager.getPermanentBreakpointsForFile(filePath);
        //throw out duplicate breakpoints (account for entry breakpoint) and sort them ascending
        breakpoints = this.breakpointManager.sortAndRemoveDuplicateBreakpoints(breakpoints);

        let sourceLineByDebuggerLine = {};
        let sourceLineNumber = 0;
        for (let loopDebuggerLineNumber = 1; loopDebuggerLineNumber <= debuggerLineNumber; loopDebuggerLineNumber++) {
            sourceLineNumber++;
            sourceLineByDebuggerLine[loopDebuggerLineNumber] = sourceLineNumber;

            /**
             * A line with a breakpoint on it should share the same debugger line number.
             * The injected `STOP` line will be given the correct line number automatically,
             * but we need to compensate for the actual code line. So if there's a breakpoint
             * on this line, handle the next line's mapping as well (and skip one iteration of the loop)
             */
            // eslint-disable-next-line @typescript-eslint/no-loop-func
            let breakpointForLine = breakpoints.find(x => x.line === sourceLineNumber);
            if (breakpointForLine) {
                sourceLineByDebuggerLine[loopDebuggerLineNumber + 1] = sourceLineNumber;
                loopDebuggerLineNumber++;
            }
        }

        return sourceLineByDebuggerLine[debuggerLineNumber];
    }

    public sourceLocationCache = new Cache<string, Promise<SourceLocation>>();

    /**
     * @param debuggerPath
     * @param debuggerLineNumber - the 1-based line number from the debugger
     * @param debuggerColumnNumber - the 1-based column number from the debugger
     */
    public async getSourceLocation(debuggerPath: string, debuggerLineNumber: number, debuggerColumnNumber = 1) {
        return this.sourceLocationCache.getOrAdd(`${debuggerPath}-${debuggerLineNumber}`, async () => {
            //get source location using
            let stagingFileInfo = await this.getStagingFileInfo(debuggerPath);
            if (!stagingFileInfo) {
                return;
            }
            let project = stagingFileInfo.project;

            //remove the component library postfix if present
            if (project instanceof ComponentLibraryProject) {
                stagingFileInfo.absolutePath = fileUtils.unPostfixFilePath(stagingFileInfo.absolutePath, project.postfix);
                stagingFileInfo.relativePath = fileUtils.unPostfixFilePath(stagingFileInfo.relativePath, project.postfix);
            }

            let sourceLocation = await this.locationManager.getSourceLocation({
                lineNumber: debuggerLineNumber,
                columnIndex: debuggerColumnNumber - 1,
                fileMappings: project.fileMappings,
                rootDir: project.rootDir,
                stagingFilePath: stagingFileInfo.absolutePath,
                stagingDir: project.stagingDir,
                sourceDirs: project.sourceDirs,
                enableSourceMaps: this.launchConfiguration?.enableSourceMaps ?? true
            });

            //if sourcemaps are disabled, and this is a telnet debug dession, account for breakpoint offsets
            if (sourceLocation && this.launchConfiguration?.enableSourceMaps === false && !this.launchConfiguration.enableDebugProtocol) {
                sourceLocation.lineNumber = this.getLineNumberOffsetByBreakpoints(sourceLocation.filePath, sourceLocation.lineNumber);
            }

            if (!sourceLocation?.filePath) {
                //couldn't find a source location. At least send back the staging file information so the user can still debug
                return {
                    filePath: stagingFileInfo.absolutePath,
                    lineNumber: sourceLocation?.lineNumber || debuggerLineNumber,
                    columnIndex: debuggerColumnNumber - 1
                } as SourceLocation;
            } else {
                return sourceLocation;
            }
        });
    }

    /**
     *
     * @param stagingDir - the path to
     */
    public async registerEntryBreakpoint(stagingDir: string) {
        //find the main function from the staging flder
        let entryPoint = await fileUtils.findEntryPoint(stagingDir);

        //convert entry point staging location to source location
        let sourceLocation = await this.getSourceLocation(entryPoint.relativePath, entryPoint.lineNumber);

        this.logger.info(`Registering entry breakpoint at ${sourceLocation.filePath}:${sourceLocation.lineNumber} (${entryPoint.pathAbsolute}:${entryPoint.lineNumber})`);
        //register the entry breakpoint
        this.breakpointManager.setBreakpoint(sourceLocation.filePath, {
            //+1 to select the first line of the function
            line: sourceLocation.lineNumber + 1
        });
    }

    /**
     * Given a debugger-relative file path, find the path to that file in the staging directory.
     * This supports the standard out dir, as well as component library out dirs
     * @param debuggerPath the path to the file which was provided by the debugger
     * @param stagingDir - the path to the root of the staging folder (where all of the files were copied before deployment)
     * @return a full path to the file in the staging directory
     */
    public async getStagingFileInfo(debuggerPath: string) {
        let componentLibraryIndex = fileUtils.getComponentLibraryIndexFromFileName(debuggerPath, componentLibraryPostfix);

        //the path carries a `__lib<index>` postfix, so we know exactly which component library it belongs to
        if (componentLibraryIndex !== undefined) {
            let lib = this.componentLibraryProjects.find(x => x.libraryIndex === componentLibraryIndex);
            if (!lib) {
                throw new Error(`There is no component library with index ${componentLibraryIndex}`);
            }
            return this.buildStagingFileInfo(debuggerPath, lib);
        }

        //No `__lib<index>` postfix on the path. It's either a main-project file, or a file from a
        //component library that has postfixing disabled (those report device paths that look identical
        //to the main project's). Try the main project first.
        let stagingFileInfo = await this.buildStagingFileInfo(debuggerPath, this.mainProject);

        //if the file actually exists in the main project, use it
        if (stagingFileInfo && await fsExtra.pathExists(stagingFileInfo.absolutePath)) {
            return stagingFileInfo;
        }

        //otherwise, fall back to any component library that has postfixing disabled, since those are the
        //only other source of un-postfixed device paths. Use the first one that has the file on disk.
        for (const lib of this.componentLibraryProjects) {
            if (lib.enablePostfix === false) {
                const libStagingFileInfo = await this.buildStagingFileInfo(debuggerPath, lib);
                if (libStagingFileInfo && await fsExtra.pathExists(libStagingFileInfo.absolutePath)) {
                    return libStagingFileInfo;
                }
            }
        }

        //nothing matched on disk; preserve prior behavior by returning the main-project result (if any)
        return stagingFileInfo;
    }

    /**
     * Resolve a debugger-reported path to a staging file within a specific project. Returns undefined if the
     * path could not be mapped into that project's staging directory.
     */
    private async buildStagingFileInfo(debuggerPath: string, project: Project) {
        let relativePath: string;

        //if the path starts with a scheme (i.e. pkg:/ or complib:/), we have an exact match.
        if (util.getFileScheme(debuggerPath)) {
            relativePath = util.removeFileScheme(debuggerPath);
        } else {
            relativePath = await fileUtils.findPartialFileInDirectory(debuggerPath, project.stagingDir);
        }
        if (relativePath) {
            relativePath = fileUtils.removeLeadingSlash(
                fileUtils.standardizePath(relativePath)
            );
            return {
                relativePath: relativePath,
                absolutePath: s`${project.stagingDir}/${relativePath}`,
                project: project
            };
        } else {
            return undefined;
        }
    }

    public dispose() {
        util.applyDispose(this.getAllProjects());
    }
}

export interface AddProjectParams {
    rootDir: string;
    outDir: string;
    packagePath?: string;
    sourceDirs?: string[];
    files: Array<FileEntry>;
    injectRaleTrackerTask?: boolean;
    raleTrackerTaskFileLocation?: string;
    injectRdbOnDeviceComponent?: boolean;
    rdbFilesBasePath?: string;
    bsConst?: Record<string, boolean>;
    stagingDir?: string;
    enhanceREPLCompletions: boolean;
}

export class Project {
    constructor(params: AddProjectParams) {
        if (!params?.rootDir) {
            throw new Error('rootDir is required');
        }
        this.rootDir = fileUtils.standardizePath(params.rootDir);

        if (!params?.outDir) {
            throw new Error('outDir is required');
        }
        this.outDir = fileUtils.standardizePath(params.outDir);
        this.stagingDir = params.stagingDir ?? rokuDeploy.getOptions(this).stagingDir;
        this.bsConst = params.bsConst;
        this.sourceDirs = (params.sourceDirs ?? [])
            //standardize every sourcedir
            .map(x => fileUtils.standardizePath(x));
        this.injectRaleTrackerTask = params.injectRaleTrackerTask ?? false;
        this.raleTrackerTaskFileLocation = params.raleTrackerTaskFileLocation;
        this.injectRdbOnDeviceComponent = params.injectRdbOnDeviceComponent ?? false;
        this.rdbFilesBasePath = params.rdbFilesBasePath;
        this.files = params.files ?? [];
        this.packagePath = params.packagePath;
        this.enhanceREPLCompletions = params.enhanceREPLCompletions;
    }
    public rootDir: string;
    public outDir: string;
    public packagePath: string;
    public sourceDirs: string[];
    public files: Array<FileEntry>;
    public stagingDir: string;
    public fileMappings: Array<{ src: string; dest: string }>;

    /**
     * Absolute staging paths of every file referenced by a `<script uri="...">` tag in any staged XML
     * component. Roku loads these as BrightScript regardless of file extension, so they are valid
     * breakpoint targets even when they don't end in `.brs`. Populated during `stage()` (the single
     * staging-file walk in `preprocessStagingFiles`) so consumers don't have to re-scan the staging dir.
     */
    public scriptReferencedFiles = new Set<string>();
    public bsConst: Record<string, boolean>;
    public injectRaleTrackerTask: boolean;
    public raleTrackerTaskFileLocation: string;
    public injectRdbOnDeviceComponent: boolean;
    public rdbFilesBasePath: string;
    public enhanceREPLCompletions: boolean;

    /**
     * A BrighterScript project for the stagingDir
     */
    private stagingBscProject = new BscProjectThreaded();

    //the default project doesn't have a postfix, but component libraries will have a postfix, so just use empty string to standardize the postfix logic
    public get postfix() {
        return '';
    }

    private logger = logger.createLogger(`[${ProjectManager.name}]`);

    public async stage() {
        if (!this.fileMappings) {
            this.fileMappings = await this.getFileMappings();
        }

        //copy all project files to the staging folder
        await rokuDeploy.prepublishToStaging({
            rootDir: this.rootDir,
            stagingDir: this.stagingDir,
            files: this.fileMappings,
            outDir: this.outDir,
            //we already fetched the file mappings ourselves, so roku-deploy doesn't need to glob the files again
            resolveFilesArray: false
        });

        await this.preprocessStagingFiles();

        if (this.enhanceREPLCompletions) {
            //activate our background brighterscript ProgramBuilder now that the staging directory contains the final production project
            this.stagingBscProject.activate({
                rootDir: this.stagingDir,
                files: ['**/*'],
                watch: false,
                createPackage: false,
                deploy: false,
                copyToStaging: false,
                showDiagnosticsInConsole: false,
                logLevel: 'error',
                //this project is only used for file and scope lookups, so skip all validations since that takes a while and we don't care
                validate: false
            }).catch((e) => {
                this.logger.error('Error activating staging project.', e);
            });
        }

        //preload the original location of every file
        await this.resolveFileMappingsForSourceDirs();

        await this.transformManifestWithBsConst();

        await this.copyAndTransformRaleTrackerTask();

        await this.copyAndTransformRDB();
    }

    /**
     * Get all of the functions available for all scopes for this file.
     * @param relativePath path to the file relative to rootDir
     * @returns
     */
    public getScopeFunctionsForFile(relativePath: string) {
        if (this.enhanceREPLCompletions && this.stagingBscProject?.isActivated) {
            return this.stagingBscProject.getScopeFunctionsForFile({ relativePath: relativePath });
        } else {
            return [];
        }
    }

    /**
     * Get the range of the scope for the given position in the file
     * @param relativePath path to the file relative to rootDir
     * @param position the position in the file to get the scope range for
     */
    public async getScopeRange(relativePath: string, position: Position) {
        if (this.stagingBscProject?.isActivated) {
            return this.stagingBscProject.getScopeRange({ relativePath: relativePath, position: position });
        } else {
            return undefined;
        }
    }

    /**
     * If the project uses sourceDirs, replace every `fileMapping.src` with its original location in sourceDirs
     */
    private resolveFileMappingsForSourceDirs() {
        return Promise.all([
            this.fileMappings.map(async x => {
                let stagingFilePathRelative = fileUtils.getRelativePath(this.stagingDir, x.dest);
                let sourceDirFilePath = await fileUtils.findFirstRelativeFile(stagingFilePathRelative, this.sourceDirs);
                if (sourceDirFilePath) {
                    x.src = sourceDirFilePath;
                }
            })
        ]);
    }

    /**
     * Walk every staged file once and apply all necessary rewrites for files that were moved
     * from a different source location:
     *  - .map files: rewrite `sources` paths to be relative to the new staging location
     *  - .brs/.xml files: rewrite the sourceMappingURL comment path to point to the staged map
     */
    private async preprocessStagingFiles() {
        const srcToDestMap = new Map<string, string>();
        const destToSrcMap = new Map<string, string>();
        for (const mapping of this.fileMappings) {
            srcToDestMap.set(mapping.src, mapping.dest);
            destToSrcMap.set(mapping.dest, mapping.src);
        }

        //reset before re-scanning
        this.scriptReferencedFiles.clear();

        //walk over every file
        const stagedFiles: string[] = (await fastGlob('**/*', { cwd: this.stagingDir, absolute: true, onlyFiles: true }))
            .map((f: string) => fileUtils.standardizePath(f));

        await Promise.all(stagedFiles.map(async (stagingFilePath: string) => {
            const ext = path.extname(stagingFilePath).toLowerCase();
            const originalSrcPath = destToSrcMap.get(stagingFilePath);

            //.map files are handled separately (they get their own JSON read), and never need the
            //text-content path below. Skip maps that aren't in fileMappings (generated after staging).
            if (ext === '.map') {
                if (originalSrcPath) {
                    await this.fixSourceMapSources({
                        stagingMapPath: stagingFilePath,
                        originalMapPath: originalSrcPath
                    });
                }
                return;
            }

            //read each text file at most once and share the contents between the two consumers below:
            // - collectScriptReferencedFiles: runs for ALL staged xml (a component may be generated during
            //   staging, so it isn't necessarily in fileMappings)
            // - fixSourceMapComment: runs only for files that were moved from a source dir (in fileMappings)
            //binary files need neither, so we never read them.
            const isXml = ext === '.xml';
            const needsCommentFix = !!originalSrcPath;
            if (Project.binaryExtensions.has(ext) || (!isXml && !needsCommentFix)) {
                return;
            }

            let contents: string;
            try {
                contents = await fsExtra.readFile(stagingFilePath, 'utf8');
            } catch (e) {
                this.logger.debug('Error reading staged file during preprocess', { stagingFilePath, error: e });
                return;
            }

            if (isXml) {
                this.collectScriptReferencedFiles(stagingFilePath, contents);
            }
            if (needsCommentFix) {
                await this.fixSourceMapComment(stagingFilePath, originalSrcPath, srcToDestMap, contents);
            }
        }));
    }

    /**
     * Parse a staged XML file's contents for `<script uri="...">` tags and add each referenced file's
     * absolute staging path to {@link scriptReferencedFiles}. `pkg:/`/`libpkg:/` uris resolve from the
     * staging root; bare relative uris resolve from the XML file's own directory. Roku loads these as
     * BrightScript regardless of extension, so they are valid breakpoint targets.
     * @param contents the already-loaded file contents (read once by the staging walk)
     */
    private collectScriptReferencedFiles(xmlStagingPath: string, contents: string) {
        const scriptUriRegex = /<script\b[^>]*\buri\s*=\s*"([^"]*)"[^>]*\/?>/gi;
        let match: RegExpExecArray;
        while ((match = scriptUriRegex.exec(contents)) !== null) {
            const uri = match[1];
            const protocolIndex = uri.indexOf(':/');
            let absolutePath: string;
            if (protocolIndex >= 0) {
                //pkg:/ or libpkg:/ — resolve from staging root
                const relativePath = uri.substring(protocolIndex + 2).replace(/^\//, '');
                absolutePath = s`${this.stagingDir}/${relativePath}`;
            } else {
                //relative path — resolve from the XML file's directory
                absolutePath = s`${path.resolve(path.dirname(xmlStagingPath), uri)}`;
            }
            this.scriptReferencedFiles.add(absolutePath);
        }
    }

    /**
     * Per-path write locks. Async file ops interleave (e.g. `preprocessStagingFiles` fans out
     * tasks that can target the same staging `.map`), so we queue all writes to a given path
     * through a single promise chain. Entries clean themselves up once their chain is idle.
     */
    private writeLocks = new Map<string, Promise<unknown>>();

    private serializeWrite<T>(filePath: string, work: () => Promise<T>): Promise<T> {
        const key = fileUtils.standardizePath(filePath).toLowerCase();
        const prev = this.writeLocks.get(key) ?? Promise.resolve();
        //run work whether the prior op resolved or rejected — failures upstream shouldn't poison the chain
        const next = prev.then(work, work);
        this.writeLocks.set(key, next);
        //drop the entry once nothing else has chained onto it
        void next.catch(() => { /* swallow — caller's await sees the real error */ }).then(() => {
            if (this.writeLocks.get(key) === next) {
                this.writeLocks.delete(key);
            }
        });
        return next;
    }

    /**
     * Serialized wrapper around `fsExtra.writeFile`. Use in place of `fsExtra.writeFile` anywhere
     * a path might also be written by another concurrent task in this Project.
     */
    private writeFile(filePath: string, data: Parameters<typeof fsExtra.writeFile>[1], options?: Parameters<typeof fsExtra.writeFile>[2]) {
        return this.serializeWrite(filePath, () => fsExtra.writeFile(filePath, data, options));
    }

    /**
     * Serialized wrapper around `fsExtra.copyFile`. The dest path is the one we serialize on,
     * since that's what gets written.
     */
    private copyFile(srcPath: string, destPath: string) {
        return this.serializeWrite(destPath, () => fsExtra.copyFile(srcPath, destPath));
    }

    /**
     * Rewrite the `sources` paths in a staged .map file so they are relative to the map's
     * new staging location rather than the original source directory.
     */
    private async fixSourceMapSources(params: { stagingMapPath: string; originalMapPath: string }) {
        const { stagingMapPath, originalMapPath } = params;

        try {
            const sourceMap = await fsExtra.readJsonSync(stagingMapPath) as SourceMapPayload;
            if (!Array.isArray(sourceMap.sources) || sourceMap.sources.length === 0) {
                return;
            }
            // Resolve sources relative to original map's base dir (honoring sourceRoot if present)
            const originalBaseDir = path.resolve(
                //sourceRoot should resolve relative to originalMapDir, or keep as-is when absolute path
                path.dirname(originalMapPath),
                sourceMap.sourceRoot ?? ''
            );

            const stagingMapDir = path.dirname(stagingMapPath);

            sourceMap.sources = sourceMap.sources.map((source) => {
                const absoluteSourcePath = path.resolve(originalBaseDir, source);
                return fileUtils.standardizePath(path.relative(stagingMapDir, absoluteSourcePath));
            });

            // Clear sourceRoot since sources are now relative to the map file's new location
            delete sourceMap.sourceRoot;

            await this.writeFile(stagingMapPath, JSON.stringify(sourceMap));
        } catch (e) {
            this.logger.error(`Error updating source map sources for '${stagingMapPath}'`, e);
        }
    }


    public static readonly binaryExtensions = new Set([
        // images
        '.jpg', '.jpeg', '.png', '.gif', '.bmp', '.webp', '.tiff', '.tif', '.ico', '.svg',
        '.heic', '.heif', '.avif', '.raw', '.cr2', '.nef', '.arw', '.dng',
        // video
        '.mp4', '.mkv', '.mov', '.avi', '.wmv', '.flv', '.webm', '.m4v', '.mpg', '.mpeg',
        '.m2v', '.ts', '.mts', '.m2ts', '.vob', '.ogv', '.3gp', '.3g2',
        // audio
        '.mp3', '.wav', '.aac', '.ogg', '.flac', '.m4a', '.wma', '.opus', '.aiff', '.aif',
        // fonts
        '.ttf', '.otf', '.woff', '.woff2', '.eot',
        // archives / binary containers
        '.zip', '.gz', '.tar', '.bz2', '.xz', '.7z', '.rar', '.pkg', '.exe', '.dll', '.so',
        // documents / other binary formats
        '.pdf', '.psd', '.ai', '.eps', '.indd',
        // roku-specific
        '.roku', '.rdb', '.squashfs'
    ]);

    /**
     * Extracts the sourceMappingURL comment from the given file contents.
     *
     * `match[3]` is the path (which may be relative or absolute)
     * @param contents
     * @returns
     */
    public static getSourceMapComment(contents: string) {

        //https://regex101.com/r/FMRJNy/2
        const commentMatch = [
            ...contents.matchAll(/^([ \t]*(?:'|<!--)?[ \t]*)((?:\/\/)?[ \t]*[#@][ \t]*sourceMappingURL=(.+\b))(?:|-->)?/gm)
        ].pop();
        if (commentMatch) {
            return {
                /**
                 * The entire matched comment, including any leading whitespace and comment characters (e.g. `'` or `<!--`), which should be preserved when rewriting the comment
                 */
                fullMatch: commentMatch?.[0],
                /**
                 * The leading whitespace and comment characters (e.g. `'` or `<!--`) before the actual `sourceMappingURL` text, which should be preserved when rewriting the comment
                 */
                leadingInfo: commentMatch?.[1],
                /**
                 * The entire comment text without the leadingInfo (e.g. `//# sourceMappingURL=someFile.map`)
                 */
                wholeComment: commentMatch?.[2],
                /**
                 * The path to the source map file (e.g. `someFile.map`)
                 */
                mapPath: commentMatch?.[3]
            };
        } else {
            return undefined;
        }
    }

    /**
     * Rewrite the sourceMappingURL comment in a staged .brs or .xml file so the path points
     * to the map file's new staging location.
     *
     * Recognised comment forms (# and legacy @ are both accepted; // is optional for brs/xml):
     *   BRS:   ' [//] [#|@] sourceMappingURL=<path>
     *   XML:   <!-- [//] [#|@] sourceMappingURL=<path> -->
     *   other: // \s* [#|@] sourceMappingURL=<path>
     *
     * When rewriting, the canonical modern form is always written:
     *   BRS:   '//# sourceMappingURL=<path>
     *   XML:   <!--//# sourceMappingURL=<path> -->
     *   other: //# sourceMappingURL=<path>
     */
    private async fixSourceMapComment(stagingFilePath: string, originalSrcPath: string, srcToDestMap: Map<string, string>, contents: string) {
        try {
            const commentMatch = Project.getSourceMapComment(contents);

            let absoluteMapPath: string;

            if (commentMatch) {
                absoluteMapPath = fileUtils.standardizePath(
                    path.isAbsolute(commentMatch.mapPath)
                        ? commentMatch.mapPath
                        : path.resolve(path.dirname(originalSrcPath), commentMatch.mapPath)
                );

                //copy the sourcemap right next to our file in staging
                absoluteMapPath = await this.colocateSourceMap({
                    absoluteMapPath: absoluteMapPath,
                    stagingFilePath: stagingFilePath
                });

            } else {
                // No comment — check if a colocated map exists next to the original source file
                absoluteMapPath = fileUtils.standardizePath(originalSrcPath + '.map');

                //there is no colocated map next to the original source file
                if (!await fsExtra.pathExists(absoluteMapPath)) {
                    return;
                }

                //copy the sourcemap right next to our file in staging — the debugger will find it automatically
                await this.colocateSourceMap({
                    absoluteMapPath: absoluteMapPath,
                    stagingFilePath: stagingFilePath
                });
                return;
            }

            // If the map was also staged, point at its new location; otherwise point back at the original
            const mapTarget = srcToDestMap.get(absoluteMapPath) ?? absoluteMapPath;
            const newRelativePath = fileUtils.standardizePath(
                path.relative(path.dirname(stagingFilePath), mapTarget)
            );

            const newComment = `${commentMatch.leadingInfo.trimEnd()}//# sourceMappingURL=${newRelativePath}`;
            contents = contents.replace(commentMatch.fullMatch, newComment);
            await this.writeFile(stagingFilePath, contents, 'utf8');
        } catch (e) {
            this.logger.error(`Error updating sourceMappingURL comment in '${stagingFilePath}'`, e);
        }
    }

    private async colocateSourceMap(options: { stagingFilePath: string; absoluteMapPath: string }) {
        //copy the sourcemap right next to our file (skip if it's already there)
        const stagingMapPath = `${options.stagingFilePath}.map`;
        if (fileUtils.standardizePath(options.absoluteMapPath) !== fileUtils.standardizePath(stagingMapPath)) {
            await this.copyFile(options.absoluteMapPath, stagingMapPath);
        }
        await this.fixSourceMapSources({
            stagingMapPath: stagingMapPath,
            originalMapPath: options.absoluteMapPath
        });
        return stagingMapPath;
    }


    /**
     * Apply the bsConst transformations to the manifest file for this project
     */
    public async transformManifestWithBsConst() {
        if (this.bsConst) {
            let manifestPath = s`${this.stagingDir}/manifest`;
            if (await fsExtra.pathExists(manifestPath)) {
                // Update the bs_const values in the manifest in the staging folder before side loading the channel
                let fileContents = (await fsExtra.readFile(manifestPath)).toString();
                fileContents = this.updateManifestBsConsts(this.bsConst, fileContents);
                await this.writeFile(manifestPath, fileContents);
            }
        }
    }

    public updateManifestBsConsts(consts: Record<string, boolean>, fileContents: string): string {
        let bsConstLine: string;
        let missingConsts: string[] = [];
        let lines = fileContents.split(/\r?\n/g);

        let newLine: string;
        //loop through the lines until we find the bs_const line if it exists
        for (const line of lines) {
            if (line.toLowerCase().startsWith('bs_const')) {
                bsConstLine = line;
                newLine = line;
                break;
            }
        }

        if (bsConstLine) {
            // update the consts in the manifest and check for missing consts
            missingConsts = Object.keys(consts).reduce((results, key) => {
                let match = new RegExp('(' + key + '\\s*=\\s*[true|false]+[^\\S\\r\\n]*\)', 'i').exec(bsConstLine);
                if (match) {
                    newLine = newLine.replace(match[1], `${key}=${consts[key].toString()}`);
                } else {
                    results.push(key);
                }

                return results;
            }, []);

            // check for consts that where not in the manifest
            if (missingConsts.length > 0) {
                throw new Error(`The following bs_const keys were not defined in the channel's manifest:\n\n${missingConsts.join(',\n')}`);
            } else {
                // update the manifest contents
                return fileContents.replace(bsConstLine, newLine);
            }
        } else {
            throw new Error('bs_const was defined in the launch.json but not in the channel\'s manifest');
        }
    }

    public static RALE_TRACKER_TASK_CODE = `if true = CreateObject("roAppInfo").IsDev() then m.vscode_rale_tracker_task = createObject("roSGNode", "TrackerTask") ' Roku Advanced Layout Editor Support`;
    public static RALE_TRACKER_ENTRY = 'vscode_rale_tracker_entry';
    /**
     * Search the project files for the comment "' vscode_rale_tracker_entry" and replace it with the code needed to start the TrackerTask.
     */
    public async copyAndTransformRaleTrackerTask() {
        // inject the tracker task into the staging files if we have everything we need
        if (!this.injectRaleTrackerTask || !this.raleTrackerTaskFileLocation) {
            return;
        }
        try {
            await fsExtra.copy(this.raleTrackerTaskFileLocation, s`${this.stagingDir}/components/TrackerTask.xml`);
            this.logger.log('Tracker task successfully injected');
            // Search for the tracker task entry injection point
            const trackerReplacementResult = await replaceInFile({
                files: `${this.stagingDir}/**/*.+(xml|brs)`,
                from: new RegExp(`^.*'\\s*${Project.RALE_TRACKER_ENTRY}.*$`, 'mig'),
                to: (match: string) => {
                    // Strip off the comment
                    let startOfLine = match.substring(0, match.indexOf(`'`));
                    if (/[\S]/.exec(startOfLine)) {
                        // There was some form of code before the tracker entry
                        // append and use single line syntax
                        startOfLine += ': ';
                    }
                    return `${startOfLine}${Project.RALE_TRACKER_TASK_CODE}`;
                }
            });
            const injectedFiles = trackerReplacementResult
                .filter(result => result.hasChanged)
                .map(result => result.file);

            if (injectedFiles.length === 0) {
                console.error(`WARNING: Unable to find an entry point for Tracker Task.\nPlease make sure that you have the following comment in your BrightScript project: "\' ${Project.RALE_TRACKER_ENTRY}"`);
            }
        } catch (err) {
            console.error(err);
        }
    }

    public static RDB_ODC_NODE_CODE = `if true = CreateObject("roAppInfo").IsDev() then m.vscode_rdb_odc_node = createObject("roSGNode", "RTA_OnDeviceComponent") ' RDB OnDeviceComponent`;
    public static RDB_ODC_ENTRY = 'vscode_rdb_on_device_component_entry';
    /**
     * Search the project files for the RTA_ODC_ENTRY comment and replace it with the code needed to start RTA_OnDeviceComponent which is used by RDB.
     */
    public async copyAndTransformRDB() {
        // inject the on device component into the staging files if we have everything we need
        if (!this.injectRdbOnDeviceComponent || !this.rdbFilesBasePath) {
            return;
        }
        try {

            let files: string[] = await fastGlob(
                //fast-glob requires forward slashes, so convert any backslashes in the provided path to forward slashes before globbing
                `${this.rdbFilesBasePath}/**/*`.replace(/[\\/]+/g, '/'),
                {
                    cwd: './',
                    absolute: false,
                    followSymbolicLinks: true
                }
            );
            for (let filePathAbsolute of files) {
                const promises = [];
                //only include files (i.e. skip directories)
                if (await util.isFile(filePathAbsolute)) {
                    const relativePath = s`${filePathAbsolute}`.replace(s`${this.rdbFilesBasePath}`, '');
                    const destinationPath = s`${this.stagingDir}/${relativePath}`;
                    promises.push(fsExtra.copy(filePathAbsolute, destinationPath));
                }
                await Promise.all(promises);
                this.logger.log('RDB OnDeviceComponent successfully injected');
            }

            // Search for the tracker task entry injection point
            const replacementResult = await replaceInFile({
                files: `${this.stagingDir}/**/*.+(xml|brs)`,
                from: new RegExp(`^.*'\\s*${Project.RDB_ODC_ENTRY}.*$`, 'mig'),
                to: (match: string) => {
                    // Strip off the comment
                    let startOfLine = match.substring(0, match.indexOf(`'`));
                    if (/[\S]/.exec(startOfLine)) {
                        // There was some form of code before the tracker entry
                        // append and use single line syntax
                        startOfLine += ': ';
                    }
                    return `${startOfLine}${Project.RDB_ODC_NODE_CODE}`;
                }
            });
            const injectedFiles = replacementResult
                .filter(result => result.hasChanged)
                .map(result => result.file);

            if (injectedFiles.length === 0) {
                console.error(`WARNING: Unable to find an entry point for RDB.\nPlease make sure that you have the following comment in your BrightScript project: "\' ${Project.RDB_ODC_ENTRY}"`);
            }
        } catch (err) {
            console.error(err);
        }
    }

    /**
     *
     * @param stagingPath
     */
    public async zipPackage(params: { retainStagingFolder: boolean }) {
        const options = rokuDeploy.getOptions({
            ...this,
            ...params
        });

        let packagePath = this.packagePath;
        if (!this.packagePath) {
            //make sure the output folder exists
            await fsExtra.ensureDir(options.outDir);

            packagePath = rokuDeploy.getOutputZipFilePath(options);
        }

        //ensure the manifest file exists in the staging folder
        if (!await rokuDeployUtil.fileExistsCaseInsensitive(`${options.stagingDir}/manifest`)) {
            throw new Error(`Cannot zip package: missing manifest file in "${options.stagingDir}"`);
        }

        // create a zip of the staging folder
        await rokuDeploy.zipFolder(options.stagingDir, packagePath, undefined, [
            '**/*',
            //exclude sourcemap files (they're large and can't be parsed on-device anyway...)
            '!**/*.map'
        ]);

        //delete the staging folder unless told to retain it.
        if (options.retainStagingDir !== true) {
            await fsExtra.remove(options.stagingDir);
        }
    }

    /**
     * Get the file paths from roku-deploy, and ensure the dest paths are absolute
     * (`dest` paths are relative in later versions of roku-deploy)
     */
    protected async getFileMappings() {
        let fileMappings = await rokuDeploy.getFilePaths(this.files, this.rootDir, true, this.stagingDir);
        return fileMappings;
    }

    public dispose() {
        this.stagingBscProject?.dispose?.();
    }
}

export interface ComponentLibraryConstructorParams extends AddProjectParams {
    outFile: string;
    libraryIndex: number;
    install?: boolean;
    enablePostfix?: boolean;
}

export class ComponentLibraryProject extends Project {
    constructor(params: ComponentLibraryConstructorParams) {
        super(params);
        this.outFile = params.outFile;
        this.libraryIndex = params.libraryIndex;
        this.install = params.install ?? false;
        this.enablePostfix = params.enablePostfix ?? true;
    }
    public outFile: string;
    public libraryIndex: number;
    public install: boolean;
    /**
     * Should this component library's `.brs` files be renamed with a `__lib<index>` postfix during staging?
     * Postfixing is how the debugger maps a device-reported file path back to the component library it came
     * from. When disabled, file names are left untouched (useful when a library loads files by a fixed name
     * at runtime), at the cost of degraded source mapping for this library's files while debugging.
     */
    public enablePostfix: boolean;
    /**
     * The name of the component library that this project represents. This is loaded during `this.computeOutFileName`
     */
    public name: string;

    /**
     * Takes a component Library and checks the outFile for replaceable values pulled from the libraries manifest
     * @param manifestPath the path to the manifest file to check
     */
    private async computeOutFileName(manifestPath: string) {
        let regexp = /\$\{([\w\d_]*)\}/;
        let renamingMatch: RegExpExecArray;
        let manifestValues = await util.convertManifestToObject(manifestPath);
        if (!manifestValues) {
            throw new Error(`Cannot find manifest file at "${manifestPath}"\n\nCould not complete automatic component library naming.`);
        }

        //load the component libary name from the manifest
        this.name = manifestValues.sg_component_libs_provided || manifestValues.bs_libs_provided;

        // search the outFile for replaceable values such as ${title}
        while ((renamingMatch = regexp.exec(this.outFile))) {

            // replace the replaceable key with the manifest value
            let manifestVariableName = renamingMatch[1];
            let manifestVariableValue = manifestValues[manifestVariableName];
            if (manifestVariableValue) {
                this.outFile = this.outFile.replace(renamingMatch[0], manifestVariableValue);
            } else {
                throw new Error(`Cannot find manifest value:\n"${manifestVariableName}"\n\nCould not complete automatic component library naming.`);
            }
        }
    }

    public async stage() {
        /*
         Compute the file mappings now (i.e. don't let the parent class compute them).
         This must be done BEFORE finding the manifest file location.
         */
        this.fileMappings = await this.getFileMappings();

        let expectedManifestDestPath = fileUtils.standardizePath(`${this.stagingDir}/manifest`).toLowerCase();
        //find the file entry with the `dest` value of `${stagingDir}/manifest` (case insensitive)
        let manifestFileEntry = this.fileMappings.find(x => x.dest.toLowerCase() === expectedManifestDestPath);
        if (manifestFileEntry) {
            //read the manifest from `src` since nothing has been copied to staging yet
            await this.computeOutFileName(manifestFileEntry.src);
        } else {
            throw new Error(`Could not find manifest path for component library at '${this.rootDir}'`);
        }
        let fileNameWithoutExtension = path.basename(this.outFile, path.extname(this.outFile));

        let defaultStagingDir = this.stagingDir;

        //compute the staging folder path.
        this.stagingDir = s`${this.outDir}/${fileNameWithoutExtension}`;

        /*
          The fileMappings were created using the default stagingDir (because we need the manifest path
          to compute the out file name and staging path), so we need to replace the default stagingDir
          with the actual stagingDir.
         */
        for (let fileMapping of this.fileMappings) {
            fileMapping.dest = fileUtils.replaceCaseInsensitive(fileMapping.dest, defaultStagingDir, this.stagingDir);
        }

        return super.stage();
    }

    /**
     * The text used as a postfix for every brs file so we can accurately track the location of the files
     * back to their original component library whenever the debugger truncates the file path.
     */
    public get postfix() {
        //when postfixing is disabled, return an empty postfix so all postfix-aware logic (file renaming,
        //breakpoint path matching, source-location resolution) becomes a no-op for this library
        return this.enablePostfix ? `${componentLibraryPostfix}${this.libraryIndex}` : '';
    }

    public async postfixFiles() {
        //postfixing disabled for this library; leave file names and `uri=` references untouched
        if (!this.enablePostfix) {
            return;
        }
        let pathDetails = {};
        await Promise.all(this.fileMappings.map(async (fileMapping) => {
            let relativePath = fileUtils.removeLeadingSlash(
                fileUtils.getRelativePath(this.stagingDir, fileMapping.dest)
            );
            let postfixedPath = fileUtils.postfixFilePath(relativePath, this.postfix, ['.brs']);
            if (postfixedPath !== relativePath) {
                // Rename the brs files to include the postfix namespacing tag
                await fsExtra.move(fileMapping.dest, path.join(this.stagingDir, postfixedPath));
                // Add to the map of original paths and the new paths
                pathDetails[postfixedPath] = relativePath;
            }
        }));

        // Update all the file name references in the library to the new file names
        await replaceInFile({
            files: [
                path.join(this.stagingDir, '**/*.xml'),
                path.join(this.stagingDir, '**/*.brs')
            ],
            from: /uri\s*=\s*"(.+)\.brs"/gi,
            to: (match: string) => {
                // only alter file ending if it is a) pkg:/ url or b) relative url
                let isPkgUrl = !!/^uri\s*=\s*"(pkg:|libpkg:)\//i.exec(match);
                let isRelativeUrl = !/:\//i.exec(match);
                if (isPkgUrl || isRelativeUrl) {
                    return match.replace('.brs', this.postfix + '.brs');
                } else {
                    return match;
                }
            }
        });
    }
}

rokucommunity / roku-debug / 28191818298

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous