CtrlK
BlogDocsLog inGet started
Tessl Logo
PluginPublic

adobe/stardust

Redesign an existing website to make it better. Built on top of impeccable.

Quality

88%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Low

Low-risk findings worth noting

Overview
Quality
Evals
Security
Files

lib.mjsskills/qa/scripts/

/**
 * qa/lib.mjs — shared helpers for the stardust:qa read-only checkers.
 *
 * Everything here is side-effect-free except writeJSON/ensureDir, which only
 * ever target the QA output directory. No module in this skill mutates site
 * content, DA documents, or repo code.
 */
import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
import { join, dirname } from 'node:path';
import { fileURLToPath } from 'node:url';

// The shared rules (contracts.mjs) live beside browser.mjs in the master skill's scripts dir — the plugin tree or the
// Setup step 7 copy — resolved here once and re-exported, so the checks keep importing them from ../lib.mjs.
const CONTRACTS = ['../../stardust/scripts/contracts.mjs', '../stardust/contracts.mjs']
  .map((p) => new URL(p, import.meta.url)).find((u) => existsSync(u));
if (!CONTRACTS) throw new Error('qa/lib.mjs: contracts.mjs not found (looked in ../../stardust/scripts/ and ../stardust/). Copy the master skill\'s scripts dir to stardust/scripts/stardust/ (skills/stardust/SKILL.md § Setup).');
const C = await import(CONTRACTS.href);
const { QA_CHROME_PATHS } = C;
export const { listingKey, listingUrl, deliveredUrl, pathKey, isMetaBlock, widgetLinks, AI_EXCLUDE_DEFAULT, loadSibling } = C;

export function arg(name, fallback = null) {
  const i = process.argv.indexOf(`--${name}`);
  return i !== -1 && process.argv[i + 1] !== undefined ? process.argv[i + 1] : fallback;
}
export function flag(name) { return process.argv.includes(`--${name}`); }

export const STARDUST_VERSION = (() => {
  try {
    const here = dirname(fileURLToPath(import.meta.url));
    const pj = JSON.parse(readFileSync(join(here, '..', '..', '..', '.claude-plugin', 'plugin.json'), 'utf8'));
    return pj.version || '0.0.0';
  } catch { return '0.0.0'; }
})();

export function provenance(script, input) {
  return {
    writtenBy: `stardust:qa/${script}`,
    stardustVersion: STARDUST_VERSION,
    writtenAt: new Date().toISOString(),
    againstInput: input,
  };
}

export function ensureDir(dir) { mkdirSync(dir, { recursive: true }); }
export function readJSON(file, fallback = undefined) {
  try { return JSON.parse(readFileSync(file, 'utf8')); } catch { return fallback; }
}
export function writeJSON(file, obj) {
  ensureDir(dirname(file));
  writeFileSync(file, `${JSON.stringify(obj, null, 2)}\n`);
}

/* ---------------------------------------------------------------- fetch -- */

const UA = 'stardust-qa/1.0 (+read-only site QA)';

/**
 * Fetch a URL with timeout + one retry. redirect: 'manual' callers get the
 * Location back instead of the followed body.
 */
