boards-service.ts

import { isWindows, isOSX } from '@theia/core/lib/common/os';
import { naturalCompare } from './../utils';
import { Searchable } from './searchable';
import { Installable } from './installable';
import { ArduinoComponent } from './arduino-component';

export type AvailablePorts = Record<string, [Port, Array<Board>]>;
export namespace AvailablePorts {
  export function groupByProtocol(availablePorts: AvailablePorts): {
    serial: AvailablePorts;
    network: AvailablePorts;
    unknown: AvailablePorts;
  } {
    const serial: AvailablePorts = {};
    const network: AvailablePorts = {};
    const unknown: AvailablePorts = {};
    for (const key of Object.keys(availablePorts)) {
      const [port, boards] = availablePorts[key];
      const { protocol } = port;
      if (protocol === 'serial') {
        serial[key] = [port, boards];
      } else if (protocol === 'network') {
        network[key] = [port, boards];
      } else {
        unknown[key] = [port, boards];
      }
    }
    return { serial, network, unknown };
  }
}

export interface AttachedBoardsChangeEvent {
  readonly oldState: Readonly<{ boards: Board[]; ports: Port[] }>;
  readonly newState: Readonly<{ boards: Board[]; ports: Port[] }>;
}
export namespace AttachedBoardsChangeEvent {
  export function isEmpty(event: AttachedBoardsChangeEvent): boolean {
    const { detached, attached } = diff(event);
    return (
      !!detached.boards.length &&
      !!detached.ports.length &&
      !!attached.boards.length &&
      !!attached.ports.length
    );
  }

  export function toString(event: AttachedBoardsChangeEvent): string {
    const rows: string[] = [];
    if (!isEmpty(event)) {
      const { attached, detached } = diff(event);
      const visitedAttachedPorts: Port[] = [];
      const visitedDetachedPorts: Port[] = [];
      for (const board of attached.boards) {
        const port = board.port
          ? ` on ${Port.toString(board.port, { useLabel: true })}`
          : '';
        rows.push(` - Attached board: ${Board.toString(board)}${port}`);
        if (board.port) {
          visitedAttachedPorts.push(board.port);
        }
      }
      for (const board of detached.boards) {
        const port = board.port
          ? ` from ${Port.toString(board.port, { useLabel: true })}`
          : '';
        rows.push(` - Detached board: ${Board.toString(board)}${port}`);
        if (board.port) {
          visitedDetachedPorts.push(board.port);
        }
      }
      for (const port of attached.ports) {
        if (!visitedAttachedPorts.find((p) => Port.sameAs(port, p))) {
          rows.push(
            ` - New port is available on ${Port.toString(port, {
              useLabel: true,
            })}`
          );
        }
      }
      for (const port of detached.ports) {
        if (!visitedDetachedPorts.find((p) => Port.sameAs(port, p))) {
          rows.push(
            ` - Port is no longer available on ${Port.toString(port, {
              useLabel: true,
            })}`
          );
        }
      }
    }
    return rows.length ? rows.join('\n') : 'No changes.';
  }

  export function diff(event: AttachedBoardsChangeEvent): Readonly<{
    attached: {
      boards: Board[];
      ports: Port[];
    };
    detached: {
      boards: Board[];
      ports: Port[];
    };
  }> {
    // In `lefts` AND not in `rights`.
    const diff = <T>(
      lefts: T[],
      rights: T[],
      sameAs: (left: T, right: T) => boolean
    ) => {
      return lefts.filter(
        (left) => rights.findIndex((right) => sameAs(left, right)) === -1
      );
    };
    const { boards: newBoards } = event.newState;
    const { boards: oldBoards } = event.oldState;
    const { ports: newPorts } = event.newState;
    const { ports: oldPorts } = event.oldState;
    const boardSameAs = (left: Board, right: Board) =>
      Board.sameAs(left, right);
    const portSameAs = (left: Port, right: Port) => Port.sameAs(left, right);
    return {
      detached: {
        boards: diff(oldBoards, newBoards, boardSameAs),
        ports: diff(oldPorts, newPorts, portSameAs),
      },
      attached: {
        boards: diff(newBoards, oldBoards, boardSameAs),
        ports: diff(newPorts, oldPorts, portSameAs),
      },
    };
  }
}

