@xenos1996/usat 1.0.0

package/docs/configuration.md

@@ -0,0 +1,105 @@
+# Configuration — `.usat.yaml`
+
+Generate one with `usat init`. Every field is optional; a missing file is fine.
+
+```yaml
+version: 1
+
+# ── Lifecycle stage ────────────────────────────────────────────────────────
+# Override auto-detection: prototype | mvp | beta | production | legacy
+maturity: production
+
+# ── Rule packs ─────────────────────────────────────────────────────────────
+include: [stacks/solidity] # force on, regardless of detection
+exclude: [stacks/mobile] # force off
+
+# ── Per-rule overrides ─────────────────────────────────────────────────────
+rules:
+  DOC-003:
+    severity: LOW
+    reason: 'Docs live in Notion, not the repo (decision: ADR-014)'
+  SEC-042:
+    disabled: true
+    reason: 'No user-facing auth in this worker'
+  CQ-010:
+    weight: 4
+
+# ── Accepted risk ──────────────────────────────────────────────────────────
+suppressions:
+  - rule: PERF-005
+    reason: 'Known N+1 in the admin panel; 40 rows max.'
+    until: '2026-12-31'
+
+# ── Indexing ───────────────────────────────────────────────────────────────
+ignore: # extra globs, on top of .gitignore + USAT defaults
+  - 'generated/**'
+  - 'vendor/**'
+
+# ── Facts ──────────────────────────────────────────────────────────────────
+facts: # assert what detection could not infer
+  - 'has:database'
+  - 'platform:server'
+```
+
+## Field reference
+
+| Field                 | Type                    | Effect                                                                         |
+| --------------------- | ----------------------- | ------------------------------------------------------------------------------ |
+| `version`             | `1`                     | Schema version                                                                 |
+| `maturity`            | stage                   | Overrides auto-detection; changes dampening and the expected band              |
+| `include`             | pack ids                | Force packs on even when `skip_when` says no                                   |
+| `exclude`             | pack ids                | Force packs off                                                                |
+| `rules.<id>.severity` | severity                | Re-grade one rule (must be on the ladder, else ignored with a warning)         |
+| `rules.<id>.weight`   | number                  | Change how much it moves the score (finite, ≥ 0, else ignored with a warning)  |
+| `rules.<id>.disabled` | bool                    | Skip entirely (still listed as ➖ SKIPPED)                                     |
+| `rules.<id>.reason`   | string                  | **Required in practice** — an override with no reason is an unaudited decision |
+| `suppressions[]`      | `{rule, reason, until}` | Excluded from the score, listed under Accepted Risk                            |
+| `ignore`              | globs                   | Extra paths to keep out of the index                                           |
+| `facts`               | fact strings            | Assert detection facts manually (`ns:value`)                                   |
+| `sections`            | section ids             | Restrict the report to these sections                                          |
+
+## What is indexed
+
+The file index skips, in order:
+
+1. `.git/`
+2. `DEFAULT_IGNORES` — `node_modules/`, `dist/`, `build/`, `.next/`, `venv/`, `target/`, media, archives, binaries
+3. Your `.gitignore`
+4. `ignore:` from `.usat.yaml`
+
+Lockfiles **are** indexed (a rule asking "is a lockfile committed?" has to see them)
+but are never grepped — they are huge and full of false positives. Files over 2 MB
+and anything with a NUL byte in the first 8 KB are skipped as binary.
+
+Build-output checks therefore use `tracked_absent`, which asks git what is tracked
+rather than what is on disk:
+
+```yaml
+- id: REPO-007
+  check:
+    kind: tracked_absent
+    patterns: ['dist/**', 'build/**', 'node_modules/**']
+```
+
+## Rules of thumb
+
+**Prefer `facts:` over `ignore:`.** If detection is wrong, say what is true:
+
+```yaml
+facts: ['has:database', 'orm:prisma']
+```
+
+**Prefer a suppression over disabling a rule.** A suppression stays visible in the
+report under Accepted Risk; a disabled rule disappears and takes its knowledge with it.
+
+**Waivers expire — and expiry fails closed.** An `until` date in the past, or
+one that cannot be parsed as a date, excludes the suppression with a warning
+and the finding reports normally. Use unambiguous ISO dates (`2026-12-31`).
+An audit must never silently honour dead risk acceptances (see ADR-0007).
+
+**`include` forces packs on wholesale.** A force-loaded pack applies all its
+rules regardless of depth and `applies_when` — that is the documented
+contract, and the operator is responsible for what they force on.
+
+**Keep `.usat.yaml` in the repo.** It is the audit trail for every exception you
+have taken. A reviewer should be able to read it and understand what the team decided.

