@xenos1996/usat 1.0.0

package/rules/stacks/web-frontend.yaml

@@ -0,0 +1,159 @@
+id: stacks/web-frontend
+title: Web Frontend
+section: S15
+section_title: Platform-Specific
+description: 'Activated for browser-facing applications. Covers Core Web Vitals, a11y, and bundle discipline.'
+version: '1.0'
+skip_when:
+  all:
+    - { fact: 'platform:web', op: 'absent' }
+    - { fact: 'fw:react', op: 'absent' }
+    - { fact: 'fw:vue', op: 'absent' }
+    - { fact: 'fw:svelte', op: 'absent' }
+    - { fact: 'fw:angular', op: 'absent' }
+    - { fact: 'fw:next', op: 'absent' }
+    - { fact: 'fw:nuxt', op: 'absent' }
+    - { fact: 'fw:sveltekit', op: 'absent' }
+    - { fact: 'fw:astro', op: 'absent' }
+
+rules:
+  - id: WEB-001
+    title: Core Web Vitals are measured
+    section: S15
+    section_title: Platform-Specific
+    severity: MEDIUM
+    class: performance
+    check:
+      kind: grep_present
+      pattern: '(web-vitals|LCP|CLS|INP|lighthouse|next/web-vitals|useReportWebVitals|reportWebVitals)'
+      include:
+        ['**/*.{ts,tsx,js,jsx,html}', 'package.json', '.github/workflows/*.yml', 'lighthouse*']
+      exclude: ['**/node_modules/**']
+      flags: i
+    why: 'You cannot improve what you do not measure, and LCP/INP/CLS are what search and users actually judge.'
+    remediation: 'Report web-vitals to your analytics; add Lighthouse CI to catch regressions per PR.'
+    references: ['Web-Vitals']
+
+  - id: WEB-002
+    title: Code splitting / lazy loading is used
+    section: S15
+    section_title: Platform-Specific
+    severity: MEDIUM
+    class: performance
+    check:
+      kind: grep_present
+      pattern: '(React\.lazy|import\(\s*[''"]|dynamic\s*\(\s*\(\s*\)|defineAsyncComponent|loadable|next/dynamic|Suspense)'
+      include: ['**/*.{ts,tsx,js,jsx,vue,svelte}']
+      exclude: ['**/node_modules/**', '**/*.test.*']
+    why: 'A single 2 MB bundle means every user pays for the heaviest route on first load.'
+    remediation: 'Route-level code splitting first, then lazy-load anything behind a tab, modal, or fold.'
+    references: ['Web-Vitals:LCP']
+
+  - id: WEB-003
+    title: Images are optimised
+    section: S15
+    section_title: Platform-Specific
+    severity: MEDIUM
+    class: performance
+    check:
+      kind: grep_present
+      pattern: '(loading\s*=\s*[''"]lazy|next/image|next/font|<Image|webp|avif|decoding\s*=\s*[''"]async)'
+      include: ['**/*.{ts,tsx,js,jsx,vue,svelte,html,astro}']
+      exclude: ['**/node_modules/**']
+      flags: i
+    why: 'Images are usually 60%+ of page weight. AVIF/WebP plus lazy loading is the single biggest win available.'
+    remediation: 'Serve WebP/AVIF at the rendered size; lazy-load below the fold; set width/height to avoid CLS.'
+    references: ['Web-Vitals:LCP', 'Web-Vitals:CLS']
+
+  - id: WEB-004
+    title: Accessibility basics are in place
+    section: S15
+    section_title: Platform-Specific
+    severity: MEDIUM
+    class: compliance
+    check: { kind: manual }
+    evidence: 'Lighthouse/axe accessibility score, or evidence of: semantic landmarks, labelled form inputs, visible focus, and alt text on meaningful images.'
+    why: 'Roughly 1 in 4 adults has a disability. Accessibility bugs are also, almost always, plain bugs.'
+    remediation: 'Add eslint-plugin-jsx-a11y; run axe in CI; test keyboard-only navigation end to end.'
+    references: ['WCAG-2.2-AA', 'EN-301-549', 'ADA']
+
+  - id: WEB-005
+    title: Bundle size is monitored
+    section: S15
+    section_title: Platform-Specific
+    severity: LOW
+    class: performance
+    check:
+      kind: grep_present
+      pattern: '(size-limit|bundlesize|rollup-plugin-visualizer|webpack-bundle-analyzer|bundlephobia|build\.analyze|"size-limit")'
+      include:
+        [
+          'package.json',
+          '.github/workflows/*.yml',
+          'vite.config.*',
+          'next.config.*',
+          'webpack.config.*',
+        ]
+      exclude: ['**/node_modules/**']
+      flags: i
+    why: 'Bundle size grows by 5% a sprint and nobody notices until it is 3 MB.'
+    remediation: 'Add size-limit with a per-entry budget; fail CI when the budget is exceeded.'
+    references: ['Web-Vitals']
+
+  - id: WEB-006
+    title: Error boundaries exist around risky UI
+    section: S15
+    section_title: Platform-Specific
+    severity: MEDIUM
+    class: correctness
+    applies_when:
+      any:
+        - { fact: 'fw:react' }
+        - { fact: 'fw:next' }
+    check:
+      kind: grep_present
+      pattern: '(ErrorBoundary|componentDidCatch|error\.tsx|error-boundary|useErrorBoundary)'
+      include: ['**/*.{ts,tsx,js,jsx}']
+      exclude: ['**/node_modules/**', '**/*.test.*']
+    why: 'One throw inside a render and the user gets a blank white page.'
+    remediation: 'Wrap route segments in an ErrorBoundary with a retry and a report-to-Sentry path.'
+    references: ['React-Error-Boundaries']
+
+  - id: WEB-007
+    title: No secrets in client-side bundles
+    section: S15
+    section_title: Platform-Specific
+    severity: CRITICAL
+    class: security
+    check:
+      kind: grep_wrong
+      pattern: '(NEXT_PUBLIC_.*(SECRET|KEY|TOKEN|PASSWORD)|VITE_.*(SECRET|PRIVATE|PASSWORD)|process\.env\.[A-Z_]*(SECRET|PRIVATE_KEY|PASSWORD)[A-Z_]*)'
+      include: ['**/*.{ts,tsx,js,jsx,vue,svelte}']
+      exclude: ['**/node_modules/**', '**/*.test.*', '**/server/**', '**/api/**']
+    why: 'Anything bundled for the browser is public. NEXT_PUBLIC_/VITE_ variables are shipped verbatim.'
+    remediation: 'Move the call server-side (API route, server action, BFF) and keep the secret out of the bundle.'
+    references: ['CWE-798', 'ASVS-14.3.2']
+
+  - id: WEB-008
+    title: Forms validate and expose errors accessibly
+    section: S15
+    section_title: Platform-Specific
+    severity: MEDIUM
+    class: compliance
+    check: { kind: manual }
+    evidence: 'A form with: a validation schema, error text linked via aria-describedby, and focus moved to the first error.'
+    why: 'An error message only sighted users can see (or only sighted users can find) is not an error message.'
+    remediation: 'Use a schema validator, render errors next to the field, and set aria-invalid / aria-describedby.'
+    references: ['WCAG-3.3.1', 'WCAG-3.3.3']
+
+  - id: WEB-009
+    title: An offline/PWA story exists
+    section: S15
+    section_title: Platform-Specific
+    severity: FUTURE
+    class: performance
+    check: { kind: manual }
+    evidence: 'Service worker, offline fallback page, or an explicit decision that offline support is not required.'
+    why: 'Mobile networks fail. Deciding not to support offline is fine; discovering it during an outage is not.'
+    remediation: 'At minimum, add a custom offline page. Full PWA only if the use case justifies it.'
+    references: ['Web-Vitals']

