{"owner":"mochajs","repo":"mocha","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md"],"skills":{"AGENTS.md":"# AGENTS.md\n\nAgent onboarding for the `mochajs/mocha` repository.\n\n> **Trust this file first.** If you are unsure about command order, use the sequences below before trying alternatives.\n\n## Instruction precedence and execution defaults\n\n- Use `AGENTS.md` as the primary repository playbook for agent work.\n- Use `.github/copilot-instructions.md` as the short compatibility layer for tools that prefer it.\n- If prose and executable configuration disagree on command details, trust `package.json` scripts and `.github/workflows/*.yml`.\n- Prefer repository `npm` scripts over ad hoc shell pipelines.\n- If the current tool environment cannot edit files or run commands, provide copy-ready patch/command text and clearly mark validation as not run.\n\n## Mission and scope\n\n- Keep changes minimal and targeted.\n- Preserve compatibility (Mocha is highly depended-upon and semver-sensitive).\n- Never edit generated artifacts directly.\n- Validate locally with the smallest command set that matches your change.\n\n## Environment prerequisites\n\n- Node.js: `^20.19.0 || >=22.12.0` (prefer Node 22 locally)\n- npm (do not use pnpm/yarn for this repo)\n- Google Chrome (required for browser tests)\n\n## Repository map (quick)\n\n- `lib/` — core runtime (runner, suite, hooks, reporters, CLI internals)\n- `bin/` — CLI entrypoints (`mocha`)\n- `test/` — unit, integration, node-only, browser-specific, smoke\n- `docs/` — Astro/Starlight docs app with separate lockfile/scripts\n- `mocha.js` / `mocha.js.map` — browser bundle outputs (generated)\n- `.github/workflows/` — CI job matrix and script partitioning\n\n## Generated files and do-not-edit rules\n\n- **Do not edit** `mocha.js` or `mocha.js.map` by hand.\n- These are generated via `npm run build` (Rollup).\n- `npm run clean` removes generated bundle artifacts.\n\n## Verified command runbooks\n\nRun from repository root unless noted.\n\n### Bootstrap\n\n1. `npm install`\n2. (Docs work only) `cd docs && npm install`\n\nFor clean CI reproduction on a fresh checkout, prefer `npm ci --ignore-scripts`; use `npm install` for normal local bootstrap.\n\n### Fast sanity (recommended before/after focused edits)\n\n1. `npm run clean`\n2. `npm run build`\n3. `npm run tsc`\n4. `npm run test-smoke`\n5. Targeted tests relevant to changed area (see below)\n\n### Targeted tests\n\n- Unit/core: `npm run test-node:unit`\n- Integration: `npm run test-node:integration`\n- Interfaces: `npm run test-node:interfaces`\n- Reporters: `npm run test-node:reporters`\n- Browser subset: `npm run test-browser -- --grep bdd`\n- Full browser path: `npm run test-browser` (includes clean + build)\n\n### Validation routing\n\n- Instruction/docs-only edits: no runtime checks required unless behavior claims changed.\n- Browser or reporter changes: `npm run clean` → `npm run build` → browser validation.\n- CLI or node runtime changes: `npm run test-smoke` plus the closest `test-node:*` suite.\n- Type/signature changes: `npm run tsc`.\n- Workflow or script changes: mirror the affected `package.json` script or workflow job locally when practical.\n\n### Full local gate (closest to CI intent)\n\n1. `npm run format:check`\n2. `npm run lint`\n3. `npm run test-node`\n4. `npm run test-browser`\n5. `npm run tsc`\n\n## Critical command-order gotchas\n\n- Browser tests depend on built bundle artifacts.\n  - If you run `clean`, you **must** run `build` before invoking `playwright test` directly, or the page will 404 on `/mocha.js`.\n- `test-browser` script is safer than calling `playwright test` directly because it includes `clean build`.\n\n## CI parity notes\n\nMain workflow: `.github/workflows/mocha.yml`\n\nCI partitions checks into separate jobs:\n\n- `format:check`\n- `lint`\n- `test-smoke` (Node 20/22/24)\n- `test-node:*` matrix (interfaces/unit/integration/jsapi/requires/reporters/only)\n- browser tests (`test-browser` with ChromeHeadless)\n- `tsc`\n\nReusable execution details in `.github/workflows/npm-script.yml`:\n\n- Uses `npm ci --ignore-scripts`\n- Default Node 22 unless overridden\n- `NODE_OPTIONS=--trace-warnings`\n- Optional coverage upload via Codecov\n\n## Transient validation issues and environment drift\n\nDuring onboarding or after dependency refresh, you may encounter validation failures that reflect local environment or ecosystem drift rather than a persistent repository bug.\n\nCommon patterns include:\n\n- Lint commands (for example, `npm run lint:code`) failing because new or stricter rules turn warnings into errors (such as via `--max-warnings 0`). Inspect the reported rule and location before changing lint configuration or adding suppressions.\n- Docs-related workflows where documentation generation succeeds but a subsequent static site or bundler step (for example, `astro build`) fails with runtime errors originating in third-party dependencies.\n\nTreat these as potential environment/version drift signals. Do not resolve them by broadly weakening checks (for example, relaxing lint strictness or skipping build steps) unless explicitly requested in the task.\n\n## Change strategy for agents\n\n- Prefer smallest reproducible command to validate your specific edit first.\n- Add/adjust tests with behavior changes; do not change unrelated tests.\n- Avoid broad dependency upgrades unless task explicitly requests it.\n- If touching browser behavior, always include at least one browser test run.\n- If touching CLI or node runtime behavior, include smoke + targeted node suite.\n\n### CJS to ESM migration conventions (runtime code)\n\n- Scope: prioritize runtime modules under `lib/`; do not include test fixtures unless explicitly requested.\n- For ESM modules, prefer **named exports** over `export default`.\n- When consuming ESM from CJS via `require()`, import named bindings from the namespace object:\n  - Use `const { SomeName } = require(\"./file.mjs\");`\n  - Avoid `require(\"./file.mjs\").default` for runtime modules.\n- Keep PRs small and reviewable (roughly <=100 changed lines when practical).\n- After each migration slice, update all direct runtime call sites in the same PR to avoid mixed import patterns.\n\n## Docs subsystem notes (`docs/`)\n\n- Separate package and lockfile.\n- Script chain in `docs/package.json`:\n  - `generate` fetches supporter metadata/assets\n  - `build` runs `astro check && astro build`\n  - `docs` script reinstalls root+docs deps, then generate+build\n- Docs output can be very noisy (many supporter image fetch logs).\n\n## High-signal troubleshooting\n\n- Never claim a check passed unless you actually ran it.\n- If blocked, report the exact command, working directory, and first meaningful error.\n- Missing Chrome / browser launch failures: ensure local Chrome installed and available.\n- Browser path errors after cleanup: rerun `npm run build`.\n- Strange lint failures after dependency changes: rerun on clean install (`npm ci`), inspect warning-as-error output first.\n- Unexpected CI mismatch: mirror exact script from workflow rather than invoking custom command combinations.\n"},"files":{"AGENTS.md":"# AGENTS.md\n\nAgent onboarding for the `mochajs/mocha` repository.\n\n> **Trust this file first.** If you are unsure about command order, use the sequences below before trying alternatives.\n\n## Instruction precedence and execution defaults\n\n- Use `AGENTS.md` as the primary repository playbook for agent work.\n- Use `.github/copilot-instructions.md` as the short compatibility layer for tools that prefer it.\n- If prose and executable configuration disagree on command details, trust `package.json` scripts and `.github/workflows/*.yml`.\n- Prefer repository `npm` scripts over ad hoc shell pipelines.\n- If the current tool environment cannot edit files or run commands, provide copy-ready patch/command text and clearly mark validation as not run.\n\n## Mission and scope\n\n- Keep changes minimal and targeted.\n- Preserve compatibility (Mocha is highly depended-upon and semver-sensitive).\n- Never edit generated artifacts directly.\n- Validate locally with the smallest command set that matches your change.\n\n## Environment prerequisites\n\n- Node.js: `^20.19.0 || >=22.12.0` (prefer Node 22 locally)\n- npm (do not use pnpm/yarn for this repo)\n- Google Chrome (required for browser tests)\n\n## Repository map (quick)\n\n- `lib/` — core runtime (runner, suite, hooks, reporters, CLI internals)\n- `bin/` — CLI entrypoints (`mocha`)\n- `test/` — unit, integration, node-only, browser-specific, smoke\n- `docs/` — Astro/Starlight docs app with separate lockfile/scripts\n- `mocha.js` / `mocha.js.map` — browser bundle outputs (generated)\n- `.github/workflows/` — CI job matrix and script partitioning\n\n## Generated files and do-not-edit rules\n\n- **Do not edit** `mocha.js` or `mocha.js.map` by hand.\n- These are generated via `npm run build` (Rollup).\n- `npm run clean` removes generated bundle artifacts.\n\n## Verified command runbooks\n\nRun from repository root unless noted.\n\n### Bootstrap\n\n1. `npm install`\n2. (Docs work only) `cd docs && npm install`\n\nFor clean CI reproduction on a fresh checkout, prefer `npm ci --ignore-scripts`; use `npm install` for normal local bootstrap.\n\n### Fast sanity (recommended before/after focused edits)\n\n1. `npm run clean`\n2. `npm run build`\n3. `npm run tsc`\n4. `npm run test-smoke`\n5. Targeted tests relevant to changed area (see below)\n\n### Targeted tests\n\n- Unit/core: `npm run test-node:unit`\n- Integration: `npm run test-node:integration`\n- Interfaces: `npm run test-node:interfaces`\n- Reporters: `npm run test-node:reporters`\n- Browser subset: `npm run test-browser -- --grep bdd`\n- Full browser path: `npm run test-browser` (includes clean + build)\n\n### Validation routing\n\n- Instruction/docs-only edits: no runtime checks required unless behavior claims changed.\n- Browser or reporter changes: `npm run clean` → `npm run build` → browser validation.\n- CLI or node runtime changes: `npm run test-smoke` plus the closest `test-node:*` suite.\n- Type/signature changes: `npm run tsc`.\n- Workflow or script changes: mirror the affected `package.json` script or workflow job locally when practical.\n\n### Full local gate (closest to CI intent)\n\n1. `npm run format:check`\n2. `npm run lint`\n3. `npm run test-node`\n4. `npm run test-browser`\n5. `npm run tsc`\n\n## Critical command-order gotchas\n\n- Browser tests depend on built bundle artifacts.\n  - If you run `clean`, you **must** run `build` before invoking `playwright test` directly, or the page will 404 on `/mocha.js`.\n- `test-browser` script is safer than calling `playwright test` directly because it includes `clean build`.\n\n## CI parity notes\n\nMain workflow: `.github/workflows/mocha.yml`\n\nCI partitions checks into separate jobs:\n\n- `format:check`\n- `lint`\n- `test-smoke` (Node 20/22/24)\n- `test-node:*` matrix (interfaces/unit/integration/jsapi/requires/reporters/only)\n- browser tests (`test-browser` with ChromeHeadless)\n- `tsc`\n\nReusable execution details in `.github/workflows/npm-script.yml`:\n\n- Uses `npm ci --ignore-scripts`\n- Default Node 22 unless overridden\n- `NODE_OPTIONS=--trace-warnings`\n- Optional coverage upload via Codecov\n\n## Transient validation issues and environment drift\n\nDuring onboarding or after dependency refresh, you may encounter validation failures that reflect local environment or ecosystem drift rather than a persistent repository bug.\n\nCommon patterns include:\n\n- Lint commands (for example, `npm run lint:code`) failing because new or stricter rules turn warnings into errors (such as via `--max-warnings 0`). Inspect the reported rule and location before changing lint configuration or adding suppressions.\n- Docs-related workflows where documentation generation succeeds but a subsequent static site or bundler step (for example, `astro build`) fails with runtime errors originating in third-party dependencies.\n\nTreat these as potential environment/version drift signals. Do not resolve them by broadly weakening checks (for example, relaxing lint strictness or skipping build steps) unless explicitly requested in the task.\n\n## Change strategy for agents\n\n- Prefer smallest reproducible command to validate your specific edit first.\n- Add/adjust tests with behavior changes; do not change unrelated tests.\n- Avoid broad dependency upgrades unless task explicitly requests it.\n- If touching browser behavior, always include at least one browser test run.\n- If touching CLI or node runtime behavior, include smoke + targeted node suite.\n\n### CJS to ESM migration conventions (runtime code)\n\n- Scope: prioritize runtime modules under `lib/`; do not include test fixtures unless explicitly requested.\n- For ESM modules, prefer **named exports** over `export default`.\n- When consuming ESM from CJS via `require()`, import named bindings from the namespace object:\n  - Use `const { SomeName } = require(\"./file.mjs\");`\n  - Avoid `require(\"./file.mjs\").default` for runtime modules.\n- Keep PRs small and reviewable (roughly <=100 changed lines when practical).\n- After each migration slice, update all direct runtime call sites in the same PR to avoid mixed import patterns.\n\n## Docs subsystem notes (`docs/`)\n\n- Separate package and lockfile.\n- Script chain in `docs/package.json`:\n  - `generate` fetches supporter metadata/assets\n  - `build` runs `astro check && astro build`\n  - `docs` script reinstalls root+docs deps, then generate+build\n- Docs output can be very noisy (many supporter image fetch logs).\n\n## High-signal troubleshooting\n\n- Never claim a check passed unless you actually ran it.\n- If blocked, report the exact command, working directory, and first meaningful error.\n- Missing Chrome / browser launch failures: ensure local Chrome installed and available.\n- Browser path errors after cleanup: rerun `npm run build`.\n- Strange lint failures after dependency changes: rerun on clean install (`npm ci`), inspect warning-as-error output first.\n- Unexpected CI mismatch: mirror exact script from workflow rather than invoking custom command combinations.\n"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","title":"AGENTS.md","content":"# AGENTS.md\n\nAgent onboarding for the `mochajs/mocha` repository.\n\n> **Trust this file first.** If you are unsure about command order, use the sequences below before trying alternatives.\n\n## Instruction precedence and execution defaults\n\n- Use `AGENTS.md` as the primary repository playbook for agent work.\n- Use `.github/copilot-instructions.md` as the short compatibility layer for tools that prefer it.\n- If prose and executable configuration disagree on command details, trust `package.json` scripts and `.github/workflows/*.yml`.\n- Prefer repository `npm` scripts over ad hoc shell pipelines.\n- If the current tool environment cannot edit files or run commands, provide copy-ready patch/command text and clearly mark validation as not run.\n\n## Mission and scope\n\n- Keep changes minimal and targeted.\n- Preserve compatibility (Mocha is highly depended-upon and semver-sensitive).\n- Never edit generated artifacts directly.\n- Validate locally with the smallest command set that matches your change.\n\n## Environment prerequisites\n\n- Node.js: `^20.19.0 || >=22.12.0` (prefer Node 22 locally)\n- npm (do not use pnpm/yarn for this repo)\n- Google Chrome (required for browser tests)\n\n## Repository map (quick)\n\n- `lib/` — core runtime (runner, suite, hooks, reporters, CLI internals)\n- `bin/` — CLI entrypoints (`mocha`)\n- `test/` — unit, integration, node-only, browser-specific, smoke\n- `docs/` — Astro/Starlight docs app with separate lockfile/scripts\n- `mocha.js` / `mocha.js.map` — browser bundle outputs (generated)\n- `.github/workflows/` — CI job matrix and script partitioning\n\n## Generated files and do-not-edit rules\n\n- **Do not edit** `mocha.js` or `mocha.js.map` by hand.\n- These are generated via `npm run build` (Rollup).\n- `npm run clean` removes generated bundle artifacts.\n\n## Verified command runbooks\n\nRun from repository root unless noted.\n\n### Bootstrap\n\n1. `npm install`\n2. (Docs work only) `cd docs && npm install`\n\nFor clean CI reproduction on a fresh checkout, prefer `npm ci --ignore-scripts`; use `npm install` for normal local bootstrap.\n\n### Fast sanity (recommended before/after focused edits)\n\n1. `npm run clean`\n2. `npm run build`\n3. `npm run tsc`\n4. `npm run test-smoke`\n5. Targeted tests relevant to changed area (see below)\n\n### Targeted tests\n\n- Unit/core: `npm run test-node:unit`\n- Integration: `npm run test-node:integration`\n- Interfaces: `npm run test-node:interfaces`\n- Reporters: `npm run test-node:reporters`\n- Browser subset: `npm run test-browser -- --grep bdd`\n- Full browser path: `npm run test-browser` (includes clean + build)\n\n### Validation routing\n\n- Instruction/docs-only edits: no runtime checks required unless behavior claims changed.\n- Browser or reporter changes: `npm run clean` → `npm run build` → browser validation.\n- CLI or node runtime changes: `npm run test-smoke` plus the closest `test-node:*` suite.\n- Type/signature changes: `npm run tsc`.\n- Workflow or script changes: mirror the affected `package.json` script or workflow job locally when practical.\n\n### Full local gate (closest to CI intent)\n\n1. `npm run format:check`\n2. `npm run lint`\n3. `npm run test-node`\n4. `npm run test-browser`\n5. `npm run tsc`\n\n## Critical command-order gotchas\n\n- Browser tests depend on built bundle artifacts.\n  - If you run `clean`, you **must** run `build` before invoking `playwright test` directly, or the page will 404 on `/mocha.js`.\n- `test-browser` script is safer than calling `playwright test` directly because it includes `clean build`.\n\n## CI parity notes\n\nMain workflow: `.github/workflows/mocha.yml`\n\nCI partitions checks into separate jobs:\n\n- `format:check`\n- `lint`\n- `test-smoke` (Node 20/22/24)\n- `test-node:*` matrix (interfaces/unit/integration/jsapi/requires/reporters/only)\n- browser tests (`test-browser` with ChromeHeadless)\n- `tsc`\n\nReusable execution details in `.github/workflows/npm-script.yml`:\n\n- Uses `npm ci --ignore-scripts`\n- Default Node 22 unless overridden\n- `NODE_OPTIONS=--trace-warnings`\n- Optional coverage upload via Codecov\n\n## Transient validation issues and environment drift\n\nDuring onboarding or after dependency refresh, you may encounter validation failures that reflect local environment or ecosystem drift rather than a persistent repository bug.\n\nCommon patterns include:\n\n- Lint commands (for example, `npm run lint:code`) failing because new or stricter rules turn warnings into errors (such as via `--max-warnings 0`). Inspect the reported rule and location before changing lint configuration or adding suppressions.\n- Docs-related workflows where documentation generation succeeds but a subsequent static site or bundler step (for example, `astro build`) fails with runtime errors originating in third-party dependencies.\n\nTreat these as potential environment/version drift signals. Do not resolve them by broadly weakening checks (for example, relaxing lint strictness or skipping build steps) unless explicitly requested in the task.\n\n## Change strategy for agents\n\n- Prefer smallest reproducible command to validate your specific edit first.\n- Add/adjust tests with behavior changes; do not change unrelated tests.\n- Avoid broad dependency upgrades unless task explicitly requests it.\n- If touching browser behavior, always include at least one browser test run.\n- If touching CLI or node runtime behavior, include smoke + targeted node suite.\n\n### CJS to ESM migration conventions (runtime code)\n\n- Scope: prioritize runtime modules under `lib/`; do not include test fixtures unless explicitly requested.\n- For ESM modules, prefer **named exports** over `export default`.\n- When consuming ESM from CJS via `require()`, import named bindings from the namespace object:\n  - Use `const { SomeName } = require(\"./file.mjs\");`\n  - Avoid `require(\"./file.mjs\").default` for runtime modules.\n- Keep PRs small and reviewable (roughly <=100 changed lines when practical).\n- After each migration slice, update all direct runtime call sites in the same PR to avoid mixed import patterns.\n\n## Docs subsystem notes (`docs/`)\n\n- Separate package and lockfile.\n- Script chain in `docs/package.json`:\n  - `generate` fetches supporter metadata/assets\n  - `build` runs `astro check && astro build`\n  - `docs` script reinstalls root+docs deps, then generate+build\n- Docs output can be very noisy (many supporter image fetch logs).\n\n## High-signal troubleshooting\n\n- Never claim a check passed unless you actually ran it.\n- If blocked, report the exact command, working directory, and first meaningful error.\n- Missing Chrome / browser launch failures: ensure local Chrome installed and available.\n- Browser path errors after cleanup: rerun `npm run build`.\n- Strange lint failures after dependency changes: rerun on clean install (`npm ci`), inspect warning-as-error output first.\n- Unexpected CI mismatch: mirror exact script from workflow rather than invoking custom command combinations.\n","category":"root","tokens":1721}]}