tadforce 0.0.0-stage → 0.3.0

package/src/build/browser.js

@@ -0,0 +1,70 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+/** Find a Chromium-based browser already installed (Chrome, Edge, Chromium) or a Puppeteer download. */
+export function findBrowser() {
+  const env = process.env.TADFORCE_CHROME || process.env.PUPPETEER_EXECUTABLE_PATH || process.env.CHROME_PATH;
+  if (env && fs.existsSync(env)) return env;
+  const pf = process.env.ProgramFiles || 'C:\\Program Files';
+  const pf86 = process.env['ProgramFiles(x86)'] || 'C:\\Program Files (x86)';
+  const local = process.env.LOCALAPPDATA || '';
+  const candidates = process.platform === 'win32'
+    ? [
+        path.join(pf, 'Google', 'Chrome', 'Application', 'chrome.exe'),
+        path.join(pf86, 'Google', 'Chrome', 'Application', 'chrome.exe'),
+        path.join(local, 'Google', 'Chrome', 'Application', 'chrome.exe'),
+        path.join(pf86, 'Microsoft', 'Edge', 'Application', 'msedge.exe'),
+        path.join(pf, 'Microsoft', 'Edge', 'Application', 'msedge.exe'),
+      ]
+    : process.platform === 'darwin'
+      ? ['/Applications/Google Chrome.app/Contents/MacOS/Google Chrome', '/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge', '/Applications/Chromium.app/Contents/MacOS/Chromium']
+      : [];
+  for (const c of candidates) if (c && fs.existsSync(c)) return c;
+  if (process.platform !== 'win32') {
+    for (const bin of ['google-chrome', 'google-chrome-stable', 'chromium', 'chromium-browser', 'microsoft-edge']) {
+      const r = spawnSync('which', [bin], { encoding: 'utf8' });
+      if (r.status === 0 && r.stdout.trim()) return r.stdout.trim();
+    }
+  }
+  // Browsers downloaded with `npx @puppeteer/browsers install chrome-headless-shell@stable`
+  for (const base of [path.join(os.homedir(), '.cache', 'puppeteer'), path.join(process.cwd(), 'chrome-headless-shell'), path.join(process.cwd(), 'chrome')]) {
+    if (!fs.existsSync(base)) continue;
+    const hit = findExecutable(base, 4);
+    if (hit) return hit;
+  }
+  return null;
+}
+
+function findExecutable(dir, depth) {
+  if (depth < 0) return null;
+  for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, e.name);
+    if (e.isFile() && /^(chrome|chrome-headless-shell)(\.exe)?$/.test(e.name)) return full;
+    if (e.isDirectory()) { const r = findExecutable(full, depth - 1); if (r) return r; }
+  }
+  return null;
+}
+
+let shared = null;
+
+/** Launch (once) a headless browser. Caller closes it with closeBrowser(). */
+export async function getBrowser() {
+  if (shared) return shared;
+  const executablePath = findBrowser();
+  if (!executablePath) {
+    throw new Error('No Chrome, Edge or Chromium found. Install one, or run `npx @puppeteer/browsers install chrome-headless-shell@stable` and set TADFORCE_CHROME to its path.');
+  }
+  const { default: puppeteer } = await import('puppeteer-core');
+  shared = await puppeteer.launch({
+    executablePath,
+    headless: true,
+    args: ['--disable-gpu', '--allow-file-access-from-files', '--no-first-run', '--no-default-browser-check', ...(process.platform === 'linux' ? ['--no-sandbox'] : [])],
+  });
+  return shared;
+}
+
+export async function closeBrowser() {
+  if (shared) { const b = shared; shared = null; await b.close(); }
+}

package/src/build/directives.js

