@xenos1996/usa 2.26.2 → 2.28.0

package/dist/scanner/types.d.ts

@@ -0,0 +1,236 @@
+/**
+ * Scanner subsystem types.
+ *
+ * These are the only types the adapter layer owns, and nothing in `src/engine/`
+ * imports them: a rule consumes scanner *artifacts* through the existing
+ * `oracle` check (ADR-0011) instead of importing evidence objects. That keeps
+ * the dependency direction one-way and keeps the rule engine free of any
+ * scanner-specific schema.
+ */
+/** The tool's own severity word, quoted verbatim and never re-mapped. */
+export type ScannerSeverity = 'CRITICAL' | 'HIGH' | 'MEDIUM' | 'LOW' | 'INFO';
+/**
+ * A scanner's verdict about its own observation — NOT a rule status.
+ * `UNAVAILABLE` exists so that "no evidence found" can never be read as
+ * "the feature does not exist" (Phase 5's hard requirement).
+ */
+export type ScannerVerdict = 'PASS' | 'FAIL' | 'PARTIAL' | 'UNKNOWN' | 'NOT_APPLICABLE' | 'UNAVAILABLE';
+export type ScannerStatus = 'ok' | 'unavailable' | 'timeout' | 'error' | 'skipped';
+/**
+ * One fact, observed by a tool, with enough provenance to re-find it.
+ *
+ * The `id` is a content hash over source + identifier + location + claim, so the
+ * same observation deduplicates across tools and across runs.
+ */
+export interface Evidence {
+    /** Stable content hash (EVT-<hex>). */
+    id: string;
+    source: EvidenceSource;
+    provenance: EvidenceProvenance;
+    claim: string;
+    severity: ScannerSeverity;
+    severitySource: 'tool-native' | 'adapter-default';
+    confidence: number;
+    status: ScannerVerdict;
+    /** Where to look. `null` means the tool does not locate — never "everywhere". */
+    location: EvidenceLocation | null;
+    /** Pointer back into the raw tool output, for re-reading. */
+    rawReference: RawReference;
+    /**
+     * CWE ids the tool itself attached to this finding (`CWE-79`).
+     *
+     * Structured rather than inferred from the claim text, because this is the
+     * join key between scanner evidence and a declared threat model — and a join
+     * built on substring matching would invent relationships.
+     */
+    cwes?: string[];
+}
+export interface EvidenceSource {
+    /** Adapter id, e.g. `trivy`. */
+    tool: string;
+    /** Tool version, as reported by `tool --version`. */
+    version: string;
+    /** Tool-native category (e.g. `vulnerability`, `secret`, `dependency-edge`). */
+    kind: string;
+    /** Tool-native identifier, preserved verbatim (CVE id, rule id, …). */
+    identifier: string;
+}
+export interface EvidenceProvenance {
+    executionId: string;
+    /** argv actually executed, for a re-run. */
+    command: string[];
+    /**
+     * Upstream stages that ran before `command`, in order. Present so that a
+     * provenance record reproduces the run rather than only its last step.
+     */
+    preparedBy?: string[][];
+    /** Adapter config in effect, including rule-pack versions. */
+    config: Record<string, unknown>;
+    /** The commit the target pointed at, or `unversioned`. */
+    repositoryRevision: string;
+    timestamp: string;
+    executable: string;
+    /** Command timeout in milliseconds. */
+    timeoutMs: number;
+    /** Seconds the tool ran. */
+    elapsedMs: number;
+}
+export interface EvidenceLocation {
+    file: string;
+    line?: number;
+    column?: number;
+}
+export interface RawReference {
+    /** Byte offset into the artifact the claim came from. */
+    artifactOffset?: number;
+    jsonPath?: string;
+    excerpt?: string;
+}
+/** A finding produced directly from scanner evidence (path 2). */
+export interface ScannerFinding {
+    id: string;
+    ruleId: string;
+    title: string;
+    claim: string;
+    severity: ScannerSeverity;
+    confidence: number;
+    status: ScannerVerdict;
+    evidenceIds: string[];
+    remediation: string;
+    locations: EvidenceLocation[];
+}
+/** One adapter's record in the run manifest — coverage as a first-class fact. */
+export interface AdapterRun {
+    id: string;
+    available: boolean;
+    version: string;
+    command: string[];
+    /** Upstream stages that ran before `command`, in order. */
+    prepare?: string[][];
+    /** Artifact the evidence was parsed from, relative to the workdir. */
+    artifact?: string;
+    status: ScannerStatus;
+    /** Why an adapter did not produce evidence. Mandatory unless ok. */
+    reason?: string;
+    /**
+     * The process exit status, recorded and never interpreted.
+     *
+     * Tools disagree about what a non-zero status means: ORT exits 2 when it
+     * found violations (the run succeeded), while a usage error is also non-zero.
+     * The verdict comes from the parsed payload; the status is here so a reader
+     * can tell "it ran and objected" from "it never started".
+     */
+    exitCode?: number;
+    evidenceCount: number;
+    elapsedMs: number;
+    needsNetwork: boolean;
+}
+export interface RunManifest {
+    executionId: string;
+    target: string;
+    repositoryRevision: string;
+    timestamp: string;
+    adapters: AdapterRun[];
+    environment: {
+        sandbox: string;
+        network: 'denied' | 'allowed';
+        outputCapBytes: number;
+    };
+}
+/** Everything an adapter needs to describe how it should run. */
+export interface ScanTarget {
+    /** Absolute path to the audited project. */
+    path: string;
+    /** Scratch copy working directory; adapters run here, never in `path`. */
+    workdir: string;
+    revision: string;
+    executionId: string;
+}
+/** One process in a staged tool's pipeline (ORT `analyze`, CodeQL `create`). */
+export interface ScannerStage {
+    argv: string[];
+    /** Overrides the command timeout for this stage alone. */
+    timeoutMs?: number;
+}
+export interface ScannerCommand {
+    /** The command that produces the evidence. */
+    argv: string[];
+    /**
+     * Stages that must succeed before `argv` runs.
+     *
+     * Some tools are pipelines, not single processes: ORT's `evaluate` reads a
+     * result file that `analyze` writes, and CodeQL's `analyze` reads a database
+     * that `create` writes. Without this the adapter can only describe a command
+     * that will always fail on a fresh checkout.
+     */
+    prepare?: ScannerStage[];
+    /**
+     * Files the tool writes its parseable output to, relative to the scan
+     * workdir. The first that exists is read and handed to `parse` instead of
+     * stdout.
+     *
+     * Measured, not assumed: ORT's `evaluate` and CodeQL's `analyze` write JSON
+     * to a file and log to stdout, so an adapter that parses stdout gets progress
+     * lines where it expected violations.
+     */
+    artifacts?: string[];
+    network?: boolean;
+    /** Extra wall-time for slow tools (database builds). */
+    timeoutMs?: number;
+}
+export interface ScannerConfig {
+    [key: string]: unknown;
+}
+export interface AdapterProbe {
+    available: boolean;
+    version: string;
+    /** Why it is unavailable, when it is. */
+    reason?: string;
+    executable?: string;
+}
+/**
+ * The contract every scanner lives behind.
+ *
+ * `buildCommand` and `parse` are pure functions of their inputs — that is what
+ * makes a scanner testable without being installed.
+ */
+export interface ScannerAdapter {
+    readonly id: string;
+    readonly name: string;
+    /** True when a run may need network access (declared in the manifest). */
+    readonly needsNetwork?: boolean;
+    /**
+     * The `.usa/scanners.yaml` key that removes this adapter's network need, e.g.
+     * `scanners.semgrep.rules`. Named in the refusal message, because "needs
+     * network" is only actionable if the reader knows what to change.
+     */
+    readonly networkConfigKey?: string;
+    defaultConfig(): ScannerConfig;
+    probe(): AdapterProbe;
+    buildCommand(target: ScanTarget, config: ScannerConfig): ScannerCommand;
+    parse(raw: string, context: ParseContext): Evidence[];
+    findings?(evidence: Evidence[]): ScannerFinding[];
+}
+export interface ParseContext {
+    adapterId: string;
+    adapterVersion: string;
+    target: ScanTarget;
+    config: ScannerConfig;
+}
+export interface ScanOptions {
+    target: string;
+    /** Adapter ids to run; default = all enabled in config. */
+    adapters?: string[];
+    config?: Record<string, ScannerConfig>;
+    /** Refuse to run anything that needs a build step (default true). */
+    allowBuildCommands?: boolean;
+    network?: boolean;
+    timeoutMs?: number;
+    now?: () => Date;
+}
+export interface ScanResult {
+    manifest: RunManifest;
+    evidence: Evidence[];
+    findings: ScannerFinding[];
+}
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/scanner/types.ts"],"names":[],"mappings":"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"}