export const BoardsServicePath = '/services/boards-service';
export const BoardsService = Symbol('BoardsService');
export interface BoardsService
  extends Installable<BoardsPackage>,
    Searchable<BoardsPackage> {
  /**
   * Deprecated. `getState` should be used to correctly map a board with a port.
   * @deprecated
   */
  getAttachedBoards(): Promise<Board[]>;
  /**
   * Deprecated. `getState` should be used to correctly map a board with a port.
   * @deprecated
   */
  getAvailablePorts(): Promise<Port[]>;
  getState(): Promise<AvailablePorts>;
  getBoardDetails(options: { fqbn: string }): Promise<BoardDetails | undefined>;
  getBoardPackage(options: { id: string }): Promise<BoardsPackage | undefined>;
  getContainerBoardPackage(options: {
    fqbn: string;
  }): Promise<BoardsPackage | undefined>;
  searchBoards({ query }: { query?: string }): Promise<BoardWithPackage[]>;
}

export interface Port {
  readonly address: string;
  readonly protocol: Port.Protocol;
  /**
   * Optional label for the protocol. For example: `Serial Port (USB)`.
   */
  readonly label?: string;
}
export namespace Port {
  export type Protocol = 'serial' | 'network' | 'unknown';
  export namespace Protocol {
    export function toProtocol(protocol: string | undefined): Protocol {
      if (protocol === 'serial') {
        return 'serial';
      } else if (protocol === 'network') {
        return 'network';
      } else {
        return 'unknown';
      }
    }
  }

  export function is(arg: any): arg is Port {
    return (
      !!arg &&
      'address' in arg &&
      typeof arg['address'] === 'string' &&
      'protocol' in arg &&
      typeof arg['protocol'] === 'string'
    );
  }

  export function toString(
    port: Port,
    options: { useLabel: boolean } = { useLabel: false }
  ): string {
    if (options.useLabel && port.label) {
      return `${port.address} ${port.label}`;
    }
    return port.address;
  }

  export function compare(left: Port, right: Port): number {
    // Board ports have higher priorities, they come first.
    if (isBoardPort(left) && !isBoardPort(right)) {
      return -1;
    }
    if (!isBoardPort(left) && isBoardPort(right)) {
      return 1;
    }
    let result = naturalCompare(
      left.protocol.toLocaleLowerCase(),
      right.protocol.toLocaleLowerCase()
    );
    if (result !== 0) {
      return result;
    }
    result = naturalCompare(left.address, right.address);
    if (result !== 0) {
      return result;
    }
    return naturalCompare(left.label || '', right.label || '');
  }

  export function equals(
    left: Port | undefined,
    right: Port | undefined
  ): boolean {
    if (left && right) {
      return (
        left.address === right.address &&
        left.protocol === right.protocol &&
        (left.label || '') === (right.label || '')
      );
    }
    return left === right;
  }

  // Based on: https://github.com/arduino/Arduino/blob/93581b03d723e55c60caedb4729ffc6ea808fe78/arduino-core/src/processing/app/SerialPortList.java#L48-L74
  export function isBoardPort(port: Port): boolean {
    const address = port.address.toLocaleLowerCase();
    if (isWindows) {
      // `COM1` seems to be the default serial port on Windows.
      return address !== 'COM1'.toLocaleLowerCase();
    }
    // On macOS and Linux, the port should start with `/dev/`.
    if (!address.startsWith('/dev/')) {
      return false;
    }
    if (isOSX) {
      // Example: `/dev/cu.usbmodem14401`
      if (/(tty|cu)\..*/i.test(address.substring('/dev/'.length))) {
        return [
          '/dev/cu.MALS',
          '/dev/cu.SOC',
          '/dev/cu.Bluetooth-Incoming-Port',
        ]
          .map((a) => a.toLocaleLowerCase())
          .every((a) => a !== address);
      }
    }

    // Example: `/dev/ttyACM0`
    if (
      /(ttyS|ttyUSB|ttyACM|ttyAMA|rfcomm|ttyO)[0-9]{1,3}/i.test(
        address.substring('/dev/'.length)
      )
    ) {
      // Default ports were `/dev/ttyS0` -> `/dev/ttyS31` on Ubuntu 16.04.2.
      if (address.startsWith('/dev/ttyS')) {
        const index = Number.parseInt(
          address.substring('/dev/ttyS'.length),
          10
        );
        if (!Number.isNaN(index) && 0 <= index && 31 >= index) {
          return false;
        }
      }
      return true;
    }

    return false;
  }

