@ohos-ports/nx 23.3.0-beta.3 → 24.0.2-beta.0

package/dist/src/utils/owned-private-dir.js

@@ -2,14 +2,22 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DirectoryRefusedError = void 0;
 exports.describeRefusal = describeRefusal;
-exports.remedyFor = remedyFor;
 exports.canonicalDir = canonicalDir;
 exports.isSafeSharedRoot = isSafeSharedRoot;
-exports.isPeerWritable = isPeerWritable;
 exports.ensureSafeSharedRoot = ensureSafeSharedRoot;
 exports.isOwnedRealDirectory = isOwnedRealDirectory;
 exports.getUserSegment = getUserSegment;
 exports.ensureOwnedPrivateDir = ensureOwnedPrivateDir;
+/**
+ * Directory guards for Nx's runtime state: create a directory only when it is
+ * ours and unreachable by other users on this machine.
+ *
+ * `native/utils/owned_dir.rs` implements the same rules and must change with
+ * this file. This copy exists because the native binding loader has to place
+ * and lock down the `.node` before Rust can be called, and `cache-directory.ts`,
+ * `git-utils.ts` and `nx-tmp-dir.ts` share it. Node builtins only, for the
+ * loader's sake.
+ */
 const node_fs_1 = require("node:fs");
 const node_os_1 = require("node:os");
 const node_path_1 = require("node:path");
@@ -56,42 +64,6 @@ function describeRefusal(r) {
         }
     }
 }
