SuperAPI AI Directory

dym-impeccable-contributor-build-and-test

Coding & development

View repository

Updated 10-18 01:38

About this skill

Skill: dym-impeccable-contributor-build-and-test — Contributing: build and test Impeccable itself

Why use it: you clone pbakaus/impeccable to change detector rules or skills, or add a provider — and need a correct build/test loop from the first run. What it produces: dist/ (per-provider bundles), regenerated provider directories in the repository (must be committed), and test results.


Requirements

Item Version Notes
Bun 1.3.x (run with 1.3.5) Primary package manager and test runner
Node ≥ 22.18.0 CI runs a matrix of 22.18.0 and 24
Chrome — Needed only for the detector: bunx puppeteer browsers install chrome
Playwright chromium — Needed only for the live-e2e* opt-in suites: npx playwright install chromium

The basic loop

git clone https://github.com/pbakaus/impeccable
cd impeccable

bun install                    # ~24s, 227 package
bun run build                  # ~7s
env -u OPENCODE_CONFIG_DIR bun run test:core   # ~72s — xem cảnh báo bên dưới

bun run build ends with self-checks; use these to determine whether the build is healthy:

✓ Generated counts: 23 commands, 61 detection rules
✓ Plugin/skill versions agree: 4.1.3
✓ Plugin manifest shape matches the verified loader contract
✓ Prose validator: no AI tells in user-facing copy
✓ Skill prose validator: skill/ is clean
✓ ask_instruction call sites: 8 sentence-initial

✨ Build complete!

Other build scripts in package.json:

Command What it does
bun run build:skills Build skills only, skipping synchronization to the root
bun run build build:skills + copy dist to build/_data/dist
bun run build:release As above, but with synchronization to the root (for releases)
bun run build:browser Regenerate cli/engine/detect-antipatterns-browser.js
bun run build:extension Package the extension — see 07
bun run clean / rebuild rm -rf dist build / clean, then build

⚠️ The easiest gate to miss: generated output must be committed

CI checks that generated provider directories are already in the commit (.github/workflows/ci.yml:113-114):

- name: Verify generated tracked outputs
  run: git diff --exit-code -- .agents .claude .cursor .gemini .github/skills plugin cli/engine/detect-antipatterns-browser.js extension/detector

Changing skill/SKILL.src.md and committing only the source makes CI fail. The correct process:

# sửa skill/SKILL.src.md hoặc cli/engine/...
bun run build
git add -A .agents .claude .cursor .gemini .github/skills plugin \
          cli/engine/detect-antipatterns-browser.js extension/detector
git commit -m "..."

Check before pushing, using the exact command CI runs:

bun run build && \
git diff --exit-code -- .agents .claude .cursor .gemini .github/skills plugin \
  cli/engine/detect-antipatterns-browser.js extension/detector \
  && echo "GATE CLEAN" || echo "GATE DIRTY — commit generated output"

Actually run on a clean checkout at fcc271c: bun run build ; afterward, the gate was clean — the build is deterministic and does not create incidental changes.

The repository's latest commit is literally named Sync generated provider output — this is the normal workflow, not an incident.

⚠️ Environment trap: OPENCODE_CONFIG_DIR causes 8 tests to fail

Running without cleanup on a machine with this variable set (Orca sets it):

518 pass · 8 skip · 8 fail

All 8 failures are in tests/skills-cli.test.js, and the assertion states the reason:

Expected to contain: "Install target: [1] Detected only (claude, codex, cursor, gemini)  [2] Customize [1]:"
Received:            "... [1] Detected only (claude, codex, cursor, gemini, opencode)  [2] Customize [1]: ..."

Cause, from cli/bin/commands/skills.mjs:80-84:

function opencodeGlobalConfigDir(home) {
  if (process.env.OPENCODE_CONFIG_DIR) return process.env.OPENCODE_CONFIG_DIR;
  if (process.env.XDG_CONFIG_HOME) return join(process.env.XDG_CONFIG_HOME, 'opencode');
  return join(home, '.config', 'opencode');
}

The harness detector reads the actual environment variables on your machine, so OpenCode is detected and leaks into the assertion. This suite is not hermetic. Overriding HOME does not help (tested — still 8 failures), because the path comes from environment variables, not home.

