tadforce 0.0.0-stage → 0.3.0

package/src/facts/index.js

@@ -0,0 +1,197 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { readJson, exists, toPosix, safeReadJson } from '../util/fsx.js';
+import { findMetadataRoots, files, safeRead, clearReadCache } from './xml.js';
+import { extractApex, tokens } from './extractors/apex.js';
+import { extractData } from './extractors/data.js';
+import { extractAutomation } from './extractors/automation.js';
+import { extractUi, placements } from './extractors/ui.js';
+import { extractSecurity } from './extractors/security.js';
+import { extractIntegration } from './extractors/integration.js';
+import { extractMisc, detectNamespaces } from './extractors/misc.js';
+import { applyExclusions, applyScope, exclusionCandidates } from './heuristics/exclusions.js';
+import { detectModules } from './heuristics/modules.js';
+import { detectNaming } from './heuristics/naming.js';
+import { computeSignals } from './heuristics/signals.js';
+
+export const FACTS_SCHEMA = 1;
+
+/**
+ * Build facts.json from source-format metadata. Pure and deterministic: same input, same bytes.
+ * @param {string[]} dirs   source directories (snapshot or package directories)
+ * @param {object} knowledge { exclusions, glossary, scope }
+ * @param {object} [opts]   { base: path used to relativise roots, org: org facts, codeAnalyzer }
+ */
+export function extractFacts(dirs, knowledge = {}, opts = {}) {
+  const roots = findMetadataRoots(dirs);
+  const apex = extractApex(roots);
+  const data = extractData(roots);
+  const automation = extractAutomation(roots);
+  const ui = extractUi(roots);
+  const security = extractSecurity(roots);
+  const integration = extractIntegration(roots);
+  const misc = extractMisc(roots);
+  const namespaces = detectNamespaces(roots, misc.installedPackages);
+
+  const refs = references(roots, apex, ui, automation, integration);
+  const facts = { schema: FACTS_SCHEMA, apex, data, automation, ui, security, integration, misc, namespaces };
+
+  const outOfScope = applyScope(facts, knowledge.scope || {});
+  const applied = applyExclusions(facts, knowledge.exclusions || {});
+  // placements are recomputed so that excluded containers no longer count as usages
+  const placementsAfter = {};
+  const live = new Set([...facts.ui.flexipages.map((p) => 'flexipage:' + p.name), ...facts.ui.lwc.map((l) => 'lwc:' + l.name), ...facts.ui.aura.map((a) => 'aura:' + a.name)]);
+  for (const [comp, uses] of Object.entries(refs.placements)) {
+    const kept = uses.filter((u) => !['flexipage', 'lwc', 'aura'].includes(u.kind) || live.has(u.kind + ':' + u.name));
+    if (kept.length) placementsAfter[comp] = kept;
+  }
+  refs.placements = placementsAfter;
+  for (const l of facts.ui.lwc) l.placedIn = placementsAfter[l.name] || [];
+  for (const a of facts.ui.aura) a.placedIn = placementsAfter[a.name] || [];
+
+  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);
+  // 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;
+    facts.modules.clouds.push({ id: p.id || p.name, name: p.name, reference: p.reference || null, evidence: ['declared'] });
+    if (p.id) facts.modules[p.id] = true;
+    if (p.reference && !facts.modules.references.includes(p.reference)) facts.modules.references.push(p.reference);
+    if (!facts.modules.products.includes(p.name)) facts.modules.products.push(p.name);
+  }
+  facts.naming = detectNaming(facts);
+  facts.systems = externalSystems(facts, knowledge.glossary || {});
+  facts.counts = counts(facts);
+  facts.inventory = inventory(facts);
+  facts.signals = computeSignals(facts, opts.org || null, opts.codeAnalyzer || null);
+  facts.sources = roots.map((r) => (opts.base ? toPosix(path.relative(opts.base, r)) || '.' : toPosix(r)));
+
+  // internal token sets are not serialised
+  for (const c of facts.apex.classes) delete c._tokens;
+  for (const t of facts.apex.triggers) delete t._tokens;
+  clearReadCache();
+  return facts;
+}
+
+/** 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);
+  const testTokens = new Set();
+  for (const c of apex.classes.filter((c) => c.test)) for (const t of c._tokens) testTokens.add(t);
+  const prodTokens = new Map(); // token -> count of producing files
+  const bump = (set, self) => { for (const t of set) if (t !== self) prodTokens.set(t, (prodTokens.get(t) || 0) + 1); };
+  for (const c of nonTest) bump(c._tokens, c.name);
+  for (const t of apex.triggers) bump(t._tokens, null);
+  const textFolders = ['flows', 'omniScripts', 'omniIntegrationProcedures', 'omniDataTransforms', 'omniUiCard', 'aura', 'lwc', 'pages', 'components', 'authproviders', 'quickActions', 'customMetadata', 'experiences', 'digitalExperiences', 'emailservices', 'objects', 'permissionsets', 'profiles', 'flexipages'];
+  for (const folder of textFolders) {
+    for (const f of files(roots, folder, '', { recursive: true })) {
+      if (!/\.(xml|js|html|cmp|app|page|component|json|design|evt)$/.test(f)) continue;
+      if (folder === 'permissionsets' || folder === 'profiles') continue; // class access grants are not usages
+      bump(tokens(safeRead(f)), null);
+    }
+  }
+  const apexReferenced = new Set(nonTest.filter((c) => prodTokens.has(c.name)).map((c) => c.name));
+  for (const l of ui.lwc) for (const a of l.apex) apexReferenced.add(a);
+  const apexReferencedByTests = new Set(nonTest.filter((c) => testTokens.has(c.name)).map((c) => c.name));
+
+  const assignTokens = new Set();
+  for (const folder of ['applications', 'objects', 'tabs', 'customApplications']) {
+    for (const f of files(roots, folder, '', { recursive: true })) if (/\.(app-meta|object-meta|tab-meta)\.xml$/.test(f)) for (const t of tokens(safeRead(f))) assignTokens.add(t);
+  }
+  const flexipageAssigned = new Set(ui.flexipages.filter((p) => assignTokens.has(p.name) || p.type === 'UtilityBar' && ui.apps.some((a) => a.utilityBar === p.name)).map((p) => p.name));
+  return { placements: placements(roots, ui), apexReferenced, apexReferencedByTests, flexipageAssigned };
+}
+
+/** External systems seen from Salesforce, grouped by host, and named from the glossary when possible. */
+function externalSystems(f, glossary) {
+  const endpoints = [];
+  for (const n of f.integration.namedCredentials) endpoints.push({ kind: 'namedCredential', name: n.name, host: n.host });
+  for (const r of f.integration.remoteSites) endpoints.push({ kind: 'remoteSite', name: r.name, host: r.host });
+  for (const c of f.integration.cspTrustedSites) endpoints.push({ kind: 'cspTrustedSite', name: c.name, host: c.host });
+  for (const a of f.integration.authProviders) endpoints.push({ kind: 'authProvider', name: a.name, host: null });
+  for (const a of f.integration.connectedApps) endpoints.push({ kind: 'connectedApp', name: a.name, host: null });
+  for (const c of f.integration.callCenters) endpoints.push({ kind: 'callCenter', name: c.name, host: c.adapterHost });
+  const systems = (glossary.systems || []).map((s) => ({ id: s.id || s.name, name: s.name, description: s.description || null, match: (s.match || []).map(String), endpoints: [] }));
+  const unnamed = [];
+  for (const e of endpoints) {
+    const sys = systems.find((s) => s.match.some((m) => m.toLowerCase() === String(e.name).toLowerCase() || (e.host && (e.host === m.toLowerCase() || e.host.endsWith('.' + m.toLowerCase())))));
+    if (sys) sys.endpoints.push(e); else unnamed.push(e);
+  }
+  for (const s of systems) { s.endpoints.sort((a, b) => (a.kind + a.name).localeCompare(b.kind + b.name)); delete s.match; }
+  return { named: systems, unnamed: unnamed.sort((a, b) => (a.kind + a.name).localeCompare(b.kind + b.name)) };
+}
+
+function counts(f) {
+  const app = f.apex.classes.filter((c) => !c.test);
+  const kind = (k) => app.filter((c) => c.kinds.includes(k)).length;
+  const local = f.data.objects.filter((o) => !o.namespace);
+  const o = f.automation.omnistudio;
+  return {
+    apex: { classes: app.length, tests: f.apex.classes.filter((c) => c.test).length, triggers: f.apex.triggers.length, batch: kind('batch'), queueable: kind('queueable'), schedulable: kind('schedulable'), future: kind('future'), rest: kind('rest'), soap: kind('soap'), invocable: kind('invocable'), auraEnabled: kind('auraEnabled'), callout: kind('callout'), lines: app.reduce((n, c) => n + c.lines, 0), withSharing: app.filter((c) => c.sharing === 'with').length, withoutSharing: app.filter((c) => c.sharing === 'without').length, inheritedSharing: app.filter((c) => c.sharing === 'inherited').length },
+    objects: { custom: local.filter((x) => x.kind === 'custom').length, standard: local.filter((x) => x.kind === 'standard').length, managed: f.data.objects.filter((x) => x.namespace).length, platformEvents: local.filter((x) => x.kind === 'platformEvent').length, customSettings: local.filter((x) => x.kind === 'customSetting').length, cmdtTypes: f.data.cmdtTypes.length, bigObjects: local.filter((x) => x.kind === 'bigObject').length, externalObjects: local.filter((x) => x.kind === 'externalObject').length },
+    fields: { custom: f.data.objects.reduce((n, x) => n + x.customFields, 0), externalIds: f.data.objects.reduce((n, x) => n + x.externalIds.length, 0), relations: f.data.objects.reduce((n, x) => n + x.relations.length, 0), formulas: f.data.objects.reduce((n, x) => n + x.formulaFields, 0) },
+    recordTypes: f.data.objects.reduce((n, x) => n + x.recordTypes.length, 0),
+    validationRules: { total: f.data.objects.reduce((n, x) => n + x.validationRules.length, 0), active: f.data.objects.reduce((n, x) => n + x.validationRules.filter((v) => v.active).length, 0) },
+    cmdt: { types: f.data.cmdtTypes.length, records: f.data.cmdtTypes.reduce((n, t) => n + t.records, 0) },
+    flows: { total: f.automation.flows.length, active: f.automation.flows.filter((x) => x.active).length, recordTriggered: f.automation.flows.filter((x) => x.active && /Record/.test(x.triggerType || '')).length, scheduled: f.automation.flows.filter((x) => x.active && x.triggerType === 'Scheduled').length, screen: f.automation.flows.filter((x) => x.active && x.processType === 'Flow').length, autolaunched: f.automation.flows.filter((x) => x.active && x.processType === 'AutoLaunchedFlow' && !x.triggerType).length, platformEvent: f.automation.flows.filter((x) => x.active && x.triggerType === 'PlatformEvent').length },
+    omni: { scripts: o.omniScripts.length, scriptsActive: o.omniScripts.filter((x) => x.active).length, ips: o.integrationProcedures.length, ipsActive: o.integrationProcedures.filter((x) => x.active).length, dataMappers: o.dataMappers.length, dataMappersActive: o.dataMappers.filter((x) => x.active).length, cards: o.flexCards.length, cardsActive: o.flexCards.filter((x) => x.active).length },
+    ui: { apps: f.ui.apps.length, consoleApps: f.ui.apps.filter((a) => a.console).length, flexipages: f.ui.flexipages.length, recordPages: f.ui.flexipages.filter((p) => p.type === 'RecordPage').length, lwc: f.ui.lwc.length, aura: f.ui.aura.length, vfPages: f.ui.vfPages.length, tabs: f.ui.tabs.length, quickActions: f.ui.quickActions.length, messageChannels: f.ui.messageChannels.length },
+    security: { profiles: f.security.profiles.length, permissionSets: f.security.permissionSets.length, permissionSetGroups: f.security.permissionSetGroups.length, roles: f.security.roles.length, queues: f.security.queues.length, groups: f.security.groups.length, sharingRules: f.security.sharingRules.reduce((n, s) => n + s.rules.length, 0), customPermissions: f.security.customPermissions.length },
+    integration: { namedCredentials: f.integration.namedCredentials.length, externalCredentials: f.integration.externalCredentials.length, remoteSites: f.integration.remoteSites.length, connectedApps: f.integration.connectedApps.length, authProviders: f.integration.authProviders.length, cspTrustedSites: f.integration.cspTrustedSites.length, corsOrigins: f.integration.corsOrigins.length, restResources: kind('rest'), callCenters: f.integration.callCenters.length, externalServices: f.integration.externalServices.length, systems: f.systems.named.length },
+    misc: { labels: f.misc.labels.length, staticResources: f.misc.staticResources.length, reports: f.misc.reports.names.length, dashboards: f.misc.dashboards.names.length, reportTypes: f.misc.reportTypes.length, emailTemplates: f.misc.emailTemplates.length, namespaces: f.namespaces.length },
+    exclusions: { applied: f.exclusions.applied.length, candidates: f.exclusions.candidates.length },
+  };
+}
+
+/** Every documented component name, used by `tadforce validate` to check identifiers in the text. */
+function inventory(f) {
+  const names = new Set();
+  const addAll = (xs, k = 'name') => xs.forEach((x) => names.add(typeof x === 'string' ? x : x[k]));
+  addAll(f.apex.classes); addAll(f.apex.triggers); addAll(f.ui.lwc); addAll(f.ui.aura); addAll(f.ui.vfPages); addAll(f.ui.flexipages); addAll(f.ui.apps); addAll(f.ui.tabs); addAll(f.ui.quickActions);
+  addAll(f.automation.flows);
+  for (const k of Object.keys(f.automation.omnistudio)) {
+    addAll(f.automation.omnistudio[k]);
+    f.automation.omnistudio[k].forEach((x) => { [x.type, x.subType, x.label].forEach((v) => v && names.add(v)); if (x.type && x.subType) { names.add(`${x.type}_${x.subType}`); names.add(`${x.type}/${x.subType}`); } });
+  }
+  for (const list of Object.values(f.misc.named || {})) addAll(list);
+  for (const o of f.data.objects) { names.add(o.name); (o.customFieldNames || []).forEach((x) => { names.add(x); names.add(`${o.name}.${x}`); }); o.externalIds.forEach((x) => { names.add(x); names.add(`${o.name}.${x}`); }); o.relations.forEach((r) => { names.add(r.field); names.add(`${o.name}.${r.field}`); r.to.forEach((x) => names.add(x)); }); o.recordTypes.forEach((r) => names.add(r.name)); o.validationRules.forEach((v) => names.add(v.name)); }
+  for (const t of f.data.cmdtTypes) { names.add(t.type); t.names.forEach((n) => names.add(n)); }
+  addAll(f.security.profiles); addAll(f.security.permissionSets); addAll(f.security.permissionSetGroups); addAll(f.security.roles); addAll(f.security.queues); addAll(f.security.groups); addAll(f.security.customPermissions);
+  f.security.sharingRules.forEach((s) => s.rules.forEach((r) => names.add(r.name)));
+  addAll(f.integration.namedCredentials); addAll(f.integration.externalCredentials); addAll(f.integration.remoteSites); addAll(f.integration.connectedApps); addAll(f.integration.authProviders); addAll(f.integration.cspTrustedSites); addAll(f.integration.callCenters);
+  f.apex.classes.forEach((c) => c.restUrl && names.add(c.restUrl));
+  addAll(f.ui.messageChannels); addAll(f.misc.reports.folders);
+  f.integration.connectedApps.forEach((a) => a.scopes.forEach((s) => names.add(s)));
+  [...f.security.profiles, ...f.security.permissionSets].forEach((p) => p.powerful.forEach((x) => names.add(x)));
+  addAll(f.misc.labels); addAll(f.misc.staticResources); addAll(f.misc.reports.names); addAll(f.misc.dashboards.names); addAll(f.misc.reportTypes); addAll(f.misc.emailTemplates); addAll(f.data.globalValueSets);
+  return [...names].filter(Boolean).sort((a, b) => a.localeCompare(b));
+}
+
+export function loadFacts(ws) {
+  const p = path.join(ws, 'facts', 'facts.json');
+  if (!exists(p)) return null;
+  const facts = readJson(p);
+  const orgP = path.join(ws, 'facts', 'org.json');
+  facts.org = exists(orgP) ? readJson(orgP) : null;
+  return facts;
+}
+
+/** Summarise a Code Analyzer JSON report (sf code-analyzer run --output-file x.json) if the user provided one. */
+export function readCodeAnalyzer(ws) {
+  const dir = path.join(ws, 'knowledge', 'inputs');
+  if (!exists(dir)) return null;
+  const f = fs.readdirSync(dir).find((n) => /code-analyzer.*\.json$/i.test(n));
+  if (!f) return null;
+  const j = safeReadJson(path.join(dir, f));
+  const violations = j?.violations || j?.results?.flatMap?.((r) => r.violations || []) || [];
+  if (!violations.length) return null;
+  const bySeverity = {}, byRule = {};
+  for (const v of violations) {
+    const sev = String(v.severity ?? v.sev ?? 3);
+    bySeverity[sev] = (bySeverity[sev] || 0) + 1;
+    const rule = v.rule || v.ruleName || 'rule';
+    byRule[rule] = (byRule[rule] || 0) + 1;
+  }
+  return { file: f, total: violations.length, bySeverity, topRules: Object.entries(byRule).sort((a, b) => b[1] - a[1]).slice(0, 10).map(([rule, count]) => ({ rule, count })) };
+}

