From 574c02251ae78b833f80d2100bca937f0457de56 Mon Sep 17 00:00:00 2001 From: Ramon Brullo Date: Fri, 1 Nov 2024 19:10:59 +0100 Subject: [PATCH] refactor: rename symbols 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 --- src/app/add-dependencies.ts | 39 +++--- src/app/get-registry-packument-version.ts | 2 +- src/cli/cmd-add.ts | 129 +++++++++--------- src/cli/cmd-deps.ts | 22 ++- src/cli/cmd-remove.ts | 25 ++-- src/cli/cmd-view.ts | 16 +-- src/cli/dependency-logging.ts | 32 ++--- src/cli/error-logging.ts | 6 +- src/cli/validators.ts | 11 +- src/domain/dependency-graph.ts | 4 +- .../{package-reference.ts => package-spec.ts} | 37 +++-- src/domain/packument.ts | 2 +- test/e2e/add.test.ts | 6 +- test/unit/cli/dependency-logging.test.ts | 30 ++-- ...reference.test.ts => package-spec.test.ts} | 28 ++-- 15 files changed, 195 insertions(+), 194 deletions(-) rename src/domain/{package-reference.ts => package-spec.ts} (72%) rename test/unit/domain/{package-reference.test.ts => package-spec.test.ts} (80%) diff --git a/src/app/add-dependencies.ts b/src/app/add-dependencies.ts index 1cb503e4..847371e0 100644 --- a/src/app/add-dependencies.ts +++ b/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, force: boolean, shouldAddTestable: boolean, - pkgs: ReadonlyArray + packageSpecs: ReadonlyArray ): Promise>> { const loadProjectManifest = partialApply( loadProjectManifestUsing, @@ -202,7 +202,7 @@ export async function addDependenciesUsing( ): Promise>>> { 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 = {}; - 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, diff --git a/src/app/get-registry-packument-version.ts b/src/app/get-registry-packument-version.ts index 71f05cce..facb3009 100644 --- a/src/app/get-registry-packument-version.ts +++ b/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, diff --git a/src/cli/cmd-add.ts b/src/cli/cmd-add.ts index f3e9a4a5..c57b0200 100644 --- a/src/cli/cmd-add.ts +++ b/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( "", "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 [otherPkgs...] openupm add @ [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."); + } + ) ); } diff --git a/src/cli/cmd-deps.ts b/src/cli/cmd-deps.ts index a8e8fe9a..5a9aed69 100644 --- a/src/cli/cmd-deps.ts +++ b/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("", "Reference to a package").argParser( - mustBePackageReference -); +const packageSpecArg = new Argument( + "", + "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 openupm deps @` ) .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 @` ); 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 @` throw new PackumentNotFoundError(packageName); await debugLog( - `fetch: ${makePackageReference(packageName, latestVersion)}, deep=${ + `fetch: ${makePackageSpec(packageName, latestVersion)}, deep=${ options.deep }` ); diff --git a/src/cli/cmd-remove.ts b/src/cli/cmd-remove.ts index 4ac22864..93e0e8a8 100644 --- a/src/cli/cmd-remove.ts +++ b/src/cli/cmd-remove.ts @@ -3,7 +3,7 @@ import { Logger } from "npmlog"; import { removeDependenciesUsing } from "../app/remove-dependencies"; import { partialApply } from "../domain/fp-utils"; import type { DebugLog } from "../domain/logging"; -import { makePackageReference } from "../domain/package-reference"; +import { makePackageSpec } from "../domain/package-spec"; import type { ReadTextFile, WriteTextFile } from "../io/fs"; import { eachValue } from "./cli-parsing"; import { logError, withErrorLogger } from "./error-logging"; @@ -11,11 +11,12 @@ import { workDirOpt } from "./opt-wd"; import { ResultCodes } from "./result-codes"; import { mustBeDomainName } from "./validators"; -const pkgArg = new Argument("", "Name of the package to remove").argParser( - mustBeDomainName -); +const packageNameArg = new Argument( + "", + "Name of the package to remove" +).argParser(mustBeDomainName); -const otherPkgsArg = new Argument( +const otherPackageNamesArg = new Argument( "[otherPkgs...]", "Names of additional packages to remove" ).argParser(eachValue(mustBeDomainName)); @@ -43,20 +44,22 @@ export function makeRemoveCmd( return new Command("remove") .aliases(["rm", "uninstall"]) - .addArgument(pkgArg) - .addArgument(otherPkgsArg) + .addArgument(packageNameArg) + .addArgument(otherPackageNamesArg) .addOption(workDirOpt) .description("remove package from manifest json") .action( withErrorLogger( log, async function (packageName, otherPackageNames, options) { - const pkgs = [packageName, ...otherPackageNames]; + const packageNames = [packageName, ...otherPackageNames]; const projectDir = options.chdir; - const removeResult = await removeDependencies(projectDir, pkgs) - .promise; + const removeResult = await removeDependencies( + projectDir, + packageNames + ).promise; if (removeResult.isErr()) { logError(log, removeResult.error); return process.exit(ResultCodes.Error); @@ -66,7 +69,7 @@ export function makeRemoveCmd( removedPackages.forEach((removedPackage) => { log.notice( "", - `Removed "${makePackageReference( + `Removed "${makePackageSpec( removedPackage.name, removedPackage.version )}".` diff --git a/src/cli/cmd-view.ts b/src/cli/cmd-view.ts index e2c9836c..24236e60 100644 --- a/src/cli/cmd-view.ts +++ b/src/cli/cmd-view.ts @@ -6,7 +6,7 @@ import { queryAllRegistriesLazy } from "../app/query-registries"; import { PackumentNotFoundError } from "../domain/common-errors"; import { partialApply } from "../domain/fp-utils"; import type { DebugLog } from "../domain/logging"; -import { hasVersion, splitPackageReference } from "../domain/package-reference"; +import { hasVersion, splitPackageSpec } from "../domain/package-spec"; import { unityRegistry } from "../domain/registry"; import { getHomePathFromEnv } from "../domain/special-paths"; import { getUserUpmConfigPathFor } from "../domain/upm-config"; @@ -18,7 +18,7 @@ import { systemUserOpt } from "./opt-system-user"; import { upstreamOpt } from "./opt-upstream"; import { formatPackumentInfo } from "./output-formatting"; import { ResultCodes } from "./result-codes"; -import { mustBePackageReference } from "./validators"; +import { mustBePackageSpec } from "./validators"; /** * Makes the `openupm view` cli command with the given dependencies. @@ -41,14 +41,14 @@ export function makeViewCmd( ); return new Command("view") - .argument("", "Reference to a package", mustBePackageReference) + .argument("", "Reference to a package", mustBePackageSpec) .addOption(primaryRegistryUrlOpt) .addOption(systemUserOpt) .addOption(upstreamOpt) .aliases(["v", "info", "show"]) .description("view package information") .action( - withErrorLogger(log, async function (pkg, options) { + withErrorLogger(log, async function (packageSpec, options) { const homePath = getHomePathFromEnv(process.env); const upmConfigPath = getUserUpmConfigPathFor( process.env, @@ -62,8 +62,8 @@ export function makeViewCmd( ); // parse name - if (hasVersion(pkg)) { - const [name] = splitPackageReference(pkg); + if (hasVersion(packageSpec)) { + const [name] = splitPackageSpec(packageSpec); log.warn( "", `please do not specify a version (Write only '${name}').` @@ -78,10 +78,10 @@ export function makeViewCmd( ]; const packumentFromRegistry = await queryAllRegistriesLazy( sources, - (source) => getRegistryPackument(source, pkg) + (source) => getRegistryPackument(source, packageSpec) ); const packument = packumentFromRegistry?.value ?? null; - if (packument === null) throw new PackumentNotFoundError(pkg); + if (packument === null) throw new PackumentNotFoundError(packageSpec); const output = formatPackumentInfo(packument, EOL); log.notice("", output); diff --git a/src/cli/dependency-logging.ts b/src/cli/dependency-logging.ts index 9fe20c0a..6d953f21 100644 --- a/src/cli/dependency-logging.ts +++ b/src/cli/dependency-logging.ts @@ -10,9 +10,9 @@ import { } from "../domain/dependency-graph"; import { DomainName } from "../domain/domain-name"; import { - makePackageReference, - PackageReference, -} from "../domain/package-reference"; + makePackageSpec, + PackageSpec, +} from "../domain/package-spec"; import { ResolvePackumentVersionError, VersionNotFoundError, @@ -27,7 +27,7 @@ import { recordEntries } from "../domain/record-utils"; */ export async function logResolvedDependency( debugLog: DebugLog, - packageRef: PackageReference, + packageSpec: PackageSpec, source: RegistryUrl | "built-in" ) { const tag = @@ -36,7 +36,7 @@ export async function logResolvedDependency( : source === unityRegistryUrl ? "[unity]" : ""; - const message = `${packageRef} ${tag}`; + const message = `${packageSpec} ${tag}`; await debugLog(message); } @@ -54,7 +54,7 @@ export function stringifyDependencyGraph( rootVersion: SemanticVersion, chalk?: Chalk ): readonly string[] { - const printedRefs = new Set(); + const printedRefs = new Set(); function tryColor(chalk: Chalk | undefined, s: string) { return chalk !== undefined ? chalk(s) : s; @@ -67,7 +67,7 @@ export function stringifyDependencyGraph( const node = tryGetGraphNode(graph, packageName, version); if (node === null) throw new RangeError( - `Dependency graph did not contain a node for ${makePackageReference( + `Dependency graph did not contain a node for ${makePackageSpec( rootPackage, rootVersion )}` @@ -86,8 +86,8 @@ export function stringifyDependencyGraph( } } - function makeDuplicateLine(packageRef: PackageReference): string { - return tryColor(chalk?.blueBright, `${packageRef} ..`); + function makeDuplicateLine(packageSpec: PackageSpec): string { + return tryColor(chalk?.blueBright, `${packageSpec} ..`); } function makeErrorLines(errors: FailedNode["errors"]): readonly string[] { @@ -133,17 +133,17 @@ export function stringifyDependencyGraph( version: SemanticVersion ): readonly string[] { const node = getNode(packageName, version); - const packageRef = makePackageReference(packageName, version); + const packageSpec = makePackageSpec(packageName, version); // We only print package@version once. If two packages depend on the // same package@version, we print a short version of it. - const isDuplicate = printedRefs.has(packageRef); - if (isDuplicate) return [makeDuplicateLine(packageRef)]; - else printedRefs.add(packageRef); + const isDuplicate = printedRefs.has(packageSpec); + if (isDuplicate) return [makeDuplicateLine(packageSpec)]; + else printedRefs.add(packageSpec); if (node.type === NodeType.Unresolved) // package@version - return [packageRef]; + return [packageSpec]; if (node.type === NodeType.Failed) { /* @@ -152,7 +152,7 @@ export function stringifyDependencyGraph( - url2: package not found */ const errorLines = makeErrorLines(node.errors); - return [tryColor(chalk?.red, packageRef), ...errorLines]; + return [tryColor(chalk?.red, packageSpec), ...errorLines]; } // Resolved node @@ -161,7 +161,7 @@ export function stringifyDependencyGraph( └─ dependency@version */ const dependencyLines = makeDependencyLines(node.dependencies); - return [packageRef, ...dependencyLines]; + return [packageSpec, ...dependencyLines]; } return stringifyRecursively(rootPackage, rootVersion); diff --git a/src/cli/error-logging.ts b/src/cli/error-logging.ts index a8ecc9a5..33561639 100644 --- a/src/cli/error-logging.ts +++ b/src/cli/error-logging.ts @@ -61,16 +61,16 @@ function makeErrorMessageFor(error: unknown): string { error.version )}.`; if (error instanceof CompatibilityCheckFailedError) - return `Could not confirm editor compatibility for ${error.packageRef}.`; + return `Could not confirm editor compatibility for ${error.packageSpec}.`; if (error instanceof PackageIncompatibleError) return `"${ - error.packageRef + error.packageSpec }" is not compatible with Unity ${stringifyEditorVersion( error.editorVersion )}.`; if (error instanceof UnresolvedDependenciesError) return ( - `"${error.packageRef}" has one or more unresolved dependencies and was not added.${EOL}` + + `"${error.packageSpec}" has one or more unresolved dependencies and was not added.${EOL}` + `${error.dependencies.map(stringifyUnresolvedDependency).join(EOL)}` ); if (error instanceof NoVersionsError) diff --git a/src/cli/validators.ts b/src/cli/validators.ts index 0fe305f5..800c65cc 100644 --- a/src/cli/validators.ts +++ b/src/cli/validators.ts @@ -1,15 +1,16 @@ import { DomainName } from "../domain/domain-name"; -import { isPackageReference } from "../domain/package-reference"; +// eslint-disable-next-line @typescript-eslint/no-unused-vars +import { isPackageSpec, type PackageSpec } from "../domain/package-spec"; import { coerceRegistryUrl } from "../domain/registry-url"; import { isZod } from "../domain/zod-utils"; import { mustBeParsable, mustSatisfy } from "./cli-parsing"; /** - * {@link CliValueParser} for checking that a string is a {@link PackageReference}. + * {@link CliValueParser} for checking that a string is a {@link PackageSpec}. */ -export const mustBePackageReference = mustSatisfy( - isPackageReference, - (input) => `"${input}" is not a valid package-reference` +export const mustBePackageSpec = mustSatisfy( + isPackageSpec, + (input) => `"${input}" is not a valid package-spec` ); /** diff --git a/src/domain/dependency-graph.ts b/src/domain/dependency-graph.ts index 4ed84de1..d5e9b398 100644 --- a/src/domain/dependency-graph.ts +++ b/src/domain/dependency-graph.ts @@ -1,6 +1,6 @@ -import { recordEntries } from "./record-utils"; import { DomainName } from "./domain-name"; import { ResolvePackumentVersionError } from "./packument"; +import { recordEntries } from "./record-utils"; import { RegistryUrl } from "./registry-url"; import { SemanticVersion } from "./semantic-version"; @@ -125,7 +125,7 @@ export function makeGraphFromSeed( } /** - * Attempts to get the next unresolved package reference from a dependency + * Attempts to get the next unresolved package-spec from a dependency * graph. * @param graph The graph to search. * @returns A tuple with the name and version of the next unresolved package or diff --git a/src/domain/package-reference.ts b/src/domain/package-spec.ts similarity index 72% rename from src/domain/package-reference.ts rename to src/domain/package-spec.ts index f89b9de1..b2307fcb 100644 --- a/src/domain/package-reference.ts +++ b/src/domain/package-spec.ts @@ -28,9 +28,9 @@ export type PackageTag = LatestTag | StableTag; export type VersionReference = SemanticVersion | PackageUrl | PackageTag; /** - * A package reference that includes a version. + * A package-spec that includes a version. */ -export type ReferenceWithVersion = `${DomainName}@${VersionReference}`; +export type PackageAtVersion = `${DomainName}@${VersionReference}`; /** * A {@link VersionReference} that is resolvable. @@ -42,8 +42,9 @@ export type ResolvableVersion = Exclude; * References a package. Could be just the name or a reference to a specific * version. Not as specific as a {@link PackageId} as other version-formats * besides semantic versions, such as "latest" are also allowed. + * @see https://docs.npmjs.com/cli/v8/using-npm/package-spec */ -export type PackageReference = DomainName | ReferenceWithVersion; +export type PackageSpec = DomainName | PackageAtVersion; /** * Checks if a string is a version-reference. @@ -59,10 +60,10 @@ function isVersionReference(s: string): s is VersionReference { } /** - * Checks if a string is a package-reference. + * Checks if a string is a package-spec. * @param s The string. */ -export function isPackageReference(s: string): s is PackageReference { +export function isPackageSpec(s: string): s is PackageSpec { const [name, version] = trySplitAtFirstOccurrenceOf(s, "@"); return ( isZod(name, DomainName) && (version === null || isVersionReference(version)) @@ -70,13 +71,13 @@ export function isPackageReference(s: string): s is PackageReference { } /** - * Split a package-reference into the name and version if present. - * @param reference The reference. + * Split a package-spec into the name and version if present. + * @param spec The spec. */ -export function splitPackageReference( - reference: PackageReference +export function splitPackageSpec( + spec: PackageSpec ): [DomainName, VersionReference | null] { - const [name, version] = trySplitAtFirstOccurrenceOf(reference, "@") as [ + const [name, version] = trySplitAtFirstOccurrenceOf(spec, "@") as [ DomainName, VersionReference | null ]; @@ -84,15 +85,15 @@ export function splitPackageReference( } /** - * Constructs a package-reference. + * Constructs a package-spec. * @param name The package-name. Will be validated to be a {@link DomainName}. * @param version Optional version-reference. Will be validated to be a * {@link VersionReference}. */ -export function makePackageReference( +export function makePackageSpec( name: string, version: string | null -): PackageReference { +): PackageSpec { assertZod(name, DomainName); if (version === null) return name; assert( @@ -103,11 +104,9 @@ export function makePackageReference( } /** - * Checks if the package-reference includes a version. - * @param reference The package-reference. + * Checks if the package-spec includes a version. + * @param spec The package-spec. */ -export function hasVersion( - reference: PackageReference -): reference is ReferenceWithVersion { - return reference.includes("@"); +export function hasVersion(spec: PackageSpec): spec is PackageAtVersion { + return spec.includes("@"); } diff --git a/src/domain/packument.ts b/src/domain/packument.ts index 465eb91a..d74a4593 100644 --- a/src/domain/packument.ts +++ b/src/domain/packument.ts @@ -8,7 +8,7 @@ import { ResolvableVersion, type LatestTag, type StableTag, -} from "./package-reference"; +} from "./package-spec"; import { recordKeys } from "./record-utils"; import { compareVersions, isStable, SemanticVersion } from "./semantic-version"; diff --git a/test/e2e/add.test.ts b/test/e2e/add.test.ts index a921b818..45bb1908 100644 --- a/test/e2e/add.test.ts +++ b/test/e2e/add.test.ts @@ -22,14 +22,14 @@ describe("add packages", () => { const homeDir = await prepareHomeDirectory(); const projectDir = await prepareUnityProject(homeDir); - const pkgRefs = cases.map((it) => + const packageSpecs = cases.map((it) => it.addVersion !== undefined ? `${it.packageName}@${it.addVersion}` : it.packageName ); const output = await runOpenupm(projectDir, [ "add", - ...pkgRefs, + ...packageSpecs, ...(registryOverride !== undefined ? [`--registry=${registryOverride}`] : []), @@ -289,7 +289,7 @@ describe("add packages", () => { expect(output.stdOut).toEqual([]); expect(output.stdErr).toEqual( expect.arrayContaining([ - expect.stringContaining(`"1,2,3" is not a valid package-reference`), + expect.stringContaining(`"1,2,3" is not a valid package-spec`), ]) ); }); diff --git a/test/unit/cli/dependency-logging.test.ts b/test/unit/cli/dependency-logging.test.ts index 3a2e7ee6..392c453a 100644 --- a/test/unit/cli/dependency-logging.test.ts +++ b/test/unit/cli/dependency-logging.test.ts @@ -5,7 +5,7 @@ import { markRemoteResolved, } from "../../../src/domain/dependency-graph"; import { stringifyDependencyGraph } from "../../../src/cli/dependency-logging"; -import { makePackageReference } from "../../../src/domain/package-reference"; +import { makePackageSpec } from "../../../src/domain/package-spec"; import { someRegistryUrl } from "../../common/data-registry"; import { PackumentNotFoundError } from "../../../src/domain/common-errors"; import { unityRegistryUrl } from "../../../src/domain/registry-url"; @@ -46,7 +46,7 @@ describe("dependency-logging", () => { // Print just name@version expect(actual).toEqual([ - `${makePackageReference(somePackage, someVersion)}`, + `${makePackageSpec(somePackage, someVersion)}`, ]); }); @@ -67,9 +67,9 @@ describe("dependency-logging", () => { // Print name@version plus dependencies in the next lines expect(actual).toEqual([ - `${makePackageReference(somePackage, someVersion)}`, - `└─ ${makePackageReference(otherPackage, otherVersion)}`, - `└─ ${makePackageReference(anotherPackage, someVersion)}`, + `${makePackageSpec(somePackage, someVersion)}`, + `└─ ${makePackageSpec(otherPackage, otherVersion)}`, + `└─ ${makePackageSpec(anotherPackage, someVersion)}`, ]); }); @@ -88,7 +88,7 @@ describe("dependency-logging", () => { // Print name@version plus error message in next line expect(actual).toEqual([ - `${makePackageReference(somePackage, someVersion)}`, + `${makePackageSpec(somePackage, someVersion)}`, ` - "${someRegistryUrl}": package not found`, ` - "${unityRegistryUrl}": version not found`, ]); @@ -122,10 +122,10 @@ describe("dependency-logging", () => { // Print | next to nested trees expect(actual).toEqual([ - `${makePackageReference(somePackage, someVersion)}`, - `└─ ${makePackageReference(otherPackage, otherVersion)}`, - `│ └─ ${makePackageReference(anotherPackage, someVersion)}`, - `└─ ${makePackageReference(thatPackage, someVersion)}`, + `${makePackageSpec(somePackage, someVersion)}`, + `└─ ${makePackageSpec(otherPackage, otherVersion)}`, + `│ └─ ${makePackageSpec(anotherPackage, someVersion)}`, + `└─ ${makePackageSpec(thatPackage, someVersion)}`, ]); }); @@ -160,13 +160,13 @@ describe("dependency-logging", () => { const actual = stringifyDependencyGraph(graph, somePackage, someVersion); expect(actual).toEqual([ - `${makePackageReference(somePackage, someVersion)}`, - `└─ ${makePackageReference(otherPackage, otherVersion)}`, - `│ └─ ${makePackageReference(anotherPackage, someVersion)}`, - `│ └─ ${makePackageReference(thatPackage, someVersion)}`, + `${makePackageSpec(somePackage, someVersion)}`, + `└─ ${makePackageSpec(otherPackage, otherVersion)}`, + `│ └─ ${makePackageSpec(anotherPackage, someVersion)}`, + `│ └─ ${makePackageSpec(thatPackage, someVersion)}`, // Because this package was printed before, now only its name is printed // with a string at the end that indicates that this is a duplicate. - `└─ ${makePackageReference(anotherPackage, someVersion)} ..`, + `└─ ${makePackageSpec(anotherPackage, someVersion)} ..`, ]); }); }); diff --git a/test/unit/domain/package-reference.test.ts b/test/unit/domain/package-spec.test.ts similarity index 80% rename from test/unit/domain/package-reference.test.ts rename to test/unit/domain/package-spec.test.ts index b0fc9e8d..26fa2bf3 100644 --- a/test/unit/domain/package-reference.test.ts +++ b/test/unit/domain/package-spec.test.ts @@ -1,19 +1,19 @@ import fc from "fast-check"; import { - isPackageReference, - makePackageReference, - splitPackageReference, -} from "../../../src/domain/package-reference"; + isPackageSpec, + makePackageSpec, + splitPackageSpec, +} from "../../../src/domain/package-spec"; import { arbDomainName } from "./domain-name.arb"; import { arbPackageUrl } from "./package-url.arb"; import { arbSemanticVersion } from "./semantic-version.arb"; -describe("package-reference", () => { +describe("package-spec", () => { describe("validation", () => { it("should be ok for just name", () => { fc.assert( fc.property(arbDomainName, (packumentName) => { - expect(isPackageReference(packumentName)).toBeTruthy(); + expect(isPackageSpec(packumentName)).toBeTruthy(); }) ); }); @@ -22,7 +22,7 @@ describe("package-reference", () => { fc.assert( fc.property(arbDomainName, (packumentName) => { const input = `${packumentName}@1.2.3`; - expect(isPackageReference(input)).toBeTruthy(); + expect(isPackageSpec(input)).toBeTruthy(); }) ); }); @@ -31,7 +31,7 @@ describe("package-reference", () => { fc.assert( fc.property(arbDomainName, (packumentName) => { const input = `${packumentName}@file:/path/to/${packumentName}`; - expect(isPackageReference(input)).toBeTruthy(); + expect(isPackageSpec(input)).toBeTruthy(); }) ); }); @@ -40,7 +40,7 @@ describe("package-reference", () => { fc.assert( fc.property(arbDomainName, (packumentName) => { const input = `${packumentName}@http://my.server/${packumentName}`; - expect(isPackageReference(input)).toBeTruthy(); + expect(isPackageSpec(input)).toBeTruthy(); }) ); }); @@ -49,7 +49,7 @@ describe("package-reference", () => { fc.assert( fc.property(arbDomainName, (packumentName) => { const input = `${packumentName}@git@github:user/${packumentName}`; - expect(isPackageReference(input)).toBeTruthy(); + expect(isPackageSpec(input)).toBeTruthy(); }) ); }); @@ -58,7 +58,7 @@ describe("package-reference", () => { fc.assert( fc.property(arbDomainName, (packumentName) => { const input = `${packumentName}@latest`; - expect(isPackageReference(input)).toBeTruthy(); + expect(isPackageSpec(input)).toBeTruthy(); }) ); }); @@ -73,14 +73,14 @@ describe("package-reference", () => { // Bad tag "my.package@ltst", ])(`"should not be ok for "%s"`, (input) => { - expect(isPackageReference(input)).not.toBeTruthy(); + expect(isPackageSpec(input)).not.toBeTruthy(); }); }); describe("split", () => { function shouldSplitCorrectly(name: string, version?: string) { - const [actualName, actualVersion] = splitPackageReference( - makePackageReference(name, version ?? null) + const [actualName, actualVersion] = splitPackageSpec( + makePackageSpec(name, version ?? null) ); expect(actualName).toEqual(name); expect(actualVersion).toEqual(version ?? null);