This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
@mhvelplund/scientist: a TypeScript port of GitHub's Ruby Scientist library. It has zero runtime dependencies and ships ESM and CJS builds with type declarations. It tracks upstream tag v1.6.5. The API, behavior and docs follow the Ruby original as closely as JavaScript allows. Every intentional deviation is listed in docs/differences-from-ruby.md, so update that file whenever behavior or naming diverges from Ruby.
mise pins every CLI tool in mise.toml and is the local build entrypoint. The tools are Node 24, gh, EarthBuild's earth, actionlint, uv, and commitizen (cz) and pre-commit through uv. When the repo needs a new binary, add it to mise.toml instead of documenting a manual install. mise.toml puts ./node_modules/.bin on PATH.
CI installs the tools with jdx/mise-action and runs the same steps in containers through the EarthBuild Earthfile (earth --ci +ci in .github/workflows/ci.yml). Keep its targets in step with the mise tasks. earth +pack writes the npm tarball that release.yml publishes.
mise run ci # everything CI runs: lint, typecheck, test, build, smoke
mise run lint # biome check .
mise run format # biome check --write .
mise run typecheck # tsc --noEmit (src + test)
mise run test # vitest run --coverage
mise run build # tsdown -> dist/ (also runs publint + attw)
mise run smoke # load built dist/ from CJS and ESM, type-check the declarations
mise run hooks # install git hooks (pre-commit, commit-msg, pre-push); do this once per clone
mise run bump # preview the next version/changelog (cz bump --dry-run)Run a single test file or test by name with npx vitest run test/experiment.test.ts or npx vitest run -t "pattern".
- Vitest also type-checks
test/**/*.test-d.ts(expectTypeOfassertions intest/types.test-d.ts). test/smoke/is excluded from the root tsconfig. It only runs against the builtdist/, so runbuildfirst.
One algorithm, sync and async. The experiment logic is written once, as generator functions ("steps", named *Steps) in experiment.ts, observation.ts and result.ts. src/internal.ts holds the two drivers:
runSyncexpects the generator never to yield. It throws an internal error if it does.runAsyncawaits every yielded value and resumes the generator with the result.
Every user callback result goes through one of two helpers:
behaviorValue(foruse/trybehaviors): in sync mode it passes the value through untouched.hookValue(for compare, ignore, runIf, enabled, clean and similar callbacks): in sync mode it throws aTypeErrorif it gets a Promise.
When adding logic that calls user code, write it inside a steps generator and route the value through the matching helper. Don't fork separate sync and async implementations.
Private state via WeakMap. Experiment keeps its configuration (behaviors, comparators, context, hooks, frozen flag) in a module-level WeakMap (stateOf() in experiment.ts), not in instance fields. This keeps subclass namespaces clean, because users subclass Experiment and override enabled() / publish() / raised(). After a run the state is frozen, and use/try/context(data) then throw TypeError.
Entry points.
Experiment.setDefault(klass)registers the default experiment class.Experiment.create(name)instantiates it.src/scientist.tswraps these asrun/runAsync,science/scienceAsync, theScientistbase class, and thewithScience(Base)mixin.DefaultExperimentis never enabled and never publishes.
Ruby-compat naming. Ruby names are exported as aliases in src/index.ts, for example Default, BadBehavior and NoValue. Error operations passed to raised() are the strings in RaisedOperation ("run_if" keeps Ruby's snake_case).
Tests. Unit tests in test/*.test.ts mirror upstream's test/scientist/*_test.rb. test/docs-examples.test.ts has executable copies of the examples in README.md, docs/*.md and the agent skill. When you change a doc example, update its test too.
Agent skill. skills/scientist-experiments/ (SKILL.md + reference.md) is an agent skill that users install with npx skills add mhvelplund/scientist.js. It is a condensed version of the docs, so update it whenever the public API, defaults or a documented pitfall changes.
- Every commit message must be a Conventional Commit:
type(optional-scope): summary, where type is one offeat,fix,perf,refactor,docs,test,build,ci,style,choreorrevert. Mark breaking changes with!(feat!: ...) or aBREAKING CHANGE:footer. PR titles follow the same format. Thecommit-msgandpre-pushhooks enforce it, so never bypass them with--no-verify. - Pick the type by user-visible effect, because it decides the release:
featbumps minor,fix/perfbump patch, and breaking changes bump minor while on 0.x (major after 1.0). Other types don't release. mainonly changes through PRs, and thecicheck must pass. Work on a branch and open a PR..github/workflows/release.ymlruns commitizen (.cz.toml) on every push tomain. It bumpspackage.json/package-lock.json, updatesCHANGELOG.md, tagsvX.Y.Zas thecommitizen-ciapp (the only bypass actor onmain), publishes to npm with trusted publishing, and creates a GitHub release (a pre-release for 0.x). Never edit the version orCHANGELOG.mdby hand, and never createv*tags yourself.
- Biome sets the formatting: 2-space indent, 100-column lines, double quotes. It also organizes imports.
- tsconfig is strict, with
noUncheckedIndexedAccess,noImplicitOverride(subclass overrides needoverride) andverbatimModuleSyntax(useimport type/ inlinetypeimports). - Build target is ES2022.