# builtin-ext/ — builtin extension directory

The directory of extension modules that ship with stupidtools (plan
todo 20). It is currently empty on purpose; it exists to lock the
convention.

## What goes here

Lua extension modules (`*.lua`) that load by default on every run. A
module registers checks and languages through the sandboxed runtime's
`st` API:

```lua
st.register_check("magic")
st.register_language("fortran")
```

Only regular files with a `.lua` suffix are loaded (dotfiles are
skipped); anything else here — this README included — is ignored by
discovery. Files load in bytewise-lexicographic order.

## How discovery finds this directory

`st_ext_discover()` (src/ext/discovery.c) scans this directory LAST in
the search order:

1. each `--ext-dir` directory (repeatable flag),
2. each `STUPIDTOOLS_EXT` entry (colon-separated environment list),
3. the user directory: `$XDG_DATA_HOME/stupidtools/ext`, falling back
   to `$HOME/.local/share/stupidtools/ext`,
4. this directory.

The location is the `STUPIDTOOLS_BUILTIN_EXT_DIR` macro — currently the
literal `builtin-ext`, resolved relative to the working directory of
the running binary (fine for the in-repo layout). When an installed
layout arrives, the build will override it at compile time, e.g.
`-DSTUPIDTOOLS_BUILTIN_EXT_DIR='"<prefix>/share/stupidtools/ext"'`, and
ship modules here.

## Why it is empty today

The builtin C and C++ language modules are compiled C code
(`src/ext/lang_c.c`, `src/ext/lang_cpp.c`), not Lua, so nothing needs
to live here yet. The first shipped Lua module arrives with the example
extension todo and could serve as a fixture for this location.