unslop-ci 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,289 @@
+type Severity = 'high' | 'medium' | 'low';
+/**
+ * The orthogonal axis to severity. "bug" means the flagged code is wrong (it
+ * eats a failure or ships unfinished) and gets fixed on those grounds alone;
+ * "cosmetic" means it is the model's chat voice leaking into the file. All
+ * text and UI rules are cosmetic; only the code scanner carries bug-class
+ * rules.
+ */
+type RuleClass = 'bug' | 'cosmetic';
+type ScannerName = 'code' | 'text' | 'ui';
+interface Rule {
+    id: string;
+    label: string;
+    severity: Severity;
+    class: RuleClass;
+    /** The share of the underlying Reddit study this tell carries, kept verbatim. */
+    share?: string;
+    fix: string;
+    patterns: RegExp[];
+    /** Rules compiled case-sensitively (verbose-naming keys on camelCase). */
+    caseSensitive?: boolean;
+    /**
+     * Text scanner only: flagged even inside quotes/backticks/blockquotes
+     * (the em dash rule — the rule is simply not to ship one).
+     */
+    raw?: boolean;
+    /** UI scanner only: a line matching this is not flagged by the rule. */
+    suppress?: RegExp;
+}
+interface ScannerDef {
+    name: ScannerName;
+    title: string;
+    exts: Set<string>;
+    skipDirs: Set<string>;
+    rules: Rule[];
+    /** Skip .min.js/.min.css/.map files and single-line files > 5000 chars. */
+    skipMinified: boolean;
+    /** Use the prose pipeline (frontmatter, fences, quote stripping, word counts). */
+    prose: boolean;
+}
+interface Finding {
+    scanner: ScannerName;
+    rule: string;
+    label: string;
+    severity: Severity;
+    class: RuleClass;
+    share?: string;
+    fix: string;
+    /** Repo-relative posix path. */
+    file: string;
+    /** 1-based line number. */
+    line: number;
+    match: string;
+    snippet: string;
+    /** True when this finding fails the gate. Filled in by the gate. */
+    blocking: boolean;
+}
+type FailOn = 'high+bugs' | 'high' | 'medium' | 'any';
+interface ScannerReport {
+    scanner: ScannerName;
+    filesScanned: number;
+    counts: Record<Severity, number>;
+    classCounts: Record<RuleClass, number>;
+    score: number;
+    verdict: string;
+    /** Text scanner only: words considered (added lines in diff mode). */
+    words?: number;
+    /** Text scanner only: weighted score per 1,000 words. */
+    densityPer1kWords?: number;
+}
+interface Report {
+    mode: 'diff' | 'scan';
+    base?: string;
+    head?: string;
+    failOn: FailOn;
+    filesScanned: number;
+    /** Diff mode only: total added lines considered. */
+    addedLines?: number;
+    findings: Finding[];
+    blockingCount: number;
+    scanners: ScannerReport[];
+}
+
+interface ScannerConfig {
+    /** When set, only paths matching one of these globs are scanned. */
+    include?: string[];
+    /** Paths matching one of these globs are never scanned. */
+    exclude?: string[];
+    /** Rule ids disabled for this scanner. */
+    disableRules?: string[];
+}
+interface UnslopConfig {
+    /** What blocks the build. Default: 'high+bugs'. */
+    failOn?: FailOn;
+    /** Global path excludes, applied to every scanner. */
+    exclude?: string[];
+    /** Rule ids disabled everywhere. */
+    disableRules?: string[];
+    /** Per-rule severity override, or 'off' to disable. */
+    rules?: Record<string, Severity | 'off'>;
+    /** Per-scanner settings; set a scanner to false to disable it entirely. */
+    scanners?: Partial<Record<ScannerName, ScannerConfig | false>>;
+}
+declare const DEFAULT_CONFIG_FILENAME = "unslop.config.json";
+declare class ConfigError extends Error {
+}
+declare function validateConfig(raw: unknown, source: string): UnslopConfig;
+/**
+ * Load config from an explicit path, or from unslop.config.json in cwd when
+ * present. An explicit path that does not exist is an error; a missing
+ * default file just means defaults.
+ */
+declare function loadConfig(cwd: string, explicitPath?: string): UnslopConfig;
+
+declare const ALL_SCANNERS: ScannerDef[];
+interface RunOptions {
+    cwd: string;
+    mode: 'diff' | 'scan';
+    /** Diff mode: the ref to diff against (required). */
+    base?: string;
+    /** Diff mode: the ref whose content is scanned; omit for the working tree. */
+    head?: string;
+    /** Diff mode: use merge-base (three-dot) semantics. Default true. */
+    mergeBase?: boolean;
+    /** Scan mode: the path to walk. Defaults to cwd. */
+    scanPath?: string;
+    configPath?: string;
+    /** Pre-loaded config; skips file loading when provided. */
+    config?: UnslopConfig;
+    /** Overrides config failOn. */
+    failOn?: FailOn;
+    /** Restrict to a subset of scanners. */
+    scanners?: ScannerName[];
+}
+/** Apply config rule overrides/disables to a scanner definition. */
+declare function effectiveRules(def: ScannerDef, cfg: UnslopConfig): Rule[];
+declare function run(opts: RunOptions): Report;
+
+interface RawFinding {
+    rule: string;
+    label: string;
+    severity: Severity;
+    class: Finding['class'];
+    share?: string;
+    fix: string;
+    line: number;
+    match: string;
+    snippet: string;
+}
+interface ScanResult {
+    findings: RawFinding[];
+    /** Prose scanners only: word count per 1-based line (index 0 unused). */
+    lineWords?: number[];
+}
+/** True when the file looks minified: a single line longer than 5000 chars. */
+declare function looksMinified(lines: string[]): boolean;
+interface NoiseState {
+    inCode: boolean;
+    inQuote: boolean;
+}
+/**
+ * Blank what the author is quoting or showing as a literal example, so the
+ * prose rules lint the author's own sentences. Inline-code spans (backticks)
+ * and double-quoted spans are removed, and the open/closed state is carried
+ * across lines so a span that wraps onto the next line is still skipped.
+ * State is reset at every blank line by the caller, so an unbalanced quote
+ * can never swallow more than one paragraph.
+ */
+declare function stripNoise(line: string, state: NoiseState): string;
+/** Scan a file's content with one scanner. Content is split on newlines. */
+declare function scanContent(scanner: ScannerDef, content: string): ScanResult;
+
+interface DiffOptions {
+    base: string;
+    /** When omitted, the diff is taken against the working tree. */
+    head?: string;
+    cwd: string;
+    /**
+     * Diff from the merge-base of base and head (three-dot semantics), so only
+     * lines the branch itself added are considered. Defaults to true.
+     */
+    mergeBase?: boolean;
+}
+declare class GitError extends Error {
+}
+/**
+ * Unquote a path from a `+++ b/...` header. Git C-quotes paths containing
+ * special characters; handle the common escapes and octal bytes.
+ */
+declare function unquoteGitPath(raw: string): string;
+/**
+ * Parse `git diff -U0` output into a map of file path (repo-relative posix)
+ * to the set of 1-based line numbers that the diff ADDS. With zero context
+ * every `@@ -a,b +c,d @@` hunk contributes exactly the range c..c+d-1.
+ */
+declare function parseAddedLines(diffText: string): Map<string, Set<number>>;
+/** Compute the added-line map for a base..head (or base..worktree) diff. */
+declare function getAddedLines(opts: DiffOptions): Map<string, Set<number>>;
+
+/**
+ * Whether a finding fails the build.
+ *
+ * - 'high'      only high-severity findings block
+ * - 'high+bugs' high-severity findings block, plus bug-class findings of any
+ *               severity (a swallowed error is quiet but wrong) — the default
+ * - 'medium'    high and medium block, plus bug-class findings
+ * - 'any'       every finding blocks
+ */
+declare function isBlocking(finding: Pick<Finding, 'severity' | 'class'>, failOn: FailOn): boolean;
+
+/**
+ * A small glob matcher for repo-relative posix paths. Supported syntax:
+ *
+ * - `*`   any run of characters within one path segment
+ * - `?`   one character within a segment
+ * - `**`  any number of whole segments (including zero)
+ * - `{a,b}` alternation (no nesting)
+ * - a trailing `/` matches the directory and everything under it
+ * - a pattern with no `/` matches against the basename as well as the path
+ */
+declare function globToRegExp(glob: string): RegExp;
+declare class GlobSet {
+    private readonly regexes;
+    private readonly basenames;
+    constructor(globs: string[]);
+    matches(path: string): boolean;
+    get isEmpty(): boolean;
+}
+
+declare function countBySeverity(findings: Pick<Finding, 'severity'>[]): Record<Severity, number>;
+declare function weightedScore(counts: Record<Severity, number>): number;
+/** Weighted slop score per 1,000 words; concentration is the real signal. */
+declare function densityPer1kWords(weighted: number, words: number): number;
+/** Ported per-scanner verdict logic from the upstream scanners. */
+declare function verdict(scanner: ScannerName, counts: Record<Severity, number>, weighted: number, words?: number): string;
+
+interface ConsoleReportOptions {
+    color: boolean;
+    /** Max examples printed per non-blocking rule group. */
+    maxExamples: number;
+}
+declare function renderConsoleReport(report: Report, opts: ConsoleReportOptions): string;
+
+/** Render workflow-command annotations for the findings. */
+declare function renderAnnotations(report: Report): string[];
+/** Render the markdown step summary. */
+declare function renderStepSummary(report: Report): string;
+/** Append the step summary when running inside GitHub Actions. */
+declare function writeStepSummary(report: Report): boolean;
+
+/**
+ * In GitHub Actions, work out the base ref of the event when no explicit
+ * base was given: the PR base sha for pull_request events, the merge-group
+ * base for merge queues, the pre-push sha for pushes, then the base branch
+ * name as a last resort.
+ */
+declare function resolveBaseFromEnv(env: NodeJS.ProcessEnv): string | undefined;
+
+/**
+ * Ported verbatim from unslop_code_scan.py (vibecoded-design-tells, MIT).
+ * Severity follows the verified shares from the Reddit study; the two
+ * conclusive paste-in artifacts are HIGH because when they survive into
+ * committed code they are unmistakable. Class is the orthogonal axis:
+ * "bug" means the code is wrong, "cosmetic" means chat voice leaked in.
+ * The biggest bug of all (hallucinated APIs) is structural and cannot be
+ * caught by regex — build, type-check, and run the code for that.
+ */
+declare const CODE_RULES: Rule[];
+declare const codeScanner: ScannerDef;
+
+/**
+ * Ported verbatim from unslop_text_scan.py (vibecoded-design-tells, MIT).
+ * Severity tiers follow the cited/keyword shares from the study:
+ * HIGH = the strongest cited tells, down to LOW = real but minor.
+ * All text rules are cosmetic-class: prose is never a bug.
+ */
+declare const TEXT_RULES: Rule[];
+declare const textScanner: ScannerDef;
+
+/**
+ * Ported verbatim from devibe_scan.py (vibecoded-design-tells, MIT).
+ * Severity follows how often each tell is named in the underlying study.
+ * Patterns are kept specific enough to avoid drowning the report in false
+ * positives. All UI rules are cosmetic-class.
+ */
+declare const UI_RULES: Rule[];
+declare const uiScanner: ScannerDef;
+
+export { ALL_SCANNERS, CODE_RULES, ConfigError, DEFAULT_CONFIG_FILENAME, type FailOn, type Finding, GitError, GlobSet, type Report, type Rule, type RuleClass, type RunOptions, type ScannerConfig, type ScannerDef, type ScannerName, type ScannerReport, type Severity, TEXT_RULES, UI_RULES, type UnslopConfig, codeScanner, countBySeverity, densityPer1kWords, effectiveRules, getAddedLines, globToRegExp, isBlocking, loadConfig, looksMinified, parseAddedLines, renderAnnotations, renderConsoleReport, renderStepSummary, resolveBaseFromEnv, run, scanContent, stripNoise, textScanner, uiScanner, unquoteGitPath, validateConfig, verdict, weightedScore, writeStepSummary };