package/docs/detectors.md

@@ -0,0 +1,186 @@
+# Detectors — the fact catalogue
+
+Detection is entirely declarative: [`rules/detectors.yaml`](../rules/detectors.yaml)
+maps file patterns to **facts**, and rule packs select themselves on those facts.
+Add a signal and every pack that cares starts applying — no TypeScript required.
+
+```bash
+usat detect .            # what USAT thinks your project is
+```
+
+## How a detector works
+
+```yaml
+- fact: 'fw:next'
+  category: framework
+  title: 'Next.js'
+  match:
+    any_of:
+      - file_exists: ['next.config.js', 'next.config.mjs', 'next.config.ts']
+      - manifest: { file: 'package.json', key: 'dependencies.next' }
+```
+
+| Primitive                          | Meaning                                          |
+| ---------------------------------- | ------------------------------------------------ |
+| `any_file: [glob]`                 | at least one file matches                        |
+| `file_exists: [glob]`              | path present                                     |
+| `dir_exists: [path]`               | directory present                                |
+| `content: {include, pattern}`      | regex found in matching files                    |
+| `manifest: {file, key, contains?}` | dotted key resolves (JSON, or TOML/YAML section) |
+| `metric: {name, min\|max}`         | numeric fact comparison                          |
+| `any_of` / `all_of`                | boolean composition                              |
+| `implies: [fact]`                  | derived — all listed facts must hold             |
+
+Several detectors may emit the same fact; the fact is set if **any** of them fires
+(OR semantics). `implies` chains resolve to a fixed point (bounded by
+detector count + 1 passes, early exit), so chains of any length resolve
+regardless of declaration order.
+
+Request-serving frameworks imply their platform: `fw:express` …
+`fw:sveltekit` (24 frameworks) each derive `platform:server`, so a bare
+framework app with no Dockerfile still gets the platform-gated rules
+(SEC-003 et al.). Task queues, static builders, and desktop/mobile packs
+deliberately imply nothing — see the comment block in
+`rules/detectors.yaml`.
+
+Manifest queries are section-scoped where sections exist: a dotted key
+(`tool.poetry.dependencies`) matches a full header segment
+(case-insensitive; `[dev-dependencies]` is not `[dependencies]`), the leaf
+matches on word boundaries, and `contains` is checked against the matched
+block — never the whole file. Flat files with no headers keep whole-text
+search. See ADR-0010.
+
+## Prose, tests, and examples are excluded from `content` scans
+
+A repo whose README mentions Postgres does not have a Postgres dependency. Every
+`content:` scan automatically skips:
+
+```
+**/*.md  **/*.mdx  **/*.rst  README*  docs/**  doc/**  examples/**
+example/**  templates/**  fixtures/**  __mocks__/**  test/**  tests/**
+__tests__/**  spec/**  *.test.*  *.spec.*  *.stories.*  test_*
+*_test.*  LICENSE*  CHANGELOG*
+```
+
+Deliberately **not** excluded: `**/*.txt` — `requirements.txt` is a
+manifest, not prose. This list mirrors `CONTENT_EXCLUDES` in
+`src/detect/index.ts`; if they drift, the code wins and this doc is a bug —
+file it.
+
+Everything else in the tree is fair game. If a project's own config comments are
+still producing noise, add the file to `ignore:` in `.usat.yaml` — that is what
+[`../.usat.yaml`](../.usat.yaml) does with `rules/`.
+
+## Fact namespaces
+
+### `lang:*` — language
+
+`typescript` `javascript` `python` `go` `rust` `java` `kotlin` `swift` `ruby` `php`
+`csharp` `cpp` `scala` `dart` `elixir` `lua` `zig` `solidity` `shell` `haskell`
+
+### `pm:*` — package manager
+
+`node` `npm` `pnpm` `yarn` `bun` `pip` `poetry` `uv` `pipenv` `cargo` `go-mod`
+`maven` `gradle` `composer` `nuget` `swiftpm` `pub` `mix` `foundry` `hardhat`
+
+### `fw:*` — framework
+
+Web: `react` `vue` `angular` `svelte` `solid` `next` `nuxt` `remix` `sveltekit`
+`astro` `vite` `tailwind`
+Node backend: `express` `fastify` `nest` `hono` `koa`
+Python: `django` `flask` `fastapi` `celery` `airflow` `streamlit`
+Go: `gin` `echo` `fiber` `chi` · Rust: `axum` `actix` `rocket`
+JVM: `spring` `quarkus` · Ruby: `rails` · PHP: `laravel` `symfony` · .NET: `dotnet`
+Mobile/desktop: `react-native` `expo` `flutter` `electron` `tauri`
+
+### `project:*` — archetype
+
+`library` `cli` `monorepo` `api` `ml` `blockchain` `iac` `data-pipeline` `game` `docs`
+
+### `platform:*` — runtime
+
+`web` `server` `desktop` `mobile` `ios` `android` `evm` `embedded`
+
+### `db:*` — datastore
+
+`postgres` `mysql` `sqlite` `mongodb` `redis` `clickhouse` `elasticsearch` `vector`
+`dynamodb` · plus `has:database`
+
+### `orm:*`
+
+`prisma` `drizzle` `typeorm` `sequelize` `mongoose` `sqlalchemy` `gorm` `sqlx`
+`diesel` `hibernate` `activerecord`
+
+### `auth:*`
+
+`jwt` `oauth` `session` `apikey` `passport` `nextauth` `supabase` `firebase` `auth0`
+
+### `api:*` · `obs:*`
+
+`api:graphql` `api:grpc` `api:trpc` `api:websocket`
+`obs:sentry` `obs:otel` `obs:prometheus` `obs:datadog` `obs:grafana` · `has:monitoring`
+
+### `test:*`
+
+`vitest` `jest` `mocha` `pytest` `gotest` `cargotest` `junit` `rspec` `phpunit`
+`playwright` `cypress` · plus `has:tests` `has:e2e` `has:perf-tests`
+
+### `ci:*` · `infra:*`
+
+`ci:github-actions` `ci:gitlab` `ci:jenkins` `ci:circleci` `ci:buildkite` `ci:azure`
+· `has:ci`
+
+### `ai:*`
+
+`ai:llm-sdk` `ai:prompts` `ai:agents` `ai:mcp` `ai:rag` `ai:evals`
+
+### `doc:*`
+
+`readme` `license` `contributing` `code-of-conduct` `security-policy` `changelog`
+`architecture` `adr` `api-reference` `runbook` `onboarding` `env-example`
+`gitignore` `codeowners` `pr-template` `issue-templates` `agents`
+
+### `has:*` — cross-cutting capabilities
+
+`has:lint` `has:format` `has:typecheck` `has:precommit` `has:dependabot`
+`has:renovate` `has:changesets` `has:release-automation` `has:editorconfig`
+`has:containers` `has:kubernetes` `has:terraform` `has:serverless` `has:sbom`
+`has:secrets-scan` `has:sast` `has:dep-scan` `has:codecov` `has:monitoring`
+`has:crypto` `has:file-upload` `has:payments` `has:pii` `has:csp` `has:rate-limit`
+`has:database` `has:tests` `has:e2e` `has:perf-tests` `has:ci`
+
+### `practice:*`
+
+`conventional-commits` `codeowners` `signed-commits` `branch-protection-doc`
+`pinned-versions` `i18n` `feature-flags` `queue` `cache`
+`monorepo-tool-turborepo` `monorepo-tool-nx`
+
+### `maturity:*` and metrics
+
+`maturity:prototype` `maturity:mvp` `maturity:beta` `maturity:production` `maturity:legacy`
+
+Metrics, referenced as `metric:<name>` in predicates:
+
+| Metric                | Source                      |
+| --------------------- | --------------------------- |
+| `commits`             | `git rev-list --count HEAD` |
+| `contributors`        | `git shortlog -sn --all`    |
+| `tags`                | `git tag --list`            |
+| `branches`            | `git branch --list`         |
+| `files`               | indexed file count          |
+| `daysSinceLastCommit` | `git log -1 --format=%ct`   |
+
+## Adding a detector
+
+1. Add an entry to `rules/detectors.yaml` with a clear `fact:` name.
+2. Use `manifest:` where possible — it is far more reliable than a content regex
+   (`dependencies.hono` beats grepping for `hono` in source).
+3. Verify against a project that uses the technology and one that does not:
+
+```bash
+usat detect ~/code/uses-hono
+usat detect ~/code/does-not
+```
+
+4. If detection is right but a project still eludes it, users can assert facts in
+   `.usat.yaml` — but if you find yourself doing that often, the detector is wrong.

