samey-cli 0.0.0-stage → 0.1.0

package/dist/report/prompt.js

@@ -0,0 +1,62 @@
+/** Shared by the HTML report's copy buttons, fix-prompt.md, and `samey prompt`. */
+export const PROMPT_HEADER = 'Fix the following UI issues reported by samey. Make focused changes, keep unrelated code as is, and re-run samey afterwards to verify.\n\n';
+/** One finding as plain text an AI coding agent can act on. */
+export function fixPrompt(f) {
+    const ev = f.evidence
+        .slice(0, 10)
+        .map((e) => {
+        const bits = [
+            e.route && `route ${e.route}${e.viewport ? ` (${e.viewport})` : ''}${e.alsoOn?.length ? `, also on ${e.alsoOn.join(', ')}` : ''}`,
+            e.file && `${e.file}${e.line ? `:${e.line}` : ''}`,
+            e.selector && `selector \`${e.selector}\``,
+            e.excerpt && `"${e.excerpt}"`,
+            e.detail,
+        ].filter(Boolean);
+        return `- ${bits.join(', ')}`;
+    })
+        .join('\n');
+    return `[${f.ruleId}] ${f.title}${f.verified ? '' : ' (design observation, use judgment)'}\n${f.description}\n${ev ? `Evidence:\n${ev}\n` : ''}Fix: ${f.recommendation}`;
+}
+function rerunCommand(report) {
+    if (report.target.url && report.target.path)
+        return `npx samey-cli audit . --url ${report.target.url}`;
+    if (report.target.url)
+        return `npx samey-cli audit --url ${report.target.url}`;
+    return 'npx samey-cli audit .';
+}
+/**
+ * The whole audit as one prompt: measured defects first, then design observations the agent
+ * should weigh rather than apply blindly. Info-level and advisory model findings are left out.
+ */
+export function fullPrompt(report, opts = {}) {
+    const actionable = report.findings.filter((f) => !f.advisory && f.severity !== 'info');
+    const defects = actionable.filter((f) => f.verified);
+    const observations = opts.onlyDefects ? [] : actionable.filter((f) => !f.verified);
+    if (!defects.length && !observations.length)
+        return null;
+    const context = [];
+    if (report.target.url)
+        context.push(`Site: ${report.target.url}`);
+    if (report.repo?.frameworks.length)
+        context.push(`Stack: ${report.repo.frameworks.join(', ')}`);
+    if (report.score !== null)
+        context.push(`Current slop score: ${report.score}/100 (lower is better)`);
+    const out = [PROMPT_HEADER.trimEnd(), ''];
+    if (context.length)
+        out.push(context.join('\n'), '');
+    out.push('Work through the list in order. Each item names the page, the CSS selector, and the source file and line when samey could trace it. ' +
+        'Where a fix needs content only a person can provide (real testimonials, real numbers, a brand colour), ask instead of inventing it.', '');
+    let n = 0;
+    if (defects.length) {
+        out.push('## Defects (measured, fix these)', '');
+        for (const f of defects)
+            out.push(`${++n}. ${fixPrompt(f)}`, '');
+    }
+    if (observations.length) {
+        out.push('## Design observations (heuristics, use judgment)', '');
+        for (const f of observations)
+            out.push(`${++n}. ${fixPrompt(f)}`, '');
+    }
+    out.push(`When you are done, run \`${rerunCommand(report)}\` and confirm these findings are gone.`);
+    return out.join('\n') + '\n';
+}

package/dist/report/terminal.d.ts

@@ -0,0 +1,6 @@
+import type { AuditReport } from '../types.js';
+export declare function summarize(report: AuditReport, files: {
+    html?: string;
+    json?: string;
+    prompt?: string;
+}): string;

package/dist/report/terminal.js