@@ -0,0 +1,293 @@
+// Deterministic content generated from facts: appendices, ERDs, figures, KPI tiles, placeholders.
+import path from 'node:path';
+import { t, formatNumber } from '../util/i18n.js';
+import { exists, readText } from '../util/fsx.js';
+import { contextView, layersBlock } from './figures.js';
+
+const cell = (v) => String(v ?? '').replace(/\|/g, '\\|').replace(/\n/g, ' ');
+const code = (v) => (v ? '`' + String(v).replace(/`/g, '') + '`' : '—');
+const list = (xs, n = 8, dict) => (xs.length > n ? xs.slice(0, n).map(code).join(', ') + ' ' + t(dict, 'annex.more', { n: xs.length - n }) : xs.map(code).join(', ') || '—');
+
+export function mdTable(headers, rows) {
+  if (!rows.length) return '';
+  return ['| ' + headers.map(cell).join(' | ') + ' |', '|' + headers.map(() => '---').join('|') + '|', ...rows.map((r) => '| ' + r.map(cell).join(' | ') + ' |')].join('\n');
+}
+
+/** Read a dotted path from an object: get(facts, 'counts.apex.classes'). */
+export function get(obj, p) {
+  return p.split('.').reduce((o, k) => (o == null ? undefined : o[k]), obj);
+}
+
+const truthy = (v) => (Array.isArray(v) ? v.length > 0 : v && typeof v === 'object' ? Object.keys(v).length > 0 : !!v);
+
+/** <!-- tad:if modules.omnistudio --> … <!-- tad:else --> … <!-- tad:endif --> (nestable, `!` negates). */
+export function resolveConditionals(text, scope) {
+  const out = [];
+  const stack = [];
+  for (const line of text.split('\n')) {
+    const mIf = /^\s*<!--\s*tad:if\s+(!?)([\w.|]+)\s*-->\s*$/.exec(line);
+    const mElse = /^\s*<!--\s*tad:else\s*-->\s*$/.test(line);
+    const mEnd = /^\s*<!--\s*tad:endif\s*-->\s*$/.test(line);
+    const active = stack.every((s) => s.on);
+    if (mIf) {
+      let v = mIf[2].split('|').some((p) => truthy(get(scope, p)));
+      if (mIf[1]) v = !v;
+      stack.push({ on: v, parentOn: active });
+      continue;
+    }
+    if (mElse && stack.length) { const s = stack[stack.length - 1]; s.on = !s.on; continue; }
+    if (mEnd && stack.length) { stack.pop(); continue; }
+    if (active) out.push(line);
+  }
+  return out.join('\n');
+}
+
+export function resolveIncludes(text, baseDir) {
+  return text.replace(/^@@INCLUDE:(.+?)@@[ \t]*$/gm, (m, rel) => {
+    const p = path.resolve(baseDir, rel.trim());
+    if (!exists(p)) return `> [!WARN]\n> Missing include: \`${rel}\``;
+    const content = readText(p);
+    return /\.svg$/i.test(p) ? '<div class="fig-body hand">' + content.replace(/\n\n/g, '\n') + '</div>' : content;
+  });
+}
+
+/** {{n:path}} numbers (from counts, then facts), {{v:path}} raw values, {{cfg:path}} configuration. */
+export function resolveValues(text, ctx, problems) {
+  return text.replace(/\{\{(n|v|cfg):([\w.-]+)\}\}/g, (m, kind, p) => {
+    const src = kind === 'cfg' ? ctx.cfg : ctx.facts;
+    let v = kind === 'n' ? (get(ctx.facts.counts, p) ?? get(ctx.facts, p)) : get(src, p);
+    if (kind === 'n' && Array.isArray(v)) v = v.length;
+    if (v === undefined || v === null) { problems.push({ level: 'error', code: 'unknown-placeholder', message: `Unknown placeholder ${m}` }); return `⟨${m.slice(2, -2)}⟩`; }
+    return kind === 'n' && typeof v === 'number' ? formatNumber(v, ctx.lang) : String(v);
+  });
+}
+
+// ---------------------------------------------------------------- appendices
+function annexes(ctx) {
+  const { facts: f, dict, cfg, glossary } = ctx;
+  const A = (k) => t(dict, 'annex.' + k);
+  const yes = A('yes'), no = A('no');
+  const kindsLabel = (ks) => ks.filter((k) => dict.kinds[k]).map((k) => dict.kinds[k]).join(', ') || '—';
+  const local = f.data.objects.filter((o) => !o.namespace);
+  const n = (x) => formatNumber(x, ctx.lang);
+  return {
+    'doc-control': () => mdTable([t(dict, 'control.element'), t(dict, 'control.value')], [
+      [t(dict, 'control.title'), `${ctx.docName || t(dict, 'meta.docName')} — ${cfg.document.title}`],
+      [t(dict, 'control.reference'), ctx.doc === 'axes' ? cfg.document.reference + '-AX' : cfg.document.reference],
+      [t(dict, 'control.client'), cfg.client.name],
+      ...(cfg.integrator.name ? [[t(dict, 'control.integrator'), cfg.integrator.name]] : []),
+      ...(cfg.document.author ? [[t(dict, 'control.preparedBy'), cfg.document.author]] : []),
+      [t(dict, 'control.version'), `${cfg.document.version}${cfg.document.status ? ' — ' + cfg.document.status : ''}`],
+      [t(dict, 'control.date'), cfg.document.date],
+      [t(dict, 'control.classification'), cfg.document.classification],
+      [t(dict, 'control.scope'), t(dict, 'control.scopeValue', { environment: cfg.document.environment, client: cfg.client.name, date: cfg.document.date })
+        + (cfg.scope && (cfg.scope.include || []).length ? ' — ' + t(dict, 'control.scopeLimited', { scope: cfg.scope.include.map((x) => '`' + x + '`').join(', ') }) : '')],
+    ]),
+    'version-history': () => mdTable([t(dict, 'control.version'), t(dict, 'control.date'), t(dict, 'control.author'), t(dict, 'control.purpose')],
+      (cfg.document.history && cfg.document.history.length ? cfg.document.history : [{ version: cfg.document.version, date: cfg.document.date, author: [cfg.document.author, cfg.integrator.name].filter(Boolean).join(' — ') || cfg.client.name, purpose: t(dict, 'control.firstVersion', { client: cfg.client.name }) }])
+        .map((h) => [h.version, h.date, h.author, h.purpose])),
+    legend: () => `<div class="legend">\n<span class="lg actor">${t(dict, 'legend.actor')}</span>\n<span class="lg sf">${t(dict, 'legend.sf')}</span>\n<span class="lg ext">${t(dict, 'legend.ext')}</span>\n<span class="lg data">${t(dict, 'legend.data')}</span>\n</div>`,
+    'key-figures': () => mdTable([A('domain'), A('count')], [
+      [t(dict, 'keyfig.apps'), n(f.counts.ui.apps)], [t(dict, 'keyfig.pages'), n(f.counts.ui.flexipages)], [t(dict, 'keyfig.lwc'), n(f.counts.ui.lwc)],
+      ...(f.counts.ui.aura ? [[t(dict, 'keyfig.aura'), n(f.counts.ui.aura)]] : []), ...(f.counts.ui.vfPages ? [[t(dict, 'keyfig.vf'), n(f.counts.ui.vfPages)]] : []),
+      [t(dict, 'keyfig.classes'), n(f.counts.apex.classes)], [t(dict, 'keyfig.tests'), n(f.counts.apex.tests)], [t(dict, 'keyfig.triggers'), n(f.counts.apex.triggers)],
+      [t(dict, 'keyfig.flows'), `${n(f.counts.flows.active)} / ${n(f.counts.flows.total)}`],
+      ...(f.modules.omnistudio ? [[t(dict, 'keyfig.os'), n(f.counts.omni.scriptsActive)], [t(dict, 'keyfig.ips'), n(f.counts.omni.ipsActive)], [t(dict, 'keyfig.dms'), n(f.counts.omni.dataMappers)]] : []),
+      [t(dict, 'keyfig.objects'), n(f.counts.objects.custom)], [t(dict, 'keyfig.fields'), n(f.counts.fields.custom)], [t(dict, 'keyfig.cmdt'), `${n(f.counts.cmdt.types)} / ${n(f.counts.cmdt.records)}`],
+      [t(dict, 'keyfig.psg'), `${n(f.counts.security.permissionSetGroups)} / ${n(f.counts.security.permissionSets)}`], [t(dict, 'keyfig.roles'), n(f.counts.security.roles)],
+      [t(dict, 'keyfig.nc'), `${n(f.counts.integration.namedCredentials)} / ${n(f.counts.integration.externalCredentials)}`], [t(dict, 'keyfig.rest'), n(f.counts.integration.restResources)],
+      [t(dict, 'keyfig.reports'), `${n(f.counts.misc.reports)} / ${n(f.counts.misc.dashboards)}`],
+    ]),
+    products: () => mdTable([A('product'), A('evidence')], [
+      ...f.modules.clouds.map((x) => [x.name, x.evidence.map((e) => (e === 'metadata' ? A('evMetadata') : e.replace(/^(namespace|object) (.+)$/, (m0, k, v) => A(k === 'namespace' ? 'evNamespace' : 'evObject') + ' ' + code(v)))).join(', ')]),
+      ...(f.modules.omniChannel && !f.modules.clouds.some((x) => x.id === 'serviceCloud') ? [['Omni-Channel', `${f.misc.signals.serviceChannels} service channels`]] : []),
+      ...(f.modules.cti ? [['CTI / call centers', f.integration.callCenters.map((x) => code(x.name)).join(', ')]] : []),
+      ...f.namespaces.filter((x) => !f.modules.clouds.some((cl) => cl.evidence.includes('namespace ' + x.namespace))).map((x) => [x.product || A('managed'), `${code(x.namespace)} · ${n(x.references)} references${x.installed ? ', installed package' : ''}`]),
+    ]),
+    naming: () => mdTable([A('family'), A('convention'), A('examples')], [
+      ...f.naming.apex.suffixes.map((s) => ['Apex', `*${s.value}`, n(s.count)]),
+      ...['apex', 'triggers', 'lwc', 'flows', 'objects', 'permissionSets'].flatMap((k) => f.naming[k].prefixes.map((p) => [k === 'apex' ? 'Apex' : k === 'lwc' ? 'LWC' : k[0].toUpperCase() + k.slice(1), `${p.value}*`, n(p.count)])),
+    ]),
+    objects: () => mdTable([A('apiName'), A('label'), A('owd'), A('fields'), A('recordTypes'), A('relations'), A('description')],
+      local.filter((o) => o.kind === 'custom').map((o) => [code(o.name), o.label || '—', `${o.sharingModel || '—'} / ${o.externalSharingModel || '—'}`, o.customFields, o.recordTypes.length, o.relations.length, o.description || '—'])),
+    'standard-objects': () => mdTable([A('apiName'), A('fields'), A('recordTypes'), A('owd')],
+      local.filter((o) => o.kind === 'standard' && (o.customFields > 0 || o.recordTypes.length)).map((o) => [code(o.name), o.customFields, o.recordTypes.length, `${o.sharingModel || '—'} / ${o.externalSharingModel || '—'}`])),
+    'external-ids': () => mdTable([A('object'), A('field')], local.flatMap((o) => o.externalIds.map((x) => [code(o.name), code(x)]))),
+    'record-types': () => mdTable([A('object'), A('recordTypes')], local.filter((o) => o.recordTypes.length).map((o) => [code(o.name), o.recordTypes.filter((r) => r.active).map((r) => code(r.name)).join(', ') || '—'])),
+    'validation-rules': () => mdTable([A('object'), A('rule'), A('status')], local.flatMap((o) => o.validationRules.map((v) => [code(o.name), code(v.name), v.active ? A('active') : A('inactive')]))),
+    cmdt: () => mdTable([A('type'), A('records')], f.data.cmdtTypes.map((x) => [code(x.type), n(x.records)])),
+    'platform-events': () => mdTable([A('apiName'), A('label')], local.filter((o) => o.kind === 'platformEvent').map((o) => [code(o.name), o.label || '—'])),
+    volumes: () => (f.org && f.org.volumes ? mdTable([A('object'), A('records'), A('lastCreated')], f.org.volumes.filter((v) => v.records > 0).sort((a, b) => b.records - a.records).map((v) => [code(v.object), n(v.records), v.lastCreated || '—'])) : ''),
+    'apex-summary': () => mdTable([A('kinds'), A('count')], Object.entries(dict.kinds).map(([k, label]) => [label, f.apex.classes.filter((c) => !c.test && c.kinds.includes(k)).length]).filter(([, c]) => c > 0).map(([l, c]) => [l, n(c)])),
+    triggers: () => mdTable([A('trigger'), A('object'), A('events')], f.apex.triggers.map((x) => [code(x.name), code(x.object), x.events.join(', ')])),
+    async: () => mdTable([A('class'), A('kinds')], f.apex.classes.filter((c) => !c.test && c.kinds.some((k) => ['batch', 'queueable', 'schedulable', 'future'].includes(k))).map((c) => [code(c.name), kindsLabel(c.kinds.filter((k) => ['batch', 'queueable', 'schedulable', 'future', 'stateful', 'callout'].includes(k)))])),
+    rest: () => mdTable([A('url'), A('class'), A('kinds')], f.apex.classes.filter((c) => c.restUrl || c.kinds.includes('soap')).map((c) => [code(c.restUrl || 'SOAP'), code(c.name), c.restUrl ? 'Apex REST' : 'Apex SOAP'])),
+    flows: () => mdTable([A('apiName'), A('label'), A('processType'), A('start'), A('object'), A('status')], f.automation.flows.map((x) => [code(x.name), x.label || '—', x.processType || '—', [x.triggerType, x.recordTriggerType, x.scheduleFrequency].filter(Boolean).join(' · ') || '—', x.object ? code(x.object) : '—', x.status])),
+    'omni-scripts': () => mdTable([A('apiName'), A('label'), A('type'), A('language'), A('status')], f.automation.omnistudio.omniScripts.filter((x) => x.active).map((x) => [code(x.name), x.label || '—', `${x.type || ''}/${x.subType || ''}`, x.language || '—', A('active')])),
+    'integration-procedures': () => mdTable([A('apiName'), A('label'), A('type'), A('status')], f.automation.omnistudio.integrationProcedures.filter((x) => x.active).map((x) => [code(x.name), x.label || '—', `${x.type || ''}/${x.subType || ''}`, A('active')])),
+    'data-mappers': () => mdTable([A('apiName'), A('type')], f.automation.omnistudio.dataMappers.map((x) => [code(x.name), x.type || '—'])),
+    apps: () => mdTable([A('apiName'), A('label'), A('navigation'), A('formFactors')], f.ui.apps.map((a) => [code(a.name), a.label || '—', a.navType || '—', a.formFactors.join(', ') || '—'])),
+    flexipages: () => mdTable([A('apiName'), A('type'), A('object'), A('components')], f.ui.flexipages.map((p) => [code(p.name), p.type || '—', p.object ? code(p.object) : '—', list(p.customComponents, 6, dict)])),
+    lwc: () => mdTable([A('apiName'), A('placement'), A('controllers')], f.ui.lwc.map((l) => [code(l.name), l.placedIn.length ? [...new Set(l.placedIn.map((u) => u.name))].slice(0, 4).map(code).join(', ') + (l.placedIn.length > 4 ? ' …' : '') : '—', list(l.apex, 4, dict)])),
+    aura: () => mdTable([A('apiName'), A('type'), A('placement')], f.ui.aura.map((a) => [code(a.name), a.type, a.placedIn.length ? a.placedIn.slice(0, 4).map((u) => code(u.name)).join(', ') : '—'])),
+    visualforce: () => mdTable([A('apiName'), A('controllers')], f.ui.vfPages.map((p) => [code(p.name), [p.controller, ...p.extensions].filter(Boolean).map(code).join(', ') || '—'])),
+    psg: () => mdTable([A('apiName'), A('label'), A('permissionSets')].concat(f.org && f.org.psgAssignments ? [A('users')] : []), f.security.permissionSetGroups.map((g) => {
+      const row = [code(g.name), g.label || '—', list(g.permissionSets, 10, dict)];
+      if (f.org && f.org.psgAssignments) row.push(n((f.org.psgAssignments.find((a) => a.group === g.name) || {}).users || 0));
+      return row;
+    })),
+    'permission-sets': () => mdTable([A('apiName'), A('label'), A('license')], f.security.permissionSets.map((p) => [code(p.name), p.label || '—', p.license || '—'])),
+    profiles: () => mdTable([A('name'), A('license')].concat(f.org && f.org.usersByProfile ? [A('users')] : []), f.security.profiles.map((p) => {
+      const row = [code(p.name), p.userLicense || '—'];
+      if (f.org && f.org.usersByProfile) row.push(n((f.org.usersByProfile.find((u) => u.profile === p.name) || {}).users || 0));
+      return row;
+    })),
+    roles: () => mdTable([A('apiName'), A('label'), A('parent')], f.security.roles.map((r) => [code(r.name), r.label || '—', r.parent ? code(r.parent) : '—'])),
+    owd: () => mdTable([A('object'), A('owd')], local.filter((o) => o.sharingModel && ['custom', 'standard'].includes(o.kind)).map((o) => [code(o.name), `${o.sharingModel} / ${o.externalSharingModel || '—'}`])),
+    'sharing-rules': () => mdTable([A('object'), A('rule'), A('kind'), A('access')], f.security.sharingRules.flatMap((s) => s.rules.map((r) => [code(s.object), code(r.name), r.kind, r.access || '—']))),
+    queues: () => mdTable([A('apiName'), A('label'), A('object')], f.security.queues.map((q) => [code(q.name), q.label || '—', q.objects.map(code).join(', ') || '—'])),
+    'named-credentials': () => mdTable([A('apiName'), A('label'), A('type'), A('endpoint'), A('externalCredential')], f.integration.namedCredentials.map((x) => [code(x.name), x.label || '—', x.type, x.host || '—', x.externalCredential ? code(x.externalCredential) : '—'])),
+    'external-credentials': () => mdTable([A('apiName'), A('label'), A('protocol')], f.integration.externalCredentials.map((x) => [code(x.name), x.label || '—', x.protocol || '—'])),
+    'connected-apps': () => mdTable([A('apiName'), A('label'), A('scopes')], f.integration.connectedApps.map((x) => [code(x.name), x.label || '—', x.scopes.join(', ') || (x.saml ? 'SAML' : '—')])),
+    'auth-providers': () => mdTable([A('apiName'), A('label'), A('type'), A('handler')], f.integration.authProviders.map((x) => [code(x.name), x.label || '—', x.type || '—', x.registrationHandler ? code(x.registrationHandler) : '—'])),
+    'allowed-domains': () => mdTable([A('kind'), A('apiName'), A('endpoint')], [
+      ...f.integration.remoteSites.map((x) => ['Remote Site', code(x.name), x.host || '—']),
+      ...f.integration.cspTrustedSites.map((x) => ['CSP Trusted Site', code(x.name), x.host || '—']),
+      ...f.integration.corsOrigins.map((x) => ['CORS', code(x.name), x.host || '—']),
+    ]),
+    'call-centers': () => mdTable([A('apiName'), A('label'), A('endpoint')], f.integration.callCenters.map((x) => [code(x.name), x.label || '—', x.adapterHost || '—'])),
+    systems: () => mdTable([A('system'), A('description'), A('endpoints')], f.systems.named.map((s) => [s.name, s.description || '—', s.endpoints.map((e) => `${code(e.name)}`).join(', ') || '—'])),
+    reports: () => mdTable([A('folder'), A('count')], f.misc.reports.folders.map((fo) => [code(fo), n((f.misc.reports.byFolder || {})[fo] || 0)])),
+    labels: () => mdTable([A('apiName'), A('kind')], f.misc.labels.slice(0, 40).map((l) => [code(l.name), l.category || '—'])),
+    'scheduled-jobs': () => (f.org && f.org.scheduledJobs ? mdTable([A('name'), A('type'), A('cron'), A('status')], f.org.scheduledJobs.map((j) => [j.name, j.type || '—', code(j.cron), j.state])) : ''),
+    packages: () => (f.org && f.org.packages && f.org.packages.length
+      ? mdTable([A('product'), A('namespace'), A('version')], f.org.packages.map((p) => [p.name, p.namespace ? code(p.namespace) : '—', p.version || '—']))
+      : mdTable([A('namespace'), A('product')], f.namespaces.map((x) => [code(x.namespace), x.product || A('managed')]))),
+    exclusions: () => mdTable([A('type'), A('apiName'), A('reason')], f.exclusions.applied.map((x) => [x.type, code(x.name), x.reason || '—'])),
+    inventory: () => mdTable([A('type'), A('count')], Object.entries(f.misc.folders).filter(([, c]) => c > 0).map(([k, c]) => [code(k), n(c)])),
+    traceability: () => mdTable([A('chapter'), A('metadata')], Object.entries(dict.traceability).map(([k, v]) => [ctx.chapterTitle(k), v])),
+    glossary: () => mdTable([A('term'), A('definition')], [
+      ...(glossary.terms || []).filter((x) => x.definition).map((x) => [x.term || x.use, x.definition]),
+      ...Object.entries(dict.glossary).map(([k, v]) => [k, v]),
+    ].sort((a, b) => a[0].localeCompare(b[0]))),
+    signals: () => mdTable([A('signal'), A('pillar'), A('priority'), A('observed'), A('evidence')], f.signals.map((s) => [t(dict, 'signals.' + s.id), t(dict, 'pillars.' + s.pillar), `<span class="b ${s.priority}">${s.priority.toUpperCase()}</span>`, String(s.value), s.evidence.length ? list(s.evidence.map((e) => e.split(' ')[0]), 6, dict) : '—'])),
+    'signals-trusted': () => signalTable(ctx, 'trusted'),
+    'signals-easy': () => signalTable(ctx, 'easy'),
+    'signals-adaptable': () => signalTable(ctx, 'adaptable'),
+    'exclusion-candidates': () => mdTable([A('type'), A('apiName'), A('reason')], f.exclusions.candidates.map((c) => [c.type, code(c.name), c.reasons.join('; ')])),
+  };
+}
+
+function signalTable(ctx, pillar) {
+  const { facts: f, dict } = ctx;
+  const A = (k) => t(dict, 'annex.' + k);
+  return mdTable([A('signal'), A('priority'), A('observed'), A('evidence')], f.signals.filter((s) => s.pillar === pillar).map((s) => [t(dict, 'signals.' + s.id), `<span class="b ${s.priority}">${s.priority.toUpperCase()}</span>`, String(s.value), s.evidence.length ? s.evidence.slice(0, 6).map((e) => '`' + e + '`').join(', ') + (s.total > 6 ? ' ' + t(dict, 'annex.more', { n: s.total - 6 }) : '') : '—']));
+}
+
+// ---------------------------------------------------------------- ERD, figures, KPIs
+
+/** Mermaid ER diagram limited to Lookup / Master-Detail relationships between the given objects. */
+export function erd(facts, objectNames, caption) {
+  const byName = new Map(facts.data.objects.map((o) => [o.name, o]));
+  let names = objectNames;
+  if (names.length === 1 && names[0] === 'auto') {
+    const degree = {};
+    for (const o of facts.data.objects.filter((x) => !x.namespace)) {
+      for (const r of o.relations) for (const to of r.to) { if (to === o.name || to === 'User' || to === 'Group') continue; degree[o.name] = (degree[o.name] || 0) + 1; degree[to] = (degree[to] || 0) + 1; }
+    }
+    names = Object.entries(degree).sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0])).slice(0, 12).map(([k]) => k);
+  }
+  const set = new Set(names);
+  const lines = ['erDiagram'];
+  const seen = new Set();
+  for (const nm of names) {
+    const o = byName.get(nm);
+    if (!o) continue;
+    for (const r of o.relations) {
+      for (const to of r.to) {
+        if (!set.has(to) || to === nm) continue;
+        const key = `${to}>${nm}>${r.field}`;
+        if (seen.has(key)) continue;
+        seen.add(key);
+        const card = r.type === 'MasterDetail' ? '||--|{' : '|o--o{';
+        lines.push(`  ${ent(to)} ${card} ${ent(nm)} : "${r.field}"`);
+      }
+    }
+  }
+  for (const nm of names) if (!lines.some((l) => l.includes(` ${ent(nm)} `) || l.endsWith(` ${ent(nm)}`))) lines.push(`  ${ent(nm)} {\n    Id id\n  }`);
+  return '```mermaid\n' + lines.join('\n') + '\n```\nFigure: ' + (caption || 'Entity-relationship model') + '\n';
+}
+const ent = (n) => n.replace(/[^A-Za-z0-9_]/g, '_');
+
+function rolesFigure(facts, caption) {
+  const roles = facts.security.roles;
+  if (!roles.length) return '';
+  const id = new Map(roles.map((r, i) => [r.name, 'r' + i]));
+  const depth = (r, d = 0) => (d > 12 || !r.parent || !id.has(r.parent) ? d : depth(roles.find((x) => x.name === r.parent), d + 1));
+  const shown = roles.filter((r) => depth(r) <= (roles.length > 40 ? 2 : 5));
+  const lines = ['flowchart TB'];
+  for (const r of shown) lines.push(`  ${id.get(r.name)}["${(r.label || r.name).replace(/"/g, "'")}"]:::${r.parent ? 'sf' : 'data'}`);
+  for (const r of shown) if (r.parent && id.has(r.parent) && shown.some((s) => s.name === r.parent)) lines.push(`  ${id.get(r.parent)} --> ${id.get(r.name)}`);
+  return '```mermaid\n' + lines.join('\n') + '\n```\nFigure: ' + caption + '\n';
+}
+
+function integrationsFigure(facts, cfg, dict, caption) {
+  const lines = ['flowchart LR', `  SF["${(t(dict, 'context.salesforce') + ' — ' + (cfg.client.short || cfg.client.name)).replace(/"/g, "'")}"]:::sf`];
+  let i = 0;
+  for (const s of facts.systems.named) {
+    const k = 's' + i++;
+    lines.push(`  ${k}["${s.name.replace(/"/g, "'")}"]:::ext`);
+    const ncs = s.endpoints.filter((e) => e.kind === 'namedCredential').map((e) => e.name);
+    const label = ncs.length ? ncs.slice(0, 2).join(', ') : [...new Set(s.endpoints.map((e) => e.kind))].join(', ');
+    const inbound = s.endpoints.every((e) => e.kind === 'connectedApp' || e.kind === 'authProvider');
+    lines.push(inbound ? `  ${k} -- "${label}" --> SF` : `  SF -- "${label}" --> ${k}`);
+  }
+  const hosts = [...new Set(facts.systems.unnamed.filter((e) => e.host).map((e) => e.host))].slice(0, 8);
+  for (const h of hosts) { const k = 's' + i++; lines.push(`  ${k}["${h}"]:::ext`); lines.push(`  SF --> ${k}`); }
+  if (facts.counts.integration.restResources) lines.push(`  IN["${t(dict, 'context.callers')}"]:::actor`, `  IN -- "Apex REST" --> SF`);
+  if (i === 0 && !facts.counts.integration.restResources) return '';
+  return '```mermaid\n' + lines.join('\n') + '\n```\nFigure: ' + caption + '\n';
+}
+
+function kpis(ctx) {
+  const { facts: f, dict } = ctx;
+  const n = (x) => formatNumber(x, ctx.lang);
+  const tile = (href, value, label) => `<a class="kpi" href="#${href}"><b>${value}</b><span>${label}</span></a>`;
+  const tiles = [
+    tile('annex-apps', n(f.counts.ui.apps), t(dict, 'kpi.apps')),
+    tile('annex-objects', n(f.counts.objects.custom), t(dict, 'kpi.objects')),
+    tile('annex-apex', n(f.counts.apex.classes), t(dict, 'kpi.classes', { tests: n(f.counts.apex.tests) })),
+    tile('annex-lwc', n(f.counts.ui.lwc), t(dict, 'kpi.lwc')),
+    f.modules.omnistudio && tile('annex-omnistudio', `${n(f.counts.omni.scriptsActive)} / ${n(f.counts.omni.ipsActive)}`, t(dict, 'kpi.omni')),
+    tile('annex-automation', n(f.counts.flows.active), t(dict, 'kpi.flows')),
+    f.counts.cmdt.records && tile('annex-cmdt', n(f.counts.cmdt.records), t(dict, 'kpi.cmdt', { types: n(f.counts.cmdt.types) })),
+    f.counts.integration.systems ? tile('annex-integration', n(f.counts.integration.systems), t(dict, 'kpi.systems')) : tile('annex-integration', n(f.counts.integration.namedCredentials + f.counts.integration.restResources), t(dict, 'kpi.integrations')),
+  ].filter(Boolean);
+  return `<div class="kpis">\n${tiles.join('\n')}\n</div>`;
+}
+
+/** Replace every @@DIRECTIVE@@ line by generated content. Unknown directives are reported. */
+export function resolveDirectives(text, ctx, problems) {
+  const A = annexes(ctx);
+  return text.replace(/^@@([A-Z]+)(?::([^@|]*))?(?:\|([^@]*))?@@[ \t]*$/gm, (m, kind, arg = '', caption = '') => {
+    arg = arg.trim(); caption = caption.trim();
+    if (kind === 'ANNEX') {
+      const fn = A[arg];
+      if (!fn) { problems.push({ level: 'error', code: 'unknown-annex', message: `Unknown appendix generator @@ANNEX:${arg}@@` }); return ''; }
+      const out = fn();
+      return out || `<p class="empty-annex">${t(ctx.dict, 'annex.none')}</p>`;
+    }
+    if (kind === 'ERD') return erd(ctx.facts, arg.split(',').map((s) => s.trim()).filter(Boolean), caption);
+    if (kind === 'KPIS') return kpis(ctx);
+    if (kind === 'FIGURE') {
+      if (arg === 'context') return '<div class="fig-body hand">' + contextView(ctx.facts, ctx.glossary, ctx.cfg, ctx.dict) + '</div>\n<p class="figcap">Figure — ' + (caption || t(ctx.dict, 'context.caption')) + '</p>';
+      if (arg === 'layers') return layersBlock(ctx.facts, ctx.dict);
+      if (arg === 'roles') return rolesFigure(ctx.facts, caption || 'Role hierarchy');
+      if (arg === 'integrations') return integrationsFigure(ctx.facts, ctx.cfg, ctx.dict, caption || 'Integration map');
+      problems.push({ level: 'error', code: 'unknown-figure', message: `Unknown figure @@FIGURE:${arg}@@` });
+      return '';
+    }
+    problems.push({ level: 'error', code: 'unknown-directive', message: `Unknown directive ${m}` });
+    return '';
+  });
+}

