BsConfig.ts

import type { LogLevel } from './logging';

export interface BsConfig {
    /**
     * The inheritance tree for all parent configs used to generate this config. Do not set this, it is computed.
     */
    _ancestors?: string[];

    /**
     * A path to a project file. This is really only passed in from the command line, and should not be present in bsconfig.json files.
     * Prefix with a question mark (?) to prevent throwing an exception if the file does not exist.
     */
    project?: string;

    manifest?: {
        bs_const?: Record<string, boolean | null>;
    };

    /**
     * when set, bsconfig.json loading is disabled
     */
    noProject?: boolean;


    /**
     * Relative or absolute path to another bsconfig.json file that this file should import and then override.
     * Prefix with a question mark (?) to prevent throwing an exception if the file does not exist.
     */
    extends?: string;

    /**
     * Override the current working directory.
     */
    cwd?: string;

    /**
     * The root directory of your Roku project. Defaults to current directory.
     */
    rootDir?: string;

    /**
     * The list of file globs used to find all files for the project
     * If using the {src;dest;} format, you can specify a different destination directory
     * for the matched files in src.
     */
    files?: Array<string | { src: string | string[]; dest?: string }>;

    /**
     * The path where the output zip file should be placed.
     * @default "./out/package.zip"
     */
    outFile?: string;

    /**
     * Creates a zip package. Defaults to true. This setting is ignored when deploy is enabled.
     */
    createPackage?: boolean;

    /**
     * If true, the files are copied to staging. This setting is ignored when deploy is enabled or if createPackage is enabled
     */
    copyToStaging?: boolean;

    /**
     * If true, the server will keep running and will watch and recompile on every file change
     * @default false
     */
    watch?: boolean;

    /**
     * If true, after a successful buld, the project will be deployed to the roku specified in host
     */
    deploy?: boolean;

    /**
     * The host of the Roku that this project will deploy to
     */
    host?: string;

    /**
     * The username to use when deploying to a Roku device
     */
    username?: string;

    /**
     * The password to use when deploying to a Roku device
     */
    password?: string;

    /**
     * Prevent the staging folder from being deleted after creating the package
     * @default false
     */
    retainStagingDir?: boolean;

    /**
     * Prevent the staging folder from being deleted after creating the package
     * @default false
     * @deprecated use `retainStagingDir` instead
     */
    retainStagingFolder?: boolean;

    /**
     * The path to the staging directory (wehre the output files are copied immediately before creating the zip)
     */
    stagingDir?: string;

    /**
     * The path to the staging folder (where all files are copied to right before creating the zip package)
     * @deprecated use `stagingDir` instead
     */
    stagingFolderPath?: string;

    /**
     * A list of error codes the compiler should NOT emit, even if encountered.
     */
    ignoreErrorCodes?: (number | string)[];

    /**
     * A map of error codes with their severity level override (error|warn|info)
     */
    diagnosticSeverityOverrides?: Record<number | string, 'error' | 'warn' | 'info' | 'hint'>;

    /**
     * Emit full paths to files when printing diagnostics to the console. Defaults to false
     */
    emitFullPaths?: boolean;

    /**
     * Emit type definition files (`d.bs`)
     * @default false
     */
    emitDefinitions?: boolean;

    /**
     * If true, removes the explicit type to function's parameters and return (i.e. the `as type` syntax); otherwise keep this information.
     * @default false
     */
    removeParameterTypes?: boolean;

    /**
     * A list of filters used to exclude diagnostics from the output
     */
    diagnosticFilters?: Array<number | string | { src: string; codes: (number | string)[] } | { src: string } | { codes: (number | string)[] }>;

    /**
     * Specify what diagnostic types should be printed to the console. Defaults to 'warn'
     */
    diagnosticLevel?: 'info' | 'hint' | 'warn' | 'error';

    /**
     * A list of scripts or modules to add extra diagnostics or transform the AST
     */
    plugins?: Array<string>;

    /**
     * A list of scripts or modules to pass to node's `require()` on startup. This is useful for doing things like ts-node registration
     */
    require?: Array<string>;

