Impeccable explained: design guidance inside an AI coding workflow
Source code tour: from CLI installer to engine contract
Read the JavaScript entry point without assuming the packaged engine is ordinary source code.
What you will learn
- Locate the installer surface
- Use the contract documents
- Record what remains opaque
Before you start
- One screen and its user task
- Authority to inspect an agent skill and project hook
Produce an evidence-backed design change that another reviewer can accept or reject.
Key takeaways
- The npm CLI and binary engine are distinct layers.
- Exit 1 and exit 2 have different meanings.
- Source inspection does not verify a downloaded binary.
Locate the installer surface
The inspected package.json declares the CLI package, while cli/bin/cli.js is an entry point for invoking the distributed engine. Follow argument handling, platform selection and process exit behavior before writing automation around it.
The README says the npm package is a shim and that the engine is a self-contained binary. Code visible in this repository explains installation and integration, but does not by itself expose every detector implementation.
Use the contract documents
docs/CLI-CONTRACT.md describes command and output expectations; docs/ENGINE.md documents the runtime boundary. Read a single operation in those files beside the launcher so you know which behavior belongs to JavaScript and which belongs to the engine.
A machine-readable detector result has its own exit meanings. The README says exit 0 indicates no primary findings, 2 indicates findings and 1 means an operational scan failure. An automation that treats every nonzero status as the same fault loses information.
Record what remains opaque
Pin the source commit, package version and engine artifact used in a real trial. Compare the documented command with actual stdout, stderr and exit status; this article has not run that experiment.
If a hook behaves differently between Codex and Cursor, inspect their provider manifests rather than inferring one generic lifecycle. The monorepo contains several adapters and their trust models differ.
Decision guide
| Criterion | Option A | Option B |
|---|---|---|
| Best when | You need predictable behavior and easy auditing | You need adaptive optimization and have reliable telemetry |
| Main risk | May leave performance on the table | Can become difficult to explain or debug |
Implementation steps
- 1
Open package.json and cli/bin/cli.js at the fixed commit.
- 2
Trace one command through the CLI contract.
- 3
Record actual exit status and installed engine version in a later trial.
Copy-ready example
npx impeccable detect src/
# 0: scan completed without primary findings
# 2: scan completed with primary findings
# 1: at least one target could not be scannedFrequently asked questions
Where is each detector rule implemented?
The README describes a self-contained engine; inspect its distribution and documented interfaces rather than assuming the JS shim contains every rule.
Did this series execute the CLI?
No. The code and contracts were read at a fixed revision.
Sources
- Impeccable / package.jsonSource checked 2026-09-29
- Impeccable / cli/bin/cli.jsSource checked 2026-09-29
- Impeccable / docs/CLI-CONTRACT.mdSource checked 2026-09-29
- Impeccable / docs/ENGINE.mdSource checked 2026-09-29