@xenos1996/usa 2.4.0 → 2.6.0

package/dist/live/types.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Live conversational audit sessions — shared types.
+ *
+ * Doctrine: the session is a deterministic state machine. The transcript is
+ * the artifact; it carries no timestamps so its rendering is byte-stable and
+ * test-assertable (structure asserted, never times).
+ */
+import type { ChatRequest, ChatResult } from '../agent/types.js';
+/** Conversational phases, in walking order. */
+export type SessionPhase = 'idle' | 'foundation' | 'audit' | 'triage' | 'report' | 'done';
+/** Who produced a transcript line. */
+export type TranscriptKind = 'user' | 'tool' | 'model' | 'decision';
+/** One deterministic transcript line: no timestamps by design. */
+export interface TranscriptEntry {
+    phase: SessionPhase;
+    kind: TranscriptKind;
+    text: string;
+}
+/** Reducer state: where the session is, what was said, what was learned. */
+export interface SessionState {
+    phase: SessionPhase;
+    transcript: TranscriptEntry[];
+    facts: string[];
+}
+/** LLM call behind an injectable interface. Types come from `src/agent` only. */
+export type ChatFn = (req: ChatRequest) => Promise<ChatResult>;
+/** Synchronous line reader injected by the caller (stdin in the CLI). */
+export type AskFn = (prompt: string) => string | null | Promise<string | null>;
+/** Line printer injected by the caller (console in the CLI). */
+export type PrintFn = (line: string) => void;
+//# sourceMappingURL=types.d.ts.map

package/dist/live/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/live/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEjE,+CAA+C;AAC/C,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,YAAY,GAAG,OAAO,GAAG,QAAQ,GAAG,QAAQ,GAAG,MAAM,CAAC;AAE1F,sCAAsC;AACtC,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,UAAU,CAAC;AAEpE,kEAAkE;AAClE,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,YAAY,CAAC;IACpB,IAAI,EAAE,cAAc,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,4EAA4E;AAC5E,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,YAAY,CAAC;IACpB,UAAU,EAAE,eAAe,EAAE,CAAC;IAC9B,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,iFAAiF;AACjF,MAAM,MAAM,MAAM,GAAG,CAAC,GAAG,EAAE,WAAW,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC;AAE/D,yEAAyE;AACzE,MAAM,MAAM,KAAK,GAAG,CAAC,MAAM,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;AAE/E,gEAAgE;AAChE,MAAM,MAAM,OAAO,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC"}

package/dist/live/types.js