package/docs/getting-started.md

@@ -0,0 +1,99 @@
+# Getting started
+
+## Install
+
+```bash
+npx @xenos1996/usat audit .          # zero-install
+npm i -g @xenos1996/usat             # or globally
+npm i -D @xenos1996/usat             # or per project, so CI and laptops agree
+```
+
+Requires Node 20+. No network access is needed at audit time, and USAT never
+uploads anything — it reads files and writes one Markdown file.
+
+## Your first audit
+
+```bash
+cd ~/code/my-project
+usat detect .     # 1. check what it thinks you are
+usat audit .      # 2. audit it
+open AUDIT.md
+```
+
+Start with `detect`. If the detected facts are wrong, the report will be wrong —
+and fixing it takes one line of config:
+
+```yaml
+# .usat.yaml
+facts: ['has:database'] # assert anything detection missed
+```
+
+## Reading the report
+
+**1 · Look at the band, not the number.**
+
+```
+Overall Health Score: 71.4/100
+Expected band for Beta / Growing: 60–85 — within the expected band 👍
+```
+
+A 55/100 on a prototype is healthy. The same 55/100 on a production service is a
+problem. USAT tells you which you are looking at.
+
+**2 · Read Immediate Action Required.** CRITICAL and security-HIGH findings, with
+location and fix. Everything else waits.
+
+**3 · Check confidence before celebrating.**
+
+| Dimension          | Score | Confidence |
+| ------------------ | ----- | ---------- |
+| S10 · Dependencies | 10/10 | 25%        |
+
+A 10/10 at 25% confidence means one of four applicable rules could be checked
+automatically. The other three are in the judgement queue. Sections where
+_nothing_ could be verified say **"— not verified"** and are excluded from the
+total rather than quietly scoring 10.
+
+**4 · Work the judgement queue.** These are the checks grep cannot settle. Take them
+to an agent or a reviewer. Every row says what to look for and what evidence to
+record. **Do not mark anything ✅ without evidence.**
+
+**5 · Ship the roadmap.** SPRINT 0 → SPRINT 1 → SPRINT 2 → BACKLOG, generated from
+severity. `DEFERRED` lists what the maturity profile says you should deliberately
+ignore _at this stage_.
+
+## Common flags
+
+```bash
+usat audit . --depth deep                 # include deep-only rules (cycles, duplication, complexity)
+usat audit . --profile production         # grade against the full bar regardless of age
+usat audit . --fail-on high               # exit 1 on HIGH+ (for CI gates)
+usat audit . --out reports/2026-09.md     # dated reports, so you can diff them later
+usat audit . --allow-commands             # run shell checks (npm audit, depcheck, dpdm)
+usat audit . --include stacks/solidity    # force a pack on
+usat rules --section S2                   # list rules
+usat explain SEC-001                      # everything about one rule
+```
+
+`--allow-commands` is **off by default** because it shells out. Those rules appear
+as ❓ NEEDS REVIEW until you enable it — which is the point: they are real checks,
+they just need your permission to run.
+
+## Compare two audits
+
+```bash
+usat audit . --out reports/2026-06.md
+# ... three months of work ...
+usat audit . --out reports/2026-09.md
+usat diff reports/2026-06.md reports/2026-09.md
+```
+
+The diff reads the YAML trailer embedded in every report — so a Markdown report is
+still the only artefact you need to keep.
+
+## Next steps
+
+- [Concepts](concepts.md) — how severity, status, and scoring actually work
+- [Configuration](configuration.md) — `.usat.yaml` reference
+- [Rule packs](rule-packs.md) — write your own rules
+- [Agent integration](agent-integration.md) — drive USAT from Claude, Cursor, Codex

