Add bslib inline functionality to eliminate need for bslib.brs imports

[Copilot]

Adds the ability to inline bslib functions directly into individual files, eliminating the need for library consumers to manage bslib.brs imports.

Problem

The current bslib.brs pattern works for app developers but creates friction for library consumers who must remember to add bslib.brs imports when using libraries that leverage BrighterScript features like template strings and ternary operators.

Solution

This PR introduces a new bslibHandling configuration option that allows developers to choose between two modes:

• shared (default): Current behavior with a single shared bslib.brs file
• unique-per-file: Inlines bslib functions directly into each file with unique suffixes

Configuration

{
  "bslibHandling": {
    "mode": "shared" | "unique-per-file",
    "uniqueStrategy": "md5" | "guid"
  }
}

Example

Input BrighterScript:

function main()
    message = `Hello ${m.top.name}`
end function

Shared Mode (current behavior):

function main()
    message = ("Hello " + bslib_toString(m.top.name))
end function

Unique-per-file Mode:

function main()
    message = ("Hello " + bslib_toString_3a155d918876f6cf(m.top.name))
end function

function bslib_toString_3a155d918876f6cf(value)
    valueType = type(value)
    'if the var supports `toStr()`
    if valueType = "<uninitialized>" then
        return valueType
    else if value = invalid then
        return "<invalid>"
    else if GetInterface(value, "ifToStr") <> invalid then
        return value.toStr()
    else if valueType = "roSGNode"
        return "Node(" + value.subType() + ")"
    end if
    'when all else fails, just return the type
    return "<" + valueType + ">"
end function

Key Features

• Backward Compatible: Default behavior remains unchanged
• Self-Sufficient Files: Generated files don't require external bslib dependencies
• Efficient: Only inlines functions that are actually used
• Deterministic: MD5 strategy generates consistent suffixes based on file path
• XML Integration: Automatically skips bslib imports in XML files when using unique-per-file mode

Implementation Details

• Added bslibHandling configuration to BsConfig.ts and schema
• Extended BrsTranspileState to track used bslib functions and generate unique suffixes
• Modified expression transpilation to use unique suffixes when enabled
• Updated BrsFile.transpile() to inject inlined functions
• Modified XmlFile and Program to skip bslib imports/copying in unique-per-file mode
• Comprehensive test coverage with 9 test cases

This makes BrighterScript libraries more portable and reduces the friction for library adoption while maintaining full backward compatibility.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Inline bslib functions to eliminate need for bslib.brs</issue_title>
<issue_description>Add the ability to inline the bslib functions in the current file to eliminate the need for bslib.brs.

Motivation

While the current bslib.brs pattern works for app developers, it introduces friction for library consumers who must remember to add bslib.brs imports. This proposal aims to make library adoption easier and reduce manual steps.

Example:

function main()
        message = `Hello ${m.top.name}`
end function

Used to transpile to:

function main()
                         'bslib_toString somehow imported from `pkg:/source/bslib.brs`
    message = ("Hello " + bslib_toString(m.top.name))
end function

But now will transpile to the following code (enabling that file to be completely self-sufficient):

function main()
    message = ("Hello " + bslib_toString_1234567890abcdef(m.top.name))
end function

function bslib_toString_1234567890abcdef(value)
    '...the contents of bslib_toString
end function

Requirements:

1. Add a new configuration option

• Extend the configuration system to support a bslibHandling object as shown below. (final name up for discussion):

{
  "bslibHandling": {
    "mode": "shared" | "unique-per-file",
    "uniqueStrategy": "md5" | "guid" // for unique-per-file
  }
}

• Add a mode property with options: "shared" (default) and "unique-per-file"
• Add a uniqueStrategy property for "unique-per-file" which supports "md5" (default) and "guid". This decides how to generate the suffix for file-inlined functions.

2. Implement the two behaviors

shared (default):

• Current behavior: output all bslib helpers to a single shared file (e.g., bslib.brs).

unique-per-file:

When this mode is enabled, generate unique bslib functions for each file

• the unique identifier should be either
  • md5(file.srcPath) (default)
  • or a GUID.
• Inline all bslib helpers directly into each file that needs them; do not generate a shared file.
• change all bslib calls to use that suffixed file. (i.e. bslib_ternary => bslib_ternary_1234567890abcdef)
• prevent injecting the bslib.brs imports into xml files that currently happens

3. Documentation

• Update documentation to explain the new configuration options and their effects.
  </issue_description>

<agent_instructions>You must create extensive unit tests to prove this works (with transpiled outputs using the testTranspile test functionality). </agent_instructions>

Comments on the Issue (you are @copilot in this section)

Fixes #1524

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.