@@ -0,0 +1,9 @@
+/**
+ * Live conversational audit sessions — shared types.
+ *
+ * Doctrine: the session is a deterministic state machine. The transcript is
+ * the artifact; it carries no timestamps so its rendering is byte-stable and
+ * test-assertable (structure asserted, never times).
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/live/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/live/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xenos1996/usa",
-  "version": "2.4.0",
+  "version": "2.6.0",
   "description": "Universal Software Auditor — an open-source, self-adapting audit framework for any project, any stack, any stage",
   "license": "MIT",
   "type": "module",

package/rules/categories.yaml

@@ -0,0 +1,124 @@
+# =============================================================================
+# USA assurance categories  (schema: usa-categories-v1)
+# -----------------------------------------------------------------------------
+# The future-ready categorization axis: ten stable categories that group the
+# sixteen report sections (S1..S16) and the rule-id prefixes into assurance
+# themes. Categories never replace sections and never change scoring — they
+# are a *derived* view (see src/engine/categories.ts), the same derivation
+# precedent ADR-0021 set for catalogues.
+#
+# Honesty discipline (normative): every description states IMPLEMENTED (real
+# rules mapped below) or PROPOSED (aspirational, no rules mapped yet). An
+# aspirational-but-empty category is a valid, labeled state — never pad
+# `sections` or `rulePrefixes` to fake coverage.
+#
+# Adding a category is not supported: the set is frozen at these ten ids and
+# the loader skips any unknown id with a warning.
+# =============================================================================
+
+schema: usa-categories-v1
+
+categories:
+  - id: foundational
+    name: Foundational
+    description: 'Status: IMPLEMENTED. Covers repository structure, project hygiene, and
+      foundation readiness — the ground an audit stands on. It matters for
+      assurance because undetectable projects (no manifest, no VCS, no stated
+      intent) cannot be audited deterministically, so every deeper category
+      depends on this one holding.'
+    sections: [S1, S3]
+    rulePrefixes: [REPO-, FND-]
+
+  - id: security
+    name: Security
+    description: 'Status: IMPLEMENTED. Covers application security controls, supply-chain
+      integrity and provenance, and dependency risk — what keeps malicious
+      input, tampered artifacts, and known-vulnerable components out. It
+      matters for assurance because a single auth or provenance failure
+      outweighs tidy docs or passing linters, which is why these rules carry
+      the heaviest scoring weights.'
+    sections: [S2, S3, S10]
+    rulePrefixes: [SEC-, SUP-, DEP-]
+
+  - id: networking
+    name: Networking
+    description: 'Status: PROPOSED — aspirational, no rules mapped yet. Will cover
+      transport security, DNS hygiene, ingress/egress policy, and service
+      connectivity. It matters for assurance because most breaches cross a
+      network boundary, but the current rule tree has no dedicated networking
+      checks, so this category is an empty placeholder until such packs land.'
+    sections: []
+    rulePrefixes: []
+
+  - id: communication
+    name: Communication
+    description: 'Status: PROPOSED — aspirational, no rules mapped yet. Will cover
+      messaging, eventing, notification, and human coordination surfaces
+      (queues, webhooks, changelogs, incident channels). It matters for
+      assurance because silent systems fail silently, but the current rule
+      tree has no communication packs, so this category stays empty by
+      design rather than borrowing unrelated rules.'
+    sections: []
+    rulePrefixes: []
+
+  - id: ux
+    name: User Experience
+    description: 'Status: PROPOSED — aspirational, no rules mapped yet. Will cover
+      interaction quality, accessibility behaviour, and user-facing clarity
+      beyond static compliance text. It matters for assurance because users
+      work around hostile interfaces in unsafe ways, but the current tree
+      holds no dedicated UX checks, so nothing is mapped here yet.'
+    sections: []
+    rulePrefixes: []
+
+  - id: vision
+    name: Vision
+    description: 'Status: PROPOSED — aspirational, no rules mapped yet. Will cover the
+      live-assurance future: continuous verification, runtime attestation,
+      and audit-as-a-service loops that outgrow point-in-time reports. It
+      matters for assurance because auditing must become continuous to stay
+      relevant, but no vision packs exist yet, so this category is a labeled
+      empty axis awaiting them.'
+    sections: []
+    rulePrefixes: []
+
+  - id: technical-sota
+    name: Technical State of the Art
+    description: "Status: IMPLEMENTED. Covers AI/LLM-era risk controls, machine-learning
+      stack hygiene, and future-readiness signals — the frontier where new
+      failure modes appear first. It matters for assurance because yesterday's
+      checklist misses prompt injection, model provenance, and framework
+      churn, so the audit must track what the state of the art demands now."
+    sections: [S14, S15, S16]
+    rulePrefixes: [AI-, ML-, FUT-]
+
+  - id: architecture
+    name: Architecture
+    description: 'Status: IMPLEMENTED. Covers system structure, modularity, and design
+      intent — the decisions that make a codebase comprehensible or
+      accidental. It matters for assurance because architectural drift
+      compounds every other risk: monoliths that should be modules fail
+      reviews, rollbacks, and onboarding alike.'
+    sections: [S4]
+    rulePrefixes: [ARCH-]
+
+  - id: standards
+    name: Standards
+    description: 'Status: IMPLEMENTED. Covers compliance posture and alignment with
+      external frameworks — accessibility, licensing, data-protection, and
+      regulatory duties. It matters for assurance because contractual and
+      legal obligations are audit findings with counterparties, not opinions,
+      so conformance evidence must be checkable independently of taste.'
+    sections: [S13]
+    rulePrefixes: [COMP-]
+
+  - id: protocol
+    name: Protocol
+    description: 'Status: PROPOSED — aspirational, no rules mapped yet. Will cover
+      wire-protocol conformance, API contract fidelity, and schema
+      compatibility guarantees. It matters for assurance because
+      integrations fail at boundaries, but the current tree has no
+      protocol-conformance packs, so this category is empty until they
+      exist.'
+    sections: []
+    rulePrefixes: []

package/rules/core/testing-assurance.yaml

@@ -0,0 +1,240 @@
+id: core/testing-assurance
+title: Testing Assurance Markers
+section: S7
+section_title: Testing & Quality Assurance
+description: >
+  Deterministic presence-markers for the testing assurance program: unit,
+  integration, and system layouts; contract tests; coverage and mutation
+  evidence; retry/determinism guards; failure assertions; and test-data
+  isolation. Every rule asserts only that a marker exists — never that the
+  tests are good, sufficient, or green.
+version: '1.0'
+
+rules:
+  - id: TAS-001
+    title: A unit-test layout exists
+    section: S7
+    section_title: Testing & Quality Assurance
+    severity: MEDIUM
+    class: correctness
+    check:
+      kind: any_file
+      patterns:
+        - 'tests/unit/**'
+        - 'test/unit/**'
+        - 'unit/**'
+        - '**/*.unit.test.*'
+        - '**/*.unit.spec.*'
+    why: 'A conventional unit-test location tells contributors and CI exactly where confidence lives.'
+    remediation: 'Put unit tests under tests/unit (or mark them *.unit.test.*) and wire the directory into CI.'
+    references: ['Testing-Trophy', 'OpenSSF-Scorecard:CI-Tests']
+
+  - id: TAS-002
+    title: An integration-test layout exists
+    section: S7
+    section_title: Testing & Quality Assurance
+    severity: MEDIUM
+    class: correctness
+    check:
+      kind: any_file
+      patterns:
+        - 'tests/integration/**'
+        - 'test/integration/**'
+        - 'tests/integ/**'
+        - '**/*.integration.test.*'
+        - '**/*.integ.test.*'
+        - '**/*.int.test.*'
+    why: 'Unit tests with everything mocked verify the mock, not the seam; a named integration layout is where seam coverage lives.'
+    remediation: 'Add tests/integration with tests that exercise a real database, queue, or HTTP boundary.'
+    references: ['Testing-Trophy']
+
+  - id: TAS-003
+    title: A system/end-to-end test layout exists
+    section: S7
+    section_title: Testing & Quality Assurance
+    severity: MEDIUM
+    class: correctness
+    check:
+      kind: any_file
+      patterns:
+        - 'tests/e2e/**'
+        - 'test/e2e/**'
+        - 'e2e/**'
+        - 'tests/system/**'
+        - 'test/system/**'
+        - 'system-tests/**'
+        - '**/*.e2e.*'
+    why: 'Unit tests cannot tell you that checkout is broken because a button moved; a system-level layout is where journey coverage lives.'
+    remediation: 'Cover three journeys first: sign up/log in, the core money path, and the path that would lose data if it failed.'
+    references: ['Testing-Trophy']
+
+  - id: TAS-004
+    title: Contract tests are present
+    section: S7
+    section_title: Testing & Quality Assurance
+    severity: LOW
+    class: correctness
+    check:
+      kind: any_file
+      patterns:
+        - 'pacts/**'
+        - 'pact/**'
+        - '**/*.pact.*'
+        - 'tests/contracts/**'
+        - 'tests/contract/**'
+        - 'test/contracts/**'
+        - '**/*.contract.test.*'
+        - '**/*.contract.spec.*'
+    why: 'An API without checked-in consumer contracts can only be tested by hand; pact files and contract suites are the machine-checkable shadow of that agreement.'
+    remediation: 'Record consumer-driven contracts (e.g. Pact) or add a tests/contracts suite asserting request/response shapes.'
+    references: ['OpenAPI', 'Testing-Trophy']
+
+  - id: TAS-005
+    title: Coverage configuration or output is present
+    section: S7
+    section_title: Testing & Quality Assurance
+    severity: LOW
+    class: correctness
+    check:
+      kind: any_file
+      patterns:
+        - '.codecov.yml'
+        - 'codecov.yml'
+        - 'codecov.yaml'
+        - '.coveragerc'
+        - '.nycrc'
+        - '.nycrc.json'
+        - '.c8rc'
+        - '.c8rc.json'
+        - 'coverage/**'
+        - '**/lcov.info'
+    why: 'Unmeasured coverage drifts down silently; a coverage config or report artifact proves measurement was set up at least once.'
+    remediation: 'Turn on coverage reporting in the test runner and publish the number on every PR.'
+    references: ['NIST-SSDF-RV.1.1']
+
+  - id: TAS-006
+    title: A coverage threshold is pinned in the package.json-embedded jest config
+    section: S7
+    section_title: Testing & Quality Assurance
+    severity: LOW
+    class: correctness
+    check:
+      kind: json_path
+      file: 'package.json'
+      path: 'jest.coverageThreshold'
+    why: 'A gate stops the slide — but this check reads only the package.json-embedded jest config, the one JSON location with a stable schema. Thresholds kept in vitest.config, jest.config.js, or .nycrc are invisible to it.'
+    remediation: 'Set jest.coverageThreshold in package.json, or keep the threshold wherever the runner reads it and accept this marker as not-applicable.'
+    references: ['NIST-SSDF-RV.1.1']
+
+  - id: TAS-007
+    title: Mutation-testing evidence is present
+    section: S7
+    section_title: Testing & Quality Assurance
+    severity: FUTURE
+    class: correctness
+    check:
+      kind: any_file
+      patterns:
+        - 'reports/**/*mut*'
+        - 'reports/mutation/**'
+        - 'stryker.conf.*'
+        - '.stryker.conf.*'
+        - '.mutmut*'
+        - 'mutants/**'
+    why: 'Coverage tells you which lines ran, not whether the test would have failed if the line were wrong; a mutation config or report proves the question was asked.'
+    remediation: 'Run mutation testing on the highest-risk module first and keep the config or report in the repo.'
+    references: ['Mutation-Testing']
+
+  - id: TAS-008
+    title: A determinism guard is set in test config or CI
+    section: S7
+    section_title: Testing & Quality Assurance
+    severity: LOW
+    class: correctness
+    check:
+      kind: grep_present
+      pattern: '(forbidOnly|forbid-only|forbid_only|failOnConsole|fail-on-console)'
+      include:
+        [
+          'playwright.config.*',
+          'cypress.config.*',
+          'vitest.config.*',
+          'vitest.workspace.*',
+          'jest.config.*',
+          'package.json',
+          '.github/workflows/*.yml',
+          '.github/workflows/*.yaml',
+          '.gitlab-ci.yml',
+        ]
+    why: 'Focused-test markers (.only) committed by accident silently skip the rest of the suite; a forbid-only guard string proves the leak was thought about.'
+    remediation: 'Set forbidOnly on CI (e.g. Playwright forbidOnly) so a stray .only fails the build instead of shrinking it.'
+    references: ['Google-Testing-Blog:Flaky']
+
+  - id: TAS-009
+    title: A test retry budget is declared
+    section: S7
+    section_title: Testing & Quality Assurance
+    severity: LOW
+    class: operations
+    check:
+      kind: grep_present
+      pattern: '(retries\s*:\s*[1-9]|"retries"\s*:\s*[1-9]|retries=[1-9]|--retries[ =][1-9]|rerun-failed|flaky-test-retry|retry-on-failure)'
+      include:
+        [
+          'playwright.config.*',
+          'cypress.config.*',
+          'vitest.config.*',
+          'jest.config.*',
+          'package.json',
+          '.github/workflows/*.yml',
+          '.github/workflows/*.yaml',
+          '.gitlab-ci.yml',
+        ]
+    why: 'A retries setting proves the project pays for reruns; it proves nothing about whether the tests are flaky or stable — only that the budget exists.'
+    remediation: 'Declare an explicit retry budget (e.g. retries: 2 on CI) and track which tests consume it; quarantine chronic consumers.'
+    references: ['Google-Testing-Blog:Flaky']
+
+  - id: TAS-010
+    title: Tests assert failure paths
+    section: S7
+    section_title: Testing & Quality Assurance
+    severity: MEDIUM
+    class: correctness
+    check:
+      kind: grep_present
+      pattern: '(\.toThrow\(|\.rejects|pytest\.raises|assertRaises|assert\.rejects|ShouldThrow|assert\.throws)'
+      include:
+        [
+          '**/*.test.*',
+          '**/*.spec.*',
+          '**/test_*.py',
+          '**/*_test.*',
+          'tests/**',
+          'test/**',
+          '__tests__/**',
+          'spec/**',
+        ]
+    why: 'A suite that only asserts happy paths never proves the error handling works; failure-assertion strings prove at least one test looks at the sad path.'
+    remediation: 'Add negative tests for every permission boundary and every error branch — 401/403 paths, validation rejections, and cross-tenant attempts.'
+    references: ['Testing-Patterns']
+
+  - id: TAS-011
+    title: Test-data and environment isolation markers exist
+    section: S7
+    section_title: Testing & Quality Assurance
+    severity: LOW
+    class: maintainability
+    check:
+      kind: any_file
+      patterns:
+        - 'tests/fixtures/**'
+        - 'test/fixtures/**'
+        - '**/__fixtures__/**'
+        - '**/factories/**'
+        - '**/__factories__/**'
+        - '.env.test'
+        - '.env.testing'
+        - 'tests/.env.test'
+    why: 'Hand-built object literals in 200 tests make every schema change a 200-file migration, and tests sharing the live environment leak state; fixtures, factories, and a dedicated test env file are the markers of isolation.'
+    remediation: 'Add a factory or fixtures directory and a .env.test so tests generate data and never touch the dev or prod environment.'
+    references: ['Testing-Patterns', '12-Factor:Config']

package/rules/index.yaml

@@ -19,6 +19,7 @@ packs:
   - core/architecture.yaml
   - core/code-quality.yaml
   - core/testing.yaml
+  - core/testing-assurance.yaml
   - core/cicd.yaml
   - core/release.yaml
   - core/dependencies.yaml