Glossary

This page explains the tools and ideas the rest of the site uses, in plain words. Each entry links to the official documentation, or to the best beginner introduction I know of. If a technique page uses a word you have not met before, it is probably here.

Jump to: Agents · Code quality tools · Testing · Proofs · Tools and environment · Programming ideas

Working with LLM agents

LLM coding agent

A program built around a large language model (LLM) that can read files, run commands and edit code on its own, in a loop, until it thinks a task is done. Examples are Claude Code, OpenAI Codex and OpenCode. This whole site is about keeping their output honest.

AGENTS.md

A Markdown file at the root of a repository that tells coding agents how to work in it. agents.md describes the convention. Some tools look for their own file name instead (Claude Code reads CLAUDE.md), so those files can just point at AGENTS.md.

Simplified Technical English (STE)

A controlled form of English with a limited vocabulary and strict grammar rules, first written for aircraft maintenance manuals so that instructions cannot be misread. See ASD-STE100 and the Wikipedia overview.

Code quality tools

Linter

A tool that reads source code without running it and reports patterns that are likely bugs or break the house style, such as an unused variable or == instead of ===. Many linters can fix some problems for you. What is a linter?

Biome

A fast linter and code formatter for JavaScript and TypeScript, used by both example repositories. Its rule list explains every rule with examples. Start with the getting started guide.

Cognitive complexity

A score for how hard a function is to follow: each if, loop and level of nesting adds to it. A linter can fail any function above a limit. See Biome's noExcessiveCognitiveComplexity and the original paper from SonarSource.

Type checker

The part of TypeScript that checks your code uses values the way their types say, before the code runs. deno check and tsc --noEmit run it on their own. See Strict type checking.

jscpd (copy-paste detector)

A tool that finds duplicated blocks of code across a project by comparing runs of tokens (words and symbols). It can ignore names and values, so it also finds code that was copied and then renamed. See jscpd on GitHub.

Knip

A tool that finds unused files, unused exports and unused dependencies in JavaScript and TypeScript projects, by following imports from your entry points. See knip.dev.

Dead code

Code that nothing in the running program uses. It still has to be read, kept compiling and kept tested, so it costs time and hides real code. Wikipedia.

Ratchet (or baseline)

A committed list of the problems a check already knows about, which is allowed to get shorter but never longer. It lets you switch a new check on today without first fixing every old problem. See Ratchets.

Import cycle

When file A imports file B and B (directly or through other files) imports A. In JavaScript this can leave a value undefined when one file starts running before the other has finished. Wikipedia.

Testing

Unit test

A small automated test of one function or module, with fixed inputs and checked outputs. Martin Fowler's short definition.

Assertion

The line in a test that checks a result, such as expect(total).toBe(45). A weak assertion like expect(total).toBeDefined() passes for almost any value. See the expect API in Deno's standard library.

Test coverage

The share of your code's lines and branches (each side of an if) that ran at least once during the tests. It tells you what ran, not what was checked. Wikipedia. Coverage tools usually write an lcov report that other tools can read.

Mutation testing

A way to test your tests. A tool makes a small change to your code, such as turning < into <=, and runs the tests. If no test fails, the change "survived", and your tests have a gap. The Stryker introduction is the best beginner explanation, even though these projects use their own runners. Wikipedia.

Equivalent mutant

A mutation that does not change what the program does for any possible input, so no test can ever catch it. For example x ?? "a" and x || "a" behave the same when x can never be an empty string.

Cucumber and Gherkin

Cucumber runs tests written as plain-English scenarios. The scenario language is called Gherkin: Given some starting state, When something happens, Then this is the result. Each line is matched to a "step definition" in code that does the real work. This style is often called behaviour-driven development.

End-to-end (e2e) test

A test that drives the whole system the way a user would, often through a real browser using a tool like Playwright.

Mock and sandbox

A mock is a fake version of an outside service that your tests talk to instead of the real thing, such as stripe-mock. A sandbox is a real test account at the provider, which behaves like production but moves no real money, such as Stripe test mode or the Square sandbox.

Webhook and callback

A request that another service sends to your site to tell it something happened, such as "this payment succeeded". Stripe's explanation is a good introduction.