package/src/build/export.js

@@ -0,0 +1,60 @@
+import fs from 'node:fs';
+import { pathToFileURL } from 'node:url';
+import { getBrowser } from './browser.js';
+
+/** PDF through the browser print engine (same layout as « Print / export › PDF »). */
+export async function exportPdf(htmlPath, pdfPath) {
+  const browser = await getBrowser();
+  const page = await browser.newPage();
+  try {
+    await page.goto(pathToFileURL(htmlPath).href, { waitUntil: 'load', timeout: 120000 });
+    await page.emulateMediaType('print');
+    await page.pdf({ path: pdfPath, printBackground: true, preferCSSPageSize: true, displayHeaderFooter: false, timeout: 300000 });
+  } finally {
+    await page.close();
+  }
+  return fs.statSync(pdfPath).size;
+}
+
+/** DOCX through the page's own export (same result as « Print / export › Word »). */
+export async function exportDocx(htmlPath, docxPath) {
+  const browser = await getBrowser();
+  const page = await browser.newPage();
+  try {
+    await page.setViewport({ width: 1400, height: 1000 });
+    await page.goto(pathToFileURL(htmlPath).href, { waitUntil: 'load', timeout: 120000 });
+    const b64 = await page.evaluate(async () => {
+      let blob = null;
+      const orig = URL.createObjectURL.bind(URL);
+      URL.createObjectURL = function (b) { blob = b; return orig(b); };
+      HTMLAnchorElement.prototype.click = function () {};
+      document.getElementById('doDocx').click();
+      for (let i = 0; i < 480 && !blob; i++) await new Promise((r) => setTimeout(r, 250));
+      if (!blob) return null;
+      const bytes = new Uint8Array(await blob.arrayBuffer());
+      let s = '';
+      for (let i = 0; i < bytes.length; i += 8192) s += String.fromCharCode.apply(null, bytes.subarray(i, i + 8192));
+      return btoa(s);
+    });
+    if (!b64) throw new Error('The page did not produce a DOCX file.');
+    fs.writeFileSync(docxPath, Buffer.from(b64, 'base64'));
+  } finally {
+    await page.close();
+  }
+  return fs.statSync(docxPath).size;
+}
+
+/** PNG screenshot of a page region (used for README visuals). */
+export async function screenshot(htmlPath, pngPath, { width = 1440, height = 900, script } = {}) {
+  const browser = await getBrowser();
+  const page = await browser.newPage();
+  try {
+    await page.setViewport({ width, height, deviceScaleFactor: 1 });
+    await page.goto(pathToFileURL(htmlPath).href, { waitUntil: 'load' });
+    if (script) await page.evaluate(script);
+    await new Promise((r) => setTimeout(r, 600));
+    await page.screenshot({ path: pngPath });
+  } finally {
+    await page.close();
+  }
+}

