@fnndsc/brasa 0.16.0 → 0.17.0

package/dist/builtins/net/query.csv.js

@@ -0,0 +1,267 @@
+/** The columns of a PACS answer's table, in reading order. */
+const CSV_COLUMNS = [
+    'MRN', 'PATIENT', 'SERVER', 'STATUS', 'STUDY', 'DATE',
+    'ACCESSION', 'MODALITY', 'SERIES', 'ANSWERED',
+];
+/**
+ * Quotes one cell.
+ *
+ * Everything is quoted, including numbers: a study description carrying a
+ * comma is the ordinary case, not the edge one, and a renderer that quotes
+ * only when it thinks it must is a renderer that will one day think wrong.
+ *
+ * @param value - The cell's value.
+ * @returns The quoted cell.
+ */
+function cell_quote(value) {
+    return `"${String(value ?? '').split('"').join('""')}"`;
+}
+/**
+ * Renders one answer as CSV.
+ *
+ * ANSWERED carries the ISO timestamp rather than `3 MONTHS AGO`: a
+ * spreadsheet sorts and subtracts dates, and the phrase a surface reads out
+ * is for a human glance, not for a column of data.
+ *
+ * @param model - The answer.
+ * @returns The CSV text, header row first.
+ */
+export function pacsAnswer_toCsv(model) {
+    const rows = [];
+    const patients = model.patients ?? [];
+    const studiesOf = (patient) => model.studies.filter((study) => study.patientId === patient.patientId
+        && (patient.server === undefined || study.server === undefined || study.server === patient.server));
+    const study_row = (study, facts) => [
+        facts.mrn,
+        study.patientName,
+        facts.server,
+        facts.status,
+        study.description,
+        study.date,
+        study.accession,
+        study.modalities,
+        String(study.series.length),
+        facts.answeredAt,
+    ];
+    if (patients.length > 0) {
+        for (const patient of patients) {
+            const server = patient.server ?? model.pacsName;
+            const answeredAt = patient.provenance?.answeredAt ?? '';
+            const owned = studiesOf(patient);
+            if (owned.length === 0) {
+                // The row that cannot be derived from studies, and the one an
+                // audit is usually about: a patient with no imaging, or one whose
+                // question could not be asked at all.
+                rows.push([
+                    patient.patientId, patient.patientName ?? '', server, patient.status,
+                    '', '', '', '', '0', answeredAt,
+                ]);
+                continue;
+            }
+            for (const study of owned) {
+                rows.push(study_row(study, {
+                    mrn: patient.patientId, server, status: patient.status, answeredAt,
+                }));
+            }
+        }
+    }
+    else {
+        for (const study of model.studies) {
+            rows.push(study_row(study, {
+                mrn: study.patientId,
+                server: study.server ?? model.pacsName,
+                status: 'found',
+                answeredAt: model.provenance?.answeredAt ?? '',
+            }));
+        }
+    }
+    const lines = [CSV_COLUMNS.map(cell_quote).join(',')];
+    for (const row of rows)
+        lines.push(row.map(cell_quote).join(','));
+    return `${lines.join('\n')}\n`;
+}
+/**
+ * Paths a file cannot be written to.
+ *
+ * These are providers — commands, processes, PACS queries — not storage. A
+ * write into one fails inside CUBE with a message about an upload, which
+ * tells an operator nothing about why the place they chose was never a
+ * place at all.
+ */
+const VIRTUAL_PREFIXES = ['/bin', '/usr', '/etc', '/proc', '/net'];
+/** How long to wait for a removed file to actually stop resolving. */
+const GONE_TIMEOUT_MS = 10_000;
+/** How often to ask whether it has. */
+const GONE_POLL_MS = 400;
+/**
+ * Whether a resolved path names a provider rather than storage.
+ *
+ * @param resolved - An absolute CFS path.
+ * @returns True when nothing can be written there.
+ */
+function path_isVirtual(resolved) {
+    return VIRTUAL_PREFIXES.some((prefix) => resolved === prefix || resolved.startsWith(`${prefix}/`));
+}
+/**
+ * Writes a rendered table into ChRIS storage.
+ *
+ * The path plumbing lives here rather than in the command: rendering a
+ * table and putting it somewhere are one job, and the command should read
+ * as the decision it makes rather than as the mechanics it performs.
+ *
+ * Imported where they are used — a CSV destination is a rare path, and
+ * pulling the session and storage stacks into this module's graph would
+ * load both for every query that never names one.
+ *
+ * The reason travels in the result rather than on the error stack, which
+ * keeps this module free of any runtime import — so the renderer beside it
+ * can be tested without loading the storage stack to do it.
+ *
+ * Four things are checked before anything is written, because a chooser
+ * can hand this a place that cannot be used:
+ *
+ * 1. A provider path is refused BY NAME. `/net/pacs/x.csv` fails inside
+ *    CUBE with a message about an upload, which says nothing about why.
+ * 2. A missing parent is created, and the result says so — an operator
+ *    reads what happened rather than discovering a folder later.
+ * 3. An existing file is never overwritten in silence: an audit table
+ *    quietly replacing another audit table is the workaround the
+ *    principles forbid, so it takes `--force` to say it twice.
+ * 4. The path that was actually written is returned, so a surface can
+ *    state it rather than repeat what the operator typed.
+ *
+ * @param csv - The rendered table.
+ * @param destination - Where the operator said to put it.
+ * @param force - True when the operator asked to overwrite.
+ * @returns The resolved path it landed on, or why it did not.
+ */
+export async function csvFile_write(csv, destination, force = false) {
+    try {
+        return await csvFile_put(csv, destination, force);
+    }
+    catch (error) {
+        // CUBE's failures arrive as thrown axios errors, and a throw out of a
+        // builtin does not stop at the command: under a daemon it takes the
+        // process, and every surface attached to it, with it. Measured — a
+        // re-upload over an existing path answers 500 and threw straight
+        // through this call. A store's bad day is a refusal, not an outage.
+        const why = error instanceof Error ? error.message : String(error);
+        return { ok: false, message: `${destination} could not be written: ${why}` };
+    }
+}
+/**
+ * The write itself, once the guard above owns the failures.
+ *
+ * @param csv - The rendered table.
+ * @param destination - Where the operator said to put it.
+ * @param force - True when the operator asked to replace what is there.
+ * @returns The resolved path it landed on, or why it did not.
+ */
+async function csvFile_put(csv, destination, force) {
+    const { errorStack } = await import('@fnndsc/cumin');
+    const { path_resolve, error_stripDebugPrefix } = await import('../utils.js');
+    const { files_create, files_delete, files_listAll, files_mkdir, files_path_isDirectory } = await import('@fnndsc/salsa');
+    const resolved = await path_resolve(destination);
+    if (path_isVirtual(resolved)) {
+        return {
+            ok: false,
+            message: `${resolved} is a provider, not storage: nothing can be written there`,
+        };
+    }
+    const cut = resolved.lastIndexOf('/');
+    const parent = cut <= 0 ? '/' : resolved.slice(0, cut);
+    const name = resolved.slice(cut + 1);
+    if (name === '')
+        return { ok: false, message: `${resolved} names a folder, not a file` };
+    /**
+     * Whether the folder already holds a file of that name.
+     *
+     * A null listing means the folder holds no files — `files_listAll`
+     * answers null both for an empty folder and for one that is not there,
+     * so existence is asked of `files_path_isDirectory` instead and never
+     * inferred from this.
+     */
+    const taken_find = async () => {
+        const listed = await files_listAll({ limit: 1000, offset: 0 }, 'files', parent);
+        const rows = listed?.tableData ?? [];
+        return rows.find((row) => {
+            const candidate = row.path ?? row.fname ?? '';
+            return candidate === resolved || candidate.slice(candidate.lastIndexOf('/') + 1) === name;
+        }) ?? null;
+    };
+    let created;
+    let replaced = false;
+    if (!await files_path_isDirectory(parent)) {
+        // The folder the operator named is not there. Making it is the ordinary
+        // thing to want, so it is made — and said, since a directory appearing
+        // without a word is the silent side effect this replaces.
+        if (!await files_mkdir(parent)) {
+            return { ok: false, message: `${parent} does not exist and could not be created` };
+        }
+        created = parent;
+    }
+    else {
+        const standing = await taken_find();
+        if (standing !== null && !force) {
+            // An audit table quietly replacing another audit table is the silent
+            // workaround the principles forbid: it takes saying so twice.
+            return { ok: false, message: `${resolved} already exists; pass --force to overwrite it` };
+        }
+        if (standing !== null) {
+            // Removed, then written. CUBE answers a re-upload of a path it
+            // already holds with a 500 — measured — so "overwrite" has to be
+            // spelled out rather than left to the store, and the removal is
+            // reported because a file disappearing unremarked is the silent act
+            // this whole check exists to prevent.
+            const id = standing.id;
+            if (id === undefined || !await files_delete(id, 'files', parent)) {
+                return { ok: false, message: `${resolved} exists and could not be replaced` };
+            }
+            // Deletion in CUBE is asynchronous — salsa's folder delete documents
+            // the same thing — and writing into a path the store still holds
+            // answers 500. So the removal is waited out rather than assumed,
+            // which is what turned a replacement into a lost file and an error.
+            let gone = false;
+            for (let waited = 0; waited < GONE_TIMEOUT_MS; waited += GONE_POLL_MS) {
+                if (await taken_find() === null) {
+                    gone = true;
+                    break;
+                }
+                await new Promise((settle) => {
+                    setTimeout(settle, GONE_POLL_MS);
+                });
+            }
+            if (!gone) {
+                return {
+                    ok: false,
+                    message: `${resolved} was removed but the store still holds it; nothing was written`,
+                };
+            }
+            replaced = true;
+        }
+    }
+    const written = await files_create(csv, resolved);
+    if (written) {
+        // Confirmed, not assumed. A create straight after making its folder has
+        // been seen to report success and leave nothing behind, and a table an
+        // operator believes they have is worse than one they know they lack.
+        if (await taken_find() === null) {
+            return {
+                ok: false,
+                message: `${resolved} was reported written but is not there; try again`,
+            };
+        }
+        return {
+            ok: true,
+            path: resolved,
+            ...(created === undefined ? {} : { created }),
+            ...(replaced ? { replaced: true } : {}),
+        };
+    }
+    const problem = errorStack.stack_pop();
+    // Stripped where it is read: a refusal an operator acts on should not
+    // arrive wearing the stack's debugging prefix.
+    const why = problem === undefined ? 'refused' : error_stripDebugPrefix(problem.message);
+    return { ok: false, message: `could not write ${resolved}: ${why}` };
+}
+//# sourceMappingURL=query.csv.js.map

