@cspeach/cli 1.1.30 → 1.1.32

package/dist/register/export-files.js

@@ -0,0 +1,58 @@
+/**
+ * The CSV export on disk (step 2, Task 4; spec 2026-10-08 §3.4, D2). The
+ * tables come from register-core (`exportSet`, pure); this file writes them:
+ * each file whole, then renamed, so a sync tool never picks up half of one;
+ * CSV as UTF-8 with a BOM (Excel then reads umlauts right), CRLF line ends,
+ * RFC 4180 quoting (`csvText`).
+ *
+ * The switch is visible JSON in the team project file — `"exports": { "csv": true }`
+ * — set by `cspeach team export --always` or the journey's report card. No
+ * hidden state. Default off.
+ */
+import path from 'node:path';
+import { csvText, exportSet } from '@cspeach/register-core';
+import { HELD } from './workbooks.js';
+import { readProjectFile, TEAM_FILE } from './store.js';
+import { writeWhole } from './write-whole.js';
+/** The folder the export goes into, under the reports folder (or the folder `--out` named for a report). */
+export const EXPORTS_DIR = 'exports';
+/** True only when the team project file says exactly `"exports": { "csv": true }`. */
+export function exportsOn(project) {
+    const e = project.exports;
+    return !!e && typeof e === 'object' && e.csv === true;
+}
+/** Set the switch on or off: the whole project file, then renamed. Every other field stays as it is. */
+export function setExports(projectDir, on) {
+    const project = readProjectFile(projectDir);
+    const had = project.exports && typeof project.exports === 'object' ? project.exports : {};
+    const next = { ...project, exports: { ...had, csv: on } };
+    writeWhole(path.join(projectDir, TEAM_FILE), `${JSON.stringify(next, null, 2)}\n`);
+}
+/** Turn the switch on (`team export --always`, the card's "Every time"). */
+export const setExportsAlways = (projectDir) => setExports(projectDir, true);
+/**
+ * Every file of the export into `dir`. Each file is tried on its own: one held
+ * open in Excel never costs the others, and the caller names it.
+ */
+export function writeExportFiles(register, project, dir, generatedAt) {
+    const set = exportSet(register, project, { generatedAt });
+    const files = [
+        ...set.tables.map((t) => [t.file, csvText(t)]),
+        ['manifest.json', `${JSON.stringify(set.manifest, null, 2)}\n`],
+        ['SCHEMA.md', set.schema],
+    ];
+    const saved = [];
+    const held = [];
+    for (const [name, text] of files) {
+        try {
+            writeWhole(path.join(dir, name), Buffer.from(text, 'utf8'));
+            saved.push(name);
+        }
+        catch (e) {
+            if (!HELD.has(e?.code ?? ''))
+                throw e;
+            held.push(name);
+        }
+    }
+    return { saved, held };
+}

package/dist/register/findings.js

@@ -20,7 +20,7 @@ const basisOf = (v) => {
     const w = String(v).trim().toLowerCase();
     return w === '' || w === 'system' ? 'system' : 'file';
 };