package/templates/AGENTS.audit.md

@@ -0,0 +1,135 @@
+# AGENTS.md — auditing this repository with USAT
+
+> Paste this into any repository you want an agent to audit with USAT.
+> Generated by `usat init`, or copy from
+> [`templates/AGENTS.audit.md`](https://github.com/Er-Sajan-PLG/software-auditing-template/blob/master/templates/AGENTS.audit.md).
+
+---
+
+## What this repository is
+
+<!-- Fill this in. One paragraph. An agent that knows what the project is
+     audits it far better than one that has to guess. -->
+
+TODO: describe the project in two sentences.
+
+## Commands
+
+```bash
+# TODO: replace with this project's real commands
+npm install
+npm run lint
+npm test
+npm run build
+```
+
+## Layout
+
+<!-- Where things live. Delete what does not apply. -->
+
+```
+src/        application code
+tests/      test suite
+docs/       documentation
+scripts/    one-off utilities
+```
+
+## Conventions
+
+- TODO: naming, module boundaries, error-handling style, what belongs where.
+
+## Do not
+
+<!-- Explicit denylists beat implicit trust. Agents follow these literally. -->
+
+- Do not force-push or rewrite published history.
+- Do not read, print, or commit `.env*` files, credentials, or tokens.
+- Do not run destructive commands (`rm -rf`, `git clean -fdx`, `DROP TABLE`) without
+  explicit approval.
+- Do not disable tests, linters, or type checks to make something pass.
+- Do not commit secrets, even in tests or fixtures.
+
+---
+
+# Auditing with USAT
+
+USAT is a two-part framework. **The tool settles what is mechanically checkable; you
+settle the rest.** Do not re-do the tool's work.
+
+## Step 1 — Detect
+
+```bash
+usat detect .
+```
+
+Confirm the facts against what you see. If detection is wrong, say so; the operator
+can assert facts with `--fact has:database` or in `.usat.yaml`.
+
+## Step 2 — Deterministic pass
+
+```bash
+usat audit . --out AUDIT.md --depth standard
+```
+
+This produces findings with locations and a score. **Treat these as settled.** Do not
+re-grep for a rule the tool already resolved to ✅ or 🚫.
+
+## Step 3 — Work the Judgement Queue
+
+The report's _Judgement Queue_ lists every check that cannot be settled by reading a
+file. Each row states what to look for and what evidence to record.
+
+For each item:
+
+1. Find the relevant code.
+2. Decide: `PASS` · `WRONG` · `MISSING` · `UNKNOWN`.
+3. Record `file:line` **and** one sentence of reasoning.
+4. If you cannot determine it, answer `UNKNOWN` and say what you would need.
+
+## Step 4 — Report
+
+Follow the Section 14 template in `USAT.md`:
+
+1. CRITICAL and security-HIGH findings first — with location and fix
+2. Section-by-section findings
+3. Judgement queue with your recorded evidence
+4. Roadmap: sprint 0 / sprint 1 / sprint 2 / backlog
+
+## The ten rules
+
+| #   | Rule                                                                |
+| --- | ------------------------------------------------------------------- |
+| 1   | Skip non-applicable sections silently. Do not write "N/A" 40 times. |
+| 2   | Partially applicable ⇒ audit the applicable parts only.             |
+| 3   | CRITICAL findings always go first, above every summary.             |
+| 4   | **Never mark ✅ without evidence.** `file:line` or command output.  |
+| 5   | Every finding: location + severity + why + fix.                     |
+| 6   | Score sections 0–10 from the share of applicable checks that pass.  |
+| 7   | Never assume. A file you did not find is 🚫 MISSING.                |
+| 8   | Audit what is absent as well as what is present.                    |
+| 9   | ⚠️ WRONG is worse than 🚫 MISSING. Surface it.                      |
+| 10  | Priority: Security > Correctness > Maintainability > Style.         |
+
+## Status vocabulary
+
+|     | Status       | Meaning                                  |
+| --- | ------------ | ---------------------------------------- |
+| ✅  | GOOD         | Verified present and correct             |
+| 🧪  | EXPERIMENTAL | Present, unvalidated                     |
+| 💀  | DEPRECATED   | Present, EOL                             |
+| ⚠️  | WRONG        | Present but implemented incorrectly      |
+| 🚫  | MISSING      | Required and absent                      |
+| ❓  | NEEDS REVIEW | Cannot be determined from the code alone |
+
+Severity: 🔴 CRITICAL · 🟠 HIGH · 🟡 MEDIUM · 🟢 LOW · 🔵 FUTURE
+
+## Two things agents get wrong
+
+**Guessing instead of saying UNKNOWN.** An audit that invents a passing result is worse
+than one that admits uncertainty. `UNKNOWN` lowers the report's _confidence_, which is
+the honest signal. Guessing corrupts the _score_, which is not.
+
+**Re-escalating dampened findings.** If a finding says
+_"Downgraded HIGH → MEDIUM by the MVP profile"_, that is the framework doing its job —
+the project is an MVP and the calendar is a real constraint. Leave it alone. The one
+exception is 🔴 CRITICAL, which is **never** dampened at any stage.

package/templates/AUDIT_REPORT.md

@@ -0,0 +1,155 @@
+# Audit report template
+
+> USAT's CLI emits this structure automatically (`usat audit .`).
+> Use this file when you are writing a report by hand — or when an agent is
+> producing one without the tool. Matching the structure is what makes reports
+> diffable and comparable across time and teams.
+
+---
+
+```
+══════════════════════════════════════════════════════════
+              UNIVERSAL SOFTWARE AUDIT REPORT
+══════════════════════════════════════════════════════════
+Project      : [name]
+Repository   : [url]
+Commit       : [sha] ([ref])
+Audited by   : USAT [version] + [agent / human]
+Date         : [ISO-8601]
+Detected type: [auto-detected]
+Platform     : [auto-detected]
+Stack        : [auto-detected]
+Maturity     : [Prototype / MVP / Beta / Production / Legacy]
+Depth        : [quick | standard | deep]
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+                    EXECUTIVE SUMMARY
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Overall Health Score : [X/100]
+Expected band for [maturity]: [lo]–[hi]  → [verdict]
+
+Dimension                            Score      Confidence
+S1  Repository & Structure            X/10      N%
+S2  Security                          X/10      N%
+S3  Supply Chain & Provenance         X/10      N%
+S4  Architecture & Design             X/10      N%
+S5  Code Quality                      X/10      N%
+S6  Data & Database                   X/10      N%
+S7  Testing & Quality Assurance       X/10      N%
+S8  CI/CD, Infrastructure & Obs.      X/10      N%
+S9  Release & Change Management       X/10      N%
+S10 Dependencies & Third-Party        X/10      N%
+S11 Performance & Resilience          X/10      N%
+S12 Documentation & Knowledge         X/10      N%
+S13 Accessibility, i18n & Compliance  X/10      N%
+S14 AI / LLM-Era Risks                X/10      N%
+S15 Platform-Specific                 X/10      N%
+S16 Future Readiness                  X/10      N%
+
+Automation coverage: N%   (the rest is in the judgement queue)
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+                    FINDINGS SUMMARY
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+✅ GOOD       : N     🔴 CRITICAL : N
+⚠️ WRONG      : N     🟠 HIGH     : N
+🚫 MISSING    : N     🟡 MEDIUM   : N
+💀 DEPRECATED : N     🟢 LOW      : N
+🧪 EXPERIMENTAL: N    🔵 FUTURE   : N
+❓ TO REVIEW  : N
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+                 IMMEDIATE ACTION REQUIRED
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+1. 🔴 [Finding] → [file:line] → [why] → [fix]
+2. 🟠 [Finding] → [file:line] → [why] → [fix]
+   (No CRITICAL/HIGH? Say so, plainly.)
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+                SECTION-BY-SECTION FINDINGS
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+[S1] Repository & Structure   → X/10
+  🔴 [finding] → [location] → [fix]
+  🚫 [finding] → [location] → [fix]
+  ✅ [N checks passing]
+
+[S2] Security                 → X/10
+  ...
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+                     JUDGEMENT QUEUE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+| Rule | Section | Severity | What to look for | Evidence to record |
+|------|---------|----------|------------------|--------------------|
+| SEC-015 | S2 | 🟠 HIGH | Authorization per resource | file:line of the ownership check |
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+                        ACCEPTED RISK
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+| Rule | Severity | Reason | Until |
+|------|----------|--------|-------|
+| PERF-005 | 🟡 MEDIUM | Known N+1 in the admin panel; 40 rows max. | 2026-12-31 |
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+                    RECOMMENDED ROADMAP
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+SPRINT 0 (now)       : CRITICAL + security HIGH
+SPRINT 1 (1–2 weeks) : remaining HIGH
+SPRINT 2 (1 month)   : MEDIUM
+BACKLOG              : LOW + FUTURE
+DEFERRED (this stage): what the maturity profile says to ignore
+
+WHAT MATTERS AT [STAGE]:
+  - [focus item from the maturity profile]
+  - [focus item]
+
+══════════════════════════════════════════════════════════
+```
+
+---
+
+## Rules for filling this in
+
+1. **Every finding carries location + severity + why + fix.** A finding without a
+   location is an opinion.
+2. **CRITICAL first, always.** Above the summary, above the score.
+3. **No ✅ without evidence.** `file:line`, a command output, or a doc link.
+4. **Skip non-applicable sections without comment.** Do not write "N/A: not a web app".
+5. **Surface ⚠️ WRONG above 🚫 MISSING** within a severity band. Wrong is worse than
+   absent because it looks finished.
+6. **Record UNKNOWNs in the judgement queue**, not as silent passes. They are what
+   confidence measures.
+7. **The roadmap is the deliverable.** A score nobody acts on is a number; a sprint
+   list is a plan.
+
+## Rendering notes
+
+- Use the emoji tags consistently — they are what makes a long report skimmable.
+- Keep the section order fixed (S1 → S16) so two reports can be compared line by line.
+- If you are an agent writing this by hand, end the file with the machine-readable
+  trailer so `usat diff` works on it:
+
+````markdown
+<!-- USAT:TRAILER:BEGIN -->
+
+```yaml
+schema: usat-report-v1
+generated_at: 2026-09-08T00:00:00.000Z
+usat_version: 1.0.0
+overall: 71.4
+sections:
+  S1: { score: 8.4, open: 2, review: 2 }
+  S2: { score: 6.2, open: 3, review: 1 }
+severity_totals:
+  CRITICAL: 0
+  HIGH: 3
+  MEDIUM: 4
+  LOW: 6
+  FUTURE: 2
+rules:
+  SEC-001: { status: PASS, severity: CRITICAL, section: S2 }
+  SEC-015: { status: UNKNOWN, severity: HIGH, section: S2 }
+```
+
+<!-- USAT:TRAILER:END -->
+````