@wix/agent-skills 1.36.0 → 1.36.1

package/skills/wix-replatform/lib/internal-link-reconciliation.js

@@ -1,166 +0,0 @@
-'use strict';
-
-const { createHash } = require('node:crypto');
-const { isDeepStrictEqual } = require('node:util');
-
-function exactHosts(hosts) {
-  return new Set((hosts || []).map((host) => new URL(`https://${host}`).host.toLowerCase()));
-}
-
-function classifyNavigation(value, containingUrl, { sourceHosts = [], destinationHosts = [] } = {}) {
-  if (typeof value !== 'string' || !value) return { kind: 'invalid' };
-  if (/^(?:javascript|data|mailto|tel):/i.test(value)) return { kind: 'action', value };
-  let url;
-  try { url = new URL(value, containingUrl); } catch { return { kind: 'invalid', value }; }
-  if (!['http:', 'https:'].includes(url.protocol)) return { kind: 'external', value };
-  const hosts = exactHosts([...sourceHosts, ...destinationHosts]);
-  if (!hosts.has(url.host.toLowerCase())) return { kind: 'external', value };
-  const path = `${url.pathname}${url.search}${url.hash}`;
-  const stateful = /^\/(?:wp-admin|wp-login|account\/login|checkout\/order-pay)(?:\/|$)/i.test(url.pathname)
-    || [...url.searchParams.keys()].some((key) => /^(?:nonce|_wpnonce|token|auth|session|add-to-cart|remove_item|order-pay)$/i.test(key));
-  if (stateful) return { kind: 'stateful', original: value, path, host: url.host.toLowerCase() };
-  return { kind: 'internal', original: value, path, lookupPath: `${url.pathname}${url.search}`, host: url.host.toLowerCase(), fragmentOnly: value.startsWith('#') };
-}
-
-function occurrenceId({ sourceFile, sourceRecordId = '', field, location, original }) {
-  return createHash('sha256').update([sourceFile, sourceRecordId, field, location, original].join('\0')).digest('hex').slice(0, 24);
-}
-
-function verifiedDestination(row) {
-  if (!row || !row.targetRecordId || !row.path || !row.pageFamily || !row.deploymentId || !row.routeRevision || !row.checkedAt || row.identityMatched !== true || row.rendered !== true) {
-    throw new Error('verified destination requires target identity, served path and current deployment evidence');
-  }
-  if (!row.path.startsWith('/') || row.path.startsWith('//')) throw new Error('verified path must be root-relative');
-  return row;
-}
-
-function writerGuard(field, activeWriters, recordType) {
-  if (recordType === 'blog-post') return { ok: false, reason: 'blog-writer-integration-pending' };
-  if (!activeWriters || activeWriters.complete !== true || !Array.isArray(activeWriters.writers) || activeWriters.writers.some((row) => !row || !Array.isArray(row.fields))) {
-    return { ok: false, reason: 'unknown-writer-contract' };
-  }
-  const touching = activeWriters.writers.filter((row) => row.fields.includes(field));
-  if (touching.length !== 1 || touching[0].writer !== 'internal-link-reconciler' || touching[0].compatible !== true || touching[0].runsAfter !== 'post-frontend-verification') {
-    return { ok: false, reason: 'incompatible-writer-contract' };
-  }
-  return { ok: true };
-}
-
-// Mutation is per logical record. A guarded field may proceed while another field is held.
-// The adapter owns native field serialization; this function never edits blog post fields.
-async function reconcileRecord({ recordId, recordType, fields, destinations, activeWriters, destinationState, adapter, journal, intentKey = null, priorIntentKeys = [] }) {
-  if (!adapter || typeof adapter.patchField !== 'function' || !journal || !recordId) throw new Error('record, structured patch adapter and journal required');
-  if (destinationState !== 'migration-not-live') throw new Error('content writes require a confirmed non-live migration destination');
-  const blocked = [];
-  const eligible = [];
-  for (const field of fields) {
-    const guard = writerGuard(`${recordType}:${field.name}`, activeWriters, recordType);
-    if (!guard.ok) { blocked.push({ field: field.name, occurrenceIds: field.occurrenceIds, reason: guard.reason }); continue; }
-    const destination = field.patches ? null : destinations[field.destinationId];
-    if (field.patches) {
-      if (!field.patches.length || field.patches.some((patch) => {
-        try { verifiedDestination(destinations[patch.destinationId]); return false; } catch { return true; }
-      })) {
-        blocked.push({ field: field.name, occurrenceIds: field.occurrenceIds, reason: 'destination-unverified' }); continue;
-      }
-      eligible.push({ field, destination: null });
-      continue;
-    }
-    if (field.unresolvedNormalization === true) {
-      if (!destination || !destination.path || !destination.path.startsWith('/') || destination.path.startsWith('//')) {
-        blocked.push({ field: field.name, occurrenceIds: field.occurrenceIds, reason: 'unresolved-original-path-invalid' }); continue;
-      }
-    } else {
-      try { verifiedDestination(destination); } catch {
-        blocked.push({ field: field.name, occurrenceIds: field.occurrenceIds, reason: 'destination-unverified' }); continue;
-      }
-    }
-    eligible.push({ field, destination });
-  }
-  if (!eligible.length) return { recordId, blocked, written: [] };
-  const current = await adapter.read(recordId);
-  if (!current || !current.revision) throw new Error('content read needs revision');
-  if (intentKey && typeof journal.findCompleted === 'function') {
-    const completed = await journal.findCompleted(recordId, intentKey);
-    if (completed) {
-      if (!completed.changes.every((change) => isDeepStrictEqual(current.fields[change.name], change.after))) throw new Error('completed link repair conflicts with changed content');
-      return { recordId, blocked, written: completed.changes.map((change) => change.name), resumed: true, contentRevision: current.revision };
-    }
-  }
-  if (intentKey && typeof journal.findOpen === 'function') {
-    const open = await journal.findOpen(recordId, intentKey);
-    if (open) {
-      if (open.changes.every((change) => isDeepStrictEqual(current.fields[change.name], change.after))) {
-        await journal.complete(open);
-        return { recordId, blocked, written: open.changes.map((change) => change.name), resumed: true, contentRevision: current.revision };
-      }
-      if (current.revision !== open.baseRevision) throw new Error('uncertain write conflicts with changed content');
-      await adapter.write(recordId, Object.fromEntries(open.changes.map((change) => [change.name, change.after])), current.revision);
-      const readBack = await adapter.read(recordId);
-      if (!open.changes.every((change) => isDeepStrictEqual(readBack.fields[change.name], change.after))) throw new Error('content write read-back mismatch');
-      await journal.complete(open);
-      return { recordId, blocked, written: open.changes.map((change) => change.name), resumed: true, contentRevision: readBack.revision };
-    }
-  }
-  // A frontend redeploy invalidates served-link evidence, not a completed content write.
-  // Reuse the exact journaled after-image only when it still matches the current record.
-  if (typeof journal.findCompleted === 'function') {
-    for (const priorKey of priorIntentKeys) {
-      const completed = await journal.findCompleted(recordId, priorKey);
-      if (!completed || !eligible.every(({ field }) => completed.changes.some((change) =>
-        change.name === field.name && field.occurrenceIds.every((id) => change.occurrenceIds.includes(id)))) ||
-          !completed.changes.every((change) => isDeepStrictEqual(current.fields[change.name], change.after))) continue;
-      return { recordId, blocked, written: eligible.map(({ field }) => field.name), resumed: true, contentRevision: current.revision, priorIntentKey: priorKey };
-    }
-  }
-  for (const { field } of eligible) {
-    if (field.expectedRevision && field.expectedRevision !== current.revision) {
-      blocked.push({ field: field.name, occurrenceIds: field.occurrenceIds, reason: 'concurrent-edit' });
-    }
-  }
-  if (blocked.some((row) => row.reason === 'concurrent-edit')) return { recordId, blocked, written: [] };
-  const intended = eligible.map(({ field, destination }) => {
-    const baseValue = field.baseValue === undefined ? current.fields[field.name] : field.baseValue;
-    let patch;
-    if (field.patches) {
-      const ordered = [...field.patches].sort((a, b) => {
-        const offset = (row) => Number(/char:(\d+)/.exec(row.occurrence.location || '')?.[1] || 0);
-        return offset(b) - offset(a);
-      });
-      patch = { value: baseValue, preservedUnrelated: true, changedLocations: [] };
-      for (const row of ordered) {
-        const next = adapter.patchField(patch.value, row.occurrence, row.path);
-        if (!next || next.preservedUnrelated !== true || !next.changedLocations?.length) throw new Error(`field ${field.name} lacks a verified structured link patch`);
-        patch = { value: next.value, preservedUnrelated: true, changedLocations: [...patch.changedLocations, ...next.changedLocations] };
-      }
-    } else patch = adapter.patchField(baseValue, field, destination.path);
-    if (!patch || patch.preservedUnrelated !== true || !Array.isArray(patch.changedLocations) || !patch.changedLocations.length) {
-      throw new Error(`field ${field.name} lacks a verified structured link patch`);
-    }
-    return { name: field.name, before: baseValue, after: patch.value, occurrenceIds: field.occurrenceIds, changedLocations: patch.changedLocations };
-  });
-  const attempt = intentKey ? null : await journal.find(recordId, intended);
-  if (attempt && intended.every((change) => isDeepStrictEqual(current.fields[change.name], change.after))) {
-    await journal.complete(attempt);
-    return { recordId, blocked, written: intended.map((change) => change.name), resumed: true };
-  }
-  if (attempt && current.revision !== attempt.baseRevision) throw new Error('uncertain write conflicts with changed content');
-  const changes = [];
-  for (const { field, destination } of eligible) {
-    if (!isDeepStrictEqual(current.fields[field.name], field.baseValue === undefined ? current.fields[field.name] : field.baseValue)) {
-      blocked.push({ field: field.name, occurrenceIds: field.occurrenceIds, reason: 'concurrent-edit' });
-    } else {
-      const intendedChange = intended.find((row) => row.name === field.name);
-      if (!isDeepStrictEqual(current.fields[field.name], intendedChange.after)) changes.push(intendedChange);
-    }
-  }
-  if (!changes.length) return { recordId, blocked, written: [] };
-  const started = attempt || await journal.start(recordId, current.revision, changes, intentKey);
-  await adapter.write(recordId, Object.fromEntries(changes.map((change) => [change.name, change.after])), current.revision);
-  const readBack = await adapter.read(recordId);
-  if (!changes.every((change) => isDeepStrictEqual(readBack.fields[change.name], change.after))) throw new Error('content write read-back mismatch');
-  await journal.complete(started);
-  return { recordId, blocked, written: changes.map((change) => change.name), contentRevision: readBack.revision };
-}
-
-module.exports = { classifyNavigation, occurrenceId, verifiedDestination, writerGuard, reconcileRecord };

