universal-emoji-parser

--- name: fix-build description: Diagnose and repair a failing TypeScript / Webpack / Mocha build --- # Command: `/fix-build` The build is broken. Find the root cause and fix it without disabling the failing check. ## Inputs to confirm - **Which command fails?** `npm test`, `npm run build`, `npm run eslint:check`, `npm run prettier:check`, `npm run build:tsc` - **Full error output** — paste the last ~30 lines, especially any "Caused by" / "Error:" / "TS####" lines ## Procedure ### 1. Reproduce Run the failing command yourself with verbose output: ```bash npm run <script> --silent=false 2>&1 | tee tmp/build.log ``` Read the actual root cause, not just the surface error. ### 2. Classify the failure | Symptom | Likely cause | Section | | -------------------------------------------------------- | ---------------------------------------------------------------- | ------- | | `Cannot find module '@twemoji/parser'` (or similar) | Stale `node_modules` | A | | `TSError: ⨯ Unable to compile TypeScript` | TS source error | B | | `error TS####:` | TypeScript compiler error | B | | `Module parse failed` (Webpack) | TS file Webpack can't parse — usually `ts-loader` not picking up | C | | ESLint `Parsing error: Cannot read file 'tsconfig.json'` | Wrong working directory | D | | ESLint `'X' is not defined` (no-console, etc.) | Code violates a lint rule | E | | Prettier `Code style issues found` | Code violates Prettier formatting | F | | Mocha tests time out | Regenerator accidentally enabled | G | | Mocha tests fail with assertion mismatch | Real test failure — fix the code | H | | `npm publish` 401/403 | Auth or scope issue | I | | GitHub Actions fails on `npm install` | Lock file / cache issue in CI | J | ### A. Stale `node_modules` ```bash rm -rf node_modules npm install ``` If still broken, also clear npm cache: ```bash npm cache verify npm cache clean --force # last resort npm install ``` ### B. TypeScript compile error Read the `error TS####:` line. Common patterns: | Code | Meaning | Fix | | ------ | ----------------------------------- | ------------------------------------------------------------- | | TS2304 | Cannot find name | Missing import | | TS2322 | Type X is not assignable to type Y | Adjust types or cast carefully | | TS2339 | Property does not exist on type | Property genuinely missing, or wrong type — check declaration | | TS6133 | Declared but never read | `noUnusedLocals: true`; remove the unused thing or use it | | TS6053 | File not found | Path typo or missing source file | | TS7006 | Parameter implicitly has 'any' type | `noImplicitAny: true`; annotate the parameter | Run `npm run build:tsc` for the cleanest TS error output (Webpack obscures TypeScript errors slightly). ### C. Webpack `Module parse failed` on a `.ts` file ts-loader didn't get a chance to compile. Verify `webpack.config.js` rules: ```js module: { rules: [ { test: /\.tsx?$/, use: 'ts-loader', exclude: /node_modules/ }, ], }, ``` If this looks right, `ts-loader` may not be installed: ```bash npm install ls node_modules/ts-loader ``` ### D. ESLint can't find tsconfig ``` eslint.config.mjs » @typescript-eslint/... Parsing error: Cannot read file '/.../tsconfig.json' ``` ESLint runs from a directory without `tsconfig.json`. Run from the repo root: ```bash cd /app # or wherever the repo is npm run eslint:check ``` ### E. ESLint rule violation Common violations and fixes: | Rule | Violation | Fix | | ------------------------------------ | ---------------------------- | -------------------------------------------------------------------------------------- | | `no-console` | `console.log(...)` in `src/` | Remove it. Tests are exempt | | `semi` | Stray semicolon | Run `npm run prettier:fix` | | `@typescript-eslint/no-unused-vars` | Declared but unused | Remove or prefix with `_` | | `@typescript-eslint/no-explicit-any` | `any` type | Use `unknown` and narrow, or suppress with `// eslint-disable-next-line` and a comment | If the rule is genuinely wrong for the case, suppress with: ```ts // eslint-disable-next-line @typescript-eslint/<rule-name> const result: any = ... ``` …and **always** add a comment explaining why. ### F. Prettier formatting ```bash npm run prettier:fix git diff # review what Prettier changed ``` If Prettier and ESLint disagree (rare — `eslint-config-prettier` should prevent this), ensure `eslint-plugin-prettier/recommended` stays **last** in `eslint.config.mjs` so it wins. ### G. Mocha timeout — regenerator accidentally enabled Open `test/prepareEmojiLibJson.test.ts`. If line ~39 reads `it(...)` instead of `it.skip(...)`, that's the bug. Restore: ```ts it.skip('create emojis lib json file', () => { ``` Save, re-run `npm test`. Tests now finish in ~5 seconds. ### H. Real test failure The test asserts something the code no longer does. Two sub-cases: 1. **Test is right, code is wrong** — fix the code in `src/index.ts` 2. **Test is wrong, code is right** — update the test If the failing test is in `emojiLibJson.test.ts` after a regeneration, see [`/regenerate-emoji-lib`](regenerate-emoji-lib.md) — the count or sample data probably changed. If the failing test is a snapshot of HTML output and `@twemoji/parser` was bumped, the URL format changed: - If the change is intentional (bumping Twemoji is documented): update the test expectation, **bump the major version** (HTML output change is breaking) - If the change is unintentional: pin Twemoji back ### I. `npm publish` auth | Error | Fix | | ------------------ | --------------------------------------------------------------------------------------------------------- | | `401 Unauthorized` | Token expired or wrong scope. Generate a new automation token in npm settings; update `secrets.NPM_TOKEN` | | `403 Forbidden` | Token doesn't have publish access for this package. Verify with `npm access list packages` | | `404 Not Found` | First publish — add `--access public` (for scoped packages) | | `EPUBLISHCONFLICT` | Version already exists. Bump and retry | ### J. CI cache / lock issues ```yaml # .github/workflows/code_check.yml caches node_modules and ~/.npm ``` If CI is using a stale cache: 1. Bump the cache key in the workflow (e.g., add `-v2` to the key string) 2. Or push an empty commit to invalidate (won't always work) 3. Or delete the cache via GitHub UI: Repo → Actions → Caches → Delete ### 3. After fixing ```bash npm install # If you touched package.json npm run eslint:check npm run prettier:check npm test npm run build npm run build:tsc # If you touched TS configs ``` All five should pass. If the original failure was in CI, push and verify the workflow goes green. ### 4. Don't bypass Avoid: - `--skip-tests`, `--no-test`, `it.skip`-ing the failing test (unless it's testing something that no longer applies and you've considered carefully) - Disabling lint rules wholesale (`/* eslint-disable */` at the file level) — target the specific line - Lowering TypeScript strictness (`strictNullChecks: false`) to make errors go away - Editing `dist/` directly to "fix" a build issue — the next build overwrites it ### 5. Document recurring failures If you fix the same kind of build break twice, write it up: - Add a note to [`docs/getting-started/TROUBLESHOOTING.md`](../../docs/getting-started/TROUBLESHOOTING.md) - Add a defensive check in `package.json` scripts or a workflow if applicable ## Don't - ❌ Disable a check to make the build pass - ❌ Bump every dependency at once when a build breaks — bump one, build, then the next - ❌ Edit `dist/` files (gitignored, regenerated) - ❌ Run `git checkout -- .` to "reset" partial work without investigating ## Do - ❌ Read the actual error message before guessing the fix - ✅ Use `npm run build:tsc` for clearer TS errors than `npm run build` - ✅ Run all four checks (lint + format + test + build) after fixing - ✅ Commit the fix with a `fix:` conventional message