@packall/core 0.0.1 → 0.2.0

package/src/Spec.ts

@@ -1,186 +0,0 @@
-/**
- * Parsing and validation of package specs — the `lodash`, `react@18.2.0`,
- * `@babel/core@^7`, `typescript@next` strings a user types.
- *
- * Deliberately dependency-light and synchronous: parsing must never touch the
- * network, so `--dry-run` and argument validation stay instant.
- */
-import semver from "semver"
-import { InvalidSpecError } from "./Errors.js"
-
-/** How a spec narrows down which version(s) of a package we want. */
-export type Selector =
-  /** An exact, fully-qualified version: `react@18.2.0`. */
-  | { readonly _tag: "Exact"; readonly version: string }
-  /** A semver range: `react@^18`, `react@>=17 <19`, `react@*`. */
-  | { readonly _tag: "Range"; readonly range: string }
-  /** A dist-tag: `react@latest`, `typescript@next`. */
-  | { readonly _tag: "Tag"; readonly tag: string }
-
-/** A parsed, validated package spec. */
-export interface PackageSpec {
-  /** The npm package name, including scope. */
-  readonly name: string
-  /** What the user asked for after the `@`. */
-  readonly selector: Selector
-  /** The original string, kept verbatim for error messages and the manifest. */
-  readonly raw: string
-}
-
-/** Renders a spec back into the canonical `name@selector` form. */
-export const formatSpec = (spec: PackageSpec): string => {
-  switch (spec.selector._tag) {
-    case "Exact":
-      return `${spec.name}@${spec.selector.version}`
-    case "Range":
-      return `${spec.name}@${spec.selector.range}`
-    case "Tag":
-      return `${spec.name}@${spec.selector.tag}`
-  }
-}
-
-/** Human-readable form of just the selector part. */
-export const formatSelector = (selector: Selector): string => {
-  switch (selector._tag) {
-    case "Exact":
-      return selector.version
-    case "Range":
-      return selector.range
-    case "Tag":
-      return selector.tag
-  }
-}
-
-const MAX_NAME_LENGTH = 214
-
-/**
- * Validates an npm package name against the rules the registry actually
- * enforces. Returns `null` when valid, or the reason it is not.
- */
-export const validatePackageName = (name: string): string | null => {
-  if (name.length === 0) return "name is empty"
-  if (name.length > MAX_NAME_LENGTH) {
-    return `name is longer than ${MAX_NAME_LENGTH} characters`
-  }
-  if (name.trim() !== name) return "name has leading or trailing whitespace"
-  if (name.startsWith(".")) return "name cannot start with a period"
-  if (name.startsWith("_")) return "name cannot start with an underscore"
-  if (name !== name.toLowerCase()) return "name cannot contain capital letters"
-
-  if (name.startsWith("@")) {
-    const slash = name.indexOf("/")
-    if (slash === -1) return "scoped name is missing the '/name' part"
-    const scope = name.slice(1, slash)
-    const rest = name.slice(slash + 1)
-    if (scope.length === 0) return "scope is empty"
-    if (rest.length === 0) return "name after the scope is empty"
-    if (rest.includes("/")) return "name contains more than one '/'"
-    if (!SEGMENT_RE.test(scope)) return `scope "${scope}" contains illegal characters`
-    if (!SEGMENT_RE.test(rest)) return `name "${rest}" contains illegal characters`
-    return null
-  }
-
-  if (name.includes("/")) return "unscoped name cannot contain '/'"
-  if (!SEGMENT_RE.test(name)) return "name contains illegal characters"
-  return null
-}
-
-// The registry accepts URL-safe characters plus `-`, `.` and `_`.
-const SEGMENT_RE = /^[a-z0-9\-._~]+$/
-
-/**
- * Parses a single spec string.
- *
- * Splitting on `@` is the fiddly part: a scoped name *starts* with `@`, so we
- * look for the last `@` that is not at index 0.
- */
-export const parseSpec = (raw: string): PackageSpec => {
-  const input = raw.trim()
-  if (input.length === 0) {
-    throw new InvalidSpecError(raw, "spec is empty")
-  }
-
-  const at = input.lastIndexOf("@")
-  const hasSelector = at > 0
-  const name = hasSelector ? input.slice(0, at) : input
-  const selectorText = hasSelector ? input.slice(at + 1) : ""
-
-  const nameProblem = validatePackageName(name)
-  if (nameProblem !== null) {
-    throw new InvalidSpecError(raw, nameProblem)
-  }
-
-  if (!hasSelector || selectorText.length === 0) {
-    return { name, selector: { _tag: "Tag", tag: "latest" }, raw: input }
-  }
-
-  return { name, selector: parseSelector(raw, selectorText), raw: input }
-}
-
-/** Classifies the part after the `@` as an exact version, a range, or a dist-tag. */
-export const parseSelector = (raw: string, text: string): Selector => {
-  // `semver.valid` only accepts a complete `x.y.z`, which is exactly the
-  // "pin me to this one version" case.
-  const exact = semver.valid(text, { loose: false })
-  if (exact !== null) {
-    return { _tag: "Exact", version: exact }
-  }
-
-  if (semver.validRange(text, { loose: false }) !== null) {
-    return { _tag: "Range", range: text }
-  }
-
-  // Anything left has to be a dist-tag. Tags may not look like versions and
-  // may not contain characters that would break a registry URL.
-  if (!DIST_TAG_RE.test(text)) {
-    throw new InvalidSpecError(
-      raw,
-      `"${text}" is not a valid version, semver range, or dist-tag`
-    )
-  }
-  return { _tag: "Tag", tag: text }
-}
-
-const DIST_TAG_RE = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/
-
-/**
- * Parses many specs, collecting *every* failure rather than stopping at the
- * first. Somebody bundling forty packages should be told about all four typos
- * in one go, not made to re-run four times.
- */
-export const parseSpecs = (
-  inputs: ReadonlyArray<string>
-): { readonly specs: ReadonlyArray<PackageSpec>; readonly errors: ReadonlyArray<InvalidSpecError> } => {
-  const specs: Array<PackageSpec> = []
-  const errors: Array<InvalidSpecError> = []
-  for (const input of inputs) {
-    try {
-      specs.push(parseSpec(input))
-    } catch (error) {
-      if (error instanceof InvalidSpecError) {
-        errors.push(error)
-      } else {
-        throw error
-      }
-    }
-  }
-  return { specs, errors }
-}
-
-/**
- * Collapses duplicate specs, keeping the first occurrence.
- *
- * `npmb react react@latest` is a plausible thing to type and should not
- * download React twice.
- */
-export const dedupeSpecs = (specs: ReadonlyArray<PackageSpec>): ReadonlyArray<PackageSpec> => {
-  const seen = new Set<string>()
-  const out: Array<PackageSpec> = []
-  for (const spec of specs) {
-    const key = formatSpec(spec)
-    if (seen.has(key)) continue
-    seen.add(key)
-    out.push(spec)
-  }
-  return out
-}