Chris Tate
f5f04a5f49
* Warn on non-null assertions - Surface non-null assertions during linting without making them blocking. - Preserve existing assertion sites for opportunistic cleanup. * Classify internal compiler errors - Export InternalCompilerError and migrate compiler invariant throws without changing messages. - Rename the native cache test to match cc.ts and update test scheduling references. - Document test placement by unit, package integration, and cross-package scope. * Fix internal compiler error classification
2.5 KiB
Agent Guide
Guidance for agents (and humans) working on this repository. These conventions apply repo-wide; the docs site under docs/ additionally has its own conventions in docs/AGENTS.md.
Build and test
pnpm install && pnpm -r build # build the workspace
pnpm test:sandbox # default full gate: plain + sanitized lanes (~4 minutes)
Use focused local tests while iterating, then use pnpm test:sandbox whenever a
full validation gate is required. It loads Sandbox configuration from the
shell and .env.local, runs portable coverage across disposable Linux
Sandboxes, and retains the Darwin-native contracts on macOS. Linux hosts run
their supported native-clang contracts locally; other hosts retain those
checks in the Sandboxes. Both lanes green is the bar before shipping any
change.
Only when Vercel Sandbox credentials or SCRIPTC_SANDBOX_IMAGE are unavailable,
run the slower local fallback:
SCRIPTC_TEST_WORKERS=4 pnpm test # plain lane
SCRIPTC_TEST_WORKERS=4 SCRIPTC_SAN=1 pnpm test # sanitized lane
SCRIPTC_TEST_WORKERS caps the vitest worker pool so concurrent agents don't
contend for cores; full local suites also queue behind an advisory lock per
lane.
Corpus programs are differential tests against Node: every program runs under Node and as a compiled native binary, and stdout, stderr, and exit codes must match byte-for-byte. A new feature lands with corpus programs that pin its behavior both ways.
Test location follows scope:
- Co-locate white-box unit tests with implementation files under
packages/*/src; name them after the source file (cc.ts→cc.test.ts). - Put package-level API and integration tests in
packages/*/test. - Put cross-package differential, harness, and end-to-end tests in the root
tests/tree.
Keep existing tests in place unless a change already touches their organization; new tests should follow this convention.
Where things live
packages/compiler— the frontend (tsc API to IR), the typed IR with validator and serializer, and the LLVM and C backends.packages/runtime— the C runtime compiled into every scriptc binary.packages/cli—scriptc build | run | coverage.tests/— the differential corpus, diagnostics snapshots, and the harness.docs/— the documentation site (standalone pnpm workspace); seedocs/AGENTS.md.scripts/— repo tooling, including the release version stamp.
Releases
Releases are maintainer-run; see RELEASING.md.