@cplieger/deadset-ts 8.0.0-dev.1 → 8.0.0-dev.11

package/src/dependencies.ts

@@ -42,17 +42,26 @@ import {
 import type { FindingPosition } from "./finding.ts";
 import type { Host } from "./host.ts";
 import { nodeKey, packageScope, type Inventory } from "./inventory.ts";
-import { scriptTokens } from "./manifest.ts";
-import { dirnamePath, isAbsolutePath, joinPath, relativePath, resolvePath } from "./paths.ts";
+import {
+  ancestors,
+  dirnamePath,
+  isAbsolutePath,
+  joinPath,
+  relativePath,
+  resolvePath,
+} from "./paths.ts";
 import type { DependencySection, Module } from "./ref.ts";
 import { UNANSWERED } from "./query.ts";
 import type { Handle, ProjectView } from "./session.ts";
 import { sourceFilesOf, type SourceFiles } from "./source-files.ts";
-import { workflowTokens } from "./workflow-steps.ts";
+import { manifestCommands } from "./manifest.ts";
+import { workflowCommands, workflowTokens } from "./workflow-steps.ts";
+import { bytewise } from "./text/compare.ts";
+import { isRecord } from "./json-document.ts";
+import { inInstalledPackages, INSTALLED_PACKAGES, MANIFEST, readDocument } from "./fs/manifest.ts";
+import { commandsOf, scriptTokens } from "./text/shell.ts";
 
-const MANIFEST = "package.json";
-const MODULES_DIR = "node_modules";
-const MODULES_SEGMENT = `/${MODULES_DIR}/`;
+const MODULES_SEGMENT = `/${INSTALLED_PACKAGES}/`;
 const TYPES_SCOPE = "@types/";
 
 /** A script token naming a JavaScript file by a path no expansion changes. */
@@ -160,25 +169,6 @@ export interface Dependencies {
   readonly heldBy: ReadonlyMap<string, readonly string[]>;
 }
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
-/** One JSON document's decoded value, or undefined where it cannot be read or parsed. */
-function readJSON(host: Host, path: string): { text: string; value: unknown } | undefined {
-  let text: string;
-  try {
-    text = host.readFile(path);
-  } catch {
-    return undefined;
-  }
-  try {
-    return { text, value: JSON.parse(text) };
-  } catch {
-    return undefined;
-  }
-}
-
 /**
  * The package a bare module specifier names: its first segment, or its first two
  * where it starts with a scope. A relative, absolute or scheme-prefixed specifier and
@@ -429,7 +419,7 @@ export function projectNeeds<Brand>(
   }
   for (const { strings, manifestDirs } of configuration.documents) {
     for (const manifestDir of manifestDirs) {
-      const names = declaredAt(joinPath(manifestDir, "package.json"));
+      const names = declaredAt(joinPath(manifestDir, MANIFEST));
       for (const text of strings) {
         use([PROJECT_OWNER], dependenciesNamed(text, names), joinPath(manifestDir, MANIFEST));
       }
@@ -444,7 +434,7 @@ export function projectNeeds<Brand>(
   );
   for (const { file, manifestDirs } of [...configuration.outside, ...ranFiles]) {
     for (const manifestDir of manifestDirs) {
-      const names = declaredAt(joinPath(manifestDir, "package.json"));
+      const names = declaredAt(joinPath(manifestDir, MANIFEST));
       for (const { text } of moduleStrings(file)) {
         use([PROJECT_OWNER], dependenciesNamed(text, names), joinPath(manifestDir, MANIFEST));
       }
@@ -467,8 +457,8 @@ function scriptRunFiles(
   const root = resolvePath(host.workingDirectory(), targetRoot);
   const dirs = new Set<string>([root]);
   for (const name of files.byName.keys()) {
-    for (let dir = dirnamePath(name); !dirs.has(dir); dir = dirnamePath(dir)) {
-      if (relativePath(root, dir) === undefined) {
+    for (const dir of ancestors(dirnamePath(name), root)) {
+      if (dirs.has(dir)) {
         break;
       }
       dirs.add(dir);
@@ -478,7 +468,7 @@ function scriptRunFiles(
     [root, new Set(workflowTokens(host, root))],
   ]);
   for (const dir of dirs) {
-    const read = readJSON(host, joinPath(dir, MANIFEST));
+    const read = readDocument(host, joinPath(dir, MANIFEST));
     if (read !== undefined && isRecord(read.value)) {
       const own = scriptTokensOf(read.value);
       tokens.set(dir, dir === root ? new Set([...own, ...(tokens.get(root) ?? [])]) : own);
@@ -491,7 +481,8 @@ function scriptRunFiles(
       const below = path === undefined ? undefined : relativePath(root, path);
       if (
         path !== undefined &&
-        below?.split("/").includes(MODULES_DIR) === false &&
+        below !== undefined &&
+        !inInstalledPackages(below) &&
         !files.byName.has(path) &&
         host.kindOf(path) === "file"
       ) {
@@ -797,8 +788,8 @@ function lineAndColumn(text: string, offset: number): { line: number; column: nu
 
 /** The installed copy of one dependency, read where the package manager puts it for the target. */
 function installedOf(host: Host, root: string, name: string): InstalledDependency | undefined {
-  for (let dir = root; ; dir = dirnamePath(dir)) {
-    const read = readJSON(host, joinPath(dir, MODULES_DIR, name, MANIFEST));
+  for (const dir of ancestors(root)) {
+    const read = readDocument(host, joinPath(dir, INSTALLED_PACKAGES, name, MANIFEST));
     if (read !== undefined && isRecord(read.value)) {
       const bin = read.value["bin"];
       const peers = read.value["peerDependencies"];
@@ -815,10 +806,8 @@ function installedOf(host: Host, root: string, name: string): InstalledDependenc
               : [],
       };
     }
-    if (dirnamePath(dir) === dir) {
-      return undefined;
-    }
   }
+  return undefined;
 }
 
 /** Every dependency the manifest text at `path` declares, in the order the text writes them. */
@@ -871,6 +860,88 @@ function scriptTokensOf(manifest: Record<string, unknown>): ReadonlySet<string>
   return found;
 }
 