package/dist/builtins/net/query.csv.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.csv.js","sourceRoot":"","sources":["../../../src/builtins/net/query.csv.ts"],"names":[],"mappings":"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"}

package/dist/builtins/net/query.d.ts

@@ -9,7 +9,7 @@
  * @module
  */
 import { PACSQueryDecodedResult, type CommandEnvelope } from '@fnndsc/cumin';
-import { type PacsQueryModel } from '@fnndsc/menu';
+import { type PacsProvenance, type PacsQueryModel } from '@fnndsc/menu';
 /**
  * Result of a successful query-create-and-wait operation.
  *
@@ -65,7 +65,34 @@ export declare function pacsQueryModel_build(decoded: PACSQueryDecodedResult, fa
     vfsPath: string;
     pacsName: string;
     expression: string;
+    /**
+     * Where this answer came from. Said once here so chell's sentence and
+     * argus's pill are the same fact rather than two guesses at it.
+     */
+    provenance?: PacsProvenance;
 }): PacsQueryModel;
+/**
+ * Resolves whatever names a PACS server into its canonical identifier.
+ *
+ * The context may hold a numeric id, a `--pacsserver` may be either, and
+ * CUBE files a query under the identifier. The index is keyed on what CUBE
+ * stores, so both the write and the lookup have to speak that.
+ *
+ * @param pacsserver - An id or an identifier.
+ * @returns The identifier, or the input unchanged when it cannot be resolved.
+ */
+export declare function pacsIdentifier_resolve(pacsserver: string): Promise<string>;
+/**
+ * Says how long ago something was answered, in the coarsest true unit.
+ *
+ * A replay states its age because mise refuses to decide staleness on the
+ * operator's behalf: an accession names a study that will not change, an
+ * MRN can gain one tomorrow, and no heuristic tells those apart reliably.
+ *
+ * @param at - An ISO timestamp.
+ * @returns A phrase like `3 months ago`, or null when the stamp is unusable.
+ */
+export declare function age_describe(at: string): string | null;
 /**
  * Creates a PACS query, waits for results, displays findings, and prints the VFS path.
  *

package/dist/builtins/net/query.fanout.d.ts

@@ -0,0 +1,92 @@
+/**
+ * @file A PACS question that names several patients is several questions.
+ *
+ * A PACS will not match a list. `PatientID:4356325\4433255` — the DICOM
+ * multi-value form — returns nothing from PACSDCM, and the standard agrees:
+ * *List of UID Matching* is defined only for attributes whose VR is `UI`,
+ * and `PatientID` is `LO`. So two hundred MRNs is two hundred C-FINDs. The
+ * fan-out is forced, not chosen.
+ *
+ * This module is the arithmetic of that: reading a cohort out of what the
+ * operator typed (or out of a file in CFS), turning multi-valued terms into
+ * the individual questions they stand for, and refusing by name when the
+ * cross-product would launch hundreds.
+ *
+ * @module
+ */
+import { type Result } from '@fnndsc/cumin';
+/** The DICOM key a cohort is expressed in. */
+export declare const PATIENT_KEY: string;
+/**
+ * The most questions one inline expression may stand for.
+ *
+ * A handful of MRNs typed on a line is the case this serves; a real cohort
+ * belongs in `--patients`, which is why the refusal names that flag. The
+ * cross-product of several multi-valued terms grows fast enough that a typo
+ * could otherwise launch hundreds of C-FINDs at a shared clinical system.
+ */
+export declare const QUERY_INLINE_FANOUT_MAX: number;
+/**
+ * The most questions `--patients` may stand for.
+ *
+ * Deliberately generous — a two-hundred-MRN audit is the point of the flag —
+ * but not unbounded: a file of the wrong kind should be refused rather than
+ * walked.
+ */
+export declare const QUERY_COHORT_MAX: number;
+/**
+ * Parses a query expression into terms, each of which may carry several
+ * values.
+ *
+ * The operator's own syntax, accepted as written:
+ *
+ * ```
+ * PatientID:1234,4532,6654          one key, three values  → three questions
+ * PatientID:1234,StudyDate:20240101 two keys, one value each → one question
+ * ```
+ *
+ * There is no ambiguity to resolve: every genuine term carries a colon, so a
+ * bare segment can only be another value for the key before it.
+ *
+ * @param expr - The expression as typed.
+ * @returns Each key with its values in order, or null when the expression is
+ *   malformed.
+ */
+export declare function queryTerms_parse(expr: string): Record<string, string[]> | null;
+/**
+ * Expands multi-valued terms into the individual questions they stand for.
+ *
+ * Several multi-valued keys fan out over their cross-product, in the order
+ * the keys were written, so the questions come out in the order an operator
+ * would have listed them.
+ *
+ * @param terms - Parsed terms.
+ * @returns One criteria record per question.
+ */
+export declare function queryTerms_expand(terms: Record<string, string[]>): Array<Record<string, string>>;
+/**
+ * Reads a `--patients` value: MRNs listed inline, or `@` and a CFS path.
+ *
+ * The file is read through the session's own CFS path, never the engine's
+ * host filesystem, so the flag behaves identically from a local shell, a
+ * remote shell and a browser — and a list sitting on somebody's own machine
+ * reaches it through `upload`, which is the gated door, rather than through
+ * a second ungated one.
+ *
+ * One MRN per line; blank lines and `#` comments are ignored. An inline
+ * value is comma-separated, which is what a handful of MRNs looks like.
+ *
+ * @param value - The flag's value.
+ * @returns The MRNs in the order given, or a failure with the reason on the
+ *   error stack.
+ */
+export declare function patients_read(value: string): Promise<Result<string[]>>;
+/**
+ * Guards a fan-out's size, refusing by name rather than launching it.
+ *
+ * @param count - How many questions the expansion came to.
+ * @param limit - The ceiling that applies to how they were asked.
+ * @returns True when the fan-out may proceed; otherwise the reason is on the
+ *   error stack.
+ */
+export declare function fanout_permit(count: number, limit: number): boolean;

