Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 0 additions & 7 deletions .checkov.yml

This file was deleted.

40 changes: 0 additions & 40 deletions .devcontainer/devcontainer.json

This file was deleted.

116 changes: 71 additions & 45 deletions .github/copilot-instructions.md
Original file line number Diff line number Diff line change
@@ -1,40 +1,48 @@
# Copilot Instructions

This GitHub Action is written in TypeScript and transpiled to JavaScript. Both
the TypeScript sources and the **generated** JavaScript code are contained in
this repository. The TypeScript sources are contained in the `src` directory and
the JavaScript code is contained in the `dist` directory. A GitHub Actions
workflow checks that the JavaScript code in `dist` is up-to-date. Therefore, you
should not review any changes to the contents of the `dist` folder and it is
expected that the JavaScript code in `dist` closely mirrors the TypeScript code
it is generated from.
This GitHub Action is written in TypeScript and bundled to JavaScript with
Rollup. Both the TypeScript sources and the **generated** JavaScript code are
contained in this repository. The TypeScript sources are contained in the `src`
directory and the JavaScript code is contained in the `dist` directory. A
GitHub Actions workflow (`check-dist.yml`) checks that the JavaScript code in
`dist` is up-to-date. Therefore, any change to `src` must be followed by a
rebuild of `dist`, you should not review any manual changes to the contents of
the `dist` folder, and it is expected that the JavaScript code in `dist`
closely mirrors the TypeScript code it is generated from.

