@sfqa/scar 0.0.0-stage → 0.1.1

package/dist/report.d.ts

@@ -0,0 +1,23 @@
+import type { Finding, Severity, SeverityCounts } from './types.js';
+export declare const SEVERITY_ORDER: Record<Severity, number>;
+export interface Report {
+    tool: 'sfqa-scar';
+    ruleSet: string;
+    filesScanned: number;
+    summary: SeverityCounts;
+    findings: Finding[];
+}
+export declare function summarise(findings: readonly Finding[]): SeverityCounts;
+export declare function buildReport(ruleSet: string, filesScanned: number, findings: readonly Finding[]): Report;
+/** Lowest severity that fails the run. `any` means even `low` fails. */
+export type FailOn = Severity | 'any';
+export declare function shouldFail(findings: readonly Finding[], failOn?: FailOn): boolean;
+export declare function formatText(report: Report, cwd: string): string;
+export declare function formatJson(report: Report): string;
+/**
+ * Markdown for a pull-request comment or a write-up. Paths are relative to the
+ * directory the scan ran in, so the output can be pasted or screenshotted
+ * without leaking a home directory. The table is the scan; the fix list is what
+ * a reader acts on.
+ */
+export declare function formatMarkdown(report: Report): string;

package/dist/report.js

@@ -0,0 +1,137 @@
+// packages/scar/src/report.ts
+// -----------------------------------------------------------------------------
+// Reporting. Every finding is explainable: the rule that fired, the matching
+// line, the class of incident that produced the rule, and a concrete fix.
+//
+// Three formats, one source of truth: text for a human, JSON for CI or a PR
+// comment, Markdown for a pull request or a write-up. None drops a finding, and
+// none prints an absolute path except the text format - a screenshot or a pasted
+// block should never carry someone's home directory.
+// -----------------------------------------------------------------------------
+export const SEVERITY_ORDER = { high: 3, med: 2, low: 1 };
+export function summarise(findings) {
+    const counts = { high: 0, med: 0, low: 0 };
+    for (const finding of findings)
+        counts[finding.rule.severity]++;
+    return counts;
+}
+export function buildReport(ruleSet, filesScanned, findings) {
+    return {
+        tool: 'sfqa-scar',
+        ruleSet,
+        filesScanned,
+        summary: summarise(findings),
+        findings: [...findings],
+    };
+}
+export function shouldFail(findings, failOn = 'high') {
+    const threshold = failOn === 'any' ? 'low' : failOn;
+    return findings.some((finding) => SEVERITY_ORDER[finding.rule.severity] >= SEVERITY_ORDER[threshold]);
+}
+function originText(finding) {
+    const origin = finding.rule.origin;
+    const reference = origin.commit
+        ? `${origin.commit}${origin.pr ? ` (${origin.pr})` : ''}`
+        : (origin.pr ?? 'incident');
+    return `${reference}\n           ${origin.summary}`;
+}
+export function formatText(report, cwd) {
+    const lines = [];
+    lines.push(`sfqa-scar - ${report.filesScanned} file(s) reviewed`);
+    lines.push(`rule set: ${report.ruleSet}`);
+    const ordered = orderedFindings(report);
+    for (const finding of ordered) {
+        const rule = finding.rule;
+        lines.push('');
+        lines.push(`[${rule.severity.toUpperCase()}] ${rule.id} - ${rule.rule}`);
+        if (rule.severity_note)
+            lines.push(`note: ${rule.severity_note}`);
+        lines.push(`  where  : ${cwd}/${finding.relPath}${finding.line ? `:${finding.line}` : ''}`);
+        lines.push(`  matched: ${finding.snippet}${finding.meta ? `\n           (${finding.meta})` : ''}`);
+        lines.push(`  context: ${rule.context}`);
+        lines.push(`  origin : ${originText(finding)}`);
+        lines.push(`  do this: ${rule.recommendation}`);
+    }
+    const { high, med, low } = report.summary;
+    lines.push('');
+    lines.push(`summary: ${report.findings.length} finding(s) - ${high} high, ${med} med, ${low} low across ${report.filesScanned} file(s)`);
+    return lines.join('\n');
+}
+export function formatJson(report) {
+    return JSON.stringify({
+        tool: report.tool,
+        ruleSet: report.ruleSet,
+        filesScanned: report.filesScanned,
+        summary: report.summary,
+        findings: report.findings.map((finding) => ({
+            id: finding.rule.id,
+            severity: finding.rule.severity,
+            rule: finding.rule.rule,
+            file: finding.relPath,
+            line: finding.line || null,
+            matched: finding.snippet,
+            detail: finding.meta ?? null,
+            originCommit: finding.rule.origin.commit ?? null,
+            why: finding.rule.origin.summary,
+            recommendation: finding.rule.recommendation,
+        })),
+    }, null, 2);
+}
+/** Order findings worst-first, then by path and line. Shared by the formatters. */
+function orderedFindings(report) {
+    return [...report.findings].sort((a, b) => SEVERITY_ORDER[b.rule.severity] - SEVERITY_ORDER[a.rule.severity] ||
+        a.relPath.localeCompare(b.relPath) ||
+        a.line - b.line);
+}
+/**
+ * One table cell has to stay one line: newlines would end the row, and an
+ * unescaped pipe would split it into a new column.
+ */
+function cell(text, limit = 120) {
+    const flat = text.replace(/\s+/g, ' ').replace(/\|/g, '\\|').trim();
+    return flat.length > limit ? `${flat.slice(0, limit - 1)}…` : flat;
+}
+/**
+ * Markdown for a pull-request comment or a write-up. Paths are relative to the
+ * directory the scan ran in, so the output can be pasted or screenshotted
+ * without leaking a home directory. The table is the scan; the fix list is what
+ * a reader acts on.
+ */
+export function formatMarkdown(report) {
+    const lines = [];
+    const { high, med, low } = report.summary;
+    const ordered = orderedFindings(report);
+    lines.push('## sfqa-scar');
+    lines.push('');
+    if (ordered.length === 0) {
+        lines.push(`**Clean** - 0 findings across ${report.filesScanned} file(s), at every severity.`);
+        return lines.join('\n');
+    }
+    lines.push(`**${ordered.length} finding(s)** across ${report.filesScanned} file(s) - ${high} high, ${med} med, ${low} low.`);
+    lines.push('');
+    lines.push('| Rule | Severity | Where | Matched |');
+    lines.push('| --- | --- | --- | --- |');
+    for (const finding of ordered) {
+        const where = `${finding.relPath}${finding.line ? `:${finding.line}` : ''}`;
+        const matched = finding.meta ? `${finding.snippet} (${finding.meta})` : finding.snippet;
+        lines.push(`| ${finding.rule.id} | ${finding.rule.severity} | \`${cell(where, 80)}\` | \`${cell(matched)}\` |`);
+    }
+    const seen = new Set();
+    const fixes = ordered.filter((finding) => {
+        if (seen.has(finding.rule.id))
+            return false;
+        seen.add(finding.rule.id);
+        return true;
+    });
+    if (fixes.length > 0) {
+        lines.push('');
+        lines.push('### Fixes');
+        for (const finding of fixes) {
+            lines.push('');
+            lines.push(`**${finding.rule.id}** - ${cell(finding.rule.rule, 400)}`);
+            lines.push('');
+            lines.push(`> ${finding.rule.recommendation.replace(/\s+/g, ' ').trim()}`);
+        }
+    }
+    return lines.join('\n');
+}