package/docs/maturity-profiles.md

@@ -0,0 +1,156 @@
+# Maturity profiles
+
+The same repository deserves a different report at age three days and age three years.
+Grading a prototype against a production bar produces a wall of noise nobody reads;
+grading production with prototype standards produces a false all-clear.
+
+USAT detects a lifecycle stage and **dampens** severity to match.
+
+## How the stage is detected
+
+A score out of 7.5, from signals that are hard to fake:
+
+| Signal                 | Points |
+| ---------------------- | ------ |
+| Tests present          | +1     |
+| CI configured          | +1     |
+| CHANGELOG maintained   | +1     |
+| Release tags published | +1     |
+| ≥50 commits            | +1     |
+| SECURITY.md published  | +1     |
+| Containerised          | +0.5   |
+| Monitoring configured  | +0.5   |
+| CONTRIBUTING guide     | +0.5   |
+
+Then:
+
+| Condition                     | Stage          |
+| ----------------------------- | -------------- |
+| No commits for ~18 months     | **legacy**     |
+| ~12 months idle **and** no CI | **legacy**     |
+| Score ≥ 7 **and** tags exist  | **production** |
+| Score ≥ 5                     | **beta**       |
+| Score ≥ 2.5                   | **mvp**        |
+| Otherwise                     | **prototype**  |
+
+A `0.x` version with no tags is never promoted to _production_ — it downgrades to
+_beta_ with the reason recorded in the report.
+
+Boundary semantics, stated exactly because auditors must not hedge: staleness
+is exclusive (`> 365` and `> 540` days — exactly-365-days-stale counts as
+fresh); production needs score ≥ 7 **and** at least one tag (7.0 with zero
+tags is beta); prerelease detection reads the **root** `package.json` only,
+so monorepos and polyglot version files (`pyproject.toml`, `Cargo.toml`,
+`go.mod`) should assert maturity explicitly via `facts:` or `maturity:` if
+the auto-detection misreads them.
+
+Every signal and the resulting score are printed in the report appendix, so the
+classification can be argued with.
+
+## Dampening
+
+Steps move down the ladder `FUTURE < LOW < MEDIUM < HIGH < CRITICAL`.
+
+| Class             | 🌱 Prototype | 🚀 MVP | 🧪 Beta | 🏭 Production | 🏚️ Legacy |
+| ----------------- | ------------ | ------ | ------- | ------------- | --------- |
+| `security`        | −1           | −0     | −0      | −0            | −0        |
+| `supply-chain`    | −1           | −1     | −0      | −0            | −0        |
+| `correctness`     | −1           | −1     | −0      | −0            | −0        |
+| `maintainability` | −2           | −1     | −1      | −0            | −1        |
+| `operations`      | −2           | −1     | −1      | −0            | −0        |
+| `performance`     | −2           | −1     | −1      | −0            | −1        |
+| `compliance`      | −2           | −1     | −1      | −0            | −0        |
+| `documentation`   | −2           | −2     | −1      | −0            | −1        |
+| `style`           | −2           | −2     | −1      | −0            | −1        |
+
+> ### 🔴 CRITICAL is never dampened, at any stage.
+>
+> A leaked credential in a weekend prototype is still a leaked credential.
+> A committed `.env` in an MVP is still a committed `.env`.
+> Everything else is negotiable with the calendar. This one is not, and it is
+> enforced in code (`src/engine/maturity.ts`), not just documented here.
+
+Every dampened finding says so in the report, so a growing prototype can see what
+will climb on its own:
+
+```
+- 🚫 **LICENSE present** `REPO-005`
+  - 🪶 Downgraded HIGH → LOW by the Prototype / Spike profile
+```
+
+## Expected score bands
+
+| Stage         | Band  | Reading                                                                      |
+| ------------- | ----- | ---------------------------------------------------------------------------- |
+| 🌱 Prototype  | 30–65 | "Above band" here means you started with good hygiene, not that you are done |
+| 🚀 MVP        | 45–75 | Real users, real data — the security basics must exist                       |
+| 🧪 Beta       | 60–85 | Close the process gaps before they compound                                  |
+| 🏭 Production | 75–95 | Full bar; nothing dampened                                                   |
+| 🏚️ Legacy     | 40–70 | Graded on risk containment, not modernisation ambition                       |
+
+The report always prints the score **and** the band and a verdict:
+
+```
+Overall Health Score: 71.4/100
+Expected band for Beta / Growing: 60–85 — within the expected band 👍
+```
+
+## Per-stage guidance
+
+Each profile in [`rules/profiles/maturity.yaml`](../rules/profiles/maturity.yaml)
+carries a `focus` list (what actually matters now) and a `defer` list (what to
+deliberately ignore). Both are rendered in the report's roadmap:
+
+### 🌱 Prototype
+
+**Focus:** secret hygiene and `.gitignore` · a README that says what this is and how
+to run it · one smoke test so the happy path is known-good.
+**Defer:** Kubernetes, multi-region, formal ADRs, 80% coverage gates.
+
+### 🚀 MVP
+
+**Focus:** input validation and output encoding on every user-facing path · automated
+backup plus a restore you have actually performed · CI running lint + tests ·
+dependency scanning before the graph grows.
+**Defer:** formal threat model, multi-region, chaos engineering, SBOM/VEX.
+
+### 🧪 Beta
+
+**Focus:** branch protection with mandatory review · structured logging with
+correlation IDs and real alerting · integration tests around critical flows ·
+documented rollback.
+**Defer:** full DR site, formal verification, mutation testing.
+
+### 🏭 Production
+
+**Focus:** close every HIGH · provenance/attestation on release artifacts (SLSA) ·
+tested DR with a real RTO/RPO · observability that answers "is it broken?" in under
+five minutes.
+
+### 🏚️ Legacy
+
+**Focus:** inventory EOL dependencies with a replacement date · confirm backups
+restore and that someone still knows how · monitoring, alerting, and a named owner per
+service · document well enough to hand over or retire.
+**Defer:** rewrites without a strangler plan; framework migrations for their own sake.
+
+## Overriding
+
+```bash
+usat audit . --profile production     # grade against the full bar
+```
+
+```yaml
+# .usat.yaml
+maturity: production
+```
+
+Use `--profile production` on a younger project when you want the
+_"what would it take to ship this?"_ view. Expect the score to drop and the CRITICAL
+list to stay exactly the same length — that is the point.
+
+## Customising
+
+Edit [`rules/profiles/maturity.yaml`](../rules/profiles/maturity.yaml) — no code
+changes needed. Add a stage, change the dampening table, adjust the expected bands, or
+rewrite the focus/defer lists to match how your organisation actually ships.