ask262/AGENTS.md

AGENTS.md - Ask262 Project Guide

Project Overview

Ask262 is a RAG-based AI chat agent for exploring the ECMAScript specification and its implementation in engine262 (a JavaScript engine written in JavaScript).

The agent combines:

• Vector search (via LlamaIndex + Ollama embeddings) to find relevant spec sections
• Knowledge graph (via Graphology) mapping spec sections to implementation functions
• LLM reasoning (via OpenAI-compatible API) to answer questions about JavaScript internals

Users ask questions like: "How does the if statement work?" or "Which function implements sec-if-statement?"

Prerequisites

• Node.js 18+ with Bun runtime
• Ollama installed locally with nomic-embed-text model
• NVIDIA API key (or other OpenAI-compatible endpoint) in config.json

Project Structure

ask262/
├── agent.ts              # Main ReAct agent - answers user queries
├── agent-tools/          # Agent tool implementations
├── constants.ts          # Directory paths and file locations
├── config.json           # API keys and endpoints (user-created)
├── setup/
│   ├── ingest.ts         # Ingests spec HTML into vector index
│   ├── buildGraph.ts     # Builds knowledge graph (spec → code mappings)
│   └── stripSpecContainer.ts   # Cleans spec HTML files
├── spec-built/multipage/ # ECMAScript spec HTML files (ecmarkup output)
├── engine262/src/        # JavaScript engine implementation code
├── storage/              # Vector index persistence (LlamaIndex)
└── graphology/           # Knowledge graph JSON file

Key Files:

• agent.ts: ReAct agent with two tools - spec_retriever (vector search) and graph_explorer (graph navigation)
• setup/ingest.ts: Parses HTML files, extracts emu-clause sections, chunks them, creates embeddings
• setup/buildGraph.ts: Parses spec sections and code functions, creates nodes/edges showing which functions implement which spec sections
• constants.ts: Defines STORAGE_DIR, SPEC_DIR, CODE_DIR, GRAPH_FILE

Commands

Manual:

bun run setup/ingest.ts     # Direct ingest execution
bun run setup/buildGraph.ts  # Direct graph build
bun run agent.ts "Your question here"  # Direct agent execution

Code Style Guidelines

Imports & Modules

• Use ES modules (import/export), never CommonJS
• Node.js built-ins: import fs from "node:fs" (with node: prefix)
• Third-party: import * as cheerio from "cheerio"
• Type: "type": "module" in package.json

Formatting (Biome)

• Indent: 2 spaces (not tabs)
• Excluded: spec-built/, engine262/, graphology/ (external/vendor)

TypeScript

• Target: ES2022
• Strict mode: Enabled
• Module resolution: Node
• Explicit types for function parameters and return values
• Use as const for literal arrays
• Avoid any - use proper types or unknown

Comments & Documentation

• JSDoc for public functions explaining purpose, params, return values
• Inline comments for complex logic or non-obvious decisions
• Use // for implementation notes, /** */ for documentation

Important notes

1. Always use Typescript for implementation. Don't use plain javascript.