    /**
     * When enabled, every xml component will search for a .bs or .brs file with the same name
     * in the same folder, and add it as a script import if found. Disabled by default"
     */
    autoImportComponentScript?: boolean;
    /**
     * When enabled, diagnostics will be printed to the console.
     * When disabled, no diagnostics will be printed to the console.
     * @default true
     */
    showDiagnosticsInConsole?: boolean;
    /**
     * The log level.
     * @default LogLevel.log
     */
    logLevel?: LogLevel | 'error' | 'warn' | 'log' | 'info' | 'debug' | 'trace' | 'off';
    /**
     * Override the path to source files in source maps. Use this if you have a preprocess step and want
     * to ensure the source maps point to the original location.
     * This will only alter source maps for files within rootDir. Any files found outside of rootDir will not
     * have their source maps changed. This option also affects the `SOURCE_FILE_PATH` and `SOURCE_LOCATION` source literals.
     */
    sourceRoot?: string;
    /**
     * Should the `sourceRoot` property be resolve to an absolute path (relative to the bsconfig it's defined in)
     * @default false
     */
    resolveSourceRoot?: boolean;
    /**
     * Enables generating sourcemap files, which allow debugging tools to show the original source code while running the emitted files.
     * @default true
     */
    sourceMap?: boolean;
    /**
     * Excludes empty files from being included in the output. Some Brighterscript files
     * are left empty or with only comments after transpilation to Brightscript.
     * The default behavior is to write these to disk after transpilation.
     * Setting this flag to `true` will prevent empty files being written and will
     * remove associated script tags from XML
     * @default false
     */
    pruneEmptyCodeFiles?: boolean;
    /**
     * Allow brighterscript features (classes, interfaces, etc...) to be included in BrightScript (`.brs`) files, and force those files to be transpiled.
     * @default false
     */
    allowBrighterScriptInBrightScript?: boolean;

    /**
     * Override the destination directory for the bslib.brs file.  Use this if
     * you want to customize where the bslib.brs file is located in the staging
     * directory.  Note that using a location outside of `source` will break
     * scripts inside `source` that depend on bslib.brs.  Defaults to `source`.
     */
    bslibDestinationDir?: string;

    /**
     * Configuration for tree shaking (dead code elimination).
     */
    treeShaking?: TreeShakingConfig;
}

/**
 * A single keep-rule entry in `treeShaking.keep`.
 *
 * A plain string is shorthand for `{ functions: [string] }`.
 * An object entry must contain at least one of `src`, `dest`, `functions`, or `matches`.
 * All fields present on one rule are combined with AND semantics.
 * Rules across the list are combined with OR semantics.
 */
export type TreeShakingKeepEntry = string | TreeShakingKeepRule;

export interface TreeShakingKeepRule {
    /** Glob pattern(s) matched against the declaration's source file path. */
    src?: string | string[];
    /** Glob pattern(s) matched against the declaration's package-relative destination path. */
    dest?: string | string[];
    /** Exact function name(s) to keep (BrightScript/transpiled names). */
    functions?: string | string[];
    /** Glob/wildcard pattern(s) matched against the function name (BrightScript/transpiled names). */
    matches?: string | string[];
}

export interface TreeShakingConfig {
    /**
     * Enable or disable tree shaking. Defaults to `true`.
     */
    enabled?: boolean;
    /**
     * Declarations matching any rule in this list are always retained,
     * along with their full dependency closure.
     */
    keep?: TreeShakingKeepEntry[];
}

/** Normalized internal form produced by `normalizeConfig`. */
export interface NormalizedKeepRule {
    src?: string[];
    dest?: string[];
    functions?: string[];
    matches?: string[];
}

export interface NormalizedTreeShakingConfig {
    enabled: boolean;
    keep: NormalizedKeepRule[];
}

type OptionalBsConfigFields =
    | '_ancestors'
    | 'sourceRoot'
    | 'project'
    | 'manifest'
    | 'noProject'
    | 'extends'
    | 'host'
    | 'password'
    | 'require'
    | 'stagingFolderPath'
    | 'diagnosticLevel'
    | 'rootDir'
    | 'stagingDir';

export type FinalizedBsConfig =
    Omit<Required<BsConfig>, OptionalBsConfigFields | 'treeShaking'>
    & Pick<BsConfig, OptionalBsConfigFields>
    & { treeShaking: NormalizedTreeShakingConfig };