@sfqa/scar 0.0.0-stage → 0.1.0

package/dist/scan.js

@@ -0,0 +1,404 @@
+// packages/scar/src/scan.ts
+// -----------------------------------------------------------------------------
+// File discovery and detection. The scanner is intentionally boring: it reads
+// text, applies declarative detectors, and reports where each one fired.
+//
+// Two exemption scopes, both deliberate:
+//   - fileExemptSignals: a mitigation anywhere in the file clears the file
+//     (e.g. a Promise.race guarding a toast wait)
+//   - fileExemptLines: one line is individually safe (e.g. an empty env
+//     fallback); sibling hardcoded literals in the same file still fire
+// -----------------------------------------------------------------------------
+import { execFileSync } from 'node:child_process';
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { basename, extname, join, relative, resolve, sep } from 'node:path';
+export const SKIP_DIRS = new Set([
+    'node_modules',
+    '.git',
+    '.features-gen',
+    'test-results',
+    'test-results1',
+    'test-artifacts',
+    'allure-results',
+    'playwright-report',
+    'html-report',
+    '.local',
+]);
+const MAX_BYTES = 1_000_000;
+const BINARY_EXT = new Set([
+    '.png',
+    '.jpg',
+    '.jpeg',
+    '.gif',
+    '.zip',
+    '.xlsx',
+    '.pdf',
+    '.ico',
+    '.woff',
+    '.woff2',
+    '.ttf',
+    '.mp4',
+    '.webm',
+]);
+/** Normalise to forward slashes so globs behave the same on every platform. */
+export function toPosix(path) {
+    return path.split(sep).join('/');
+}
+export function relPosix(root, path) {
+    return toPosix(relative(root, path));
+}
+export function walk(dir, output = []) {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        if (entry.isDirectory()) {
+            if (!SKIP_DIRS.has(entry.name))
+                walk(join(dir, entry.name), output);
+        }
+        else if (entry.isFile()) {
+            output.push(join(dir, entry.name));
+        }
+    }
+    return output;
+}
+/** Expand CLI path arguments into absolute file paths. */
+export function collectFiles(targets, cwd) {
+    const files = [];
+    for (const target of targets) {
+        const absolute = resolve(cwd, target);
+        let stat;
+        try {
+            stat = statSync(absolute);
+        }
+        catch {
+            continue;
+        }
+        if (stat.isDirectory())
+            files.push(...walk(absolute));
+        else if (stat.isFile())
+            files.push(absolute);
+    }
+    return files;
+}
+export function gitChangedFiles(cwd, baseRef, staged = false) {
+    const args = ['diff', '--name-only', '--relative'];
+    if (staged)
+        args.push('--cached');
+    else if (baseRef)
+        args.push(baseRef);
+    const output = execFileSync('git', args, { cwd, encoding: 'utf8' });
+    return output
+        .split('\n')
+        .map((line) => line.trim())
+        .filter(Boolean);
+}
+/** True when the path is covered by .gitignore (exit 0 from git check-ignore). */
+export function isGitIgnored(cwd, relPath) {
+    try {
+        execFileSync('git', ['check-ignore', '-q', relPath], { cwd, stdio: 'ignore' });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * 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 function gitIgnoredSet(cwd, relPaths) {
+    const result = new Set();
+    if (relPaths.length === 0)
+        return result;
+    let stdout;
+    try {
+        stdout = execFileSync('git', ['check-ignore', '--stdin', '-z'], {
+            cwd,
+            input: `${relPaths.join('\0')}\0`,
+            encoding: 'utf8',
+            stdio: ['pipe', 'pipe', 'ignore'],
+        });
+    }
+    catch (error) {
+        // Exit 1 means "none of these are ignored", which is not an error.
+        const output = error.stdout ?? '';
+        if (!output)
+            return result;
+        stdout = output;
+    }
+    for (const entry of stdout.split('\0'))
+        if (entry)
+            result.add(entry);
+    return result;
+}
+function isComment(line) {
+    const trimmed = line.trimStart();
+    return (trimmed.startsWith('//') ||
+        trimmed.startsWith('/*') ||
+        trimmed.startsWith('*') ||
+        (trimmed.startsWith('#') && !trimmed.startsWith('#!')));
+}
+function lineOf(content, index) {
+    return content.slice(0, index).split('\n').length;
+}
+/**
+ * A line pattern is matched against the line plus the next three lines, but a
+ * finding is only reported when the match starts on this line. That is how a
+ * guard written on the following line - `.isVisible({ timeout: 5000 })` then
+ * `.catch(() => false)` - reads as a deliberate probe instead of a silent
+ * assertion, without teaching the rule about JavaScript.
+ */
+function matchesOnLine(re, lines, index) {
+    const line = lines[index];
+    const match = re.exec(lines.slice(index, index + 4).join('\n'));
+    return match !== null && match.index < line.length;
+}
+function isExemptLine(rule, line) {
+    return rule._exemptLines.length > 0 && rule._exemptLines.some((re) => re.test(line));
+}
+function spansLines(re) {
+    return /\[\\s\\S\]|\\n/.test(re.source);
+}
+function quotedLiterals(content) {
+    const literals = [];
+    const pattern = /(['"])([^'"\n]{2,})\1/g;
+    let match;
+    while ((match = pattern.exec(content)) !== null) {
+        const start = match.index;
+        const end = start + match[0].length;
+        literals.push({
+            value: match[2],
+            line: lineOf(content, start),
+            before: content.slice(Math.max(0, start - 1), start),
+            prefix: content.slice(Math.max(0, start - 4), start),
+            after: content.slice(end, end + 1),
+        });
+    }
+    return literals;
+}
+/**
+ * Not every quoted string is a picklist label. Three shapes produced false
+ * positives in the repository this rule was mined from, and all three are code,
+ * not labels:
+ *
+ *   'input[name="FirstName"]'  - a value inside an attribute selector
+ *   'Email': 'email'           - an object key, and its value
+ *   cond ? 'email' : 'name'    - the branches of a ternary
+ *   'First Name': 'firstName'  - a camelCase identifier
+ *
+ * A lowercase single word is kept: `['web']` where the canonical value is `Web`
+ * is exactly the drift this rule exists to catch, and there is no way to tell it
+ * from a lowercase value without the surrounding type information.
+ */
+function looksLikeLabel(literal) {
+    if (literal.after === ':')
+        return false;
+    // `[` is an array, so only the attribute-operator characters count here.
+    if (/[=~|^$*]/.test(literal.before))
+        return false;
+    // A value after a colon or a question mark is a map value or a ternary
+    // branch, not a label. `['web', 'Event']` is untouched - an array element is
+    // exactly where a drifted picklist value lives.
+    if (/[?:]\s*$/.test(literal.prefix))
+        return false;
+    if (/^[a-z][A-Za-z0-9]*[A-Z]/.test(literal.value))
+        return false;
+    return true;
+}
+function normaliseLabel(value) {
+    return value.toLowerCase().replace(/[\s_-]+/g, '');
+}
+/**
+ * Label drift: a quoted literal that is the same label as a canonical one but
+ * differs in case, spacing or hyphenation. This is the generic form of "copy
+ * the picklist label verbatim" - the canonical list is supplied by the org.
+ */
+function labelFindings(rule, content, lines, relPath, severity, maxPerRule, ignored) {
+    const findings = [];
+    if (rule._labels.length === 0)
+        return findings;
+    const flush = (value, line, canonical, kind) => {
+        const lineText = lines[line - 1] ?? '';
+        if (isComment(lineText) || isExemptLine(rule, lineText))
+            return;
+        findings.push({
+            rule: { ...rule, severity },
+            relPath,
+            line,
+            snippet: `${lineText.trim().slice(0, 140)}${ignored ? ' [gitignored - informational]' : ''}`,
+            meta: `${kind}: "${value}" should be "${canonical}"`,
+        });
+    };
+    const literals = quotedLiterals(content);
+    outer: for (const labelRule of rule._labels) {
+        for (const canonical of labelRule.canonical) {
+            for (const literal of literals) {
+                if (findings.length >= maxPerRule)
+                    break outer;
+                if (!looksLikeLabel(literal))
+                    continue;
+                if (literal.value === canonical)
+                    continue;
+                if (literal.value.toLowerCase() === canonical.toLowerCase()) {
+                    flush(literal.value, literal.line, canonical, 'case drift');
+                    break;
+                }
+                if (normaliseLabel(literal.value) === normaliseLabel(canonical)) {
+                    flush(literal.value, literal.line, canonical, 'spacing/hyphen drift');
+                    break;
+                }
+            }
+        }
+    }
+    return findings;
+}
+export function lintContent(relPath, content, rules, options = {}) {
+    const maxPerRule = options.maxPerRule ?? 5;
+    const ignored = options.ignored ?? false;
+    const findings = [];
+    const file = basename(relPath);
+    const lines = content.split('\n');
+    for (const rule of rules) {
+        const gated = rule._include.length > 0 && !rule._include.some((re) => re.test(relPath));
+        if (gated || rule._exclude.some((re) => re.test(relPath)))
+            continue;
+        const severity = ignored ? 'low' : rule.severity;
+        // Filename-based rules (e.g. a tracked .env file).
+        for (const fileNameRule of rule._fileName) {
+            if (fileNameRule.re.test(file)) {
+                findings.push({
+                    rule: { ...rule, severity },
+                    relPath,
+                    line: 0,
+                    snippet: `(file name "${file}" matched /${fileNameRule.re.source}/)${ignored ? ' [gitignored - informational]' : ''}`,
+                });
+            }
+        }
+        const fileExempt = rule._exempt.length > 0 && rule._exempt.some((re) => re.test(content));
+        // Per-line patterns. A pattern containing [\s\S] or \n is written to span
+        // lines, so it can never match inside one line; split those out and scan
+        // them against the whole content, mapping each match back to its line.
+        if (rule._line.length > 0 && !fileExempt) {
+            const singleLine = rule._line.filter((re) => !spansLines(re));
+            const multiLine = rule._line.filter(spansLines);
+            let hits = 0;
+            for (let i = 0; i < lines.length && hits < maxPerRule; i++) {
+                if (isComment(lines[i]) || isExemptLine(rule, lines[i]))
+                    continue;
+                if (singleLine.some((re) => matchesOnLine(re, lines, i))) {
+                    findings.push({
+                        rule: { ...rule, severity },
+                        relPath,
+                        line: i + 1,
+                        snippet: `${lines[i].trim().slice(0, 160)}${ignored ? ' [gitignored - informational]' : ''}`,
+                    });
+                    hits++;
+                }
+            }
+            for (const re of multiLine) {
+                if (hits >= maxPerRule)
+                    break;
+                const global = new RegExp(re.source, re.flags.includes('g') ? re.flags : `${re.flags}g`);
+                let match;
+                while ((match = global.exec(content)) !== null && hits < maxPerRule) {
+                    const line = lineOf(content, match.index);
+                    const lineText = lines[line - 1] ?? '';
+                    if (!isComment(lineText) && !isExemptLine(rule, lineText)) {
+                        findings.push({
+                            rule: { ...rule, severity },
+                            relPath,
+                            line,
+                            snippet: `${match[0].trim().slice(0, 160)}${ignored ? ' [gitignored - informational]' : ''}`,
+                        });
+                        hits++;
+                    }
+                    if (match.index === global.lastIndex)
+                        global.lastIndex++;
+                }
+            }
+        }
+        // Numeric-range rules: capture group 1 must fall in [min, max].
+        if (!fileExempt) {
+            for (const numeric of rule._numeric) {
+                numeric.re.lastIndex = 0;
+                let hits = findings.filter((finding) => finding.rule.id === rule.id).length;
+                let match;
+                while ((match = numeric.re.exec(content)) !== null && hits < maxPerRule) {
+                    const value = Number(match[1]);
+                    if (Number.isFinite(value) && value >= numeric.min && value <= numeric.max) {
+                        const lineStart = content.lastIndexOf('\n', match.index) + 1;
+                        const lineText = content.slice(lineStart, match.index + match[0].length + 40);
+                        if (isComment(lineText) || isExemptLine(rule, lineText))
+                            continue;
+                        findings.push({
+                            rule: { ...rule, severity },
+                            relPath,
+                            line: lineOf(content, match.index),
+                            snippet: match[0].trim().slice(0, 160),
+                            meta: `value ${value} outside safe range (${numeric.min}-${numeric.max})`,
+                        });
+                        hits++;
+                    }
+                }
+            }
+        }
+        // Label drift: exact display labels supplied by the org.
+        if (!fileExempt) {
+            findings.push(...labelFindings(rule, content, lines, relPath, severity, maxPerRule, ignored));
+        }
+        // Required-signal rules: fire once when NO required signal exists.
+        if (!fileExempt &&
+            rule._required.length > 0 &&
+            !rule._required.some((re) => re.test(content))) {
+            findings.push({
+                rule: { ...rule, severity },
+                relPath,
+                line: 0,
+                snippet: `(file passed rule scope but contains none of: ${(rule.match.fileRequiredSignals ?? []).join(', ')})`,
+            });
+        }
+    }
+    return findings;
+}
+/** Read and lint every file, skipping binaries, huge files and ignored dirs. */
+export function scanFiles(cwd, files, rules, options = {}) {
+    const findings = [];
+    let filesScanned = 0;
+    // Lint first, ask git only about files that actually matched something. The
+    // ignore ledger is cosmetic (it downgrades a finding and marks it), so paying
+    // for it on 1,400 clean files was pure waste.
+    const matched = [];
+    for (const absolute of files) {
+        const rel = relPosix(cwd, absolute);
+        if (SKIP_DIRS.has(rel.split('/')[0]))
+            continue;
+        if (BINARY_EXT.has(extname(absolute)))
+            continue;
+        let stat;
+        try {
+            stat = statSync(absolute);
+        }
+        catch {
+            continue;
+        }
+        if (stat.size > MAX_BYTES)
+            continue;
+        const content = readFileSync(absolute, 'utf8');
+        filesScanned++;
+        if (lintContent(rel, content, rules, { maxPerRule: options.maxPerRule }).length > 0) {
+            matched.push({ rel, content });
+        }
+    }
+    const ignored = options.isIgnored
+        ? new Set(matched.filter((entry) => options.isIgnored?.(entry.rel)).map((entry) => entry.rel))
+        : gitIgnoredSet(cwd, matched.map((entry) => entry.rel));
+    for (const entry of matched) {
+        findings.push(...lintContent(entry.rel, entry.content, rules, {
+            maxPerRule: options.maxPerRule,
+            ignored: ignored.has(entry.rel),
+        }));
+    }
+    return { filesScanned, findings };
+}

package/dist/types.d.ts

@@ -0,0 +1,77 @@
+export type Severity = 'high' | 'med' | 'low';
+export interface RuleOrigin {
+    /** Optional commit or PR in the adopting repository. */
+    commit?: string | null;
+    pr?: string | null;
+    /** What class of incident produced the rule. Never client data. */
+    summary: string;
+}
+export interface FileNameRule {
+    /** Regex tested against the file's base name (e.g. `^\.env$`). */
+    pattern: string;
+}
+export interface NumericRule {
+    pattern: string;
+    flags?: string;
+    /** Capture group 1 must fall in [min, max] for the rule to fire. */
+    min: number;
+    max: number;
+}
+export interface LabelRule {
+    /**
+     * Canonical display labels, exactly as the org renders them. A quoted
+     * literal that matches one of these case-insensitively, or after removing
+     * spaces and hyphens, is drift and fires the rule.
+     */
+    canonical: string[];
+}
+export interface RuleMatch {
+    pathInclude?: string[];
+    pathExclude?: string[];
+    /**
+     * Matched against the line plus the next three lines, and reported only when
+     * the match starts on that line. A guard written on the following line -
+     * `.isVisible({ timeout: 5000 })` then `.catch(() => false)` - therefore reads
+     * as a deliberate probe, not a finding.
+     */
+    linePatterns?: string[];
+    numericRules?: NumericRule[];
+    fileNameRules?: FileNameRule[];
+    /** Fire when NONE of these are present anywhere in the file. */
+    fileRequiredSignals?: string[];
+    /** Clear the whole file when ANY of these are present. */
+    fileExemptSignals?: string[];
+    /** Clear a single line when ANY of these match it. */
+    fileExemptLines?: string[];
+    labelRules?: LabelRule[];
+}
+export interface ScarRule {
+    id: string;
+    rule: string;
+    context: string;
+    origin: RuleOrigin;
+    severity: Severity;
+    detection_pattern: string;
+    match: RuleMatch;
+    recommendation: string;
+    severity_note?: string;
+}
+export interface RuleSet {
+    version: number;
+    description?: string;
+    generated_from_repo?: string;
+    rules: ScarRule[];
+}
+export interface Finding {
+    rule: ScarRule;
+    relPath: string;
+    /** 1-based; 0 means the finding is about the file itself. */
+    line: number;
+    snippet: string;
+    meta?: string;
+}
+export interface SeverityCounts {
+    high: number;
+    med: number;
+    low: number;
+}

package/dist/types.js

@@ -0,0 +1,11 @@
+// packages/scar/src/types.ts
+// -----------------------------------------------------------------------------
+// The rule-set contract. A rule is data, not code: the detector is a small,
+// declarative object so a team can regenerate the rule set from their own git
+// history without touching this package.
+//
+// Nothing in here names an org, a user, a label or a project. The shipped
+// `rules/generic.json` is a template: its example value lists are meant to be
+// replaced with the org's own canonical labels.
+// -----------------------------------------------------------------------------
+export {};

package/package.json

@@ -1,6 +1,61 @@
 {
   "name": "@sfqa/scar",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Review code against a Salesforce test suite's scar tissue: past failures, encoded as declarative rules.",
+  "license": "MIT",
+  "author": "Vaishali Desarda",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/desardavaishali/sfqa-scar.git",
+    "directory": "packages/scar"
+  },
+  "bugs": {
+    "url": "https://github.com/desardavaishali/sfqa-scar/issues"
+  },
+  "homepage": "https://github.com/desardavaishali/sfqa-scar#readme",
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "sfqa-scar": "./dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./rules/generic.json": "./rules/generic.json",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "rules",
+    "prompts",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "test": "tsx --test test/scar.test.ts test/harvest.test.ts",
+    "typecheck": "tsc -p tsconfig.json",
+    "verify": "node scripts/verify.mjs",
+    "validate:scar": "node ../../scar-validation/run.mjs"
+  },
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "salesforce",
+    "scar-tissue",
+    "code-review",
+    "lint",
+    "testing",
+    "qa",
+    "playwright"
+  ]
+}

package/prompts/extract-rules.md

@@ -0,0 +1,80 @@
+# Extract your own scar tissue
+
+A reusable prompt for any capable LLM agent that can read your repository's git
+history. It produces a rule set compatible with `@sfqa/scar`.
+
+Run it once per repository, review the output (every rule should cite a commit
+you can verify), keep the JSON next to your code, and re-run it after every
+postmortem or hotfix so the rule set grows with the team.
+
+---
+
+PROMPT (copy everything below this line):
+
+You are mining a git repository for "scar tissue": hard-won rules derived from
+real past failures - bugs, flaky tests, reverts, hotfixes, leaked secrets, data
+corruption incidents.
+
+1. Explore history exhaustively:
+   - `git log --oneline --all`, then read every commit whose message contains
+     fix, revert, hotfix, flaky, race, timeout, workaround, credentials,
+     rollback.
+   - For each candidate, read the diff (`git show <hash>`) and any linked PR
+     description, ADR or postmortem doc.
+2. Extract only lessons with DIRECT evidence in a specific commit or incident
+   doc. Do not invent generic best practices; if you cannot cite a hash, drop
+   the lesson.
+3. For each lesson emit ONE JSON object with exactly these keys:
+
+   - `"id"`: stable slug matching `^[A-Z]+-\d+$`, e.g. `"ST-013"`.
+   - `"rule"`: one-line guardrail (what future automation must or must not do).
+   - `"context"`: which objects, flows, files or classes it applies to.
+   - `"origin"`: `{ "commit": "<hash>", "pr": "<id or null>",
+     "summary": "1-2 sentences on what went wrong and the cost" }`.
+   - `"severity"`: `"high" | "med" | "low"` - how bad is violating it today
+     (data corruption / leaked secrets / wrong records = high;
+     flaky-but-recovers = med; cosmetic = low).
+   - `"detection_pattern"`: what a reviewer should look for in new code to
+     catch a repeat - be concrete about syntax, not vibes.
+   - `"match"`: the machine-executable detector:
+     {
+       "pathInclude": ["glob", ...],        // optional scope gate
+       "pathExclude": ["glob", ...],        // optional
+       "fileNameRules": [{ "pattern": "regex" }],        // optional
+       "linePatterns": ["regex", ...],      // per-line (use [\s\S] to span lines)
+       "numericRules": [{ "pattern": "regex-with-(group)", "min": n, "max": m, "flags": "gm" }],
+       "labelRules": [{ "canonical": ["Exact Label", ...] }], // exact-label drift
+       "fileRequiredSignals": ["regex", ...], // fire if NONE present
+       "fileExemptSignals": ["regex", ...],   // suppress the file if ANY present
+       "fileExemptLines": ["regex", ...]      // suppress a single line if ANY present
+     }
+     Regexes are JavaScript RegExp source. A leading `(?i)` means
+     case-insensitive. Prefer few high-precision patterns over many noisy ones;
+     use `pathInclude` to scope rules to where the failure class lives.
+   - `"recommendation"`: a concrete fix, ideally describing how the origin
+     commit solved it.
+
+4. Output: a single JSON document
+   `{ "version": 1, "generated_from_repo": "<name>", "rules": [ ... ] }`.
+5. Self-check before finishing:
+   - Every rule's origin commit exists (`git cat-file -e <hash>^{commit}`).
+   - Each regex compiles against JavaScript `RegExp`.
+   - No regex or prose contains a real secret, customer value, person's name or
+     client-specific label. Labels belong in `labelRules.canonical`, not in a
+     hardcoded "known-bad" blocklist.
+   - Every `labelRules.canonical` list contains the org's exact rendered labels.
+   - At least one rule is a documented gap if you cannot write a detector; do
+     not invent one that can never fire.
+   - Rules that scope paths use globs the scanner supports (`**`, `*`, `?`).
+
+---
+
+## Reviewing the output
+
+- Run the packaged proof harness shape against your own rule set: a fixture per
+  executable rule must make it fire, and a clean fixture set must produce zero
+  findings. If a rule has a detector it cannot fire, the proof failed.
+- Delete any rule whose origin you cannot defend. A rule set is a claim about
+  your history, not a style guide.
+- Re-run extraction after a major incident. Rules that stop mattering should be
+  removed, not left as noise.