Idempotent

An operation is idempotent when doing it twice has the same effect as doing it once. A payment webhook handler must be idempotent, because providers can send the same webhook more than once. Stripe on idempotency.

Race condition

A bug that only happens when two things run at the same time in an unlucky order, such as two people booking the last seat at once. Wikipedia.

Fault injection

Making part of the system fail on purpose during a test, to check the rest handles it. In these projects, an SQLite trigger makes one chosen database write fail.

Machines and proofs

State machine

A description of something that can be in one of a fixed set of states (such as waiting, paid, refunded) and the events that move it from one state to another. Wikipedia. XState's introduction is friendlier.

Invariant

A rule that must always be true, such as "the number of booked seats is never more than the capacity". Wikipedia.

Model checking

Automatically checking every possible behaviour of a simplified model of a system against a rule, instead of only the cases someone wrote tests for. Wikipedia.

TLA+

A language for describing how a system changes over time, created by Leslie Lamport, so that tools can check it. Hillel Wayne's Learn TLA+ is the gentlest start. The official site has Lamport's video course.

Apalache

A model checker for TLA+ that turns the question "can this rule ever break?" into a maths problem for an SMT solver. See the Apalache manual and its tutorial on symbolic model checking.

SMT solver

A program that decides whether a set of logical and arithmetic conditions can all be true at once. Wikipedia.

Inductive invariant

A rule that is true at the start, and stays true after any single step from any state where it was true. Those two facts together prove it is true forever, the same way mathematical induction works.

Tools and environment

Deno

A JavaScript and TypeScript runtime with a built-in test runner, formatter and type checker. The tickets repository runs on it. Deno docs.

Bun

Another JavaScript runtime and package manager, used by the chobble-template and this site. Bun docs.

Bunny Edge Scripting

A service that runs JavaScript on bunny.net servers close to the user. Each request may start a fresh copy of the program (a "cold start"), which is why the tickets code avoids heavy work at startup.

Eleventy

A static site generator: it turns Markdown and templates into plain HTML files. This site is built with it. Eleventy docs.

Nix and devenv

Nix is a package manager that can pin every tool to an exact version. devenv builds a project's development environment on top of it, from one devenv.nix file.

Lockfile

A file (such as deno.lock) that records the exact version of every dependency, so every install gets the same code. Deno on lockfiles.

Continuous integration (CI)

A service that runs your checks on every push. GitHub Actions is the one used here.

Pre-commit hook

A script that git runs before it makes a commit, which can refuse the commit if a check fails. Git hooks in the Git book.

Stacked pull requests

A large change split into a chain of small pull requests, each built on the one before it, so each can be reviewed on its own. stacking.dev explains the idea.

Programming ideas

Pure function

A function whose result depends only on its arguments, and which changes nothing outside itself: no database, no network, no clock. Pure functions are the easiest code to test. Wikipedia.

Currying

Turning a function that takes several arguments into a chain of functions that each take one. add(1, 2) becomes add(1)(2), so you can make addOne = add(1) and reuse it. javascript.info on currying.

Functional programming

A style built from small pure functions combined with helpers like map, filter and pipe, instead of loops that change variables. Mostly Adequate Guide is a free beginner book.

Schema validation

Checking that data from outside your program (a form, an API response) has the shape you expect, once, at the point where it arrives. Both repositories use Valibot for this.

Standard library

The well-tested modules that ship with a language or runtime, or are kept alongside it. Deno's standard library lives at jsr.io/@std: @std/collections for lists and maps, @std/assert and @std/expect for tests, @std/path for file paths, and more. Using it instead of writing your own helper means less code to test. See Libraries over hand-rolled code.

Discriminated union

A TypeScript type that is one of several shapes, told apart by a shared field like kind. It lets each shape carry only the fields that make sense for it. TypeScript handbook.

Fail fast

Stopping with a clear error as soon as something is wrong, instead of carrying on with a guessed value. Wikipedia. The Offensive programming page shows it in practice.

Import map and aliases

A mapping from short names like #fp to real file paths, so imports do not need long ../../ paths. See Deno's import maps and Node.js subpath imports.