+/**
+ * The runtime flags whose value is a module loaded before the entry, as `--flag value` or
+ * `--flag=value`: https://nodejs.org/api/cli.html#--importmodule,
+ * https://nodejs.org/api/cli.html#--experimental-loadermodule,
+ * https://nodejs.org/api/cli.html#-r---require-module
+ */
+const PRELOAD_FLAGS: ReadonlySet<string> = new Set([
+  "--experimental-loader",
+  "--import",
+  "--loader",
+  "--require",
+  "-r",
+]);
+
+/**
+ * The programs that pass a preload flag to the runtime they start: Node itself, and the
+ * runners that forward Node's flags or read the same `--require`:
+ * https://mochajs.org/#-require-module-r-module, https://tsx.is/node-enhancement,
+ * https://typestrong.org/ts-node/docs/options#require,
+ * https://github.com/remy/nodemon#running-non-node-scripts
+ */
+const PRELOADING_PROGRAMS: ReadonlySet<string> = new Set([
+  "mocha",
+  "node",
+  "nodemon",
+  "ts-node",
+  "tsx",
+]);
+
+/** The programs that run the command after them, and an environment assignment before it. */
+const LAUNCHERS: ReadonlySet<string> = new Set(["cross-env", "env", "npx"]);
+const ASSIGNMENT = /^[A-Za-z_][A-Za-z0-9_]*=/u;
+
+/**
+ * The packages `scripts` preload by a runtime flag's bare module specifier, a flag
+ * counting only in a command whose program passes it to the runtime, and for Node only
+ * before the script it runs, whose own arguments come after it.
+ */
+function preloadsOf(scripts: readonly string[]): ReadonlySet<string> {
+  const found = new Set<string>();
+  for (const script of scripts) {
+    for (const command of commandsOf(script)) {
+      const tokens = scriptTokens(command);
+      let at = 0;
+      while (
+        at < tokens.length &&
+        (ASSIGNMENT.test(tokens[at] ?? "") || LAUNCHERS.has(tokens[at] ?? ""))
+      ) {
+        at += 1;
+      }
+      const path = tokens[at] ?? "";
+      const program = path.slice(path.lastIndexOf("/") + 1);
+      if (!PRELOADING_PROGRAMS.has(program)) {
+        continue;
+      }
+      for (at += 1; at < tokens.length; at += 1) {
+        const token = tokens[at] ?? "";
+        if (!token.startsWith("-")) {
+          if (program === "node") {
+            break;
+          }
+          continue;
+        }
+        const equals = token.indexOf("=");
+        const flag = equals < 0 ? token : token.slice(0, equals);
+        if (!PRELOAD_FLAGS.has(flag)) {
+          continue;
+        }
+        if (equals < 0) {
+          at += 1;
+        }
+        const value = equals < 0 ? tokens[at] : token.slice(equals + 1);
+        const name = value === undefined ? undefined : packageOfSpecifier(value);
+        if (name !== undefined) {
+          found.add(name);
+        }
+      }
+    }
+  }
+  return found;
+}
+
 /** Whether a path below the target root lies in the directory `dir` below it, `""` being the root. */
 function isInside(path: string, dir: string): boolean {
   return dir === "" || path.startsWith(`${dir}/`);
@@ -966,22 +1037,29 @@ export function dependenciesOf(
     }
   }
   const workflow = new Set(workflowTokens(host, targetRoot));
