Changelog

The last thing you see

The score summary has always led the report — which means on any project with real findings, it scrolls off screen long before the report finishes. By the time the post-scan menu appears, the verdict is gone.

Now the report ends the way it begins: with your grade. Local interactive scans close with the grade and score rendered as large shadowed block letters, colorized by the same green, yellow, and red bands as the score bar, sitting directly above the menu.

Honest by construction, still

The banner is a pure function of the score and grade, so determinism is untouched: the same source produces the same banner, every run. It renders only on local Unicode terminals — CI logs, piped output, and plain terminals keep the exact tight report they had in 0.1.0. Terminals too narrow for the letterforms get a single "Final grade" line instead.

One command, one answer

npx @shadscan/cli@0.1.0 audits the current project and scores its UI fundamentals from 0 to 100: command menus, theme shortcuts, route states, accessible controls, form feedback, metadata, mobile behavior, and the composition contracts of shadcn components themselves. The result is deterministic — the same source produces the same report, byte for byte — so scores are comparable across machines, teammates, and CI runs. Every finding carries repository-relative evidence and a suggested fix, and the rules that cannot be proven statically say so instead of guessing.

Built for the agent era

The audit is designed to be handed off. After every interactive scan, the agent handoff is one Enter away — a neutral, paste-ready plan that groups findings into fix, decide, and verify work items with acceptance criteria and the exact rescan command. --apply launches an installed Claude Code, Codex CLI, or Grok Build with that plan directly, and the same handoff is embedded in the tracked issues our GitHub Action maintains.

Guardrails that hold

--fail-under turns the score into a CI gate that cannot be satisfied by a partial scan. The composite GitHub Action posts the score and category table to the job summary on every push. shadscan setup --pre-commit installs a version-pinned score floor as a Git hook, and the shadscan-pre-commit agent skill holds AI agents to the same standard before every commit they make.

Honest by construction

Shadscan reads source and configuration — nothing else. It does not start your app, edit files, call an AI model, upload code, or require secrets. Rules that need a rendered browser to verify report as advisories rather than pretending certainty, and anatomy rules resolve against the components your project actually vendors, so your customizations are part of the contract rather than violations of it.

A menu you can feel

Typing 1 and pressing Enter worked, but it read as a form. The menu now renders a live cursor: arrows or j/k move it (wrapping at the ends), Enter confirms, and the row highlight follows you without the report above ever scrolling. The old number keys still act as instant shortcuts, so nothing you learned in rc.6 is wasted.

One keypress to the handoff

The agent handoff is why the menu exists, so it starts highlighted — a bare scan followed by a single Enter puts the paste-ready remediation plan on your clipboard and prints it. Pressing Esc (or q) dismisses the menu and keeps just the score, which the hint line below the menu spells out.

Careful with your terminal

Raw-mode input is easy to get wrong, so the selector treats restoration as a contract: raw mode, the cursor, and key listeners are restored on selection, escape, interrupt, and error alike — Ctrl+C hands the terminal back before forwarding the signal. Minimal terminals without raw-mode support fall back to the rc.6 numbered prompt, NO_COLOR and non-unicode environments get a plain ASCII pointer, and no new dependencies were added for any of it.

The handoff, one keypress away

The recommended shadscan workflow is to hand the audit to a coding agent — but until now the CLI printed a report and quietly exited, leaving the handoff behind a flag most first-time users never saw. Interactive scans now end with a short menu whose first option copies the paste-ready remediation plan to your clipboard and prints it, so the next step is always visible. Printing without copying, launching an installed agent, and adding a pre-commit score gate sit right below it, and Enter still means "just the score, thanks."

Clipboard that works everywhere, honestly

Copying uses the platform's own utilities — pbcopy on macOS, clip on Windows, wl-copy, xclip, or xsel on Linux — and falls back to the OSC 52 terminal escape for SSH sessions and minimal environments. When no channel is available, shadscan says so and prints the handoff instead of pretending. No new dependencies were added.

Automation is untouched

The menu exists only for interactive terminals. CI environments, piped output, --json, --prompt, and --no-interactive behave byte-for-byte as they did in rc.5.

Composition contracts, checked

shadcn components are composition contracts: items belong in groups, InputGroup provides its own input and addon parts, and an Alert is built from a leading icon, a title, and a description. A new anatomy engine encodes those contracts declaratively and checks them across your JSX — starting with three advisory rules that never move your score while they earn trust.

Two design decisions keep them honest. Anatomy is resolved against the components your project actually vendors, so a part you added to your own components/ui/alert.tsx is part of the contract, not a violation. And composition that crosses component boundaries — an item rendered by a helper, children passed through props — is treated as unknowable rather than wrong.

The audit in your CI