-/** Single-quoted for a shell, so a path with a space or quote survives a paste. */
-const shellQuote = (s) => `'${s.replace(/'/g, `'\\''`)}'`;
-/** What the user can do about a refusal, or `undefined` when there is nothing. */
-function remedyFor(r) {
-    switch (r.kind) {
-        case 'not-a-directory':
-            return r.symlink
-                ? `${r.dir} is a symlink where Nx expects a directory. If you did not create it, treat it as hostile: remove the link itself (not what it points at) and run the command again.`
-                : undefined;
-        case 'foreign-owner':
-            return `${r.dir} belongs to another user on this machine, so Nx cannot keep its own directory there. Set NX_SOCKET_DIR to a short directory your user owns, or move it aside — which you can do yourself if you own the directory it sits in, and otherwise needs an administrator.`;
-        case 'not-tightenable':
-            // Both producers reach here having already established that the directory
-            // is ours, so `chmod` is the user's to run. Names no cause: one producer
-            // is a mount that discards the mode, the other is any `chmod` failure.
-            return `${r.dir} is reachable by other users (mode ${asMode(r.mode)}) and Nx could not restrict it. Run \`chmod 0700 ${shellQuote(r.dir)}\` and try again; if the mode does not stick, set NX_SOCKET_DIR to a short directory on a filesystem that keeps POSIX permissions.`;
-        case 'foreign-shared-container':
-            // Unreachable today: `isSafeSharedRoot` denies with this kind only when
-            // `stats.uid !== 0`, so a root-owned container never reaches here.
-            if (r.uid === 0) {
-                return undefined;
-            }
-            const q = shellQuote(r.dir);
-            return `${r.dir} belongs to another user on this machine, so Nx cannot keep a private directory beneath it. Ask an administrator to hand it to root with \`sudo chown root ${q} && sudo chmod 1777 ${q}\`; every user can then keep their own directory under it.`;
-        case 'not-created':
-        case 'not-inspectable':
-        case 'peer-writable-not-sticky':
-            return undefined;
-        default: {
-            // Matches `describeRefusal`'s arm, so a new kind cannot ship with a
-            // sentence and no advice — which is how `not-tightenable` went unadvised.
-            const unhandled = r;
-            return undefined;
-        }
-    }
-}
 /** One refusal as an `Error`, so several can travel in an `AggregateError`. */
 class DirectoryRefusedError extends Error {
     constructor(refusal) {
@@ -207,30 +179,6 @@ function isSafeSharedRoot(dir) {
         return deny({ kind: 'not-inspectable', dir, code: e?.code });
     }
 }
-/**
- * Whether other users on this machine can write into `dir`. Gates whether a
- * refusal message may cite other users, so it must not over-report: `false` on
- * Windows, where libuv synthesizes `st_mode` from the READONLY attribute and
- * reports an ordinary per-account directory as `0666`, and `false` on a path
- * that cannot be inspected.
- *
- * `statSync`, not `lstatSync`: the question is about the directory that will be
- * used, not the link pointing at it. Link modes mislead in both directions —
- * Linux creates symlinks `0777`, macOS applies the umask. Nothing here decides
- * whether a path is accepted, so following the link costs nothing the guards
- * do not already re-check.
- */
-function isPeerWritable(dir) {
-    if (process.platform === 'win32') {
-        return false;
-    }
-    try {
-        return !!((0, node_fs_1.statSync)(dir).mode & 0o022);
-    }
-    catch {
-        return false;
-    }
-}
 /**
  * Create a shared container as sticky + world-writable if it does not exist,
  * and report whether the resulting path is safe for the current user.

package/dist/src/utils/package-json.js

@@ -231,7 +231,7 @@ function readModulePackageJson(moduleSpecifier, requirePaths = (0, installation_
  *      path instead of the workspace path.
  *
  *   2. Package self-reference. When a file inside package `nx` calls
- *      `require.resolve('@ohos-ports/nx/...')`, Node returns that calling package's
+ *      `require.resolve('nx/...')`, Node returns that calling package's
  *      own file regardless of `paths`. We avoid that by issuing the
  *      resolve from a `createRequire` rooted at a synthetic path that is
  *      outside any package, so the resolver has no "self" to reference

package/dist/src/utils/package-manager.d.ts

@@ -13,7 +13,15 @@ export interface PackageManagerCommands {
     why: string;
     run: (script: string, args?: string) => string;
     getRegistryUrl?: string;
+    /**
+     * @deprecated Use `publishArgv` instead, which needs no shell off Windows.
+     * This will be removed in Nx 25.
+     */
     publish: (packageRoot: string, registry: string, registryConfigKey: string, tag: string) => string;
+    publishArgv: (packageRoot: string, registry: string, registryConfigKey: string, tag: string) => {
+        command: string;
+        args: string[];
+    };
     ignoreScriptsFlag?: string;
 }
 /**

package/dist/src/utils/package-manager.js

@@ -23,6 +23,7 @@ exports.addPackagePathToWorkspaces = addPackagePathToWorkspaces;
 const child_process_1 = require("child_process");
 const fs_1 = require("fs");
 const promises_1 = require("node:fs/promises");
+const node_os_1 = require("node:os");
 const path_1 = require("path");
 const semver_1 = require("semver");
 const tmp_1 = require("tmp");
@@ -124,6 +125,13 @@ function isWorkspacesEnabled(packageManager = detectPackageManager(), root = wor
     const packageJson = (0, file_utils_1.readPackageJson)(root);
     return !!packageJson?.workspaces;
 }
+/**
+ * The registry and tag reach `publish` from `.npmrc`, which an install script
+ * can write, so every token is quoted before it becomes shell syntax.
+ */
+function publishCommandFromArgv({ command, args, }) {
+    return [command, ...args].map(shell_quoting_1.quoteShellArg).join(' ');
+}
 /**
  * Returns commands for the package manager used in the workspace.
  * By default, the package manager is derived based on the lock file,
@@ -150,6 +158,16 @@ function getPackageManagerCommand(packageManager = detectPackageManager(), root
                 yarnVersion = 'latest';
                 useBerry = true;
             }
+            const publishArgv = (packageRoot, registry, registryConfigKey, tag) => ({
+                command: 'npm',
+                args: [
+                    'publish',
+                    packageRoot,
+                    '--json',
+                    `--${registryConfigKey}=${registry}`,
+                    `--tag=${tag}`,
+                ],
+            });
             // new versions of yarn only support ignoring scripts via .yarnrc.yml
             return {
                 preInstall: `yarn set version ${yarnVersion}`,
@@ -171,7 +189,8 @@ function getPackageManagerCommand(packageManager = detectPackageManager(), root
                 getRegistryUrl: useBerry
                     ? 'yarn config get npmRegistryServer'
                     : 'yarn config get registry',
-                publish: (packageRoot, registry, registryConfigKey, tag) => `npm publish "${packageRoot}" --json --"${registryConfigKey}=${registry}" --tag=${tag}`,
+                publish: (...args) => publishCommandFromArgv(publishArgv(...args)),
+                publishArgv,
                 ignoreScriptsFlag: useBerry ? undefined : `--ignore-scripts`,
             };
         },
@@ -194,6 +213,21 @@ function getPackageManagerCommand(packageManager = detectPackageManager(), root
                 scopedForm = false;
             }
             const isPnpmWorkspace = (0, fs_1.existsSync)((0, path_1.join)(root, 'pnpm-workspace.yaml'));
+            const publishArgv = (packageRoot, registry, registryConfigKey, tag) => ({
+                command: 'pnpm',
+                args: [
+                    'publish',
+                    packageRoot,
+                    '--json',
+                    `--${configForm
+                        ? `config.${registryConfigKey}`
+                        : scopedForm
+                            ? registryConfigKey
+                            : 'registry'}=${registry}`,
+                    `--tag=${tag}`,
+                    '--no-git-checks',
+                ],
+            });
             return {
                 install: 'pnpm install --no-frozen-lockfile', // explicitly disable in case of CI
                 ciInstall: 'pnpm install --frozen-lockfile',
@@ -215,15 +249,22 @@ function getPackageManagerCommand(packageManager = detectPackageManager(), root
                 list: 'pnpm ls --depth 100',
                 why: 'pnpm why',
                 getRegistryUrl: 'pnpm config get registry',
-                publish: (packageRoot, registry, registryConfigKey, tag) => `pnpm publish "${packageRoot}" --json --"${configForm
-                    ? `config.${registryConfigKey}`
-                    : scopedForm
-                        ? registryConfigKey
-                        : 'registry'}=${registry}" --tag=${tag} --no-git-checks`,
+                publish: (...args) => publishCommandFromArgv(publishArgv(...args)),
+                publishArgv,
                 ignoreScriptsFlag: '--ignore-scripts',
             };
         },
         npm: () => {
+            const publishArgv = (packageRoot, registry, registryConfigKey, tag) => ({
+                command: 'npm',
+                args: [
+                    'publish',
+                    packageRoot,
+                    '--json',
+                    `--${registryConfigKey}=${registry}`,
+                    `--tag=${tag}`,
+                ],
+            });
             return {
                 install: 'npm install',
                 ciInstall: 'npm ci',
@@ -237,11 +278,22 @@ function getPackageManagerCommand(packageManager = detectPackageManager(), root
                 list: 'npm ls',
                 why: 'npm explain',
                 getRegistryUrl: 'npm config get registry',
-                publish: (packageRoot, registry, registryConfigKey, tag) => `npm publish "${packageRoot}" --json --"${registryConfigKey}=${registry}" --tag=${tag}`,
+                publish: (...args) => publishCommandFromArgv(publishArgv(...args)),
+                publishArgv,
                 ignoreScriptsFlag: '--ignore-scripts',
             };
         },
         bun: () => {
+            const publishArgv = (packageRoot, registry, _registryConfigKey, tag) => ({
+                command: 'bun',
+                args: [
+                    'publish',
+                    `--cwd=${packageRoot}`,
+                    '--json',
+                    `--registry=${registry}`,
+                    `--tag=${tag}`,
+                ],
+            });
             // bun doesn't current support programmatically reading config https://github.com/oven-sh/bun/issues/7140
             return {
                 install: 'bun install',
@@ -256,7 +308,8 @@ function getPackageManagerCommand(packageManager = detectPackageManager(), root
                 list: 'bun pm ls',
                 why: 'bun why',
                 // Unlike npm, bun publish does not support a custom registryConfigKey option
-                publish: (packageRoot, registry, registryConfigKey, tag) => `bun publish --cwd="${packageRoot}" --json --registry="${registry}" --tag=${tag}`,
+                publish: (...args) => publishCommandFromArgv(publishArgv(...args)),
+                publishArgv,
                 ignoreScriptsFlag: '--ignore-scripts',
             };
         },
@@ -283,6 +336,10 @@ function getPackageManagerVersion(packageManager = detectPackageManager(), cwd =
                 cwd,
                 encoding: 'utf-8',
                 windowsHide: true,
+                // Store discovery creates temporary workspace files even for --version.
+                env: packageManager === 'pnpm'
+                    ? { ...process.env, PNPM_CONFIG_STORE_DIR: (0, node_os_1.tmpdir)() }
+                    : undefined,
             }).trim();
         }
         catch { }

package/dist/src/utils/perf-hooks.d.ts

@@ -1,3 +1,4 @@
+// tsc doesn't emit hand-written .d.ts files; assets.json copies this one into dist.
 import type { EventParameters } from '../analytics/analytics';
 
 export interface TrackedDetail extends EventParameters {

package/dist/src/utils/plugins/core-plugins.js

@@ -80,7 +80,11 @@ exports.CORE_PLUGINS = [
     },
     {
         name: '@nx/remix',
-        capabilities: 'executors,generators',
+        capabilities: 'generators',
+    },
+    {
+        name: '@nx/rolldown',
+        capabilities: 'generators',
     },
     {
         name: '@nx/rollup',

package/dist/src/utils/progress-topics.d.ts

@@ -15,5 +15,6 @@
  */
 export declare const ProgressTopics: {
     readonly GraphConstruction: 'graph-construction';
+    readonly AffectedTasks: 'affected-tasks';
 };
 export type ProgressTopic = (typeof ProgressTopics)[keyof typeof ProgressTopics];