package/dist/scanner/types.js

@@ -0,0 +1,11 @@
+/**
+ * Scanner subsystem types.
+ *
+ * These are the only types the adapter layer owns, and nothing in `src/engine/`
+ * imports them: a rule consumes scanner *artifacts* through the existing
+ * `oracle` check (ADR-0011) instead of importing evidence objects. That keeps
+ * the dependency direction one-way and keeps the rule engine free of any
+ * scanner-specific schema.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/scanner/types.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xenos1996/usa",
-  "version": "2.26.2",
+  "version": "2.28.0",
   "description": "Universal Software Auditor — an open-source, self-adapting audit framework for any project, any stack, any stage",
   "license": "MIT",
   "type": "module",
@@ -71,17 +71,18 @@
   "devDependencies": {
     "@changesets/changelog-github": "^1.0.1",
     "@changesets/cli": "^3.0.3",
-    "@commitlint/cli": "^21.2.2",
-    "@commitlint/config-conventional": "^21.2.2",
+    "@commitlint/cli": "^21.2.3",
+    "@commitlint/config-conventional": "^21.2.3",
     "@eslint/js": "^10.0.1",
-    "@types/node": "^26.5.1",
+    "@types/node": "^26.6.4",
     "@vitest/coverage-v8": "^5.0.0",
-    "eslint": "^10.10.0",
+    "eslint": "^10.12.0",
     "husky": "^9.1.7",
-    "lint-staged": "^17.5.1",
-    "prettier": "^3.4.2",
+    "lint-staged": "^17.6.0",
+    "prettier": "^3.9.9",
     "typescript": "^5.7.3",
-    "typescript-eslint": "^8.20.0",
+    "typescript-eslint": "^8.71.0",
+    "vite": "^8.3.3",
     "vitest": "^5.0.0"
   },
   "scripts": {

package/rules/core/code-quality.yaml

@@ -100,7 +100,12 @@ rules:
     applies_when: { fact: 'lang:typescript' }
     check:
       kind: grep_absent
-      pattern: '(@ts-ignore|@ts-expect-error|:\s*any\b|\bas any\b|as unknown as)'
+      # `:\s*any\b` alone matched prose — "Degraded-never-empty: any fetch
+      # failure" in a doc comment — so the type-escape branch now requires a
+      # type position after the keyword (`: any,` `: any)` `: any[]` `: any =`).
+      # Masking comments instead is not an option here: `@ts-ignore` lives in a
+      # comment, and the rule exists to catch it.
+      pattern: '(@ts-ignore|@ts-expect-error|:\s*any\b(?=\s*[,;)\]}>=]|$)|\bas any\b|as unknown as)'
       include: ['**/*.{ts,tsx}']
       exclude: ['**/*.test.*', '**/*.spec.*', '**/*.d.ts']
     why: 'Every `any` is a place the type system was told to stop helping. A few are fine; a pattern is a problem.'
