react-cheminfo 0.11.0 → 0.13.0

package/src/delimited/core/index.ts

@@ -1,11 +1,10 @@
 export type { DelimiterChoice, DelimiterId } from './delimiters.ts';
-export { DEFAULT_DELIMITER, DELIMITER_CHOICES } from './delimiters.ts';
+export {
+  DEFAULT_DELIMITER,
+  DELIMITER_CHOICES,
+  delimiterChoice,
+} from './delimiters.ts';
 export type { ReadDelimitedOptions } from './readDelimited.ts';
 export { detectDelimiter, readDelimited } from './readDelimited.ts';
-export type {
-  DelimitedColumn,
-  RowsToDelimitedOptions,
-} from './rowsToDelimited.ts';
-export { rowsToDelimited } from './rowsToDelimited.ts';
 export type { ToDelimitedOptions } from './toDelimited.ts';
-export { toDelimited } from './toDelimited.ts';
+export { escapeCell, toDelimited } from './toDelimited.ts';

package/src/delimited/ui/DelimitedTextDialog.tsx

@@ -26,7 +26,13 @@ export interface DelimitedTextDialogProps extends DelimitedTextPanelProps {
 export function DelimitedTextDialog(
   props: DelimitedTextDialogProps,
 ): ReactElement {
-  const { isOpen, onClose, title = 'Copy the table', ...panel } = props;
+  const {
+    isOpen,
+    onClose,
+    title = 'Copy the table',
+    className,
+    ...panel
+  } = props;
 
   return (
     <Dialog
@@ -34,6 +40,7 @@ export function DelimitedTextDialog(
       onClose={onClose}
       title={title}
       icon="th"
+      className={className}
       style={DIALOG_STYLE}
     >
       <DialogBody>

package/src/delimited/ui/DelimitedTextPanel.tsx

@@ -1,10 +1,14 @@
-import { Button, Callout, SegmentedControl } from '@blueprintjs/core';
+import { Button, Callout, Classes, SegmentedControl } from '@blueprintjs/core';
 import type { CSSProperties, ReactElement, ReactNode } from 'react';
 import { useMemo, useState } from 'react';
 
 import { CopyButton } from '../../clipboard/ui/CopyButton.tsx';
 import { downloadText } from '../../download/core/downloadText.ts';
 import { sanitizeFileName } from '../../download/core/sanitizeFileName.ts';
+import { formatInteger } from '../../format/core/numbers.ts';
+import { pluralize } from '../../format/core/words.ts';
+import { joinClassNames } from '../../shared/ui/joinClassNames.ts';
+import { TOKEN } from '../../tokens/core/familyTokens.ts';
 import type { DelimiterId } from '../core/delimiters.ts';
 import { DELIMITER_CHOICES, delimiterChoice } from '../core/delimiters.ts';
 import { toDelimited } from '../core/toDelimited.ts';
@@ -50,6 +54,11 @@ export interface DelimitedTextPanelProps {
    * @default 320
    */
   height?: number;
+  /**
+   * Class names added to the root element, after the component's own.
+   * @default undefined
+   */
+  className?: string;
 }
 
 /**
@@ -66,6 +75,7 @@ export function DelimitedTextPanel(
   props: DelimitedTextPanelProps,
 ): ReactElement {
   const {
+    className,
     rows,
     header,
     description,
@@ -84,7 +94,7 @@ export function DelimitedTextPanel(
   );
 
   return (
-    <div className="delimited-text">
+    <div className={joinClassNames('delimited-text', className)}>
       <Callout intent="primary" compact icon="info-sign">
         {description ?? defaultDescription(rows.length)}
       </Callout>
@@ -121,7 +131,7 @@ export function DelimitedTextPanel(
         value={text}
         spellCheck={false}
         aria-label={label}
-        className="bp6-input"
+        className={Classes.INPUT}
         style={{ ...TEXT_STYLE, height }}
         onFocus={(event) => event.currentTarget.select()}
       />
@@ -130,7 +140,7 @@ export function DelimitedTextPanel(
 }
 
 function defaultDescription(rowCount: number): string {
-  const rows = rowCount === 1 ? '1 row' : `${rowCount.toLocaleString()} rows`;
+  const rows = `${formatInteger(rowCount)} ${pluralize(rowCount, 'row')}`;
   return `${rows}, one per line. Copy them, then paste into a spreadsheet.`;
 }
 
@@ -143,7 +153,7 @@ const CONTROLS_STYLE = {
 } as const satisfies CSSProperties;
 
 const LABEL_STYLE = {
-  color: 'var(--text-muted, #5f6b7c)',
+  color: TOKEN.textMuted,
   fontSize: 12,
 } as const satisfies CSSProperties;
 

package/src/deploy/core/checkDeploy.ts

@@ -0,0 +1,84 @@
+import { readComposeFile } from './composeFile.ts';
+import { readEnvExample } from './envExample.ts';
+import type { CheckDeployOptions, DeployFile, DeployProblem } from './types.ts';
+import { DEPLOY_COMPOSE_FILES } from './types.ts';
+
+/**
+ * Every way a repository would break, or silently mis-deploy, under the
+ * server's global deploy script.
+ *
+ * The script is not in any repository: it pulls, builds and tags each build
+ * immutably, writes `IMAGE_TAG`, then keeps the new container only if Docker
+ * reports it healthy. So a repository has to hand it a selectable tag on every
+ * image we build, an `IMAGE_NAME` that names the package our own workflow
+ * publishes, a compose file that parses on a checkout with no `.env` yet, and a
+ * health probe to read. Each of those is invisible until a deploy, which is the
+ * worst moment to discover it — an `env_file` without `required: false` fails
+ * before a container starts, and an `IMAGE_NAME` off by a suffix pulls a
+ * package that was never published.
+ * @param files - The repository files to read, each with the path a report names it by.
+ * @param options - The package this repo publishes, and what it is allowed to ship.
+ * @returns Every problem, in file order and then in reading order.
+ */
+export function findDeployProblems(
+  files: readonly DeployFile[],
+  options: CheckDeployOptions = {},
+): DeployProblem[] {
+  const expected = options.composeFiles ?? DEPLOY_COMPOSE_FILES;
+  const rules = {
+    imageName: options.imageName,
+    foreignImages: options.foreignImages ?? [],
+    requireHealthcheck: options.requireHealthcheck ?? true,
+    healthcheckMarker: (
+      options.healthcheckMarker ?? 'healthcheck-ok'
+    ).toLowerCase(),
+    pinMarker: (options.pinMarker ?? 'pin-ok').toLowerCase(),
+  };
+
+  const byPath = new Map<string, string>();
+  for (const file of files) byPath.set(file.path, file.text);
+
+  const problems: DeployProblem[] = [];
+
+  for (const name of expected) {
+    const text = byPath.get(name);
+    if (text === undefined) {
+      problems.push({
+        file: name,
+        line: 0,
+        kind: 'missing-compose',
+        message: 'the deploy script found no such compose file',
+        hint: `commit ${name} at the repository root`,
+      });
+    } else {
+      readComposeFile(name, text, rules, problems);
+    }
+  }
+
+  const envExample = byPath.get('.env.example');
+  if (envExample === undefined) {
+    problems.push({
+      file: '.env.example',
+      line: 0,
+      kind: 'missing-env-example',
+      message: 'the operator has no template to copy to .env',
+      hint: 'commit .env.example declaring IMAGE_NAME, IMAGE_TAG and the COMPOSE_FILE choices',
+    });
+  } else {
+    readEnvExample(envExample, expected, problems);
+  }
+
+  const gitignore = byPath.get('.gitignore');
+  if (gitignore === undefined || !/^\s*\/?\.deploy\/?\s*$/m.test(gitignore)) {
+    problems.push({
+      file: '.gitignore',
+      line: 0,
+      kind: 'missing-deploy-ignore',
+      message:
+        '.deploy is not ignored, so the deploy script dirties the checkout it deploys',
+      hint: 'add a .deploy line to .gitignore',
+    });
+  }
+
+  return problems;
+}

package/src/deploy/core/composeDocument.ts

@@ -0,0 +1,181 @@
+import type { Document, Pair } from 'yaml';
+import {
+  LineCounter,
+  isAlias,
+  isMap,
+  isScalar,
+  isSeq,
+  parseDocument,
+} from 'yaml';
+
+/** One service of a compose file, with its merge keys applied. */
+export interface ComposeService {
+  /** The service's key under `services`. */
+  readonly name: string;
+  /** The line its key is written on, counting from 1. */
+  readonly line: number;
+  /** The first and the last line of its text, comments directly above it included. */
+  readonly lines: readonly [first: number, last: number];
+  /** The service as compose reads it: anchors resolved and `<<` merge keys applied. */
+  readonly value: Readonly<Record<string, unknown>>;
+  /**
+   * The line a key of the service is written on, following `<<` merge keys into
+   * the anchor that declares it.
+   * @param key - The key, such as `image`.
+   * @returns Its line, or the service's own line when the key is absent.
+   */
+  readonly lineOf: (key: string) => number;
+}
+
+/** A compose file, parsed. */
+interface ComposeDocument {
+  /** Its text, split into lines. */
+  readonly lines: readonly string[];
+  /** Its services, in the order they are written. */
+  readonly services: readonly ComposeService[];
+  /** Why it could not be read, when it could not; its services are then empty. */
+  readonly error?: { line: number; message: string };
+}
+
+interface ServiceKey {
+  pair: Pair;
+  name: string;
+  line: number;
+  first: number;
+}
+
+/**
+ * Parse a compose file the way compose reads it — any indentation, flow or
+ * block style, anchors, aliases and `<<` merge keys — keeping the line each
+ * service and key is written on, so a report can point at it.
+ * @param text - The content of the compose file.
+ * @returns Its services, or the error that stops it from parsing.
+ */
+export function readComposeDocument(text: string): ComposeDocument {
+  const lines = text.split('\n');
+  const lineCounter = new LineCounter();
+  const document = parseDocument(text, { lineCounter, merge: true });
+
+  const [parseError] = document.errors;
+  if (parseError !== undefined) {
+    return {
+      lines,
+      services: [],
+      error: {
+        line: parseError.linePos?.[0].line ?? 1,
+        message: firstLine(parseError.message),
+      },
+    };
+  }
+
+  let resolved: unknown;
+  try {
+    resolved = document.toJS();
+  } catch (error) {
+    return {
+      lines,
+      services: [],
+      error: { line: 1, message: firstLine(String(error)) },
+    };
+  }
+
+  const servicesNode = document.get('services', true);
+  if (!isMap(servicesNode)) return { lines, services: [] };
+  const servicesValue = recordOf(recordOf(resolved).services);
+  const lineAt = (offset: number) => lineCounter.linePos(offset).line;
+
+  const keys: ServiceKey[] = [];
+  for (const pair of servicesNode.items) {
+    if (!isScalar(pair.key) || isMergeKey(pair) || !pair.key.range) continue;
+    const { line, col } = lineCounter.linePos(pair.key.range[0]);
+    const previous = keys.at(-1)?.line ?? 0;
+    const first = firstLineOfService(lines, line, col, previous);
+    keys.push({ pair, name: String(pair.key.value), line, first });
+  }
+
+  const end = servicesNode.range?.[2] ?? text.length;
+  const lastLine = lineAt(Math.max(end - 1, 0));
+  const services: ComposeService[] = [];
+  for (let index = 0; index < keys.length; index++) {
+    const { pair, name, line, first } = keys[index] as ServiceKey;
+    const next = keys[index + 1];
+    services.push({
+      name,
+      line,
+      lines: [first, next === undefined ? lastLine : next.first - 1],
+      value: recordOf(servicesValue[name]),
+      lineOf: (key) => {
+        const found = findPair(pair.value, key, document)?.key;
+        return isScalar(found) && found.range ? lineAt(found.range[0]) : line;
+      },
+    });
+  }
+
+  return { lines, services };
+}
+
+/**
+ * Where a service's text starts: the comment block directly above its key
+ * belongs to it, unless the block is indented deeper than the key and so
+ * closes the service before.
+ * @param lines - The file, split into lines.
+ * @param line - The line of the service's key.
+ * @param column - The column of the key, counting from 1.
+ * @param previous - The line of the service key written before it, or 0.
+ * @returns The first line of the service.
+ */
+function firstLineOfService(
+  lines: readonly string[],
+  line: number,
+  column: number,
+  previous: number,
+): number {
+  let first = line;
+  while (first - 1 > previous) {
+    const comment = /^(?<indent>\s*)#/.exec(lines[first - 2] ?? '');
+    if (comment?.groups?.indent === undefined) break;
+    if (comment.groups.indent.length >= column) break;
+    first--;
+  }
+  return first;
+}
+
+function findPair(
+  node: unknown,
+  key: string,
+  document: Document,
+): Pair | undefined {
+  const map = isAlias(node) ? node.resolve(document) : node;
+  if (!isMap(map)) return undefined;
+  for (const pair of map.items) {
+    if (isScalar(pair.key) && pair.key.value === key) return pair;
+  }
+  for (const pair of map.items) {
+    if (!isMergeKey(pair)) continue;
+    const sources = isSeq(pair.value) ? pair.value.items : [pair.value];
+    for (const source of sources) {
+      const found = findPair(source, key, document);
+      if (found !== undefined) return found;
+    }
+  }
+  return undefined;
+}
+
+function isMergeKey(pair: Pair): boolean {
+  if (!isScalar(pair.key)) return false;
+  const { value } = pair.key;
+  return (
+    value === '<<' || (typeof value === 'symbol' && value.description === '<<')
+  );
+}
+
+function recordOf(value: unknown): Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : {};
+}
+
+function firstLine(message: string): string {
+  const [head = ''] = message.split('\n', 1);
+  return head.replace(/:$/, '');
+}

package/src/deploy/core/composeFile.ts

@@ -0,0 +1,195 @@
+import type { ComposeService } from './composeDocument.ts';
+import { readComposeDocument } from './composeDocument.ts';
+import { carriesMarker } from './markers.ts';
+import type { DeployProblem } from './types.ts';
+
+/** The rules a compose file is read against, resolved from the options. */
+interface ComposeRules {
+  /** The package this repository publishes, when it is checked. */
+  imageName: string | undefined;
+  /** Image prefixes built elsewhere, exempt from the tag rule. */
+  foreignImages: readonly string[];
+  /** Whether every service we build must declare a healthcheck. */
+  requireHealthcheck: boolean;
+  /** The lowercased marker that waives a service's healthcheck. */
+  healthcheckMarker: string;
+  /** The lowercased marker that waives an image's tag rules. */
+  pinMarker: string;
+}
+
+const OWN_IMAGE = /^\$\{IMAGE_NAME:-(?<name>[^}]+)\}:\$\{IMAGE_TAG:-[^}]+\}$/;
+
+/**
+ * Report what one compose file gets wrong: whether it parses, its images, its
+ * build contexts, its `env_file` entries and its healthchecks.
+ * @param name - The file, as a report names it.
+ * @param text - Its content.
+ * @param rules - What the file is checked against.
+ * @param problems - Where each problem found is appended, in reading order.
+ */
+export function readComposeFile(
+  name: string,
+  text: string,
+  rules: ComposeRules,
+  problems: DeployProblem[],
+): void {
+  const document = readComposeDocument(text);
+  if (document.error !== undefined) {
+    problems.push({
+      file: name,
+      line: document.error.line,
+      kind: 'invalid-compose',
+      message: `the file is not valid YAML: ${document.error.message}`,
+      hint: 'fix the YAML; docker compose config reports the same error',
+    });
+    return;
+  }
+
+  const found: DeployProblem[] = [];
+  const report = (
+    line: number,
+    problem: Pick<DeployProblem, 'kind' | 'message' | 'hint'>,
+  ) => found.push({ file: name, line, ...problem });
+
+  for (const service of document.services) {
+    const { image, build } = service.value;
+    const own =
+      typeof image === 'string'
+        ? OWN_IMAGE.exec(image)?.groups?.name
+        : undefined;
+
+    if (typeof image === 'string') {
+      const line = service.lineOf('image');
+      const problem =
+        own === undefined
+          ? foreignImageProblem(
+              image,
+              carriesMarker(document.lines, line - 1, rules.pinMarker),
+              rules,
+            )
+          : ownImageProblem(own, rules);
+      if (problem !== undefined) report(line, problem);
+    }
+
+    if (
+      'env_file' in service.value &&
+      requiresEnvFile(service.value.env_file)
+    ) {
+      report(service.lineOf('env_file'), {
+        kind: 'required-env-file',
+        message:
+          'env_file is required, so compose fails on a checkout that has no .env yet',
+        hint: 'write env_file: [{ path: .env, required: false }]',
+      });
+    }
+
+    if (own === undefined) continue;
+    if (build === undefined || build === null) {
+      report(service.line, {
+        kind: 'missing-build',
+        message: `service ${service.name} carries no build context, so it cannot be built from the checkout`,
+        hint: 'add build: . next to image:',
+      });
+    }
+    if (rules.requireHealthcheck && !isProbed(service, document.lines, rules)) {
+      report(service.line, {
+        kind: 'missing-healthcheck',
+        message: `service ${service.name} declares no healthcheck, so the deploy script cannot tell a broken container from a good one`,
+        hint: 'add a healthcheck probing the health endpoint',
+      });
+    }
+  }
+
+  problems.push(...found.toSorted((one, other) => one.line - other.line));
+}
+
+function ownImageProblem(
+  name: string,
+  rules: ComposeRules,
+): Pick<DeployProblem, 'kind' | 'message' | 'hint'> | undefined {
+  if (rules.imageName === undefined || name === rules.imageName) {
+    return undefined;
+  }
+  return {
+    kind: 'wrong-image-name',
+    message: `IMAGE_NAME defaults to ${name}, which this repository never publishes`,
+    hint: `default it to ${rules.imageName}`,
+  };
+}
+
+function foreignImageProblem(
+  value: string,
+  waived: boolean,
+  rules: ComposeRules,
+): Pick<DeployProblem, 'kind' | 'message' | 'hint'> | undefined {
+  // Somebody else builds it and this site tracks it on purpose.
+  if (waived) return undefined;
+
+  const bare = value.replace(/^docker\.io\/(?:library\/)?/, '');
+  const isForeign = rules.foreignImages.some(
+    (prefix) => value.startsWith(prefix) || bare.startsWith(prefix),
+  );
+  if (!isForeign) {
+    return {
+      kind: 'unpinned-image',
+      message: `image ${value} gives the deploy script no tag to select`,
+      hint: `write \${IMAGE_NAME:-ghcr.io/<owner>/<repo>}:\${IMAGE_TAG:-latest}`,
+    };
+  }
+  if (value.endsWith(':latest') || !value.includes(':')) {
+    return {
+      kind: 'floating-sidecar',
+      message: `third-party image ${value} is not pinned, so a rebuild is not reproducible`,
+      hint: 'pin the sidecar to an exact version',
+    };
+  }
+  return undefined;
+}
+
+/**
+ * Whether compose fails when a listed file is absent: a bare path is required,
+ * and so is a `{ path }` entry unless it says `required: false`.
+ * @param value - The service's `env_file`, in its short or long form.
+ * @returns True when any entry is required.
+ */
+function requiresEnvFile(value: unknown): boolean {
+  const entries: unknown[] = Array.isArray(value) ? value : [value];
+  for (const entry of entries) {
+    if (typeof entry !== 'object' || entry === null) return true;
+    if ((entry as { required?: unknown }).required !== false) return true;
+  }
+  return false;
+}
+
+/**
+ * Whether Docker will report the service's health: it declares a healthcheck
+ * that is not disabled, or a comment inside it carries the waiver.
+ * @param service - The service.
+ * @param lines - The file, split into lines.
+ * @param rules - The marker that waives the healthcheck.
+ * @returns True when the deploy script has a health to read, or needs none.
+ */
+function isProbed(
+  service: ComposeService,
+  lines: readonly string[],
+  rules: ComposeRules,
+): boolean {
+  const [first, last] = service.lines;
+  for (let line = first; line <= last; line++) {
+    if (
+      (lines[line - 1] ?? '').toLowerCase().includes(rules.healthcheckMarker)
+    ) {
+      return true;
+    }
+  }
+
+  const { healthcheck } = service.value;
+  if (typeof healthcheck !== 'object' || healthcheck === null) return false;
+  const { disable, test } = healthcheck as {
+    disable?: unknown;
+    test?: unknown;
+  };
+  if (disable === true) return false;
+  const command = Array.isArray(test) ? test[0] : test;
+  return command !== 'NONE';
+}

package/src/deploy/core/envExample.ts

@@ -0,0 +1,46 @@
+import type { DeployProblem } from './types.ts';
+
+/**
+ * Report what an `.env.example` fails to offer the operator: the two variables
+ * the deploy script rewrites, and one commented `COMPOSE_FILE` line per mode.
+ * @param text - The content of `.env.example`.
+ * @param expected - The compose files the repository is expected to ship.
+ * @param problems - Where each problem found is appended.
+ */
+export function readEnvExample(
+  text: string,
+  expected: readonly string[],
+  problems: DeployProblem[],
+): void {
+  for (const name of ['IMAGE_NAME', 'IMAGE_TAG']) {
+    if (!new RegExp(String.raw`^#?\s*${name}=`, 'm').test(text)) {
+      problems.push({
+        file: '.env.example',
+        line: 0,
+        kind: 'missing-env-example',
+        message: `${name} is not declared, so the operator cannot see what the deploy script sets`,
+        hint: `add a ${name}= line`,
+      });
+    }
+  }
+
+  for (const name of expected) {
+    const offered = new RegExp(
+      String.raw`^#\s*COMPOSE_FILE=${escapeRegExp(name)}(?:\s|$)`,
+      'm',
+    );
+    if (!offered.test(text)) {
+      problems.push({
+        file: '.env.example',
+        line: 0,
+        kind: 'missing-env-example',
+        message: `no commented COMPOSE_FILE line offers ${name}`,
+        hint: `add a commented COMPOSE_FILE=${name} line`,
+      });
+    }
+  }
+}
+
+function escapeRegExp(value: string): string {
+  return value.replaceAll(/[$()*+.?[\\\]^{|}]/g, String.raw`\$&`);
+}

package/src/deploy/core/index.ts

@@ -0,0 +1,8 @@
+export { findDeployProblems } from './checkDeploy.ts';
+export type {
+  CheckDeployOptions,
+  DeployFile,
+  DeployProblem,
+  DeployProblemKind,
+} from './types.ts';
+export { DEPLOY_COMPOSE_FILES } from './types.ts';

package/src/deploy/core/markers.ts

@@ -0,0 +1,21 @@
+/**
+ * Whether a line, or the comment block written directly above it, carries a
+ * marker — so a waiver can be explained in as many lines as it needs.
+ * @param lines - The file, split into lines.
+ * @param index - The line the marker would apply to.
+ * @param marker - The marker to look for, lowercased.
+ * @returns True when the line or its comment block carries it.
+ */
+export function carriesMarker(
+  lines: readonly string[],
+  index: number,
+  marker: string,
+): boolean {
+  if ((lines[index] ?? '').toLowerCase().includes(marker)) return true;
+  for (let above = index - 1; above >= 0; above--) {
+    const line = lines[above] ?? '';
+    if (!/^\s*#/.test(line)) return false;
+    if (line.toLowerCase().includes(marker)) return true;
+  }
+  return false;
+}