The runtime is Bun (pinned in `.mise.toml`), with Node.js >= 24 required by the
action itself (`.node-version`, `package.json` `engines`). Formatting and
linting are handled entirely by Biome — there is no ESLint or Prettier in this
repository. Tests run on `bun test` (Bun's built-in test runner) — there is no
Jest and no coverage tooling.

See `CONTRIBUTING.md` for branch naming, commit conventions, and the release
process.

## Repository Structure

| Path | Description |
| -------------------- | -------------------------------------------------------- |
| `__fixtures__/` | Unit Test Fixtures |
| `__tests__/` | Unit Tests |
| `.devcontainer/` | Development Container Configuration |
| `.github/` | GitHub Configuration |
| `.licenses/` | License Information |
| `__tests__/` | Unit Tests (Bun test) |
| `.github/` | GitHub Configuration (workflows, Copilot instructions) |
| `.vscode/` | Visual Studio Code Configuration |
| `badges/` | Badges for readme |
| `dist/` | Generated JavaScript Code |
| `src/` | TypeScript Source Code |
| `dist/` | Generated JavaScript Code (bundled, no sourcemap) |
| `public/` | Static Assets for the Web Player |
| `scripts/` | Development Scripts (e.g. SVG comparison) |
| `src/` | TypeScript Source Code (`src/main.ts` is the Action entry, `src/web/` is the Web Player) |
| `.env.example` | Environment Variables Example for `@github/local-action` |
| `.licensed.yml` | Licensed Configuration |
| `.markdown-lint.yml` | Markdown Linter Configuration |
| `.markdown-lint.yml` | Markdown Linter Configuration (VS Code markdownlint) |
| `.mise.toml` | mise Tool Versions (Bun) |
| `.node-version` | Node.js Version Configuration |
| `.prettierrc.yml` | Prettier Formatter Configuration |
| `.yaml-lint.yml` | YAML Linter Configuration |
| `action.yml` | GitHub Action Metadata |
| `CODEOWNERS` | Code Owners File |
| `eslint.config.mjs` | ESLint Configuration |
| `jest.config.js` | Jest Configuration |
| `.yaml-lint.yml` | YAML Linter Configuration (VS Code YAML extension) |
| `action.yml` | GitHub Action Metadata (inputs/outputs) |
| `biome.json` | Biome Formatter/Linter Configuration |
| `bun.lock` | Bun Lockfile |
| `CONTRIBUTING.md` | Contribution Guide |
| `LICENSE` | License File |
| `package.json` | NPM Package Configuration |
| `README.md` | Project Documentation |
| `README_zh.md` | Chinese Documentation |
| `rollup.config.ts` | Rollup Bundler Configuration |
| `tsconfig.json` | TypeScript Configuration |

Expand All @@ -43,29 +51,45 @@ it is generated from.
Install dependencies by running:

```bash
npm install
bun install
```

## Testing

Ensure all unit tests pass by running:

```bash
npm run test
npm run ci-test
```

Unit tests should exist in the `__tests__` directory. They are powered by
`jest`. Fixtures should be placed in the `__fixtures__` directory.
Unit tests live in the `__tests__` directory and are powered by `bun:test`.
They mock the network, the physics engine and file output; keep that separation
when adding tests.

## Linting and Formatting

```bash
bun biome check . # format + lint check (CI gate)
bun biome check --write . # auto-fix
```

## Bundling

Any time files in the `src` directory are changed, you should run the following
command to bundle the TypeScript code into JavaScript:
Any time files in `src` are changed, you must rebuild and commit `dist`:

```bash
npm run bundle
```

This runs a Biome check (with auto-fix) and then bundles `src/index.ts` into
`dist/index.js`. The bundle does not produce sourcemaps — keep it that way.

The Web Player (`src/web/`) is built separately and is not committed:

```bash
bun run build:web # outputs dist-web/, deployed by pages.yml
```

## General Coding Guidelines

- Follow standard TypeScript and JavaScript coding conventions and best
Expand All @@ -80,8 +104,11 @@ npm run bundle
- Keep functions focused and manageable
- Use descriptive variable and function names that clearly convey their purpose
- Use JSDoc comments to document functions, classes, and complex logic
- After doing any refactoring, ensure to run `npm run test` to ensure that all
tests still pass and coverage requirements are met
- After doing any refactoring, run `npm run ci-test` to ensure that all tests
still pass
- Action inputs are validated strictly with `zod` in `src/main.ts`; when adding
an input, extend `action.yml`, the schema in `src/main.ts` and the plumbing
tests in `__tests__/main.test.ts` together
- When suggesting code changes, always opt for the most maintainable approach.
Try your best to keep the code clean and follow "Don't Repeat Yourself" (DRY)
principles
Expand All @@ -95,24 +122,23 @@ npm run bundle

### Versioning

GitHub Actions are versioned using branch and tag names. Please ensure the
version in the project's `package.json` is updated to reflect the changes made
in the codebase. The version should follow
[Semantic Versioning](https://semver.org/) principles.
The `version` field in `package.json` is the single source of truth and must
follow [Semantic Versioning](https://semver.org/) principles. Bump it in the PR
when user-facing behavior changes; the `sync-version-tag.yml` workflow creates
and maintains the `vX.Y.Z` / `vX` tags automatically — never tag manually.

## Pull Request Guidelines

When creating a pull request (PR), please ensure that:

- Keep changes focused and minimal (avoid large changes, or consider breaking
them into separate, smaller PRs)
- Formatting checks pass
- Linting checks pass
- Unit tests pass and coverage requirements are met
- The action has been transpiled to JavaScript and the `dist` directory is
up-to-date with the latest changes in the `src` directory
- If necessary, the `README.md` file is updated to reflect any changes in
functionality or usage
- Biome checks pass (`bun biome check .`)
- Unit tests pass (`npm run ci-test`)
- The action has been re-bundled and the `dist` directory is up-to-date with
the latest changes in the `src` directory (`npm run bundle`)
- If necessary, the `README.md` and `README_zh.md` files are updated to reflect
any changes in functionality or usage

The body of the PR should include:

Expand All @@ -126,5 +152,5 @@ The body of the PR should include:
When performing a code review, please follow these guidelines:

- If there are changes that modify the functionality/usage of the action,
validate that there are changes in the `README.md` file that document the new
or modified functionality
validate that there are changes in the `README.md` and `README_zh.md` files
that document the new or modified functionality
4 changes: 4 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,10 @@ jobs:
id: biome-check
run: bun biome check .

- name: Type Check
id: type-check
run: npx tsc --noEmit

- name: Test
id: npm-ci-test
run: npm run ci-test
Expand Down
7 changes: 0 additions & 7 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -22,13 +22,6 @@ pids
# Directory for instrumented libs generated by jscoverage/JSCover
lib-cov

# Coverage directory used by tools like istanbul
coverage
*.lcov

# nyc test coverage
.nyc_output

# Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files)
.grunt

Expand Down
18 changes: 0 additions & 18 deletions .licensed.yml

This file was deleted.

20 changes: 0 additions & 20 deletions .licenses/npm/@actions/core.dep.yml

This file was deleted.

20 changes: 0 additions & 20 deletions .licenses/npm/@actions/exec.dep.yml

This file was deleted.

32 changes: 0 additions & 32 deletions .licenses/npm/@actions/http-client.dep.yml

This file was deleted.

20 changes: 0 additions & 20 deletions .licenses/npm/@actions/io.dep.yml

This file was deleted.

Loading
Loading