tadforce 0.4.0 → 0.4.1

package/src/commands/update.js

@@ -61,20 +61,33 @@ function sectionLocations(lang) {
   return out;
 }
 
-/** Sections whose spec reads a facts area that changed. */
+// Sections whose spec names no facts are matched by their chapter.
+const CHAPTER_AREAS = { data: ['data'], application: ['apex', 'automation'], ui: ['ui'], integration: ['integration'], security: ['security'], reporting: ['misc'] };
+
+/**
+ * Sections whose spec reads a facts area that changed. A component change (« changed classes:Foo ») makes a
+ * section relevant; a moved count only matters where the spec reads that count.
+ */
 export function affectedSections(areas, specs, locations) {
   const hits = [];
   for (const [id, s] of Object.entries(specs)) {
     const reasons = [];
-    for (const p of s.facts || []) {
+    const paths = s.facts && s.facts.length ? s.facts : (CHAPTER_AREAS[id.split('.')[0]] || []);
+    for (const p of paths) {
       const fp = p.replace(/^counts\./, '');
-      for (const [area, why] of Object.entries(areas)) {
-        if (p === 'counts' || fp === area || fp.startsWith(area + '.') || area.startsWith(fp + '.') || (p === 'modules' && area === 'modules')) reasons.push(...why);
+      for (const [area, whys] of Object.entries(areas)) {
+        for (const why of whys) {
+          const isCount = why.startsWith('count ');
+          if (p === 'counts' ? isCount : fp === area || fp.startsWith(area + '.') || area.startsWith(fp + '.') || (p === 'modules' && area === 'modules')) reasons.push(why);
+        }
       }
     }
-    if (reasons.length) hits.push({ id, ...(locations[id] || {}), reasons: [...new Set(reasons)].slice(0, 12) });
+    if (!reasons.length) continue;
+    const unique = [...new Set(reasons)];
+    hits.push({ id, ...(locations[id] || {}), relevance: unique.some((r) => !r.startsWith('count ')) ? 'components' : 'counts', reasons: unique.slice(0, 12) });
   }
-  return hits;
+  // what changed in the components first: count-only sections usually need no rewrite
+  return hits.sort((a, b) => (a.relevance === b.relevance ? 0 : a.relevance === 'components' ? -1 : 1));
 }
 
 const nextVersion = (v) => { const m = /^(\d+)\.(\d+)$/.exec(String(v)); return m ? `${m[1]}.${Number(m[2]) + 1}` : `${v}.1`; };
@@ -86,25 +99,21 @@ export async function run(args) {
   if (!exists(before)) throw new Error('No previous facts: run `tadforce doctor` and `tadforce build` first.');
   say(() => log.banner('update'));
 
-  // 1. Archive what the current document was written from.
+  // 1. What the current version was written from (archived below, once something changed).
   const stamp = new Date().toISOString().slice(0, 10);
-  const archive = ctx.p('facts', 'history', stamp);
-  fs.mkdirSync(archive, { recursive: true });
   const oldFacts = readJson(before);
   const oldPrints = exists(ctx.p('facts', 'fingerprints.json')) ? readJson(ctx.p('facts', 'fingerprints.json')) : fingerprints(sourceDirs(ctx));
-  writeJson(path.join(archive, 'facts.json'), oldFacts);
-  writeJson(path.join(archive, 'fingerprints.json'), oldPrints);
-  say(() => log.ok(`Previous facts archived in ${path.relative(ctx.project, archive)}`));
 
   // 2. Read the org again (a fresh snapshot: deleted components must disappear too).
   const mode = ctx.cfg.source.mode || 'org';
-  const quiet = async (fn) => { if (!args.json) return fn(); const o = console.log; console.log = () => {}; try { return await fn(); } finally { console.log = o; } };
+  // in --json mode stdout carries only the report; progress goes to stderr
+  const quiet = async (fn) => { if (!args.json) return fn(); const o = console.log; console.log = (...a) => process.stderr.write(a.join(' ') + '\n'); try { return await fn(); } finally { console.log = o; } };
   if (mode !== 'local' && !args.skipRetrieve) {
     const snap = ctx.p(ctx.cfg.source.dir);
     if (exists(snap)) fs.rmSync(snap, { recursive: true, force: true });
     for (const fn of [org.manifest, org.retrieve]) { const code = await quiet(() => fn({ ...args, cwd: ctx.project })); if (code) return code; }
   }
-  await quiet(() => docs.facts({ ...args, cwd: ctx.project, org: mode === 'local' || args.skipRetrieve ? false : ctx.cfg.org.alias }));
+  await quiet(() => docs.facts({ ...args, json: false, cwd: ctx.project, org: mode === 'local' || args.skipRetrieve ? false : ctx.cfg.org.alias }));
   const ctx2 = loadWorkspace(ctx.project);
   const newPrints = fingerprints(sourceDirs(ctx2));
   writeJson(ctx2.p('facts', 'fingerprints.json'), newPrints);
@@ -122,33 +131,55 @@ export async function run(args) {
   for (const m of modulesAfter.filter((x) => !modulesBefore.includes(x))) note('modules', `new product detected: ${m}`);
   for (const m of modulesBefore.filter((x) => !modulesAfter.includes(x))) note('modules', `product no longer detected: ${m}`);
   const specs = readYaml(path.join(TEMPLATES, 'specs', 'sections.yml'), {}).sections || {};
-  const sections = affectedSections(areas, specs, sectionLocations(templateLang(ctx2.cfg.language)));
+  // sections still to write are not « to rewrite »: their first writing reads the new facts anyway
+  const srcText = (file) => (exists(ctx2.p(file)) ? readText(ctx2.p(file)) : '');
+  const sections = affectedSections(areas, specs, sectionLocations(templateLang(ctx2.cfg.language)))
+    .filter((x) => !x.file || !new RegExp(`<!--\\s*tad:pending\\s+${x.id.replace(/\./g, '\\.')}\\s*-->`).test(srcText(x.file)));
+  const upToDate = !(diff.added.length + diff.changed.length + diff.removed.length) && !Object.keys(counts).length;
+
+  // the facts of the previous version, kept once per version: never overwritten by a later run
+  const archive = ctx2.p('facts', 'history', `v${ctx2.cfg.document.version}`);
+  if (!upToDate && !exists(archive)) {
+    writeJson(path.join(archive, 'facts.json'), oldFacts);
+    writeJson(path.join(archive, 'fingerprints.json'), oldPrints);
+    say(() => log.ok(`Facts of version ${ctx2.cfg.document.version} archived in ${path.relative(ctx2.project, archive)}`));
+  }
 
   // 4. New version in the document control.
   const cfg = ctx2.cfg;
   const total = diff.added.length + diff.changed.length + diff.removed.length;
   const from = cfg.document.version;
   if (total && args.bump !== false) {
-    const by = [cfg.document.author, cfg.integrator.name].filter(Boolean).join(' — ') || cfg.client.name;
+    const by = [cfg.document.author, cfg.integrator.name].filter(Boolean).join(' — ') || '—';
     const history = cfg.document.history && cfg.document.history.length ? cfg.document.history : [{ version: from, date: cfg.document.date, author: by, purpose: cfg.language === 'fr' ? 'Version initiale' : 'Initial version' }];
     cfg.document.version = nextVersion(from);
     cfg.document.date = stamp;
-    const purpose = cfg.language === 'fr'
-      ? `Mise à jour : ${diff.added.length} composant(s) ajouté(s), ${diff.changed.length} modifié(s), ${diff.removed.length} supprimé(s)`
-      : `Update: ${diff.added.length} component(s) added, ${diff.changed.length} changed, ${diff.removed.length} removed`;
+    const fr = cfg.language === 'fr';
+    const parts = [[diff.added.length, fr ? 'ajouté(s)' : 'added'], [diff.changed.length, fr ? 'modifié(s)' : 'changed'], [diff.removed.length, fr ? 'supprimé(s)' : 'removed']].filter(([n]) => n).map(([n, w]) => `${n} ${w}`);
+    const purpose = `${fr ? 'Mise à jour, composants' : 'Update, components'} : ${parts.join(', ')}`.replace(/^Update, components :/, 'Update, components:');
     cfg.document.history = [...history, { version: cfg.document.version, date: stamp, author: by, purpose }];
     ctx2.save(cfg);
   }
-  const report = { from, to: cfg.document.version, changes: diff, counts, sections, next: sections.length ? 'rewrite each listed section from the new facts (keep its heading and anchor), then `tadforce build`' : 'tadforce build' };
-  writeJson(ctx2.p('facts', 'update.json'), report);
+  const report = { upToDate, from, to: cfg.document.version, changes: diff, counts, sections, next: upToDate ? null : sections.length ? 'rewrite the sections whose relevance is « components » from the new facts (keep heading and anchor); check the « counts » ones for numbers written in the text; then `npx tadforce build`' : `npx tadforce build --cwd "${ctx2.project}"` };
+  // a rerun before the rewrite and the build keeps the work to do of the previous update
+  const prevFile = ctx2.p('facts', 'update.json');
+  const prev = exists(prevFile) ? readJson(prevFile) : null;
+  if (upToDate && prev && !prev.built && prev.to === cfg.document.version && (prev.sections || []).length) {
+    const carried = { ...prev, carried: true, next: prev.next };
+    if (args.json) { console.log(JSON.stringify(carried, null, 2)); return 0; }
+    log.ok(`Nothing new since the update to ${prev.to}, whose ${prev.sections.length} section(s) are still to rewrite:`);
+    for (const s of prev.sections) console.log(`  ${c.cyan(s.id.padEnd(28))} ${c.dim((s.file || '') + (s.anchor ? '#' + s.anchor : ''))}`);
+    return 0;
+  }
+  writeJson(prevFile, report);
   if (args.json) { console.log(JSON.stringify(report, null, 2)); return 0; }
 
-  if (!total && !Object.keys(counts).length) { log.ok('Nothing changed since the last version. The document is up to date.'); return 0; }
+  if (upToDate) { log.ok('Nothing changed since the last version. The document is up to date.'); return 0; }
   log.ok(`${diff.added.length} added · ${diff.changed.length} changed · ${diff.removed.length} removed · ${Object.keys(counts).length} count(s) moved`);
   for (const [kind, list] of Object.entries(diff)) if (list.length) console.log(`  ${c.bold(kind)}: ${list.slice(0, 15).map((x) => `${x.folder}/${x.name}`).join(', ')}${list.length > 15 ? c.dim(` … +${list.length - 15}`) : ''}`);
   if (total) log.ok(`Version ${from} → ${cfg.document.version} (history updated)`);
   log.step(`${sections.length} section(s) to review:`);
-  for (const s of sections) console.log(`  ${c.cyan(s.id.padEnd(28))} ${c.dim((s.file || '') + (s.anchor ? '#' + s.anchor : ''))}  ${s.reasons.slice(0, 2).join('; ')}`);
+  for (const s of sections) console.log(`  ${s.relevance === 'components' ? c.cyan(s.id.padEnd(28)) : c.dim(s.id.padEnd(28))} ${c.dim((s.file || '') + (s.anchor ? '#' + s.anchor : ''))}  ${s.reasons.slice(0, 2).join('; ')}`);
   log.human('let your agent rewrite these sections (/tadforce-update), then `tadforce build`. Numbers and generated tables update by themselves.');
   return 0;
 }

package/src/facts/extractors/misc.js

@@ -25,6 +25,8 @@ export function extractMisc(roots) {
     genAi: count('genAiPlanners', '') + count('genAiPlannerBundles', '') + count('genAiPlugins', '') + count('genAiFunctions', '') + bundles(roots, 'aiAuthoringBundles').length,
     entitlementProcesses: count('entitlementProcesses', ''),
     dataStreams: count('dataStreamDefinitions', ''),
+    // every org has a PlatformEncryption.settings file: only switched-on options are evidence of Shield
+    platformEncryption: files(roots, 'settings', 'PlatformEncryption.settings-meta.xml').reduce((n, f) => n + (safeRead(f).match(/<enable\w*>true</g) || []).length, 0),
   };
 
   // Components documented by name only (routing, channels, sites, paths, rules, agents…)

package/src/facts/heuristics/exclusions.js

@@ -26,6 +26,7 @@ export const COLLECTIONS = [
   ['namedCredential', (f) => f.integration.namedCredentials],
   ['externalCredential', (f) => f.integration.externalCredentials],
   ['remoteSite', (f) => f.integration.remoteSites],
+  ['cspTrustedSite', (f) => f.integration.cspTrustedSites],
   ['connectedApp', (f) => f.integration.connectedApps],
   ['authProvider', (f) => f.integration.authProviders],
   ['report', (f) => f.misc.reports.names, null],
@@ -64,11 +65,21 @@ export function applyExclusions(facts, knowledge = {}) {
       }
     }
   }
+  // the tests of an excluded class leave with it (LegacyRateHelper → LegacyRateHelperTest, …_Test, …Tests)
+  const gone = new Set(applied.filter((a) => a.type === 'apex').map((a) => String(a.name).toLowerCase()));
+  const classes = facts.apex.classes;
+  for (let i = classes.length - 1; i >= 0; i--) {
+    const base = String(classes[i].name).toLowerCase().replace(/_?tests?$/, '');
+    if (classes[i].test && base !== String(classes[i].name).toLowerCase() && gone.has(base)) {
+      applied.push({ type: 'apex', name: classes[i].name, reason: `test of an excluded class`, feature: null });
+      classes.splice(i, 1);
+    }
+  }
   return applied.sort((a, b) => (a.type + a.name).localeCompare(b.type + b.name));
 }
 
 // Org-wide components (profiles, roles, queues, report folders…) are shared by every project: never scoped out.
-const SCOPED_TYPES = new Set(['apex', 'trigger', 'lwc', 'aura', 'vfPage', 'flexipage', 'app', 'tab', 'quickAction', 'flow', 'omniScript', 'integrationProcedure', 'dataMapper', 'flexCard', 'object', 'cmdt', 'permissionSet', 'permissionSetGroup', 'namedCredential', 'externalCredential', 'remoteSite', 'connectedApp', 'authProvider', 'staticResource']);
+const SCOPED_TYPES = new Set(['apex', 'trigger', 'lwc', 'aura', 'vfPage', 'flexipage', 'app', 'tab', 'quickAction', 'flow', 'omniScript', 'integrationProcedure', 'dataMapper', 'flexCard', 'object', 'cmdt', 'permissionSet', 'permissionSetGroup', 'namedCredential', 'externalCredential', 'remoteSite', 'cspTrustedSite', 'connectedApp', 'authProvider', 'staticResource']);
 
 /**
  * Keep only the part of the org a project owns (tadforce.config.json › scope.include, name patterns with `*`).
@@ -115,6 +126,7 @@ export function exclusionCandidates(facts, refs) {
     for (const item of list) {
       const name = keyOf(item, field);
       if (type === 'apex' && item.test) continue;
+      if (type === 'object' && !String(name).includes('__')) continue; // standard objects (AiEval…TestCase, Devops…Test) are Salesforce's
       const bad = nameWords(name).filter((w) => SUSPICIOUS.has(w));
       if (bad.length) add(type, name, `name suggests ${bad.join('/')}`);
     }

package/src/facts/heuristics/modules.js

@@ -35,9 +35,9 @@ const CLOUDS = [
   { id: 'netZero', name: 'Net Zero Cloud', ref: 'industries', objects: ['StnryAssetCrbnFtprnt', 'VehicleAssetCrbnFtprnt', 'Scope3CrbnFtprnt'] },
   { id: 'omnistudio', name: 'OmniStudio', ref: 'omnistudio', ns: ['omnistudio', 'vlocity_cmt', 'vlocity_ins', 'vlocity_ps'], test: (f) => Object.values(f.automation.omnistudio).some((l) => l.length > 0) },
   { id: 'dataCloud', name: 'Data Cloud', ref: 'data-cloud', test: (f) => f.misc.signals.dataStreams > 0 || f.data.objects.some((o) => /__(dlm|dll)$/.test(o.name)) || (f.misc.folders.dataStreamDefinitions || 0) + (f.misc.folders.dataSourceObjects || 0) > 0 },
-  { id: 'agentforce', name: 'Agentforce / Einstein', ref: 'agentforce-ai', test: (f) => f.misc.signals.bots + f.misc.signals.genAi > 0 || (f.misc.folders.genAiPromptTemplates || 0) + (f.misc.folders.mlPredictionDefinitions || 0) > 0 },
+  { id: 'agentforce', name: 'Agentforce / Einstein', ref: 'agentforce-ai', psg: /Agentforce|Copilot|EinsteinGPT|GenAI|Einstein_?Agent/i, test: (f) => f.misc.signals.bots + f.misc.signals.genAi > 0 || (f.misc.folders.genAiPromptTemplates || 0) + (f.misc.folders.mlPredictionDefinitions || 0) > 0 },
   { id: 'crmAnalytics', name: 'CRM Analytics', ref: 'analytics', ns: ['wave'], test: (f) => ['wave', 'waveDashboards', 'waveDataflows', 'waveRecipes', 'waveApplications', 'waveDatasets'].some((k) => f.misc.folders[k] > 0) },
-  { id: 'shield', name: 'Shield (encryption, event monitoring, audit)', ref: 'security-shield', test: (f) => ['transactionSecurityPolicies', 'eventSubscriptions'].some((k) => f.misc.folders[k] > 0) || f.misc.settings.some((s) => /PlatformEncryption|EventSettings|FieldHistoryRetention/.test(s)) },
+  { id: 'shield', name: 'Shield (encryption, event monitoring, audit)', ref: 'security-shield', test: (f) => ['transactionSecurityPolicies', 'eventSubscriptions'].some((k) => f.misc.folders[k] > 0) || (f.misc.signals.platformEncryption || 0) > 0 },
   { id: 'slack', name: 'Slack integration', ref: 'integration-platforms', ns: ['slackv2', 'slack'], test: (f) => (f.misc.folders.slackApps || 0) > 0 },
   { id: 'events', name: 'Platform Events / Change Data Capture', ref: 'platform-events', test: (f) => f.data.objects.some((o) => o.kind === 'platformEvent') || f.data.cdc.length > 0 },
 ];
@@ -53,7 +53,7 @@ function usedStandard(f) {
   return used;
 }
 
-export function detectModules(f) {
+export function detectModules(f, org = null) {
   const ns = new Set(f.namespaces.map((n) => n.namespace));
   const std = usedStandard(f);
   const clouds = [];
@@ -63,6 +63,8 @@ export function detectModules(f) {
     for (const n of c.ns || []) if (ns.has(n)) evidence.push(`namespace ${n}`);
     for (const o of c.objects || []) if (std.has(o) || f.data.objects.some((x) => x.name === o && x.kind === 'standard' && x.customFields > 0)) evidence.push(`object ${o}`);
     if (c.test && c.test(f)) evidence.push('metadata');
+    // users assigned to the product's permission set groups (aggregated org facts) prove it is used
+    for (const g of (org && org.psgAssignments) || []) if (c.psg && c.psg.test(String(g.group)) && g.users > 0) evidence.push(`permission set group ${g.group} (${g.users} users)`);
     const on = evidence.length > 0;
     flags[c.id] = on;
     if (on) clouds.push({ id: c.id, name: c.name, reference: c.ref, evidence: [...new Set(evidence)].slice(0, 6) });

package/src/facts/index.js

@@ -36,6 +36,7 @@ export function extractFacts(dirs, knowledge = {}, opts = {}) {
   const refs = references(roots, apex, ui, automation, integration);
   const facts = { schema: FACTS_SCHEMA, apex, data, automation, ui, security, integration, misc, namespaces };
 
+  const shipped = removeSalesforceShipped(facts);
   const outOfScope = applyScope(facts, knowledge.scope || {});
   const applied = applyExclusions(facts, knowledge.exclusions || {});
   // placements are recomputed so that excluded containers no longer count as usages
@@ -51,7 +52,8 @@ export function extractFacts(dirs, knowledge = {}, opts = {}) {
 
   facts.exclusions = { applied, candidates: exclusionCandidates(facts, refs) };
   if ((knowledge.scope?.include || []).length) facts.scope = { include: [...knowledge.scope.include], outOfScope: outOfScope.length };
-  facts.modules = detectModules(facts);
+  facts.modules = detectModules(facts, opts.org || null);
+  if (Object.keys(shipped).length) facts.salesforceShipped = shipped;
   // Products used without metadata traces are declared by a human in glossary.yml › products.
   for (const p of (knowledge.glossary && knowledge.glossary.products) || []) {
     if (!p || !p.name || facts.modules.clouds.some((c) => c.name === p.name)) continue;
@@ -74,6 +76,23 @@ export function extractFacts(dirs, knowledge = {}, opts = {}) {
   return facts;
 }
 
+// Components Salesforce ships in every org (standard apps, platform permission set groups…): not the project's architecture.
+const SHIPPED = /^(standard__|force__|sfdcInternalInt__|sf_devops)/;
+
+/** Set aside what Salesforce ships with the org; returns how many of each kind, by facts path. */
+function removeSalesforceShipped(f) {
+  const out = {};
+  // the utility bars of Salesforce's own apps go with them
+  const bars = new Set(f.ui.apps.filter((x) => SHIPPED.test(String(x.name)) && x.utilityBar).map((x) => x.utilityBar));
+  for (let i = f.ui.flexipages.length - 1; i >= 0; i--) if (bars.has(f.ui.flexipages[i].name)) { f.ui.flexipages.splice(i, 1); out['ui.utilityBars'] = (out['ui.utilityBars'] || 0) + 1; }
+  for (const [key, list] of [['ui.apps', f.ui.apps], ['ui.tabs', f.ui.tabs], ['ui.flexipages', f.ui.flexipages], ['security.permissionSets', f.security.permissionSets], ['security.permissionSetGroups', f.security.permissionSetGroups]]) {
+    let n = 0;
+    for (let i = list.length - 1; i >= 0; i--) if (SHIPPED.test(String(list[i].name))) { list.splice(i, 1); n++; }
+    if (n) out[key] = n;
+  }
+  return out;
+}
+
 /** Cross-references: where Apex classes, LWC/Aura and FlexiPages are used. */
 function references(roots, apex, ui, automation, integration) {
   const nonTest = apex.classes.filter((c) => !c.test);

package/src/sf/sf.js

@@ -1,5 +1,8 @@
 // Read-only wrapper around the Salesforce CLI. Every call goes through an allow-list:
 // TADForce never deploys, never deletes, never reads record-level data.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
 import { spawn, spawnSync } from 'node:child_process';
 
 const ALLOWED = [
@@ -16,6 +19,8 @@ const ALLOWED = [
   ['package', 'installed', 'list'],
   ['config', 'get'],
 ];
+// Read-only commands that take positional arguments after their subcommand words (`sf config get target-org`).
+const WITH_POSITIONALS = [['config', 'get']];
 
 // sObjects whose rows describe the org itself (configuration, not business data).
 const METADATA_SOBJECTS = new Set([
@@ -30,7 +35,8 @@ export function isAllowed(args) {
   const cmd = [];
   for (const a of args) { if (a.startsWith('-')) break; cmd.push(a); }
   if (!cmd.length) return args[0] === '--version';
-  return ALLOWED.some((p) => p.length === cmd.length && p.every((w, i) => w === cmd[i]));
+  if (ALLOWED.some((p) => p.length === cmd.length && p.every((w, i) => w === cmd[i]))) return true;
+  return WITH_POSITIONALS.some((p) => cmd.length > p.length && p.every((w, i) => w === cmd[i]) && cmd.slice(p.length).every((a) => /^[\w-]+$/.test(a)));
 }
 
 const AGG = /^(count\(\s*(id)?\s*\)|max\(\s*(createddate|lastmodifieddate)\s*\)|min\(\s*createddate\s*\))(\s+\w+)?$/i;
@@ -66,8 +72,21 @@ function launch(args, opts) {
   return [[resolveSf(), ...args].map(quote).join(' '), [], { ...opts, shell: true }];
 }
 
-/** Run `sf ... --json` and return the parsed result (throws with the CLI message on failure). */
-export function sfJson(args, { timeoutMs = 600000, cwd } = {}) {
+// Network hiccups (DNS, resets) are retried; the CLI reports a failed DNS lookup as DomainNotFoundError.
+const TRANSIENT = /DomainNotFound|ENOTFOUND|EAI_AGAIN|ECONNRESET|ETIMEDOUT|socket hang up|getaddrinfo/i;
+export const isTransient = (e) => TRANSIENT.test(`${e && e.name} ${e && e.message} ${e && e.sf && e.sf.name}`);
+
+/** Run `sf ... --json` and return the parsed result (throws with the CLI message on failure). Transient network errors are retried twice. */
+export async function sfJson(args, opts = {}) {
+  for (let attempt = 0; ; attempt++) {
+    try { return await sfJsonOnce(args, opts); } catch (e) {
+      if (attempt >= 2 || !isTransient(e)) throw e;
+      await new Promise((r) => setTimeout(r, 1500 * (attempt + 1)));
+    }
+  }
+}
+
+function sfJsonOnce(args, { timeoutMs = 600000, cwd } = {}) {
   if (!isAllowed(args)) throw new Error(`TADForce refuses to run: sf ${args.join(' ')}`);
   if (args[0] === 'data' && args[1] === 'query') {
     const qi = args.findIndex((a) => a === '--query' || a === '-q');
@@ -105,12 +124,17 @@ export function sfInteractive(args) {
   return r.status === 0;
 }
 
+// `sf --version` takes seconds: its answer is kept a day (per CLI binary), outside any project.
+const VERSION_CACHE = path.join(os.tmpdir(), 'tadforce-sf-version.json');
 export function sfVersion() {
+  try { const c = JSON.parse(fs.readFileSync(VERSION_CACHE, 'utf8')); if (c.bin === resolveSf() && Date.now() - c.at < 86400000 && c.version) return c.version; } catch { /* no cache yet */ }
   const [cmd, argv, opts] = launch(['--version'], { encoding: 'utf8' });
   const r = spawnSync(cmd, argv, opts);
   if (r.status !== 0) return null;
   const m = /@salesforce\/cli\/(\d+\.\d+\.\d+)/.exec(r.stdout || '');
-  return m ? m[1] : (r.stdout || '').trim() || null;
+  const version = m ? m[1] : (r.stdout || '').trim() || null;
+  try { fs.writeFileSync(VERSION_CACHE, JSON.stringify({ bin: resolveSf(), version, at: Date.now() })); } catch { /* no writable tmp: no cache */ }
+  return version;
 }
 
 export function soql(query, alias, { tooling = false } = {}) {

package/src/util/config.js

@@ -65,7 +65,7 @@ export function findWorkspace(cwd = process.cwd()) {
 export function loadWorkspace(cwd) {
   const ws = findWorkspace(cwd);
   if (!ws) {
-    const err = new Error(`No TADForce workspace found under ${cwd}. Run \`npx tadforce init\` first.`);
+    const err = new Error(`No TADForce workspace found under ${cwd}. Run \`npx tadforce doctor\` in your Salesforce project first.`);
     err.code = 'NO_WORKSPACE';
     throw err;
   }
@@ -82,6 +82,9 @@ export function loadWorkspace(cwd) {
   };
 }
 
+/** Flags for the skeletons' conditions: `<!-- tad:if source.local -->`. */
+export const sourceFlags = (cfg) => ({ local: cfg.source.mode === 'local', org: cfg.source.mode !== 'local' });
+
 /** Metadata source directories: the retrieved snapshot and/or the project's package dirs (source.mode). */
 export function sourceDirs(wsCtx) {
   const mode = wsCtx.cfg.source.mode;

package/src/util/i18n.js

@@ -41,6 +41,16 @@ export function t(dict, key, vars = {}) {
   return s.replace(/\{(\w+)\}/g, (m, k) => (vars[k] !== undefined ? String(vars[k]) : m));
 }
 
+const locale = (lang) => (lang === 'fr' ? 'fr-FR' : lang === 'en' || !lang ? 'en-GB' : lang);
+
+/** 2026-10-30 → 30 October 2026 / 30 octobre 2026 / 30 de octubre de 2026. Anything else is kept as written. */
+export function formatDate(value, lang) {
+  const m = /^(\d{4})-(\d{2})-(\d{2})$/.exec(String(value || ''));
+  if (!m) return value;
+  const d = new Date(Date.UTC(+m[1], +m[2] - 1, +m[3]));
+  try { return new Intl.DateTimeFormat(locale(lang), { day: 'numeric', month: 'long', year: 'numeric', timeZone: 'UTC' }).format(d); } catch { return value; }
+}
+
 export function formatNumber(n, lang) {
   if (typeof n !== 'number' || !Number.isFinite(n)) return String(n);
   // fr-FR uses a narrow no-break space as thousands separator, as in the reference document.

package/src/validate/index.js

@@ -73,7 +73,8 @@ export function validateDocument(wsCtx, doc, { buildReport = null } = {}) {
       const pend = /<!--\s*tad:pending\s+([\w.-]+)\s*-->/.exec(line);
       // sections inside a false <!-- tad:if --> block are not part of this org's document
       if (pend && (!buildReport || buildReport.pending.includes(pend[1]))) add('error', 'pending', `Section "${pend[1]}" is not written yet.`, where);
-      if (/\bTODO\b|\bTBD\b|lorem ipsum/i.test(line)) add('error', 'todo', 'Placeholder text left in the document.', where);
+      // upper-case markers as whole words only: « Método », « todo » (Spanish « all ») are text, not placeholders
+      if (/(?<![\p{L}\p{N}_])(TODO|TBD|FIXME)(?![\p{L}\p{N}_])/u.test(line) || /lorem ipsum/i.test(line)) add('error', 'todo', 'Placeholder text left in the document.', where);
       for (const [id, re] of SECRET_PATTERNS) if (re.test(line)) add('error', 'secret', `Possible secret or org identifier (${id}).`, where);
       for (const a of avoid) if (new RegExp(`\\b${escapeRe(a.avoid)}\\b`, 'i').test(line)) add('error', 'terminology', `"${a.avoid}" must be written "${a.use}" (glossary).`, where);
       for (const fk of forbiddenFeatures) if (new RegExp(`\\b${escapeRe(fk.k)}\\b`, 'i').test(line)) add('error', 'decommissioned', `Mentions "${fk.k}" (decommissioned feature: ${fk.feature}).`, where);
@@ -91,7 +92,7 @@ export function validateDocument(wsCtx, doc, { buildReport = null } = {}) {
         if (/[*_]$/.test(id) || /^\*/.test(id)) continue; // naming patterns such as `NWB_*` or `*Service`
         if (!looksLikeComponent(id) || COMMON.has(id) || inventory.has(id)) continue;
         if (/^[\w]+\.[\w]+$/.test(id) && inventory.has(id.split('.')[1])) continue;
-        add('warn', 'unknown-component', `\`${id}\` is not in the metadata inventory (typo, other org, or package component?).`, where);
+        add('warn', 'unknown-component', `\`${id}\` is not in the metadata inventory (${(wsCtx.cfg.scope && wsCtx.cfg.scope.include || []).length ? 'out of the project scope, ' : ''}typo, other org, or package component?).`, where);
       }
     });
     if (inCode) add('error', 'unclosed-code', 'Unclosed code fence.', `src/${doc}/${f}`);

package/templates/html/editor.js

@@ -497,6 +497,31 @@
     } catch (e) { toast(T('docxFailed', { error: e.message }), 5000); }
   }
 
+  // A rebuilt document carries the comments, not their highlights: find each quoted passage again.
+  function reanchor(c) {
+    if (c.kind === 'zone' || !c.quote || marksOf(c.id).length) return;
+    var q = c.quote.replace(/…$/, '').trim(), probe = q.slice(0, 40);
+    if (probe.length < 6) return;
+    for (var zi = 0; zi < zones.length; zi++) {
+      if (!zones[zi]) continue;
+      var w = document.createTreeWalker(zones[zi], NodeFilter.SHOW_TEXT, null), n;
+      while ((n = w.nextNode())) {
+        if (n.parentElement.closest('svg, mark.tad-cmt')) continue;
+        var i = n.nodeValue.indexOf(probe);
+        if (i < 0) continue;
+        var r = document.createRange();
+        r.setStart(n, i); r.setEnd(n, Math.min(n.nodeValue.length, i + q.length));
+        wrapRange(r, c.id);
+        return;
+      }
+    }
+    // the quoted words were corrected: pin the comment on its section heading instead
+    var heads = document.querySelectorAll('article.doc h1, article.doc h2, article.doc h3');
+    for (var hi = 0; hi < heads.length; hi++) {
+      if (c.section && heads[hi].textContent.indexOf(c.section) >= 0) { insertPin(heads[hi], c.id); return; }
+    }
+  }
+  comments.forEach(reanchor);
   comments.forEach(function (c) { if (c.status === 'resolved') marksOf(c.id).forEach(function (m) { m.classList.add('resolved'); }); });
   render();
 })();

package/templates/i18n/en.json

@@ -126,7 +126,8 @@
     "scopeValue": "Salesforce organization ({environment}) of {client}, state as of {date}",
     "firstVersion": "Consolidated version submitted to {client} for review and approval",
     "preparedBy": "Prepared by",
-    "scopeLimited": "Scope limited to: {scope}"
+    "scopeLimited": "Scope limited to: {scope}",
+    "scopeValueLocal": "Salesforce DX project of {client} (metadata sources), state as of {date}"
   },
   "legend": {
     "actor": "Actors: users, populations, channels",
@@ -171,7 +172,8 @@
     "ec": "{n} External Credentials",
     "rest": "{n} Apex REST services",
     "apps2": "{n} connected apps",
-    "caption": "Logical architecture in layers"
+    "caption": "Logical architecture in layers",
+    "servicesTitle": "Services"
   },
   "context": {
     "salesforce": "Salesforce organization",
@@ -362,5 +364,9 @@
     "nc": "Named / External credentials",
     "rest": "Apex REST services",
     "reports": "Reports / dashboards"
+  },
+  "figures": {
+    "roles": "Role hierarchy",
+    "integrations": "Integration map"
   }
 }

package/templates/i18n/fr.json

@@ -126,7 +126,8 @@
     "scopeValue": "Organisation Salesforce ({environment}) de {client}, état au {date}",
     "firstVersion": "Version consolidée remise à {client} pour revue et validation",
     "preparedBy": "Établi par",
-    "scopeLimited": "Périmètre limité à : {scope}"
+    "scopeLimited": "Périmètre limité à : {scope}",
+    "scopeValueLocal": "Projet Salesforce DX de {client} (sources de métadonnées), état au {date}"
   },
   "legend": {
     "actor": "Acteurs : utilisateurs, populations, canaux",
@@ -171,7 +172,8 @@
     "ec": "{n} External Credentials",
     "rest": "{n} services Apex REST",
     "apps2": "{n} applications connectées",
-    "caption": "Architecture logique en couches"
+    "caption": "Architecture logique en couches",
+    "servicesTitle": "Services"
   },
   "context": {
     "salesforce": "Organisation Salesforce",
@@ -362,5 +364,9 @@
     "nc": "Named / External credentials",
     "rest": "Services Apex REST",
     "reports": "Rapports / tableaux de bord"
+  },
+  "figures": {
+    "roles": "Hiérarchie des rôles",
+    "integrations": "Carte des intégrations"
   }
 }