|
| 1 | +# Copilot Instructions |
| 2 | + |
| 3 | +## Project Overview |
| 4 | + |
| 5 | +This is a GitHub Action (`tediousjs/setup-sqlserver`) that installs SQL Server on Windows-based GitHub Action runners. It's built with TypeScript, compiled with `@vercel/ncc`, and runs on Node.js 24. |
| 6 | + |
| 7 | +## Local Development |
| 8 | + |
| 9 | +Use `nvm` to ensure you're running the correct Node.js version. The required version is pinned in `.nvmrc`: |
| 10 | + |
| 11 | +```sh |
| 12 | +nvm use |
| 13 | +``` |
| 14 | + |
| 15 | +## Build, Test & Lint |
| 16 | + |
| 17 | +```sh |
| 18 | +npm run build # ncc build + auto-generates README usage section from action.yml |
| 19 | +npm run test # mocha + ts-node (runs all tests) |
| 20 | +npm run test:coverage # tests with nyc coverage |
| 21 | +npm run lint # eslint across src/, misc/, test/ |
| 22 | +npm run lint:fix # eslint with auto-fix |
| 23 | +``` |
| 24 | + |
| 25 | +Run a single test file: |
| 26 | + |
| 27 | +```sh |
| 28 | +npx mocha -r ts-node/register './test/utils.ts' |
| 29 | +``` |
| 30 | + |
| 31 | +Run a single test by name: |
| 32 | + |
| 33 | +```sh |
| 34 | +npx mocha -r ts-node/register './test/**/**.ts' --grep 'correctly returns for windows-2019' |
| 35 | +``` |
| 36 | + |
| 37 | +The build step (`npm run build`) also runs `npm run docs`, which regenerates the usage section in `README.md` from `action.yml` via `misc/generate-docs.ts`. If you change `action.yml` inputs, rebuild to keep the README in sync. |
| 38 | + |
| 39 | +## Architecture |
| 40 | + |
| 41 | +**Entry point:** `src/main.ts` → calls `install()` from `src/install.ts`, which orchestrates the full flow: |
| 42 | + |
| 43 | +1. Reads action inputs via `gatherInputs()` from `src/utils.ts` |
| 44 | +2. Validates OS compatibility using version config from `src/versions.ts` |
| 45 | +3. Optionally installs SQL Native Client (`src/install-native-client.ts`) and ODBC driver (`src/install-odbc.ts`) |
| 46 | +4. Downloads or cache-hits the SQL Server installer (box+exe or standalone exe) |
| 47 | +5. Optionally downloads cumulative updates |
| 48 | +6. Runs the installer via `@actions/exec` |
| 49 | +7. Waits for the database to be ready (exponential backoff) |
| 50 | + |
| 51 | +**Installer abstraction:** `src/installers/` contains a base `Installer` class and `MsiInstaller` subclass used by the native client and ODBC installations. SQL Server itself uses direct exe/box download logic in `src/utils.ts`. |
| 52 | + |
| 53 | +**Version registry:** `src/versions.ts` defines a `Map<string, VersionConfig>` with download URLs, optional box URLs, update URLs, and OS compatibility constraints for each supported SQL Server version (2008–2022). |
| 54 | + |
| 55 | +**Build output:** `@vercel/ncc` bundles everything into `lib/main/index.js`, which is what `action.yml` references. The `lib/` directory is committed to the repository. **Every commit must include up-to-date build output** — CI checks this by rebuilding and running `git diff-files --quiet`. Always run `npm run build` and commit the resulting changes to `lib/` and `README.md` before pushing. |
| 56 | + |
| 57 | +## Conventions |
| 58 | + |
| 59 | +- **Testing:** Mocha + Chai + Sinon. Tests heavily stub `@actions/*` packages and module-level dependencies using `sinon.stub()`. Each test file mirrors its source file (e.g., `test/install.ts` tests `src/install.ts`). |
| 60 | +- **Commit messages:** Follow [Conventional Commits](https://www.conventionalcommits.org/) enforced by commitlint. Semantic-release uses these to generate automated releases and changelogs, so correct commit types are critical. |
| 61 | + - `fix` — Bug fixes or behavioural corrections that don't change public interfaces. Triggers a **patch** release. |
| 62 | + - `feat` — New backwards-compatible functionality (e.g., adding a new input, method, or option without removing anything). Triggers a **minor** release. |
| 63 | + - `feat!` (or any type with `!`) — Breaking changes where consumers would need to update their code (removed/renamed inputs, changed default behaviour). Triggers a **major** release. |
| 64 | + - `chore` — Dependency updates, tooling changes, or housekeeping that doesn't affect project code. **Does not trigger a release.** |
| 65 | + - `ci` — Changes to CI pipelines or workflow configuration. **Does not trigger a release.** |
| 66 | + - `style` — Refactoring or stylistic changes that do not change functionality. **Does not trigger a release.** |
| 67 | + - `test` — Changes that only touch test files. **Does not trigger a release.** |
| 68 | + - Only `fix` and `feat` trigger releases. If a change doesn't neatly fit `fix` or `feat` but still needs to be released, use whichever is most appropriate to ensure a release is created. |
| 69 | +- **Commits and merges:** |
| 70 | + - Commits should be atomic and ideally deployable in isolation — all tests, linting, and commitlinting should pass on each individual commit. |
| 71 | + - PRs are merged using a **merge commit** (no squash-merge or rebase-merge). Each commit in the PR history is preserved. |
| 72 | + - To keep branches up to date with the base branch, **rebase** onto it rather than merging it in. |
| 73 | + - All changes must go through a **pull request** — no direct commits to master. |
| 74 | +- **Node version:** Pinned to 24 via `.nvmrc`. The action runs using `node24` (set in `action.yml`). |
| 75 | +- **Imports:** Use the `type` keyword for type-only imports (e.g., `import type { Foo } from './bar'`). When importing both types and values from the same module, use a single import with inline `type` (e.g., `import { type Foo, bar } from './baz'`). Imports are ordered alphabetically by module path, grouped as: `node:` built-ins first, then external packages, then local file imports. |
| 76 | +- **ESLint rules:** Trailing commas required on multiline, semicolons required, no variable shadowing. `@typescript-eslint/no-explicit-any` is disabled in test files. |
| 77 | +- **README updates:** The usage block in `README.md` between `<!-- start usage -->` and `<!-- end usage -->` is auto-generated. Edit `action.yml` inputs, not the README directly. |
| 78 | +- **Keeping this file up to date:** If a change affects the architecture, conventions, build process, or any other information documented here, update this file as part of the same PR. |
0 commit comments