samey-cli 0.0.0-stage → 0.1.0

package/dist/rules/normalize.js

@@ -0,0 +1,114 @@
+import { createHash } from 'node:crypto';
+import path from 'node:path';
+const SEVERITIES = new Set(['critical', 'high', 'medium', 'low', 'info']);
+const MAX_EVIDENCE = 24;
+/** Common credential shapes. Matches are replaced before anything reaches a report. */
+const SECRET_PATTERNS = [
+    /\b(?:sk|pk|rk)[-_](?:live|test|proj|ant)?[-_]?[A-Za-z0-9_-]{16,}\b/g, // Stripe, OpenAI, Anthropic style
+    /\bgh[pousr]_[A-Za-z0-9]{30,}\b/g, // GitHub
+    /\bAKIA[0-9A-Z]{16}\b/g, // AWS access key id
+    /\bxox[abprs]-[A-Za-z0-9-]{10,}\b/g, // Slack
+    /\bAIza[0-9A-Za-z_-]{35}\b/g, // Google API key
+    /\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b/g, // JWT
+    /-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?(?:-----END [A-Z ]*PRIVATE KEY-----|$)/g,
+    /((?:api[_-]?key|secret|token|password|passwd|auth|bearer)["']?\s*[:=]\s*["']?)[^\s"'`,;]{8,}/gi,
+];
+export function redact(text) {
+    let out = text;
+    for (const re of SECRET_PATTERNS)
+        out = out.replace(re, (m, prefix) => (typeof prefix === 'string' && m.startsWith(prefix) ? `${prefix}[redacted]` : '[redacted]'));
+    return out;
+}
+/** A source path is kept only if it is relative, inside the project, and in the scanned file set. */
+export function safeSourcePath(file, known) {
+    if (!file || path.isAbsolute(file) || /^[a-zA-Z]:/.test(file))
+        return undefined;
+    const norm = path.posix.normalize(file.replace(/\\/g, '/'));
+    if (norm.startsWith('../') || norm === '..' || norm.includes('\0'))
+        return undefined;
+    if (known && !known.has(norm))
+        return undefined;
+    return norm;
+}
+function evidenceIdentity(e) {
+    return [e.type, e.viewport ?? '', e.selector ?? '', e.file ?? '', e.line ?? '', e.excerpt ?? '', e.detail ?? ''].join('|');
+}
+/**
+ * Identical evidence on several routes (the same footer link on every page) is one problem
+ * in one shared component. Keep the first occurrence and list the other routes.
+ */
+export function collapseEvidence(evidence) {
+    const byKey = new Map();
+    for (const e of evidence) {
+        const key = evidenceIdentity(e);
+        const prev = byKey.get(key);
+        if (!prev)
+            byKey.set(key, { ...e });
+        else if (e.route && e.route !== prev.route)
+            prev.alsoOn = [...new Set([...(prev.alsoOn ?? []), e.route])];
+    }
+    return [...byKey.values()];
+}
+/** Stable hash of rule identity and evidence identity, independent of routes and order. */
+export function fingerprint(ruleId, evidence) {
+    const keys = [...new Set(evidence.map(evidenceIdentity))].sort();
+    return createHash('sha256').update(`${ruleId}\n${keys.join('\n')}`).digest('hex').slice(0, 16);
+}
+export function validateDraft(d) {
+    if (typeof d.confidence !== 'number' || !Number.isFinite(d.confidence) || d.confidence < 0 || d.confidence > 1) {
+        throw new RangeError(`Rule ${d.ruleId} produced confidence ${d.confidence}; it must be a number from 0 to 1.`);
+    }
+    if (!SEVERITIES.has(d.severity))
+        throw new RangeError(`Rule ${d.ruleId} produced unknown severity ${d.severity}.`);
+    if (!d.ruleId || !d.description)
+        throw new RangeError('Findings need a rule id and a description.');
+}
+function sanitizeEvidence(e, knownFiles) {
+    const out = { ...e };
+    if (out.file !== undefined) {
+        const safe = safeSourcePath(out.file, knownFiles);
+        if (safe)
+            out.file = safe;
+        else {
+            delete out.file;
+            delete out.line;
+        }
+    }
+    if (out.line !== undefined && (!Number.isInteger(out.line) || out.line < 1))
+        delete out.line;
+    if (out.excerpt)
+        out.excerpt = redact(out.excerpt).slice(0, 400);
+    if (out.detail)
+        out.detail = redact(out.detail).slice(0, 400);
+    return out;
+}
+const SEV_RANK = { info: 0, low: 1, medium: 2, high: 3, critical: 4 };
+/**
+ * Validates drafts, cleans evidence, assigns fingerprints and ids, and merges findings that
+ * share a fingerprint (same rule, same evidence), keeping the higher severity and confidence.
+ */
+export function normalizeFindings(drafts, knownFiles) {
+    const byFp = new Map();
+    for (const d of drafts) {
+        validateDraft(d);
+        const evidence = collapseEvidence(d.evidence.map((e) => sanitizeEvidence(e, knownFiles)));
+        const fp = fingerprint(d.ruleId, evidence);
+        const existing = byFp.get(fp);
+        if (existing) {
+            if (SEV_RANK[d.severity] > SEV_RANK[existing.severity])
+                existing.severity = d.severity;
+            existing.confidence = Math.max(existing.confidence, d.confidence);
+            existing.routes = [...new Set([...(existing.routes ?? []), ...(d.routes ?? [])])];
+            existing.evidence = collapseEvidence([...existing.evidence, ...evidence]).slice(0, MAX_EVIDENCE);
+            continue;
+        }
+        byFp.set(fp, {
+            ...d,
+            description: redact(d.description),
+            evidence: evidence.slice(0, MAX_EVIDENCE),
+            fingerprint: fp,
+            id: `${d.ruleId}-${fp.slice(0, 8)}`,
+        });
+    }
+    return [...byFp.values()];
+}

package/dist/rules/static.d.ts

@@ -0,0 +1,9 @@
+import type { Rule } from './types.js';
+export declare const srcStockGradient: Rule;
+export declare const srcGlow: Rule;
+export declare const srcEmoji: Rule;
+export declare const srcPlaceholder: Rule;
+export declare const srcStockCopy: Rule;
+export declare const arbitraryValues: Rule;
+export declare const duplicatedMarkup: Rule;
+export declare const staticRules: Rule[];

package/dist/rules/static.js

@@ -0,0 +1,314 @@
+import { createHash } from 'node:crypto';
+import { isStockGradient } from '../util/color.js';
+import { findPlaceholders, findStockPhrases, firstEmoji, hasEmoji, truncate } from '../util/text.js';
+import { plural } from './helpers.js';
+const MARKUP = new Set(['.html', '.htm', '.jsx', '.tsx', '.vue', '.svelte', '.astro', '.mdx']);
+const STYLE = new Set(['.css', '.scss', '.sass', '.less']);
+function* lines(f) {
+    const arr = f.content.split('\n');
+    for (let i = 0; i < arr.length; i++)
+        yield { text: arr[i], line: i + 1 };
+}
+function src(f, line, text, detail) {
+    return { type: 'source', file: f.path, line, excerpt: truncate(text.trim(), 160), detail };
+}
+const isComment = (t) => /^\s*(?:\/\/|\/\*|\*|<!--|\{\s*\/\*)/.test(t);
+/** Text that appears between tags or in string literals; skips attribute names like placeholder= and className=. */
+function visibleTextish(line) {
+    return line
+        .replace(/\b(?:className|class|placeholder|alt|href|src|id|key|style|aria-[\w-]+|data-[\w-]+|type|name|for|htmlFor)\s*=\s*(?:"[^"]*"|'[^']*'|\{[^}]*\})/g, ' ')
+        .replace(/\bimport\b.*$/, ' ');
+}
+const TW_GRADIENT = /\bbg-(?:gradient|linear)-to-[trbl]{1,2}\b|\bbg-(?:radial|conic)\b/;
+const TW_SYNTH_STOP = /\b(?:from|via|to)-(?:indigo|violet|purple|fuchsia|pink)-\d{2,3}\b/;
+const TW_TEXT_GRADIENT = /\bbg-clip-text\b.*\btext-transparent\b|\btext-transparent\b.*\bbg-clip-text\b/;
+export const srcStockGradient = {
+    id: 'src-stock-gradient',
+    title: 'Stock gradients in source',
+    category: 'visual',
+    needs: 'static',
+    verified: false,
+    mergeInto: 'stock-gradient',
+    description: 'Tailwind gradient utilities and CSS gradients using the indigo/violet/pink band.',
+    run({ repo }) {
+        const ev = [];
+        for (const f of repo?.files ?? []) {
+            for (const { text, line } of lines(f)) {
+                if (isComment(text))
+                    continue;
+                if (MARKUP.has(f.ext) || f.ext === '.js' || f.ext === '.ts') {
+                    if (TW_GRADIENT.test(text) && TW_SYNTH_STOP.test(text))
+                        ev.push(src(f, line, text, TW_TEXT_GRADIENT.test(text) ? 'gradient text' : 'gradient'));
+                    else if (TW_TEXT_GRADIENT.test(text) && TW_SYNTH_STOP.test(text))
+                        ev.push(src(f, line, text, 'gradient text'));
+                }
+                if ((STYLE.has(f.ext) || MARKUP.has(f.ext)) && /gradient\(/.test(text) && isStockGradient(text))
+                    ev.push(src(f, line, text, 'css gradient'));
+            }
+        }
+        if (!ev.length)
+            return [];
+        return [
+            {
+                severity: ev.length >= 4 ? 'medium' : 'low',
+                confidence: 0.6,
+                description: `${plural(ev.length, 'line')} in source define blue-violet-pink gradients.`,
+                recommendation: 'Replace stock gradient utilities with brand color tokens. Prefer solid fills; use gradients only where they carry meaning.',
+                evidence: ev,
+            },
+        ];
+    },
+};
+export const srcGlow = {
+    id: 'src-glow-effects',
+    title: 'Glow and glass utilities in source',
+    category: 'visual',
+    needs: 'static',
+    verified: false,
+    mergeInto: 'glow-effects',
+    description: 'backdrop-blur, large blur blobs, and colored shadows in source.',
+    run({ repo }) {
+        const ev = [];
+        for (const f of repo?.files ?? []) {
+            if (!MARKUP.has(f.ext) && !STYLE.has(f.ext))
+                continue;
+            for (const { text, line } of lines(f)) {
+                if (isComment(text))
+                    continue;
+                if (/\bblur-(?:2xl|3xl|\[\d{2,}px\])\b/.test(text))
+                    ev.push(src(f, line, text, 'blur blob'));
+                else if (/\bshadow-(?:indigo|violet|purple|fuchsia|pink|blue|cyan)-\d{2,3}(?:\/\d+)?\b|shadow-\[0_0_\d{2,}px/.test(text))
+                    ev.push(src(f, line, text, 'colored glow'));
+                else if (/\bbackdrop-blur(?:-\w+)?\b|backdrop-filter:\s*blur/.test(text))
+                    ev.push(src(f, line, text, 'glass panel'));
+            }
+        }
+        if (ev.length < 3)
+            return [];
+        return [
+            {
+                severity: ev.length >= 8 ? 'medium' : 'low',
+                confidence: 0.6,
+                description: `${plural(ev.length, 'line')} in source add glows, blur blobs, or glass panels.`,
+                recommendation: 'Remove decorative blur and glow utilities; keep neutral, systematic elevation.',
+                evidence: ev,
+            },
+        ];
+    },
+};
+export const srcEmoji = {
+    id: 'src-emoji-icons',
+    title: 'Emoji in component markup',
+    category: 'visual',
+    needs: 'static',
+    verified: false,
+    mergeInto: 'emoji-icons',
+    description: 'Emoji characters in markup and component files.',
+    run({ repo }) {
+        const ev = [];
+        for (const f of repo?.files ?? []) {
+            if (!MARKUP.has(f.ext) && f.ext !== '.ts' && f.ext !== '.js')
+                continue;
+            for (const { text, line } of lines(f)) {
+                if (isComment(text) || !hasEmoji(text))
+                    continue;
+                if (/console\.(?:log|warn|error)/.test(text))
+                    continue;
+                ev.push(src(f, line, text, `emoji ${firstEmoji(text)}`));
+            }
+        }
+        if (ev.length < 2)
+            return [];
+        return [
+            {
+                severity: ev.length >= 5 ? 'medium' : 'low',
+                confidence: 0.6,
+                description: `${plural(ev.length, 'line')} of markup or content data contain emoji.`,
+                recommendation: 'Use a consistent SVG icon set instead of emoji.',
+                evidence: ev,
+            },
+        ];
+    },
+};
+export const srcPlaceholder = {
+    id: 'src-placeholder-content',
+    title: 'Placeholder content in source',
+    category: 'content',
+    needs: 'static',
+    verified: true,
+    mergeInto: 'placeholder-content',
+    description: 'Lorem ipsum, sample names, and example domains in markup.',
+    run({ repo }) {
+        const ev = [];
+        for (const f of repo?.files ?? []) {
+            if (!MARKUP.has(f.ext) && f.ext !== '.ts' && f.ext !== '.js')
+                continue;
+            for (const { text, line } of lines(f)) {
+                if (isComment(text))
+                    continue;
+                const m = findPlaceholders(visibleTextish(text)).filter((x) => x.phrase !== 'TODO marker');
+                if (m.length)
+                    ev.push(src(f, line, text, m.map((x) => x.phrase).join(', ')));
+            }
+        }
+        if (!ev.length)
+            return [];
+        return [
+            {
+                severity: ev.length >= 3 ? 'high' : 'medium',
+                confidence: 0.6,
+                description: `${plural(ev.length, 'line')} in source contain placeholder content.`,
+                recommendation: 'Replace placeholders with real content before shipping.',
+                evidence: ev,
+            },
+        ];
+    },
+};
+export const srcStockCopy = {
+    id: 'src-stock-copy',
+    title: 'Stock marketing phrases in source',
+    category: 'content',
+    needs: 'static',
+    verified: false,
+    mergeInto: 'stock-copy',
+    description: 'Stock phrases in markup and content files.',
+    run({ repo }) {
+        const ev = [];
+        for (const f of repo?.files ?? []) {
+            if (!MARKUP.has(f.ext))
+                continue;
+            for (const { text, line } of lines(f)) {
+                if (isComment(text))
+                    continue;
+                const m = findStockPhrases(visibleTextish(text));
+                if (m.length)
+                    ev.push(src(f, line, text, m.map((x) => `"${x.phrase}"`).join(', ')));
+            }
+        }
+        if (ev.length < 2)
+            return [];
+        return [
+            {
+                severity: ev.length >= 6 ? 'medium' : 'low',
+                confidence: 0.6,
+                description: `${plural(ev.length, 'line')} of copy in source use stock marketing phrases.`,
+                recommendation: 'Rewrite with specifics about the product: what it does, for whom, with what result.',
+                evidence: ev,
+            },
+        ];
+    },
+};
+export const arbitraryValues = {
+    id: 'arbitrary-values',
+    title: 'Hard-coded style values bypassing tokens',
+    category: 'visual',
+    needs: 'static',
+    verified: false,
+    penalty: 25,
+    description: 'Tailwind arbitrary values and raw hex colors in components instead of design tokens.',
+    run({ repo }) {
+        const ev = [];
+        let arbitrary = 0;
+        let hex = 0;
+        const perFile = new Map();
+        for (const f of repo?.files ?? []) {
+            if (!MARKUP.has(f.ext))
+                continue;
+            for (const { text, line } of lines(f)) {
+                if (isComment(text))
+                    continue;
+                const a = text.match(/\b[a-z-]+-\[(?:#[0-9a-f]{3,8}|\d+(?:\.\d+)?(?:px|rem|em)|rgba?\([^\]]+\))\]/gi) ?? [];
+                const h = (text.match(/(?<![\w&])#[0-9a-f]{6}\b|(?<![\w&])#[0-9a-f]{3}\b/gi) ?? []).filter(() => /style|color|fill|stroke|background/i.test(text));
+                if (a.length || h.length) {
+                    arbitrary += a.length;
+                    hex += h.length;
+                    perFile.set(f.path, (perFile.get(f.path) ?? 0) + a.length + h.length);
+                    if (ev.length < 12)
+                        ev.push(src(f, line, text, [...a, ...h].slice(0, 4).join(' ')));
+                }
+            }
+        }
+        const total = arbitrary + hex;
+        if (total < 15)
+            return [];
+        const worst = [...perFile].sort((x, y) => y[1] - x[1]).slice(0, 3).map(([p, n]) => `${p} (${n})`);
+        return [
+            {
+                severity: total >= 40 ? 'medium' : 'low',
+                confidence: 0.6,
+                description: `${total} hard-coded style values in components (${arbitrary} arbitrary utilities, ${hex} raw hex colors). Most in ${worst.join(', ')}.`,
+                recommendation: 'Move repeated values into theme tokens (Tailwind theme or CSS custom properties) so the design stays consistent and changes in one place.',
+                evidence: ev,
+            },
+        ];
+    },
+};
+const SHINGLE = 5;
+export const duplicatedMarkup = {
+    id: 'duplicated-markup',
+    title: 'Copy-pasted component markup',
+    category: 'visual',
+    needs: 'static',
+    verified: false,
+    penalty: 25,
+    description: 'Identical blocks of markup repeated within or across files instead of a shared component.',
+    run({ repo }) {
+        const blocks = new Map();
+        for (const f of repo?.files ?? []) {
+            if (!MARKUP.has(f.ext))
+                continue;
+            const raw = f.content.split('\n');
+            const sig = [];
+            raw.forEach((l, i) => {
+                // Compare structure, not wording: three hand-written cards that differ only in text are still a copy-paste.
+                const t = l.trim().replace(/>[^<>{}]*</g, '><').replace(/>[^<>{}]+$/, '>');
+                // Every HTML page starts with the same document boilerplate; that is not copied component markup.
+                if (/^<(?:!doctype|\/?html|\/?head|meta|link|title|\/?body|script\b[^>]*\bsrc=)/i.test(t))
+                    return;
+                if (t.length >= 12 && /[<>]/.test(t))
+                    sig.push({ t, line: i + 1 });
+            });
+            for (let i = 0; i + SHINGLE <= sig.length; i++) {
+                const win = sig.slice(i, i + SHINGLE);
+                // Ignore windows that span a big gap; they are not one contiguous block.
+                if (win[SHINGLE - 1].line - win[0].line > SHINGLE * 3)
+                    continue;
+                const key = createHash('sha1').update(win.map((w) => w.t).join('\n')).digest('hex');
+                if (!blocks.has(key))
+                    blocks.set(key, []);
+                const list = blocks.get(key);
+                const last = list[list.length - 1];
+                if (last && last.file === f.path && win[0].line - last.line < SHINGLE)
+                    continue; // overlapping window
+                list.push({ file: f.path, line: win[0].line, text: win[0].t });
+            }
+        }
+        const clusters = [...blocks.values()].filter((l) => l.length >= 3 || new Set(l.map((x) => x.file)).size >= 2);
+        if (!clusters.length)
+            return [];
+        // Collapse overlapping clusters: keep one per first-location.
+        const seenLoc = new Set();
+        const kept = [];
+        for (const c of clusters.sort((a, b) => b.length - a.length)) {
+            const k = `${c[0].file}:${Math.floor(c[0].line / 20)}`;
+            if (seenLoc.has(k))
+                continue;
+            seenLoc.add(k);
+            kept.push(c);
+            if (kept.length >= 5)
+                break;
+        }
+        const ev = kept.flatMap((c) => c.slice(0, 3).map((x) => ({ type: 'source', file: x.file, line: x.line, excerpt: truncate(x.text, 120), detail: `block repeated ${c.length} times` })));
+        const out = [
+            {
+                severity: 'low',
+                confidence: 0.6,
+                description: `${plural(kept.length, 'block')} of markup (${SHINGLE}+ lines) are repeated with the same structure${kept.some((c) => new Set(c.map((x) => x.file)).size > 1) ? ' across files' : ''}. Copy-pasted sections drift apart over time and make the design inconsistent.`,
+                recommendation: 'Extract the repeated block into a component and render it from data.',
+                evidence: ev,
+            },
+        ];
+        return out;
+    },
+};
+export const staticRules = [srcStockGradient, srcGlow, srcEmoji, srcPlaceholder, srcStockCopy, arbitraryValues, duplicatedMarkup];

package/dist/rules/types.d.ts

@@ -0,0 +1,39 @@
+import type { Category, CrawlResult, Evidence, Finding, RepoFacts, Severity } from '../types.js';
+export interface RuleMeta {
+    id: string;
+    /** Bump when a rule's logic changes in a way that changes its findings. */
+    version?: number;
+    title: string;
+    category: Category;
+    description: string;
+    /** Measured defect (true) or design observation that needs judgment (false). */
+    verified: boolean;
+    /** Relative weight w in p = s * c * w. Defaults to SCORING.defaultPenalty. */
+    penalty?: number;
+}
+export interface RuleContext {
+    crawl?: CrawlResult;
+    repo?: RepoFacts;
+}
+export interface FindingInput {
+    severity: Severity;
+    confidence: number;
+    description: string;
+    recommendation: string;
+    evidence: Evidence[];
+    routes?: string[];
+    title?: string;
+}
+export interface Rule extends RuleMeta {
+    /** 'rendered' rules need a crawl, 'static' rules need a repository. */
+    needs: 'rendered' | 'static';
+    /**
+     * For static rules that mirror a rendered rule: when the rendered rule fires, this rule's
+     * source locations are attached to it as evidence instead of producing a second finding.
+     */
+    mergeInto?: string;
+    run(ctx: RuleContext): FindingInput[];
+}
+/** Raw finding before normalization assigns id and fingerprint. */
+export type DraftFinding = Omit<Finding, 'id' | 'fingerprint'>;
+export declare function toDraft(rule: Rule, input: FindingInput, source: Finding['source']): DraftFinding;

package/dist/rules/types.js

@@ -0,0 +1,16 @@
+export function toDraft(rule, input, source) {
+    return {
+        ruleId: rule.id,
+        ruleVersion: rule.version ?? 1,
+        title: input.title ?? rule.title,
+        category: rule.category,
+        severity: input.severity,
+        confidence: input.confidence,
+        source,
+        description: input.description,
+        recommendation: input.recommendation,
+        evidence: input.evidence,
+        routes: input.routes,
+        verified: rule.verified,
+    };
+}

package/dist/rules/visual.d.ts

@@ -0,0 +1,15 @@
+import type { SectionFact } from '../types.js';
+import type { Rule } from './types.js';
+export declare const stockGradient: Rule;
+export declare const glowEffects: Rule;
+export declare const cardGridSameness: Rule;
+export declare const repeatedRhythm: Rule;
+export declare const crossPageTemplate: Rule;
+type Kind = 'hero' | 'logos' | 'features' | 'testimonials' | 'pricing' | 'faq' | 'cta';
+export declare function classifySection(s: SectionFact, index: number, total: number): Kind | undefined;
+export declare const stockLandingSequence: Rule;
+export declare const centeredEverything: Rule;
+export declare const emojiIcons: Rule;
+export declare const tokenSprawl: Rule;
+export declare const visualRules: Rule[];
+export {};