/* ---------------------------------------------------------- site auth -- */
// Protected origins (access allow-list + site secret) 401 every unauthenticated
// probe. The header is sent to the BASE origin only — never to third parties,
// whose CORS checks would turn a credentialed request into a false failure.
let ORIGIN_AUTH = null;
export function setOriginAuth(base, headerValue) { ORIGIN_AUTH = base && headerValue ? { origin: new URL(base).origin, value: headerValue } : null; }
export function originAuthFor(url) {
  if (!ORIGIN_AUTH || ORIGIN_AUTH.origin === 'null') return null;
  try { return new URL(url).origin === ORIGIN_AUTH.origin ? ORIGIN_AUTH.value : null; } catch { return null; }
}
/** browser side: attach the auth header to base-origin requests of a Playwright context (route filter, never extraHTTPHeaders) */
export async function attachOriginAuth(context) {
  if (!ORIGIN_AUTH || ORIGIN_AUTH.origin === 'null') return;
  const { attachOriginAuth: attach } = await frontDoor();
  await attach(context, ORIGIN_AUTH.origin, ORIGIN_AUTH.value);
}
/** `--auth-header "token …"` or `--token-env NAME` (process.env, then a cwd `.env`); default env name SITE_TOKEN */
export function resolveAuthHeader() {
  const direct = arg('auth-header'); if (direct) return direct;
  const name = arg('token-env') || 'SITE_TOKEN';
  let v = process.env[name];
  if (!v && existsSync('.env')) v = (readFileSync('.env', 'utf8').match(new RegExp(`^${name}=(.*)$`, 'm')) || [])[1];
  if (!v) return null;
  v = v.trim().replace(/^["']|["']$/g, '');
  return /^(token|bearer) /i.test(v) ? v : `token ${v}`;
}

export async function fetchUrl(url, { redirect = 'follow', method = 'GET', timeoutMs = 20000, retries = 1, binary = false } = {}) {
  for (let attempt = 0; ; attempt += 1) {
    const ctl = new AbortController();
    const timer = setTimeout(() => ctl.abort(), timeoutMs);
    try {
      const auth = originAuthFor(url);
      const res = await fetch(url, { method, redirect, signal: ctl.signal, headers: { 'user-agent': UA, ...(auth ? { authorization: auth } : {}) } });
      const bytes = binary && method !== 'HEAD' ? Buffer.from(await res.arrayBuffer()) : undefined;
      const body = method === 'HEAD' || binary ? '' : await res.text();
      clearTimeout(timer);
      return {
        ok: res.ok,
        ...(bytes ? { bytes } : {}),
        status: res.status,
        headers: Object.fromEntries(res.headers.entries()),
        location: res.headers.get('location'),
        url: res.url,
        body,
      };
    } catch (e) {
      clearTimeout(timer);
      if (attempt >= retries) return { ok: false, status: 0, headers: {}, location: null, url, body: '', error: e.message };
      await new Promise((r) => setTimeout(r, 1000 * (attempt + 1)));
    }
  }
}

/**
 * Shared page-fetch cache for one sweep: routing, content, metadata, and links
 * each visit every page, so without this a fleet is fetched ~3× (full HTML)
 * plus 2× (.plain.html). Only plain GET+follow requests are cached (probes —
 * HEAD, redirect:'manual' — have distinct semantics and bypass it); network
 * failures (status 0) are not cached so a transient error can't poison later
 * checks. Stores in-flight promises, so concurrent callers share one request.
 */
export function createPageCache(maxEntries = 4096) {
  const cache = new Map(); // url -> Promise<fetchUrl result>
  const cachedFetch = (url, opts = {}) => {
    const cacheable = (!opts.method || opts.method === 'GET')
      && (!opts.redirect || opts.redirect === 'follow');
    if (!cacheable) return fetchUrl(url, opts);
    if (cache.has(url)) return cache.get(url);
    const p = fetchUrl(url, opts).then((res) => {
      if (res.status === 0 || cache.size > maxEntries) cache.delete(url);
      return res;
    });
    cache.set(url, p);
    return p;
  };
  return cachedFetch;
}

/** Tiny concurrency limiter: run tasks (thunks) with at most n in flight. */
export async function pMap(items, fn, n = 6) {
  const results = new Array(items.length);
  let next = 0;
  async function worker() {
    for (;;) {
      const i = next; next += 1;
      if (i >= items.length) return;
      results[i] = await fn(items[i], i);
    }
  }
  await Promise.all(Array.from({ length: Math.min(n, items.length) }, worker));
  return results;
}

/* ----------------------------------------------------------------- html -- */

export function stripTags(html) {
  return html
    .replace(/<script[\s\S]*?<\/script>/gi, ' ')
    .replace(/<style[\s\S]*?<\/style>/gi, ' ')
    .replace(/<[^>]+>/g, ' ')
    .replace(/&nbsp;/g, ' ')
    .replace(/&amp;/g, '&').replace(/&lt;/g, '<').replace(/&gt;/g, '>')
    .replace(/&#x([0-9a-f]+);/gi, (_, h) => String.fromCodePoint(parseInt(h, 16)))
    .replace(/&#(\d+);/g, (_, d) => String.fromCodePoint(Number(d)))
    .replace(/&[a-z]+;/gi, ' ')
    .replace(/\s+/g, ' ')
    .trim();
}

/** Decode HTML entities in an attribute value (hrefs/content carry &#x26; etc.). */
export function decodeAttr(s) {
  return (s || '')
    .replace(/&#x([0-9a-f]+);/gi, (_, h) => String.fromCodePoint(parseInt(h, 16)))
    .replace(/&#(\d+);/g, (_, d) => String.fromCodePoint(Number(d)))
    .replace(/&amp;/g, '&').replace(/&lt;/g, '<').replace(/&gt;/g, '>')
    .replace(/&quot;/g, '"').replace(/&#39;|&apos;/g, "'");
}

/** Normalize text for containment comparisons: lowercase, alphanumerics only. */
export function normText(s) {
  return s.toLowerCase().normalize('NFKD')
    .replace(/[‘’]/g, "'").replace(/[“”]/g, '"')
    .replace(/[^a-z0-9']+/g, ' ')
    .replace(/\s+/g, ' ')
    .trim();
}

/** Extract `<p>…</p>` inner texts in order (tags stripped). */
export function paragraphTexts(html) {
  return [...html.matchAll(/<p[^>]*>([\s\S]*?)<\/p>/gi)].map((m) => stripTags(m[1]));
}

/** Delivered path → live URL. '/' maps to the site root. */
export function pageUrl(base, path) {
  return `${base.replace(/\/$/, '')}${path === '/' ? '/' : path}`;
}
export function plainUrl(base, path) {
  const b = base.replace(/\/$/, '');
  return path.endsWith('/') ? `${b}${path}index.plain.html` : `${b}${path}.plain.html`;
}
export function pathSlug(path) {
  return path === '/' ? 'index' : path.replace(/^\//, '').replace(/\//g, '__');
}

/* ------------------------------------------------------------- findings -- */

/**
 * Finding shape (schemas/qa-report.schema.json):
 *   check     one of routing|content|templates|rendered|visual|metadata|links|a11y|perf
 *   id        stable machine id within the check, e.g. "missing-canonical"
 *   severity  error | warn | info
 *   path      delivered path the finding is about ('' = fleet-level)
 *   message   one-line human statement
 *   evidence  optional free-form object (urls, counts, excerpts, file refs)
 */
export function finding(check, id, severity, path, message, evidence = undefined) {
  const f = { check, id, severity, path, message };
  if (evidence !== undefined) f.evidence = evidence;
  return f;
}

/* ------------------------------------------------------------ allowlist -- */

/**
 * Allowlist entries (schemas/qa-allowlist.schema.json):
 *   { check, id?, path?, messagePattern?, reason, addedAt? }
 * A finding is allowlisted when every provided field matches:
 *   check: exact or '*'; id: exact or '*'; path: exact or prefix ending in '*';
 *   messagePattern: JS regex tested against message.
 * Allowlisted findings stay in the report (allowlisted: true) — they are
 * documented non-defects, not deleted evidence.
 */
export function loadAllowlist(file) {
  const doc = readJSON(file, null);
  if (!doc) return [];
  return Array.isArray(doc) ? doc : (doc.entries || []);
}

function pathMatches(pattern, path) {
  if (pattern === undefined || pattern === null) return true;
  if (pattern.endsWith('*')) return path.startsWith(pattern.slice(0, -1));
  return pattern === path;
}

export function applyAllowlist(findings, entries) {
  for (const f of findings) {
    const hit = entries.find((e) => (e.check === '*' || e.check === f.check)
      && (e.id === undefined || e.id === '*' || e.id === f.id)
      && pathMatches(e.path, f.path)
      && (e.messagePattern === undefined || new RegExp(e.messagePattern, 'i').test(f.message)));
    if (hit) { f.allowlisted = true; f.allowlistReason = hit.reason || ''; }
  }
  return findings;
}

/* ------------------------------------------------------------ playwright -- */

// The browser front door (stardust/scripts/browser.mjs), resolved once. A check that needs a browser and cannot
// find it throws, like a missing playwright: the orchestrator records the crash, links.mjs reports "unverified".
const BROWSER = ['../../stardust/scripts/browser.mjs', '../stardust/browser.mjs']
  .map((p) => new URL(p, import.meta.url)).find((u) => existsSync(u));
function frontDoor() {
  if (!BROWSER) throw new Error('qa/lib.mjs: browser.mjs not found (looked in ../../stardust/scripts/ and ../stardust/). Copy the master skill\'s scripts dir to stardust/scripts/stardust/ (skills/stardust/SKILL.md § Setup).');
  return import(BROWSER.href);
}
const viaFrontDoor = (name) => async (...args) => (await frontDoor())[name](...args);
export const loadPlaywright = viaFrontDoor('loadPlaywright');
export const openBrowser = viaFrontDoor('openBrowser');
export const newContext = viaFrontDoor('newContext');
export const newPage = viaFrontDoor('newPage');
export const goto = viaFrontDoor('goto');

/* ------------------------------------------------------------- inventory -- */

/**
 * Build the page inventory (the fleet the checks sweep). Sources, merged:
 *   --paths-file <txt>          one delivered path per line
 *   --template-map <json>       stardust/template-map.json ({templates:{t:{urls:[]}}})
 *   sitemap.xml at --base       always fetched when base is set (also used for parity findings)
 * Fragments (default lib/kinds.mjs QA_CHROME_PATHS: nav/footer) are tracked separately: they are delivered
 * documents but not pages (no h1/metadata expectations).
 */
export async function buildInventory({ base, pathsFile, templateMap, fragments = QA_CHROME_PATHS, mergeSitemap = true }) {
  const pages = new Map(); // path -> {path, sources:[], template}
  // path is the key (no trailing slash); url is where EDS serves the page: a folder index at /x/, which a source
  // listing it with its slash tells (/x 404s on a plain EDS site) — lib/paths.mjs listingKey / listingUrl
  const add = (path, source, template) => {
    const p = listingKey(path);
    if (!pages.has(p)) pages.set(p, { path: p, url: p, sources: [], template: template || null });
    const row = pages.get(p);
    if (listingUrl(path) !== p) row.url = listingUrl(path);
    if (!row.sources.includes(source)) row.sources.push(source);
    if (template && !row.template) row.template = template;
  };

  if (pathsFile && existsSync(pathsFile)) {
    for (const line of readFileSync(pathsFile, 'utf8').split('\n')) {
      const t = line.trim();
      if (t && !t.startsWith('#')) add(t.startsWith('/') ? t : `/${t}`, 'paths-file');
    }
  }
  if (templateMap && existsSync(templateMap)) {
    const doc = readJSON(templateMap, {});
    for (const [tname, t] of Object.entries(doc.templates || {})) {
      for (const u of t.urls || []) add(u, 'template-map', tname);
    }
  }
  let sitemapPaths = null;
  if (base) {
    const res = await fetchUrl(`${base.replace(/\/$/, '')}/sitemap.xml`);
    if (res.ok) {
      sitemapPaths = [...res.body.matchAll(/<loc>\s*([^<\s]+)\s*<\/loc>/g)]
        .map((m) => { try { return listingKey(new URL(m[1]).pathname); } catch { return null; } })
        .filter(Boolean);
      if (mergeSitemap) for (const p of sitemapPaths) if (!fragments.includes(p)) add(p, 'sitemap');
    }
  }
  return {
    pages: [...pages.values()].sort((a, b) => a.path.localeCompare(b.path)),
    sitemapPaths, // null = sitemap unavailable
    fragments,
  };
}

skills

README.md

tile.json