@@ -0,0 +1,73 @@
+import path from 'node:path';
+import pc from 'picocolors';
+import { CATEGORY_LABELS } from '../score.js';
+const SEV_COLOR = {
+    critical: (s) => pc.bold(pc.red(s)),
+    high: pc.red,
+    medium: pc.yellow,
+    low: pc.dim,
+    info: pc.dim,
+};
+export function summarize(report, files) {
+    const out = [];
+    const scored = report.findings.filter((f) => !f.advisory);
+    const cov = report.coverage;
+    out.push('');
+    if (report.score === null)
+        out.push(`  ${pc.bold('Slop score n/a')}  ${pc.dim('nothing could be measured')}`);
+    else
+        out.push(`  ${pc.bold(`Slop score ${report.score}`)}${pc.dim('/100, lower is better')}${cov.rendered ? '' : pc.dim('  (static analysis only)')}`);
+    out.push('');
+    for (const c of report.categories) {
+        const label = CATEGORY_LABELS[c.category].padEnd(28);
+        if (c.score === null) {
+            out.push(pc.dim(`  ${label} not measured`));
+            continue;
+        }
+        const filled = Math.round(c.score / 5);
+        const bar = '█'.repeat(filled) + pc.dim('░'.repeat(20 - filled));
+        out.push(`  ${label} ${bar} ${String(Math.round(c.score)).padStart(3)}`);
+    }
+    out.push('');
+    out.push(pc.dim(`  ${cov.pagesAudited} page${cov.pagesAudited === 1 ? '' : 's'} rendered` +
+        (report.repo ? `, ${report.repo.fileCount} source files scanned` : '') +
+        (cov.routeLimitHit ? `, route limit reached` : '') +
+        (cov.blockedRequests.length ? `, ${cov.blockedRequests.length} requests blocked by network policy` : '')));
+    if (cov.renderedNote)
+        out.push(pc.yellow(`  ${cov.renderedNote}`));
+    if (scored.length) {
+        out.push('');
+        out.push(pc.bold('  Fix first'));
+        for (const f of scored.slice(0, 5)) {
+            const where = f.evidence.find((e) => e.file) ?? f.evidence.find((e) => e.route);
+            const loc = where?.file ? `${where.file}${where.line ? `:${where.line}` : ''}` : where?.route ?? '';
+            out.push(`  ${SEV_COLOR[f.severity](f.severity.padEnd(8))} ${f.title}${f.verified ? '' : pc.dim(' (observation)')}${loc ? pc.dim(`  ${loc}`) : ''}`);
+        }
+        if (scored.length > 5)
+            out.push(pc.dim(`  …and ${scored.length - 5} more in the report`));
+    }
+    else {
+        out.push('');
+        out.push('  No findings.');
+    }
+    out.push('');
+    const rel = (p) => {
+        const r = path.relative(process.cwd(), p);
+        return !r || r.startsWith('..') ? p : r;
+    };
+    if (files.html)
+        out.push(`  Report  ${pc.underline(rel(files.html))}`);
+    if (files.json)
+        out.push(`  JSON    ${rel(files.json)}`);
+    if (files.prompt) {
+        out.push(`  Prompt  ${rel(files.prompt)}`);
+        // Spell out the exact command, since `samey prompt` looks in <path>/.samey unless told otherwise.
+        const dir = path.dirname(files.prompt);
+        const base = report.target.path ?? process.cwd();
+        const fromCwd = path.relative(process.cwd(), base);
+        const arg = dir !== path.join(base, '.samey') ? ` --out ${rel(dir)}` : !fromCwd ? '' : fromCwd.startsWith('..') ? ` ${base}` : ` ${fromCwd}`;
+        out.push(pc.dim(`          Paste it into Claude Code, Cursor or Codex, or copy it: npx samey-cli prompt${arg}${process.platform === 'darwin' ? ' | pbcopy' : ''}`));
+    }
+    out.push('');
+    return out.join('\n');
+}

package/dist/rules/content.d.ts

@@ -0,0 +1,8 @@
+import type { Rule } from './types.js';
+export declare const stockCopy: Rule;
+export declare const placeholderContent: Rule;
+export declare const duplicateCopy: Rule;
+export declare const unverifiedClaims: Rule;
+export declare const anonymousTestimonials: Rule;
+export declare const genericLinkText: Rule;
+export declare const contentRules: Rule[];

package/dist/rules/content.js

