@cspeach/cli 1.1.29 → 1.1.31

package/dist/register/discover.js

@@ -0,0 +1,901 @@
+/**
+ * Discovery: the estate inventory, from fixed read-only SQL (spec §5.1–§5.3).
+ *
+ * Every statement is a fixed shape built here (DISCOVER_STATEMENTS lists them
+ * for the static rules test) and goes through the one `SqlQuery` capability —
+ * `AdtClient.sqlQuery`, which runs sap-client's read-only gate. The ADT
+ * data-preview dialect rules hold for every statement: no IN-lists, at most one
+ * LIKE per WHERE, an alias on every aggregate, never `UP TO n ROWS` (the row
+ * cap is the maxRows argument), one query per prefix and per namespace.
+ *
+ * Honesty rules:
+ *   - a failed statement is recorded (`queries[]`, `ok:false`) and named under
+ *     `unknowns`; discovery never throws for a SQL failure and the files are
+ *     still produced;
+ *   - usage has four states and "unused" only ever rests on an ACTIVE runtime
+ *     source over a stated period; "last changed" is never called use;
+ *   - callers are "read" only for objects the where-used pull really covered.
+ */
+import { CODE_OBJECT_TYPES, LOCAL_PACKAGE } from './baseline.js';
+import { callersFromIndex, reposrcNameFor } from './xref.js';
+import { outsideUsageWindowLine, shortUsageWindow, usageUnknownLineOf } from '@cspeach/register-core';
+// ── Fixed values ──
+/** Rows per keyset page (steps 5, 6, 8, 9, 10). */
+const PAGE = 5000;
+/** Namespaces that are SAP's or a product's, never treated as customer even with role P. */
+const NOT_CUSTOMER_NAMESPACES = [
+    '/BI0/', '/BIC/', '/IWBEP/', '/IWFND/', '/UI2/', '/UI5/', '/SDF/', '/BOBF/', '/OSP/', '/SCWM/', '/SCMB/', '/S4PPM/',
+    '/ARBA/', '/AIF/', '/BA1/', '/CFG/', '/DMF/', '/GBT/', '/LIME/', '/MRSS/', '/NXL/', '/PLMB/', '/PLMI/', '/POSDW/',
+    '/SAPAPO/', '/SAPPO/', '/SAPSLL/', '/SAPTRX/', '/SCDL/', '/SCMTMS/', '/SPE/', '/STTP/', '/TDF/', '/CPD/', '/OPT/', '/XLSO/',
+];
+/**
+ * Types the where-used index records callers for. Others (a function group's
+ * callers sit under its function modules' names; domains, access controls,
+ * services, behaviour definitions, messages, transactions, forms, …) are
+ * "not read", never "no callers".
+ */
+const INDEXED_TYPES = new Set(['PROG', 'CLAS', 'INTF', 'TABL', 'VIEW', 'DTEL', 'TTYP', 'DDLS', 'SHLP']);
+const NOT_INDEXED = 'The where-used index does not record callers for this type.';
+/** Types runtime usage sources (SUSG, SCMON) can see: executed main programs. */
+const RUNTIME_TYPES = new Set(['PROG', 'CLAS', 'FUGR']);
+const STEP_LABELS = {
+    1: 'namespaces', 2: 'packages', 3: 'object counts', 4: 'objects per package', 5: 'local objects',
+    6: 'change dates', 7: 'batch jobs', 8: 'usage sources', 9: 'where-used', 10: 'include to program',
+    11: 'modifications', 12: 'successor data',
+};
+const NO_USAGE = 'No program usage is recorded on this system.';
+const BATCH_NOTE = 'A batch run proves use. Finding no batch run proves nothing.';
+const STOPPED = 'stopped before it finished';
+const notPerObject = (source, period) => `Usage data exists on this system (${source}${period ? ` from ${period.from} to ${period.to}` : ''}), but CSPeach does not read it per object yet.`;
+const PREFIX_RE = /^[A-Z/][A-Z0-9_/]{0,29}$/;
+const NAMESPACE_RE = /^\/[A-Z0-9_]{1,10}\/$/;
+const PACKAGE_RE = /^[A-Z0-9_/$]{1,30}$/;
+const clean = (v) => (v ?? '').trim();
+const num = (v) => { const n = Number(clean(v)); return Number.isFinite(n) ? n : 0; };
+const lit = (v) => v.replace(/'/g, "''");
+const iso = (v) => {
+    const s = clean(v);
+    if (/^\d{8}$/.test(s))
+        return s === '00000000' ? null : `${s.slice(0, 4)}-${s.slice(4, 6)}-${s.slice(6, 8)}`;
+    if (/^\d{4}-\d{2}-\d{2}/.test(s))
+        return s.slice(0, 10);
+    return null;
+};
+const isNamespace = (p) => p.startsWith('/');
+const capped = (s) => (s.length > 300 ? `${s.slice(0, 297)}...` : s);
+// ── Statement builders: the only SQL discovery sends ──
+const after = (col, a, strict = false) => (a === undefined ? '' : ` AND ${col} ${strict ? '>' : '>='} '${lit(a)}'`);
+export const SQL = {
+    namespaces: () => 'SELECT NAMESPACE, ROLE FROM TRNSPACE',
+    packages: (p) => `SELECT DEVCLASS, PARENTCL, COMPONENT, APPLICAT, DLVUNIT, CREATED_BY, CREATED_ON FROM TDEVC WHERE DEVCLASS LIKE '${p}%'`,
+    packageTexts: (p) => `SELECT DEVCLASS, SPRAS, CTEXT FROM TDEVCT WHERE SPRAS = 'E' AND DEVCLASS LIKE '${p}%'`,
+    counts: (p) => `SELECT DEVCLASS, OBJECT, COUNT(*) AS CNT FROM TADIR WHERE PGMID = 'R3TR' AND DELFLAG = ' ' AND DEVCLASS LIKE '${p}%' GROUP BY DEVCLASS, OBJECT`,
+    packageObjects: (pkg) => `SELECT OBJECT, OBJ_NAME, DEVCLASS, AUTHOR, GENFLAG, CREATED_ON FROM TADIR WHERE PGMID = 'R3TR' AND DELFLAG = ' ' AND DEVCLASS = '${pkg}'`,
+    localCount: (p) => `SELECT COUNT(*) AS CNT FROM TADIR WHERE PGMID = 'R3TR' AND DELFLAG = ' ' AND DEVCLASS = '${LOCAL_PACKAGE}' AND OBJ_NAME LIKE '${p}%'`,
+    localObjects: (p, a) => `SELECT OBJECT, OBJ_NAME, DEVCLASS, AUTHOR, GENFLAG, CREATED_ON FROM TADIR WHERE PGMID = 'R3TR' AND DELFLAG = ' ' AND DEVCLASS = '${LOCAL_PACKAGE}' AND OBJ_NAME LIKE '${p}%'${after('OBJ_NAME', a)} ORDER BY OBJ_NAME, OBJECT`,
+    changes: (p, a) => `SELECT PROGNAME, R3STATE, UNAM, UDAT, CNAM, CDAT FROM REPOSRC WHERE R3STATE = 'A' AND PROGNAME LIKE '${p}%'${after('PROGNAME', a)} ORDER BY PROGNAME`,
+    batch: (p) => `SELECT p~PROGNAME, COUNT(*) AS RUNS, MAX( o~STRTDATE ) AS LAST_RUN FROM TBTCP AS p INNER JOIN TBTCO AS o ON p~JOBNAME = o~JOBNAME AND p~JOBCOUNT = o~JOBCOUNT WHERE o~STATUS = 'F' AND p~PROGNAME LIKE '${p}%' GROUP BY p~PROGNAME`,
+    batchWindow: () => `SELECT MIN( STRTDATE ) AS FIRST_RUN, MAX( STRTDATE ) AS LAST_RUN, COUNT(*) AS CNT FROM TBTCO WHERE STATUS = 'F'`,
+    scmonConfig: () => 'SELECT CONFIG_KEY, CONFIG_VALUE FROM SCMON_CONFIG',
+    scmonData: () => 'SELECT COUNT(*) AS CNT FROM SCMON_DATA',
+    scmonSlice: () => 'SELECT MIN( STARTDATE ) AS FROM_DATE, MAX( ENDDATE ) AS TO_DATE FROM SCMON_SLICE',
+    sdfScmonConfig: () => 'SELECT COUNT(*) AS CNT FROM /SDF/SCMON_CFG',
+    sdfScmonData: () => 'SELECT COUNT(*) AS CNT FROM /SDF/SCMON_DATA',
+    susgAdmin: () => 'SELECT USGID, KIND, DATE_FROM, DATE_TO, DAYS_AVAILABLE FROM SUSG_ADMIN',
+    susgData: () => 'SELECT COUNT(*) AS CNT, MIN( LAST_USED ) AS MIN_LU, MAX( LAST_USED ) AS MAX_LU FROM SUSG_DATA',
+    susgObjects: (p, a) => `SELECT g~OBJ_TYPE, g~OBJ_NAME, g~PROGNAME, MAX( d~LAST_USED ) AS LAST_USED FROM SUSG_DATA AS d INNER JOIN SUSG_PROG AS g ON d~USGID = g~USGID AND d~TRIGID = g~PROGID WHERE g~PROGNAME LIKE '${p}%'${after('g~PROGNAME', a)} GROUP BY g~OBJ_TYPE, g~OBJ_NAME, g~PROGNAME ORDER BY g~PROGNAME, g~OBJ_TYPE, g~OBJ_NAME`,
+    scmonProg: (p, a) => `SELECT PROGID, PROGNAME, OBJECT, OBJ_NAME FROM SCMON_PROG WHERE PROGNAME LIKE '${p}%'${after('PROGNAME', a)} ORDER BY PROGNAME, PROGID`,
+    monHeader: () => 'SELECT COUNT(*) AS CNT FROM /SDF/MON_HEADER',
+    monCall: () => 'SELECT COUNT(*) AS CNT FROM /SDF/MON_CALL',
+    workload: () => 'SELECT MIN( FIRSTRECDY ) AS FROM_DATE, MAX( LASTRECDY ) AS TO_DATE, COUNT(*) AS CNT FROM SWNCMONIINDEX',
+    wbcrossgt: (p, a, strict) => `SELECT OTYPE, NAME, INCLUDE FROM WBCROSSGT WHERE NAME LIKE '${p}%'${after('NAME', a, strict)} ORDER BY NAME, INCLUDE`,
+    cross: (p, a, strict) => `SELECT TYPE, NAME, INCLUDE FROM CROSS WHERE NAME LIKE '${p}%'${after('NAME', a, strict)} ORDER BY NAME, INCLUDE`,
+    masters: (p, a) => `SELECT MASTER, INCLUDE FROM D010INC WHERE INCLUDE LIKE '${p}%'${after('INCLUDE', a)} ORDER BY INCLUDE, MASTER`,
+    modifications: (op) => `SELECT OBJ_TYPE, OBJ_NAME, SUB_TYPE, SUB_NAME, OPERATION, MOD_USER, MOD_DATE FROM SMODILOG WHERE OPERATION = '${op}'`,
+    modificationCount: (op) => `SELECT COUNT(*) AS CNT FROM SMODILOG WHERE OPERATION = '${op}'`,
+    successors: () => 'SELECT COUNT(*) AS CNT FROM ARS_W_API_STATE',
+};
+/** Function groups' main programs and includes do not start with the prefix (SAPLZ…, LZ…). */
+const fugrPrefixes = (p, lead) => (isNamespace(p) ? [] : [`${lead}${p}`]);
+/** Every statement shape for one prefix (and package / paging key), for the static rules test. */
+export const DISCOVER_STATEMENTS = (o) => {
+    const p = o.prefix;
+    const a = o.after;
+    const out = [
+        { step: 1, sql: SQL.namespaces() },
+        { step: 2, sql: SQL.packages(p) },
+        { step: 2, sql: SQL.packageTexts(p) },
+        { step: 3, sql: SQL.counts(p) },
+        { step: 4, sql: SQL.packageObjects(o.pkg ?? `${p}PKG`) },
+        { step: 5, sql: SQL.localCount(p) },
+        { step: 5, sql: SQL.localObjects(p, a) },
+        { step: 6, sql: SQL.changes(p, a) },
+        ...fugrPrefixes(p, 'SAPL').map((fp) => ({ step: 6, sql: SQL.changes(fp, a) })),
+        { step: 7, sql: SQL.batch(p) },
+        { step: 7, sql: SQL.batchWindow() },
+        { step: 8, sql: SQL.scmonConfig() },
+        { step: 8, sql: SQL.scmonData() },
+        { step: 8, sql: SQL.scmonSlice() },
+        { step: 8, sql: SQL.sdfScmonConfig() },
+        { step: 8, sql: SQL.sdfScmonData() },
+        { step: 8, sql: SQL.susgAdmin() },
+        { step: 8, sql: SQL.susgData() },
+        { step: 8, sql: SQL.susgObjects(p, a) },
+        { step: 8, sql: SQL.scmonProg(p, a) },
+        ...fugrPrefixes(p, 'SAPL').flatMap((fp) => [{ step: 8, sql: SQL.susgObjects(fp, a) }, { step: 8, sql: SQL.scmonProg(fp, a) }]),
+        { step: 8, sql: SQL.monHeader() },
+        { step: 8, sql: SQL.monCall() },
+        { step: 8, sql: SQL.workload() },
+        { step: 9, sql: SQL.cross(p, a) },
+        { step: 9, sql: SQL.wbcrossgt(p, a) },
+        ...(a === undefined ? [] : [{ step: 9, sql: SQL.cross(p, a, true) }, { step: 9, sql: SQL.wbcrossgt(p, a, true) }]),
+        { step: 10, sql: SQL.masters(p, a) },
+        ...fugrPrefixes(p, 'L').map((fp) => ({ step: 10, sql: SQL.masters(fp, a) })),
+        { step: 11, sql: SQL.modifications('MOD') },
+        { step: 11, sql: SQL.modifications('NEW') },
+        { step: 11, sql: SQL.modifications('IMP') },
+        { step: 11, sql: SQL.modificationCount('NOTE') },
+        { step: 11, sql: SQL.modificationCount('ALL') },
+        { step: 12, sql: SQL.successors() },
+    ];
+    return out;
+};
+export async function discover(sql, opts) {
+    const now = opts.now ?? (() => new Date());
+    const takenAt = now().toISOString();
+    const queries = [];
+    const unknowns = [];
+    const aborted = () => opts.signal?.aborted === true;
+    const codeTypes = new Set(CODE_OBJECT_TYPES);
+    /** The one wrapper every statement runs through. Never throws. */
+    const run = async (step, statement, maxRows, what) => {
+        const t0 = Date.now();
+        try {
+            const res = await sql(statement, maxRows);
+            const rows = res.rows ?? [];
+            queries.push({ step, statement, rows: rows.length, ms: Date.now() - t0, ok: true });
+            return { rows };
+        }
+        catch (err) {
+            const error = capped(clean(err instanceof Error ? err.message : String(err)) || 'The query failed without a message.');
+            queries.push({ step, statement, rows: 0, ms: Date.now() - t0, ok: false, error });
+            unknowns.push({ what: what ?? `step ${step}: ${STEP_LABELS[step]}`, why: error });
+            return { error };
+        }
+    };
+    /** Keyset paging with `>=` on the key column; rows already seen (by `uniq`) are dropped. */
+    const paged = async (step, build, keyCol, uniq, stop, what, 
+    /** One key fills a whole page: hand it over and read on past it, instead of stopping. */
+    skip) => {
+        const rows = [];
+        const seen = new Set();
+        let a;
+        let strict = false;
+        for (;;) {
+            const why = stop();
+            if (why)
+                return { rows, complete: false, boundary: a, stop: why };
+            const res = await run(step, build(a, strict), PAGE, what);
+            if ('error' in res)
+                return { rows, complete: false, boundary: a, stop: 'error', error: res.error };
+            let fresh = 0;
+            for (const r of res.rows) {
+                const k = uniq(r);
+                if (seen.has(k))
+                    continue;
+                seen.add(k);
+                rows.push(r);
+                fresh += 1;
+            }
+            if (res.rows.length < PAGE)
+                return { rows, complete: true };
+            const last = clean(res.rows[res.rows.length - 1][keyCol]);
+            if (fresh === 0 || last === a) {
+                if (!skip || !last)
+                    return { rows, complete: false, boundary: last, stop: 'stuck' };
+                skip(last);
+                a = last;
+                strict = true;
+                continue;
+            }
+            a = last;
+            strict = false;
+        }
+    };
+    const abortOnly = () => (aborted() ? 'abort' : null);
+    const started = new Set();
+    /** Steps Ctrl-C stopped part way through: listed under unknowns like the ones never started. */
+    const cut = new Set();
+    const step = (n) => {
+        if (aborted())
+            return false;
+        started.add(n);
+        opts.onStep?.(n, STEP_LABELS[n]);
+        return true;
+    };
+    // Prefixes from options (checked, never escaped — they go into LIKE literals).
+    const prefixes = [];
+    for (const raw of opts.prefixes.length ? opts.prefixes : ['Z', 'Y']) {
+        const p = clean(raw).toUpperCase();
+        if (!PREFIX_RE.test(p)) {
+            unknowns.push({ what: `prefix ${raw}`, why: 'Not a valid name prefix; it was not read.' });
+            continue;
+        }
+        if (!prefixes.includes(p))
+            prefixes.push(p);
+    }
+    // ── Step 1: namespaces ──
+    let namespaces = [];
+    if (step(1)) {
+        const res = await run(1, SQL.namespaces(), 500);
+        let customer = [];
+        if ('rows' in res) {
+            let notCustomer = 0;
+            for (const r of res.rows) {
+                const ns = clean(r.NAMESPACE).toUpperCase();
+                if (!ns)
+                    continue;
+                const sap = ns.startsWith('/SAP') || ns.startsWith('/1') || NOT_CUSTOMER_NAMESPACES.includes(ns);
+                // ROLE P (producer): this system develops in the namespace. C (recipient) only receives its objects.
+                if (!sap && clean(r.ROLE).toUpperCase() === 'P' && NAMESPACE_RE.test(ns))
+                    customer.push(ns);
+                else
+                    notCustomer += 1;
+            }
+            customer = [...new Set(customer)].sort();
+            unknowns.push({
+                what: `namespaces not treated as customer: ${notCustomer}`,
+                why: 'SAP, partner or product namespaces. Their objects are not in this inventory.',
+            });
+        }
+        if (opts.namespaces === 'auto')
+            namespaces = customer;
+    }
+    if (opts.namespaces !== 'auto') {
+        for (const raw of opts.namespaces) {
+            const ns = clean(raw).toUpperCase();
+            if (!NAMESPACE_RE.test(ns)) {
+                unknowns.push({ what: `namespace ${raw}`, why: 'Not a valid namespace; it was not read.' });
+                continue;
+            }
+            if (!namespaces.includes(ns))
+                namespaces.push(ns);
+        }
+    }
+    // A prefix a shorter one already covers (Z and ZFI) would count its objects twice: dropped.
+    const covered = (p, all) => all.some((q) => q !== p && p.startsWith(q));
+    const both = [...prefixes, ...namespaces];
+    for (const list of [prefixes, namespaces]) {
+        for (let i = list.length - 1; i >= 0; i--)
+            if (covered(list[i], both))
+                list.splice(i, 1);
+    }
+    const allPrefixes = [...prefixes, ...namespaces];
+    const customerNamed = (name) => allPrefixes.some((p) => name.startsWith(p) || (!isNamespace(p) && name.startsWith(`SAPL${p}`)));
+    // ── Step 2: packages + texts ──
+    const pkgInfo = new Map();
+    const pkgText = new Map();
+    if (step(2)) {
+        for (const p of allPrefixes) {
+            const res = await run(2, SQL.packages(p), 10000);
+            if ('rows' in res)
+                for (const r of res.rows)
+                    pkgInfo.set(clean(r.DEVCLASS).toUpperCase(), r);
+            const tx = await run(2, SQL.packageTexts(p), 10000);
+            if ('rows' in tx)
+                for (const r of tx.rows)
+                    pkgText.set(clean(r.DEVCLASS).toUpperCase(), clean(r.CTEXT));
+        }
+    }
+    // ── Step 3: counts by package and type ──
+    const byPkg = new Map();
+    const countedPrefixes = new Set();
+    if (step(3)) {
+        for (const p of allPrefixes) {
+            const res = await run(3, SQL.counts(p), 50000);
+            if (!('rows' in res))
+                continue;
+            countedPrefixes.add(p);
+            for (const r of res.rows) {
+                const pkg = clean(r.DEVCLASS).toUpperCase();
+                const t = clean(r.OBJECT).toUpperCase();
+                const m = byPkg.get(pkg) ?? {};
+                m[t] = (m[t] ?? 0) + num(r.CNT);
+                byPkg.set(pkg, m);
+            }
+        }
+    }
+    const packageNames = [...new Set([...pkgInfo.keys(), ...byPkg.keys()])]
+        .filter((p) => p !== LOCAL_PACKAGE).sort((a, b) => a.localeCompare(b));
+    // ── Step 4: every object, per package, with the control total ──
+    const objects = [];
+    const seenObj = new Set();
+    const genPerPkg = new Map();
+    const addObject = (r, pkg) => {
+        const type = clean(r.OBJECT).toUpperCase();
+        const name = clean(r.OBJ_NAME).toUpperCase();
+        if (!codeTypes.has(type))
+            return;
+        const key = `${type}|${name}`;
+        if (seenObj.has(key))
+            return;
+        seenObj.add(key);
+        objects.push({
+            type, name, package: pkg, author: clean(r.AUTHOR), createdOn: iso(r.CREATED_ON) ?? clean(r.CREATED_ON),
+            generated: clean(r.GENFLAG) !== '', changed: null,
+            callers: { read: false, why: 'Where-used was not read.' }, batch: null, usage: { state: 'unknown', why: NO_USAGE },
+        });
+    };
+    if (step(4)) {
+        for (const pkg of packageNames) {
+            if (aborted()) {
+                cut.add(4);
+                break;
+            }
+            if (!PACKAGE_RE.test(pkg)) {
+                unknowns.push({ what: `step 4: objects of package ${pkg}`, why: 'Not a valid package name; it was not read.' });
+                continue;
+            }
+            const counts = byPkg.get(pkg);
+            const expected = counts ? Object.values(counts).reduce((n, c) => n + c, 0) : 0;
+            const prefixCounted = allPrefixes.some((p) => pkg.startsWith(p) && countedPrefixes.has(p));
+            if (prefixCounted && expected === 0)
+                continue;
+            const res = await run(4, SQL.packageObjects(pkg), prefixCounted ? expected + 50 : 50000, `step 4: objects of package ${pkg}`);
+            if (!('rows' in res))
+                continue;
+            if (prefixCounted && res.rows.length !== expected) {
+                unknowns.push({
+                    what: `step 4: objects of package ${pkg}`,
+                    why: `Package ${pkg}: the system counted ${expected} objects but the pull returned ${res.rows.length}.`,
+                });
+            }
+            for (const r of res.rows) {
+                if (clean(r.GENFLAG))
+                    genPerPkg.set(pkg, (genPerPkg.get(pkg) ?? 0) + 1);
+                addObject(r, pkg);
+            }
+        }
+    }
+    // ── Step 5: $TMP ──
+    const localByPrefix = {};
+    let localCode = 0;
+    if (step(5)) {
+        for (const p of allPrefixes) {
+            if (aborted()) {
+                cut.add(5);
+                break;
+            }
+            const cnt = await run(5, SQL.localCount(p), 10);
+            if (!('rows' in cnt))
+                continue;
+            const n = num(cnt.rows[0]?.CNT);
+            if (!n)
+                continue;
+            localByPrefix[p] = n;
+            const res = await paged(5, (a) => SQL.localObjects(p, a), 'OBJ_NAME', (r) => `${clean(r.OBJECT)}|${clean(r.OBJ_NAME)}`, abortOnly);
+            if (res.stop === 'abort')
+                cut.add(5);
+            for (const r of res.rows) {
+                const before = objects.length;
+                addObject(r, LOCAL_PACKAGE);
+                if (objects.length > before)
+                    localCode += 1;
+            }
+        }
+    }
+    // Lookups over the code objects.
+    const byKey = new Map(objects.map((o) => [`${o.type}|${o.name}`, o]));
+    const byProgname = new Map();
+    for (const o of objects) {
+        const pn = reposrcNameFor(o.type, o.name);
+        if (pn)
+            byProgname.set(pn, o);
+    }
+    // ── Step 6: change dates from REPOSRC ──
+    if (step(6)) {
+        for (const p of allPrefixes) {
+            for (const lp of [p, ...fugrPrefixes(p, 'SAPL')]) {
+                if (aborted()) {
+                    cut.add(6);
+                    break;
+                }
+                const res = await paged(6, (a) => SQL.changes(lp, a), 'PROGNAME', (r) => clean(r.PROGNAME), abortOnly);
+                if (res.stop === 'abort')
+                    cut.add(6);
+                for (const r of res.rows) {
+                    const o = byProgname.get(clean(r.PROGNAME).toUpperCase());
+                    if (!o)
+                        continue;
+                    const at = iso(r.UDAT) ?? iso(r.CDAT);
+                    if (!at)
+                        continue;
+                    const by = iso(r.UDAT) ? clean(r.UNAM) : clean(r.CNAM);
+                    o.changed = { at, by, source: 'REPOSRC' };
+                }
+            }
+        }
+    }
+    // ── Step 7: batch runs ──
+    const usageSources = [];
+    let batchPeriod = null;
+    let batchSource = {
+        name: 'Batch jobs', state: 'not read', period: null, rows: null,
+        note: `${opts.jobs ? STOPPED : 'skipped on request'}. ${BATCH_NOTE}`,
+    };
+    if (opts.jobs && step(7)) {
+        const win = await run(7, SQL.batchWindow(), 10);
+        let failed = 'error' in win ? win.error : undefined;
+        if ('rows' in win) {
+            const from = iso(win.rows[0]?.FIRST_RUN);
+            const to = iso(win.rows[0]?.LAST_RUN);
+            if (from && to)
+                batchPeriod = { from, to };
+        }
+        let found = 0;
+        for (const p of allPrefixes) {
+            if (aborted()) {
+                cut.add(7);
+                break;
+            }
+            const res = await run(7, SQL.batch(p), 50000);
+            if (!('rows' in res)) {
+                failed = failed ?? res.error;
+                continue;
+            }
+            for (const r of res.rows) {
+                const o = byKey.get(`PROG|${clean(r.PROGNAME).toUpperCase()}`);
+                if (!o)
+                    continue;
+                found += 1;
+                o.batch = { runs: num(r.RUNS), lastRun: iso(r.LAST_RUN), source: 'TBTCO/TBTCP', period: batchPeriod };
+            }
+        }
+        batchSource = cut.has(7)
+            ? { name: 'Batch jobs', state: 'not read', period: batchPeriod, rows: found, note: `${STOPPED}. ${BATCH_NOTE}` }
+            : failed
+                ? { name: 'Batch jobs', state: 'not read', period: batchPeriod, rows: found, note: `${failed} ${BATCH_NOTE}` }
+                : { name: 'Batch jobs', state: found ? 'active' : 'empty', period: batchPeriod, rows: found, note: BATCH_NOTE };
+    }
+    let susg = { state: 'not read', period: null, error: STOPPED };
+    let scmon = { state: 'not read', period: null, error: STOPPED };
+    const susgUsed = new Map(); // object key → last used
+    const scmonUsed = new Set();
+    let susgObjectsError;
+    let scmonObjectsError;
+    const objectOf = (type, name, progname) => byKey.get(`${clean(type).toUpperCase()}|${clean(name).toUpperCase()}`) ?? byProgname.get(clean(progname).toUpperCase());
+    if (step(8)) {
+        // SUSG
+        {
+            const admin = await run(8, SQL.susgAdmin(), 1000, 'step 8: SUSG');
+            const data = await run(8, SQL.susgData(), 10, 'step 8: SUSG');
+            const err = 'error' in admin ? admin.error : 'error' in data ? data.error : undefined;
+            if (err) {
+                susg = { state: 'not read', period: null, error: err };
+                usageSources.push({ name: 'SUSG', state: 'not read', period: null, rows: null, note: err });
+            }
+            else {
+                const aRows = admin.rows;
+                const rows = num(data.rows[0]?.CNT);
+                const froms = aRows.map((r) => iso(r.DATE_FROM)).filter((x) => !!x).sort();
+                const tos = aRows.map((r) => iso(r.DATE_TO)).filter((x) => !!x).sort();
+                const period = froms.length && tos.length ? { from: froms[0], to: tos[tos.length - 1] } : null;
+                const state = period && rows > 0 ? 'active' : aRows.length || rows > 0 ? 'empty' : 'off';
+                susg = { state, period };
+                usageSources.push({
+                    name: 'SUSG', state, period, rows,
+                    note: state === 'active' ? 'Aggregated usage over the stated period.' : state === 'empty' ? 'Set up, but holds no usage over a stated period.' : 'Not set up on this system.',
+                });
+            }
+        }
+        // SCMON
+        {
+            const cfg = await run(8, SQL.scmonConfig(), 100, 'step 8: SCMON');
+            const data = await run(8, SQL.scmonData(), 10, 'step 8: SCMON');
+            const slice = await run(8, SQL.scmonSlice(), 10, 'step 8: SCMON');
+            const err = 'error' in cfg ? cfg.error : 'error' in data ? data.error : 'error' in slice ? slice.error : undefined;
+            if (err) {
+                scmon = { state: 'not read', period: null, error: err };
+                usageSources.push({ name: 'SCMON', state: 'not read', period: null, rows: null, note: err });
+            }
+            else {
+                const cfgRows = cfg.rows.length;
+                const rows = num(data.rows[0]?.CNT);
+                const s = slice.rows[0];
+                const from = iso(s?.FROM_DATE);
+                const to = iso(s?.TO_DATE);
+                const period = from && to ? { from, to } : null;
+                const state = cfgRows > 0 && rows > 0 && period ? 'active' : cfgRows > 0 || rows > 0 ? 'empty' : 'off';
+                scmon = { state, period };
+                usageSources.push({
+                    name: 'SCMON', state, period, rows,
+                    note: state === 'active' ? 'Call monitor rows over the stated period.' : state === 'empty' ? 'Set up, but holds no calls over a stated period.' : 'Not set up on this system.',
+                });
+            }
+        }
+        // The ST-PI copy of the call monitor: state only, it does not feed usage here.
+        {
+            const cfg = await run(8, SQL.sdfScmonConfig(), 10, 'step 8: SCMON (ST-PI copy)');
+            const data = await run(8, SQL.sdfScmonData(), 10, 'step 8: SCMON (ST-PI copy)');
+            const err = 'error' in cfg ? cfg.error : 'error' in data ? data.error : undefined;
+            if (err)
+                usageSources.push({ name: 'SCMON (ST-PI copy)', state: 'not read', period: null, rows: null, note: err });
+            else {
+                const c = num(cfg.rows[0]?.CNT);
+                const rows = num(data.rows[0]?.CNT);
+                const state = c > 0 && rows > 0 ? 'active' : c > 0 || rows > 0 ? 'empty' : 'off';
+                usageSources.push({
+                    name: 'SCMON (ST-PI copy)', state, period: null, rows,
+                    note: state === 'active' ? 'Holds rows. Per-object use is not read from this copy.' : state === 'empty' ? 'Set up, but holds no calls.' : 'Not set up on this system.',
+                });
+            }
+        }
+        // ST-PI monitor: system snapshots, never usage.
+        {
+            const header = await run(8, SQL.monHeader(), 10, 'step 8: ST-PI monitor');
+            const call = await run(8, SQL.monCall(), 10, 'step 8: ST-PI monitor');
+            const err = 'error' in header ? header.error : 'error' in call ? call.error : undefined;
+            const rows = err ? null : num(header.rows[0]?.CNT) + num(call.rows[0]?.CNT);
+            usageSources.push({
+                name: 'ST-PI monitor (not usage)', state: err ? 'not read' : rows ? 'active' : 'empty', period: null, rows,
+                note: err ?? 'System snapshots (work processes, memory). It does not record which programs ran.',
+            });
+        }
+        // Workload statistics: the window only.
+        {
+            const w = await run(8, SQL.workload(), 10, 'step 8: workload statistics');
+            if ('error' in w)
+                usageSources.push({ name: 'Workload statistics', state: 'not read', period: null, rows: null, note: w.error });
+            else {
+                const from = iso(w.rows[0]?.FROM_DATE);
+                const to = iso(w.rows[0]?.TO_DATE);
+                const rows = num(w.rows[0]?.CNT);
+                usageSources.push({
+                    name: 'Workload statistics', state: rows ? 'active' : 'empty', period: from && to ? { from, to } : null, rows,
+                    note: from && to
+                        ? `Covers ${from} to ${to}. Per-program figures are stored in a form SQL cannot read, so they do not count as use here.`
+                        : 'No workload window recorded. Per-program figures are stored in a form SQL cannot read.',
+                });
+            }
+        }
+        // Per-object pulls, only from an active source — and only where the join is
+        // proven (it is not yet: see `unprovenPerObjectUsage`). Function groups run
+        // as SAPL<fg>, which LIKE '<p>%' never matches, so those prefixes are read too.
+        const usagePrefixes = allPrefixes.flatMap((p) => [p, ...fugrPrefixes(p, 'SAPL')]);
+        if (!opts.unprovenPerObjectUsage) { /* no per-object usage until the link is proven live */ }
+        else if (susg.state === 'active') {
+            for (const p of usagePrefixes) {
+                const res = await paged(8, (a) => SQL.susgObjects(p, a), 'PROGNAME', (r) => `${clean(r.PROGNAME)}|${clean(r.OBJ_TYPE)}|${clean(r.OBJ_NAME)}`, abortOnly, 'step 8: SUSG per object');
+                if (!res.complete)
+                    susgObjectsError = res.error ?? STOPPED;
+                for (const r of res.rows) {
+                    const o = objectOf(r.OBJ_TYPE, r.OBJ_NAME, r.PROGNAME);
+                    if (!o)
+                        continue;
+                    const k = `${o.type}|${o.name}`;
+                    const lu = iso(r.LAST_USED);
+                    const prev = susgUsed.get(k);
+                    susgUsed.set(k, prev && lu ? (prev > lu ? prev : lu) : (prev ?? lu));
+                }
+                if (susgObjectsError)
+                    break;
+            }
+        }
+        else if (scmon.state === 'active') {
+            for (const p of usagePrefixes) {
+                const res = await paged(8, (a) => SQL.scmonProg(p, a), 'PROGNAME', (r) => `${clean(r.PROGNAME)}|${clean(r.PROGID)}`, abortOnly, 'step 8: SCMON per object');
+                if (!res.complete)
+                    scmonObjectsError = res.error ?? STOPPED;
+                for (const r of res.rows) {
+                    const o = objectOf(r.OBJECT, r.OBJ_NAME, r.PROGNAME);
+                    if (o)
+                        scmonUsed.add(`${o.type}|${o.name}`);
+                }
+                if (scmonObjectsError)
+                    break;
+            }
+        }
+    }
+    usageSources.push(batchSource);
+    // Usage per object (D2).
+    // The window the page's Usage tile names (its first active source). An object
+    // with nothing read about it on a system that has one says so with the
+    // window, never "no usage is recorded" under a tile that names a period.
+    // An aggregate window (workload statistics) is never read per object, and the sentence says so.
+    const unknownWhy = usageUnknownLineOf(usageSources.map((s) => ({ name: s.name, state: s.state, ...(s.period ? { period: s.period } : {}) })), takenAt) ?? NO_USAGE;
+    // "Unused" is never said from a window too short or too old to show it (rehearsal fix 2).
+    const unusedOrUnknown = (source, period) => (shortUsageWindow(period, takenAt)
+        ? { state: 'unknown', why: outsideUsageWindowLine(period, takenAt) }
+        : { state: 'unused', source, period });
+    for (const o of objects) {
+        const k = `${o.type}|${o.name}`;
+        let u;
+        if (!started.has(8))
+            u = { state: 'not read', why: STOPPED };
+        else if (!opts.unprovenPerObjectUsage && (susg.state === 'active' || scmon.state === 'active')) {
+            // The source is real and active; reading it per object is not proven, so nothing is claimed either way.
+            u = { state: 'unknown', why: notPerObject(susg.state === 'active' ? 'SUSG' : 'SCMON', susg.state === 'active' ? susg.period : scmon.period) };
+        }
+        else if (susg.state === 'active') {
+            if (susgObjectsError)
+                u = { state: 'not read', why: susgObjectsError };
+            else if (susgUsed.has(k)) {
+                const lu = susgUsed.get(k);
+                u = { state: 'used', source: 'SUSG', period: susg.period, ...(lu ? { lastUsed: lu } : {}) };
+            }
+            else if (RUNTIME_TYPES.has(o.type))
+                u = unusedOrUnknown('SUSG', susg.period);
+            else
+                u = { state: 'unknown', why: 'Runtime use is not recorded for this type of object.' };
+        }
+        else if (scmon.state === 'active') {
+            if (scmonObjectsError)
+                u = { state: 'not read', why: scmonObjectsError };
+            else if (scmonUsed.has(k))
+                u = { state: 'used', source: 'SCMON', period: scmon.period };
+            else if (RUNTIME_TYPES.has(o.type))
+                u = unusedOrUnknown('SCMON', scmon.period);
+            else
+                u = { state: 'unknown', why: 'Runtime use is not recorded for this type of object.' };
+        }
+        else if (susg.state === 'not read' || scmon.state === 'not read') {
+            u = { state: 'not read', why: susg.state === 'not read' ? susg.error : scmon.error };
+        }
+        else
+            u = { state: 'unknown', why: unknownWhy };
+        if (o.batch && o.batch.runs > 0 && u.state !== 'used') {
+            u = {
+                state: 'used', source: 'batch',
+                ...(o.batch.period ? { period: o.batch.period } : {}),
+                ...(o.batch.lastRun ? { lastUsed: o.batch.lastRun } : {}),
+            };
+        }
+        o.usage = u;
+    }
+    // ── Steps 9 + 10: where-used from the index ──
+    let xref = { read: 'not read', objectsCovered: 0, note: 'skipped on request' };
+    let xrefStopped = false; // step 9 stopped early and is already listed under unknowns
+    if (!opts.xref) {
+        for (const o of objects)
+            o.callers = { read: false, why: 'Where-used was skipped on request.' };
+    }
+    else if (!started.has(8) && aborted()) {
+        xref = { read: 'not read', objectsCovered: 0, note: STOPPED };
+        for (const o of objects)
+            o.callers = { read: false, why: 'Stopped before where-used reached this object.' };
+    }
+    else {
+        const deadline = now().getTime() + Math.max(0, opts.maxMinutes) * 60_000;
+        let budgetHit = false;
+        const xrefStop = () => {
+            if (aborted())
+                return 'abort';
+            if (now().getTime() > deadline) {
+                budgetHit = true;
+                return 'budget';
+            }
+            return null;
+        };
+        const indexRows = [];
+        /** Names with more index rows than one page holds: unread, the rest is read on past them. */
+        const tooMany = new Set();
+        const tableState = new Map(); // `${table}|${prefix}` → result (null = not started)
+        let stopReason = null;
+        if (step(9)) {
+            for (const p of allPrefixes) {
+                for (const table of ['CROSS', 'WBCROSSGT']) {
+                    const k = `${table}|${p}`;
+                    if (stopReason === 'abort' || stopReason === 'budget') {
+                        tableState.set(k, null);
+                        continue;
+                    }
+                    const build = table === 'CROSS' ? (a, st) => SQL.cross(p, a, st) : (a, st) => SQL.wbcrossgt(p, a, st);
+                    const res = await paged(9, build, 'NAME', (r) => `${clean(r.NAME)}|${clean(r.INCLUDE)}`, xrefStop, `step 9: where-used (${table}, ${p})`, (name) => tooMany.add(name.toUpperCase().split('\\')[0]));
+                    tableState.set(k, res);
+                    for (const r of res.rows)
+                        indexRows.push({ name: clean(r.NAME).toUpperCase(), include: clean(r.INCLUDE).toUpperCase() });
+                    if (res.stop === 'abort' || res.stop === 'budget')
+                        stopReason = res.stop;
+                }
+            }
+        }
+        else {
+            stopReason = 'abort';
+        }
+        if (stopReason !== null)
+            xrefStopped = true;
+        if (stopReason === 'abort')
+            unknowns.push({ what: 'step 9: where-used', why: STOPPED });
+        if (stopReason === 'budget' || budgetHit) {
+            unknowns.push({ what: 'step 9: where-used', why: `the time budget (${opts.maxMinutes} minutes) ran out` });
+        }
+        // Step 10: include → main program (paged the same way, same budget).
+        // D010INC first: a report include that TADIR also lists as a PROG belongs to its
+        // master. A report maps to itself only where D010INC never names it as an include.
+        const masters = new Map();
+        if (stopReason === null && step(10)) {
+            let mastersComplete = true;
+            let mastersFailed = false; // a failed page is already under unknowns (run())
+            for (const p of allPrefixes) {
+                for (const lp of [p, ...fugrPrefixes(p, 'L')]) {
+                    const res = await paged(10, (a) => SQL.masters(lp, a), 'INCLUDE', (r) => `${clean(r.INCLUDE)}|${clean(r.MASTER)}`, xrefStop);
+                    for (const r of res.rows) {
+                        const inc = clean(r.INCLUDE).toUpperCase();
+                        if (!masters.has(inc))
+                            masters.set(inc, clean(r.MASTER).toUpperCase());
+                    }
+                    if (!res.complete) {
+                        mastersComplete = false;
+                        if (res.stop === 'error')
+                            mastersFailed = true;
+                        if (res.stop === 'abort' || res.stop === 'budget') {
+                            stopReason = res.stop;
+                            break;
+                        }
+                    }
+                }
+                if (stopReason)
+                    break;
+            }
+            if (!mastersComplete && !mastersFailed) {
+                unknowns.push({
+                    what: 'step 10: include to program',
+                    why: stopReason === 'abort' ? STOPPED : stopReason === 'budget' ? `the time budget (${opts.maxMinutes} minutes) ran out` : 'read only in part; some callers are counted as unmapped',
+                });
+            }
+        }
+        for (const o of objects)
+            if (o.type === 'PROG' && !masters.has(o.name))
+                masters.set(o.name, o.name);
+        const selfKey = new Map();
+        for (const o of objects)
+            if (!selfKey.has(o.name))
+                selfKey.set(o.name, `${o.type}|${o.name}`);
+        const callers = callersFromIndex(indexRows, masters, (n) => selfKey.get(n) ?? '');
+        const whyFor = (r) => {
+            if (r?.stop === 'error')
+                return r.error ?? 'The where-used query failed.';
+            if (r?.stop === 'stuck')
+                return 'Too many where-used rows for one name to page through.';
+            if (r?.stop === 'budget' || (!r && budgetHit))
+                return 'The where-used time budget ran out before this object was read.';
+            return 'Stopped before where-used reached this object.';
+        };
+        const okFor = (r, name) => {
+            if (!r)
+                return false;
+            if (r.complete)
+                return true;
+            const b = r.boundary;
+            return b !== undefined && name < b && !b.startsWith(`${name}\\`);
+        };
+        let covered = 0;
+        let indexed = 0;
+        for (const o of objects) {
+            if (!INDEXED_TYPES.has(o.type)) {
+                o.callers = { read: false, why: NOT_INDEXED };
+                continue;
+            }
+            indexed += 1;
+            if (tooMany.has(o.name)) {
+                o.callers = { read: false, why: 'too many index rows to read' };
+                continue;
+            }
+            const owners = allPrefixes.filter((p) => o.name.startsWith(p));
+            let why = 'Where-used was not read for this name.';
+            let ok = false;
+            for (const p of owners) {
+                const c = tableState.get(`CROSS|${p}`);
+                const w = tableState.get(`WBCROSSGT|${p}`);
+                if (okFor(c, o.name) && okFor(w, o.name)) {
+                    ok = true;
+                    break;
+                }
+                why = whyFor(!okFor(c, o.name) ? c : w);
+            }
+            if (ok) {
+                const c = callers.get(o.name);
+                const keys = c ? [...c.objects].sort() : [];
+                o.callers = { objects: keys.length, includesUnmapped: c?.includesUnmapped ?? 0, sample: keys.slice(0, 5), source: 'index', read: true };
+                covered += 1;
+            }
+            else {
+                o.callers = { read: false, why };
+            }
+        }
+        const total = indexed;
+        if (covered === total)
+            xref = { read: 'complete', objectsCovered: covered, note: `where-used read for ${covered} of ${total} objects` };
+        else if (covered > 0)
+            xref = { read: 'partial', objectsCovered: covered, note: `where-used read for ${covered} of ${total} objects` };
+        else {
+            const firstErr = [...tableState.values()].find((r) => r?.stop === 'error')?.error;
+            xref = { read: 'not read', objectsCovered: 0, note: firstErr ? `where-used could not be read: ${firstErr}` : `where-used read for 0 of ${total} objects` };
+        }
+    }
+    // ── Step 11: modifications of SAP objects ──
+    const real = [];
+    let noteCorrections = null;
+    let otherRows = null;
+    if (step(11)) {
+        for (const op of ['MOD', 'NEW', 'IMP']) {
+            const res = await run(11, SQL.modifications(op), 50000);
+            if (!('rows' in res))
+                continue;
+            for (const r of res.rows) {
+                const objectName = clean(r.OBJ_NAME).toUpperCase();
+                if (customerNamed(objectName))
+                    continue;
+                real.push({
+                    objectType: clean(r.OBJ_TYPE), objectName, subType: clean(r.SUB_TYPE), subName: clean(r.SUB_NAME),
+                    operation: clean(r.OPERATION), date: iso(r.MOD_DATE), user: clean(r.MOD_USER),
+                });
+            }
+        }
+        const note = await run(11, SQL.modificationCount('NOTE'), 10);
+        if ('rows' in note)
+            noteCorrections = num(note.rows[0]?.CNT);
+        const all = await run(11, SQL.modificationCount('ALL'), 10);
+        if ('rows' in all)
+            otherRows = num(all.rows[0]?.CNT);
+    }
+    // ── Step 12: successor data ──
+    if (step(12))
+        await run(12, SQL.successors(), 10);
+    // Unfinished steps after Ctrl-C (steps skipped on request are not unfinished).
+    for (let n = 1; n <= 12; n++) {
+        if (cut.has(n)) {
+            unknowns.push({ what: `step ${n}: ${STEP_LABELS[n]}`, why: STOPPED });
+            continue;
+        }
+        if (started.has(n))
+            continue;
+        if (n === 7 && !opts.jobs)
+            continue;
+        if ((n === 9 || n === 10) && !opts.xref)
+            continue;
+        if ((n === 9 || n === 10) && xrefStopped)
+            continue;
+        unknowns.push({ what: `step ${n}: ${STEP_LABELS[n]}`, why: STOPPED });
+    }
+    // ── Assemble ──
+    const nonCodeByType = {};
+    const lastChangedByPkg = new Map();
+    for (const o of objects) {
+        if (!o.changed)
+            continue;
+        const prev = lastChangedByPkg.get(o.package);
+        if (!prev || o.changed.at > prev.at)
+            lastChangedByPkg.set(o.package, { at: o.changed.at, by: o.changed.by });
+    }
+    const packages = packageNames.map((name) => {
+        const info = pkgInfo.get(name);
+        const counts = byPkg.get(name) ?? {};
+        let code = 0;
+        let nonCode = 0;
+        for (const [t, n] of Object.entries(counts)) {
+            if (codeTypes.has(t))
+                code += n;
+            else {
+                nonCode += n;
+                nonCodeByType[t] = (nonCodeByType[t] ?? 0) + n;
+            }
+        }
+        return {
+            name, text: pkgText.get(name) ?? '', parent: clean(info?.PARENTCL), component: clean(info?.DLVUNIT) || clean(info?.COMPONENT),
+            area: clean(info?.APPLICAT), objects: code + nonCode, codeObjects: code, nonCodeObjects: nonCode,
+            byType: { ...counts }, generated: genPerPkg.get(name) ?? 0, lastChanged: lastChangedByPkg.get(name) ?? null,
+        };
+    });
+    objects.sort((a, b) => a.package.localeCompare(b.package) || a.type.localeCompare(b.type) || a.name.localeCompare(b.name));
+    const estate = {
+        kind: 'estate', formatVersion: 1, takenAt, by: opts.by, system: { ...(opts.system ?? {}) },
+        prefixes, namespaces, packages,
+        local: { byPrefix: localByPrefix, codeObjects: localCode },
+        nonCode: { byType: nonCodeByType },
+        usageSources,
+        modifications: { real, noteCorrections, otherRows },
+        xref, unknowns, queries,
+    };
+    return { estate, objects: { kind: 'estate-objects', formatVersion: 1, takenAt, objects } };
+}