Redesign an existing website to make it better. Built on top of impeccable.
88%
Does it follow best practices?
Run evals on this skill
Adds up to 20 points to the overall score
Low
Low-risk findings worth noting
#!/usr/bin/env node
/**
* qa.mjs — stardust:qa orchestrator. READ-ONLY: finds issues and writes a
* report; it never edits site content, DA documents, or repo code. All output
* lands under --out (default stardust/qa/).
*
* Usage:
* node skills/qa/scripts/qa.mjs --base <live-url> [options]
*
* Options:
* --base <url> live host to sweep (required)
* --checks <list> comma list: routing,content,templates,metadata,links,browse,perf,
* editability,dynamics,chrome,ai-readability (default: all)
* --paths-file <txt> inventory source: one path per line
* --template-map <json> inventory + template assignments (stardust/template-map.json)
* --scrape <dir> stardust scrape captures for verbatim fidelity
* --expected-blocks <json> explicit per-template block expectations
* --redirects <tsv> the expected redirects (default stardust/redirects.tsv when present):
* each source must be a row of the live /redirects.json, to the same destination
* --allowlist <json> documented non-defects (default: <out>/allowlist.json)
* --out <dir> output dir (default: stardust/qa)
* --baselines <dir> visual baselines (default: <out>/baselines)
* --max-pages <n> cap the fleet (smoke runs)
* --no-sitemap-merge inventory from explicit sources only (sitemap still
* fetched for parity findings) — for sampled runs on
* large fleets
* --perf-pages <n> cap perf representatives (default 10)
* --budget-transfer-kb <n> --budget-js-kb <n>
* --skip-a11y skip axe injection
* --probe-externals probe unique external link targets (skipped by
* default — dominates sweep time on blog fleets;
* the skip is reported as links/externals-skipped)
* --ew-exempt <list> editability: comma list of blocks whose authored rows are
* config / derived / index fallback (dead texts reported as
* exempt, not errors)
* --blocks-dir <dir> editability: local blocks root — `@ew-exempt <reason>`
* JSDoc tags in <dir>/<name>/<name>.js are honoured
* --parity <json> dynamics: the parity report to replay (default stardust/dynamics/parity.json)
* --ai-exclude-blocks <a,b> ai-readability: app blocks removed from the rendered side
* (default client-app,widget — AI_EXCLUDE_DEFAULT, skills/stardust/scripts/lib/kinds.mjs)
* --browser-concurrency <n> parallel pages for the browser checks (default 3)
* --auth-header <value> | --token-env <NAME>
* auth for a protected origin: the header value, or the env var
* holding the token (default SITE_TOKEN; .env is read too)
* --fail-on <error|warn> exit 1 threshold (default: error)
*
* Writes (under --out, default stardust/qa):
* inventory.json the page inventory that was swept, with _provenance
* report.json / report.html findings, summary, checks run, duration
* shots/<path-slug>.<viewport>.png browse check: the current screenshots
* <baselines>/<same name>.png browse check: saved on first sight only (default <out>/baselines)
* Progress lines go to stderr; the summary goes to stdout.
*
* Exit codes: 0 clean (below threshold), 1 findings at/above threshold, 2 infra error.
*/
import { join, dirname } from 'node:path';
import { fileURLToPath } from 'node:url';
import { existsSync, writeFileSync, readFileSync } from 'node:fs';
import {
arg, flag, provenance, writeJSON, ensureDir, loadAllowlist, applyAllowlist, buildInventory,
createPageCache, resolveAuthHeader, setOriginAuth,
} from './lib.mjs';
import { htmlReport } from './report-html.mjs';
// --help prints this file's usage header, so an agent never reads the source to learn the flags.
if (process.argv.includes('--help') || process.argv.includes('-h')) {
const src = readFileSync(new URL(import.meta.url), 'utf8');
const header = src.match(/\/\*\*[\s\S]*?\*\//);
console.log(header ? header[0].replace(/^\/\*\*\s*|\s*\*\/$/g, '').replace(/^\s*\* ?/gm, '').trim() : 'no usage header');
process.exit(0);
}
const here = dirname(fileURLToPath(import.meta.url));
const BASE = (arg('base') || '').replace(/\/$/, '');
if (!BASE) { console.error('qa: --base <live-url> is required'); process.exit(2); }
const OUT = arg('out', 'stardust/qa');
const CHECKS = (arg('checks', 'routing,content,templates,metadata,links,browse,perf,editability,dynamics,chrome,ai-readability')).split(',').map((s) => s.trim()).filter(Boolean);
const opts = {
outDir: OUT,
scrapeDir: arg('scrape', null),
expectedBlocks: arg('expected-blocks', null),
expectedRedirects: arg('redirects', existsSync('stardust/redirects.tsv') ? 'stardust/redirects.tsv' : null),
baselineDir: arg('baselines', join(OUT, 'baselines')),
perfPages: Number(arg('perf-pages', 10)),
budgetTransferKb: Number(arg('budget-transfer-kb', 800)),
budgetJsKb: Number(arg('budget-js-kb', 250)),
skipA11y: flag('skip-a11y'),
probeExternals: flag('probe-externals'),
browserConcurrency: Number(arg('browser-concurrency', 3)),
parity: arg('parity', null),
authHeader: resolveAuthHeader(),
};
if (opts.authHeader) setOriginAuth(BASE, opts.authHeader);
const MODULES = {
routing: 'checks/routing.mjs',
content: 'checks/content.mjs',
templates: 'checks/templates.mjs',
metadata: 'checks/metadata.mjs',
links: 'checks/links.mjs',
browse: 'checks/browse.mjs',
perf: 'checks/perf.mjs',
editability: 'checks/editability.mjs',
dynamics: 'checks/dynamics.mjs',
chrome: 'checks/chrome.mjs',
'ai-readability': 'checks/ai-readability.mjs',
};
const started = Date.now();
console.error(`qa: sweeping ${BASE}`);
const inventory = await buildInventory({
base: BASE,
pathsFile: arg('paths-file', null),
templateMap: arg('template-map', null),
mergeSitemap: !flag('no-sitemap-merge'),
});
const maxPages = Number(arg('max-pages', 0));
if (maxPages > 0) inventory.pages = inventory.pages.slice(0, maxPages);
if (!inventory.pages.length) { console.error('qa: inventory is empty — pass --paths-file or --template-map, or check the sitemap'); process.exit(2); }
console.error(`qa: inventory ${inventory.pages.length} pages (sitemap ${inventory.sitemapPaths ? inventory.sitemapPaths.length : 'n/a'})`);
ensureDir(OUT);
writeJSON(join(OUT, 'inventory.json'), { _provenance: provenance('inventory', BASE), ...inventory });
// page + plain per page, with headroom for fragments and probe GETs
const ctx = {
base: BASE, inventory, opts, shared: {},
fetchPage: createPageCache(inventory.pages.length * 2 + 64),
};
const findings = [];
const checksRun = [];
for (const name of CHECKS) {
if (!MODULES[name]) { console.error(`qa: unknown check "${name}" — skipping`); continue; }
const t = Date.now();
console.error(`qa: [${name}] running…`);
try {
const mod = await import(join(here, MODULES[name]));
const f = await mod.run(ctx);
findings.push(...f);
checksRun.push(name);
console.error(`qa: [${name}] ${f.length} finding(s) in ${((Date.now() - t) / 1000).toFixed(1)}s`);
} catch (e) {
console.error(`qa: [${name}] FAILED: ${e.stack || e}`);
findings.push({ check: name, id: 'check-crashed', severity: 'error', path: '', message: `check "${name}" crashed: ${String(e).slice(0, 300)}` });
}
}
const allowlistFile = arg('allowlist', join(OUT, 'allowlist.json'));
applyAllowlist(findings, loadAllowlist(allowlistFile));
const order = { error: 0, warn: 1, info: 2 };
findings.sort((a, b) => (a.allowlisted ? 1 : 0) - (b.allowlisted ? 1 : 0)
|| order[a.severity] - order[b.severity]
|| a.check.localeCompare(b.check) || (a.path || '').localeCompare(b.path || ''));
const active = findings.filter((f) => !f.allowlisted);
const summary = {
error: active.filter((f) => f.severity === 'error').length,
warn: active.filter((f) => f.severity === 'warn').length,
info: active.filter((f) => f.severity === 'info').length,
allowlisted: findings.length - active.length,
byCheck: Object.fromEntries(checksRun.map((c) => [c, active.filter((f) => f.check === c || (c === 'browse' && ['rendered', 'visual', 'a11y'].includes(f.check))).length])),
};
const report = {
provenance: provenance('qa', BASE),
base: BASE,
checksRun,
inventory: { pages: inventory.pages.length, sitemapEntries: inventory.sitemapPaths ? inventory.sitemapPaths.length : null },
durationSeconds: Math.round((Date.now() - started) / 1000),
summary,
findings,
};
writeJSON(join(OUT, 'report.json'), report);
writeFileSync(join(OUT, 'report.html'), htmlReport(report));
console.log(`\nstardust:qa — ${BASE}`);
console.log(`pages: ${inventory.pages.length} · duration: ${report.durationSeconds}s · checks: ${checksRun.join(', ')}`);
console.log(`findings: ${summary.error} error / ${summary.warn} warn / ${summary.info} info (+${summary.allowlisted} allowlisted)`);
for (const f of active.filter((x) => x.severity === 'error').slice(0, 30)) {
console.log(` ERROR [${f.check}/${f.id}] ${f.path || '(fleet)'} — ${f.message}`);
}
console.log(`report: ${join(OUT, 'report.json')} · ${join(OUT, 'report.html')}`);
const failOn = arg('fail-on', 'error');
const failing = failOn === 'warn' ? summary.error + summary.warn : summary.error;
process.exit(failing > 0 ? 1 : 0);.tessl-plugin
skills
audit
reference
deploy
reference
scripts
test
diff
direct
dynamics
extract
migrate
prepare-migration
prototype
assets
motion
fixtures
reference
qa
replica
reference
scripts
test
reskin
rollout
spec
stardust
uplift
reference