themackabu.com / ant
MIRROR: javascript for 馃悳's, a tiny runtime with big ambitions
1
fork

Configure Feed

Select the types of activity you want to include in your feed.

ant / AGENTS.md
at master 3.5 kB view raw view code
theMackabu clean up dead code in promise path
c8e4eafa

AGENTS.md#

Status: active Last reviewed: 2026-04-09 Owner: theMackabu

This file is the table of contents for agent work in Ant. Start here, then open the smallest linked document that matches the task instead of loading the entire repository into context.

Start Here#

Fast Path#

  • Start here for most changes: maid preflight
  • Build from an existing configured tree: meson compile -C build
  • Fresh local setup: maid setup
  • Run a focused test file: ./build/ant tests/test_<name>.cjs
  • Run the spec suite: ./build/ant examples/spec/run.js --all
  • Run the individual harness steps when needed: maid validate_changes, maid structure, maid knowledge

Codebase Map#

  • src/main.c, src/ant.c, and src/runtime.c wire process startup and the runtime entrypoints.
  • src/silver/ contains the parser, compiler, VM, and JIT-facing execution logic for the Ant Silver engine.
  • src/gc/ contains heap layout, roots, strings, ropes, and collection logic.
  • src/modules/ and src/builtins/ implement built-in modules and host APIs.
  • src/http/, src/net/, and src/streams/ are the transport and I/O stack.
  • src/pkg/ is the Zig package manager; src/strip/ is the Rust type-stripper.
  • meson/ and meson.build define the build graph and generated headers.
  • .github/agents/ contains the lightweight repo-harness checks and validation router used by local tasks and CI.
  • tests/, examples/spec/, and tools/wpt/ cover targeted runtime tests, the spec suite, and conformance harnesses.

See ARCHITECTURE.md for subsystem boundaries and change guidance.

Change Rules#

  • Prefer changes in src/, include/, meson/, tests/, tools/, and .github/agents/.
  • Treat vendor/ and build/ as generated or third-party surfaces. Only edit them when the task explicitly requires it.
  • Keep durable design notes and execution history in versioned markdown under docs/. Treat todo/ as scratch space, not the source of truth.
  • Add or update tests when behavior changes.
  • When touching build or runtime invariants, document the reasoning in docs/exec-plans/index.md or a linked plan if the work spans multiple steps.
  • Builds and broad validation runs (for example maid build or spec runs with --all) may need broader system access; pause and get explicit user approval before proceeding when sandbox escalation is required.
  • Check docs/repo/testing.md before choosing validation scope or retrying a failing broad test command.
  • Before finalizing most code changes, run maid preflight and then execute any additional build or spec commands it recommends, or explain why they were not run.

Which Doc To Open Next#

Keep This File Small#

AGENTS.md should stay a concise entrypoint. Add durable detail to the linked documents instead of expanding this file into a manual.