refactor: rename symbols (#412)

After looking at the npm documentation, seems like the term for a package-name with or without version is called a "package spec"

https://docs.npmjs.com/cli/v8/using-npm/package-spec

Renamed relevant symbols to match this term

Author: ComradeVanti

src/app/add-dependencies.ts

@@ -21,11 +21,11 @@ import { partialApply } from "../domain/fp-utils";
 import type { DebugLog } from "../domain/logging";
 import { tryGetTargetEditorVersionFor } from "../domain/package-manifest";
 import {
-  type PackageReference,
+  type PackageSpec,
   type VersionReference,
-  makePackageReference,
-  splitPackageReference,
-} from "../domain/package-reference";
+  makePackageSpec,
+  splitPackageSpec,
+} from "../domain/package-spec";
 import { PackageUrl } from "../domain/package-url";
 import type { ResolvePackumentVersionError } from "../domain/packument";
 import {
@@ -63,7 +63,7 @@ export class PackageIncompatibleError extends CustomError {
     /**
      * The package that was added.
      */
-    public readonly packageRef: PackageReference,
+    public readonly packageSpec: PackageSpec,
     /**
      * The packages target editor version.
      */
@@ -101,7 +101,7 @@ export class UnresolvedDependenciesError extends CustomError {
     /**
      * The package that should have been added.
      */
-    public readonly packageRef: PackageReference,
+    public readonly packageSpec: PackageSpec,
     /**
      * The dependencies which could not be resolved.
      */
@@ -120,7 +120,7 @@ export class CompatibilityCheckFailedError extends CustomError {
     /**
      * The package that could not be added.
      */
-    public readonly packageRef: PackageReference
+    public readonly packageSpec: PackageSpec
   ) {
     super();
   }
@@ -157,7 +157,7 @@ function pickMostFixable(
  * @param sources The sources from which to resolve the packuments.
  * @param force Whether to force add the dependencies.
  * @param shouldAddTestable Whether to also add dependencies to the `testables`.
- * @param pkgs References to the dependencies to add.
+ * @param packageSpecs Specs of the dependencies to add.
  * @returns A summary of the added packages.
  */
 export async function addDependenciesUsing(
@@ -171,7 +171,7 @@ export async function addDependenciesUsing(
   sources: ReadonlyArray<Registry>,
   force: boolean,
   shouldAddTestable: boolean,
-  pkgs: ReadonlyArray<PackageReference>
+  packageSpecs: ReadonlyArray<PackageSpec>
 ): Promise<Readonly<Record<DomainName, AddResult>>> {
   const loadProjectManifest = partialApply(
     loadProjectManifestUsing,
@@ -202,7 +202,7 @@ export async function addDependenciesUsing(
   ): Promise<Readonly<Record<RegistryUrl, ReadonlyArray<DomainName>>>> {
     if (source === unityRegistryUrl) return {};
 
-    await debugLog(`fetch: ${makePackageReference(packageName, verison)}`);
+    await debugLog(`fetch: ${makePackageSpec(packageName, verison)}`);
 
     const dependencyGraph = await resolveDependencies(
       sources,
@@ -231,10 +231,7 @@ export async function addDependenciesUsing(
       }
       if (dependency.type === NodeType.Unresolved) continue;
 
-      const dependencyRef = makePackageReference(
-        dependencyName,
-        dependencyVersion
-      );
+      const dependencyRef = makePackageSpec(dependencyName, dependencyVersion);
       await logResolvedDependency(debugLog, dependencyRef, dependency.source);
 
       const isUnityPackage =
@@ -249,7 +246,7 @@ export async function addDependenciesUsing(
     // print suggestion for depsInvalid
     if (unresolvedDependencies.length > 0 && !force)
       throw new UnresolvedDependenciesError(
-        makePackageReference(packageName, verison),
+        makePackageSpec(packageName, verison),
         unresolvedDependencies
       );
 
@@ -295,11 +292,11 @@ export async function addDependenciesUsing(
         targetEditorVersion = tryGetTargetEditorVersionFor(packumentVersion);
       } catch (error) {
         if (!force) {
-          const packageRef = makePackageReference(packageName, versionToAdd);
+          const packageSpec = makePackageSpec(packageName, versionToAdd);
           await debugLog(
-            `"${packageRef}" is malformed. Target editor version could not be determined.`
+            `"${packageSpec}" is malformed. Target editor version could not be determined.`
           );
-          throw new CompatibilityCheckFailedError(packageRef);
+          throw new CompatibilityCheckFailedError(packageSpec);
         }
         targetEditorVersion = null;
       }
@@ -310,7 +307,7 @@ export async function addDependenciesUsing(
         compareEditorVersion(editorVersion, targetEditorVersion) >= 0;
       if (!isCompatible && !force)
         throw new PackageIncompatibleError(
-          makePackageReference(packageName, versionToAdd),
+          makePackageSpec(packageName, versionToAdd),
           targetEditorVersion!
         );
     }
@@ -357,8 +354,8 @@ export async function addDependenciesUsing(
   let manifest = await loadProjectManifest(projectDirectory);
 
   const results: Record<DomainName, AddResult> = {};
-  for (const pkg of pkgs) {
-    const [packageName, version] = splitPackageReference(pkg);
+  for (const packageSpec of packageSpecs) {
+    const [packageName, version] = splitPackageSpec(packageSpec);
     const [newManifest, result] = await addSingle(
       manifest,
       packageName,

src/app/get-registry-packument-version.ts

@@ -1,7 +1,7 @@
 import { AsyncResult, Err } from "ts-results-es";
 import { PackumentNotFoundError } from "../domain/common-errors";
 import { DomainName } from "../domain/domain-name";
-import { ResolvableVersion } from "../domain/package-reference";
+import { ResolvableVersion } from "../domain/package-spec";
 import {
   ResolvePackumentVersionError,
   tryResolvePackumentVersion,

src/cli/cmd-add.ts

@@ -5,7 +5,7 @@ import { determineEditorVersionUsing } from "../app/determine-editor-version";
 import { loadRegistryAuthUsing } from "../app/get-registry-auth";
 import { partialApply } from "../domain/fp-utils";
 import { DebugLog } from "../domain/logging";
-import { makePackageReference } from "../domain/package-reference";
+import { makePackageSpec } from "../domain/package-spec";
 import { recordEntries } from "../domain/record-utils";
 import { unityRegistry } from "../domain/registry";
 import { openupmRegistryUrl } from "../domain/registry-url";
@@ -20,17 +20,17 @@ import { primaryRegistriesUrlOpt } from "./opt-registry";
 import { systemUserOpt } from "./opt-system-user";
 import { upstreamOpt } from "./opt-upstream";
 import { workDirOpt } from "./opt-wd";
-import { mustBePackageReference } from "./validators";
+import { mustBePackageSpec } from "./validators";
 
-const pkgArg = new Argument(
+const packageSpecArg = new Argument(
   "<pkg>",
   "Reference to the package that should be added"
-).argParser(mustBePackageReference);
+).argParser(mustBePackageSpec);
 
-const otherPkgsArg = new Argument(
+const otherPackageSpecsArg = new Argument(
   "[otherPkgs...]",
   "References to additional packages that should be added"
-).argParser(eachValue(mustBePackageReference));
+).argParser(eachValue(mustBePackageSpec));
 
 const addTestableOpt = new Option(
   "-t, --test",
@@ -83,8 +83,8 @@ export function makeAddCmd(
 
   return new Command("add")
     .aliases(["install", "i"])
-    .addArgument(pkgArg)
-    .addArgument(otherPkgsArg)
+    .addArgument(packageSpecArg)
+    .addArgument(otherPackageSpecsArg)
     .addOption(addTestableOpt)
     .addOption(forceOpt)
     .addOption(primaryRegistriesUrlOpt)
@@ -97,65 +97,68 @@ openupm add <pkg> [otherPkgs...]
 openupm add <pkg>@<version> [otherPkgs...]`
     )
     .action(
-      withErrorLogger(log, async function (pkg, otherPkgs, options) {
-        const pkgs = [pkg].concat(otherPkgs);
+      withErrorLogger(
+        log,
+        async function (packageSpec, otherPackageSpecs, options) {
+          const packageSpecs = [packageSpec].concat(otherPackageSpecs);
+
+          const projectDirectory = options.chdir;
+
+          const editorVersion = await determineEditorVersion(projectDirectory);
+
+          if (typeof editorVersion === "string")
+            log.warn(
+              "editor.version",
+              `${editorVersion} is unknown, the editor version check is disabled`
+            );
+
+          const homePath = getHomePathFromEnv(process.env);
+          const upmConfigPath = getUserUpmConfigPathFor(
+            process.env,
+            homePath,
+            options.systemUser
+          );
 
-        const projectDirectory = options.chdir;
+          const sources = await Promise.all(
+            (options.registry ?? [openupmRegistryUrl]).map((it) =>
+              getRegistryAuth(upmConfigPath, it)
+            )
+          );
 
-        const editorVersion = await determineEditorVersion(projectDirectory);
+          if (options.upstream) sources.push(unityRegistry);
 
-        if (typeof editorVersion === "string")
-          log.warn(
-            "editor.version",
-            `${editorVersion} is unknown, the editor version check is disabled`
+          const addResults = await addDependencies(
+            projectDirectory,
+            typeof editorVersion === "string" ? null : editorVersion,
+            sources,
+            options.force,
+            options.test,
+            packageSpecs
           );
 
-        const homePath = getHomePathFromEnv(process.env);
-        const upmConfigPath = getUserUpmConfigPathFor(
-          process.env,
-          homePath,
-          options.systemUser
-        );
-
-        const sources = await Promise.all(
-          (options.registry ?? [openupmRegistryUrl]).map((it) =>
-            getRegistryAuth(upmConfigPath, it)
-          )
-        );
-
-        if (options.upstream) sources.push(unityRegistry);
-
-        const addResults = await addDependencies(
-          projectDirectory,
-          typeof editorVersion === "string" ? null : editorVersion,
-          sources,
-          options.force,
-          options.test,
-          pkgs
-        );
-
-        recordEntries(addResults)
-          .map(([packageName, addResult]) => {
-            switch (addResult.type) {
-              case "added":
-                return `added ${makePackageReference(
-                  packageName,
-                  addResult.version
-                )}`;
-              case "upgraded":
-                return `modified ${packageName} ${addResult.fromVersion} => ${addResult.toVersion}`;
-              case "noChange":
-                return `existed ${makePackageReference(
-                  packageName,
-                  addResult.version
-                )}`;
-            }
-          })
-          .forEach((message) => {
-            log.notice("", message);
-          });
-
-        log.notice("", "please open Unity project to apply changes.");
-      })
+          recordEntries(addResults)
+            .map(([packageName, addResult]) => {
+              switch (addResult.type) {
+                case "added":
+                  return `added ${makePackageSpec(
+                    packageName,
+                    addResult.version
+                  )}`;
+                case "upgraded":
+                  return `modified ${packageName} ${addResult.fromVersion} => ${addResult.toVersion}`;
+                case "noChange":
+                  return `existed ${makePackageSpec(
+                    packageName,
+                    addResult.version
+                  )}`;
+              }
+            })
+            .forEach((message) => {
+              log.notice("", message);
+            });
+
+          log.notice("", "please open Unity project to apply changes.");
+        }
+      )
     );
 }

src/cli/cmd-deps.ts

@@ -9,10 +9,7 @@ import { resolveDependenciesUsing } from "../app/resolve-dependencies";
 import { PackumentNotFoundError } from "../domain/common-errors";
 import { partialApply } from "../domain/fp-utils";
 import { DebugLog } from "../domain/logging";
-import {
-  makePackageReference,
-  splitPackageReference,
-} from "../domain/package-reference";
+import { makePackageSpec, splitPackageSpec } from "../domain/package-spec";
 import { PackageUrl } from "../domain/package-url";
 import { unityRegistry } from "../domain/registry";
 import { SemanticVersion } from "../domain/semantic-version";
@@ -27,11 +24,12 @@ import { withErrorLogger } from "./error-logging";
 import { primaryRegistryUrlOpt } from "./opt-registry";
 import { systemUserOpt } from "./opt-system-user";
 import { ResultCodes } from "./result-codes";
-import { mustBePackageReference } from "./validators";
+import { mustBePackageSpec } from "./validators";
 
-const pkgArg = new Argument("<pkg>", "Reference to a package").argParser(
-  mustBePackageReference
-);
+const packageSpecArg = new Argument(
+  "<pkg>",
+  "Reference to a package"
+).argParser(mustBePackageSpec);
 
 const deepOpt = new Option(
   "-d, --deep",
@@ -72,7 +70,7 @@ export function makeDepsCmd(
 
   return new Command("deps")
     .alias("dep")
-    .addArgument(pkgArg)
+    .addArgument(packageSpecArg)
     .addOption(deepOpt)
     .addOption(primaryRegistryUrlOpt)
     .addOption(systemUserOpt)
@@ -82,7 +80,7 @@ openupm deps <pkg>
 openupm deps <pkg>@<version>`
     )
     .action(
-      withErrorLogger(log, async function (pkg, options) {
+      withErrorLogger(log, async function (packageSpec, options) {
         const homePath = getHomePathFromEnv(process.env);
         const upmConfigPath = getUserUpmConfigPathFor(
           process.env,
@@ -95,7 +93,7 @@ openupm deps <pkg>@<version>`
         );
         const sources = [primaryRegistry, unityRegistry];
 
-        const [packageName, requestedVersion] = splitPackageReference(pkg);
+        const [packageName, requestedVersion] = splitPackageSpec(packageSpec);
 
         if (requestedVersion !== null && isZod(requestedVersion, PackageUrl)) {
           log.error("", "cannot get dependencies for url-version");
@@ -115,7 +113,7 @@ openupm deps <pkg>@<version>`
           throw new PackumentNotFoundError(packageName);
 
         await debugLog(
-          `fetch: ${makePackageReference(packageName, latestVersion)}, deep=${
+          `fetch: ${makePackageSpec(packageName, latestVersion)}, deep=${
             options.deep
           }`
         );