mirror of
https://github.com/colbymchenry/codegraph.git
synced 2026-11-14 19:41:47 +08:00
danusha2345andClaude Opus 5.5
b1e6c9767d
The repo ran two Vite stacks. ui/ builds the viewer with Vite 7 and
vite-plugin-svelte 6, while Vitest 2 at the root kept Vite 5.4 and plugin 4 with
their own esbuild, whose dev tree carried the critical audit findings. The move
leaves one stack.
Tests now run as test.projects in vitest.config.mts, so vitest.workspace.mts goes
away: engine extends the base (env, global setup, home sandbox), ui stands alone
with the Svelte plugin, jsdom and the browser conditions. The WASM flags move to
test.execArgv, because Vitest 4 ignores poolOptions.forks.execArgv with a
deprecation line and the #1779 worker death comes back. git-index-currency injects
its failures through the mocks' own vi.fn: under Vitest 4 a spy on a mocked module
is that vi.fn, so the captured real function recursed into itself, and
restoreAllMocks no longer resets one, so the injection leaked into later tests.
devEngines sets Node 22.12 as the floor for working in the repo, which is what
Vite 7 asks for; engines, what users run, is unchanged.
Changes on top of the contributor's commits:
- The lockfile is regenerated from main's, not taken from the PR: the PR's would
have put devalue, postcss and ignore back below the fixes in issues 3044 and
3050, and restored the @types/better-sqlite3 that 3044 dropped. ui's packages
hoist to the root at the versions it already built with, and rollup stays.
- testTimeout and hookTimeout rise to 30 s and 60 s. Since Vitest 3 a synchronous
test or hook that outlasts its limit fails; under Vitest 2 the timer could not
fire until the body returned, so a body blocked in spawnSync never timed out. A
6 s synchronous test passes on 2.1.9 and fails on 4.1.11, and an 11 s hook does
the same and skips its tests. The first full run lost frontload-hook to this,
the contributor's lost two bundle-launcher listings, and 31 tests passed 4 s on
a quiet machine, so on a loaded one they would all flake.
- A new test reads the WASM flags from the worker's own command line, since the
config can stop reaching workers with no failure, and a Vitest 5 move could
repeat that.
- CONTRIBUTING and AGENTS state the new floor and the projects setup; two test
files name TestProject, which replaced the removed GlobalSetupContext type.
- Left out as out of scope: a trailing blank line in ui/src/lib/trail-codec.ts.
Validated on Windows, Node 22.22, npm 10.9:
- what ships is unchanged: npm ci --omit=dev, the bundle's step, gives 193 files
byte-identical to main's; npm run build:lib gives 171 byte-identical files;
dist/viewer matches main's once Svelte's scope hashes, which come from the
checkout path, are masked (main built in two folders differs the same way).
- every test is kept: at cd04b21a vitest list finds 9,719 tests on main (9,701
engine, 18 ui) and those plus the new guard here, each in the same project, none
twice.
- npm's own checks across Node versions: from 22.12 up, devEngines passes and no
package warns EBADENGINE, the same as main; below it npm ci and npm run stop with
EBADDEVENGINES. Node 20 could not run from source already, and Vite 7 rejects
22.5 to 22.11. npm ci logs the one deprecation main logs. release.yml's lock sync
changes only the version fields.
- dev tree audit: main 10 findings with 2 critical, here 7 with none critical;
production stays at 0.
- red to green: main's git-index-currency fails 7 of 13 under Vitest 4; putting
the flags back under poolOptions turns the guard red.
Original PR #1667 by @danusha2345.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
73 lines
4.9 KiB
Markdown
73 lines
4.9 KiB
Markdown
# Contributing to CodeGraph
|
|
|
|
Thanks for helping out. Small, focused changes are the easiest to review and land.
|
|
|
|
**Reporting a bug?** Open an [issue](https://github.com/colbymchenry/codegraph/issues) with your CodeGraph version (`codegraph --version`), Node.js version, operating system, the steps to reproduce it, what you expected, and what happened instead. A small public repository or snippet that shows the problem helps most.
|
|
|
|
**Asking for a feature?** Describe the use case and why what's there today doesn't cover it.
|
|
|
|
## Build from source
|
|
|
|
You need Git, npm, and Node.js 22.12 or later, below 25. `npm ci` stops on anything older, because the build and test tools need it and running from source uses Node's built-in `node:sqlite`; the published installers bundle their own Node, so this only matters here.
|
|
|
|
```bash
|
|
# Fork the repository on GitHub, then:
|
|
git clone https://github.com/<your-username>/codegraph.git
|
|
cd codegraph
|
|
git remote add upstream https://github.com/colbymchenry/codegraph.git
|
|
|
|
npm ci
|
|
npm run build
|
|
```
|
|
|
|
A globally installed `codegraph` doesn't run your changes, so run your build directly:
|
|
|
|
```bash
|
|
node dist/bin/codegraph.js --help # the build as it stands
|
|
npm run cli -- status # rebuild first, then run a command
|
|
npm run dev # recompile TypeScript on every save
|
|
```
|
|
|
|
`npm run build` covers the CLI, the SQL schema, the parser grammars and the browser viewer. Two builds are separate:
|
|
|
|
- `npm run build:kernel` builds the optional native extraction kernel, and needs a Rust toolchain. Tests that need the kernel are skipped without it.
|
|
- `npm run build:lib` builds the viewer's component library.
|
|
|
|
## Test your change
|
|
|
|
```bash
|
|
npx vitest run __tests__/extraction.test.ts # one file
|
|
npx vitest run __tests__/extraction.test.ts -t "TypeScript" # tests matching a name
|
|
npm run test:watch # rerun as you edit
|
|
npm test # everything
|
|
```
|
|
|
|
Run the focused tests while you work, then `npm test` before opening a pull request. Tests that run the compiled CLI use `dist/`, and the test setup rebuilds it first when it's stale.
|
|
|
|
- **Tests live in `__tests__/`** and use real files and real SQLite databases, with no database mocking. Create temporary folders with `fs.mkdtempSync` and remove them in `afterEach`.
|
|
- **A bug fix needs a test that fails without the fix.**
|
|
- **Behavior that differs by platform** gets a gated test, such as `it.runIf(process.platform === 'win32')(...)`, and needs checking on the platforms it affects. See [cross-platform validation](AGENTS.md#cross-platform-validation).
|
|
- **New language or framework support** needs validating on real repositories. Start with the `/add-lang` skill in [`.claude/skills/add-lang/SKILL.md`](.claude/skills/add-lang/SKILL.md), then follow the [validation methodology](docs/AGENTS.md#validation-methodology-required-for-every-new-languageframework) and the [coverage playbook](docs/design/dynamic-dispatch-coverage-playbook.md). Before extending a router or web framework, read [framework coverage](docs/design/framework-coverage.md).
|
|
- **A documentation-only change** doesn't need the test suite. Check its examples and links instead.
|
|
|
|
## Prepare a pull request
|
|
|
|
- Branch from the latest `main`, and keep to one concern. Unrelated formatting, CI or feature work belongs in its own pull request.
|
|
- Name commits `type(scope): what now works`, such as `fix(go): a constant in a const ( … ) group keeps its own doc comment`. Types in use are `feat`, `fix`, `docs`, `test`, `perf`, `chore` and `ci`.
|
|
- In the description, explain the problem, the resulting behavior, and what you ran, including any failures and any platform you couldn't test.
|
|
- Keep existing CLI commands and the default MCP tools working, unless the pull request exists to change them and says why.
|
|
- Add a line to `CHANGELOG.md` under `## [Unreleased]`, in `### New Features` or `### Fixes`, for anything a user would notice. Write one plain sentence about what changed for them, without internal file names or benchmark numbers. Changes to the `codegraph ui` viewer, which isn't released yet, go in [`docs/viewer-launch-changelog.md`](docs/viewer-launch-changelog.md) instead.
|
|
- Don't bump the version, and change `package-lock.json` only when you add or remove a dependency.
|
|
- Use public or made-up examples. Keep local paths, private code and machine-specific settings out of fixtures.
|
|
|
|
## What happens next
|
|
|
|
A maintainer reads every change closely before anything lands, and may ask for changes. Keep your branch up to date by rebasing on `main`.
|
|
|
|
A maintainer may also land your contribution as their own commit, rewritten where needed, instead of merging your branch. You're credited in the changelog either way.
|
|
|
|
## Find your way around
|
|
|
|
- [Documentation index](docs/README.md): guides, design notes and benchmarks.
|
|
- [AGENTS.md](AGENTS.md): the architecture and the development rules, which [CLAUDE.md](CLAUDE.md) imports for Claude Code.
|