package/skills/wix-replatform/lib/link-audit.js

@@ -1,173 +0,0 @@
-'use strict';
-
-const fs = require('node:fs/promises');
-const path = require('node:path');
-
-const RELATIVE_PATH = 'state/url-preservation/link-audit.json';
-const UNRESOLVED_REASONS = new Set([
-  'target-not-imported', 'source-broken', 'collision', 'ambiguous-target', 'unsupported-family',
-]);
-const INTEGRATION_PROMPT = 'Resume internal-link writer integration for the listed audit records: establish exclusive ownership of each content field, keep source-origin URL rewriting limited to non-content configuration, and connect the dedicated blog-post link writer to verified destinations and a checkpointed post-frontend update, publish and read-back phase. Run the scoped compatibility and end-to-end checks, resume only compatible writers, and return the refreshed link audit, report and handoff. If a required writer or lifecycle is unavailable, keep the affected repairs pending and report the missing contract.';
-const ROUTE_PROMPT = "Resume app page routing for the listed page families and original paths: inspect the destination's current route configuration, apply the supported source-matching configuration, record any unsupported family with its actual Wix destination and redirect requirement, and return the refreshed capability matrix, configuration read-back and report.";
-const UNRESOLVED_PROMPT = 'Resume app routing and internal-link reconciliation for the listed audit occurrence IDs; obtain missing capture/adapter access, resolve intended targets, apply approved repairs, and return the refreshed link audit and report.';
-const PENDING_PROMPT = 'Run the post-frontend routing and link verification step for this migration: confirm the frontend deployment origin and mount path, read back generated entity URLs, run the read-only calibration and budget estimate, and only within the approved budget check the per-family samples and verify and repair the stored destinations, and return the refreshed link audit and report.';
-const UNAVAILABLE_PROMPT = 'Rerun internal-link verification for the listed audit occurrence and destination IDs against the current Wix deployment: confirm deployment origin, mount path, permissions and safe session fixtures, re-check route identity, rendered links, fragments and actions, and return the refreshed link audit and report.';
-const BUDGET_PROMPT = 'Present the recorded link counts, estimate and budget to the migration owner and request a decision to continue, reduce scope or stop. Then resume verification and repair for the listed audit within the approved limit and return the refreshed link audit and report.';
-
-function auditPath(projectDir) {
-  return path.join(projectDir, RELATIVE_PATH);
-}
-
-function nonempty(value, label) {
-  if (typeof value !== 'string' || !value) throw new Error(`${label} must be a non-empty string`);
-  return value;
-}
-
-function unique(values, label) {
-  if (!Array.isArray(values) || values.some((value) => typeof value !== 'string' || !value)) {
-    throw new Error(`${label} must be an array of non-empty strings`);
-  }
-  if (new Set(values).size !== values.length) throw new Error(`${label} contains duplicates`);
-}
-
-// The queues partition navigation occurrences. A missing or duplicated occurrence must never
-// disappear from cutover just because a backend import succeeded.
-function validateLinkAudit(audit) {
-  if (!audit || audit.schemaVersion !== 1) throw new Error('link audit schemaVersion must be 1');
-  if (audit.postDnsStatus === 'verified' && (!audit.postDnsEvidence || !audit.postDnsEvidence.host || !audit.postDnsEvidence.checkedAt || audit.postDnsEvidence.wixIdentityMatched !== true)) {
-    throw new Error('verified post-DNS status requires public-host Wix identity evidence');
-  }
-  const occurrences = audit.occurrences || [];
-  const pending = audit.pendingDestinations || [];
-  const unresolved = audit.unresolved || [];
-  const outcomes = audit.outcomes || [];
-  const ids = new Set();
-  for (const row of occurrences) {
-    nonempty(row.id, 'occurrence.id');
-    if (ids.has(row.id)) throw new Error(`duplicate occurrence ${row.id}`);
-    ids.add(row.id);
-  }
-  const assigned = new Map();
-  const assign = (id, location) => {
-    if (!ids.has(id)) throw new Error(`${location} references missing occurrence ${id}`);
-    if (assigned.has(id)) throw new Error(`occurrence ${id} appears in both ${assigned.get(id)} and ${location}`);
-    assigned.set(id, location);
-  };
-  for (const row of pending) {
-    nonempty(row.id, 'pending.id');
-    nonempty(row.targetRecordId, 'pending.targetRecordId');
-    nonempty(row.expectedPath, 'pending.expectedPath');
-    if (!row.expectedPath.startsWith('/') || row.expectedPath.startsWith('//')) throw new Error('pending.expectedPath must be root-relative');
-    nonempty(row.pageFamily, 'pending.pageFamily');
-    unique(row.occurrenceIds, 'pending.occurrenceIds');
-    row.occurrenceIds.forEach((id) => assign(id, `pending ${row.id}`));
-  }
-  for (const row of unresolved) {
-    nonempty(row.id, 'unresolved.id');
-    if ('expectedPath' in row) throw new Error('unresolved entries cannot carry expectedPath');
-    if (!UNRESOLVED_REASONS.has(row.reason)) throw new Error(`invalid unresolved reason ${row.reason}`);
-    unique(row.occurrenceIds, 'unresolved.occurrenceIds');
-    row.occurrenceIds.forEach((id) => assign(id, `unresolved ${row.id}`));
-  }
-  for (const row of outcomes) {
-    nonempty(row.occurrenceId, 'outcome.occurrenceId');
-    nonempty(row.status, 'outcome.status');
-    assign(row.occurrenceId, 'outcome');
-  }
-  for (const id of ids) if (!assigned.has(id)) throw new Error(`unaccounted navigation occurrence ${id}`);
-  for (const row of audit.writerIntegrations || []) {
-    nonempty(row.field, 'writerIntegration.field');
-    nonempty(row.status, 'writerIntegration.status');
-    unique(row.occurrenceIds || [], 'writerIntegration.occurrenceIds');
-    for (const id of row.occurrenceIds || []) if (!ids.has(id)) throw new Error(`writer integration references missing occurrence ${id}`);
-  }
-  return audit;
-}
-
-async function readLinkAudit(projectDir) {
-  try {
-    return validateLinkAudit(JSON.parse(await fs.readFile(auditPath(projectDir), 'utf8')));
-  } catch (error) {
-    if (error.code === 'ENOENT') return null;
-    throw error;
-  }
-}
-
-async function writeLinkAudit(projectDir, audit) {
-  validateLinkAudit(audit);
-  const target = auditPath(projectDir);
-  await fs.mkdir(path.dirname(target), { recursive: true });
-  const temporary = `${target}.${process.pid}.${Date.now()}.tmp`;
-  try {
-    await fs.writeFile(temporary, `${JSON.stringify(audit, null, 2)}\n`);
-    await fs.rename(temporary, target);
-  } finally {
-    await fs.rm(temporary, { force: true });
-  }
-  return target;
-}
-
-function linkOperatorActions(audit) {
-  if (!audit) return [];
-  validateLinkAudit(audit);
-  const actions = [];
-  const pendingWriter = (audit.writerIntegrations || []).filter((row) => row.status === 'pending');
-  if (pendingWriter.length) {
-    actions.push({
-      code: 'link_writer_integration', severity: 'high',
-      action: `Requires Import Operator. ${INTEGRATION_PROMPT} Affected fields: ${pendingWriter.map((row) => row.field).join(', ')}. Evidence: ${RELATIVE_PATH}.`,
-      deadlineReason: 'After compatible writers and lifecycle are available, before DNS; destination checks alone do not complete content repair.',
-      entity: 'internal-links', affectedCount: new Set(pendingWriter.flatMap((row) => row.occurrenceIds)).size,
-    });
-  }
-  const ownershipGaps = audit.unresolved.filter((row) => row.detail !== 'fragment-anchor-unverified');
-  if (ownershipGaps.length) actions.push({
-    code: 'unresolved_internal_links', severity: 'high',
-    action: `Requires Import Operator. ${UNRESOLVED_PROMPT} Evidence: ${RELATIVE_PATH}; ambiguous ownership needs a human decision.`,
-    deadlineReason: 'Before website handoff; unresolved navigation can open missing or wrong pages.',
-    entity: 'internal-links', affectedCount: ownershipGaps.reduce((count, row) => count + row.occurrenceIds.length, 0),
-  });
-  const routeIssues = (audit.routes || []).filter((row) => !['configured', 'reused'].includes(row.status));
-  if (routeIssues.length) actions.push({
-    code: 'app_route_configuration', severity: 'high',
-    action: `Requires Import Operator. ${ROUTE_PROMPT} Evidence: ${RELATIVE_PATH}. Conflicting ownership needs a human decision.`,
-    deadlineReason: 'After apps are installed and before DNS; a planned or unsupported route is not a served page.',
-    entity: 'app-routes', affectedCount: routeIssues.length,
-  });
-  const scanGaps = (audit.manifest || []).filter((row) => ['unsupported', 'unsupported-construct', 'unreadable', 'missing'].includes(row.disposition));
-  if (scanGaps.length) actions.push({
-    code: 'internal_link_scan_gaps', severity: 'high',
-    action: `Requires Import Operator. ${UNRESOLVED_PROMPT} Evidence: ${RELATIVE_PATH}.`,
-    deadlineReason: 'Before website handoff; unsupported or unreadable files cannot count as verified link coverage.',
-    entity: 'internal-links', affectedCount: scanGaps.length,
-  });
-  if (audit.stage !== 'verified' || audit.pendingDestinations.length) actions.push({
-    code: 'pending_link_verification', severity: 'high',
-    action: `Requires Import Operator. ${PENDING_PROMPT} Evidence: ${RELATIVE_PATH}.`,
-    deadlineReason: 'After frontend creation and before DNS; planned paths have not been shown to serve intended pages.',
-    entity: 'internal-links', affectedCount: audit.pendingDestinations.reduce((count, row) => count + row.occurrenceIds.length, 0),
-  });
-  const unavailable = (audit.pendingDestinations || []).filter((row) => row.reason && row.reason !== 'writer-or-link-verification-pending');
-  const fragmentGaps = (audit.unresolved || []).filter((row) => row.detail === 'fragment-anchor-unverified');
-  if (unavailable.length || fragmentGaps.length) actions.push({
-    code: 'link_verification_unavailable', severity: 'high',
-    action: `Requires Import Operator. ${UNAVAILABLE_PROMPT} Evidence: ${RELATIVE_PATH}.`,
-    deadlineReason: 'Before DNS; a served-page response alone does not prove link behavior, fragments or current content.',
-    entity: 'internal-links', affectedCount: unavailable.reduce((sum, row) => sum + row.occurrenceIds.length, 0) + fragmentGaps.reduce((sum, row) => sum + row.occurrenceIds.length, 0),
-  });
-  if (audit.stage === 'budget-hold') actions.push({
-    code: 'link_verification_budget', severity: 'high',
-    action: `Requires Import Operator. ${BUDGET_PROMPT} Evidence: ${RELATIVE_PATH}.`,
-    deadlineReason: 'The approved 30-minute live-work or 100,000 exception-review-token ceiling would be exceeded; resume only after an explicit decision.',
-    entity: 'internal-links', affectedCount: audit.pendingDestinations.reduce((count, row) => count + row.occurrenceIds.length, 0),
-  });
-  if (audit.postDnsStatus !== 'verified') actions.push({
-    code: 'post_dns_route_check', severity: 'medium',
-    action: `Cutover Operator: after DNS and HTTPS readiness, check the public host against the routes listed in ${RELATIVE_PATH}; return any local repair to the Import Operator.`,
-    deadlineReason: 'After DNS; preview-host checks do not prove the final public route.',
-    entity: 'app-routes', affectedCount: (audit.routes || []).length,
-  });
-  return actions;
-}
-
-module.exports = { RELATIVE_PATH, auditPath, validateLinkAudit, readLinkAudit, writeLinkAudit, linkOperatorActions };