package/src/facts/org.js

@@ -0,0 +1,87 @@
+// Live org facts: configuration and aggregates only (COUNT, MAX(CreatedDate), GROUP BY).
+// Stored apart from facts.json (facts/org.json) because they change over time.
+import { soql, sfJson } from '../sf/sf.js';
+
+async function safe(fn, fallback = null) {
+  try { return await fn(); } catch (e) { return { error: e.message.slice(0, 300), value: fallback }; }
+}
+const rows = (r) => (r && Array.isArray(r.records) ? r.records : []);
+const unwrap = (v) => (v && v.error !== undefined ? v.value : v);
+
+async function pool(items, n, fn) {
+  const out = new Array(items.length);
+  let i = 0;
+  await Promise.all(Array.from({ length: Math.min(n, items.length) }, async () => {
+    while (i < items.length) { const k = i++; out[k] = await fn(items[k], k); }
+  }));
+  return out;
+}
+
+export async function collectOrgFacts(alias, facts, { onProgress = () => {} } = {}) {
+  const errors = [];
+  const run = async (label, fn, fallback) => { const v = await safe(fn, fallback); if (v && v.error !== undefined) errors.push({ step: label, error: v.error }); return unwrap(v); };
+
+  onProgress('organization');
+  const orgRow = rows(await run('organization', () => soql('SELECT Name, OrganizationType, IsSandbox, InstanceName, LanguageLocaleKey, DefaultLocaleSidKey, TimeZoneSidKey, NamespacePrefix FROM Organization', alias)))[0] || null;
+  const organization = orgRow && {
+    name: orgRow.Name, edition: orgRow.OrganizationType, sandbox: orgRow.IsSandbox, instance: orgRow.InstanceName,
+    language: orgRow.LanguageLocaleKey, locale: orgRow.DefaultLocaleSidKey, timeZone: orgRow.TimeZoneSidKey,
+  };
+
+  onProgress('users');
+  const usersByProfile = rows(await run('users', () => soql('SELECT Profile.Name p, COUNT(Id) c FROM User WHERE IsActive = true GROUP BY Profile.Name', alias)))
+    .map((r) => ({ profile: r.p || r.Name, users: r.c ?? r.expr0 })).sort((a, b) => String(a.profile).localeCompare(String(b.profile)));
+  const usersByLicense = rows(await run('licenses', () => soql('SELECT Name, TotalLicenses, UsedLicenses FROM UserLicense', alias)))
+    .filter((r) => r.UsedLicenses > 0).map((r) => ({ license: r.Name, used: r.UsedLicenses, total: r.TotalLicenses })).sort((a, b) => a.license.localeCompare(b.license));
+  const psgAssignments = rows(await run('psg', () => soql('SELECT PermissionSetGroup.DeveloperName g, COUNT(Id) c FROM PermissionSetAssignment WHERE PermissionSetGroupId != null AND Assignee.IsActive = true GROUP BY PermissionSetGroup.DeveloperName', alias)))
+    .map((r) => ({ group: r.g || r.DeveloperName, users: r.c ?? r.expr0 })).sort((a, b) => String(a.group).localeCompare(String(b.group)));
+
+  onProgress('records');
+  const objects = facts.data.objects.filter((o) => ['custom', 'standard'].includes(o.kind) && !o.namespace && (o.kind === 'custom' || o.customFields > 0));
+  const volumes = (await pool(objects, 4, async (o) => {
+    const count = await run(`count ${o.name}`, async () => (await soql(`SELECT COUNT() FROM ${o.name}`, alias)).totalSize);
+    if (count == null) return null;
+    let last = null;
+    if (count > 0) {
+      const r = rows(await run(`last ${o.name}`, () => soql(`SELECT MAX(CreatedDate) d FROM ${o.name}`, alias)))[0];
+      last = r ? (r.d || r.expr0 || null) : null;
+    }
+    return { object: o.name, records: count, lastCreated: last ? String(last).slice(0, 10) : null };
+  })).filter(Boolean);
+
+  onProgress('jobs');
+  const scheduledJobs = rows(await run('cron', () => soql("SELECT CronJobDetail.Name, CronJobDetail.JobType, State, CronExpression, NextFireTime FROM CronTrigger WHERE State NOT IN ('DELETED','COMPLETE')", alias)))
+    .map((r) => ({ name: r.CronJobDetail?.Name, type: r.CronJobDetail?.JobType, state: r.State, cron: r.CronExpression, next: r.NextFireTime ? String(r.NextFireTime).slice(0, 16) : null }))
+    .sort((a, b) => String(a.name).localeCompare(String(b.name)));
+  const activeFlows = rows(await run('flows', () => soql('SELECT ApiName, IsActive, ProcessType FROM FlowDefinitionView WHERE IsActive = true', alias))).map((r) => r.ApiName).sort();
+
+  onProgress('coverage');
+  const cov = rows(await run('coverage', () => soql('SELECT PercentCovered FROM ApexOrgWideCoverage', alias, { tooling: true })))[0];
+  const coverage = cov ? cov.PercentCovered : null;
+
+  onProgress('packages');
+  const packages = (await run('packages', () => sfJson(['package', 'installed', 'list', '--target-org', alias]), []) || [])
+    .map((p) => ({ name: p.SubscriberPackageName, namespace: p.SubscriberPackageNamespace || null, version: p.SubscriberPackageVersionNumber || p.SubscriberPackageVersionName || null }))
+    .sort((a, b) => String(a.name).localeCompare(String(b.name)));
+
+  onProgress('limits');
+  const limits = (await run('limits', () => sfJson(['org', 'list', 'limits', '--target-org', alias]), []) || [])
+    .filter((l) => ['DataStorageMB', 'FileStorageMB', 'DailyApiRequests', 'DailyAsyncApexExecutions', 'DailyBulkV2QueryJobs'].includes(l.name))
+    .map((l) => ({ name: l.name, max: l.max, remaining: l.remaining })).sort((a, b) => a.name.localeCompare(b.name));
+
+  return {
+    collectedAt: new Date().toISOString().slice(0, 19) + 'Z',
+    alias,
+    organization,
+    usersByProfile,
+    usersByLicense,
+    psgAssignments,
+    volumes,
+    scheduledJobs,
+    activeFlows,
+    coverage,
+    packages,
+    limits,
+    errors,
+  };
+}

