script-auditor

Files (2)

• SKILL.md
• audit-helper-scripts.mjs · scripts/

SKILL.md (first lines)

# Script auditor

Check helper scripts in this repository against the "Scripts" guidelines in `AGENTS.md`, and bring them into compliance. Use this skill when creating a new helper script, reviewing one in a diff, or sweeping the whole repo for drift.

The guidelines this skill enforces:

* **Language.** Default to Node.js ES modules (`.mjs`) or zsh. Python is banned (the overhead of managing Python environments across machines is not worth it). Non-module JavaScript (`.js` / `.cjs`) and non-zsh shells are allowed but not the default.
* **`--help`.** Every script must support `--help` and print clear, informative usage.
* **Notes section.** Every script must carry a notes section near the top with general notes (what it does), usage (how to invoke it), output (what it generates or returns), and a version history (a reverse-chronological list, each entry in the form `vX.Y - YYYY-MM-DD - summary of the change`).
* **Version format.** Each version history entry must read `vX.Y - YYYY-MM-DD - summary of the change`, newest first. The auditor checks the form, not just that a version history exists.
* **Status emojis.** Scripts should use emojis to clarify status, for example ✅ for success, ⚠️ for warnings, and ❌ for errors.


## Scope

In scope:

* Helper and tooling scripts tracked by git under a `scripts/` directory - both the top-level `scripts/` folder and a skill's own `skills/<skill-name>/scripts/` folder.
* Files with a script extension (`.mjs`, `.js`, `.cjs`, `.sh`, `.zsh`, `.bash`, `.py`).

Out of scope (the auditor skips these):

* Vendored Figma plugin scripts under `skills/figma-*/scripts/`. These are Figma Plugin API snippets run inside Figma via `use_figma`, not repo CLI helpers, so the script-authoring guidelines do not apply to them.
* Non-script files (Markdown, CSV, JSON, YAML, lockfiles).
* Source files that are not helper scripts and do not live under a `scripts/` directory.


## Quick start

Run the bundled auditor from anywhere inside the repo (requires Node.js 24+):

```bash
# Sweep all tracked helper scripts and print a per-script report.
node skills/script-auditor/scripts/audit-helper-scripts.mjs

# Audit specific scripts (for example, the ones in the current diff).
node skills/script-auditor/scripts/audit-helper-scripts.mjs scripts/my-tool.mjs

# Machine-readable output for further processing.
node skills/script-auditor/scripts/audit-helper-scripts.mjs --json
```

Exit codes:

* `0` - every audited script passes.
* `1` - at least one warning or failure was found.
* `2` - configuration error (not a git checkout, no scripts found, unreadable file).


## Workflow

1. **Scope the run.**
   * When the user just added or changed scripts, pass those paths explicitly so the report stays focused.
   * For a repo-wide health check, run with no file arguments to audit every tracked helper script.

2. **Audit.** Run the bundled script. Read the per-script report. Each script gets one of three verdicts:
   * ✅ ok - all five checks pass.
   * ⚠️ warning - a soft signal only (for example, a `.js` file that should be `.mjs`, or a bash script where zsh is the default). Mention it, but do not block on it.
   * ❌ failing - a hard guideline is broken (Python, missing `--help`, an incomplete notes section, or a version history with no entries).

3. **Report.** Summarize for the user: which scripts pass, which have warnings, and which fail and why. Group by guideline so the fix list is clear.

4. **Fix (on request or when authoring).**
   * **New script you are writing:** make it pass all five checks before finishing - use `.mjs` or zsh, add a notes section, wire up `--help`, and use status emojis. Use the template below.
   * **Existing failing script:** apply the smallest change that satisfies the guideline. Add a notes section, add `--help` handling, or swap status messages for emoji-prefixed ones. Do not rewrite a working script wholesale.
   * **Python script:** flag it for a rewrite to `.mjs` or zsh. This is a larger change - confirm with the user before rewriting, and preserve the script's behavior and any `pnpm` script wiring.

5. **Re-audit.** Run the auditor again on the changed files and confirm the verdict is now ✅.

6. **Update indexes.** If you added a new script, update `scripts/README.md` (or the relevant folder README) and any `pnpm` script wiring in `package.json`, per the project conventions.


## What each check looks for

The checks are heuristics that surface candidates for review, not a hard gate. Confirm a flagged finding by reading the file before acting on it.

* **Language.** Reads the file extension and shebang. `.py` or a `python` shebang fails. `.mjs` and zsh pass. `.js` / `.cjs` and non-zsh shells warn.
* **`--help`.** Looks for `--help` anywhere in the source. A script that parses `--help` but routes it elsewhere may need a manual check.
* **Notes section.** Scans the first ~60 lines (the leading comment block) for the words that mark the four required parts: a general description (`general notes`, `description`, `purpose`, or `notes`), `usage`, `output`, and `version history`. A script that documents these with different wording may need the keywords added so the intent is explicit.
* **Version format.** Finds the `Version history:` header on its own line, then validates every following line that opens with a version number against `vX.Y - YYYY-MM-DD - summary` (a three-part `vX.Y.Z` is accepted too). Indented continuation lines of a multi-line entry are ignored. A malformed entry warns; a header with no entries at all fails.
* **Status emojis.** Looks for any status emoji (✅, ⚠️, ❌, and common siblings) in the source. A library-style script with no user-facing output is a reasonable exception - note it and move on.


## Script template

A new Node.js helper that passes all five checks starts like this:

```javascript
// my-tool.mjs notes
// General notes:
// * Purpose: <one-line description of what this script does>.
// Usage:
//   node scripts/my-tool.mjs [options]
// Output:
// * <what the script prints or writes, and its exit codes>.
// Version history:
// * v1.0 - <YYYY-MM-DD> - Initial release.

function printUsage() {
  console.log('Usage: node my-tool.mjs [options]');
}

// ... parse argv, handle --help by calling printUsage() and exiting ...

console.log('✅ Done.'); // use ✅ / ⚠️ / ❌ for status
```

For zsh, put the same notes block in `#` comments near the top, handle `--help`/`-h` in argument parsing, and prefix status output with the same emojis. See `skills/skill-allowlist-syncer/scripts/check-skill-allowlist.mjs` for a fully compliant example, including the version history format (a reverse-chronological `vX.Y - YYYY-MM-DD - summary` list).


## Bundled resources


### scripts/audit-helper-scripts.mjs

Audits helper scripts against the five guidelines and prints a per-script verdict.

Behavior:

From ahandsel/tokyo-geek, MIT.

More from ahandsel/tokyo-geek