The correct way to run:

env -u OPENCODE_CONFIG_DIR bun run test:core
# 874 pass · 0 fail · ~72s

If your machine has XDG_CONFIG_HOME or HERMES_HOMEset, unset those as well when running tests.

Test suites

Run through node scripts/run-tests.mjs <suite...>; package.json , wrapped as npm scripts.

Suite Command File count Contents
core bun run test:core 45 Build, provider transform, CLI helper, context, storage
detector bun run test:detector 11 Detector via text, fixtures, and Puppeteer
live bun run test:live 44 Live-mode unit and local-server tests
framework bun run test:framework 1 Fixture framework: inject, CSP, generated-file, wrap
plugin-e2e bun run test:plugin-e2e 1 Install the ./plugin subtree into an actual Claude Code sandbox
cli-e2e bun run test:cli-e2e 1 Deterministic install/update with a local universal bundle

Alias:

default / all-local  = core, detector, live, framework, plugin-e2e
all                  = default + cli-remote-e2e, live-e2e, live-e2e-accept-cleanup,
                       new-work-e2e, skill-behavior, live-svelte-adapter-deepseek
node scripts/run-tests.mjs --list     # xem từng suite gồm file nào
node scripts/run-tests.mjs --help
bun run test                          # = suite default

Opt-in suites (not run by default; cost money or time):

Suite Requirements
live-e2e npx playwright install chromium, ~2 minutes
live-e2e-accept-cleanup Provider API key
new-work-e2e Playwright
skill-behavior API keys for 3 providers in .env at the root (gitignored); ~5 minutes, costing a few cents. Current baseline: 21–22/24
cli-remote-e2e Network access to impeccable.style
live-svelte-adapter-deepseek DeepSeek key

Without a key, the suite skips cleanly, rather than failing.

Suite skill-behavior runs the 3 cheapest models from 3 vendors, inlines skill/SKILL.src.md as the system prompt, then asserts against tool-call traces rather than free-form text. Run it whenever you change the Setup section of skill/SKILL.src.md, skill/scripts/context.mjs, or references affecting Setup.

What CI checks

Job Contents
changes node scripts/ci-test-plan.mjs decides which parts need to run
test-matrix Node 22.18.0 + 24: bun install → core → install Chrome → detector → live → framework → build:browser → build → build:extension → lint the Firefox extension with web-ext@10 → generated-output gate → upload dist/
test Aggregate gate, checking only the results of test-matrix
cli-remote-e2e, live-e2e-smoke, live-e2e-full, live-e2e-accept-cleanup, live-svelte-adapter-deepseek, skill-behavior Opt-in paths, gated by changes and secrets

Architecture: where to edit

To change Edit this file
Skill content and chat commands skill/SKILL.src.md (the sole source) → bun run build
Command metadata (description, argument hint) plugin/skills/impeccable/scripts/command-metadata.json (generated — edit the source, then build)
Detector rules cli/engine/registry/antipatterns.mjs, cli/engine/rules/checks.mjs
Static HTML/CSS engine cli/engine/engines/static-html/
Regex engine cli/engine/engines/regex/detect-text.mjs
Browser engine cli/engine/engines/browser/detect-url.mjs
CLI argument parsing and exit codes cli/engine/cli/main.mjs
Install/update/link cli/bin/commands/skills.mjs
Add a new provider See docs/DEVELOP.md , section "Adding a New Provider"

Full contributor documentation: docs/DEVELOP.md, docs/STYLE.md, docs/HARNESSES.md.

Release

node scripts/release.mjs skill        # bun run release:skill
node scripts/release.mjs cli          # bun run release:cli
node scripts/release.mjs extension    # bun run release:ext

Three separate version lines: CLI (npm, currently 3.6.1), skill bundle (currently 4.1.3), and extension (currently 1.3.3).

Verified note: npm version 3.6.1 lags behind git main with the same version number — SUBCOMMAND_HELP (per-subcommand help) exists in main but not in the published tarball. When debugging user reports, ask whether they use npx (the npm version) or run from a checkout; do not assume they are identical.

Other checks

bun run audit                       # bun audit --audit-level=moderate
bun run smoke:hooks                 # smoke provider hook
bun run bench:detector              # benchmark detector
bun run bench:detector:browser