starface-outlook-sync-addin/node_modules/ts-loader/AGENTS.md

AGENTS.md

ts-loader is a TypeScript loader for webpack, enabling webpack to compile .ts and .tsx files via the TypeScript compiler.

Package manager

Use yarn (not npm).

Key commands

yarn build              # compile src/ → dist/ (tsc --project "./src")
yarn lint               # type-check + ESLint (no separate typecheck script)
yarn test               # full test suite (comparison + execution tests)
yarn comparison-tests   # fast subset: compare webpack output against snapshots
yarn execution-tests    # run compiled code via Karma/Jasmine

To run a single test:

yarn comparison-tests -- --single-test <testName>
yarn execution-tests  -- --single-test <testName> --watch

Comparison tests (test/comparison-tests/)

Each sub-directory is a mini webpack project. The harness compiles it and diffs the output against expectedOutput/ snapshots (bundle.js, output.txt, err.txt). These are especially useful for failure cases — asserting that the right compiler errors appear.

Full docs: test/comparison-tests/README.md

Watch-mode tests apply a series of patches (patch0/, patch1/, …) after the initial build, re-compiling and re-comparing after each one.

Flaky tests: place an empty _FLAKY_ file in the test directory to allow occasional failures without blocking the build.

yarn comparison-tests                                              # all tests
yarn comparison-tests -- --single-test <name>                     # one test
yarn comparison-tests -- --save-output                            # regenerate all snapshots
yarn comparison-tests -- --save-output --single-test <name>       # regenerate one snapshot

Note: test name casing must be exact when using --single-test.

Seeding snapshots for a new TypeScript version

When adding support for a new TypeScript version, run:

yarn comparison-tests-generate

This does two things:

1. git clean -xfd test/comparison-tests — wipes all untracked/generated files in the test directory.
2. Runs test/comparison-tests/stub-new-version.js, which copies every expectedOutput-{OLD}/ and expectedOutput-transpile-{OLD}/ folder to the corresponding expectedOutput-{NEW}/ counterpart across all test sub-directories.

The OLD_VERSION and NEW_VERSION constants at the top of stub-new-version.js must be updated manually before running this script each time a new TypeScript version is introduced. After running, review and commit the seeded snapshots, then use --save-output to correct any that differ from the new version's actual output.

Execution tests (test/execution-tests/)

Each sub-directory is a mini webpack project with a Karma/Jasmine test suite. The harness compiles the project and runs the compiled code — useful for asserting correct runtime behaviour. These are matrix-tested in CI across Node 20/22 and TypeScript 5.x versions.

Full docs: test/execution-tests/README.md

Tests prefixed with a TypeScript version (e.g. 2.0.3_es2016) are skipped when the installed TypeScript is older than that prefix.

Every webpack.config.js in this pack must include this alias so the local ts-loader is resolved:

// for test harness purposes only
module.exports.resolveLoader = { alias: { 'ts-loader': path.join(__dirname, "../../../index.js") } }

yarn execution-tests                                    # all tests
yarn execution-tests -- --single-test <name>            # one test
yarn execution-tests -- --single-test <name> --watch    # watch mode (open http://localhost:9876/)

Always add or update tests when fixing bugs or adding features — see CONTRIBUTING.md.