package/src/build/figures.js

@@ -0,0 +1,119 @@
+// Data-driven figures drawn as SVG (context view) or HTML blocks (logical layers).
+import { t } from '../util/i18n.js';
+
+const STY = {
+  actor: ['#F1E8FF', '#7B3FE4', '#2A1458'],
+  sf: ['#E8F1FF', '#2F6FE4', '#0B2545'],
+  ext: ['#FFF2E2', '#E0861F', '#4A2A05'],
+  data: ['#E7F6EC', '#2E9E5B', '#0E3B22'],
+  warn: ['#FDECEF', '#D6336C', '#5A0A23'],
+};
+const esc = (s) => String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+const clip = (s, n) => { s = String(s || ''); return s.length > n ? s.slice(0, n - 1) + '…' : s; };
+
+export class Svg {
+  constructor(w, h, title) { this.w = w; this.h = h; this.title = title; this.parts = []; }
+  box(x, y, w, h, kind, lines, { pill = false } = {}) {
+    const [fill, stroke, ink] = STY[kind];
+    this.parts.push(`<rect x="${x}" y="${y}" width="${w}" height="${h}" rx="${pill ? h / 2 : 8}" fill="${fill}" stroke="${stroke}" stroke-width="1.4"/>`);
+    lines.forEach((tx, i) => {
+      const ty = y + h / 2 + (i - (lines.length - 1) / 2) * 16 + 5;
+      this.parts.push(`<text x="${x + w / 2}" y="${ty}" text-anchor="middle" font-size="${i === 0 ? 13.5 : 12}" font-weight="${i === 0 ? 600 : 400}" fill="${ink}">${esc(tx)}</text>`);
+    });
+  }
+  group(x, y, w, h, title) {
+    this.parts.push(`<rect x="${x}" y="${y}" width="${w}" height="${h}" rx="14" fill="#F7F9FC" stroke="#C9D4E3" stroke-width="1.4" stroke-dasharray="5 4"/>`);
+    this.parts.push(`<text x="${x + 14}" y="${y + 20}" font-size="13" font-weight="700" fill="#33475B">${esc(title)}</text>`);
+  }
+  arrow(pts, { label, dashed = false, both = false } = {}) {
+    const d = 'M' + pts.map(([a, b]) => `${a},${b}`).join(' L');
+    this.parts.push(`<path d="${d}" fill="none" stroke="#5B6B7D" stroke-width="1.5"${dashed ? ' stroke-dasharray="5 4"' : ''} marker-end="url(#ah)"${both ? ' marker-start="url(#ahs)"' : ''}/>`);
+    if (label) {
+      const [x1, y1] = pts[0], [x2, y2] = pts[pts.length - 1];
+      const lx = (x1 + x2) / 2, ly = (y1 + y2) / 2 - 6;
+      this.parts.push(`<rect x="${lx - label.length * 3.4 - 4}" y="${ly - 12}" width="${label.length * 6.8 + 8}" height="16" rx="4" fill="#fff"/>`);
+      this.parts.push(`<text x="${lx}" y="${ly}" text-anchor="middle" font-size="11.5" fill="#33475B">${esc(label)}</text>`);
+    }
+  }
+  render() {
+    return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${this.w} ${this.h}" role="img" aria-label="${esc(this.title)}" style="font-family:Segoe UI,Arial,sans-serif;max-width:100%">` +
+      `<defs><marker id="ah" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path d="M0,0 L10,5 L0,10 z" fill="#5B6B7D"/></marker>` +
+      `<marker id="ahs" viewBox="0 0 10 10" refX="1" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path d="M10,0 L0,5 L10,10 z" fill="#5B6B7D"/></marker></defs>` +
+      this.parts.join('') + '</svg>';
+  }
+}
+
+const KIND_LABEL = { namedCredential: 'Named Credential', remoteSite: 'Remote Site', cspTrustedSite: 'CSP', authProvider: 'SSO', connectedApp: 'Connected App', callCenter: 'CTI' };
+
+/** Context view: users on the left, the Salesforce org in the middle, connected systems on the right. */
+export function contextView(facts, glossary, cfg, dict) {
+  const actors = (glossary.actors || []).map((a) => [a.name, a.channel || a.description || '']).slice(0, 6);
+  if (!actors.length) {
+    for (const a of facts.ui.apps.slice(0, 5)) actors.push([a.label || a.name, a.console ? 'Console' : 'Lightning']);
+    if (!actors.length) actors.push([t(dict, 'context.users'), 'Lightning']);
+  }
+  const systems = facts.systems.named.map((s) => [s.name, [...new Set(s.endpoints.map((e) => KIND_LABEL[e.kind] || e.kind))].join(' · ')]);
+  const seenHosts = new Set();
+  for (const e of facts.systems.unnamed) {
+    const key = e.host || e.name;
+    if (seenHosts.has(key) || systems.length >= 8) continue;
+    seenHosts.add(key);
+    systems.push([e.host || e.name, KIND_LABEL[e.kind] || e.kind]);
+  }
+  const rest = facts.counts.integration.restResources;
+  if (rest) systems.push([t(dict, 'context.callers'), `${t(dict, 'context.rest')} · ${rest} API`]);
+
+  const m = facts.modules;
+  const caps = m.clouds.map((x) => x.name.replace(/ \(.*\)$/, ''));
+  for (const p of m.products) if (!caps.some((x) => p.startsWith(x))) caps.push(p);
+  if (m.omniChannel && !caps.includes('Omni-Channel')) caps.push('Omni-Channel');
+  if (m.cti) caps.push('CTI');
+  if (!caps.length) caps.push('Lightning Platform');
+
+  const rows = Math.max(actors.length, systems.length, 4);
+  const H = Math.max(360, 70 + rows * 64);
+  const svg = new Svg(1180, H, t(dict, 'context.caption'));
+  // actors
+  const ay = (i, n) => 50 + i * ((H - 80) / n);
+  actors.forEach(([name, sub], i) => svg.box(20, ay(i, actors.length) + 6, 230, 50, 'actor', [clip(name, 30), clip(sub, 34)]));
+  // salesforce org
+  const gx = 320, gw = 520;
+  svg.group(gx, 30, gw, H - 50, `${t(dict, 'context.salesforce')} — ${cfg.client.short || cfg.client.name}`);
+  const apps = facts.ui.apps.filter((a) => a.label).slice(0, 4);
+  const appW = apps.length ? (gw - 40 - (apps.length - 1) * 10) / apps.length : 0;
+  apps.forEach((a, i) => svg.box(gx + 20 + i * (appW + 10), 56, appW, 46, 'sf', [clip(a.label, Math.floor(appW / 8)), a.console ? 'Console' : 'Lightning']));
+  const capY = apps.length ? 122 : 60;
+  svg.parts.push(`<text x="${gx + 20}" y="${capY}" font-size="12" font-weight="700" fill="#33475B">${esc(t(dict, 'context.platform'))}</text>`);
+  const capList = caps.slice(0, 8);
+  const capW = (gw - 40 - 10) / 2;
+  capList.forEach((c, i) => svg.box(gx + 20 + (i % 2) * (capW + 10), capY + 10 + Math.floor(i / 2) * 40, capW, 32, 'sf', [clip(c, Math.floor(capW / 7.4))], { pill: true }));
+  const dataY = capY + 20 + Math.ceil(capList.length / 2) * 40;
+  svg.parts.push(`<text x="${gx + 20}" y="${dataY}" font-size="12" font-weight="700" fill="#33475B">${esc(t(dict, 'context.data'))}</text>`);
+  svg.box(gx + 20, dataY + 10, capW, 40, 'data', [t(dict, 'context.objects', { n: facts.counts.objects.custom })]);
+  svg.box(gx + 30 + capW, dataY + 10, capW, 40, 'data', [t(dict, 'context.cmdt', { n: facts.counts.cmdt.types })]);
+  // external systems
+  const sy = (i, n) => 50 + i * ((H - 80) / Math.max(n, 1));
+  systems.forEach(([name, sub], i) => svg.box(930, sy(i, systems.length) + 6, 230, 50, 'ext', [clip(name, 30), clip(sub, 34)]));
+  // arrows
+  actors.forEach((_, i) => svg.arrow([[250, ay(i, actors.length) + 31], [gx, ay(i, actors.length) + 31]]));
+  systems.forEach((s, i) => {
+    const y = sy(i, systems.length) + 31;
+    const inbound = s[0] === t(dict, 'context.callers');
+    svg.arrow(inbound ? [[930, y], [gx + gw, y]] : [[gx + gw, y], [930, y]], { dashed: inbound });
+  });
+  return svg.render();
+}
+
+/** Logical layers block (HTML), with counts from facts. */
+export function layersBlock(facts, dict) {
+  const c = facts.counts;
+  const L = (k, n) => t(dict, `layers.${k}`, { n });
+  const span = (s) => `<span>${esc(s)}</span>`;
+  const row = (cls, title, items) => `<div class="layer${cls ? ' ' + cls : ''}"><div class="ln">${esc(title)}</div><div class="li">${items.filter(Boolean).map(span).join('')}</div></div>`;
+  const pres = [c.ui.apps && L('apps', c.ui.apps), c.ui.flexipages && L('pages', c.ui.flexipages), c.ui.lwc && L('lwc', c.ui.lwc) + (c.ui.aura ? ' · ' + L('aura', c.ui.aura) : ''), c.omni.scriptsActive && L('os', c.omni.scriptsActive), c.ui.vfPages && L('vf', c.ui.vfPages)];
+  const orch = [c.flows.active && L('flows', c.flows.active), c.omni.ipsActive && L('ips', c.omni.ipsActive), c.omni.dataMappers && L('dms', c.omni.dataMappers)];
+  const svc = [c.apex.triggers && L('triggers', c.apex.triggers), c.apex.auraEnabled && L('controllers', c.apex.auraEnabled), L('services', c.apex.classes), (c.apex.batch + c.apex.queueable + c.apex.schedulable + c.apex.future) && L('async')];
+  const data = [L('standard'), c.objects.custom && L('custom', c.objects.custom), c.cmdt.types && L('cmdt', c.cmdt.types), L('files')];
+  const integ = [c.integration.namedCredentials && L('nc', c.integration.namedCredentials), c.integration.externalCredentials && L('ec', c.integration.externalCredentials), c.integration.restResources && L('rest', c.integration.restResources), c.integration.connectedApps && L('apps2', c.integration.connectedApps)];
+  return `<div class="layers">\n${row('', L('presentation'), pres)}\n${row('', L('orchestration'), orch.length && orch.some(Boolean) ? orch : ['—'])}\n${row('', L('services'), svc)}\n${row('data', L('data'), data)}\n${row('int', L('integration'), integ.some(Boolean) ? integ : ['—'])}\n</div>\n<p class="figcap">Figure — ${esc(L('caption'))}</p>`;
+}