-export function findingsByObject(projectDir, outboxDir) {
+export function findingsByObject(projectDir, outboxDir, opts = {}) {
     const project = readProjectFile(projectDir);
     const ours = variantKey(project.atcVariant);
     const records = [
@@ -56,13 +56,16 @@ export function findingsByObject(projectDir, outboxDir) {
                 // handed-over file, and it goes to a terminal and to the model's tools.
                 const message = named && typeof f.message === 'string' ? shown(f.message) : '';
                 const had = seen.rules.get(rule);
+                const line = opts.lines && named && Number.isInteger(f.line) && f.line > 0 ? f.line : undefined;
                 if (had) {
                     had.count += 1;
                     if (!had.message && message)
                         had.message = message;
+                    if (line !== undefined && (had.line === undefined || line < had.line))
+                        had.line = line;
                 }
                 else
-                    seen.rules.set(rule, { rule, message, count: 1 });
+                    seen.rules.set(rule, { rule, message, count: 1, ...(line !== undefined ? { line } : {}) });
             }
             byKey.set(key, list);
         }

package/dist/register/measure.js

@@ -98,18 +98,169 @@ function apiNameIn(text) {
  *
  * The TITLE is read first: it is where SAP names the API, while the long text
  * can quote source code and would otherwise hand a token like `TABLE` to the
- * record. The wording is STILL ASSUMED: the 2026-09-20 capture ran DEFAULT and
- * S4HANA_READINESS_2022 only, and neither produced an unreleased-API finding
- * (README answer 9, still open). This function is the only place that wording
- * is read, and it must be re-checked against a clean-core variant run.
+ * record.
+ *
+ * READINESS WORDING: VERIFIED-NO-API-NAME (live, S4H, 2026-10-08). On a real
+ * ABAP_CLOUD_READINESS worklist the message TEXT is empty on every finding and
+ * the title says only "Usage of not released ABAP Platform APIs." — SAP's
+ * wording names no API (`__tests__/fixtures/atc-readiness-worklist.xml`). So
+ * this rule names nothing on a real system, and it is KEPT ONLY AS A FALLBACK
+ * for a text that ever does name one. The API of a USAGE_OF_RELEASED_APIS
+ * finding comes from the finding itself instead: its REF_OBJ_NAME /
+ * REF_OBJ_TYPE tags, or its document (`apiNamesFor`), and it only feeds
+ * `uses` — the finding keeps its check's own rule id.
  */
 export function unreleasedApiRule(f) {
+    const name = unreleasedApiName(f);
+    return name ? `UNRELEASED_API:${name}` : null;
+}
+/** The API an unreleased-API finding names, by the same (unverified) reading as `unreleasedApiRule`. */
+function unreleasedApiName(f) {
     const title = f.messageTitle ?? '';
     const body = f.messageText ?? '';
     if (!NOT_RELEASED.test(`${title} ${body}`))
         return null;
-    const name = apiNameIn(title) ?? apiNameIn(body);
-    return name ? `UNRELEASED_API:${name}` : null;
+    return apiNameIn(title) ?? apiNameIn(body);
+}
+/**
+ * A finding of SAP's "Usage of Released APIs" check (USAGE_OF_RELEASED_APIS),
+ * read by its rule id exactly the way register-core's `classifyFinding` reads
+ * it. Only such a finding's referenced object is "the API it uses": the syntax
+ * check also tags a REF_OBJ_NAME, and that names a statement.
+ */
+export function isReleasedApiFinding(f) {
+    return [ruleIdFromAtc(f), ...ruleAliasesFromAtc(f)]
+        .some((id) => normalizeRuleId(id).split(':')[0] === 'USAGE_OF_RELEASED_APIS');
+}
+const apiRef = (o) => {
+    const name = typeof o?.name === 'string' ? o.name.trim().toUpperCase() : '';
+    const type = typeof o?.type === 'string' ? o.type.trim().toUpperCase() : '';
+    return name ? { name, ...(type ? { type } : {}) } : undefined;
+};
+/** Finding documents one run reads, at most. The rest are left without `uses`, counted and said. */
+export const MAX_API_DOCUMENTS = 200;
+/** Finding documents read at the same time. */
+export const API_DOCUMENT_CONCURRENCY = 4;
+/**
+ * The API each USAGE_OF_RELEASED_APIS finding uses, by finding.
+ *
+ * The worklist's own REF_OBJ_NAME / REF_OBJ_TYPE tags first — they cost
+ * nothing. A finding without them has its document read (distinct links, at
+ * most `API_DOCUMENT_CONCURRENCY` at a time, at most `cap` per run). A
+ * document that fails, names nothing, or was past the cap leaves its finding
+ * without a name: no `uses`, so it stays open for B. Never a guess.
+ */
+async function apiNamesFor(findings, read, cap, signal) {
+    const named = new Map();
+    const needDoc = new Map();
+    let namedNone = 0;
+    let notLookedUp = 0;
+    for (const f of findings) {
+        const tag = apiRef(f.referencedObject);
+        if (tag) {
+            named.set(f, tag);
+            continue;
+        }
+        if (!f.documentation)
+            namedNone += 1;
+        else if (!read)
+            notLookedUp += 1;
+        else
+            needDoc.set(f.documentation, [...(needDoc.get(f.documentation) ?? []), f]);
+    }
+    const hrefs = [...needDoc.keys()];
+    const toRead = hrefs.slice(0, Math.max(0, cap));
+    const overCap = hrefs.slice(toRead.length).reduce((n, h) => n + needDoc.get(h).length, 0);
+    let unreadable = 0;
+    let documents = 0;
+    const started = Date.now();
+    let next = 0;
+    const worker = async () => {
+        while (next < toRead.length && !signal?.aborted) {
+            const href = toRead[next++];
+            documents += 1;
+            try {
+                const ref = apiRef((await read(href))?.referencedObject);
+                if (ref)
+                    for (const f of needDoc.get(href))
+                        named.set(f, ref);
+                else
+                    namedNone += needDoc.get(href).length;
+            }
+            catch {
+                unreadable += needDoc.get(href).length;
+            }
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(API_DOCUMENT_CONCURRENCY, toRead.length) }, worker));
+    // Within the cap but never asked for: the run was stopped.
+    const stopped = toRead.slice(next).reduce((n, h) => n + needDoc.get(h).length, 0);
+    return {
+        named,
+        report: {
+            findings: findings.length, named: named.size, documents, ms: documents ? Date.now() - started : 0,
+            unnamed: findings.length - named.size, overCap, unreadable, namedNone, stopped, notLookedUp,
+        },
+    };
+}
+/* ── `uses`: what SAP says about the API a finding names (step 2, F8) ────── */
+/** API names per `ARS_W_API_STATE` read. */
+export const ARS_CHUNK = 50;
+/** At most this many type/state pairs are kept for one API name. */
+export const MAX_USES = 10;
+/**
+ * Rows asked for per ARS read. ARS holds a row per sub-object too, so a read
+ * that comes back FULL may have been cut, and the row cut off may be the one
+ * that is not stable: a full page is read as unreadable (review 3).
+ */
+export const ARS_MAX_ROWS = ARS_CHUNK * 20;
+/**
+ * One batched read of `ARS_W_API_STATE` per run, by `OBJECT_NAME`, in chunks
+ * of 50 distinct names (F8). Every distinct type/state SAP returns for a name
+ * is kept, as SAP spells it, so one entry that is not stable keeps the finding
+ * open for B (register-core `stateOfUses`). A name SAP returns nothing for
+ * gets no entry: the finding then has no `uses` and stays open — honest, not
+ * guessed. A read that fails reads nothing, and the measurement is written as
+ * it always was.
+ *
+ * The names come from the USAGE_OF_RELEASED_APIS findings themselves
+ * (`apiNamesFor`) and, as a fallback, from a message text that names an API
+ * (`unreleasedApiRule`): `uses` is written only on a finding one of them named.
+ */
+async function apiStatesOf(sql, names) {
+    const out = new Map();
+    // A name goes into the statement only when it can hold no quote or bracket.
+    const safe = [...new Set(names)].filter((n) => SAP_NAME.test(n));
+    for (let i = 0; i < safe.length; i += ARS_CHUNK) {
+        const chunk = safe.slice(i, i + ARS_CHUNK);
+        let rows;
+        try {
+            ({ rows } = await sql(`SELECT DISTINCT OBJECT_TYPE, OBJECT_NAME, RELEASE_STATE FROM ARS_W_API_STATE WHERE OBJECT_NAME IN (${chunk.map((n) => `'${n}'`).join(',')})`, ARS_MAX_ROWS));
+        }
+        catch {
+            return new Map(); // unreadable: no `uses` at all, never half of them
+        }
+        const list = Array.isArray(rows) ? rows : [];
+        if (list.length >= ARS_MAX_ROWS)
+            return new Map(); // possibly cut: no `uses` at all, never a wrong state
+        for (const r of list) {
+            const name = String(r?.OBJECT_NAME ?? '').trim().toUpperCase();
+            const type = String(r?.OBJECT_TYPE ?? '').trim().toUpperCase();
+            const state = String(r?.RELEASE_STATE ?? '').trim().toUpperCase();
+            if (!name || !type || !state || !chunk.includes(name))
+                continue;
+            const seen = out.get(name) ?? [];
+            if (!seen.some((u) => u.type === type && u.state === state))
+                seen.push({ type, name, state });
+            out.set(name, seen);
+        }
+    }
+    // More pairs than a finding carries: the name gets none, never a cut list whose
+    // missing entry could be the one that is not stable (review 3).
+    for (const [name, list] of out)
+        if (list.length > MAX_USES)
+            out.delete(name);
+    return out;
 }
 /**
  * SAP writes some check names as `ID / text` — `SLIN_DB / SELECT without ORDER
@@ -144,7 +295,11 @@ function halvesOf(src) {
  * `coverage.absent` goes to 0, an absent-clean row renders a plain "Clean", and
  * nothing anywhere says that nothing actually looked at the object.
  */
-export function findingsToRows(measured, findings, projectType) {
+export function findingsToRows(measured, findings, projectType, 
+/** What `ARS_W_API_STATE` said about each API name (`apiStatesOf`). Absent: no `uses` are written. */
+usesByName, 
+/** The API each USAGE_OF_RELEASED_APIS finding uses (`apiNamesFor`), by finding. */
+apiNameOf) {
     const byKey = new Map();
     const evidenceOf = new Map();
     for (const o of measured) {
@@ -160,7 +315,13 @@ export function findingsToRows(measured, findings, projectType) {
         if (!list)
             continue; // a finding for an object that was not measured is never written
         const atcRule = ruleIdFromAtc(f);
-        const api = projectType === 'clean-core' ? unreleasedApiRule(f) : null;
+        const apiName = projectType === 'clean-core' ? unreleasedApiName(f) : null;
+        const api = apiName ? `UNRELEASED_API:${apiName}` : null;
+        // The finding's own referenced object first; the text's name only as a fallback.
+        // When SAP said the TYPE, only ARS rows of that type are its state: ARS is read by
+        // name, and a function group SCAL is not the table SCAL (live, 2026-10-08).
+        const ref = (projectType === 'clean-core' ? apiNameOf?.get(f) : undefined) ?? (apiName ? { name: apiName } : undefined);
+        const uses = ref ? usesByName?.get(ref.name)?.filter((u) => !ref.type || u.type === ref.type) : undefined;
         // A finding nobody can name still counts: dropping it would make the object look cleaner than it is.
         const rule = api ?? (atcRule || UNNAMED_FINDING);
         const aliases = [...new Set([...(api && atcRule ? [atcRule] : []), ...ruleAliasesFromAtc(f), ...halvesOf(f)])]
@@ -182,6 +343,8 @@ export function findingsToRows(measured, findings, projectType) {
             ...(f.line ? { line: f.line } : {}),
             // The title only. The long text can quote source, and the record promises: no source code.
             ...(title ? { message: title.slice(0, 200) } : {}),
+            // F8: only on a finding whose API was named, and only what SAP returned for that name.
+            ...(uses?.length ? { uses: uses.map((u) => ({ ...u })) } : {}),
         });
     }
     return [...byKey.entries()].map(([key, list]) => {
@@ -408,7 +571,25 @@ export async function measure(input) {
     };
     if (!rowRefs.length)
         return { ...counts, file: null, withFindings: 0, refusedRows };
-    const rows = findingsToRows(rowRefs, [...outcome.findings, ...ownFindings], input.project.type);
+    const allFindings = [...outcome.findings, ...ownFindings];
+    // F8: the APIs the findings of measured objects use, read once for the whole run.
+    let usesByName;
+    let apiNameOf;
+    let apiNames;
+    if (input.sql && input.project.type === 'clean-core') {
+        const rowKeys = new Set(rowRefs.map((o) => objectKey(o.type, o.name)));
+        const inRows = allFindings.filter((f) => typeof f?.key === 'string' && rowKeys.has(normalizeKey(f.key)));
+        const releasedApi = inRows.filter(isReleasedApiFinding);
+        if (releasedApi.length) {
+            const got = await apiNamesFor(releasedApi, input.atc.findingDocument?.bind(input.atc), input.apiDocumentCap ?? MAX_API_DOCUMENTS, input.signal);
+            apiNameOf = got.named;
+            apiNames = got.report;
+        }
+        const names = [...[...(apiNameOf?.values() ?? [])].map((r) => r.name), ...inRows.map((f) => unreleasedApiName(f)).filter((n) => !!n)];
+        if (names.length)
+            usesByName = await apiStatesOf(input.sql, names);
+    }
+    const rows = findingsToRows(rowRefs, allFindings, input.project.type, usesByName, apiNameOf);
     const res = writeRecord(input.joined, 'measurement', rows, input.by, {
         ...(input.now ? { now: input.now } : {}), ...(input.dir ? { dir: input.dir } : {}),
         ...(input.fileName ? { fileName: input.fileName } : {}), ...(input.rand ? { rand: input.rand } : {}),
@@ -435,5 +616,6 @@ export async function measure(input) {
     return {
         ...counts, ...coverageNow(), file: res.file, refusedRows,
         withFindings: rows.filter((r) => r.findings.length > 0).length,
+        ...(apiNames ? { apiNames } : {}),
     };
 }

package/dist/register/offer.js

@@ -1,12 +1,63 @@
 /**
- * The one line CSPeach prints after it activated, and verified, an object of
- * the team project this laptop has joined (spec §4.3). It records nothing:
- * "CSPeach activated it" and "the developer says it is fixed" are two different
- * sentences, and only the second is a claim.
+ * The line CSPeach prints after it activated, and verified, an object of the
+ * team project this laptop has joined (spec §4.3).
+ *
+ * 1.1.31 (owner, 2026-10-07: "why would developers claim it when CSPeach is
+ * working?"): when CSPeach itself wrote the object's source in this session,
+ * the fix is recorded for the developer — the claim covers every rule open at
+ * the object's last measurement, with the transport the write used. A claim is
+ * still not proof: only the next measurement moves it to verified.
+ * An object CSPeach activated but did not write (someone changed it in Eclipse
+ * or SE80) only gets the one-line offer; the developer claims that one.
  */
 import { objectKey } from '@cspeach/register-core';
 import { activeProject, readBaseline } from './store.js';
-export function teamFixOffers(objects) {
+import { findingsByObject } from './findings.js';
+import { writeRecord } from './records.js';
+import { regenerateWorkingList } from './workbooks.js';
+/** The source-writing tools, and the argument that names the object each one wrote. */
+const SOURCE_WRITES = {
+    sap_set_source: 'name',
+    sap_update_method: 'class_name',
+    sap_set_class_include: 'className',
+};
+/**
+ * Objects whose source CSPeach wrote successfully in this session (upper-case
+ * name → the transport the write used, '' when none is known).
+ */
+export function cspeachWritesThisSession(toolCalls) {
+    const out = new Map();
+    for (const c of toolCalls ?? []) {
+        if (!c.completed || c.is_error)
+            continue;
+        const field = SOURCE_WRITES[c.tool];
+        if (!field)
+            continue;
+        const args = (c.args ?? {});
+        const name = String(args[field] ?? '').trim().toUpperCase();
+        if (!name)
+            continue;
+        let transport = typeof args['transport'] === 'string' ? args['transport'] : '';
+        try {
+            // sap_set_source / sap_update_method report the request they used as transport_used.
+            const r = JSON.parse(c.result);
+            if (typeof r?.transport_used === 'string' && r.transport_used)
+                transport = r.transport_used;
+            else if (typeof r?.transport === 'string' && r.transport)
+                transport = r.transport;
+        }
+        catch { /* a plain-text result carries no transport */ }
+        out.set(name, transport.trim().toUpperCase());
+    }
+    return out;
+}
+/** Fixes this process already recorded (a write that activated, then an explicit activate, record once). */
+const recordedThisRun = new Set();
+/** Tests only. */
+export function resetRecordedFixes() { recordedThisRun.clear(); }
+export function teamFixOffers(objects, opts = {}) {
+    // A guided journey is on (journey/flow.ts): the same records, in solo words.
+    const solo = opts.wording === 'journey';
     try {
         const joined = activeProject();
         if (!joined)
@@ -17,15 +68,56 @@ export function teamFixOffers(objects) {
         for (const o of baseline)
             byName.set(o.name.toUpperCase(), [...(byName.get(o.name.toUpperCase()) ?? []), o]);
         const lines = [];
+        const done = new Set();
         for (const o of objects) {
             const type = String(o?.type ?? '').split('/')[0].trim().toUpperCase();
             const name = String(o?.name ?? '').trim().toUpperCase();
             const same = byName.get(name) ?? [];
             const hit = byKey.get(objectKey(type, name)) ?? (same.length === 1 ? same[0] : undefined);
-            if (hit)
-                lines.push(`This object is in your team project. Mark it fixed? cspeach team fixed ${hit.type.toUpperCase()} ${hit.name.toUpperCase()}`);
+            if (!hit)
+                continue;
+            const key = objectKey(hit.type, hit.name);
+            if (done.has(key))
+                continue;
+            done.add(key);
+            const label = `${hit.type.toUpperCase()} ${hit.name.toUpperCase()}`;
+            const transport = opts.written?.get(hit.name.toUpperCase());
+            if (transport === undefined) {
+                lines.push(solo
+                    ? `${label} is one of your objects, but CSPeach did not write it, so no fix was recorded.`
+                    : `This object is in your team project. Mark it fixed? cspeach team fixed ${label}`);
+                continue;
+            }
+            const runKey = `${joined.projectId}|${key}|${transport}`;
+            if (recordedThisRun.has(runKey))
+                continue;
+            const f = findingsByObject(joined.projectDir, joined.outboxDir).get(key);
+            if (!f?.latestAt) {
+                lines.push(solo
+                    ? `${label} has not been checked yet, so no fix was recorded. The next check looks at it.`
+                    : `${label} has not been measured yet, so no fix was recorded. Run cspeach team refresh to measure it.`);
+                continue;
+            }
+            if (!f.latest.length) {
+                lines.push(solo
+                    ? `${label} had nothing open at its last check, so no fix was recorded. The next check looks at it.`
+                    : `${label} had nothing open at its last measurement, so no fix was recorded. The next cspeach team refresh checks it.`);
+                continue;
+            }
+            // The name this person records under in this team project, as team verbs use it.
+            const who = opts.who ?? joined.name ?? process.env['CSPEACH_AUTHOR_NAME'] ?? process.env['USER'] ?? process.env['USERNAME'] ?? 'consultant';
+            const res = writeRecord(joined, 'fix', f.latest.map((r) => ({ key, rule: r.rule, status: 'fixed', ...(transport ? { transport } : {}) })), { name: who });
+            if (!res.file)
+                continue;
+            recordedThisRun.add(runKey);
+            const by = `✓ Recorded: ${label} fixed by CSPeach${transport ? ` in ${transport}` : ''}.`;
+            lines.push(solo ? `${by} Not yet checked — the next check proves it.` : `${by} A claim is not proof — the next cspeach team refresh checks it.`);
+            try {
+                regenerateWorkingList(joined, who);
+            }
+            catch { /* the record is kept; the list catches up on the next run */ }
         }
-        return [...new Set(lines)];
+        return lines;
     }
     catch {
         return []; // a folder halfway through a sync must never touch an activation

package/dist/register/picture.js

@@ -1,6 +1,6 @@
 import path from 'node:path';
 import { buildRegister, narrowedLanes } from '@cspeach/register-core';
-import { collectRecords, readBaseline, readLanes, readProjectFile } from './store.js';
+import { collectRecords, readBaseline, readEstate, readLanes, readProjectFile } from './store.js';
 export function registerFor(projectDir, outboxDir) {
     const project = readProjectFile(projectDir);
     const collected = collectRecords(projectDir);
@@ -10,7 +10,11 @@ export function registerFor(projectDir, outboxDir) {
     const own = outboxDir && path.resolve(outboxDir) !== path.resolve(projectDir) ? collectRecords(outboxDir) : { records: [], unreadable: 0, files: 0 };
     const baseline = readBaseline(projectDir);
     const lanes = readLanes(projectDir);
-    const register = buildRegister({ project, baseline, lanes, records: [...collected.records, ...own.records] });
+    // The newest discovery, when the folder holds one: the estate around the team project.
+    const estate = readEstate(projectDir)?.estate;
+    const register = buildRegister({
+        project, baseline, lanes, records: [...collected.records, ...own.records], ...(estate !== undefined ? { estate } : {}),
+    });
     return {
         register, files: collected.files + own.files,
         unreadable: collected.unreadable + own.unreadable, ownFiles: own.files,