package/src/facts/xml.js

@@ -0,0 +1,85 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { XMLParser } from 'fast-xml-parser';
+import { readText, walk } from '../util/fsx.js';
+
+const parser = new XMLParser({ ignoreAttributes: true, removeNSPrefix: true, parseTagValue: false, trimValues: true });
+
+/** Parse a metadata XML file and return its root element (attributes ignored, values as strings). */
+export function readXml(file) {
+  try {
+    const obj = parser.parse(safeRead(file));
+    const root = Object.keys(obj).find((k) => k !== '?xml');
+    return (root && obj[root]) || {};
+  } catch {
+    return {};
+  }
+}
+
+export const arr = (x) => (x == null ? [] : Array.isArray(x) ? x : [x]);
+export const bool = (v) => v === true || v === 'true';
+export const str = (v) => (v == null ? null : typeof v === 'object' ? null : String(v));
+export const byName = (a, b) => String(a.name).localeCompare(String(b.name));
+export const sortNames = (list) => [...new Set(list)].sort((a, b) => a.localeCompare(b));
+
+export function host(url) {
+  if (!url || typeof url !== 'string') return null;
+  const m = /^[a-z][a-z0-9+.-]*:\/\/([^/:?#]+)/i.exec(url.trim());
+  return m ? m[1].toLowerCase() : null;
+}
+
+/** Folders that identify a Salesforce source-format metadata root (e.g. force-app/main/default). */
+const MARKERS = new Set(['classes', 'objects', 'lwc', 'aura', 'flows', 'triggers', 'permissionsets', 'layouts', 'flexipages', 'applications', 'customMetadata', 'profiles', 'tabs', 'labels']);
+
+export function findMetadataRoots(dirs) {
+  const roots = new Set();
+  const scan = (d, depth) => {
+    let entries;
+    try { entries = fs.readdirSync(d, { withFileTypes: true }); } catch { return; }
+    const sub = entries.filter((e) => e.isDirectory());
+    if (sub.some((e) => MARKERS.has(e.name))) { roots.add(path.resolve(d)); return; }
+    if (depth <= 0) return;
+    for (const e of sub) if (!e.name.startsWith('.') && e.name !== 'node_modules') scan(path.join(d, e.name), depth - 1);
+  };
+  for (const d of dirs) scan(d, 5);
+  return [...roots].sort();
+}
+
+/** Files of a metadata folder across roots. `suffix` filters by file ending. */
+export function files(roots, folder, suffix, { recursive = false } = {}) {
+  const out = [];
+  for (const r of roots) {
+    const dir = path.join(r, folder);
+    if (!fs.existsSync(dir)) continue;
+    const list = recursive ? walk(dir) : fs.readdirSync(dir).sort().map((f) => path.join(dir, f)).filter((f) => fs.statSync(f).isFile());
+    out.push(...list.filter((f) => !suffix || f.endsWith(suffix)));
+  }
+  return out;
+}
+
+/** Sub-directories of a metadata folder across roots (LWC, Aura, objects…). */
+export function bundles(roots, folder) {
+  const out = [];
+  for (const r of roots) {
+    const dir = path.join(r, folder);
+    if (!fs.existsSync(dir)) continue;
+    for (const e of fs.readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+      if (e.isDirectory()) out.push({ name: e.name, dir: path.join(dir, e.name) });
+    }
+  }
+  return out;
+}
+
+export const baseName = (file, suffix) => path.basename(file).slice(0, suffix ? -suffix.length : undefined);
+// Files are read several times (parsing, references, namespaces): keep their text for one extraction run.
+const cache = new Map();
+export const safeRead = (f) => {
+  if (cache.has(f)) return cache.get(f);
+  let s = '';
+  try { s = readText(f); } catch { /* unreadable file: treated as empty */ }
+  cache.set(f, s);
+  return s;
+};
+export const clearReadCache = () => cache.clear();
+export const hasFolder = (roots, folder) => roots.some((r) => fs.existsSync(path.join(r, folder)));
+export const countFiles = (roots, folder, suffix) => files(roots, folder, suffix, { recursive: true }).length;

package/src/sf/sf.js

@@ -0,0 +1,120 @@
+// 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 { spawn, spawnSync } from 'node:child_process';
+
+const ALLOWED = [
+  ['--version'],
+  ['org', 'list'],
+  ['org', 'display'],
+  ['org', 'login', 'web'],
+  ['org', 'list', 'metadata-types'],
+  ['org', 'list', 'metadata'],
+  ['org', 'list', 'limits'],
+  ['project', 'generate', 'manifest'],
+  ['project', 'retrieve', 'start'],
+  ['data', 'query'],
+  ['package', 'installed', 'list'],
+  ['config', 'get'],
+];
+
+// sObjects whose rows describe the org itself (configuration, not business data).
+const METADATA_SOBJECTS = new Set([
+  'organization', 'crontrigger', 'flowdefinitionview', 'apexorgwidecoverage', 'apexcodecoverageaggregate',
+  'asyncapexjob', 'userlicense', 'permissionsetlicense', 'entitydefinition',
+]);
+// sObjects allowed only through aggregated queries (GROUP BY + COUNT).
+const AGGREGATE_ONLY = new Set(['user', 'permissionsetassignment']);
+
+/** The subcommand path (leading words before the first flag) must match an allowed path exactly. */
+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]));
+}
+
+const AGG = /^(count\(\s*(id)?\s*\)|max\(\s*(createddate|lastmodifieddate)\s*\)|min\(\s*createddate\s*\))(\s+\w+)?$/i;
+
+/** Throws unless the SOQL only reads org configuration or aggregates — never business records. */
+export function assertSafeQuery(q) {
+  const s = q.replace(/\s+/g, ' ').trim();
+  const refuse = (why) => { throw new Error(`Refused query (${why}): ${s}`); };
+  if (!/^select\s/i.test(s)) refuse('not a SELECT');
+  const from = /\sfrom\s+([A-Za-z0-9_]+)/i.exec(s);
+  if (!from) refuse('no FROM');
+  const obj = from[1].toLowerCase();
+  if (METADATA_SOBJECTS.has(obj)) return true;
+  const fields = s.slice(6, from.index).split(',').map((f) => f.trim());
+  const grouped = /\bgroup by\b/i.test(s);
+  if (AGGREGATE_ONLY.has(obj)) {
+    const ok = grouped && fields.some((f) => AGG.test(f)) && fields.every((f) => AGG.test(f) || /^[A-Za-z0-9_.]+(\s+\w+)?$/.test(f));
+    if (!ok) refuse(`aggregates only on ${from[1]}`);
+    return true;
+  }
+  if (grouped || !fields.every((f) => AGG.test(f))) refuse('record data is never read');
+  return true;
+}
+
+function resolveSf() {
+  return process.env.TADFORCE_SF_BIN || 'sf';
+}
+
+// On Windows `sf` is a .cmd shim and needs a shell: build one command line with quoted arguments.
+const quote = (a) => (/^[\w@+=:,./\\-]+$/.test(a) ? a : '"' + String(a).replace(/"/g, '""') + '"');
+function launch(args, opts) {
+  if (process.platform !== 'win32') return [resolveSf(), args, { ...opts, shell: false }];
+  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 } = {}) {
+  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');
+    assertSafeQuery(args[qi + 1] || '');
+  }
+  return new Promise((resolve, reject) => {
+    const [cmd, argv, opts] = launch([...args, '--json'], { cwd, env: { ...process.env, SF_DISABLE_TELEMETRY: 'true', SF_AUTOUPDATE_DISABLE: 'true' } });
+    const child = spawn(cmd, argv, opts);
+    let out = '', err = '';
+    const timer = setTimeout(() => { child.kill(); reject(new Error(`sf ${args.slice(0, 3).join(' ')} timed out`)); }, timeoutMs);
+    child.stdout.on('data', (d) => (out += d));
+    child.stderr.on('data', (d) => (err += d));
+    child.on('error', (e) => { clearTimeout(timer); reject(e); });
+    child.on('close', () => {
+      clearTimeout(timer);
+      const start = out.indexOf('{');
+      let parsed = null;
+      try { parsed = JSON.parse(out.slice(start)); } catch { /* not JSON */ }
+      if (!parsed) return reject(new Error((err || out || 'sf returned no JSON').trim().slice(0, 800)));
+      if (parsed.status !== 0 && parsed.status !== undefined) {
+        const e = new Error(parsed.message || parsed.name || 'sf command failed');
+        e.sf = parsed;
+        return reject(e);
+      }
+      resolve(parsed.result);
+    });
+  });
+}
+
+/** Interactive `sf` call (inherits the terminal) — used for the browser login only. */
+export function sfInteractive(args) {
+  if (!isAllowed(args)) throw new Error(`TADForce refuses to run: sf ${args.join(' ')}`);
+  const [cmd, argv, opts] = launch(args, { stdio: 'inherit' });
+  const r = spawnSync(cmd, argv, opts);
+  return r.status === 0;
+}
+
+export function sfVersion() {
+  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;
+}
+
+export function soql(query, alias, { tooling = false } = {}) {
+  const args = ['data', 'query', '--query', query, '--target-org', alias];
+  if (tooling) args.push('--use-tooling-api');
+  return sfJson(args, { timeoutMs: 180000 });
+}

