chore: standardize the repository like tree-sitter-kotlin

.cursor/rules/general.mdc

@@ -0,0 +1,63 @@
+---
+description: General Coding Rules
+globs:
+alwaysApply: true
+---
+
+## Project Information
+
+- Name: `@willbooster/tree-sitter-javascript`
+- Description: JavaScript grammar for tree-sitter
+- Package Manager: bun
+
+## General Instructions
+
+- If on `main`, create a new branch; otherwise work on the current branch.
+- Run `git` commands one at a time to avoid `index.lock` conflicts.
+- Write every artifact in English, except text whose language is part of what the code handles (e.g., UI strings, test inputs).
+- Write a test only when explicitly requested, or when a behavior is likely to regress and no existing automatic check (type checking, linting, an existing test or CI check) would catch the breakage. Never add a test that merely restates a mapping from conditions to constant outputs (it fails only on intentional edits) or that only confirms an external fact (a library's behavior, whether a version fixes an issue); verify those once manually.
+- Test externally observable behavior (e.g., emitted files, CLI output, rendered results) at the system boundary, not implementation details: do not mirror production logic, assert that a branch is taken, or feed hand-assembled internal objects to internal functions.
+- Prefer actual API calls over mocks, unless actual calls are impractical, have unintended side effects, or mocks are explicitly requested.
+- Ensure tests are idempotent and independent (e.g., reset persistent data) so they can run repeatedly or in parallel.
+- Avoid fixed waits in E2E tests; wait for conditions instead.
+- When fixing issues (including test failures), investigate the root cause first (e.g., via debug logs or screenshots) and fix it instead of applying workarounds.
+- After making changes, as a rule, run only what is necessary for the change locally, `bun run verify` (type checking and linting; up to 10 minutes) and the relevant tests, and leave the full test suite (`bun run verify-full`; up to 1 hour) to the PR's CI. If PR CI does not run the full suite, run it locally. Fix errors, including CI failures, and re-run until they pass.
+  - Run relevant tests with `bun wb test test/unit/example.test.ts --grep 'case name'` (omit `--grep` for the whole file; use `-w packages/example` in a monorepo). `bun wb verify --full <test-path> --grep 'case name'` combines verification with selected tests.
+  - Wait for it to finish without restarting it: prefer completion notifications, otherwise the longest permitted wait; no output does not mean it has stopped. If the displayed excerpt is insufficient, read the indicated log file before rerunning. If the environment kills long-running commands, run them detached with a saved log and exit status.
+- Once verified, commit and push to the current (non-main) branch, and create a PR via `gh` if none exists for the branch.
+  - Follow the Conventional Commits format (e.g., `feat:`, `fix:`).
+  - End your commit message with a blank line followed by `Co-authored-by: WillBooster (Cursor) <agent@willbooster.com>`, the only AI attribution to add.
+  - Always create new commits; avoid `--amend`.
+  - Base the PR body on `.github/pull_request_template.md` when creating or updating a PR, even when a skill or workflow supplies its own skeleton: keep the template's headings in order, fill each section with what its placeholder comment asks for at a length fitting the change (a sentence for a small change, numbered subsections for a large one), and delete the placeholder comments and an empty Notes section. Without a template, use no fixed headings: state the scope, the motivation, and the verification concisely.
+  - Start the body with `Close #<n>` only when the PR resolves an existing issue.
+  - Requirements section: the requirements in force now, one line per requirement, taken from the requester's instructions in the requester's terms (the issue, the conversation that asked for the change), each marked `required` (asked for, or an existing contract callers depend on) or `chosen` (your own decision with the reason that decided it, which a simpler design may replace). Never infer a requirement from the diff: when no issue, PR message, or conversation states the request, write `required: not recorded — ask the requester` as the only request-derived line (a `required` line for an existing contract callers depend on may still be listed) and say so in Notes.
+  - Current-state rule: an existing Requirements section records what the requester asked for and what was decided as it stands now; it is neither a description of the diff nor a log of how the request evolved. Keep each line as it is until the requester overrides or withdraws the instruction behind it or the decision behind it changes, and then rewrite or remove that line instead of appending a line beside it; with no instructions available, keep the requester-derived lines unchanged. Never mark when a line was added (e.g., "(added)"), and add a `chosen` line for each new decision. When the current design cannot be understood without the change of direction, state it in one sentence in Notes. A section that merely describes the implementation, or holds only the template's placeholder or a `required: not recorded` line, is not a record: write it afresh by the rule above.
+  - Place the section where the template puts it; when the template has no such heading, right after the issue-closing line, or at the top of the body when there is none.
+  - Never drop or weaken a `required` line to fit what was implemented: when one cannot hold in the diff, keep it and say so in Notes.
+- When creating an issue:
+  - Follow the closest template under `.github/ISSUE_TEMPLATE/`: `bug.md` for wrong behavior, `change.md` for anything to build or alter; a question or note fitting neither, or a repository without templates, needs no template.
+  - Title: a Conventional Commits prefix for the type that fits the change (`feat:`, `fix:`, `refactor:`, `docs:`, `chore:`, ...); when it differs from the template's `title` prefix, replace the template's type label (`t: ...`) with the one matching the type.
+  - The YAML front matter between the `---` lines is metadata, not body text: pass its `labels` via `--label` and submit only the content below the closing `---` as the body.
+- In any explanatory text (commit messages, PR descriptions, documentation, code comments, etc.) other than the PR body's Requirements section (which states what is currently asked for rather than what the code contains), describe only the current implementation: drop any statement naming an identifier, feature, or concept you cannot confirm exists in the final diff or the current codebase (e.g., one added and later removed or renamed along the way). Whenever documentation or comments no longer match the current implementation (removed options, deprecated usage, outdated behavior), delete or rewrite them, even in files you are not otherwise changing. Mention a past state only where it is needed to understand why the current design is as it is, or when explicitly asked; files that record history by design (e.g., a changelog) are exempt.
+- Use heredoc for multi-line command input (e.g., `git commit -F -`, `gh pr create --body-file -`, `gh issue create --body-file -`).
+- Put temporary files in `.tmp`; use `/tmp` only for files that must live outside the repo.
+- `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `.cursor/rules/general.mdc`, and `.gemini/styleguide.md` are generated from `AGENTS_EXTRA.md` and overwritten on every `wbfy` run; to change agent instructions, edit only `AGENTS_EXTRA.md`.
+- Tool versions (e.g., node) are pinned in `mise.toml`; run `mise install` after changing it and never install those tools globally instead.
+- `bunfig.toml` uses Bun's isolated linker, so only declared dependencies resolve. If an import fails to resolve, declare that package in the `package.json` that imports it; never switch `linker` to `hoisted` or add to `publicHoistPattern` to work around it.
+- Private repositories use self-hosted CI runners. Keep OS/size constraints in an explicit self-hosted label array; fix missing runner capabilities instead of switching to GitHub-hosted runners. The sole approved exception is the Windows desktop build in WillBooster/cheerlings.
+
+## Coding Style
+
+- Use camelCase file names for JavaScript/TypeScript (PascalCase for React components).
+- Simplify code as much as possible to eliminate redundancy.
+- Design modules and directories with high cohesion and low coupling; split large modules when needed.
+- Place calling functions above the functions they call (top-down order); place variable and type declarations above their usage.
+- Comments and JSDoc: every reader has the source, so never restate what the code, its names, or its types already say (e.g., `@param name The name`). Write one only when a plausible edit would break something without that knowledge and no type check, lint rule, or test would catch it; first encode the knowledge in code (a name, a type, an `assert`, a test) and comment only what cannot be encoded: an odd-looking workaround, a dependency on a fact outside the repository, or a rejected alternative and why. Put a contract of the declared symbol in JSDoc and line-specific knowledge in an inline comment. Delete comments that fail this test in files you touch. Exception: the exported API of a package published to npm may carry JSDoc describing what it does and how to call it, because its users read it without the source.
+- Never explain how WillBooster's in-house tools (e.g., `wb`, `wbfy`) work in code comments or documents outside the tool's own package, except in instructions for AI agents (e.g., do not note that `PORT` is unset because `wb` picks a free port).
+- If lint errors or warnings cannot be fixed, use ignore comments with reasons (e.g., `// oxlint-disable-next-line <rule> -- <reason>`).
+- Prefer `undefined` over `null` unless required by APIs or libraries.
+- Validate JavaScript objects (e.g., parsed JSON, API responses) with `zod` whenever possible instead of hand-written checks or type assertions.
+- Build prompts as a single template literal instead of `join()` on a pre-computable array of strings.
+- Assume all environment variables are defined; if validation is needed, `assert` them at startup to fail fast.
+- Assume local tools such as `git`, `gh`, and `ghq` are installed and authenticated.
+- Ensure compatibility only with macOS and Linux; do not include Windows-specific code.

.editorconfig

@@ -2,45 +2,21 @@ root = true
 
 [*]
 charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
 
-[*.{json,toml,yml,gyp}]
-indent_style = space
-indent_size = 2
-
-[*.js]
-indent_style = space
-indent_size = 2
-
-[*.scm]
-indent_style = space
+[*.{cjs,cpp,cts,dart,htm,html,js,json,json5,jsonc,jsx,mjs,mts,pu,puml,rb,sh,ts,tsx,vue,xml,yaml,yml}]
 indent_size = 2
-
-[*.{c,cc,h}]
-indent_style = space
-indent_size = 4
-
-[*.rs]
 indent_style = space
-indent_size = 4
 
-[*.{py,pyi}]
-indent_style = space
+[*.{go,gradle,java,py}]
 indent_size = 4
-
-[*.swift]
 indent_style = space
-indent_size = 4
 
-[*.go]
-indent_style = tab
-indent_size = 8
+[*.md]
+max_line_length = off
+trim_trailing_whitespace = false
 
-[Makefile]
+[{Makefile,*.mk}]
 indent_style = tab
-indent_size = 8
-
-[parser.c]
-indent_size = 2
-
-[{alloc,array,parser}.h]
-indent_size = 2

.gemini/config.yaml

@@ -0,0 +1,11 @@
+have_fun: true
+code_review:
+  disable: false
+  comment_severity_threshold: MEDIUM
+  max_review_comments: -1
+  pull_request_opened:
+    help: false
+    summary: true
+    code_review: true
+ignore_patterns:
+  - '**/__generated__'

.gemini/styleguide.md

@@ -0,0 +1,17 @@
+Review in English based on the following coding standards.
+
+## Coding Style
+
+- Use camelCase file names for JavaScript/TypeScript (PascalCase for React components).
+- Simplify code as much as possible to eliminate redundancy.
+- Design modules and directories with high cohesion and low coupling; split large modules when needed.
+- Place calling functions above the functions they call (top-down order); place variable and type declarations above their usage.
+- Comments and JSDoc: every reader has the source, so never restate what the code, its names, or its types already say (e.g., `@param name The name`). Write one only when a plausible edit would break something without that knowledge and no type check, lint rule, or test would catch it; first encode the knowledge in code (a name, a type, an `assert`, a test) and comment only what cannot be encoded: an odd-looking workaround, a dependency on a fact outside the repository, or a rejected alternative and why. Put a contract of the declared symbol in JSDoc and line-specific knowledge in an inline comment. Delete comments that fail this test in files you touch. Exception: the exported API of a package published to npm may carry JSDoc describing what it does and how to call it, because its users read it without the source.
+- Never explain how WillBooster's in-house tools (e.g., `wb`, `wbfy`) work in code comments or documents outside the tool's own package, except in instructions for AI agents (e.g., do not note that `PORT` is unset because `wb` picks a free port).
+- If lint errors or warnings cannot be fixed, use ignore comments with reasons (e.g., `// oxlint-disable-next-line <rule> -- <reason>`).
+- Prefer `undefined` over `null` unless required by APIs or libraries.
+- Validate JavaScript objects (e.g., parsed JSON, API responses) with `zod` whenever possible instead of hand-written checks or type assertions.
+- Build prompts as a single template literal instead of `join()` on a pre-computable array of strings.
+- Assume all environment variables are defined; if validation is needed, `assert` them at startup to fail fast.
+- Assume local tools such as `git`, `gh`, and `ghq` are installed and authenticated.
+- Ensure compatibility only with macOS and Linux; do not include Windows-specific code.

.gitattributes

@@ -1,42 +1,37 @@
-* text=auto eol=lf
-
-# Generated source files
-src/*.json linguist-generated
-src/parser.c linguist-generated
-src/tree_sitter/* linguist-generated
-
-# C bindings
-bindings/c/** linguist-generated
-CMakeLists.txt linguist-generated
-Makefile linguist-generated
-
-# Rust bindings
-bindings/rust/* linguist-generated
-Cargo.toml linguist-generated
-Cargo.lock linguist-generated
-
-# Node.js bindings
-bindings/node/* linguist-generated
-binding.gyp linguist-generated
-package.json linguist-generated
-package-lock.json linguist-generated
-
-# Python bindings
-bindings/python/** linguist-generated
-setup.py linguist-generated
-pyproject.toml linguist-generated
-
-# Go bindings
-bindings/go/* linguist-generated
-go.mod linguist-generated
-go.sum linguist-generated
-
-# Swift bindings
-bindings/swift/** linguist-generated
-Package.swift linguist-generated
-Package.resolved linguist-generated
-
-# Zig bindings
-bindings/zig/* linguist-generated
-build.zig linguist-generated
-build.zig.zon linguist-generated
+* text=auto
+
+.gitignore -text
+
+*.lockb binary diff=lockb
+*.vcproj text eol=crlf
+
+*.cjs text eol=lf
+*.cpp text eol=lf
+*.cts text eol=lf
+*.dart text eol=lf
+*.htm text eol=lf
+*.html text eol=lf
+*.js text eol=lf
+*.json text eol=lf
+*.json5 text eol=lf
+*.jsonc text eol=lf
+*.jsx text eol=lf
+*.mjs text eol=lf
+*.mts text eol=lf
+*.pu text eol=lf
+*.puml text eol=lf
+*.rb text eol=lf
+*.sh text eol=lf
+*.ts text eol=lf
+*.tsx text eol=lf
+*.vue text eol=lf
+*.xml text eol=lf
+*.yaml text eol=lf
+*.yml text eol=lf
+*.go text eol=lf
+*.gradle text eol=lf
+*.java text eol=lf
+*.py text eol=lf
+*.md text eol=lf
+
+dist/** linguist-generated=true

.github/ISSUE_TEMPLATE/bug.md

@@ -0,0 +1,24 @@
+---
+name: Bug / Problem
+about: Something behaves wrongly
+title: 'fix: '
+labels: 't: fix :bug:'
+---
+
+<!-- Keep Problem and Proposal; delete Evidence or Impact when they add nothing. Write in English, except text whose language is part of what the code handles (e.g., UI strings, test inputs). Delete these comments. -->
+
+## Problem
+
+<!-- What happens, and what should happen instead. -->
+
+## Evidence
+
+<!-- Reproduction steps, logs, run IDs, or links. -->
+
+## Impact
+
+<!-- Who or what is affected, and how badly. -->
+
+## Proposal
+
+<!-- The fix you have in mind, and the root cause if known. -->

.github/ISSUE_TEMPLATE/change.md

@@ -0,0 +1,40 @@
+---
+name: Change / Feature
+about: Propose a change that a third party could implement without asking a question
+title: 'feat: '
+labels: 't: feat :sparkles:'
+---
+
+<!-- Keep the first three sections for any change and add the others as the change grows; a large change fills all of them (spec-booster reviews against this list). Write in English, except text whose language is part of what the code handles (e.g., UI strings, test inputs). Delete these comments. -->
+
+## Background and goal
+
+<!-- The problem being solved, for whom, and what outcome counts as success. -->
+
+## Behavior
+
+<!-- Every user- or caller-observable behavior, including inputs, outputs, error cases, edge cases, and interactions with existing behavior, stated precisely enough that two implementers would build the same thing. -->
+
+## Acceptance criteria
+
+<!-- Checkable conditions (Given/When/Then or an equivalent) that decide whether the implementation is done. -->
+
+## Scope and non-goals
+
+<!-- What the change covers and what it deliberately leaves out, so an implementer knows where to stop. -->
+
+## Design constraints
+
+<!-- The data, API, schema, UI, and configuration changes, naming, and the existing code or conventions the implementation must fit — as far as the writer intends to constrain them, with everything else explicitly left to the implementer. -->
+
+## Compatibility and migration
+
+<!-- What existing data, users, callers, or configurations are affected and how the transition happens. -->
+
+## Verification
+
+<!-- How the change is tested or demonstrated, including what needs no test and why. -->
+
+## Open questions
+
+<!-- Undecided points, each with its options; empty once the specification is implementable. -->

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1 @@
+blank_issues_enabled: true