  export function sameAs(
    left: Port | undefined,
    right: Port | string | undefined
  ) {
    if (left && right) {
      if (left.protocol !== 'serial') {
        console.log(
          `Unexpected protocol for 'left' port: ${JSON.stringify(
            left
          )}. Ignoring 'protocol', comparing 'addresses' with ${JSON.stringify(
            right
          )}.`
        );
      }
      if (typeof right === 'string') {
        return left.address === right;
      }
      if (right.protocol !== 'serial') {
        console.log(
          `Unexpected protocol for 'right' port: ${JSON.stringify(
            right
          )}. Ignoring 'protocol', comparing 'addresses' with ${JSON.stringify(
            left
          )}.`
        );
      }
      return left.address === right.address;
    }
    return false;
  }
}

export interface BoardsPackage extends ArduinoComponent {
  readonly id: string;
  readonly boards: Board[];
}
export namespace BoardsPackage {
  export function equals(left: BoardsPackage, right: BoardsPackage): boolean {
    return left.id === right.id;
  }

  export function contains(
    selectedBoard: Board,
    { id, boards }: BoardsPackage
  ): boolean {
    if (boards.some((board) => Board.sameAs(board, selectedBoard))) {
      return true;
    }
    if (selectedBoard.fqbn) {
      const [platform, architecture] = selectedBoard.fqbn.split(':');
      if (platform && architecture) {
        return `${platform}:${architecture}` === id;
      }
    }
    return false;
  }
}

export interface Board {
  readonly name: string;
  readonly fqbn?: string;
  readonly port?: Port;
}

export interface BoardWithPackage extends Board {
  readonly packageName: string;
  readonly packageId: string;
}
export namespace BoardWithPackage {
  export function is(
    board: Board & Partial<{ packageName: string; packageId: string }>
  ): board is BoardWithPackage {
    return !!board.packageId && !!board.packageName;
  }
}

export interface InstalledBoardWithPackage extends BoardWithPackage {
  readonly fqbn: string;
}
export namespace InstalledBoardWithPackage {
  export function is(
    boardWithPackage: BoardWithPackage
  ): boardWithPackage is InstalledBoardWithPackage {
    return !!boardWithPackage.fqbn;
  }
}

export interface BoardDetails {
  readonly fqbn: string;
  readonly requiredTools: Tool[];
  readonly configOptions: ConfigOption[];
  readonly programmers: Programmer[];
  readonly debuggingSupported: boolean;
  readonly VID: string;
  readonly PID: string;
}

export interface Tool {
  readonly packager: string;
  readonly name: string;
  readonly version: Installable.Version;
}

export interface ConfigOption {
  readonly option: string;
  readonly label: string;
  readonly values: ConfigValue[];
}
export namespace ConfigOption {
  export function is(arg: any): arg is ConfigOption {
    return (
      !!arg &&
      'option' in arg &&
      'label' in arg &&
      'values' in arg &&
      typeof arg['option'] === 'string' &&
      typeof arg['label'] === 'string' &&
      Array.isArray(arg['values'])
    );
  }

  /**
   * Appends the configuration options to the `fqbn` argument.
   * Throws an error if the `fqbn` does not have the `segment(':'segment)*` format.
   * The provided output format is always segment(':'segment)*(':'option'='value(','option'='value)*)?
   */
  export function decorate(
    fqbn: string,
    configOptions: ConfigOption[]
  ): string {
    if (!configOptions.length) {
      return fqbn;
    }

    const toValue = (values: ConfigValue[]) => {
      const selectedValue = values.find(({ selected }) => selected);
      if (!selectedValue) {
        console.warn(
          `None of the config values was selected. Values were: ${JSON.stringify(
            values
          )}`
        );
        return undefined;
      }
      return selectedValue.value;
    };
    const options = configOptions
      .map(({ option, values }) => [option, toValue(values)])
      .filter(([, value]) => !!value)
      .map(([option, value]) => `${option}=${value}`)
      .join(',');

    return `${fqbn}:${options}`;
  }