package/src/util/args.js

@@ -0,0 +1,21 @@
+/** Minimal argv parser: `cmd pos --flag value --bool --no-x -k v`. */
+export function parseArgs(argv) {
+  const args = { _: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--') { args._.push(...argv.slice(i + 1)); break; }
+    if (a.startsWith('--')) {
+      const [k, inline] = a.slice(2).split(/=(.*)/s);
+      const key = k.replace(/-([a-z])/g, (_, ch) => ch.toUpperCase());
+      if (inline !== undefined) args[key] = inline;
+      else if (key.startsWith('no') && key.length > 2 && /[A-Z]/.test(key[2])) args[key[2].toLowerCase() + key.slice(3)] = false;
+      else if (argv[i + 1] !== undefined && !argv[i + 1].startsWith('-')) args[key] = argv[++i];
+      else args[key] = true;
+    } else if (a.startsWith('-') && a.length === 2) {
+      const key = a.slice(1);
+      if (argv[i + 1] !== undefined && !argv[i + 1].startsWith('-')) args[key] = argv[++i];
+      else args[key] = true;
+    } else args._.push(a);
+  }
+  return args;
+}

package/src/util/config.js

@@ -0,0 +1,104 @@
+import path from 'node:path';
+import { exists, readJson, readYaml, writeJson } from './fsx.js';
+import { CONFIG_FILE, WORKSPACE_DIR } from './paths.js';
+
+export const DEFAULT_BRAND = {
+  primary: '#0B2545',
+  accent: '#3D5AFE',
+  accent2: '#9B1FE8',
+  gradient: ['#1E88FF', '#9B1FE8'],
+  tableHeader: '#0f2a4d',
+};
+
+export function defaultConfig(overrides = {}) {
+  const today = new Date().toISOString().slice(0, 10);
+  const cfg = {
+    language: 'en',
+    client: { name: 'Client', short: 'CLIENT', logo: null },
+    // integrator and author are optional: when empty they are left out of the document.
+    integrator: { name: null, logo: null },
+    document: {
+      author: null,
+      title: 'Salesforce CRM Platform',
+      subtitle: '',
+      reference: 'TAD-CLIENT-CRM',
+      version: '1.0',
+      status: 'For review',
+      date: today,
+      classification: 'Confidential',
+      environment: 'Production',
+      history: [],
+    },
+    org: { alias: null },
+    // Functional specifications and other documents provided by the project (evidence level P2), relative to tadforce/.
+    inputs: { specs: [] },
+    // Part of the org to document: name patterns ("NWB_*") and package directories. Empty: the whole org.
+    scope: { include: [], packageDirectories: [] },
+    brand: { ...DEFAULT_BRAND },
+    // mode: org (retrieved snapshot), local (the project's package directories) or both. null: not chosen yet.
+    source: { dir: '.snapshot/source', mode: null },
+    // What tadforce doctor already asked or searched, so that it never asks twice.
+    setup: {},
+    manifest: { mode: 'curated', includePackages: false },
+    outputs: { dir: 'out', pdf: true, docx: true },
+    review: { tad: { commentsFrom: [], resolutions: {}, dropImages: [] }, axes: { commentsFrom: [], resolutions: {}, dropImages: [] } },
+  };
+  return deepMerge(cfg, overrides);
+}
+
+export function deepMerge(a, b) {
+  if (!b || typeof b !== 'object' || Array.isArray(b)) return b === undefined ? a : b;
+  const out = { ...(a || {}) };
+  for (const [k, v] of Object.entries(b)) {
+    out[k] = v && typeof v === 'object' && !Array.isArray(v) && a && typeof a[k] === 'object' && !Array.isArray(a[k]) ? deepMerge(a[k], v) : v;
+  }
+  return out;
+}
+
+/** Locate the workspace: --cwd/<tadforce>, or ./tadforce, or the current dir if it holds the config. */
+export function findWorkspace(cwd = process.cwd()) {
+  const candidates = [path.join(cwd, WORKSPACE_DIR), cwd];
+  for (const dir of candidates) if (exists(path.join(dir, CONFIG_FILE))) return dir;
+  return null;
+}
+
+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.`);
+    err.code = 'NO_WORKSPACE';
+    throw err;
+  }
+  const cfg = defaultConfig(readJson(path.join(ws, CONFIG_FILE)));
+  const project = path.dirname(ws);
+  return {
+    ws,
+    project,
+    cfg,
+    p: (...parts) => path.resolve(ws, ...parts),
+    glossary: () => readYaml(path.join(ws, 'knowledge', 'glossary.yml'), {}),
+    exclusions: () => readYaml(path.join(ws, 'knowledge', 'exclusions.yml'), {}),
+    save: (next) => writeJson(path.join(ws, CONFIG_FILE), next),
+  };
+}
+
+/** 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;
+  const snap = wsCtx.p(wsCtx.cfg.source.dir);
+  const local = localDirs(wsCtx);
+  if (mode === 'local') return local;
+  if (mode === 'both') return [...(exists(snap) ? [snap] : []), ...local];
+  if (exists(snap)) return [snap];
+  return local;
+}
+
+function localDirs(wsCtx) {
+  const sfdx = path.join(wsCtx.project, 'sfdx-project.json');
+  if (exists(sfdx)) {
+    const only = (wsCtx.cfg.scope && wsCtx.cfg.scope.packageDirectories) || [];
+    const dirs = (readJson(sfdx).packageDirectories || []).filter((d) => !only.length || only.includes(d.path)).map((d) => path.join(wsCtx.project, d.path)).filter(exists);
+    if (dirs.length) return dirs;
+  }
+  return [];
+}