@@ -204,7 +209,12 @@ rules:
       kind: grep_wrong
       pattern: '(TODO|FIXME|XXX|HACK|WORKAROUND)\b'
       include: ['**/*.{ts,tsx,js,jsx,py,go,rs,java,kt,rb,php,cs,yml,yaml}']
-      exclude: ['**/*.md', '**/docs/**', '**/node_modules/**']
+      # A fixture is a *sample of bad code*, not debt: CQ-010.yaml contains a
+      # TODO precisely so this rule has something to flag. Excluding them here
+      # (rather than from the audit index) keeps the fixtures visible to the
+      # rules that need to see them, e.g. TAS-011.
+      exclude:
+        ['**/*.md', '**/docs/**', '**/node_modules/**', '**/fixtures/**', '**/__fixtures__/**']
     why: 'A TODO with no owner and no ticket is a lie the codebase tells itself.'
     remediation: 'Convert each one to a tracked issue with a link in the comment, or delete it if it no longer applies.'
 

package/rules/core/provenance-attestation.yaml

@@ -58,6 +58,11 @@ rules:
       # An empty signature file signs nothing — presence alone is not evidence.
       non_empty: true
       files:
+        # cosign's own default bundle name is `<artifact>.sigstore.json`
+        # (`cosign sign-blob --bundle x.sigstore.json`), which `*.sigstore`
+        # does not match — that gap made every cosign-signed repo fail this
+        # rule. `*.sigstore` stays for legacy bundles written with that suffix.
+        - '**/*.sigstore.json'
         - '**/*.sigstore'
         - '**/*.bundle'
         - '**/*.sig'

package/rules/core/testing-assurance.yaml

@@ -137,11 +137,22 @@ rules:
       patterns:
         - 'reports/**/*mut*'
         - 'reports/mutation/**'
+        # Stryker's default config file has been `stryker.config.*` since v6;
+        # `stryker.conf.*` is the pre-6 name and is kept for older projects.
+        - 'stryker.config.*'
         - '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.'
+        # A committed harness that mutates and asserts is evidence too — and
+        # stronger evidence than a config file, which proves only that someone
+        # installed a tool. USA mutates every rule check and asserts its own
+        # fixture flips (tests/integration/auditor-mutation.test.ts, ~100
+        # probes in every CI run); no third-party tool name appears anywhere in
+        # the repo, so the tool-only globs scored that work as absent.
+        - 'tests/**/*mutation*'
+        - 'tests/**/mutation/**'
+    why: 'Coverage tells you which lines ran, not whether the test would have failed if the line were wrong; a mutation config, report, or committed mutation harness 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']
 
@@ -178,7 +189,11 @@ rules:
     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)'
+      # A declared budget of zero is a budget, and a stricter one than 2:
+      # the project has decided a flaky test is a failure, not a rerun. The
+      # earlier `[1-9]` required paying for retries, so the most honest
+      # answer a deterministic suite can give was scored as absent.
+      pattern: '(retr(?:y|ies)\s*:\s*\d|retries=\d|--retries[ =]\d|rerun-failed|flaky-test-retry|retry-on-failure)'
       include:
         [
           'playwright.config.*',
@@ -190,8 +205,8 @@ rules:
           '.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.'
+    why: 'A declared retry budget says what the project does when a test fails twice: rerun it, or treat it as a defect. Either answer is a policy; silence means nobody decided.'
+    remediation: 'Declare the budget explicitly. Prefer retries: 0 and fix flakes; if reruns are unavoidable, set retries: 2 on CI only, track which tests consume it, and quarantine chronic consumers.'
     references: ['Google-Testing-Blog:Flaky']
 
   - id: TAS-010