Skip to content

AGENTS.md

Latest commit

 

History

History
89 lines (62 loc) · 3.66 KB

AGENTS.md

File metadata and controls

89 lines (62 loc) · 3.66 KB
Raw

AGENTS.md

This file provides guidance to AI agents when working with code in this repository.

Project Overview

Just is a Microsoft build task organization library for JavaScript/TypeScript projects. It provides a task runner (just-task) and preset build scripts (just-scripts) for common workflows (TypeScript, Webpack, Jest, ESLint, etc.).

Branches

  • v2: the current stable release branch from just-*@latest and the doc site are published.
  • main: contains development work for the next major release of just-*, version 3. Breaking changes are allowed if necessary.

Monorepo Structure

  • Yarn v4 workspaces with Lage for task orchestration
  • Workspaces: packages/* and scripts/
  • Three packages:
    • packages/just-task — Core task runner (CLI: npx just <task>, config: just.config.ts)
    • packages/just-scripts — Preset task functions (tscTask, jestTask, webpackTask, eslintTask, etc.)
    • packages/just-example-lib — Example/integration test project

Common Commands

yarn build                # Build all packages (via Lage)
yarn test                 # Run all tests (via Lage)
yarn lint                 # ESLint on packages/ (.ts,.js)
yarn api:update           # Update API reports for all packages
yarn format               # Prettier write
yarn format:check         # Prettier check (CI uses this)
yarn change               # Create Beachball change file (required before PR)

Running a single package's tests

DO NOT run jest directly. You MUST run yarn test (which wraps jest and takes all the same args) from the specific package to ensure the correct environment is set up.

cd packages/just-task && yarn test              # Run just-task tests
cd packages/just-task && yarn test --testPathPattern=cache  # Run specific test file

Required before each commit

  • yarn build
  • yarn test
  • yarn lint
  • yarn format
  • yarn api:update

Required before creating a PR

  • Use /beachball-change-file to generate a Beachball change file.
  • If you're working on an assigned GitHub issue, include Fixes #N in the PR description to link the issue.

Architecture

Task System (just-task)

Built on Undertaker (Gulp's task orchestrator). Key modules in packages/just-task/src/:

  • task.ts — task(name, fn) registration; supports prerequisite chaining
  • undertaker.ts — Wraps Undertaker with event-based colored logging and perf tracking
  • cli.ts — CLI entry point; resolves config file and bootstraps tasks
  • config.ts — Config resolution: just.config.{js,cjs,ts,cts} or just-task.js
  • chain.ts — before()/after() hooks for task composition
  • option.ts — CLI argument parsing with yargs-parser

Task functions can: return a Promise, call a done callback, or return a stream. Composition via series() and parallel() from Undertaker.

Preset Tasks (just-scripts)

packages/just-scripts/src/tasks/ contains factory functions that return task functions: tscTask(), jestTask(), webpackTask(), eslintTask(), prettierTask(), copyTask(), esbuildTask(), nodeExecTask(), etc.

Code Style

  • TypeScript target: es2019, module: commonjs, strict mode
  • Prettier: 120 print width, single quotes, trailing commas, 2-space indent
  • Tests:
    • Jest with ts-jest
    • Test files in src/**/__tests__/*.(test|spec).ts
    • Functions such as describe, it, expect must be imported from @jest/globals (they are not implicitly available)
  • Each package compiles to lib/ directory

CI / Release

  • PR checks: format:check → lint → build/test/api (Ubuntu + Windows, Node 22)
  • Release: Beachball publish (manual trigger), docs deployed to GitHub Pages