package/dist/rules.d.ts

@@ -0,0 +1,38 @@
+import type { FileNameRule, LabelRule, NumericRule, RuleSet, ScarRule, Severity } from './types.js';
+export declare const SEVERITIES: readonly Severity[];
+export declare class RuleSetError extends Error {
+    constructor(message: string);
+}
+/**
+ * Convert a small glob (`**`, `*`, `?`) to an anchored RegExp. Deliberately
+ * tiny: a rule set should not need a dependency just to scope a file path.
+ */
+export declare function globToRegex(glob: string): RegExp;
+/**
+ * JS RegExp has no inline `(?i)`. Convention: a leading `(?i)` in a rule
+ * pattern becomes the case-insensitive flag, keeping the JSON readable and
+ * portable across engines.
+ */
+export declare function jsRegex(pattern: string, extraFlags?: string): RegExp;
+export interface CompiledRule extends ScarRule {
+    _include: RegExp[];
+    _exclude: RegExp[];
+    _line: RegExp[];
+    _numeric: Array<NumericRule & {
+        re: RegExp;
+    }>;
+    _fileName: Array<FileNameRule & {
+        re: RegExp;
+    }>;
+    _labels: LabelRule[];
+    _required: RegExp[];
+    _exempt: RegExp[];
+    _exemptLines: RegExp[];
+}
+export declare function compileRule(rule: ScarRule): CompiledRule;
+/** True when the rule has at least one machine detector. */
+export declare function isExecutable(rule: ScarRule): boolean;
+/** Validate a rule set before any file is scanned. */
+export declare function validateRuleSet(raw: unknown): RuleSet;
+export declare function loadRuleSet(path: string): RuleSet;
+export declare function compileRuleSet(ruleSet: RuleSet): CompiledRule[];

