@xenos1996/usat 1.0.0

package/dist/types.d.ts

@@ -0,0 +1,282 @@
+/**
+ * USAT — Universal Software Audit Template
+ * Core type definitions.
+ *
+ * Design note: USAT deliberately separates two orthogonal axes that most audit
+ * checklists conflate:
+ *
+ *   SEVERITY  = how bad it is *if this rule is violated* (impact).
+ *   STATUS    = what the audit actually observed (outcome).
+ *
+ * The emoji tags in USAT.md map onto these two axes (see `TAG_TABLE`) so the
+ * report still reads like a classic severity-tagged audit while the underlying
+ * model stays machine-checkable and scoreable.
+ */
+/** Impact axis — attached to a rule, meaning "severity when violated". */
+export type Severity = 'CRITICAL' | 'HIGH' | 'MEDIUM' | 'LOW' | 'FUTURE';
+/** Outcome axis — what the engine or the agent observed. */
+export type Status = 'PASS' | 'FAIL' | 'WRONG' | 'MISSING' | 'DEPRECATED' | 'EXPERIMENTAL' | 'UNKNOWN' | 'NOT_APPLICABLE';
+/** Why a rule exists — used by maturity profiles to decide what may be relaxed. */
+export type RuleClass = 'security' | 'supply-chain' | 'correctness' | 'maintainability' | 'operations' | 'performance' | 'compliance' | 'documentation' | 'style';
+/** How thorough the audit should be. */
+export type Depth = 'quick' | 'standard' | 'deep';
+/** Lifecycle stage — drives maturity-aware severity dampening. */
+export type Maturity = 'prototype' | 'mvp' | 'beta' | 'production' | 'legacy';
+export interface Location {
+    file: string;
+    line?: number;
+    excerpt?: string;
+}
+export interface Finding {
+    ruleId: string;
+    title: string;
+    section: string;
+    sectionTitle: string;
+    /** Severity after the maturity profile has been applied. */
+    severity: Severity;
+    /** Severity declared by the rule pack, before dampening. */
+    baseSeverity: Severity;
+    status: Status;
+    ruleClass: RuleClass;
+    /** True when the finding was downgraded by the maturity profile. */
+    dampened: boolean;
+    message: string;
+    locations: Location[];
+    /** Why the rule exists — surfaces in the judgement queue. */
+    why?: string;
+    /** What the agent/human must produce to resolve a judgement call. */
+    evidenceHint?: string;
+    remediation?: string;
+    references?: string[];
+    /** Set when a project-level suppression (`nack:`) hid this finding. */
+    suppressedReason?: string;
+}
+export type Predicate = {
+    all: Predicate[];
+} | {
+    any: Predicate[];
+} | {
+    not: Predicate;
+} | {
+    fact: string;
+    op?: FactOp;
+    value?: string | number | string[];
+};
+export type FactOp = 'exists' | 'absent' | 'eq' | 'neq' | 'in' | 'includes' | 'gt' | 'lt' | 'matches';
+export type Check = {
+    kind: 'manual';
+}
+/** PASS when at least one of `files` exists. */
+ | {
+    kind: 'file_exists';
+    files: string[];
+}
+/** PASS when none of `files` exist (fail → MISSING/FAIL). */
+ | {
+    kind: 'file_absent';
+    files: string[];
+}
+/** PASS when at least one file matches `patterns`. */
+ | {
+    kind: 'any_file';
+    patterns: string[];
+}
+/** PASS when `pattern` is found in the scanned files. */
+ | {
+    kind: 'grep_present';
+    pattern: string;
+    include: string[];
+    exclude?: string[];
+    flags?: string;
+}
+/** PASS when `pattern` is NOT found. Any hit is a FAIL with a location. */
+ | {
+    kind: 'grep_absent';
+    pattern: string;
+    include: string[];
+    exclude?: string[];
+    flags?: string;
+}
+/** Any hit is ⚠️ WRONG — present but implemented incorrectly. */
+ | {
+    kind: 'grep_wrong';
+    pattern: string;
+    include: string[];
+    exclude?: string[];
+    flags?: string;
+}
+/** Any hit is 💀 DEPRECATED — present but EOL / abandoned. */
+ | {
+    kind: 'grep_deprecated';
+    pattern: string;
+    include: string[];
+    exclude?: string[];
+    flags?: string;
+}
+/** PASS when `path` resolves in the JSON file (`equals` optional). */
+ | {
+    kind: 'json_path';
+    file: string;
+    path: string;
+    equals?: string | number | boolean;
+}
+/** PASS when at least one file matching `patterns` is TRACKED by git. */
+ | {
+    kind: 'tracked_present';
+    patterns: string[];
+}
+/** PASS when NO file matching `patterns` is tracked by git (committed junk). */
+ | {
+    kind: 'tracked_absent';
+    patterns: string[];
+}
+/** PASS when the number of distinct files matching `patterns` >= `min`. */
+ | {
+    kind: 'count_min';
+    patterns: string[];
+    min: number;
+}
+/** PASS when no indexed file matching `patterns` exceeds `max_lines`. */
+ | {
+    kind: 'file_lines_max';
+    patterns: string[];
+    max_lines: number;
+}
+/** PASS when the command exits with `expect_exit` (default 0). Opt-in. */
+ | {
+    kind: 'command';
+    run: string;
+    expect_exit?: number;
+}
+/** Never evaluated — informational context for the reader/agent. */
+ | {
+    kind: 'info';
+};
+export interface Rule {
+    id: string;
+    title: string;
+    section: string;
+    sectionTitle?: string;
+    severity: Severity;
+    weight?: number;
+    ruleClass: RuleClass;
+    appliesWhen?: Predicate;
+    /** Depths at which the rule participates. Omit = always. */
+    depths?: Depth[];
+    check: Check;
+    /** Why this rule matters — keeps agents from cargo-culting. */
+    why?: string;
+    /** Required proof. Mandatory for `manual` checks (RULE 4). */
+    evidence?: string;
+    remediation?: string;
+    references?: string[];
+    tags?: string[];
+}
+export interface RulePack {
+    id: string;
+    title: string;
+    description?: string;
+    version?: string;
+    /** Section id this pack primarily contributes to. */
+    section?: string;
+    sectionTitle?: string;
+    /** Facts that, if present, cause the whole pack to be skipped. */
+    skipWhen?: Predicate;
+    /** Extra facts this pack contributes simply by being loaded. */
+    provides?: string[];
+    rules: Rule[];
+    source?: string;
+}
+export interface Facts {
+    /** Set membership facts, e.g. `lang:typescript`, `has:ci`, `maturity:beta`. */
+    flags: Set<string>;
+    /** Numeric facts, e.g. `commits`, `contributors`, `loc`, `daysSinceCommit`. */
+    metrics: Record<string, number>;
+}
+export interface Suppression {
+    rule: string;
+    reason: string;
+    until?: string;
+}
+export interface UsatConfig {
+    version: 1;
+    /** Override auto-detection: force a maturity stage. */
+    maturity?: Maturity;
+    /** Rule pack ids to always load, even if `appliesWhen` says no. */
+    include?: string[];
+    /** Rule pack ids to never load. */
+    exclude?: string[];
+    /** Per-rule overrides: severity, weight, or full suppression. */
+    rules?: Record<string, {
+        severity?: Severity;
+        weight?: number;
+        disabled?: boolean;
+        reason?: string;
+    }>;
+    /** Suppressed findings — must carry a reason (auditable). */
+    suppressions?: Suppression[];
+    /** Extra globs to ignore while indexing. */
+    ignore?: string[];
+    /** Extra facts asserted by the operator. */
+    facts?: string[];
+    /** Restrict the report to these sections. */
+    sections?: string[];
+}
+export interface SectionScore {
+    id: string;
+    title: string;
+    /** null when no rule in the section could be resolved automatically. */
+    score: number | null;
+    weight: number;
+    applicable: number;
+    resolved: number;
+    passed: number;
+    failed: number;
+    unknown: number;
+    /** resolved / applicable — how much of this section the tool could verify. */
+    confidence: number;
+}
+export interface ScoreCard {
+    overall: number;
+    sections: SectionScore[];
+    counts: Record<Status, number>;
+    severityCounts: Record<Severity, number>;
+    /** Share of applicable rules the engine could verify without a human. */
+    automationCoverage: number;
+    /** Expected score band for the detected maturity stage. */
+    expectedBand: [number, number];
+}
+export interface AuditReport {
+    schema: 'usat-report-v1';
+    generatedAt: string;
+    usatVersion: string;
+    target: {
+        path: string;
+        name: string;
+        commit?: string;
+        ref?: string;
+        repoUrl?: string;
+    };
+    detection: {
+        maturity: Maturity;
+        maturitySignals: string[];
+        projectTypes: string[];
+        platforms: string[];
+        languages: string[];
+        frameworks: string[];
+        packageManagers: string[];
+        databases: string[];
+        flags: string[];
+        metrics: Record<string, number>;
+    };
+    options: {
+        depth: Depth;
+        profile: Maturity | 'auto';
+        rulesDir: string;
+        packsLoaded: string[];
+        packsSkipped: string[];
+    };
+    score: ScoreCard;
+    findings: Finding[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,16 @@
+/**
+ * USAT — Universal Software Audit Template
+ * Core type definitions.
+ *
+ * Design note: USAT deliberately separates two orthogonal axes that most audit
+ * checklists conflate:
+ *
+ *   SEVERITY  = how bad it is *if this rule is violated* (impact).
+ *   STATUS    = what the audit actually observed (outcome).
+ *
+ * The emoji tags in USAT.md map onto these two axes (see `TAG_TABLE`) so the
+ * report still reads like a classic severity-tagged audit while the underlying
+ * model stays machine-checkable and scoreable.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

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

package/dist/util/glob.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Minimal, dependency-free glob matching.
+ * Supports: `**`, `*`, `?`, `{a,b}` alternation, and `[abc]` character classes.
+ * Enough for rule packs; avoids pulling in a glob dependency.
+ */
+export declare function globToRegExp(glob: string): RegExp;
+export declare function matchesGlob(path: string, glob: string): boolean;
+export declare function matchesAny(path: string, globs: string[]): boolean;
+/** A glob that looks like it targets a literal path (no magic chars). */
+export declare function isLiteralPath(glob: string): boolean;
+//# sourceMappingURL=glob.d.ts.map

package/dist/util/glob.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"glob.d.ts","sourceRoot":"","sources":["../../src/util/glob.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAOjD;AAkED,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAE/D;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAEjE;AAED,yEAAyE;AACzE,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEnD"}

package/dist/util/glob.js

@@ -0,0 +1,86 @@
+/**
+ * Minimal, dependency-free glob matching.
+ * Supports: `**`, `*`, `?`, `{a,b}` alternation, and `[abc]` character classes.
+ * Enough for rule packs; avoids pulling in a glob dependency.
+ */
+const GLOB_CACHE = new Map();
+export function globToRegExp(glob) {
+    const cached = GLOB_CACHE.get(glob);
+    if (cached)
+        return cached;
+    const compiled = new RegExp(`^${translateGlob(glob)}$`);
+    GLOB_CACHE.set(glob, compiled);
+    return compiled;
+}
+function translateGlob(glob) {
+    let re = '';
+    let i = 0;
+    while (i < glob.length) {
+        const step = matchStar(glob, i) ?? matchQuestion(glob, i) ?? matchBrace(glob, i) ?? matchBracket(glob, i);
+        if (step) {
+            re += step.text;
+            i = step.next;
+            continue;
+        }
+        re += glob[i].replace(/[.+^${}()|[\]\\]/g, '\\$&');
+        i += 1;
+    }
+    return re;
+}
+function matchStar(glob, i) {
+    if (glob[i] !== '*')
+        return null;
+    if (glob[i + 1] === '*') {
+        // `**`
+        if (glob[i + 2] === '/')
+            return { text: '(?:.*/)?', next: i + 3 };
+        return { text: '.*', next: i + 2 };
+    }
+    return { text: '[^/]*', next: i + 1 };
+}
+function matchQuestion(glob, i) {
+    return glob[i] === '?' ? { text: '[^/]', next: i + 1 } : null;
+}
+function matchBrace(glob, i) {
+    if (glob[i] !== '{')
+        return null;
+    const end = findClosing(glob, i, '{', '}');
+    if (end === -1)
+        return { text: '\\{', next: i + 1 };
+    return { text: `(?:${glob.slice(i + 1, end).replace(/,/g, '|')})`, next: end + 1 };
+}
+function matchBracket(glob, i) {
+    if (glob[i] !== '[')
+        return null;
+    const end = findClosing(glob, i, '[', ']');
+    if (end === -1)
+        return { text: '\\[', next: i + 1 };
+    let body = glob.slice(i + 1, end);
+    if (body.startsWith('!'))
+        body = '^' + body.slice(1);
+    return { text: `[${body}]`, next: end + 1 };
+}
+function findClosing(s, start, open, close) {
+    let depth = 0;
+    for (let i = start; i < s.length; i++) {
+        if (s[i] === open)
+            depth++;
+        else if (s[i] === close) {
+            depth--;
+            if (depth === 0)
+                return i;
+        }
+    }
+    return -1;
+}
+export function matchesGlob(path, glob) {
+    return globToRegExp(glob).test(path);
+}
+export function matchesAny(path, globs) {
+    return globs.some((g) => matchesGlob(path, g));
+}
+/** A glob that looks like it targets a literal path (no magic chars). */
+export function isLiteralPath(glob) {
+    return !/[*?[\]{}]/.test(glob);
+}
+//# sourceMappingURL=glob.js.map

package/dist/util/glob.js.map

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

package/dist/util/project.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Files that ARE part of the project index but should never be grepped or read:
+ * lockfiles, minified bundles, source maps. They must stay in the index (a rule
+ * asking "is a lockfile committed?" has to see them) but scanning them produces
+ * noise, false positives, and a lot of wasted I/O.
+ */
+export declare const GREP_SKIP: string[];
+/** Directories and files never worth auditing. */
+export declare const DEFAULT_IGNORES: string[];
+export interface GrepHit {
+    file: string;
+    line: number;
+    excerpt: string;
+}
+/**
+ * A snapshot of the audited tree. Built once, reused by every rule evaluation —
+ * the whole audit is O(files) on disk and O(patterns × files) in memory.
+ */
+export declare class Project {
+    readonly root: string;
+    readonly files: string[];
+    private readonly ignores;
+    private readonly contentCache;
+    private readonly dirCache;
+    private tracked;
+    constructor(root: string, extraIgnores?: string[]);
+    private walk;
+    private visitEntry;
+    /** All files matching at least one of `globs`. */
+    glob(globs: string[]): string[];
+    has(glob: string): boolean;
+    dirExists(dir: string): boolean;
+    /** Directories present directly under root, one level deep. */
+    topLevelDirs(): string[];
+    /** True when at least one file matches `patterns`. */
+    anyFile(patterns: string[]): boolean;
+    /** Number of distinct files matching `patterns`. */
+    count(patterns: string[]): number;
+    /** File contents, or null when unreadable / binary / too large. */
+    read(rel: string): string | null;
+    readJson(rel: string): unknown | null;
+    /**
+     * Grep across the project. `include`/`exclude` are globs; when `include` is
+     * empty every indexed file is scanned.
+     */
+    grep(pattern: string, include: string[], exclude?: string[], flags?: string): GrepHit[];
+    private grepFile;
+    /**
+     * Files tracked by git. The tree index skips build output and vendored code
+     * for speed and signal quality, but some checks ("is `.env` committed?",
+     * "are build artifacts in the repo?") can only be answered from git.
+     */
+    trackedFiles(): string[];
+    trackedGlob(globs: string[]): string[];
+    gitInfo(): {
+        commit?: string;
+        ref?: string;
+        repoUrl?: string;
+        commits: number;
+        contributors: number;
+        tags: number;
+        daysSinceLastCommit?: number;
+        branches: number;
+        isRepo: boolean;
+    };
+    private gitRun;
+    private gitIdentity;
+    private gitStats;
+}
+/** package.json / tsconfig.json style comments + trailing commas. */
+export declare function stripJsonComments(text: string): string;
+//# sourceMappingURL=project.d.ts.map

package/dist/util/project.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"project.d.ts","sourceRoot":"","sources":["../../src/util/project.ts"],"names":[],"mappings":"AAKA;;;;;GAKG;AACH,eAAO,MAAM,SAAS,UAqBrB,CAAC;AAEF,kDAAkD;AAClD,eAAO,MAAM,eAAe,UAuC3B,CAAC;AA2HF,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;GAGG;AACH,qBAAa,OAAO;IAClB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,CAAM;IAC9B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAW;IACnC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAoC;IACjE,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAqB;IAC9C,OAAO,CAAC,OAAO,CAAyB;gBAE5B,IAAI,EAAE,MAAM,EAAE,YAAY,GAAE,MAAM,EAAO;IAQrD,OAAO,CAAC,IAAI;IAwBZ,OAAO,CAAC,UAAU;IAmBlB,kDAAkD;IAClD,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE;IAS/B,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI1B,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAS/B,+DAA+D;IAC/D,YAAY,IAAI,MAAM,EAAE;IAIxB,sDAAsD;IACtD,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,OAAO;IAIpC,oDAAoD;IACpD,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,MAAM;IAIjC,mEAAmE;IACnE,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAmBhC,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,GAAG,IAAI;IAUrC;;;OAGG;IACH,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,EAAE,OAAO,GAAE,MAAM,EAAO,EAAE,KAAK,SAAK,GAAG,OAAO,EAAE;IAYvF,OAAO,CAAC,QAAQ;IAwBhB;;;;OAIG;IACH,YAAY,IAAI,MAAM,EAAE;IAsBxB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE;IAItC,OAAO,IAAI;QACT,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,GAAG,CAAC,EAAE,MAAM,CAAC;QACb,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,OAAO,EAAE,MAAM,CAAC;QAChB,YAAY,EAAE,MAAM,CAAC;QACrB,IAAI,EAAE,MAAM,CAAC;QACb,mBAAmB,CAAC,EAAE,MAAM,CAAC;QAC7B,QAAQ,EAAE,MAAM,CAAC;QACjB,MAAM,EAAE,OAAO,CAAC;KACjB;IAQD,OAAO,CAAC,MAAM;IAad,OAAO,CAAC,WAAW;IAOnB,OAAO,CAAC,QAAQ;CAyBjB;AAiGD,qEAAqE;AACrE,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAWtD"}