CodeVetter · Repo Unpack · Contributor handoff
lodash/lodash
Read `.github/CONTRIBUTING.md` first — it states the core rule that for additions or bug fixes you should only modify `lodash.js` and add tests in `test/`, and explicitly says not to regenerate `dist/` or `doc/`. That rule is in tension with `ci-dist-sync.yml`, which fails the build if `npm run build` changes `dist/`, so a change to `lodash.js` does require a rebuild and commit of `dist/lodash.js` and `dist/lodash.min.js`. The style gate is JSCS with unusual rules (`requireEarlyReturn`, no `with`, single quotes, 2-space indent, JSDoc types required), so match the surrounding code exactly. Never hand-edit `dist/*`, `doc/README.md`, or anything under `vendor/` — they are generated or vendored.
- CONTRIBUTING states the contract directly: "For additions or bug fixes you should only need to modify `lodash.js`. Include updated unit tests in the `test` directory... Don't worry about regenerating the `dist/` or `doc/` files."
- Despite that guidance, `ci-dist-sync.yml` runs `npm run build` then `git diff --exit-code dist/` and fails with an explicit "Run 'npm run build' and commit the updated dist/ files" error — so an agent editing `lodash.js` must also commit the rebuilt `dist/lodash.js` and `dist/lodash.min.js`.
- `dist/lodash.js` is currently byte-identical to `lodash.js` (the build is a plain `fs.copy`), so any `lodash.js` edit produces a mechanically predictable dist diff.
- Files an agent must read before editing, in order: `.github/CONTRIBUTING.md`, `package.json` scripts, `lodash.js` (the target region plus the `lodash.<name> =` assignment block), `fp/_mapping.js` if the change touches FP, and `threat-model.md` if the change touches `set`/`merge`/`unset`/`template`.
- Tests to run locally: `npm test` (which force-builds via `pretest`), or the faster direct `node test/test` and `node test/test-fp` once a build exists; `npm run validate` is the full gate that CI uses.
- `node test/test <path>` accepts an alternate build path as its last argument, defaulting to `../lodash.js` — this is how you point the suite at `dist/lodash.min.js` or a core build.
- The Node suite requires the previous published lodash to be installed at `node_modules/lodash/lodash.js` as `lodashStable`; if it's missing the suite prints "The stable lodash dev dependency should be at least a version behind master branch" and silently returns without running.
- Style must match JSCS: two-space indent, single quotes (double only to avoid escaping), semicolons required, `with` banned, early returns required, and JSDoc blocks needing types, param descriptions and return types.
- Naming conventions are prescribed: prefer `index`, `array`, `iteratee` over `i`, `arr`, `fn`; JSCS additionally enforces `requireCamelCaseOrUpperCaseIdentifiers`.
- An optional pre-push hook is available by creating a root `.opt-in` file containing `pre-push`, which runs `npm run validate` on push.
- Safe edit boundary — do not touch: `dist/*` (generated, and `lodash.core*` only by external lodash-cli), `doc/README.md` (docdown output), `vendor/**` (Backbone/Underscore/json2/firebug-lite), `package-lock.json` unless deliberately updating deps.
- Trap: adding an FP-visible method means touching `fp/_mapping.js` in up to five places (`aryMethod` bucket, plus any of `aliasToReal`, `remap`, `methodRearg`, `iterateeAry`, `mutate`, `skipFixed`, `skipRearg`) or the FP build and wiki will silently omit or mis-wrap it. (inferred)
- Trap: `test/test.js` is 814 KB and `lodash.js` is 546 KB — read targeted line ranges rather than whole files, and locate work by grepping for `QUnit.module('<methodName>'` or `function base<Name>(`. (inferred)
- Trap: security-relevant behavior around `__proto__`/`constructor` is asserted by the threat model as intended design — changing `baseSet`, `baseUnset` or `safeGet` guards without reading `threat-model.md` risks reintroducing CVE-2019-10744-class bugs.
- Security issues go through the GitHub Security tab, not public issues; the TSC handles triage, and `incident_response_plan.md` encodes the full flow including a 5-day acknowledgement target and CVE request step.
- `git log` for this checkout shows a single commit touching `dist/` at HEAD (`2b5e6f7 ci: update actions to latest versions`), so treat the dist tree as freshly regenerated relative to `lodash.js`. (inferred)