24 lines
1.7 KiB
Markdown
24 lines
1.7 KiB
Markdown
# AGENTS
|
|
|
|
## Repository Purpose
|
|
- Provide a single home for personal mpv Lua scripts so they share release tooling, lint rules, and documentation.
|
|
- Keep each script self-documenting through richly annotated headers while this file explains meta-level conventions.
|
|
|
|
## Layout & Conventions
|
|
- `scripts/` — every Lua script lives here; filenames stay unique and map 1:1 to `script-name` values.
|
|
- `scripts/<name>.lua` — script headers must summarize behavior, configuration, and dependencies because per-script AGENTS docs were removed.
|
|
- Root configs (`.luacheckrc`, `stylua.toml`) apply to the entire tree; do not duplicate them inside subdirectories.
|
|
- Tests, fixtures, or helper assets should be placed alongside the script that depends on them using clear suffixes (e.g., `*_spec.lua`).
|
|
|
|
## Tooling
|
|
- **Linting**: `luacheck scripts` (Lua 5.2 std, mp/mpv globals allowed, long format warnings suppressed via config).
|
|
- **Formatting**: `stylua scripts` (2-space indent, 100-column width, Unix newlines, double quotes preferred).
|
|
- **mpv runtime**: target mpv 0.36+ with the bundled Lua 5.2 interpreter; scripts should avoid third-party Lua modules unless vendored.
|
|
- **Automation**: use `just` targets for common chores—`just fmt` formats, `just fmt-check` verifies formatting, `just lint` runs luacheck, and `just check` chains the formatting check plus lint.
|
|
|
|
## Working With The Repo
|
|
1. Add new scripts under `scripts/` and document behavior in the top comment block.
|
|
2. Run `stylua` followed by `luacheck` before committing.
|
|
3. Use Conventional Commits for every git commit (e.g., `feat:`, `fix:`, `chore:`) so tooling can parse history cleanly.
|
|
4. Update this file when repo-level layout or tooling changes so future contributors understand the structure.
|