@cspeach/cli 1.1.14 → 1.1.15

package/dist/register/atc-file.js

@@ -0,0 +1,802 @@
+/**
+ * An ATC result export, read in as a measurement (D8).
+ *
+ * For a team with no connection from CSPeach to SAP: somebody exports the ATC
+ * result list from the system, and this turns it into the same measurement
+ * record a live run writes — marked `basis: 'file'`, carrying the file's name
+ * and checksum, and always shown as "measured from a file". CSPeach cannot see
+ * how the file was made, so it never claims more than "this file said so".
+ *
+ * ONE rule decides everything below: a file proves "clean" only for a row
+ * CSPeach understood COMPLETELY. A column it does not know, a line cut short, a
+ * finding it cannot tie to an object, a type this team project does not have —
+ * each of those ends as "not measured", is counted, and is named. Doubt spreads
+ * to the object: if a row that could not be read may belong to ZCL_FI_TAX, then
+ * nothing in this file may write ZCL_FI_TAX clean, not even the person saying
+ * the export covers the whole scope.
+ *
+ * The file is untrusted input. It is read once, as text, from the one path a
+ * person typed: no path inside it is ever followed, nothing in it is executed,
+ * and every piece of its text that reaches the terminal goes through `shown()`.
+ *
+ * Program code only. No model tool reaches this file.
+ */
+import { createHash } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { objectKey } from '@cspeach/register-core';
+import { findingsToRows, scopeLabel, scopeObjects, } from './measure.js';
+import { writeRecord } from './records.js';
+import { RegisterError } from './store.js';
+export class AtcFileError extends RegisterError {
+}
+/*
+ * The three tables below decide what a column means, and with it what "clean"
+ * can mean in this file.
+ *
+ * CONFIRMED on 2026-09-20 against `sap-client/test/fixtures/atc-export-real/
+ * atc-findings-en-unconverted.txt` — an English logon, SAP GUI's classic
+ * "unconverted" list, run series over package ZTEST_LAS with an S/4HANA
+ * readiness variant, default layout, 26 columns:
+ *
+ *   read        Priority · Check Title · Check Message · Object name · Obj. ·
+ *               Note · RObT · Ref. Obj. · Count · Msg. Code
+ *   finding     Exemption State · Short text · Component · Category (twice) ·
+ *               Text · Marked Bsl · App. Comp. · Identity · Check Class
+ *   neutral     Contact · Package · 1st Found · Obj. Resp. · Changed by · Changed On
+ *
+ * Why each of the judged ones landed where it did:
+ *   · `Obj.` is the object TYPE (`PROG`), not its name — the name has a column
+ *     of its own. `Obj. Resp.` is a person, so it is neutral.
+ *   · `Msg. Code` is the message id (`SELECT`, `LOOP_WRITE`) — the half of a
+ *     rule's name that a live run calls `messageId`. `Check Title` is the other
+ *     half. Together they give a file finding the SAME rule id a live finding
+ *     gets, which is the whole point of reading the file.
+ *   · `Check Message` is the message title with no instance text in it.
+ *   · `RObT` / `Ref. Obj.` name the object the finding POINTS AT (`TABL BSEG`),
+ *     not the object that was checked. Read for the display message only.
+ *   · `Short text` is the cited SAP Note's title, not the finding's long text,
+ *     so it is not read into `messageText`.
+ *   · `Category` holds `I` / `T` beside a `Text` column reading `Technical`:
+ *     both describe the finding, so both are finding-side. Neither is read —
+ *     `Check Title` is what names a rule — which is why two columns called
+ *     `Category` can stand side by side without CSPeach having to guess.
+ *   · `Identity` is the finding's own number (`671,599,554-`), `Check Class`
+ *     the check's implementing class, `Marked Bsl` whether it sits in an ATC
+ *     baseline: all three belong to a finding, none is read.
+ *   · `Component` and `App. Comp.` are the cited note's component, which only a
+ *     finding has. The NEVER-neutral list from Task 7 stands: `Text`, `Status`,
+ *     `Note` and their kin are finding-side, whatever else they could mean.
+ *
+ * STILL JUDGED, with no capture behind them: every German title, every other
+ * layout ("all columns"), the spreadsheet export of the findings grid, and an
+ * Excel round-trip. A column nobody has seen is an unknown column, and an
+ * unknown column means this file proves no clean row — which is the safe way
+ * round and is where those stay until somebody exports one.
+ *
+ * A title is compared WHOLE, after `titleKey`: lower case, diacritics folded,
+ * and the separators between whole words turned into single spaces. Nothing is
+ * deleted from inside a word, so `D-a-t-u-m` is not `Datum`.
+ */
+/** Columns CSPeach reads. First match wins, in the order written here. */
+const HEADERS = {
+    type: ['object type', 'objecttype', 'obj type', 'objtype', 'objtyp', 'type', 'objekttyp', 'objekt typ', 'obj'],
+    name: ['object name', 'objectname', 'obj name', 'objname', 'object', 'name', 'objektname', 'objekt name'],
+    checkId: ['check id', 'checkid', 'check', 'test id', 'testid', 'test', 'prufung', 'prufungen'],
+    messageId: ['message id', 'messageid', 'msg id', 'msgid', 'message code', 'messagecode', 'code',
+        'message number', 'messagenumber', 'meldungsid', 'meldungs id', 'meldungsnummer', 'msg code', 'msgcode'],
+    title: ['message title', 'messagetitle', 'meldungstitel', 'meldung', 'prufmeldung',
+        'check message', 'checkmessage', 'message', 'message text', 'messagetext', 'meldungstext',
+        'short text', 'shorttext', 'kurztext', 'description', 'beschreibung', 'title'],
+    text: ['message long text', 'messagelongtext', 'long text', 'longtext', 'langtext',
+        'message text', 'messagetext', 'meldungstext'],
+    category: ['check title', 'checktitle', 'pruftitel', 'category', 'kategorie', 'check category', 'checkcategory'],
+    priority: ['priority', 'prio', 'prioritat', 'prioritaet', 'prioritt', 'severity'],
+    line: ['line', 'lineno', 'line no', 'line number', 'linenumber', 'source line', 'sourceline', 'row', 'zeile', 'zeilennummer'],
+    // These four are read last, so a column an older table already claims keeps it.
+    refType: ['robt', 'ref obj type', 'refobjtype', 'referenced object type', 'referencedobjecttype'],
+    refObject: ['ref obj', 'refobj', 'ref obj name', 'refobjname', 'referenced object name', 'referencedobjectname', 'referenced object'],
+    note: ['note', 'hinweis'],
+    count: ['count', 'anzahl'],
+};
+/**
+ * Columns CSPeach knows to be part of a FINDING but does not read. It never
+ * takes their text into a record; a cell with anything in one of them is why a
+ * row is a finding and not a clean object.
+ */
+export const FINDING_HEADERS = [
+    // what inside the object the finding sits in, and what it points at
+    'sub object type', 'subobjecttype', 'sub object name', 'subobjectname', 'sub object', 'subobject',
+    'teilobjekttyp', 'teilobjektname', 'teilobjekt',
+    'referenced object type', 'referencedobjecttype', 'referenced object name', 'referencedobjectname',
+    'referenced object', 'ref obj type', 'refobjtype', 'ref obj name', 'refobjname', 'referenziertes objekt',
+    'include', 'program', 'programm', 'column', 'spalte',
+    // what SAP says about it
+    'sap note', 'sapnote', 'note', 'hinweis', 'sap hinweis',
+    'additional information', 'additionalinformation', 'zusatzinformation', 'zusatzinformationen',
+    'quality of finding', 'qualityoffinding', 'availability', 'verfugbarkeit',
+    'quick fix', 'quickfix', 'quick fixes', 'quickfixes',
+    // how it was dealt with
+    'exemption', 'exemption status', 'exemptionstatus', 'exemption state', 'exemption id', 'ausnahme', 'ausnahmestatus',
+    'state', 'status', 'result', 'ergebnis',
+    'text', 'info', 'information', 'comment', 'kommentar', 'bemerkung',
+    // Confirmed by the 2026-09-20 export: each of these is a property of a
+    // FINDING, so a cell under one is why a row is a finding and not clean.
+    'short text', 'shorttext', 'kurztext', 'component', 'komponente', 'app comp', 'category', 'kategorie',
+    'marked bsl', 'marked baseline', 'baseline', 'identity', 'check class', 'checkclass', 'prufklasse',
+];
+const FINDING_ONLY = new Set(FINDING_HEADERS);
+/**
+ * Columns that say something about WHERE a row came from, never what was found
+ * in it. A row is "checked and clean" only when every cell outside the object
+ * type, the object name and this list is empty — so a column nobody put on one
+ * of these three lists can never be mistaken for an empty one.
+ */
+export const NEUTRAL_HEADERS = [
+    // where the object lives
+    'package', 'devclass', 'development class', 'paket', 'paketname',
+    'software component', 'softwarecomponent', 'softwarekomponente',
+    'application component', 'applicationcomponent', 'anwendungskomponente',
+    'namespace', 'namensraum', 'transport request', 'transportrequest', 'transport', 'transportauftrag',
+    // whose it is
+    'author', 'autor', 'owner', 'responsible', 'person responsible', 'personresponsible', 'verantwortlicher',
+    'obj resp', 'object responsible', 'objectresponsible',
+    'contact', 'contact person', 'contactperson', 'ansprechpartner',
+    'user', 'user name', 'username', 'benutzer',
+    // when
+    'created on', 'createdon', 'created by', 'createdby', 'angelegt am', 'angelegt von', 'erstellt am',
+    'changed on', 'changedon', 'changed by', 'changedby', 'geandert am', 'geandert von', 'letzter anderer',
+    'last changed on', 'lastchangedon', 'last changed by', 'lastchangedby',
+    'detected on', 'detectedon', 'date', 'datum', 'time', 'uhrzeit', 'timestamp', 'zeitstempel',
+    // When the run series first reported this object. A date, never a finding.
+    '1st found', 'first found', 'firstfound', 'erstmals gefunden',
+    // which system
+    'system', 'sid', 'client', 'mandant', 'release',
+    // which run
+    'run id', 'runid', 'run series', 'runseries', 'series', 'series id', 'seriesid',
+    'worklist', 'worklist id', 'worklistid', 'result id', 'resultid', 'display id', 'displayid',
+    'variant', 'check variant', 'checkvariant', 'variante', 'prufvariante',
+];
+const NEUTRAL = new Set(NEUTRAL_HEADERS);
+/**
+ * A plain row counter is neutral only while every cell under it is digits. The
+ * same short titles are what a person writes over a column of their own notes.
+ */
+export const COUNTER_HEADERS = ['no', 'nr', 'row no', 'rowno', 'row number', 'rownumber', 'lfd nr', 'lfdnr', 'laufende nummer'];
+const COUNTER = new Set(COUNTER_HEADERS);
+/** The cells that make a row a FINDING. A row with none of them names an object the export checked. */
+const FINDING_FIELDS = ['checkId', 'messageId', 'category', 'title', 'text', 'priority', 'line',
+    'refType', 'refObject', 'note', 'count', 'other'];
+const PRIORITY_WORDS = { error: 1, warning: 2, info: 3, information: 3 };
+/**
+ * How many findings one row stands for. SAP's result list carries a `Count`,
+ * and a row that says 5 is five findings in that object, not one.
+ *
+ * Anything that is not a whole number above zero is ONE finding, silently: a
+ * count CSPeach cannot read is not a reason to drop a finding, and a row can
+ * never be worth none. The cap is there so a file claiming a billion cannot
+ * fill the laptop's memory; no real result row comes near it, and erring high
+ * is the safe direction — a finding too many never makes an object look clean.
+ */
+const MAX_COUNT = 1000;
+const THOUSANDS = /^\d{1,3}(?:[.,  ]\d{3})+$/;
+export function countOf(cell) {
+    const t = cell.trim();
+    if (!t)
+        return undefined;
+    const digits = THOUSANDS.test(t) ? t.replace(/[.,  ]/g, '') : t;
+    const n = /^\d+$/.test(digits) ? Number.parseInt(digits, 10) : 1;
+    return Math.min(Math.max(n, 1), MAX_COUNT);
+}
+/**
+ * What a person reads under a finding: the message, and then what it points at.
+ * `DB Operation JOIN found (TABL BSEG, note 2431747)`.
+ *
+ * DISPLAY ONLY. It never names a rule: the referenced object changes from one
+ * finding of a rule to the next, and an id built from it would split one rule
+ * into as many rules as it has instances — the trap `messageTitle` is kept out
+ * of an id for (README answer 5, F1).
+ */
+export function fileMessage(row) {
+    const base = row.title ?? '';
+    const ref = [row.refType, row.refObject].filter(Boolean).join(' ');
+    const tail = [ref, row.note ? `note ${row.note}` : ''].filter(Boolean).join(', ');
+    if (!tail)
+        return base;
+    return base ? `${base} (${tail})` : `(${tail})`;
+}
+/**
+ * Characters that are in the text and not on the screen: a zero-width space in
+ * an object name reads as another object, and the eye cannot tell them apart.
+ * They come off type and name before anything is matched, and out of every
+ * string that is printed.
+ *
+ * Each one is written as an escape, and so is the combining-mark range below:
+ * a character class whose payload is the characters themselves is a class no
+ * reviewer can read — the line shows a dash, two gaps and a trust exercise.
+ * Both are exported so the set can be pinned code point by code point
+ * (`atc-file.test.ts`), which is the only way to prove that rewriting a line
+ * nobody can see changed nothing.
+ */
+export const ZERO_WIDTH = /[\u00AD\u200B-\u200F\u202A-\u202E\u2060-\u2064\uFEFF]/g;
+export const INVISIBLE = /[\u0000-\u001F\u007F-\u009F\u00AD\u200B-\u200F\u202A-\u202E\u2060-\u2064\uFEFF]/g;
+/** A header title, whole: lower case, diacritics folded, separators between whole words made single spaces. */
+export function titleKey(header) {
+    const folded = String(header).replace(INVISIBLE, '')
+        .normalize('NFD').replace(/[\u0300-\u036F]/g, '')
+        .replace(/ß/g, 'ss').replace(/Ø/gi, 'o')
+        .toLowerCase().trim().replace(/\s+/g, ' ');
+    const words = folded.split(/[\s_\-./]+/).filter(Boolean);
+    if (!words.length)
+        return '';
+    // One letter on its own is not a word: `D-a-t-u-m` must never become `Datum`.
+    if (words.some((w) => w.length < 2))
+        return folded;
+    return words.join(' ');
+}
+/** A sheet is not a file this reads. Said as what to do, not as what is wrong. */
+const EXCEL = 'This is an Excel workbook. Open it, save the sheet as CSV, and run this again with the CSV file.';
+const NOT_UTF8 = 'This file is not UTF-8 text. In Excel choose "CSV UTF-8" when you save it.';
+/** A result list is small. Anything this size is a download that went wrong, and reading it would hang the terminal. */
+const MAX_BYTES = 50 * 1024 * 1024;
+/** How far into the file the delimiter and the encoding are judged from. */
+const SNIFF = 4096;
+/** A cell inside quotation marks that runs on for this many lines is a quote nobody closed. */
+const MAX_QUOTED_LINES = 20;
+/** How many lines at the top may be a title above the header. */
+const HEADER_LINES = 5;
+/** Off an object type or name before anything is matched: what cannot be seen must not decide anything. */
+const clean = (cell) => cell.replace(INVISIBLE, '').trim();
+const quoteNeverClosed = (line) => `A quotation mark in line ${line} is never closed, so CSPeach cannot read this file safely.`;
+/**
+ * Text that came out of the file, made safe to print. A customer's export can
+ * carry an escape sequence that repaints the terminal, a NUL, or a megabyte of
+ * binary on one line — none of which may reach a person through CSPeach.
+ */
+export function shown(text) {
+    const flat = String(text)
+        // An OSC sequence runs to BEL or ESC-backslash and can retitle the window.
+        .replace(/\x1b\][^\x07\x1b]*(\x07|\x1b\\)?/g, ' ')
+        // A CSI sequence repaints, clears or moves the cursor.
+        .replace(/\x1b\[[0-9;?]*[ -/]*[@-~]?/g, ' ')
+        .replace(/\x1b[@-_]?/g, ' ')
+        // Zero-width and bidi characters: invisible on screen, and one of them can
+        // turn a printed name back to front. They go, leaving no gap.
+        .replace(ZERO_WIDTH, '')
+        // A control character stood between two words: it leaves a space behind, so
+        // the words do not run into one.
+        .replace(/[\x00-\x1f\x7f-\x9f]+/g, ' ')
+        .replace(/\s+/g, ' ')
+        .trim();
+    return flat.length > 60 ? `${flat.slice(0, 60)}…` : flat;
+}
+/** Five names and the count of the rest: a list nobody can read is a list nobody acts on. */
+export const upToFive = (items) => (items.length > 5 ? `${items.slice(0, 5).join(', ')} and ${items.length - 5} more` : items.join(', '));
+function splitCsv(text, delimiter) {
+    const rows = [];
+    let cells = [];
+    let cell = '';
+    let quoted = false;
+    let quoteAt = 0;
+    let atLine = 1; // where the scanner is
+    let rowAt = 1; // where the current row started
+    for (let i = 0; i < text.length; i += 1) {
+        const c = text[i];
+        if (quoted) {
+            if (c === '\n') {
+                atLine += 1;
+                if (atLine - quoteAt > MAX_QUOTED_LINES)
+                    throw new AtcFileError(quoteNeverClosed(quoteAt));
+                cell += c;
+            }
+            else if (c !== '"')
+                cell += c;
+            else if (text[i + 1] === '"') {
+                cell += '"';
+                i += 1;
+            }
+            else
+                quoted = false;
+            continue;
+        }
+        if (c === '"' && cell === '') {
+            quoted = true;
+            quoteAt = atLine;
+            continue;
+        }
+        if (c === delimiter) {
+            cells.push(cell);
+            cell = '';
+            continue;
+        }
+        if (c === '\n' || c === '\r') {
+            if (c === '\r' && text[i + 1] === '\n')
+                i += 1;
+            atLine += 1;
+            cells.push(cell);
+            cell = '';
+            rows.push({ cells, line: rowAt });
+            cells = [];
+            rowAt = atLine;
+            continue;
+        }
+        cell += c;
+    }
+    // A quotation mark nobody closed swallows every row after it. Silently
+    // reading three rows as one is how a file comes to prove something it does
+    // not say, so this is refused rather than guessed at.
+    if (quoted)
+        throw new AtcFileError(quoteNeverClosed(quoteAt));
+    if (cell !== '' || cells.length) {
+        cells.push(cell);
+        rows.push({ cells, line: rowAt });
+    }
+    return rows.filter((r) => r.cells.some((v) => v.trim() !== ''));
+}
+/* ── SAP GUI's classic "unconverted" list ───────────────────────────────────
+ *
+ * Confirmed 2026-09-20. Not a CSV at all: ASCII, CRLF, a rule of `-` above the
+ * header and below it, every data line fenced with `|`, every cell padded with
+ * spaces to its column's width and numbers pushed to the right. A closing rule
+ * may end the list.
+ *
+ * A `|` INSIDE a cell cannot be escaped in this format, so nothing here tries
+ * to guess one back together: a row that splits into a different number of
+ * cells than the header is a row of the wrong length, and the short/long rule
+ * below counts it, names its line and never calls it clean.
+ */
+/** A line that draws a rule: dashes or equals signs, and nothing that carries text. */
+const RULE_LINE = /^[-=+|\s]*[-=][-=+|\s]*$/;
+/** Three bars fence two cells: fewer than that is a sentence with a bar in it. */
+const MIN_BARS = 3;
+/** How far in the unconverted shape is judged from. */
+const UNCONVERTED_LINES = 20;
+const isFenced = (line) => line.length > 2 && line.startsWith('|') && line.endsWith('|')
+    && line.split('|').length - 1 >= MIN_BARS;
+function looksUnconverted(text) {
+    let fenced = 0;
+    let rules = 0;
+    for (const raw of text.split('\n').slice(0, UNCONVERTED_LINES)) {
+        const line = raw.replace(/\r$/, '').trim();
+        if (!line)
+            continue;
+        if (RULE_LINE.test(line)) {
+            rules += 1;
+            continue;
+        }
+        if (isFenced(line))
+            fenced += 1;
+    }
+    return fenced >= 2 || (fenced >= 1 && rules >= 1);
+}
+function splitUnconverted(text) {
+    const rows = [];
+    const lines = text.split('\n');
+    for (let i = 0; i < lines.length; i += 1) {
+        const line = lines[i].replace(/\r$/, '').trim();
+        if (!line || RULE_LINE.test(line))
+            continue;
+        // A line this format does not have — a title, a page footer — becomes one
+        // cell, which is not a header and not a row CSPeach can read whole.
+        const cells = isFenced(line) ? line.slice(1, -1).split('|').map((c) => c.trim()) : [line];
+        rows.push({ cells, line: i + 1 });
+    }
+    return rows.filter((r) => r.cells.some((v) => v.trim() !== ''));
+}
+/**
+ * The ATC RUN MONITOR: the list of runs, not the list of findings. It is one
+ * menu away from the right screen and it holds no finding at all, so a customer
+ * hands it over by mistake. Said as what to do next, not as what is wrong.
+ */
+const RUN_LIST_TITLES = new Set(['run series', 'execution id', 'restarts', 'expires on', 'started by',
+    'config access factory', 'duration seconds']);
+const RUN_LIST = 'This is the list of ATC runs, not the list of findings. '
+    + 'In SAP GUI, select your run, press Result, and export the findings list.';
+/** Two of its own column titles: one alone can stand in a findings export too. */
+const RUN_LIST_MARKS = 2;
+const looksLikeRunList = (rows) => rows.some((r) => r.cells.filter((c) => RUN_LIST_TITLES.has(titleKey(c))).length >= RUN_LIST_MARKS);
+export function parseAtcCsv(input) {
+    const text = input.charCodeAt(0) === 0xfeff ? input.slice(1) : input;
+    // 'PK' + bytes 3 and 4: the first bytes of every .xlsx (it is a zip). Not a bare 'PK': a header can start with "PKG".
+    if (text.startsWith(`PK${String.fromCharCode(3, 4)}`))
+        throw new AtcFileError(EXCEL);
+    // UTF-16 read as UTF-8 is full of NULs. `squash` would strip them and match a
+    // header that is not there, so this is refused before anything is normalised.
+    if (text.slice(0, SNIFF).includes('\u0000') || /^[\uFFFE\uFEFF]/.test(text))
+        throw new AtcFileError(NOT_UTF8);
+    // SAP GUI's unconverted list first: its `Identity` cells hold thousands
+    // separators, so a comma sniff would read it as a comma-separated file and
+    // shred every row. It is told apart by its shape, not by its punctuation.
+    const unconverted = looksUnconverted(text);
+    // The delimiter is judged from the first few lines, not from the whole file:
+    // a title line above the header holds none of them.
+    const head = text.slice(0, SNIFF).split(/\r?\n/).slice(0, HEADER_LINES + 1);
+    const count = (d) => Math.max(...head.map((l) => l.split(d).length - 1), 0);
+    const delimiter = unconverted
+        ? '|'
+        : [';', '\t', ','].reduce((best, d) => (count(d) > count(best) ? d : best), ',');
+    const all = unconverted ? splitUnconverted(text) : splitCsv(text, delimiter);
+    // A real export can carry a title line or two above the header.
+    let headerAt = -1;
+    let at = {};
+    let columns = {};
+    for (let i = 0; i < Math.min(HEADER_LINES, all.length); i += 1) {
+        const mapped = mapHeader(all[i].cells);
+        if (mapped) {
+            headerAt = i;
+            at = mapped.at;
+            columns = mapped.columns;
+            break;
+        }
+    }
+    if (headerAt < 0) {
+        // The wrong screen's export, named before the generic refusal: it has no
+        // object column and never will, and "which columns it needs" is no help.
+        if (looksLikeRunList(all.slice(0, HEADER_LINES)))
+            throw new AtcFileError(RUN_LIST);
+        const first = all[0]?.cells ?? [];
+        throw new AtcFileError('This file needs a column for the object type, one for the object name, and one for the check or message. '
+            + `It has: ${first.map((h) => shown(h)).filter(Boolean).join(', ') || 'no header row'}`);
+    }
+    const header = all[headerAt].cells;
+    const data = all.slice(headerAt + 1);
+    const taken = new Set(Object.values(at));
+    /*
+     * Two columns with one name.
+     *
+     * When CSPeach READS one of them it has to pick, and the one it did not pick
+     * becomes a cell it treats as empty — and an empty cell is what "clean" is
+     * made of. It cannot know which is true, so it refuses the file.
+     *
+     * When it reads NEITHER, nothing is hidden: both stand where they are and
+     * both are watched, finding-side or neutral, by position. The real export has
+     * exactly that — `Category` twice, confirmed 2026-09-20 — and a file CSPeach
+     * can account for whole is a file it may read. The second one is shown as
+     * `Category (2)`, so a column named on screen can still be found by eye.
+     */
+    const firstAt = new Map();
+    const seenTitles = new Map();
+    const label = header.map((h) => (h ?? '').trim());
+    for (let n = 0; n < header.length; n += 1) {
+        const w = titleKey(header[n] ?? '');
+        if (!w)
+            continue;
+        const before = seenTitles.get(w) ?? 0;
+        seenTitles.set(w, before + 1);
+        if (!before) {
+            firstAt.set(w, n);
+            continue;
+        }
+        const first = firstAt.get(w);
+        if (taken.has(n) || taken.has(first)) {
+            throw new AtcFileError(`This file has the column "${shown(label[first])}" more than once, so CSPeach cannot tell its columns apart. Nothing was read.`);
+        }
+        label[n] = `${label[n]} (${before + 1})`;
+    }
+    // A row that repeats the header is the header again, not an object called
+    // "OBJECT NAME". It is dropped whole: it says nothing either way.
+    const isHeaderRow = (cells) => cells.length === header.length && cells.every((c, n) => titleKey(c) === titleKey(header[n] ?? ''));
+    const body = data.filter((r) => !isHeaderRow(r.cells));
+    const emptyColumn = (n) => body.every((r) => (r.cells[n] ?? '').trim() === '');
+    const digitsColumn = (n) => body.every((r) => /^\d*$/.test((r.cells[n] ?? '').trim()));
+    const unknownColumns = [];
+    const findingAt = [...taken].filter((n) => n !== at.type && n !== at.name);
+    header.forEach((h, n) => {
+        if (taken.has(n))
+            return;
+        const key = titleKey(h);
+        if (FINDING_ONLY.has(key)) {
+            findingAt.push(n);
+            return;
+        }
+        if (NEUTRAL.has(key))
+            return;
+        if (COUNTER.has(key) && digitsColumn(n))
+            return;
+        // A column with no title CSPeach can read hides whatever is under it — so it
+        // is unknown unless there is nothing under it at all.
+        if (!key) {
+            if (!emptyColumn(n))
+                unknownColumns.push(`column ${n + 1}`);
+            return;
+        }
+        unknownColumns.push(shown(label[n] ?? h));
+    });
+    const fieldAt = new Map(Object.entries(at).map(([f, n]) => [n, f]));
+    const rows = [];
+    const unreadable = [];
+    let orphanFindings = 0;
+    for (const raw of body) {
+        const cellOf = (field) => (at[field] === undefined ? '' : (raw.cells[at[field]] ?? '').trim());
+        const type = clean(cellOf('type')).toUpperCase();
+        const name = clean(cellOf('name')).toUpperCase();
+        const prio = cellOf('priority');
+        const priority = PRIORITY_WORDS[prio.toLowerCase()] ?? (Number.parseInt(prio, 10) || undefined);
+        const line = Number.parseInt(cellOf('line'), 10) || undefined;
+        const row = {
+            type, name,
+            ...(cellOf('checkId') ? { checkId: cellOf('checkId') } : {}),
+            ...(cellOf('messageId') ? { messageId: cellOf('messageId') } : {}),
+            ...(cellOf('category') ? { category: cellOf('category') } : {}),
+            ...(cellOf('title') ? { title: cellOf('title') } : {}),
+            ...(cellOf('text') ? { text: cellOf('text') } : {}),
+            ...(priority ? { priority } : {}),
+            ...(line ? { line } : {}),
+            ...(cellOf('refType') ? { refType: cellOf('refType') } : {}),
+            ...(cellOf('refObject') ? { refObject: cellOf('refObject') } : {}),
+            ...(cellOf('note') ? { note: cellOf('note') } : {}),
+            ...(countOf(cellOf('count')) ? { count: countOf(cellOf('count')) } : {}),
+        };
+        // A finding is judged by the CELL, never by what CSPeach could make of it:
+        // `Very High` in the priority column is a finding, not an empty cell.
+        for (const n of findingAt) {
+            const cell = (raw.cells[n] ?? '').trim();
+            if (!cell)
+                continue;
+            const field = fieldAt.get(n);
+            if (field && row[field] !== undefined)
+                continue;
+            row.other = row.other ?? cell;
+        }
+        const hadFinding = isFindingRow(row);
+        if (!type || !name) {
+            unreadable.push({ line: raw.line, hadFinding, why: name ? 'no-type' : 'no-name', ...(name ? { name } : {}) });
+            // A finding that names no object may belong to ANY object in this file.
+            if (!name && hadFinding)
+                orphanFindings += 1;
+            continue;
+        }
+        // A line cut short is missing cells CSPeach would otherwise read as empty;
+        // a line with more cells than the header has slipped a column. With a
+        // finding in what is left it is still a finding; with nothing in it, it is
+        // not a clean object, it is half a line.
+        if (raw.cells.length !== header.length && !hadFinding) {
+            unreadable.push({ line: raw.line, name, hadFinding, why: raw.cells.length < header.length ? 'short' : 'long' });
+            continue;
+        }
+        rows.push(row);
+    }
+    return {
+        rows, columns, skipped: unreadable.length, delimiter, unknownColumns, unreadable,
+        canProveClean: unknownColumns.length === 0 && orphanFindings === 0,
+    };
+}
+/** The read columns of a header row, or null when this row is not a header at all. */
+function mapHeader(cells) {
+    const at = {};
+    const columns = {};
+    for (const field of Object.keys(HEADERS)) {
+        for (const word of HEADERS[field]) {
+            const i = cells.findIndex((h, n) => titleKey(h) === word && !Object.values(at).includes(n));
+            if (i >= 0) {
+                at[field] = i;
+                columns[field] = cells[i].trim();
+                break;
+            }
+        }
+    }
+    const named = at.checkId !== undefined || at.messageId !== undefined || at.title !== undefined;
+    return at.type !== undefined && at.name !== undefined && named ? { at, columns } : null;
+}
+/** True when the row names a finding; false when it only names an object the export checked. */
+export const isFindingRow = (row) => FINDING_FIELDS.some((f) => row[f] !== undefined);
+/** `R3TR PROG` → `PROG`, `CLAS/OC` → `CLAS`. The last word, before any slash. */
+const typeOf = (cell) => {
+    const t = cell.trim().toUpperCase().split(/\s+/).pop() ?? '';
+    return t.split('/')[0] ?? t;
+};
+/** `ZCL_FI_TAX=>CALC`, `ZCL_FI_TAX=CM001`, `ZIF_X~METH` all point at `ZCL_FI_TAX`. */
+const CLASS_INCLUDE = /=+C\w+$/;
+export function doubtCandidates(name) {
+    const whole = name.trim().toUpperCase();
+    const head = whole.split(/=>|\s+|~/)[0] ?? whole;
+    return [...new Set([whole, head, head.replace(CLASS_INCLUDE, ''), whole.replace(CLASS_INCLUDE, '')])].filter(Boolean);
+}
+export function measureFromFile(input) {
+    const bytes = readFileBytes(input.filePath);
+    const parsed = parseAtcCsv(bytes.toString('utf8'));
+    if (!parsed.rows.length && !parsed.unreadable.length) {
+        throw new AtcFileError('The file holds no result rows. An empty file is not proof that anything is clean, so nothing was written.');
+    }
+    // One object, one row, however often the baseline or the file names it.
+    const seen = new Set();
+    const baseline = input.baseline.filter((o) => { const k = objectKey(o.type, o.name); return seen.has(k) ? false : (seen.add(k), true); });
+    const byName = new Map();
+    for (const o of baseline) {
+        const n = o.name.trim().toUpperCase();
+        byName.set(n, [...(byName.get(n) ?? []), objectKey(o.type, o.name)]);
+    }
+    const inScope = input.scope ? scopeObjects(baseline, input.lanes, input.scope) : null;
+    const scopeKeys = inScope ? new Set(inScope.map((o) => objectKey(o.type, o.name))) : null;
+    const findings = [];
+    const unknown = new Set();
+    const ambiguous = new Set();
+    const disagreed = new Set();
+    const doubted = new Set();
+    const knownInFile = new Set();
+    const cleanRows = new Set();
+    const named = new Set();
+    /**
+     * Findings this file holds that CSPeach could not give to an object of this
+     * team project. Every one of them may belong to an object the file also calls
+     * clean, so ONE of them is enough: the file vouches for nothing.
+     */
+    const unplaced = [];
+    let outsideScope = 0;
+    /** A row nobody could read casts doubt on every baseline object its name could mean. */
+    const doubt = (name) => {
+        let hit = false;
+        for (const c of doubtCandidates(name))
+            if (byName.has(c)) {
+                doubted.add(c);
+                hit = true;
+            }
+        return hit;
+    };
+    for (const u of parsed.unreadable) {
+        if (u.name)
+            doubt(u.name);
+        if (u.hadFinding)
+            unplaced.push(shown(u.name ?? `line ${u.line}`));
+    }
+    for (const r of parsed.rows) {
+        // The TYPE cell decides. A name this team project holds under another type
+        // is never taken instead: that is how a finding in ZCL_FI_TAX comes to be
+        // written against the report of the same name.
+        const key = objectKey(typeOf(r.type), r.name);
+        if (!seen.has(key)) {
+            const sameName = byName.get(r.name.trim().toUpperCase()) ?? [];
+            if (sameName.length > 1)
+                ambiguous.add(shown(key));
+            else if (sameName.length === 1)
+                disagreed.add(shown(key));
+            // A method, a function module or an include names its object in its own
+            // name. It is not another system's row, and it is not this object's proof.
+            if (!doubt(r.name))
+                unknown.add(shown(key));
+            if (isFindingRow(r))
+                unplaced.push(shown(r.name));
+            continue;
+        }
+        knownInFile.add(key);
+        if (scopeKeys && !scopeKeys.has(key)) {
+            outsideScope += 1;
+            continue;
+        }
+        if (isFindingRow(r)) {
+            named.add(key);
+            const display = fileMessage(r);
+            const finding = {
+                key, ...(r.checkId ? { checkId: r.checkId } : {}), ...(r.messageId ? { messageId: r.messageId } : {}),
+                ...(r.category ? { category: r.category } : {}), ...(r.title ? { messageTitle: r.title } : {}),
+                ...(r.text ? { messageText: r.text } : {}),
+                ...(r.priority ? { priority: r.priority } : {}), ...(r.line ? { line: r.line } : {}),
+                ...(display && display !== r.title ? { displayMessage: display } : {}),
+            };
+            // A row that says it was found 5 times is five findings in that object.
+            // The same finding five times over is what the export means, and counting
+            // it once would make the object look better than SAP says it is.
+            for (let n = 0; n < (r.count ?? 1); n += 1)
+                findings.push(finding);
+            continue;
+        }
+        cleanRows.add(key);
+    }
+    if (unknown.size > knownInFile.size) {
+        throw new AtcFileError(`${unknown.size} of the ${unknown.size + knownInFile.size} objects in this file are not in this team project `
+            + `(${upToFive([...unknown])}). It looks like the export of another system or another scope, so nothing was written.`);
+    }
+    /**
+     * Whether this file may be taken at its word about ANY object being clean.
+     * One finding it could not place, one column it does not know, one finding
+     * with no object: each of those could be the finding that belongs to the
+     * object the file calls clean.
+     */
+    const vouches = parsed.canProveClean && unplaced.length === 0;
+    if (vouches)
+        for (const key of cleanRows)
+            named.add(key);
+    else
+        for (const key of cleanRows)
+            doubt(key.slice(key.indexOf('|') + 1));
+    const hasFinding = new Set(findings.map((f) => f.key));
+    const orphaned = parsed.unreadable.filter((u) => u.why === 'no-name' && u.hadFinding).length;
+    const canBeClean = (o) => vouches && !doubted.has(o.name.trim().toUpperCase());
+    // Row order follows the baseline, so two imports of the same scope read the same way.
+    const pool = inScope ?? baseline;
+    const rowRefs = pool
+        .filter((o) => {
+        const key = objectKey(o.type, o.name);
+        if (hasFinding.has(key))
+            return true;
+        if (!canBeClean(o))
+            return false;
+        return input.scope && input.absentMeansClean ? true : named.has(key);
+    })
+        .map((o) => ({ type: o.type, name: o.name }));
+    const rowKeys = new Set(rowRefs.map((o) => objectKey(o.type, o.name)));
+    // Named by this file, left as not measured: said one by one, never as a number
+    // alone. An object the file never mentions is a different sentence.
+    const touched = (o) => knownInFile.has(objectKey(o.type, o.name)) || doubted.has(o.name.trim().toUpperCase());
+    const leftOut = pool.filter((o) => !rowKeys.has(objectKey(o.type, o.name)) && touched(o))
+        .map((o) => objectKey(o.type, o.name));
+    const label = input.scope ? scopeLabel(input.scope) : 'file';
+    const asked = inScope ? inScope.length : rowRefs.length + leftOut.length;
+    // Every object of the scope that got no row, named. `doubted` above is the
+    // subset the file DID mention and could not be read; these are all of them.
+    const absentNames = pool.map((o) => objectKey(o.type, o.name)).filter((k) => !rowKeys.has(k)).slice(0, 2000);
+    const counts = {
+        scope: label, asked, measured: rowRefs.length, absent: asked - rowRefs.length,
+        failed: 0, unsupported: 0, unsupportedNames: [], absentNames, notRun: 0,
+        refusedChunks: [], fileRows: parsed.rows.length + parsed.unreadable.length,
+        unknown: [...unknown].sort(), ambiguous: [...ambiguous].sort(), disagreed: [...disagreed].sort(),
+        unplaced, vouches, doubted: leftOut.sort(), unknownColumns: parsed.unknownColumns,
+        shortRows: parsed.unreadable.filter((u) => u.why === 'short').map((u) => u.line),
+        longRows: parsed.unreadable.filter((u) => u.why === 'long').map((u) => u.line),
+        noObjectRows: parsed.unreadable.filter((u) => u.why === 'no-name').length,
+        orphanFindings: orphaned,
+        outsideScope, keys: [...rowKeys],
+    };
+    if (!rowRefs.length)
+        return { ...counts, file: null, withFindings: 0, findings: 0, refusedRows: [] };
+    // A clean the FILE listed and a clean the PERSON asserted are two different
+    // claims, and a page showing them side by side has to be able to tell them
+    // apart. So every zero-finding row says which it is: `listed` when the file
+    // carries a checked-and-clean row for that object, `absent` when it is there
+    // only because somebody passed --absent-means-clean. A row WITH findings says
+    // nothing — the findings are its evidence.
+    const rows = findingsToRows(rowRefs, findings, input.project.type)
+        .map((r) => (r.findings.length ? r : { ...r, evidence: cleanRows.has(r.key) ? 'listed' : 'absent' }));
+    const res = writeRecord(input.joined, 'measurement', rows, input.by, {
+        source: { file: path.basename(input.filePath), sha256: createHash('sha256').update(bytes).digest('hex') },
+        ...(input.now ? { now: input.now } : {}), ...(input.rand ? { rand: input.rand } : {}),
+        extra: {
+            // A file carries no reliable variant: the name is written only when the
+            // person named one, and then it is their word, not the file's.
+            ...(input.variant ? { atcVariant: input.variant } : {}),
+            scope: label, basis: 'file',
+            // Only when it was really used: a flag CSPeach turned off must not be in
+            // the record as though it had counted.
+            ...(input.absentMeansClean && vouches ? { absentMeansClean: true } : {}),
+            coverage: { asked, measured: rowRefs.length, absent: asked - rowRefs.length, failed: 0, unsupported: 0, notRun: 0 },
+        },
+    });
+    // A row the baseline on disk no longer holds was never measured here either.
+    const refusedRows = res.refused;
+    const kept = rows.filter((r) => !refusedRows.includes(r.key));
+    return {
+        ...counts, measured: kept.length, failed: refusedRows.length, absent: asked - kept.length - refusedRows.length,
+        keys: kept.map((r) => r.key),
+        file: res.file, refusedRows,
+        withFindings: kept.filter((r) => r.findings.length > 0).length,
+        findings: kept.reduce((n, r) => n + r.findings.length, 0),
+    };
+}
+/** The bytes of the file the person named — once, with a size the terminal can hold. */
+function readFileBytes(filePath) {
+    if (/\.xls[xmb]?$/i.test(filePath))
+        throw new AtcFileError(EXCEL);
+    let size;
+    try {
+        size = fs.statSync(filePath).size;
+    }
+    catch {
+        throw new AtcFileError(`Cannot read ${filePath}`);
+    }
+    if (size > MAX_BYTES) {
+        throw new AtcFileError('This file is larger than 50 MB, so it was not read. An ATC result export is a list of findings, not a database dump.');
+    }
+    let bytes;
+    try {
+        bytes = fs.readFileSync(filePath);
+    }
+    catch {
+        throw new AtcFileError(`Cannot read ${filePath}`);
+    }
+    // UTF-16, before it is decoded into something that looks like a header row.
+    const head = bytes.subarray(0, SNIFF);
+    if ((bytes[0] === 0xff && bytes[1] === 0xfe) || (bytes[0] === 0xfe && bytes[1] === 0xff) || head.includes(0)) {
+        throw new AtcFileError(NOT_UTF8);
+    }
+    return bytes;
+}