freestruct 1.0.0 → 1.2.0

package/engine/audit.js

@@ -0,0 +1,487 @@
+// engine/audit.js - the `freestruct audit` subcommand (issue #18)
+// Post-build verification that the SEO injection ACTUALLY landed, page by
+// page, plus site-level artifact checks - with an exit code for CI.
+// Ported from the donated zero-dep audit script (prestruct#34, MIT-compatible)
+// and remapped onto freestruct's own contract:
+//   - meta extraction is attribute-order tolerant (per the donor's notes)
+//   - og:image / twitter:image / twitter:site/creator are config-gated in
+//     this engine (missing-only), so their absence is a WARN, not a FAIL.
+//     The og:image / twitter:image absences are CONFIG-shaped (identical on
+//     every page), so they collapse to one line each with a page count
+//     (issue #28); twitter:site/creator are graded only when a handle is set.
+//   - the FAIL og/twitter class is the SHARED core (og:title/og:description,
+//     twitter:card/twitter:title); the rest of the injected set rides WARN
+//     because missing-only means SSG-tagged pages legitimately keep a
+//     partial set (post-injection the audit cannot tell SSG-owned heads
+//     apart, so partial-set coherence is report-grade)
+//   - the SVG og:image trap stays a FAIL here (audit-grade; the run-warning
+//     ladder from issue #20 is the pre-build enforcement point)
+//   - the 404 check is the noindex contract only (issue #11's shape)
+//   - external http(s) links: opt-in via --external (SEO-gap pass) - the
+//     baked tree is audited for the network, not the default audit; HEAD
+//     with a GET retry (some CDNs refuse HEAD), resolution failures and
+//     HTTP >= 400 come back as WARN rows (report-grade: bots get 403/429)
+
+import { readFileSync, existsSync, readdirSync, statSync } from 'fs';
+import path from 'path';
+import { decodeEntities } from './scan.js';
+
+// FAIL class = the tags core to the engine's own contract. The REST of the
+// injected set (og:url/type/site_name/locale, twitter:description) rides as
+// WARN because missing-only means SSG-tagged pages LEGITIMATELY keep a
+// partial set - fail-failing those would punish contract-abiding output.
+const OG_CORE = ['og:title', 'og:description'];
+const OG_SET = ['og:url', 'og:type', 'og:site_name', 'og:locale'];
+const TW_CORE = ['twitter:card', 'twitter:title'];
+const TW_SET = ['twitter:description', 'twitter:image', 'twitter:site', 'twitter:creator'];
+// LocalBusiness recommended fields per the donated script (schema.org).
+const LB_RECOMMENDED = ['name', 'url', 'image', 'logo', 'telephone', 'priceRange', 'openingHoursSpecification', 'geo', 'sameAs'];
+
+// ---------- scans ----------
+
+/** Attribute-order tolerant meta extraction: hits aligned multi-space output. */
+function grabMeta(head, attrHasKey, name) {
+  // `<meta\b[^>]*` (not `<meta[^>]`) so a leading attribute - `<meta charset=...
+  // name="description">` - is found too. The single-char class made the audit
+  // false-FAIL "missing meta description" on any page whose description meta
+  // carried another attribute first.
+  const keyRe = new RegExp(`<meta\\b[^>]*\\b${attrHasKey}=["']${name}["'][^>]*>`, 'i');
+  const tag = head.match(keyRe);
+  if (!tag) return null;
+  const content = attrValue(tag[0], 'content');
+  return content;
+}
+
+// Quoted-attribute reader. The naive `["']([^"']*)["']` stopped at the FIRST
+// quote of either kind, so any value holding the other quote (a description
+// with an apostrophe - "this repo's docs") was truncated at the apostrophe.
+// The backreference forces the closing quote to match the opening one, so the
+// value survives intact. Unquoted values fall through to a bare read.
+function attrValue(tag, attr) {
+  const quoted = tag.match(new RegExp(`\\b${attr}=(["'])([\\s\\S]*?)\\1`, 'i'));
+  if (quoted) return quoted[2];
+  const bare = tag.match(new RegExp(`\\b${attr}=([^\\s>]+)`, 'i'));
+  return bare ? bare[1] : null;
+}
+
+function grabCanonical(head) {
+  const link = head.match(/<link[^>]+rel=["']canonical["'][^>]*>/i)
+    || head.match(/<link[^>]+href=["'][^"']+["'][^>]+rel=["']canonical["'][^>]*>/i);
+  if (!link) return null;
+  return attrValue(link[0], 'href');
+}
+
+/** Count every occurrence of a head shape - the duplicate-class probe. */
+function countHead(head, re) {
+  return (head.match(re) || []).length;
+}
+
+function walkHtml(dir) {
+  let out = [];
+  for (const name of readdirSync(dir)) {
+    const p = path.join(dir, name);
+    if (statSync(p).isDirectory()) out = out.concat(walkHtml(p));
+    else if (/\.html?$/i.test(name)) out.push(p);
+  }
+  return out;
+}
+
+function stripTags(s) {
+  return String(s).replace(/<[^>]+>/g, '').trim();
+}
+
+// Title/description length is graded against what a SEARCH ENGINE sees: the
+// DECODED text, not the raw markup. An entity-heavy title ('&amp;', '&#39;',
+// '&#65;') inflated the raw length and tripped the > 65 / > 165 warnings on
+// text that renders well inside the band.
+function decodedLength(s) {
+  return decodeEntities(stripTags(s)).length;
+}
+
+/**
+ * Head-referenced site-local URL -> { resolved, inside } | null.
+ *
+ * null means "not a site-local path" (external host, protocol-relative,
+ * relative, empty) - nothing on disk to check. `inside` is false when the
+ * path resolves OUTSIDE the output tree: a traversal shape like
+ * '/../../etc/hostname', which must never be probed as if it were an
+ * artifact. (Before Pass 26.21 urlToDisk resolved and existsSync'd such a
+ * path, so a value pointing at any file on the host read back as "exists".)
+ */
+function sitePathInfo(urlValue, { outputDir, config }) {
+  if (!urlValue) return null;
+  let pathName = urlValue.split(/[?#]/)[0];
+  if (/^https?:\/\//i.test(pathName)) {
+    try {
+      const u = new URL(pathName);
+      const site = config?.site?.url ? new URL(config.site.url) : null;
+      // Only site-local files can exist in the output tree.
+      if (site && u.host !== site.host) return null;
+      pathName = u.pathname + u.search;
+    } catch (e) { return null; }
+  } else if (/^\/\//.test(pathName)) {
+    return null;
+  }
+  if (!pathName.startsWith('/')) return null;
+  // basePath normalization mirrors urls.js (issue #32 contract): the
+  // configured prefix may lack its leading slash, and a prefix must match a
+  // whole path segment ('/myproject' never strips '/myprojectx/...').
+  const bp = config?.basePath
+    ? ('/' + String(config.basePath).replace(/^\/+/, '')).replace(/\/+$/, '')
+    : '';
+  if (bp && (pathName === bp || pathName.startsWith(bp + '/'))) {
+    pathName = pathName.slice(bp.length);
+  }
+  const resolved = path.resolve(outputDir, pathName.replace(/^\//, ''));
+  const root = path.resolve(outputDir);
+  const inside = resolved === root || resolved.startsWith(root + path.sep);
+  return { resolved, inside };
+}
+
+// ---------- the audit ----------
+
+/**
+ * Audit a baked output directory. Returns { fails, warns, pages, sitemapLocs }.
+ * Prints a human report by default, or a JSON digest with `json: true`;
+ * `capture: true` (used when external checks ride along in json mode) skips
+ * printing and hands the caller the raw result.
+ * NEVER exits: the caller owns the exit code (0 clean / 1 findings).
+ */
+export function auditOutput({ outputDir, config, json = false, capture = false }) {
+  const fails = [];
+  const warns = [];
+  const fail = (page, msg) => fails.push({ page, msg });
+  const warn = (page, msg) => warns.push({ page, msg });
+
+  // Config-gated absences (issue #28): a condition that can only ever be
+  // true/false at the CONFIG level repeats identically on every page
+  // (og:image / twitter:image absent because no og.image is configured).
+  // Collect affected pages here and flush ONE line each with a count at the
+  // end, instead of N page-suffixed rows that bury the real findings.
+  // Page-shaped classes (title/description length, JSON-LD absence, h1
+  // sanity) still repeat - their findings genuinely differ per page.
+  const configGated = new Map(); // key -> Set(page labels)
+  const configGate = (key, label) => {
+    if (!configGated.has(key)) configGated.set(key, new Set());
+    configGated.get(key).add(label);
+  };
+
+  // File-at-path hardening (Pass 26.13): a file at the outputDir path passes
+  // existsSync, and walkHtml's readdirSync would arrive here uncaught.
+  if (!existsSync(outputDir) || !statSync(outputDir).isDirectory()) {
+    if (json) console.log(JSON.stringify({ ok: false, error: 'output dir not found: ' + outputDir }));
+    else console.error('[freestruct] audit: no "' + outputDir + '" directory - run the build first.');
+    return { fails: [{ page: 'outputDir', msg: 'missing' }], warns, pages: 0, sitemapLocs: 0 };
+  }
+
+  const pages = walkHtml(outputDir);
+  let sitemapLocs = 0;
+
+  for (const filePath of pages) {
+    let rel;
+    try { rel = path.relative(outputDir, filePath); } catch (e) { rel = filePath; }
+    const html = readFileSync(filePath, 'utf8');
+    const head = html.split('</head>')[0];
+    const label = rel.replace(/\\/g, '/');
+
+    if (/(^|\/)404\.html?$/i.test(label)) {
+      const robots = grabMeta(head, 'name', 'robots') || '';
+      if (!/noindex/i.test(robots)) fail(label, '404 page missing its noindex robots directive');
+      continue;
+    }
+
+    const titleMatch = head.match(/<title[^>]*>([\s\S]*?)<\/title>/i);
+    if (!titleMatch || !titleMatch[1].trim()) fail(label, 'missing <title>');
+    else {
+      const t = decodedLength(titleMatch[1]);
+      if (t > 65) warn(label, 'title ' + t + ' chars (> 65, may truncate)');
+      if (t < 10) warn(label, 'title ' + t + ' chars (suspiciously short)');
+    }
+
+    // A page that declares `robots noindex` is deliberately out of the index
+    // (a redirect stub, a thank-you page): the content-quality classes below
+    // - description length band, h1 shape, JSON-LD absence - grade indexable
+    // content, so they would only emit cosmetic noise on a page whose whole
+    // point is to not rank. The structural classes (title/canonical presence,
+    // duplicate tags, absolute canonical) still apply.
+    const noindex = /noindex/i.test(grabMeta(head, 'name', 'robots') || '');
+
+    const desc = grabMeta(head, 'name', 'description');
+    if (!desc) fail(label, 'missing meta description');
+    else if (!noindex) {
+      const d = decodeEntities(desc).length;
+      if (d < 70 || d > 165) warn(label, 'description ' + d + ' chars (outside 70-165, may truncate)');
+    }
+
+    const canonical = grabCanonical(head);
+    if (!canonical || canonical === '') fail(label, 'missing canonical link');
+    else if (!/^https?:\/\//i.test(canonical)) fail(label, 'canonical not absolute: ' + canonical);
+
+    // Duplicate tags ride the FAIL class: missing-only injection never
+    // adds a tag the page already carries, so any duplicate in a baked
+    // head is a page/SSG edit gone wrong (Pass 26.11). Attribute-order
+    // tolerant, same as the missing checks.
+    for (const dup of [
+      ['duplicate canonical link (a page ships exactly one)', /<link[^>]+rel=["']canonical["']/gi],
+      ['duplicate meta description', /<meta[^>]+name=["']description["']/gi],
+      ['multiple <title> elements', /<title[^>]*>/gi],
+      ['duplicate og:title', /<meta[^>]+property=["']og:title["']/gi],
+      ['duplicate og:description', /<meta[^>]+property=["']og:description["']/gi],
+      ['duplicate twitter:title', /<meta[^>]+name=["']twitter:title["']/gi],
+      ['duplicate twitter:card', /<meta[^>]+name=["']twitter:card["']/gi],
+    ]) {
+      if (countHead(head, dup[1]) > 1) fail(label, dup[0]);
+    }
+
+    // og/twitter CORE class. FAIL only when the page carries NO tag of the
+    // set at all: that is the "the engine failed to inject on a bare page"
+    // case the class exists to catch. A page shipping a PARTIAL set of its
+    // own (an SSG theme emitting only og:title, say) makes the engine's
+    // group-level missing-only gate back off the whole group BY DESIGN, so
+    // its missing companions are report-grade - failing them punished the
+    // very contract (SSG-owned partial sets) the injection rule preserves,
+    // and the audit cannot tell an SSG-owned partial head from an engine one.
+    const ogAny = countHead(head, /<meta[^>]+property=["']og:[^"']*["']/gi);
+    for (const prop of OG_CORE) {
+      if (grabMeta(head, 'property', prop)) continue;
+      if (ogAny === 0) fail(label, 'missing ' + prop);
+      else warn(label, prop + ' absent (page ships a partial og set; SSG-owned partial sets keep contract)');
+    }
+    for (const prop of OG_SET) {
+      if (!grabMeta(head, 'property', prop)) {
+        warn(label, prop + ' absent (part of the engine-injected set; SSG-owned partial sets keep contract)');
+      }
+    }
+    if (!grabMeta(head, 'property', 'og:image')) {
+      configGate('og:image', label);
+    }
+    const twAny = countHead(head, /<meta[^>]+name=["']twitter:[^"']*["']/gi);
+    for (const name of TW_CORE) {
+      if (grabMeta(head, 'name', name)) continue;
+      if (twAny === 0) fail(label, 'missing ' + name);
+      else warn(label, name + ' absent (page ships a partial twitter set; SSG-owned partial sets keep contract)');
+    }
+    for (const name of TW_SET) {
+      // Symmetry with the engine's own late pass (seo.js): without a
+      // configured handle the injector ships neither twitter:site nor
+      // twitter:creator, so the audit grades those absences only when the
+      // handle exists. The 'config-gated' wording in the warning now holds.
+      if ((name === 'twitter:site' || name === 'twitter:creator') && !config?.twitter?.username) continue;
+      if (!grabMeta(head, 'name', name)) {
+        // twitter:image is config-gated (no og.image -> the engine ships no
+        // twitter:image either): collapse it like og:image. The rest of the
+        // twitter set is SSG-owned-partial-set shaped and stays per-page.
+        if (name === 'twitter:image') configGate('twitter:image', label);
+        else warn(label, name + ' absent (config-gated or SSG-owned partial set; add a twitter username / og.image as needed)');
+      }
+    }
+
+    const ogImage = grabMeta(head, 'property', 'og:image');
+    if (ogImage && /\.svg(\?|#|$)/i.test(ogImage)) {
+      fail(label, 'og:image is SVG (' + ogImage + ') - most social scrapers cannot render it; ship a raster PNG/JPG');
+    }
+    if (ogImage && !grabMeta(head, 'property', 'og:image:width')) {
+      warn(label, 'og:image:width/height/alt absent (the og.image object form supplies them)');
+    }
+    if (ogImage) {
+      const info = sitePathInfo(ogImage, { outputDir, config });
+      if (info && !info.inside) {
+        // A site-local og:image that escapes the output tree can never be a
+        // served artifact; report it (same report-grade posture as missing).
+        warn(label, 'og:image points at ' + ogImage + ' which escapes the output directory');
+      } else if (info && !existsSync(info.resolved)) {
+        // Report-grade on purpose (issue #18 sketch: 'worth having'): an og
+        // image can legitimately be emitted on an SSG-side pass or a same-host
+        // CDN, so a hard FAIL would punish valid setups; the JSON digest
+        // carries it for teams who want to harden it in CI.
+        warn(label, 'og:image points at ' + ogImage + ' which does not exist on disk');
+      }
+    }
+
+    const ldBlocks = [...html.matchAll(/<script type=["']application\/ld\+json["'][^>]*>([\s\S]*?)<\/script>/gi)];
+    if (!ldBlocks.length && !noindex) warn(label, 'no JSON-LD structured data');
+    for (const block of ldBlocks) {
+      let parsed;
+      try { parsed = JSON.parse(block[1]); } catch (e) {
+        fail(label, 'invalid JSON-LD: ' + e.message);
+        continue;
+      }
+      const nodes = Array.isArray(parsed) ? parsed : (parsed['@graph'] ? parsed['@graph'] : [parsed]);
+      for (const node of nodes) {
+        if (!node || typeof node !== 'object') continue;
+        if (!node['@type']) { warn(label, 'JSON-LD node without @type'); continue; }
+        const types = Array.isArray(node['@type']) ? node['@type'] : [node['@type']];
+        if (types.includes('LocalBusiness')) {
+          const missing = LB_RECOMMENDED.filter(f => !(f in node));
+          if (missing.length) warn(label, 'LocalBusiness missing recommended: ' + missing.join(', '));
+        }
+        // schema-carried logo/image files: same exists-on-disk check as og:image
+        for (const key of ['logo', 'image']) {
+          const v = node[key];
+          const info = sitePathInfo(typeof v === 'string' ? v : null, { outputDir, config });
+          if (info && !info.inside) {
+            warn(label, 'JSON-LD ' + key + ' points at ' + v + ' which escapes the output directory');
+          } else if (info && !existsSync(info.resolved)) {
+            warn(label, 'JSON-LD ' + key + ' points at ' + v + ' which does not exist on disk');
+          }
+        }
+      }
+    }
+
+    const h1s = [...html.matchAll(/<h1[^>]*>([\s\S]*?)<\/h1>/gi)];
+    const h1Texts = h1s.map(m => stripTags(m[1])).filter(Boolean);
+    if (!h1Texts.length && !noindex) warn(label, 'no non-empty <h1>');
+    else if (h1Texts.length > 1) warn(label, h1Texts.length + ' <h1> elements (prefer one)');
+  }
+
+  // ---------- site-level artifacts ----------
+
+  // Honor the config's own generate switches: with `generateSitemap: false`
+  // (or robots), the run never writes the artifact, so its absence is the
+  // documented behavior, not a failure. The audit previously FAILed the
+  // missing file the config explicitly asked not to produce, so a
+  // legitimately-configured site could never pass its own audit. Configless
+  // audits (config === null) keep the strict check - absence is then a real
+  // gap. A DISABLED artifact that is present is still checked for shape.
+  const sitemapDisabled = config?.generateSitemap === false;
+  const sitemapPath = path.join(outputDir, 'sitemap.xml');
+  if (!existsSync(sitemapPath)) {
+    if (!sitemapDisabled) fail('sitemap.xml', 'missing');
+  } else {
+    const s = readFileSync(sitemapPath, 'utf8');
+    sitemapLocs = (s.match(/<loc>/g) || []).length;
+    if (sitemapLocs === 0) fail('sitemap.xml', 'no <loc> entries');
+    if (!s.includes('<lastmod>')) warn('sitemap.xml', 'no <lastmod> dates (engine runs always add them; hand-stripped?)');
+  }
+
+  const robotsDisabled = config?.generateRobots === false;
+  const robotsPath = path.join(outputDir, 'robots.txt');
+  if (!existsSync(robotsPath)) {
+    if (!robotsDisabled) fail('robots.txt', 'missing');
+  } else {
+    const r = readFileSync(robotsPath, 'utf8');
+    if (!/Sitemap:/i.test(r)) fail('robots.txt', 'no Sitemap: pointer');
+  }
+
+  // ---------- report ----------
+
+  // Flush config-gated absences as ONE line each (issue #28), with the
+  // affected-page count. Deterministic order (og:image before twitter:image).
+  // The og:image wording stays truthful when the config DOES supply an image
+  // but not for every page (og.scoped, ogImageGeneration): the line then
+  // reads "absent on N page(s)" rather than the false "not configured".
+  const ogScopedCfg = config?.og?.scoped;
+  const ogImageConfigured = Boolean(config?.og?.image)
+    || Boolean(config?.ogImageGeneration)
+    || Boolean(ogScopedCfg && typeof ogScopedCfg === 'object' && !Array.isArray(ogScopedCfg)
+      && Object.keys(ogScopedCfg).length > 0);
+  for (const [key, pages] of [...configGated.entries()].sort()) {
+    const n = pages.size;
+    let msg;
+    if (key === 'og:image') {
+      msg = ogImageConfigured
+        ? 'og:image absent on ' + n + ' page(s) - no og.image covers them (add one, or extend og.scoped)'
+        : 'og:image not configured - ' + n + ' page(s) affected (add one for share previews)';
+    } else {
+      // twitter:image ships alongside og:image (the injector derives it), so
+      // its absence tracks the same config state: "not configured" only when
+      // NO og image source exists at all, else "absent on N page(s)".
+      msg = ogImageConfigured
+        ? key + ' absent on ' + n + ' page(s) - no og.image covers them (add one, or extend og.scoped)'
+        : key + ' not configured - ' + n + ' page(s) affected (add a twitter username / og.image as needed)';
+    }
+    warn('config', msg);
+  }
+
+  if (capture) {
+    return { fails, warns, pages: pages.length, sitemapLocs };
+  }
+  if (json) {
+    console.log(JSON.stringify({ ok: fails.length === 0, pages: pages.length, fails, warns }));
+  } else {
+    console.log('[freestruct] SEO audit: ' + pages.length + ' baked page(s) checked, sitemap.xml has ' + sitemapLocs + ' <loc> entries');
+    for (const f of fails) console.log('  FAIL ' + f.page + ': ' + f.msg);
+    for (const w of warns) console.log('  WARN ' + w.page + ': ' + w.msg);
+    if (fails.length === 0) {
+      console.log('[freestruct] audit: 0 failures, ' + warns.length + ' warning(s) - clean');
+    } else {
+      console.log('[freestruct] audit: ' + fails.length + ' failure(s), ' + warns.length + ' warning(s) - exiting 1');
+    }
+  }
+  return { fails, warns, pages: pages.length, sitemapLocs };
+}
+
+// ---------- external links (opt-in, SEO-gap pass) ----------
+
+const EXTERNAL_LIMIT = 50;
+
+/** Collect external http(s) href URLs from the baked pages, deduped, with referencing pages. */
+function collectExternalLinks({ outputDir, pages }) {
+  const byUrl = new Map();
+  for (const filePath of pages) {
+    let rel;
+    try { rel = path.relative(outputDir, filePath).replace(/\\/g, '/'); } catch (e) { rel = filePath; }
+    const html = readFileSync(filePath, 'utf8');
+    for (const m of html.matchAll(/href\s*=\s*["'](https?:\/\/[^"'\s]+)["']/gi)) {
+      const url = m[1].replace(/&amp;/g, '&');
+      if (!byUrl.has(url)) byUrl.set(url, []);
+      byUrl.get(url).push(rel);
+    }
+  }
+  return byUrl;
+}
+
+/** HEAD with a GET retry (some CDNs refuse HEAD); returns the problem string or null. */
+async function headCheck(url) {
+  const tryOnce = async (method) => {
+    const res = await fetch(url, {
+      method,
+      redirect: 'follow',
+      signal: AbortSignal.timeout(8000),
+      headers: { 'user-agent': 'freestruct-audit (+https://github.com/dhaupin/freestruct)' },
+    });
+    return res.status >= 400 ? 'HTTP ' + res.status + (res.statusText ? ' ' + res.statusText : '') : null;
+  };
+  try {
+    return await tryOnce('HEAD');
+  } catch (headErr) {
+    try {
+      return await tryOnce('GET');
+    } catch (getErr) {
+      const cause = (getErr && getErr.cause && getErr.cause.code) ? getErr.cause.code : getErr.message;
+      return 'unreachable (' + cause + ')';
+    }
+  }
+}
+
+/**
+ * External-link audit (opt-in): dedupe the tree's external hrefs, HEAD-check
+ * up to EXTERNAL_LIMIT unique URLs, report every failure as a WARN row
+ * (report-grade by design: bots get 403/429 legitimately). NEVER exits.
+ */
+export async function auditExternalLinks({ outputDir, json = false }) {
+  const empty = { warns: [], checked: 0 };
+  if (!existsSync(outputDir)) return empty;
+  const pages = walkHtml(outputDir);
+  const byUrl = collectExternalLinks({ outputDir, pages });
+  if (byUrl.size === 0) return empty;
+  const capped = [...byUrl.keys()].slice(0, EXTERNAL_LIMIT);
+  const results = await Promise.all(capped.map(async (url) => [url, await headCheck(url)]));
+  const warns = [];
+  for (const [url, problem] of results) {
+    if (!problem) continue;
+    const referencing = byUrl.get(url);
+    const label = referencing.length > 1
+      ? referencing[0] + ' (+' + (referencing.length - 1) + ' more page(s))'
+      : referencing[0];
+    warns.push({ page: label, msg: 'external link ' + url + ': ' + problem });
+  }
+  if (byUrl.size > EXTERNAL_LIMIT) {
+    warns.push({ page: 'external', msg: 'checked only the first ' + EXTERNAL_LIMIT + ' unique external urls of ' + byUrl.size });
+  }
+  if (!json && warns.length > 0) {
+    console.log('[freestruct] external link check: ' + capped.length + ' unique url(s) probed');
+    for (const w of warns) console.log('  WARN ' + w.page + ': ' + w.msg);
+  }
+  return { warns, checked: capped.length };
+}