package/skills/wix-replatform/lib/link-census.js

@@ -1,194 +0,0 @@
-'use strict';
-
-const fs = require('node:fs/promises');
-const path = require('node:path');
-const { createHash } = require('node:crypto');
-const { classifyNavigation, occurrenceId } = require('./internal-link-reconciliation.js');
-
-const NAV_KEYS = new Set(['href', 'url', 'link', 'destination', 'targetUrl']);
-const RESOURCE_KEYS = new Set(['src', 'srcset', 'image', 'media', 'download', 'backgroundImage']);
-const IGNORED_SEGMENTS = new Set(['config', '.git', 'node_modules', 'secrets']);
-
-function hash(value) { return createHash('sha256').update(value).digest('hex'); }
-
-function decodeHtmlEntities(value) {
-  return value.replace(/&(#(?:x[0-9a-f]+|[0-9]+)|amp|quot|apos|lt|gt);/gi, (_whole, entity) => {
-    if (entity[0] === '#') {
-      const number = entity[1].toLowerCase() === 'x' ? parseInt(entity.slice(2), 16) : parseInt(entity.slice(1), 10);
-      return number > 0 && number <= 0x10ffff ? String.fromCodePoint(number) : _whole;
-    }
-    return { amp: '&', quot: '"', apos: "'", lt: '<', gt: '>' }[entity.toLowerCase()];
-  });
-}
-
-// Tokenizes tags and quoted attributes. It does not treat arbitrary angle-bracket text as a
-// successful parse: malformed markup produces an explicit unsupported disposition.
-function htmlAttributes(html) {
-  const found = [];
-  let index = 0;
-  while (index < html.length) {
-    const open = html.indexOf('<', index);
-    if (open < 0) break;
-    if (html.startsWith('<!--', open)) {
-      const close = html.indexOf('-->', open + 4);
-      if (close < 0) throw new Error('unterminated HTML comment');
-      const comment = html.slice(open + 4, close).trim();
-      if (comment.startsWith('wp:')) {
-        const jsonStart = comment.indexOf('{');
-        const jsonEnd = comment.lastIndexOf('}');
-        if (jsonStart >= 0 && jsonEnd > jsonStart) {
-          try {
-            for (const link of extractJson(JSON.parse(comment.slice(jsonStart, jsonEnd + 1)))) found.push({ ...link, location: `block:${open}:${link.location}` });
-          } catch { throw new Error('unsupported WordPress block attributes'); }
-        }
-      }
-      index = close + 3; continue;
-    }
-    let cursor = open + 1;
-    if (!/[A-Za-z/!?]/.test(html[cursor] || '')) { index = cursor; continue; }
-    let quote = null;
-    for (; cursor < html.length; cursor += 1) {
-      const char = html[cursor];
-      if (quote) { if (char === quote) quote = null; }
-      else if (char === '"' || char === "'") quote = char;
-      else if (char === '>') break;
-    }
-    if (cursor >= html.length) throw new Error('unterminated HTML tag');
-    const tag = html.slice(open + 1, cursor);
-    const attr = /(?:^|\s)(href|action|src|srcset)\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s>]+))/gi;
-    let match;
-    while ((match = attr.exec(tag))) found.push({ key: match[1].toLowerCase(), value: decodeHtmlEntities(match[2] ?? match[3] ?? match[4]), location: `char:${open + 1 + match.index + match[0].indexOf(match[1])}` });
-    index = cursor + 1;
-  }
-  return found;
-}
-
-function countMetadataHrefs(value) {
-  if (Array.isArray(value)) return value.reduce((count, item) => count + countMetadataHrefs(item), 0);
-  if (!value || typeof value !== 'object') return 0;
-  return Object.entries(value).reduce((count, [key, child]) => count + (key === 'href' && typeof child === 'string' ? 1 : countMetadataHrefs(child)), 0);
-}
-
-function extractJson(value, location = '$', output = [], contentField = null, stats = null) {
-  if (Array.isArray(value)) { value.forEach((item, index) => extractJson(item, `${location}[${index}]`, output, contentField, stats)); return output; }
-  if (!value || typeof value !== 'object') return output;
-  for (const [key, child] of Object.entries(value)) {
-    if (key === '_links' || key === '_embedded') {
-      if (stats) stats.metadataHrefsSkipped = (stats.metadataHrefsSkipped || 0) + countMetadataHrefs(child);
-      continue;
-    }
-    if (key === 'yoast_head' || key === 'yoast_head_json') {
-      if (stats && key === 'yoast_head' && typeof child === 'string') {
-        stats.metadataHrefsSkipped = (stats.metadataHrefsSkipped || 0) + (child.match(/(?:^|\s)href\s*=/gi) || []).length;
-      }
-      continue;
-    }
-    const next = `${location}.${key}`;
-    const owningField = contentField || (['records', 'items', 'data', 'entities'].includes(key) ? null : key);
-    if (typeof child === 'string') {
-      const resourceContext = /(?:^|\.)(?:image|media|attachment|thumbnail|download|logo|icon|background)(?:\.|\[|$)/i.test(location);
-      const navigationContext = /(?:^|\.)(?:content|body|description|button|menu|recommendation|link|anchor|action|richContent)(?:\.|\[|$)/i.test(location);
-      if (RESOURCE_KEYS.has(key) || resourceContext && key === 'url') output.push({ key, value: child, location: next, contentField: owningField, resource: true });
-      else if (NAV_KEYS.has(key) && (key === 'href' || key === 'targetUrl' || key === 'destination' || navigationContext)) output.push({ key, value: child, location: next, contentField: owningField });
-      else if (/<[a-z][^>]*>/i.test(child)) for (const attr of htmlAttributes(child)) output.push({ ...attr, contentField: owningField, location: `${next}:${attr.location}` });
-    } else extractJson(child, next, output, owningField, stats);
-  }
-  return output;
-}
-
-function extractFile(file, raw, stats = null) {
-  const ext = path.extname(file).toLowerCase();
-  if (ext === '.json') return extractJson(JSON.parse(raw), '$', [], null, stats);
-  if (ext === '.html' || ext === '.htm') return htmlAttributes(raw);
-  // CSS URLs are resources, not automatically navigational links.
-  if (ext === '.css') return [];
-  throw new Error('unsupported-format');
-}
-
-function containingRecord(file, location, containingPages) {
-  const config = containingPages[file];
-  if (typeof config === 'string') return { url: config, recordId: null };
-  if (!config || typeof config !== 'object') return null;
-  const prefix = Object.keys(config).filter((key) => location.startsWith(key)).sort((a, b) => b.length - a.length)[0];
-  if (!prefix) return null;
-  const row = config[prefix];
-  return typeof row === 'string' ? { url: row, recordId: null } : row;
-}
-
-async function walk(root, relative = '') {
-  const entries = await fs.readdir(path.join(root, relative), { withFileTypes: true });
-  const files = [];
-  for (const entry of entries) {
-    if (IGNORED_SEGMENTS.has(entry.name) || entry.name.startsWith('.')) continue;
-    const next = path.join(relative, entry.name);
-    if (entry.isDirectory()) files.push(...await walk(root, next));
-    else if (entry.isFile()) files.push(next);
-  }
-  return files;
-}
-
-async function census({ capturedRoots, expectedFiles = [], sourceHosts, destinationHosts, containingPages = {}, previous = null }) {
-  if (!Array.isArray(capturedRoots) || !capturedRoots.length) throw new Error('capturedRoots required');
-  const started = Date.now();
-  const manifest = [];
-  const occurrences = [];
-  for (const root of capturedRoots) {
-    const files = await walk(root);
-    for (const relative of files) {
-      const file = path.join(root, relative);
-      let raw;
-      try { raw = await fs.readFile(file); }
-      catch (error) { manifest.push({ file, disposition: 'unreadable', reason: error.code || 'read-error' }); continue; }
-      const digest = hash(raw);
-      const base = { file, bytes: raw.length, sha256: digest };
-      const old = previous && previous.censusVersion === 4 && previous.manifest && previous.manifest.find((row) => row.file === file && row.sha256 === digest);
-      if (old && previous.occurrences) {
-        manifest.push({ ...base, disposition: old.disposition, reason: old.reason || null, metadataHrefsSkipped: old.metadataHrefsSkipped || 0 });
-        occurrences.push(...previous.occurrences.filter((row) => row.sourceFile === file));
-        continue;
-      }
-      let links;
-      const scanStats = {};
-      try { links = extractFile(file, raw.toString('utf8'), scanStats); }
-      catch (error) { manifest.push({ ...base, disposition: 'unsupported', reason: error.message }); continue; }
-      const possibleUnparsedLink = !links.length && /https?:\/\/|href\s*=|location\.href/i.test(raw.toString('utf8')) && !scanStats.metadataHrefsSkipped;
-      manifest.push({ ...base, disposition: links.length ? 'scanned-links' : possibleUnparsedLink ? 'unsupported-construct' : 'scanned-no-links', metadataHrefsSkipped: scanStats.metadataHrefsSkipped || 0 });
-      for (const link of links) {
-        if (link.resource || RESOURCE_KEYS.has(link.key)) continue;
-        const containing = containingRecord(file, link.location, containingPages);
-        const containingUrl = containing && containing.url;
-        if (!containingUrl) {
-          // An absolute off-site URL needs no containing page to classify it.
-          if (/^https?:\/\//i.test(link.value) || /^\/\//.test(link.value)) {
-            const absolute = classifyNavigation(link.value, 'https://link-audit.invalid/', { sourceHosts, destinationHosts });
-            if (absolute.kind === 'external') continue;
-          }
-          occurrences.push({ id: occurrenceId({ sourceFile: file, field: link.key, location: link.location, original: link.value }), sourceFile: file, field: link.key, location: link.location, original: link.value, classification: 'missing-containing-page' });
-          continue;
-        }
-        const classification = classifyNavigation(link.value, containingUrl, { sourceHosts, destinationHosts });
-        if (classification.kind !== 'internal' && classification.kind !== 'stateful') continue;
-        occurrences.push({
-          id: occurrenceId({ sourceFile: file, field: link.key, location: link.location, original: link.value }),
-          sourceFile: file, sourceRecordId: containing.recordId || null, targetRecordId: containing.targetRecordId || null,
-          recordType: containing.recordType || null, targetContentRevision: containing.targetContentRevision || null,
-          field: containing.contentField || link.contentField || link.key, location: link.location, containingUrl,
-          original: link.value, classification: classification.kind === 'stateful' ? 'stateful-navigation' : 'internal-navigation',
-          originalPath: classification.path, ...(classification.fragmentOnly ? { fragmentOnly: true } : {}),
-        });
-      }
-    }
-  }
-  const scannedFiles = new Set(manifest.map((row) => row.file));
-  for (const file of expectedFiles) if (!scannedFiles.has(file)) manifest.push({ file, disposition: 'missing', reason: 'capture-file-absent' });
-  return { manifest, occurrences, counts: {
-    files: manifest.length, bytes: manifest.reduce((sum, row) => sum + (row.bytes || 0), 0),
-    internalOccurrences: occurrences.filter((row) => ['internal-navigation', 'stateful-navigation'].includes(row.classification)).length,
-    distinctInternalDestinations: new Set(occurrences.filter((row) => row.originalPath).map((row) => row.originalPath)).size,
-    unsupportedFiles: manifest.filter((row) => ['unsupported', 'unsupported-construct', 'unreadable', 'missing'].includes(row.disposition)).length,
-    metadataHrefsSkipped: manifest.reduce((sum, row) => sum + (row.metadataHrefsSkipped || 0), 0),
-    scanMs: Date.now() - started,
-  } };
-}
-
-module.exports = { decodeHtmlEntities, htmlAttributes, extractJson, extractFile, census };