Skip to content

README.md

Latest commit

 

History

History
73 lines (62 loc) · 3.61 KB

README.md

File metadata and controls

73 lines (62 loc) · 3.61 KB

Script Guide

One-line index of repository scripts. ./scripts/check.sh is the final gate for local development. Detailed flags and operating guidance for the Test262 and gap-discovery scripts live in docs/harness.md; this file only says what each script is for.

Daily Checks

  • check.sh: Standard project gate: formatting, clippy, workspace tests, and file-size limits.
  • check-ci.sh: Local parity wrapper for the GitHub Actions check job. It runs check.sh with serialized, split runtime tests and skips Test262 because the workflow owns that in a dedicated job.
  • check-touched.sh: Change-aware fast gate for AI iteration and pre-commit. Use --staged --explain before committing, or --base <ref> --explain to validate a branch slice. It runs relevant crate tests and focused Test262 allowlist filters when touched paths imply a semantic area.
  • compare-qjs.sh: Runs tests/fixtures/compare-qjs/ fixtures against both quickjs-rust and the pinned QuickJS-NG reference.
  • find-qjsng-gaps.sh: First agent entrypoint for conformance work. Wraps test262-baseline.sh --engine both, reports actionable gaps, and prints a greedy recommendation queue. See docs/harness.md for strategies, probe tuning, and replay flags.
  • test262-subset.sh: Runs the curated Test262 allowlist (tests/test262/allowlist.txt); passing expected failures are reported as stale entries. scripts/check.sh runs the same subset with a 30-second per-case timeout by default to match CI; direct subset runs default to 10 seconds unless TEST262_CASE_TIMEOUT_SECONDS is set.

Conformance Measurement

  • test262-baseline.sh: Samples or scans upstream Test262, classifying structural not-run cases, failures, and timeouts; --engine both compares against QuickJS-NG under its own test262 config. Set QJS_CLI_BIN to reuse a prebuilt binary across shards, or QJS_CLI_PROFILE=release to build an optimized quickjs-rust runner for timeout-sensitive scans. Set TEST262_TIMEOUT_RETRIES to retry only timeout results with the same per-case timeout. The generated quickjs-rust case source injects Test262 harness files only when the case or its metadata includes require them.
  • test262-aggregate.py: Aggregates QuickJS-NG and quickjs-rust case-result JSONL sets into the CI coverage summary, the schema-1 burndown entry, and an optional merged per-case comparison JSONL for follow-up gap selection. Used by the Test262 Coverage workflow; also runs locally on artifacts downloaded with gh run download.
  • test262-burndown.sh: Appends a complete-scan entry to docs/conformance/burndown.jsonl; rejects partial or filtered scans.
  • test262-baseline-metadata.awk: Internal metadata parser shared by the Test262 scripts.

Focused Development

  • bootstrap.sh: Initializes submodules and prefetches crates for a fresh checkout.
  • microbench.sh: Runs the QuickJS microbenchmark subset, optionally against QuickJS-NG.
  • source-size-report.sh: Reports large first-party files; --vendor scans pinned upstream files instead.

Agent Workflow

  • create-agent-worktree.sh: Creates an isolated agent/** branch and worktree for one coding owner.
  • validate-agent-branch.sh: Checks that an agent branch started from the expected base sha and stayed inside its path boundary.

Internal Helpers

  • lib.sh: Shared helpers (cargo resolution, QuickJS-NG build, qjs-cli build, timeout wrapper check) sourced by the other scripts.
  • check-file-size.sh: Enforces file-size limits; called by check.sh.
  • run-with-timeout.sh: Runs a command with a timeout; shared by comparison, benchmark, and Test262 scripts.