package/dist/builtins/net/query.fanout.js

@@ -0,0 +1,171 @@
+/**
+ * @file A PACS question that names several patients is several questions.
+ *
+ * A PACS will not match a list. `PatientID:4356325\4433255` — the DICOM
+ * multi-value form — returns nothing from PACSDCM, and the standard agrees:
+ * *List of UID Matching* is defined only for attributes whose VR is `UI`,
+ * and `PatientID` is `LO`. So two hundred MRNs is two hundred C-FINDs. The
+ * fan-out is forced, not chosen.
+ *
+ * This module is the arithmetic of that: reading a cohort out of what the
+ * operator typed (or out of a file in CFS), turning multi-valued terms into
+ * the individual questions they stand for, and refusing by name when the
+ * cross-product would launch hundreds.
+ *
+ * @module
+ */
+import { Err, Ok, errorStack } from '@fnndsc/cumin';
+/** The DICOM key a cohort is expressed in. */
+export const PATIENT_KEY = 'PatientID';
+/**
+ * The most questions one inline expression may stand for.
+ *
+ * A handful of MRNs typed on a line is the case this serves; a real cohort
+ * belongs in `--patients`, which is why the refusal names that flag. The
+ * cross-product of several multi-valued terms grows fast enough that a typo
+ * could otherwise launch hundreds of C-FINDs at a shared clinical system.
+ */
+export const QUERY_INLINE_FANOUT_MAX = 32;
+/**
+ * The most questions `--patients` may stand for.
+ *
+ * Deliberately generous — a two-hundred-MRN audit is the point of the flag —
+ * but not unbounded: a file of the wrong kind should be refused rather than
+ * walked.
+ */
+export const QUERY_COHORT_MAX = 500;
+/** Marks a `--patients` value as naming a file rather than listing MRNs. */
+const FILE_SIGIL = '@';
+/**
+ * Parses a query expression into terms, each of which may carry several
+ * values.
+ *
+ * The operator's own syntax, accepted as written:
+ *
+ * ```
+ * PatientID:1234,4532,6654          one key, three values  → three questions
+ * PatientID:1234,StudyDate:20240101 two keys, one value each → one question
+ * ```
+ *
+ * There is no ambiguity to resolve: every genuine term carries a colon, so a
+ * bare segment can only be another value for the key before it.
+ *
+ * @param expr - The expression as typed.
+ * @returns Each key with its values in order, or null when the expression is
+ *   malformed.
+ */
+export function queryTerms_parse(expr) {
+    const terms = {};
+    let current = null;
+    for (const raw of expr.split(',')) {
+        const part = raw.trim();
+        if (part === '')
+            return null;
+        const colon = part.indexOf(':');
+        if (colon < 1) {
+            // A bare segment before any key names nothing.
+            if (current === null)
+                return null;
+            terms[current].push(part);
+            continue;
+        }
+        const key = part.slice(0, colon).trim();
+        const value = part.slice(colon + 1).trim();
+        if (key === '' || value === '')
+            return null;
+        current = key;
+        terms[key] = [...(terms[key] ?? []), value];
+    }
+    return Object.keys(terms).length > 0 ? terms : null;
+}
+/**
+ * Expands multi-valued terms into the individual questions they stand for.
+ *
+ * Several multi-valued keys fan out over their cross-product, in the order
+ * the keys were written, so the questions come out in the order an operator
+ * would have listed them.
+ *
+ * @param terms - Parsed terms.
+ * @returns One criteria record per question.
+ */
+export function queryTerms_expand(terms) {
+    let expanded = [{}];
+    for (const [key, values] of Object.entries(terms)) {
+        const grown = [];
+        for (const partial of expanded) {
+            for (const value of values)
+                grown.push({ ...partial, [key]: value });
+        }
+        expanded = grown;
+    }
+    return expanded;
+}
+/**
+ * Reads a `--patients` value: MRNs listed inline, or `@` and a CFS path.
+ *
+ * The file is read through the session's own CFS path, never the engine's
+ * host filesystem, so the flag behaves identically from a local shell, a
+ * remote shell and a browser — and a list sitting on somebody's own machine
+ * reaches it through `upload`, which is the gated door, rather than through
+ * a second ungated one.
+ *
+ * One MRN per line; blank lines and `#` comments are ignored. An inline
+ * value is comma-separated, which is what a handful of MRNs looks like.
+ *
+ * @param value - The flag's value.
+ * @returns The MRNs in the order given, or a failure with the reason on the
+ *   error stack.
+ */
+export async function patients_read(value) {
+    if (!value.startsWith(FILE_SIGIL)) {
+        const listed = value.split(',')
+            .map((entry) => entry.trim())
+            .filter((entry) => entry !== '');
+        if (listed.length === 0) {
+            errorStack.stack_push('error', 'query: --patients names no patients.');
+            return Err();
+        }
+        return Ok(listed);
+    }
+    const named = value.slice(FILE_SIGIL.length);
+    if (named === '') {
+        errorStack.stack_push('error', 'query: --patients @ names no file.');
+        return Err();
+    }
+    // Imported where they are used: a cohort file is a rare path, and
+    // pulling the session and storage stacks into this module's graph would
+    // load both for every query that never names one.
+    const { path_resolve } = await import('../utils.js');
+    const { fileContent_get } = await import('@fnndsc/salsa');
+    const resolved = await path_resolve(named);
+    const content = await fileContent_get(resolved);
+    if (!content.ok) {
+        const problem = errorStack.stack_pop();
+        errorStack.stack_push('error', `query: cannot read ${resolved}: ${problem?.message ?? 'unreadable'}`);
+        return Err();
+    }
+    const mrns = content.value
+        .split('\n')
+        .map((line) => line.trim())
+        .filter((line) => line !== '' && !line.startsWith('#'));
+    if (mrns.length === 0) {
+        errorStack.stack_push('error', `query: ${resolved} lists no patients.`);
+        return Err();
+    }
+    return Ok(mrns);
+}
+/**
+ * Guards a fan-out's size, refusing by name rather than launching it.
+ *
+ * @param count - How many questions the expansion came to.
+ * @param limit - The ceiling that applies to how they were asked.
+ * @returns True when the fan-out may proceed; otherwise the reason is on the
+ *   error stack.
+ */
+export function fanout_permit(count, limit) {
+    if (count <= limit)
+        return true;
+    errorStack.stack_push('error', `query: refusing: ${count} queries; use --patients with a file, or narrow the terms.`);
+    return false;
+}
+//# sourceMappingURL=query.fanout.js.map

package/dist/builtins/net/query.fanout.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.fanout.js","sourceRoot":"","sources":["../../../src/builtins/net/query.fanout.ts"],"names":[],"mappings":"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"}