@cspeach/cli 1.1.23 → 1.1.24

package/dist/lane/inputs.js

@@ -0,0 +1,459 @@
+/**
+ * App-lane inputs — everything the resolver needs that comes from outside it:
+ *
+ *   - system facts, probed (CVERS components) or declared (standalone profile);
+ *   - spec text (md/txt/docx/pdf/xlsx) and the evidence-quote check;
+ *   - the `[app-lane]` project pin in `.cspeach/conventions.toml`;
+ *   - the `## App lanes` toml block in the RAW standards file;
+ *   - the runtime-answer writer (the only writer of `[app-lane]`).
+ *
+ * Security: the spec path is contained (string + realpath), size-capped and
+ * denylisted; TOML is parsed, never evaluated, and only whitelisted values
+ * become a pin; errors never echo file contents; the runtime writer is atomic,
+ * touches only `[app-lane]`, and refuses symlinked targets.
+ */
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { createHash, randomBytes } from 'node:crypto';
+import { isDeepStrictEqual } from 'node:util';
+import toml from '@iarna/toml';
+import { resolveStandardsFile } from '../standards/standards-file.js';
+import { extractDocument } from '../tools/filesystem/extract-document.js';
+import { PathOutsideRootError } from '../tools/_filesystem-shared.js';
+import { findNormalised } from './signals.js';
+import { containSpecPath, SpecProtectedError } from './roots.js';
+// ── facts ──────────────────────────────────────────────────────────────────
+const UNKNOWN_FACTS = { source: 'unknown', tier: 'unknown', label: 'unknown' };
+function rel(components, key) {
+    const v = components[key];
+    if (v === undefined || v === '')
+        return undefined;
+    const n = Number.parseInt(v, 10);
+    return Number.isFinite(n) ? n : undefined;
+}
+/** Tier from CVERS components (probed). The label is the system-info release. */
+export function factsFromSystemInfo(info) {
+    if (!info)
+        return { ...UNKNOWN_FACTS };
+    const c = info.components ?? {};
+    const s4Raw = c['S4CORE'];
+    const appl = rel(c, 'SAP_APPL');
+    const basis = rel(c, 'SAP_BASIS');
+    let tier;
+    // S4CORE present means S/4, whatever the value; only a clean number ≥ 105 is 2020+.
+    if (typeof s4Raw === 'string' && s4Raw.trim() !== '') {
+        tier = /^\d+$/.test(s4Raw.trim()) && Number(s4Raw.trim()) >= 105 ? 's4-2020-plus' : 's4-before-2020';
+    }
+    else if (appl !== undefined)
+        tier = appl >= 617 ? 'ecc-ehp7-plus' : 'ecc-old';
+    else if (basis !== undefined)
+        tier = basis >= 740 ? 'netweaver-740-plus' : 'netweaver-old';
+    else
+        tier = 'unknown';
+    return { source: tier === 'unknown' ? 'unknown' : 'probed', tier, label: info.release };
+}
+/** Tier from the standalone profile (declared). Label `<platform> <release>`. */
+export function factsFromStandalone(p) {
+    if (!p)
+        return { ...UNKNOWN_FACTS };
+    const release = p.release ?? '';
+    let tier;
+    switch (p.platform) {
+        case 'S/4HANA':
+        case 'S/4HANA Cloud Private': {
+            const m = /(?<!\d)((?:19|20)\d{2})(?!\d)/.exec(release);
+            tier = !m ? 'unknown' : Number(m[1]) >= 2020 ? 's4-2020-plus' : 's4-before-2020';
+            break;
+        }
+        case 'ECC':
+            tier = /EHP\s*[78]\b/i.test(release) ? 'ecc-ehp7-plus' : 'ecc-old';
+            break;
+        default:
+            // S/4HANA Cloud Public, BTP ABAP Environment: outside slice 1 — unverified.
+            tier = 'unknown';
+    }
+    const r = release.trim();
+    const label = r.toLowerCase().startsWith(p.platform.toLowerCase()) ? r : `${p.platform} ${r}`.trim();
+    return { source: 'declared', tier, label };
+}
+// ── quotes ─────────────────────────────────────────────────────────────────
+/** Evidence-quote check. Delegates to the one canonical matcher. */
+export function findQuote(text, quote) {
+    return findNormalised(text, quote);
+}
+// ── spec text ──────────────────────────────────────────────────────────────
+const TEXT_MAX_BYTES = 2 * 1024 * 1024;
+const DOC_MAX_BYTES = 50 * 1024 * 1024;
+const DOC_MAX_PAGES = 150;
+const DOC_EXTS = new Set(['.pdf', '.docx', '.xlsx']);
+/**
+ * docx → turndown markdown: drop heading markers, drop unescaped `*` / `_`
+ * emphasis markers, and unescape turndown's backslash escapes (so
+ * `ZI\_SALES` becomes `ZI_SALES` again — literal underscores survive).
+ */
+function stripDocxMarkdown(md) {
+    return md
+        .replace(/^[ \t]*#{1,6}[ \t]+/gm, '')
+        .replace(/\\([\\`*_{}[\]()#+\-.!>~|=])|[*_]/g, (_m, esc) => esc ?? '');
+}
+/** pdf: drop the `[page N]` marker lines so a quote can span a page break. */
+function stripPdfMarkers(t) {
+    return t.replace(/^\[page \d+\]$/gm, '');
+}
+/** xlsx: drop the `## Sheet:` heading markers only — cell text is literal. */
+function stripXlsxMarkers(t) {
+    return t.replace(/^#{1,6}[ \t]+/gm, '');
+}
+/**
+ * I2 (final review) — the extension-aware strip that turned the extracted
+ * document into the spec text. Every string matched against that text (each
+ * evidence quote, the `ui_only_service` value) goes through the SAME function,
+ * so a quote copied from the read_document output (`ZI\_SALES`, `**bold**`)
+ * matches like a quote from a plain-text spec. Identity for .md / .txt.
+ */
+export function specNormaliser(ext) {
+    switch (ext.toLowerCase()) {
+        case '.docx': return stripDocxMarkdown;
+        case '.pdf': return stripPdfMarkers;
+        case '.xlsx': return stripXlsxMarkers;
+        default: return (s) => s;
+    }
+}
+/**
+ * Read the spec as plain text for the evidence-quote check. The path must
+ * stay inside `cwd` both as a string and after realpath (no symlink/junction
+ * escape). Errors name the path only — never the file contents.
+ */
+export async function readSpecText(cwd, specPath) {
+    // I3 — contained to cwd OR the workspace folder, as a string AND after
+    // realpath (a cwd reached through a junction still works; a link inside a
+    // root cannot escape), and refused when any root would denylist it.
+    let abs;
+    let real;
+    try {
+        ({ abs, real } = await containSpecPath(cwd, specPath));
+    }
+    catch (e) {
+        if (e instanceof PathOutsideRootError)
+            throw e;
+        if (e instanceof SpecProtectedError)
+            throw new Error(e.message);
+        if (e.code === 'ENOENT')
+            throw new Error(`spec file not found: ${specPath}`);
+        throw new Error(`spec file cannot be read: ${specPath}`);
+    }
+    const stat = await fs.stat(real);
+    if (!stat.isFile())
+        throw new Error(`spec path is not a file: ${specPath}`);
+    const ext = path.extname(real).toLowerCase();
+    if (DOC_EXTS.has(ext)) {
+        if (stat.size > DOC_MAX_BYTES)
+            throw new Error(`spec file is larger than 50 MB: ${specPath}`);
+        const buf = await fs.readFile(real);
+        let extracted;
+        try {
+            extracted = (await extractDocument(buf, ext, { maxPages: DOC_MAX_PAGES })).text;
+        }
+        catch (e) {
+            // Extractor messages are about structure (page counts, format), not content.
+            const why = e instanceof Error ? e.message.split('\n')[0].slice(0, 200) : 'unreadable document';
+            throw new Error(`spec file could not be read as ${ext}: ${specPath} (${why})`);
+        }
+        const normalise = specNormaliser(ext);
+        return { abs, text: normalise(extracted), sha256: sha256Hex(buf), normalise };
+    }
+    if (stat.size > TEXT_MAX_BYTES)
+        throw new Error(`spec file is larger than 2 MB: ${specPath}`);
+    const bytes = await fs.readFile(real);
+    return { abs, text: bytes.toString('utf8'), sha256: sha256Hex(bytes), normalise: specNormaliser(ext) };
+}
+/** sha256 of the raw spec bytes (recorded in the lane decision). */
+function sha256Hex(bytes) {
+    return createHash('sha256').update(bytes).digest('hex');
+}
+// ── [app-lane] parsing (shared by pin + standards) ─────────────────────────
+const BACKENDS = ['rap', 'cap', 'none', 'abap-report', 'segw'];
+const UIS = ['fiori-elements', 'freestyle', 'none'];
+const RUNTIMES = ['btp', 'own-server', 'none'];
+// A Map, not an object literal: keys come from the file (`constructor`, `__proto__`).
+const ALLOWED = new Map([['backend', BACKENDS], ['ui', UIS], ['runtime', RUNTIMES]]);
+const CONVENTIONS_REL = '.cspeach/conventions.toml';
+const CONVENTIONS_MAX_BYTES = 1024 * 1024;
+const HEADER_RE = /^\s*\[\s*(?:app-lane|"app-lane"|'app-lane')\s*\]\s*(?:#.*)?$/;
+const ANY_HEADER_RE = /^\s*\[/;
+/** 1-based line of `key =` inside the `[app-lane]` table, else the header line. */
+function keyLine(lines, key) {
+    const start = lines.findIndex((l) => HEADER_RE.test(l));
+    if (start < 0)
+        return undefined;
+    const k = key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); // key may come from the file
+    const keyRe = new RegExp(`^\\s*(?:${k}|"${k}"|'${k}')\\s*=`);
+    for (let i = start + 1; i < lines.length && !ANY_HEADER_RE.test(lines[i]); i++) {
+        if (keyRe.test(lines[i]))
+            return i + 1;
+    }
+    return start + 1;
+}
+/**
+ * Parse TOML text (never evaluated) and validate its `[app-lane]` table.
+ * `lineOffset` maps block-relative lines to file lines (standards block).
+ */
+function parseAppLane(text, lineOffset = 0) {
+    const at = (n) => (n === undefined ? '' : `line ${n + lineOffset}: `);
+    let doc;
+    try {
+        doc = toml.parse(text.replace(/^\uFEFF/, ''));
+    }
+    catch (e) {
+        const err = e;
+        // @iarna/toml appends " at row …" plus a source excerpt — keep only the reason.
+        const reason = String(err.message ?? 'parse error').split('\n')[0].split(' at row ')[0].slice(0, 160);
+        const line = typeof err.line === 'number' ? err.line + 1 : undefined;
+        return { error: `${at(line)}TOML parse error: ${reason}` };
+    }
+    if (!Object.prototype.hasOwnProperty.call(doc, 'app-lane'))
+        return {};
+    const lines = text.replace(/^\uFEFF/, '').split(/\r?\n/);
+    const table = doc['app-lane'];
+    if (table === null || typeof table !== 'object' || Array.isArray(table)) {
+        return { error: `${at(keyLine(lines, 'app-lane'))}app-lane must be a table` };
+    }
+    const pin = {};
+    for (const [key, value] of Object.entries(table)) {
+        const allowed = ALLOWED.get(key);
+        if (!allowed) {
+            return { error: `${at(keyLine(lines, key))}unknown key ${JSON.stringify(key.slice(0, 40))} (allowed: backend, ui, runtime)` };
+        }
+        if (typeof value !== 'string' || !allowed.includes(value)) {
+            return { error: `${at(keyLine(lines, key))}${key} must be one of ${allowed.join(', ')}` };
+        }
+        pin[key] = value;
+    }
+    return { pin: pin };
+}
+function toResult(o, file, source) {
+    if (o.error)
+        return { warning: `${file}: [app-lane] ignored — ${o.error}` };
+    if (!o.pin || Object.keys(o.pin).length === 0)
+        return {};
+    return { pin: { ...o.pin, source } };
+}
+/** The project pin: `[app-lane]` in `<cwd>/.cspeach/conventions.toml`. */
+export async function readLanePin(cwd) {
+    const file = path.join(cwd, '.cspeach', 'conventions.toml');
+    let text;
+    try {
+        const st = await fs.stat(file);
+        if (st.size > CONVENTIONS_MAX_BYTES) {
+            return { warning: `${CONVENTIONS_REL}: [app-lane] ignored — file is larger than 1 MB` };
+        }
+        text = await fs.readFile(file, 'utf8');
+    }
+    catch (e) {
+        if (e.code === 'ENOENT')
+            return {};
+        return { warning: `${CONVENTIONS_REL}: [app-lane] ignored — file cannot be read` };
+    }
+    return toResult(parseAppLane(text), CONVENTIONS_REL, CONVENTIONS_REL);
+}
+/**
+ * The standards-file lane block: the first ```toml fence after a
+ * `## App lanes` heading in the RAW standards file (not the 8000-char render).
+ */
+export async function readStandardsLane(cwd) {
+    const file = await resolveStandardsFile(cwd);
+    if (!file)
+        return {};
+    const lines = file.content.split(/\r?\n/);
+    const found = findLaneBlock(lines);
+    if (!found)
+        return {};
+    const { open, close } = found;
+    if (close < 0) {
+        return { warning: `${file.path}: [app-lane] ignored — line ${open + 1}: toml block is not closed` };
+    }
+    const block = lines.slice(open + 1, close).join('\n');
+    // resolveStandardsFile trims the content; recover leading lines so the
+    // reported line matches the file on disk.
+    const lead = await leadingLines(file.path);
+    return toResult(parseAppLane(block, open + 1 + lead), file.path, file.path);
+}
+const FENCE_OPEN_RE = /^[ \t]*(`{3,}|~{3,})[ \t]*([^`]*?)[ \t]*$/;
+const LANE_HEADING_RE = /^ {0,3}##[ \t]+App lanes[ \t]*#*[ \t]*$/i;
+/** ATX heading of level 1 or 2 — ends the `## App lanes` section. */
+const SECTION_END_RE = /^ {0,3}#{1,2}(?:[ \t]|$)/;
+/**
+ * Locate the first toml fence inside the `## App lanes` section. Headings
+ * and fences are only recognised OUTSIDE fenced code (```, ````, ~~~).
+ * Returns the opening/closing line indexes (close = -1 when unclosed), or
+ * null when there is no such section or block.
+ */
+function findLaneBlock(lines) {
+    let fence = null;
+    let inSection = false;
+    for (let i = 0; i < lines.length; i++) {
+        const l = lines[i];
+        if (fence) {
+            const m = /^[ \t]*(`{3,}|~{3,})[ \t]*$/.exec(l);
+            if (m && m[1][0] === fence.ch && m[1].length >= fence.len)
+                fence = null;
+            continue;
+        }
+        const open = FENCE_OPEN_RE.exec(l);
+        if (open) {
+            const marker = open[1];
+            const info = (open[2] ?? '').split(/[ \t]/)[0].toLowerCase();
+            if (inSection && info === 'toml') {
+                for (let j = i + 1; j < lines.length; j++) {
+                    const c = /^[ \t]*(`{3,}|~{3,})[ \t]*$/.exec(lines[j]);
+                    if (c && c[1][0] === marker[0] && c[1].length >= marker.length)
+                        return { open: i, close: j };
+                }
+                return { open: i, close: -1 };
+            }
+            fence = { ch: marker[0], len: marker.length };
+            continue;
+        }
+        if (!inSection) {
+            if (LANE_HEADING_RE.test(l))
+                inSection = true;
+        }
+        else if (SECTION_END_RE.test(l)) {
+            return null;
+        }
+    }
+    return null;
+}
+async function leadingLines(p) {
+    try {
+        const raw = await fs.readFile(p, 'utf8');
+        const lead = raw.slice(0, raw.length - raw.trimStart().length);
+        return (lead.match(/\n/g) ?? []).length;
+    }
+    catch {
+        return 0;
+    }
+}
+// ── runtime answer writer ──────────────────────────────────────────────────
+async function isSymlink(p) {
+    try {
+        return (await fs.lstat(p)).isSymbolicLink();
+    }
+    catch (e) {
+        if (e.code === 'ENOENT')
+            return false;
+        throw e;
+    }
+}
+/**
+ * Record the developer's runtime answer in `[app-lane]` of
+ * `.cspeach/conventions.toml`. Only the `runtime` line of that table is
+ * touched (or the table is appended); every other byte stays as it was.
+ * Written atomically (temp file in the same folder, then rename).
+ */
+export async function writeRuntimeAnswer(cwd, runtime) {
+    if (!RUNTIMES.includes(runtime)) {
+        throw new Error(`runtime must be one of ${RUNTIMES.join(', ')}`);
+    }
+    const dir = path.join(cwd, '.cspeach');
+    const file = path.join(dir, 'conventions.toml');
+    if (await isSymlink(dir))
+        throw new Error(`refusing to write: ${dir} is a symlink or junction`);
+    await fs.mkdir(dir, { recursive: true });
+    if (await isSymlink(file))
+        throw new Error(`refusing to write: ${CONVENTIONS_REL} is a symlink`);
+    // latin1 is a lossless byte↔char round-trip: every byte we do not edit is
+    // written back unchanged, even when the file is not valid UTF-8. The edit
+    // itself only matches and inserts ASCII.
+    let before = '';
+    try {
+        before = await fs.readFile(file, 'latin1');
+    }
+    catch (e) {
+        if (e.code !== 'ENOENT')
+            throw e;
+    }
+    const line = `runtime = "${runtime}"`;
+    const after = setRuntimeLine(before, line);
+    if (before.replace(/^\u00EF\u00BB\u00BF/, '').trim() !== '' && !parseBytes(before)) {
+        // Same reason + line the readLanePin warning shows; never file contents.
+        const why = parseAppLane(Buffer.from(before, 'latin1').toString('utf8')).error ?? 'TOML parse error';
+        throw new Error(`Could not save the runtime answer: ${CONVENTIONS_REL} has a TOML error — ${why}. ` +
+            `Fix that first, then add \`[app-lane] runtime = "${runtime}"\` by hand`);
+    }
+    if (!editIsSafe(before, after, runtime)) {
+        throw new Error(`Could not save the runtime answer to ${CONVENTIONS_REL} automatically — add \`[app-lane] runtime = "${runtime}"\` by hand`);
+    }
+    const tmp = path.join(dir, `.conventions.toml.${process.pid}.${randomBytes(6).toString('hex')}.tmp`);
+    try {
+        await fs.writeFile(tmp, after, { encoding: 'latin1', flag: 'wx' });
+        await fs.rename(tmp, file);
+    }
+    catch (e) {
+        await fs.rm(tmp, { force: true }).catch(() => undefined);
+        throw e;
+    }
+}
+/** Parse latin1-held bytes as UTF-8 TOML; null when it does not parse. */
+function parseBytes(latin1Text) {
+    try {
+        const utf8 = Buffer.from(latin1Text, 'latin1').toString('utf8').replace(/^\uFEFF/, '');
+        return toml.parse(utf8);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The text edit is line-based, so prove it did what we meant: the result
+ * parses, `[app-lane]` is a valid table whose runtime is the answer, and —
+ * when the original parsed — every other top-level key is deep-equal.
+ */
+function editIsSafe(before, after, runtime) {
+    const docAfter = parseBytes(after);
+    if (!docAfter)
+        return false;
+    const lane = docAfter['app-lane'];
+    if (lane === null || typeof lane !== 'object' || Array.isArray(lane))
+        return false;
+    if (lane.runtime !== runtime)
+        return false;
+    const check = parseAppLane(Buffer.from(after, 'latin1').toString('utf8'));
+    if (check.error || check.pin?.runtime !== runtime)
+        return false;
+    const docBefore = parseBytes(before);
+    if (docBefore) {
+        const keys = new Set([...Object.keys(docBefore), ...Object.keys(docAfter)]);
+        keys.delete('app-lane');
+        for (const k of keys) {
+            if (!isDeepStrictEqual(docBefore[k], docAfter[k]))
+                return false;
+        }
+    }
+    return true;
+}
+/** Pure text edit: replace/insert the runtime line inside `[app-lane]`, or append the table. */
+function setRuntimeLine(text, line) {
+    // Split keeping each line's own terminator so untouched lines are byte-identical.
+    const parts = text.match(/[^\n]*\n|[^\n]+$/g) ?? [];
+    const body = (p) => p.replace(/\r?\n$/, '');
+    // Line 1 may carry a UTF-8 BOM, which the latin1 view shows as EF BB BF chars.
+    const start = parts.findIndex((p, i) => HEADER_RE.test(i === 0 ? body(p).replace(/^\u00EF\u00BB\u00BF/, '') : body(p)));
+    if (start < 0) {
+        return `${text}\n[app-lane]\n${line}\n`;
+    }
+    const runtimeRe = /^\s*(?:runtime|"runtime"|'runtime')\s*=/;
+    for (let i = start + 1; i < parts.length && !ANY_HEADER_RE.test(body(parts[i])); i++) {
+        if (runtimeRe.test(body(parts[i]))) {
+            const eol = parts[i].slice(body(parts[i]).length) || '\n';
+            parts[i] = line + eol;
+            return parts.join('');
+        }
+    }
+    const header = parts[start];
+    const headerEol = header.slice(body(header).length);
+    if (headerEol === '')
+        parts[start] = header + '\n';
+    parts.splice(start + 1, 0, `${line}${headerEol || '\n'}`);
+    return parts.join('');
+}

package/dist/lane/paths.js

@@ -0,0 +1,21 @@
+// Leaf module: the lane decision file's path rule, shared by the store (write
+// and read) and the plan schema (`from.lane.path`), so the two cannot drift.
+// Imports nothing but node built-ins.
+import { posix } from 'node:path';
+export const LANE_DIR = '.cspeach/lane';
+/** A file directly in `.cspeach/lane/`, named `<letter-or-digit>[A-Za-z0-9_-]{0,127}.json`. */
+export const LANE_NAME_RE = /^\.cspeach\/lane\/([A-Za-z0-9][A-Za-z0-9_-]{0,127})\.json$/;
+/**
+ * Canonical workspace-relative form: `./.cspeach/lane/x.json` and
+ * `.cspeach//lane/x.json` both become `.cspeach/lane/x.json`. Backslashes and
+ * NUL are left alone so the name rule refuses them.
+ */
+export function canonicalLanePath(p) {
+    if (typeof p !== 'string' || p === '' || /[\\\u0000]/.test(p))
+        return p;
+    return posix.normalize(p);
+}
+/** True only for a canonical path the store would accept. */
+export function isLanePath(p) {
+    return typeof p === 'string' && !/[\\\u0000]/.test(p) && !p.split('/').includes('..') && LANE_NAME_RE.test(p);
+}

package/dist/lane/resolve.js

@@ -0,0 +1,109 @@
+export const BUILT_LANES = ['rap', 'cap', 'none', 'abap-report'];
+const CAP_KEYS = ['cap_external_users', 'cap_multi_system', 'cap_own_release_cycle', 'cap_ui_on_released_api'];
+/** Reason lines the lane card matches exactly (exported for card.ts only). */
+export const UNVERIFIED_REASON = 'System not checked: every built lane is shown unverified.';
+export const READ_ONLY_ANALYTICAL_REASON = 'Read-only but analytical: it stays an app (ALP), not a report.';
+export const DEFAULT_RAP_REASON = 'Default: on-stack RAP + Fiori Elements.';
+const SEGW_NOT_YET = 'not available yet — ECC and S/4 before 2020 come next; /abap-segw works directly today';
+export function allowedFor(tier) {
+    return tier === 's4-2020-plus' || tier === 'unknown' ? [...BUILT_LANES] : ['cap', 'none', 'abap-report'];
+}
+const strong = (s, k) => s[k].strength === 'strong';
+const truthy = (s, k) => s[k].value !== false && s[k].value !== null && s[k].value !== '';
+export function resolveLane(input) {
+    const { signals: s, facts } = input;
+    const allowed = allowedFor(facts.tier);
+    const crossedOut = [{ lane: 'segw', reason: SEGW_NOT_YET }, { lane: 'bopf-generated', reason: 'not available yet' }];
+    if (!allowed.includes('rap')) {
+        crossedOut.push({ lane: 'rap', reason: `needs S/4 2020: managed RAP + draft (this system: ${facts.label})` });
+    }
+    const crossOut = (lane, reason) => {
+        const hit = crossedOut.find((c) => c.lane === lane);
+        if (hit)
+            hit.reason = `${hit.reason}; ${reason}`;
+        else
+            crossedOut.push({ lane, reason: `${reason}, but it is not available on this system` });
+    };
+    const reasons = [];
+    reasons.push(facts.source === 'unknown'
+        ? UNVERIFIED_REASON
+        : `System: ${facts.label} (${facts.source === 'declared' ? 'declared, not probed' : 'probed'}).`);
+    let backend = null;
+    let decidedBy = 'rules';
+    let decidedByPath;
+    let fired = false;
+    for (const [who, pin] of [['pin', input.pin], ['standards', input.standards]]) {
+        if (backend || !pin?.backend)
+            continue;
+        if (allowed.includes(pin.backend)) {
+            backend = pin.backend;
+            decidedBy = who;
+            decidedByPath = pin.source;
+            fired = true;
+            reasons.push(`${who === 'pin' ? 'Project pin' : 'Standards file'} ${pin.source} sets the backend to ${pin.backend}.`);
+        }
+        else {
+            crossOut(pin.backend, `${who === 'pin' ? 'project pin' : 'standards file'} ${pin.source} asks for it`);
+        }
+    }
+    if (!backend && strong(s, 'ui_only_service') && allowed.includes('none')) {
+        backend = 'none';
+        fired = true;
+        reasons.push(`The spec asks only for a UI on a published service (${String(s.ui_only_service.value)}).`);
+    }
+    if (!backend && strong(s, 'report_only') && allowed.includes('abap-report')) {
+        if (strong(s, 'analytical') && allowed.includes('rap')) {
+            reasons.push(READ_ONLY_ANALYTICAL_REASON);
+        }
+        else {
+            backend = 'abap-report';
+            fired = true;
+            reasons.push('The spec asks for list output only, not an app.');
+        }
+    }
+    const strongCap = CAP_KEYS.filter((k) => strong(s, k));
+    if (!backend && strongCap.length > 0 && allowed.includes('cap')) {
+        backend = 'cap';
+        fired = true;
+        // M6 — a `"` inside a quote would close the quoted piece early: swap it for `'`.
+        reasons.push(`Side-by-side signal in the spec: ${strongCap.map((k) => `"${(s[k].evidence ?? k).replace(/"/g, "'")}"`).join('; ')}.`);
+    }
+    let noAppLane = false;
+    if (!backend) {
+        if (allowed.includes('rap')) {
+            backend = 'rap';
+            reasons.push(DEFAULT_RAP_REASON);
+        }
+        else {
+            noAppLane = true;
+            reasons.push(`No app lane is available on this system (${facts.label}).`);
+        }
+    }
+    const neutral = !fired && backend === 'rap';
+    const weakHints = neutral ? CAP_KEYS.filter((k) => truthy(s, k) && !strong(s, k)) : [];
+    // R2: a source's ui counts only when its backend was not crossed out, or it set only a ui.
+    const usable = (p) => (p && (!p.backend || allowed.includes(p.backend)) ? p : undefined);
+    const { ui, floorplan } = uiFor(backend, s, usable(input.pin)?.ui ?? usable(input.standards)?.ui);
+    const runtimeKnown = input.runtimeKnown || !!input.pin?.runtime || !!input.standards?.runtime;
+    return {
+        backend, ui, ...(floorplan ? { floorplan } : {}), decidedBy, ...(decidedByPath ? { decidedByPath } : {}),
+        neutral, noAppLane, needsRuntime: backend === 'cap' && !runtimeKnown,
+        allowed, crossedOut, reasons, weakHints, unverified: facts.tier === 'unknown', facts,
+    };
+}
+/**
+ * The UI rule (spec §5.2), run after the backend rule. Exported so the tool can
+ * re-run it after a developer switches the backend on the card.
+ */
+export function uiFor(backend, signals, pinUi) {
+    if (backend === 'abap-report' || backend === null)
+        return { ui: 'none' };
+    const feFloorplan = strong(signals, 'analytical') ? 'alp' : 'listReport';
+    if (pinUi)
+        return pinUi === 'fiori-elements' ? { ui: pinUi, floorplan: feFloorplan } : { ui: pinUi };
+    if (strong(signals, 'analytical'))
+        return { ui: 'fiori-elements', floorplan: 'alp' };
+    if (strong(signals, 'custom_ui') || backend === 'none')
+        return { ui: 'freestyle' };
+    return { ui: 'fiori-elements', floorplan: 'listReport' };
+}