The repository now doubles as a composite GitHub Action. Point a workflow at TheOrcDev/shadscan, and every push gets a deterministic score with a category table in the job summary. Add fail-under to gate merges, and enable create-issue to keep a single tracked issue up to date — its body embeds the same paste-ready remediation handoff --prompt generates, so assigning the issue to a coding agent hands it a complete plan.

The ruleset, in the open

Every rule shadscan runs is now documented on the public rules page, generated from the same catalog the CLI bundles, and releases are published on the changelog page you are reading. Both are a keyboard shortcut away behind the site's command menu.

Monorepos, finally

Pointing the web scanner at a monorepo used to mean acquiring everything and auditing whatever the root looked like. Discovery is now bounded and explicit: shadscan finds the package roots that look like real apps, asks you to choose one, and audits exactly that project — nothing else is fetched or retained.

Bounded acquisition

GitHub archives stream through bounded source profiles that classify every entry as it arrives and keep only what the audit needs. Small selected manifests skip the archive entirely and fetch just their files. Limits are reported precisely: the failed counter, the configured threshold, the observed value, and the affected path.

Durable queued scans

Scans too large for the inline budget are dispatched to a durable queue with token-protected polling, and immutable results can be cached so repeat scans of the same commit answer instantly. Source never persists either way.

Ruleset 2026.07.33

The bundled ruleset grows to 56 rules, adding a high-confidence check that inline icons and spinners inside shadcn Buttons carry position-correct data-icon="inline-start" or data-icon="inline-end" attributes, while icon-only controls stay excluded.

See the score, then act on it

Local scans now end with a width-aware score bar and an interactive post-scan menu. From there, --apply --agent <provider> validates an installed Claude Code, Codex CLI, or Grok Build and launches it with a private, neutral remediation prompt — no copy-paste required. CI and redirected output stay deterministic and color-free by default.

Pre-commit gates you can trust

shadscan setup --pre-commit (also offered from the post-scan menu) installs a score gate pinned to the exact shadscan version and your current assessed score. It safely updates simple POSIX-native hooks, preserves existing commands, and hands you a manual plan for hook managers, other interpreters, and complex hooks instead of touching them.

Deeper, safer analysis

Navigation landmarks are now correlated through a bounded component render graph that understands route surfaces, repeated instances, child projection, responsive visibility, and mutually exclusive branches — without executing application code. Projects mixing App Router and Pages Router are detected and audited as hybrids, with both root shells and route-boundary families covered.

Hardened hosting

Hosted TypeScript parsing and rule evaluation moved into disposable, resource-limited workers that terminate on request abort and receive no deployment secrets. Each process is bounded to two active scans with a retryable SCAN_BUSY contract, rate limiting is atomic and epoch-based, and public GitHub archives download without the server token. Reports also became byte-stable across runtime locales.

Pages Router, covered

Discovery and rules now understand the Pages Router as thoroughly as the App Router: _app, _document, route-level loading, error, and not-found boundaries, metadata, theme, toast, and mounted-component analysis all participate in the audit, and the web scanner returns complete Pages Router reports.

Documentation that leads with the CLI

The docs were rebuilt around how shadscan is actually used: output formats, category scopes, score thresholds, project paths, agent prompts, and running it before AI-agent commits.

Stricter credit, stabler contracts

Command-menu and shortcut findings now require mounted application surfaces instead of awarding credit for orphaned components, and the exact hotkey evidence that satisfied a rule is reported. Hosted scan quota consumption became atomic under a single end-to-end deadline, empty GitHub archives are classified correctly, and migration and runtime database roles were separated for least-privilege access.

Supply-chain hardening

Published source maps no longer contain original TypeScript source, every privileged GitHub Actions dependency is pinned to an immutable commit, and the CLI bundles its argument parser so clean installs stop depending on an expired historical npm signing key — while keeping Node 18 support.

One command, one answer

npx @shadscan/cli audits the current project and prints an evidence-backed score across six weighted categories. The result is deterministic: the same source produces the same report, byte for byte, so scores are comparable across runs, machines, and CI.

Built for handoff

Beyond the human report, --json exposes the complete machine-readable audit and the agent prompt output groups related findings into fix, decide, and verify work items — including discovered project gates and a version-pinned rerun command — so an AI coding agent can start from evidence instead of guesswork.

Hosted scanning

A hosted scan API audits public GitHub repositories and sanitized snapshots with authentication, archive extraction limits, source timeouts, and rate limits. Local scanning stays read-only with no source upload, telemetry, install scripts, or AI dependencies.

Fewer false alarms

The rule engine invests heavily in not crying wolf: empty-state checks demand real query calls or mapped collection data, heading checks treat separate component returns as exclusive branches, focus checks inspect actual JSX focus targets, and label checks correlate dynamic id/htmlFor pairs — among many other refinements that keep findings trustworthy.