package/dist/rules.js

@@ -0,0 +1,166 @@
+// packages/scar/src/rules.ts
+// -----------------------------------------------------------------------------
+// Rule-set loading and compilation. Every detector is compiled once, up front,
+// so a malformed regex fails loudly at load time instead of silently never
+// matching a file.
+// -----------------------------------------------------------------------------
+import { readFileSync } from 'node:fs';
+export const SEVERITIES = ['high', 'med', 'low'];
+export class RuleSetError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'RuleSetError';
+    }
+}
+/**
+ * Convert a small glob (`**`, `*`, `?`) to an anchored RegExp. Deliberately
+ * tiny: a rule set should not need a dependency just to scope a file path.
+ */
+export function globToRegex(glob) {
+    let source = '';
+    for (let i = 0; i < glob.length; i++) {
+        const char = glob[i];
+        if (char === '*') {
+            if (glob[i + 1] === '*') {
+                if (glob[i + 2] === '/') {
+                    source += '(?:[^/]*/)*';
+                    i += 2;
+                }
+                else {
+                    source += '.*';
+                    i += 1;
+                }
+            }
+            else {
+                source += '[^/]*';
+            }
+        }
+        else if (char === '?') {
+            source += '[^/]';
+        }
+        else {
+            source += char.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+        }
+    }
+    return new RegExp(`^${source}$`);
+}
+/**
+ * JS RegExp has no inline `(?i)`. Convention: a leading `(?i)` in a rule
+ * pattern becomes the case-insensitive flag, keeping the JSON readable and
+ * portable across engines.
+ */
+export function jsRegex(pattern, extraFlags = '') {
+    let flags = extraFlags;
+    let source = pattern;
+    if (source.startsWith('(?i)')) {
+        flags += 'i';
+        source = source.slice(4);
+    }
+    return new RegExp(source, flags);
+}
+function compilePatterns(patterns = [], flags = '') {
+    return patterns.map((pattern) => {
+        try {
+            return jsRegex(pattern, flags);
+        }
+        catch (error) {
+            throw new RuleSetError(`invalid pattern ${JSON.stringify(pattern)}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    });
+}
+export function compileRule(rule) {
+    const match = rule.match ?? {};
+    return {
+        ...rule,
+        _include: (match.pathInclude ?? []).map(globToRegex),
+        _exclude: (match.pathExclude ?? []).map(globToRegex),
+        _line: compilePatterns(match.linePatterns),
+        _numeric: (match.numericRules ?? []).map((numeric) => ({
+            ...numeric,
+            re: jsRegex(numeric.pattern, numeric.flags ?? 'gm'),
+        })),
+        _fileName: (match.fileNameRules ?? []).map((file) => ({
+            ...file,
+            re: jsRegex(file.pattern),
+        })),
+        _labels: match.labelRules ?? [],
+        _required: compilePatterns(match.fileRequiredSignals, 'm'),
+        _exempt: compilePatterns(match.fileExemptSignals, 'm'),
+        _exemptLines: compilePatterns(match.fileExemptLines, 'm'),
+    };
+}
+/** True when the rule has at least one machine detector. */
+export function isExecutable(rule) {
+    const match = rule.match ?? {};
+    return ((match.linePatterns ?? []).length > 0 ||
+        (match.numericRules ?? []).length > 0 ||
+        (match.fileNameRules ?? []).length > 0 ||
+        (match.fileRequiredSignals ?? []).length > 0 ||
+        (match.labelRules ?? []).length > 0);
+}
+/** Validate a rule set before any file is scanned. */
+export function validateRuleSet(raw) {
+    if (!raw || typeof raw !== 'object') {
+        throw new RuleSetError('rule set must be a JSON object');
+    }
+    const candidate = raw;
+    if (!Array.isArray(candidate.rules) || candidate.rules.length === 0) {
+        throw new RuleSetError('rule set has no rules');
+    }
+    const ids = new Set();
+    for (const rule of candidate.rules) {
+        const where = rule.id ? `rule ${rule.id}` : 'rule without an id';
+        if (!rule.id || !/^[A-Z]+-\d+$/.test(rule.id)) {
+            throw new RuleSetError(`${where}: id must look like "XX-001"`);
+        }
+        if (ids.has(rule.id)) {
+            throw new RuleSetError(`duplicate rule id ${rule.id}`);
+        }
+        ids.add(rule.id);
+        if (!rule.rule?.trim())
+            throw new RuleSetError(`${where}: missing rule text`);
+        if (!rule.context?.trim())
+            throw new RuleSetError(`${where}: missing context`);
+        if (!rule.recommendation?.trim())
+            throw new RuleSetError(`${where}: missing recommendation`);
+        if (!SEVERITIES.includes(rule.severity)) {
+            throw new RuleSetError(`${where}: severity must be one of ${SEVERITIES.join(', ')}`);
+        }
+        if (!rule.origin?.summary?.trim()) {
+            throw new RuleSetError(`${where}: origin.summary is required`);
+        }
+        const match = rule.match ?? {};
+        const hasScope = (match.pathInclude ?? []).length > 0;
+        for (const labelRule of match.labelRules ?? []) {
+            if (!Array.isArray(labelRule.canonical) || labelRule.canonical.length === 0) {
+                throw new RuleSetError(`${where}: labelRules.canonical must be a non-empty array`);
+            }
+        }
+        if (!isExecutable(rule) && !hasScope) {
+            throw new RuleSetError(`${where}: rule has neither a detector nor a path scope`);
+        }
+        // Compile now: a bad regex must fail at load, not at scan time.
+        compileRule(rule);
+    }
+    return candidate;
+}
+export function loadRuleSet(path) {
+    let text;
+    try {
+        text = readFileSync(path, 'utf8');
+    }
+    catch (error) {
+        throw new RuleSetError(`cannot read rule set ${path}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch (error) {
+        throw new RuleSetError(`rule set ${path} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    return validateRuleSet(raw);
+}
+export function compileRuleSet(ruleSet) {
+    return ruleSet.rules.map(compileRule);
+}

package/dist/scan.d.ts

@@ -0,0 +1,38 @@
+import type { CompiledRule } from './rules.js';
+import type { Finding } from './types.js';
+export declare const SKIP_DIRS: Set<string>;
+/** Normalise to forward slashes so globs behave the same on every platform. */
+export declare function toPosix(path: string): string;
+export declare function relPosix(root: string, path: string): string;
+export declare function walk(dir: string, output?: string[]): string[];
+/** Expand CLI path arguments into absolute file paths. */
+export declare function collectFiles(targets: readonly string[], cwd: string): string[];
+export declare function gitChangedFiles(cwd: string, baseRef?: string | null, staged?: boolean): string[];
+/** True when the path is covered by .gitignore (exit 0 from git check-ignore). */
+export declare function isGitIgnored(cwd: string, relPath: string): boolean;
+/**
+ * The same answer for many paths in one process.
+ *
+ * `isGitIgnored` spawns git per path. On a 1,400-file repository that is the
+ * entire runtime of a scan; batching takes it from ~30s to well under a second.
+ * Paths are fed NUL-separated so a space or a newline in a filename cannot
+ * split the input.
+ */
+export declare function gitIgnoredSet(cwd: string, relPaths: readonly string[]): Set<string>;
+export interface LintOptions {
+    maxPerRule?: number;
+    /** Findings in gitignored files are informational (downgraded to low). */
+    ignored?: boolean;
+}
+export declare function lintContent(relPath: string, content: string, rules: readonly CompiledRule[], options?: LintOptions): Finding[];
+export interface ScanResult {
+    filesScanned: number;
+    findings: Finding[];
+}
+export interface ScanOptions {
+    maxPerRule?: number;
+    /** Injectable for tests; defaults to `git check-ignore`. */
+    isIgnored?: (relPath: string) => boolean;
+}
+/** Read and lint every file, skipping binaries, huge files and ignored dirs. */
+export declare function scanFiles(cwd: string, files: readonly string[], rules: readonly CompiledRule[], options?: ScanOptions): ScanResult;