  export class ConfigOptionError extends Error {
    constructor(message: string) {
      super(message);
      Object.setPrototypeOf(this, ConfigOptionError.prototype);
    }
  }

  export const LABEL_COMPARATOR = (left: ConfigOption, right: ConfigOption) =>
    naturalCompare(
      left.label.toLocaleLowerCase(),
      right.label.toLocaleLowerCase()
    );
}

export interface ConfigValue {
  readonly label: string;
  readonly value: string;
  readonly selected: boolean;
}

export interface Programmer {
  readonly name: string;
  readonly platform: string;
  readonly id: string;
}
export namespace Programmer {
  export function equals(
    left: Programmer | undefined,
    right: Programmer | undefined
  ): boolean {
    if (!left) {
      return !right;
    }
    if (!right) {
      return !left;
    }
    return (
      left.id === right.id &&
      left.name === right.name &&
      left.platform === right.platform
    );
  }
}

export namespace Board {
  export function is(board: any): board is Board {
    return !!board && 'name' in board;
  }

  export function equals(left: Board, right: Board): boolean {
    return left.name === right.name && left.fqbn === right.fqbn;
  }

  export function sameAs(left: Board, right: string | Board): boolean {
    // How to associate a selected board with one of the available cores: https://typefox.slack.com/archives/CJJHJCJSJ/p1571142327059200
    // 1. How to use the FQBN if any and infer the package ID from it: https://typefox.slack.com/archives/CJJHJCJSJ/p1571147549069100
    // 2. How to trim the `/Genuino` from the name: https://arduino.slack.com/archives/CJJHJCJSJ/p1571146951066800?thread_ts=1571142327.059200&cid=CJJHJCJSJ
    const other = typeof right === 'string' ? { name: right } : right;
    if (left.fqbn && other.fqbn) {
      return left.fqbn === other.fqbn;
    }
    return (
      left.name.replace('/Genuino', '') === other.name.replace('/Genuino', '')
    );
  }

  export function compare(left: Board, right: Board): number {
    let result = naturalCompare(left.name, right.name);
    if (result === 0) {
      result = naturalCompare(left.fqbn || '', right.fqbn || '');
    }
    return result;
  }

  export function installed(board: Board): boolean {
    return !!board.fqbn;
  }

  export function toString(
    board: Board,
    options: { useFqbn: boolean } = { useFqbn: true }
  ): string {
    const fqbn =
      options && options.useFqbn && board.fqbn ? ` [${board.fqbn}]` : '';
    return `${board.name}${fqbn}`;
  }

  export type Detailed = Board &
    Readonly<{
      selected: boolean;
      missing: boolean;
      packageName: string;
      packageId: string;
      details?: string;
    }>;
  export function decorateBoards(
    selectedBoard: Board | undefined,
    boards: Array<BoardWithPackage>
  ): Array<Detailed> {
    // Board names are not unique. We show the corresponding core name as a detail.
    // https://github.com/arduino/arduino-cli/pull/294#issuecomment-513764948
    const distinctBoardNames = new Map<string, number>();
    for (const { name } of boards) {
      const counter = distinctBoardNames.get(name) || 0;
      distinctBoardNames.set(name, counter + 1);
    }

    // Due to the non-unique board names, we have to check the package name as well.
    const selected = (board: BoardWithPackage) => {
      if (!!selectedBoard) {
        if (Board.equals(board, selectedBoard)) {
          if ('packageName' in selectedBoard) {
            return board.packageName === (selectedBoard as any).packageName;
          }
          if ('packageId' in selectedBoard) {
            return board.packageId === (selectedBoard as any).packageId;
          }
          return true;
        }
      }
      return false;
    };
    return boards.map((board) => ({
      ...board,
      details:
        (distinctBoardNames.get(board.name) || 0) > 1
          ? ` - ${board.packageName}`
          : undefined,
      selected: selected(board),
      missing: !installed(board),
    }));
  }
}