+  const workflowPreloads = preloadsOf(workflowCommands(host, targetRoot));
   const declared: DeclaredDependency[] = [];
   const ran = new Set<string>();
   const peers = new Map<string, readonly string[]>();
   const uninstalledHere = new Set(nested);
   for (const [dir, path] of manifests) {
-    const read = readJSON(host, joinPath(dir, MANIFEST));
+    const read = readDocument(host, joinPath(dir, MANIFEST));
     if (read === undefined || !isRecord(read.value)) {
       continue;
     }
     const tokens = scriptTokensOf(read.value);
+    const preloads = preloadsOf(
+      manifestCommands(host, dir, read.value).map(({ command }) => command),
+    );
     for (const dependency of declaredIn(read.text, read.value, path, scopeOf(path))) {
       const found = installedOf(host, dir, dependency.name);
       if (found === undefined && uninstalledHere.has(dir)) {
         continue;
       }
       declared.push(dependency);
+      if (preloads.has(dependency.name) || workflowPreloads.has(dependency.name)) {
+        ran.add(declarationKey(dependency));
+      }
       if (found === undefined) {
         continue;
       }
@@ -1045,10 +1123,7 @@ export function dependenciesOf(
   const heldBy = new Map<string, readonly string[]>();
   for (const [key, held] of holders) {
     if (!live.has(key) && !ran.has(key)) {
-      heldBy.set(
-        key,
-        [...held].sort((a, b) => (a < b ? -1 : 1)),
-      );
+      heldBy.set(key, [...held].sort(bytewise));
     }
   }
   const users = new Map<string, number>();
@@ -1060,10 +1135,7 @@ export function dependenciesOf(
   for (const id of candidates) {
     const sole = [...(uses.get(id) ?? [])].filter((one) => users.get(one) === 1 && names.has(one));
     if (sole.length > 0) {
-      lastUses.set(
-        id,
-        sole.sort((a, b) => (a < b ? -1 : 1)),
-      );
+      lastUses.set(id, sole.sort(bytewise));
     }
   }
   const owners = new Map<string, Set<string>>();
@@ -1075,7 +1147,7 @@ export function dependenciesOf(
     }
   }
   const fileLastUses = new Map<string, string[]>();
-  for (const [one, held] of [...owners].sort(([a], [b]) => (a < b ? -1 : 1))) {
+  for (const [one, held] of [...owners].sort(([a], [b]) => bytewise(a, b))) {
     const paths = new Set([...held].map((owner) => owner.replace(/:\d+:\d+$/u, "")));
     const [path] = paths;
     if (paths.size === 1 && path !== undefined && path !== PROJECT_OWNER) {

package/src/edges.ts

@@ -5,15 +5,18 @@
  * pairing is a use, and the merge reads the two evaluations together.
  */
 
-import { ConfigError } from "./config.ts";
+import { EDGES_SCHEMA } from "./contract/config.generated.ts";
 import type { Finding } from "./finding.ts";
 import type { EdgeSide, EdgeSideName } from "./findings/boundary.ts";
+import { readTargetDocument } from "./fs/document.ts";
 import type { Host } from "./host.ts";
 import type { InventorySymbol } from "./inventory.ts";
-import { positionAt, walkDocument } from "./json-document.ts";
-import { joinPath } from "./paths.ts";
+import { dotted, placeIn, positionAt, readStrict, StrictJSONError } from "./json-document.ts";
 import { positionKey } from "./position.ts";
+import { firstRefusal } from "./schema.ts";
 import { isPartSubject } from "./suppress.ts";
+import { bytewise } from "./text/compare.ts";
+import { UsageError } from "./usage.ts";
 
 /** The name and the location the Contract fixes for the edges document. */
 export const EDGES_FILE = "deadset-edges.json";
@@ -21,155 +24,61 @@ export const EDGES_FILE = "deadset-edges.json";
 /** The language prefix of every reference this analyzer evaluates. */
 const OWN_PREFIX = "ts://";
 
-/** The closed key list of the document and of one edge. */
-const DOCUMENT_KEYS: ReadonlySet<string> = new Set(["description", "edges"]);
-const EDGE_KEYS: ReadonlySet<string> = new Set(["id", "because", "provides", "used_by"]);
-
-/** An edge identifier: solidus-separated segments of ASCII letters, digits, `_`, `.` and `-`. */
-const ID_FORM = /^[A-Za-z0-9_.-]+(?:\/[A-Za-z0-9_.-]+)*$/u;
-
-/** A reference naming one symbol of some language: `<language>://<scope>#<fragment>`. */
-const REFERENCE_FORM = /^[a-z][a-z0-9]*:\/\/[^ \t\r\n#]+#[^ \t\r\n]*$/u;
-
-const DOCUMENT_WANT = "an object carrying the edges array, and an optional description";
-const EDGE_WANT = "an edge naming id, provides and used_by, each a string, and an optional because";
-const ID_WANT =
-  "one or more solidus-separated segments of ASCII letters, digits, underscore, full stop and hyphen";
-const REFERENCE_WANT =
-  "a stable symbol reference naming one symbol exactly, <language>://<scope>#<fragment>";
-
 /** An edges document the Contract refuses: a malformed input, answered with the usage code. */
-class EdgesError extends ConfigError {
-  constructor(at: string, text: string, want: string) {
-    super("malformed", EDGES_FILE, `${at}: ${text}: want ${want}`);
+class EdgesError extends UsageError {
+  constructor(at: string, reason: string) {
+    super(`${at}: ${reason}`);
     this.name = "EdgesError";
   }
 }
 
-/**
- * Whether a reference carries a wildcard outside a quoted or a computed component, which
- * would name a set of symbols rather than one.
- */
-function carriesWildcard(ref: string): boolean {
-  let quoted = false;
-  let computed = false;
-  let escaped = false;
-  for (const char of ref) {
-    if (escaped) {
-      escaped = false;
-    } else if (quoted && char === "\\") {
-      escaped = true;
-    } else if (quoted) {
-      quoted = char !== "'";
-    } else if (computed) {
-      computed = char !== "]";
-    } else if (char === "'") {
-      quoted = true;
-    } else if (char === "[") {
-      computed = true;
-    } else if (char === "*") {
-      return true;
-    }
-  }
-  return false;
-}
-
-function isObject(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
-/** One edge, checked: the closed key list, the value types and the value forms. */
-function readEdge(value: unknown, at: string): { id: string; provides: string; usedBy: string } {
-  const refuse = (text: string, want: string): never => {
-    throw new EdgesError(at, text, want);
-  };
-  if (!isObject(value)) {
-    return refuse(JSON.stringify(value), EDGE_WANT);
-  }
-  for (const [key, held] of Object.entries(value)) {
-    if (!EDGE_KEYS.has(key) || typeof held !== "string") {
-      refuse(`the member ${JSON.stringify(key)} holding ${JSON.stringify(held)}`, EDGE_WANT);
-    }
-  }
-  const edge = value as Readonly<Record<string, string | undefined>>;
-  const id = edge["id"] ?? refuse("an edge naming no id", EDGE_WANT);
-  const provides = edge["provides"] ?? refuse("an edge naming no provides side", EDGE_WANT);
-  const usedBy = edge["used_by"] ?? refuse("an edge naming no used_by side", EDGE_WANT);
-  if (!ID_FORM.test(id)) {
-    refuse(JSON.stringify(id), ID_WANT);
-  }
-  for (const ref of [provides, usedBy]) {
-    if (!REFERENCE_FORM.test(ref) || carriesWildcard(ref)) {
-      refuse(JSON.stringify(ref), REFERENCE_WANT);
-    }
-  }
-  return { id, provides, usedBy };
-}
+/** The sides of one edge, in the order a reader yields them. */
+const SIDE_NAMES: readonly EdgeSideName[] = ["provides", "used_by"];
 
 /**
  * Every side of a declared edge that names a symbol of this language, in document order,
  * `provides` before `used_by` within an edge. An absent document declares no edge. The
- * document is strict JSON with a closed key list at both levels, and a defect in it is an
- * {@link EdgesError}.
+ * document is strict JSON held to the Contract's edges schema, and a defect in it is an
+ * {@link EdgesError} at the line and column of the edge it is in, where it is in one.
  */
 export function readEdgeSides(host: Host, targetRoot: string): readonly EdgeSide[] {
-  const file = joinPath(targetRoot, EDGES_FILE);
-  if (host.kindOf(file) === "absent") {
+  const text = readTargetDocument(host, targetRoot, EDGES_FILE);
+  if (text === undefined) {
     return [];
   }
-  const text = host.readFile(file);
-  let parsed: unknown;
+  let read;
   try {
-    parsed = JSON.parse(text);
+    read = readStrict(text, "edges");
   } catch (error: unknown) {
-    throw new EdgesError(
-      EDGES_FILE,
-      error instanceof Error ? error.message : String(error),
-      DOCUMENT_WANT,
-    );
-  }
-  if (!isObject(parsed)) {
-    throw new EdgesError(EDGES_FILE, JSON.stringify(parsed), DOCUMENT_WANT);
-  }
-  const walk = walkDocument(text, "edges");
-  if (walk.twice !== undefined) {
-    throw new EdgesError(
-      positionKey(positionAt(text, EDGES_FILE, walk.twice.offset)),
-      `the member ${JSON.stringify(walk.twice.name)} is written twice, so neither value is chosen`,
-      DOCUMENT_WANT,
-    );
+    if (!(error instanceof StrictJSONError)) {
+      throw error;
+    }
+    throw new EdgesError(positionKey(positionAt(text, EDGES_FILE, error.offset)), error.message);
   }
-  const unknown = Object.keys(parsed).find((key) => !DOCUMENT_KEYS.has(key));
-  const description = parsed["description"];
-  const edges = parsed["edges"];
-  if (
-    unknown !== undefined ||
-    (description !== undefined && typeof description !== "string") ||
-    !Array.isArray(edges)
-  ) {
-    throw new EdgesError(
-      EDGES_FILE,
-      unknown === undefined ? EDGES_FILE : `the member ${JSON.stringify(unknown)}`,
-      DOCUMENT_WANT,
-    );
+  const value = read.value;
+  const refused = firstRefusal(EDGES_SCHEMA, value);
+  if (refused !== undefined) {
+    const place = placeIn(value, refused.pointer, refused.member);
+    const offset = place.length > 1 ? read.starts.get(place[1] ?? "") : undefined;
+    const at =
+      offset === undefined ? EDGES_FILE : positionKey(positionAt(text, EDGES_FILE, offset));
+    const where = dotted(place);
+    throw new EdgesError(at, where === "" ? refused.reason : `${where}: ${refused.reason}`);
   }
+  const edges = (
+    value as { readonly edges: Readonly<Record<string, Record<EdgeSideName, string>>> }
+  ).edges;
 
   const sides: EdgeSide[] = [];
-  (edges as readonly unknown[]).forEach((value, index) => {
-    const offset = walk.starts[index];
-    const at =
-      offset === undefined ? EDGES_FILE : positionKey(positionAt(text, EDGES_FILE, offset));
-    const edge = readEdge(value, at);
-    const named: readonly [EdgeSideName, string][] = [
-      ["provides", edge.provides],
-      ["used_by", edge.usedBy],
-    ];
-    for (const [side, symbol] of named) {
-      if (symbol.startsWith(OWN_PREFIX)) {
-        sides.push({ edge: edge.id, side, symbol });
+  for (const id of read.starts.keys()) {
+    const edge = String(id);
+    for (const side of SIDE_NAMES) {
+      const symbol = edges[edge]?.[side];
+      if (symbol?.startsWith(OWN_PREFIX) === true) {
+        sides.push({ edge, side, symbol });
       }
     }
-  });
+  }
   return sides;
 }
 
@@ -190,14 +99,6 @@ interface Evaluated<F extends Finding> {
   readonly evaluations: readonly EdgeEvaluation<F>[];
 }
 
-/** Two strings ordered bytewise. */
-function compare(a: string, b: string): number {
-  if (a === b) {
-    return 0;
-  }
-  return a < b ? -1 : 1;
-}
-
 /**
  * Evaluates every declared side of this language over the run's findings. A side naming a
  * symbol the run enumerates nothing under is `absent`; otherwise it is evaluated once per
@@ -242,6 +143,6 @@ export function evaluateEdges<F extends Finding>(
       return { ...side, state: "dead", finding };
     });
   });
-  evaluations.sort((a, b) => compare(a.edge, b.edge) || compare(a.side, b.side));
+  evaluations.sort((a, b) => bytewise(a.edge, b.edge) || bytewise(a.side, b.side));
   return { findings: findings.filter((_finding, at) => !pending.has(at)), evaluations };
 }

package/src/element-access.ts

@@ -47,6 +47,7 @@ import { renderPosition } from "./position.ts";
 import { UNANSWERED } from "./query.ts";
 import type { Reference } from "./references.ts";
 import type { ProjectView } from "./session.ts";
+import { parenthesesRemoved } from "./unwrap.ts";
 
 type Use = "read" | "write" | "both";
 
@@ -93,13 +94,9 @@ function useOf(node: Node): Use {
   return "read";
 }
 
-function unwrapped(node: Expression): Expression {
-  return isParenthesizedExpression(node) ? unwrapped(node.expression) : node;
-}
-
 /** Whether an index is a literal the checker resolves to a member by its own text. */
 function isLiteralIndex(node: Expression): boolean {
-  const at = unwrapped(node);
+  const at = parenthesesRemoved(node);
   return isStringLiteral(at) || isNumericLiteral(at) || isNoSubstitutionTemplateLiteral(at);
 }
 
@@ -293,7 +290,7 @@ export function elementAccessReferences<Brand>(
   const parameterOf = new Map<Candidate, { callable: Callable; at: number }>();
   const byCallable = new Map<Identifier, Candidate[]>();
   for (const candidate of candidates) {
-    const index = unwrapped(candidate.access.argumentExpression);
+    const index = parenthesesRemoved(candidate.access.argumentExpression);
     const fn = isIdentifier(index) ? enclosingFunction(candidate.access) : undefined;
     const callable = fn === undefined ? undefined : callableOf(fn);
     if (callable === undefined || !isIdentifier(index)) {
@@ -353,7 +350,7 @@ export function elementAccessReferences<Brand>(
       continue;
     }
     // An object that is a parameter too is read as the argument each call passes there.
-    const object = unwrapped(candidate.access.expression);
+    const object = parenthesesRemoved(candidate.access.expression);
     const objectAt = isIdentifier(object)
       ? deferred.callable.parameters.findIndex(
           (parameter) => isIdentifier(parameter.name) && parameter.name.text === object.text,

package/src/entry-point-gaps.ts

@@ -8,6 +8,8 @@
  * one at a time: beside a finding, or in a report's declared gaps.
  */
 
+import { bytewise } from "./text/compare.ts";
+
 /** One declined entry-point convention. */
 export interface DeclinedConvention {
   /** The tool the convention belongs to, by the name of the package or service. */
@@ -323,16 +325,8 @@ const PARTLY_ENTERED: readonly DeclinedConvention[] = [
   },
 ];
 
-/** Two strings ordered bytewise. */
-function compare(a: string, b: string): number {
-  if (a === b) {
-    return 0;
-  }
-  return a < b ? -1 : 1;
-}
-
 /** Every declined entry-point convention, ordered by tool and then by convention. */
 export const DECLINED_CONVENTIONS: readonly DeclinedConvention[] = [
   ...UNREAD_TOOLS.map((tool) => ({ tool, convention: EVERY_CONVENTION, reason: UNREAD })),
   ...PARTLY_ENTERED,
-].sort((a, b) => compare(a.tool, b.tool) || compare(a.convention, b.convention));
+].sort((a, b) => bytewise(a.tool, b.tool) || bytewise(a.convention, b.convention));