package/dist/src/utils/progress-topics.js

@@ -18,4 +18,5 @@ exports.ProgressTopics = void 0;
  */
 exports.ProgressTopics = {
     GraphConstruction: 'graph-construction',
+    AffectedTasks: 'affected-tasks',
 };

package/dist/src/utils/safe-spawn.js

@@ -25,9 +25,6 @@ function needsShell(binary) {
     const ext = path_1.win32.extname(binary).toLowerCase();
     return ext === '' || ext === '.cmd' || ext === '.bat';
 }
-// A line break ends the command line whatever the quoting, so nothing can carry
-// one.
-//
 // `%` is deliberately NOT refused, and this is a known gap rather than a safe
 // case. cmd.exe expands `%VAR%` whether or not the value is quoted — see
 // `quoteShellArg`'s own docstring in ./shell-quoting, which says so and pins it
@@ -42,7 +39,6 @@ function needsShell(binary) {
 // is bounded by the argument that bounds this whole class: a repo that can reach
 // here already has `mvnw` / `pom.xml` executing on its behalf. Closing it
 // properly is tracked as NXC-4798.
-const LINE_BREAK = /[\r\n]/;
 /**
  * Spawn a binary that may be a Windows `.cmd`/`.bat` shim, without letting its
  * arguments become shell syntax.
@@ -91,7 +87,7 @@ function quoteBinary(binary, shell) {
     return quoteForCmd(binary, `the path ${JSON.stringify(binary)}`);
 }
 function quoteForCmd(value, described, remedy = '') {
-    if (LINE_BREAK.test(value)) {
+    if (shell_quoting_1.LINE_BREAK.test(value)) {
         throw new Error(`Cannot pass ${described} to cmd.exe: a line break inside it would end the command line before cmd.exe reached the rest of it.${remedy}`);
     }
     return (0, shell_quoting_1.quoteShellArg)(value);

package/dist/src/utils/shell-quoting.d.ts

@@ -1,3 +1,9 @@
+/**
+ * A line break ends a cmd.exe command line whatever the quoting, so no quoted
+ * run can carry one. POSIX single quotes hold a newline fine, which is why the
+ * refusal in `quoteShellArg` is Windows-only.
+ */
+export declare const LINE_BREAK: RegExp;
 /**
  * Check if a string contains shell metacharacters that require quoting.
  * These characters have special meaning in shell and would be interpreted
@@ -20,6 +26,7 @@ export declare function isAlreadyQuoted(str: string): boolean;
  * @throws on Windows when the argument contains a double quote, which ends that
  * run, since cmd.exe recognizes no backslash escape. Carrying one means
  * caret-escaping every metacharacter instead, doubled for a `.cmd` shim, which
- * this path does not implement.
+ * this path does not implement. Also throws on a line break, which ends the
+ * command line itself and so survives no quoting at all.
  */
 export declare function quoteShellArg(arg: string): string;

package/dist/src/utils/shell-quoting.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.LINE_BREAK = void 0;
 exports.needsShellQuoting = needsShellQuoting;
 exports.isAlreadyQuoted = isAlreadyQuoted;
 exports.quoteShellArg = quoteShellArg;
@@ -24,6 +25,12 @@ exports.quoteShellArg = quoteShellArg;
  * - \s - whitespace (spaces, tabs, newlines)
  */
 const SHELL_META_CHARS = /[|&;<>()$`\\!"'*?[\]{}~#\s]/;
+/**
+ * A line break ends a cmd.exe command line whatever the quoting, so no quoted
+ * run can carry one. POSIX single quotes hold a newline fine, which is why the
+ * refusal in `quoteShellArg` is Windows-only.
+ */
+exports.LINE_BREAK = /[\r\n]/;
 /**
  * Check if a string contains shell metacharacters that require quoting.
  * These characters have special meaning in shell and would be interpreted
@@ -52,10 +59,14 @@ function isAlreadyQuoted(str) {
  * @throws on Windows when the argument contains a double quote, which ends that
  * run, since cmd.exe recognizes no backslash escape. Carrying one means
  * caret-escaping every metacharacter instead, doubled for a `.cmd` shim, which
- * this path does not implement.
+ * this path does not implement. Also throws on a line break, which ends the
+ * command line itself and so survives no quoting at all.
  */
 function quoteShellArg(arg) {
     const isWindows = process.platform === 'win32';
+    if (isWindows && exports.LINE_BREAK.test(arg)) {
+        throw new Error(`Cannot safely pass ${arg} to cmd.exe as a single argument: a line break inside it would end the command line and leave the rest of the argument to be read as commands. Remove the line break and run the command again.`);
+    }
     if (isWindows && arg.includes('"')) {
         throw new Error(`Cannot safely pass ${arg} to cmd.exe as a single argument: a double quote inside it would end the quoting and leave the rest of the argument to be read as commands. Remove the double quote and run the command again.`);
     }

package/dist/src/utils/spawn-without-terminal.d.ts

@@ -0,0 +1,27 @@
+import { type ChildProcess, type SpawnOptions } from 'child_process';
+/**
+ * Runs `command` in a shell that cannot reach the terminal nx shares with
+ * another program, so a prompt fails instead of waiting for keys that program
+ * reads. On POSIX the shell leads a new session with no controlling terminal,
+ * and loses every environment variable that names nx's terminal. Windows
+ * spawns it as usual, and with no stdio inherited it gets no console, so the
+ * terminal's Ctrl+C misses it there too. Whoever shares the terminal forwards
+ * signals with `signalCommandsWithoutTerminal`, and an nx that exits first
+ * kills each command whose output is still open.
+ */
+export declare function spawnWithoutTerminal(command: string, options: Omit<SpawnOptions, 'shell' | 'detached'>): ChildProcess;
+/**
+ * Sends `signal` to every command started by `spawnWithoutTerminal` whose
+ * output is still open: to its process group on POSIX, and on a SIGKILL also to
+ * the processes still descending from its shell, since a parent killed outright
+ * cannot stop the ones it started in groups of their own. Windows has no
+ * process groups, so there those descendants are terminated, whatever the
+ * signal.
+ */
+export declare function signalCommandsWithoutTerminal(signal: NodeJS.Signals): void;
+/**
+ * `env` without the variables whose value is the path of one of `terminals`
+ * (device ids). A process outside the new session, such as gpg-agent reading
+ * `GPG_TTY`, would otherwise open that terminal itself.
+ */
+export declare function withoutTerminalPaths(env: NodeJS.ProcessEnv, terminals: ReadonlySet<number>): NodeJS.ProcessEnv;

package/dist/src/utils/spawn-without-terminal.js

@@ -0,0 +1,110 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.spawnWithoutTerminal = spawnWithoutTerminal;
+exports.signalCommandsWithoutTerminal = signalCommandsWithoutTerminal;
+exports.withoutTerminalPaths = withoutTerminalPaths;
+const child_process_1 = require("child_process");
+const fs_1 = require("fs");
+const tty_1 = require("tty");
+// The commands spawned below whose output is still open, by pid. On POSIX each
+// one leads its own process group.
+const commands = new Map();
+/**
+ * Runs `command` in a shell that cannot reach the terminal nx shares with
+ * another program, so a prompt fails instead of waiting for keys that program
+ * reads. On POSIX the shell leads a new session with no controlling terminal,
+ * and loses every environment variable that names nx's terminal. Windows
+ * spawns it as usual, and with no stdio inherited it gets no console, so the
+ * terminal's Ctrl+C misses it there too. Whoever shares the terminal forwards
+ * signals with `signalCommandsWithoutTerminal`, and an nx that exits first
+ * kills each command whose output is still open.
+ */
+function spawnWithoutTerminal(command, options) {
+    const child = (0, child_process_1.spawn)(command, {
+        ...options,
+        shell: true,
+        windowsHide: true,
+        detached: process.platform !== 'win32',
+        ...(process.platform !== 'win32' && {
+            env: withoutTerminalPaths(options.env ?? process.env, stdioTerminals()),
+        }),
+    });
+    const pid = child.pid;
+    if (pid !== undefined) {
+        if (commands.size === 0)
+            process.on('exit', killCommands);
+        commands.set(pid, child);
+        child.once('close', () => {
+            commands.delete(pid);
+            if (commands.size === 0)
+                process.removeListener('exit', killCommands);
+        });
+    }
+    return child;
+}
+/**
+ * Sends `signal` to every command started by `spawnWithoutTerminal` whose
+ * output is still open: to its process group on POSIX, and on a SIGKILL also to
+ * the processes still descending from its shell, since a parent killed outright
+ * cannot stop the ones it started in groups of their own. Windows has no
+ * process groups, so there those descendants are terminated, whatever the
+ * signal.
+ */
+function signalCommandsWithoutTerminal(signal) {
+    for (const [pid, child] of commands) {
+        // Tree first: killing the group reparents its members' children.
+        if (process.platform === 'win32' || signal === 'SIGKILL') {
+            killTree(child, pid, signal);
+        }
+        if (process.platform !== 'win32') {
+            try {
+                process.kill(-pid, signal);
+            }
+            catch {
+                // The command already ended; its `close` is on the way.
+            }
+        }
+    }
+}
+// Only while the shell lives: once it has exited, its pid can be reused.
+function killTree(child, pid, signal) {
+    if (child.exitCode !== null || child.signalCode !== null)
+        return;
+    try {
+        const { killProcessTree } = require('../native');
+        killProcessTree(pid, signal);
+    }
+    catch {
+        // No native killer in this build; on POSIX the group signal still goes out.
+    }
+}
+function killCommands() {
+    signalCommandsWithoutTerminal('SIGKILL');
+}
+function stdioTerminals() {
+    const devices = new Set();
+    for (const fd of [0, 1, 2]) {
+        if ((0, tty_1.isatty)(fd))
+            devices.add((0, fs_1.fstatSync)(fd).rdev);
+    }
+    return devices;
+}
+/**
+ * `env` without the variables whose value is the path of one of `terminals`
+ * (device ids). A process outside the new session, such as gpg-agent reading
+ * `GPG_TTY`, would otherwise open that terminal itself.
+ */
+function withoutTerminalPaths(env, terminals) {
+    return Object.fromEntries(Object.entries(env).filter(([, value]) => !namesTerminal(value, terminals)));
+}
+function namesTerminal(value, terminals) {
+    if (!value?.startsWith('/dev/'))
+        return false;
+    try {
+        const stat = (0, fs_1.statSync)(value);
+        return stat.isCharacterDevice() && terminals.has(stat.rdev);
+    }
+    catch {
+        return false;
+    }
+}

package/dist/src/utils/string-similarity.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Computes the Levenshtein edit distance between two strings, i.e. the minimum
+ * number of single-character insertions, deletions, or substitutions required
+ * to turn `a` into `b`.
+ */
+export declare function levenshteinDistance(a: string, b: string): number;
+/**
+ * Ranks every candidate by how closely it resembles `input`, from closest to
+ * furthest, tie-broken alphabetically so the order is deterministic. Each entry
+ * keeps its computed distance so callers can reuse it (e.g. to both pick the
+ * closest match and order a list) without recomputing.
+ */
+export declare function rankByDistance(input: string, candidates: readonly string[]): {
+    candidate: string;
+    distance: number;
+}[];
+/**
+ * Whether a candidate at edit `distance` from `input` is close enough to be a
+ * useful suggestion. Exposed so callers that already have a distance (e.g. from
+ * `rankByDistance`) can gate on it without recomputing.
+ */
+export declare function isWithinSuggestionThreshold(input: string, candidate: string, distance: number): boolean;
+/**
+ * Ranks the candidates that are similar enough to `input` to be worth
+ * suggesting, closest first (ties broken alphabetically). Each entry keeps its
+ * distance so callers can compare suggestions found for different forms of the
+ * same input without recomputing.
+ */
+export declare function rankSuggestions(input: string, candidates: readonly string[]): {
+    candidate: string;
+    distance: number;
+}[];
+/**
+ * Returns up to `limit` candidates that most closely resemble `input`, sorted
+ * from closest to furthest. Candidates that are not similar enough to be a
+ * useful suggestion are excluded.
+ */
+export declare function findClosestMatches(input: string, candidates: readonly string[], limit?: number): string[];

package/dist/src/utils/string-similarity.js

@@ -0,0 +1,108 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.levenshteinDistance = levenshteinDistance;
+exports.rankByDistance = rankByDistance;
+exports.isWithinSuggestionThreshold = isWithinSuggestionThreshold;
+exports.rankSuggestions = rankSuggestions;
+exports.findClosestMatches = findClosestMatches;
+/**
+ * Computes the Levenshtein edit distance between two strings, i.e. the minimum
+ * number of single-character insertions, deletions, or substitutions required
+ * to turn `a` into `b`.
+ */
+function levenshteinDistance(a, b) {
+    if (a === b) {
+        return 0;
+    }
+    if (a.length === 0) {
+        return b.length;
+    }
+    if (b.length === 0) {
+        return a.length;
+    }
+    let previousRow = Array.from({ length: b.length + 1 }, (_, i) => i);
+    let currentRow = new Array(b.length + 1);
+    for (let i = 0; i < a.length; i++) {
+        currentRow[0] = i + 1;
+        for (let j = 0; j < b.length; j++) {
+            const cost = a[i] === b[j] ? 0 : 1;
+            currentRow[j + 1] = Math.min(currentRow[j] + 1, // insertion
+            previousRow[j + 1] + 1, // deletion
+            previousRow[j] + cost // substitution
+            );
+        }
+        [previousRow, currentRow] = [currentRow, previousRow];
+    }
+    return previousRow[b.length];
+}
+/**
+ * Ranks every candidate by how closely it resembles `input`, from closest to
+ * furthest, tie-broken alphabetically so the order is deterministic. Each entry
+ * keeps its computed distance so callers can reuse it (e.g. to both pick the
+ * closest match and order a list) without recomputing.
+ */
+function rankByDistance(input, candidates) {
+    return candidates
+        .map((candidate) => ({
+        candidate,
+        distance: levenshteinDistance(input, candidate),
+    }))
+        .sort((a, b) => a.distance - b.distance || a.candidate.localeCompare(b.candidate));
+}
+/**
+ * The number of edits tolerated before `candidate` stops being a useful
+ * suggestion for `input`.
+ *
+ * The tolerance scales with length so longer words allow for more typos, but it
+ * scales with the length of the part that actually *differs* — the shared
+ * prefix and suffix are stripped first. Scaling on the raw length lets text the
+ * user typed correctly buy a bigger budget for the part they got wrong, which
+ * matters because these inputs are joined `project:target[:configuration]`
+ * specifiers: `zzz:build` and `api:build` are 3 edits apart, but the shared
+ * `:build` inflates the raw-length budget to 4 and a project name with no
+ * character in common gets suggested.
+ *
+ * Stripping a common prefix and suffix does not change the Levenshtein
+ * distance, so a caller's precomputed `distance` remains directly comparable.
+ */
+function suggestionThreshold(input, candidate) {
+    const shortest = Math.min(input.length, candidate.length);
+    let prefix = 0;
+    while (prefix < shortest && input[prefix] === candidate[prefix]) {
+        prefix++;
+    }
+    let suffix = 0;
+    while (suffix < shortest - prefix &&
+        input[input.length - 1 - suffix] ===
+            candidate[candidate.length - 1 - suffix]) {
+        suffix++;
+    }
+    return Math.max(2, Math.ceil((input.length - prefix - suffix) * 0.4));
+}
+/**
+ * Whether a candidate at edit `distance` from `input` is close enough to be a
+ * useful suggestion. Exposed so callers that already have a distance (e.g. from
+ * `rankByDistance`) can gate on it without recomputing.
+ */
+function isWithinSuggestionThreshold(input, candidate, distance) {
+    return distance <= suggestionThreshold(input, candidate);
+}
+/**
+ * Ranks the candidates that are similar enough to `input` to be worth
+ * suggesting, closest first (ties broken alphabetically). Each entry keeps its
+ * distance so callers can compare suggestions found for different forms of the
+ * same input without recomputing.
+ */
+function rankSuggestions(input, candidates) {
+    return rankByDistance(input, candidates).filter(({ candidate, distance }) => isWithinSuggestionThreshold(input, candidate, distance));
+}
+/**
+ * Returns up to `limit` candidates that most closely resemble `input`, sorted
+ * from closest to furthest. Candidates that are not similar enough to be a
+ * useful suggestion are excluded.
+ */
+function findClosestMatches(input, candidates, limit = 3) {
+    return rankSuggestions(input, candidates)
+        .slice(0, limit)
+        .map(({ candidate }) => candidate);
+}