@@ -0,0 +1,227 @@
+import { ATTRIBUTION, findClaims, findPlaceholders, findStockPhrases, GENERIC_LINK_TEXT, snippetAround, truncate } from '../util/text.js';
+import { el, inChrome, pagesWith, plural, uniqueRoutes } from './helpers.js';
+const PLACEHOLDER_IMG = /(?:via\.placeholder\.com|placehold\.(?:co|it)|placekitten|picsum\.photos|dummyimage\.com|fakeimg\.pl|source\.unsplash\.com\/random|placeholder\.(?:png|jpe?g|svg|webp))/i;
+export const stockCopy = {
+    id: 'stock-copy',
+    title: 'Interchangeable marketing copy',
+    category: 'content',
+    needs: 'rendered',
+    verified: false,
+    description: 'Headlines and body text built from stock phrases that could describe any product.',
+    run({ crawl }) {
+        const ev = [];
+        const seen = new Set();
+        let inHeadings = 0;
+        let inH1 = false;
+        const phrases = new Map();
+        for (const { page, facts } of pagesWith(crawl, 'desktop')) {
+            for (const b of facts.textBlocks) {
+                if (!/^(?:h[1-6]|p|li|button|a|dd|figcaption|blockquote|span|div)$/.test(b.tag))
+                    continue;
+                if (seen.has(b.text))
+                    continue;
+                const matches = findStockPhrases(b.text);
+                if (!matches.length)
+                    continue;
+                seen.add(b.text);
+                for (const m of matches)
+                    phrases.set(m.phrase, (phrases.get(m.phrase) ?? 0) + 1);
+                if (/^h[1-6]$/.test(b.tag))
+                    inHeadings++;
+                if (b.tag === 'h1')
+                    inH1 = true;
+                ev.push(el(page, 'desktop', b, snippetAround(b.text, matches[0].index), matches.map((m) => `"${m.phrase}"`).join(', ')));
+            }
+        }
+        if (ev.length < 2 && !inH1)
+            return [];
+        const top = [...phrases].sort((a, b) => b[1] - a[1]).slice(0, 6).map(([p]) => `"${p}"`);
+        return [
+            {
+                severity: inH1 || inHeadings >= 3 || ev.length >= 6 ? 'medium' : 'low',
+                confidence: 0.9,
+                description: `${plural(ev.length, 'text block')} lean on stock phrases (${top.join(', ')})${inHeadings ? `, ${inHeadings} of them in headings` : ''}. Copy like this could be pasted onto any product and says nothing about this one.`,
+                recommendation: 'Rewrite headings to state what the product does, for whom, and the concrete result. Replace adjectives with specifics: numbers you can back up, named features, a real example.',
+                evidence: ev.sort((a, b) => (b.detail?.length ?? 0) - (a.detail?.length ?? 0)),
+                routes: uniqueRoutes(ev),
+            },
+        ];
+    },
+};
+export const placeholderContent = {
+    id: 'placeholder-content',
+    title: 'Placeholder content shipped',
+    category: 'content',
+    needs: 'rendered',
+    verified: true,
+    description: 'Lorem ipsum, sample names and companies, example domains, and placeholder images.',
+    run({ crawl }) {
+        const ev = [];
+        const seen = new Set();
+        for (const { page, facts } of pagesWith(crawl, 'desktop')) {
+            for (const b of facts.textBlocks) {
+                if (seen.has(b.text))
+                    continue;
+                const m = findPlaceholders(b.text);
+                if (!m.length)
+                    continue;
+                seen.add(b.text);
+                ev.push(el(page, 'desktop', b, snippetAround(b.text, m[0].index), m.map((x) => x.phrase).join(', ')));
+            }
+            for (const img of facts.images) {
+                if (PLACEHOLDER_IMG.test(img.src))
+                    ev.push(el(page, 'desktop', img, truncate(img.src, 100), 'placeholder image service'));
+            }
+        }
+        if (!ev.length)
+            return [];
+        return [
+            {
+                severity: ev.length >= 3 ? 'high' : 'medium',
+                confidence: 0.9,
+                description: `Found ${plural(ev.length, 'piece')} of placeholder content. Visitors notice this immediately and it signals the site is unfinished.`,
+                recommendation: 'Replace every placeholder with real content, or remove the section until the content exists.',
+                evidence: ev,
+                routes: uniqueRoutes(ev),
+            },
+        ];
+    },
+};
+export const duplicateCopy = {
+    id: 'duplicate-copy',
+    title: 'Repeated paragraphs',
+    category: 'content',
+    needs: 'rendered',
+    verified: true,
+    description: 'The same paragraph text repeated across the site outside header and footer.',
+    run({ crawl }) {
+        const byText = new Map();
+        for (const { page, facts } of pagesWith(crawl, 'desktop')) {
+            for (const b of facts.textBlocks) {
+                if (b.tag !== 'p' && b.tag !== 'li' && b.tag !== 'dd')
+                    continue;
+                if (b.text.length < 60 || inChrome(facts, b))
+                    continue;
+                if (!byText.has(b.text))
+                    byText.set(b.text, []);
+                byText.get(b.text).push(el(page, 'desktop', b, truncate(b.text, 100)));
+            }
+        }
+        const dupes = [...byText].filter(([, ev]) => ev.length >= 2);
+        if (!dupes.length)
+            return [];
+        const ev = dupes.slice(0, 6).flatMap(([, e]) => e.slice(0, 2));
+        return [
+            {
+                severity: dupes.length >= 3 ? 'medium' : 'low',
+                confidence: 0.9,
+                description: `${plural(dupes.length, 'paragraph')} appear more than once across the site. Repeated copy suggests sections were duplicated rather than written.`,
+                recommendation: 'Write copy specific to each place it appears, or remove the duplicate.',
+                evidence: ev,
+                routes: uniqueRoutes(ev),
+            },
+        ];
+    },
+};
+export const unverifiedClaims = {
+    id: 'unverified-claims',
+    title: 'Unsupported credibility claims',
+    category: 'content',
+    needs: 'rendered',
+    verified: false,
+    penalty: 20,
+    description: 'User counts, ratings, and performance percentages stated without a source.',
+    run({ crawl }) {
+        const ev = [];
+        const seen = new Set();
+        for (const { page, facts } of pagesWith(crawl, 'desktop')) {
+            for (const b of facts.textBlocks) {
+                if (b.text.length > 300 || seen.has(b.text))
+                    continue;
+                const m = findClaims(b.text);
+                if (!m.length)
+                    continue;
+                seen.add(b.text);
+                ev.push(el(page, 'desktop', b, snippetAround(b.text, m[0].index), m.map((x) => x.phrase).join(', ')));
+            }
+        }
+        if (!ev.length)
+            return [];
+        return [
+            {
+                severity: ev.length >= 4 ? 'medium' : 'low',
+                confidence: 0.35,
+                description: `${plural(ev.length, 'claim')} such as user counts, ratings, or percentages appear without a visible source. If these are real, they are fine; generated sites often invent them.`,
+                recommendation: 'Keep only numbers you can substantiate, and link or footnote the source. Remove invented social proof before launch.',
+                evidence: ev,
+                routes: uniqueRoutes(ev),
+            },
+        ];
+    },
+};
+export const anonymousTestimonials = {
+    id: 'anonymous-testimonials',
+    title: 'Testimonials without verifiable attribution',
+    category: 'content',
+    needs: 'rendered',
+    verified: false,
+    penalty: 20,
+    description: 'Testimonials attributed to a name and title with no photo, link, or company.',
+    run({ crawl }) {
+        const ev = [];
+        for (const { page, facts } of pagesWith(crawl, 'desktop')) {
+            for (const s of facts.sections) {
+                if (s.isChrome)
+                    continue;
+                const isTestimonials = s.hasBlockquote || /testimonial|what (?:our|people|customers)|loved by|customers say/i.test(s.heading ?? '');
+                if (!isTestimonials || !ATTRIBUTION.test(s.text))
+                    continue;
+                if (s.imageCount > 0)
+                    continue;
+                ev.push(el(page, 'desktop', s, truncate(s.text.match(ATTRIBUTION)?.[0] ?? s.heading ?? '', 80), 'quote with name and title only'));
+            }
+        }
+        if (!ev.length)
+            return [];
+        return [
+            {
+                severity: 'low',
+                confidence: 0.35,
+                description: `${plural(ev.length, 'testimonial section')} attribute quotes to a name and job title with no photo, company link, or source. Readers increasingly assume these are invented.`,
+                recommendation: 'Use real testimonials with permission, a photo or company logo, and a link where possible. If you have none yet, remove the section.',
+                evidence: ev,
+                routes: uniqueRoutes(ev),
+            },
+        ];
+    },
+};
+export const genericLinkText = {
+    id: 'generic-link-text',
+    title: 'Vague link and button labels',
+    category: 'accessibility',
+    needs: 'rendered',
+    verified: true,
+    penalty: 25,
+    description: 'Several links labelled "Learn more", "Read more", or "Click here".',
+    run({ crawl }) {
+        const ev = [];
+        for (const { page, facts } of pagesWith(crawl, 'desktop')) {
+            for (const l of facts.links)
+                if (GENERIC_LINK_TEXT.test(l.text.trim()))
+                    ev.push(el(page, 'desktop', l, l.text));
+        }
+        if (ev.length < 3)
+            return [];
+        return [
+            {
+                severity: 'low',
+                confidence: 0.9,
+                description: `${plural(ev.length, 'link')} use labels like "Learn more" that do not say where they go. Screen reader users navigating by links hear a list of identical labels.`,
+                recommendation: 'Name the destination: "Read the pricing FAQ", "See how imports work".',
+                evidence: ev,
+                routes: uniqueRoutes(ev),
+            },
+        ];
+    },
+};
+export const contentRules = [stockCopy, placeholderContent, duplicateCopy, unverifiedClaims, anonymousTestimonials, genericLinkText];

package/dist/rules/functional.d.ts

@@ -0,0 +1,17 @@
+import type { Rule } from './types.js';
+export declare const pageLoadFailed: Rule;
+export declare const brokenLinks: Rule;
+export declare const consoleErrors: Rule;
+export declare const failedRequests: Rule;
+export declare const deadLinks: Rule;
+export declare const unresponsiveButtons: Rule;
+export declare const emptyControls: Rule;
+export declare const brokenImages: Rule;
+export declare const missingAlt: Rule;
+export declare const unlabeledInputs: Rule;
+export declare const headingStructure: Rule;
+export declare const missingMetadata: Rule;
+export declare const horizontalOverflow: Rule;
+export declare const smallTargets: Rule;
+export declare const tinyText: Rule;
+export declare const functionalRules: Rule[];