@ontrails/regrade 0.2.0

package/src/downstream/package-source-manifest.ts

@@ -0,0 +1,369 @@
+import {
+  ConflictError,
+  InternalError,
+  NotFoundError,
+  Result,
+  ValidationError,
+} from '@ontrails/core';
+import type { Result as TrailsResult } from '@ontrails/core';
+import { readFile, realpath } from 'node:fs/promises';
+import {
+  dirname,
+  isAbsolute,
+  join,
+  posix,
+  relative,
+  resolve,
+  sep,
+} from 'node:path';
+import { z } from 'zod';
+
+import type {
+  RegradePackageSourceError,
+  RegradePackageSourceExpectation,
+} from './package-source.js';
+
+export interface PackageManifest {
+  readonly dependencies?: Readonly<Record<string, string>>;
+  readonly devDependencies?: Readonly<Record<string, string>>;
+  readonly name?: string;
+  readonly optionalDependencies?: Readonly<Record<string, string>>;
+  readonly peerDependencies?: Readonly<Record<string, string>>;
+  readonly version?: string;
+}
+
+export const exactVersionPattern =
+  /^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-(?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*)(?:\.(?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*))*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/u;
+const packageNamePattern = /^@ontrails\/[a-z0-9][a-z0-9._-]*$/u;
+const sha256Pattern = /^[a-f0-9]{64}$/u;
+
+export const regradePackageSourceExpectationSchema = z.discriminatedUnion(
+  'kind',
+  [
+    z
+      .object({
+        kind: z.literal('published'),
+        name: z.string().regex(packageNamePattern),
+        version: z.string().regex(exactVersionPattern),
+      })
+      .strict(),
+    z
+      .object({
+        kind: z.literal('tarball'),
+        name: z.string().regex(packageNamePattern),
+        path: z.string().min(1),
+        sha256: z.string().regex(sha256Pattern),
+      })
+      .strict(),
+  ]
+);
+
+const isNormalizedTarballPath = (value: string): boolean => {
+  if (value.length === 0) {
+    return false;
+  }
+  const normalized = posix.normalize(value);
+  return normalized === value || `./${normalized}` === value;
+};
+
+const errorCause = (error: unknown): Error =>
+  error instanceof Error ? error : new Error(String(error));
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+const dependencyMapIsValid = (value: unknown): boolean =>
+  value === undefined ||
+  (isRecord(value) &&
+    Object.values(value).every((entry) => typeof entry === 'string'));
+
+export const parsePackageManifest = (
+  bytes: string,
+  label: string
+): TrailsResult<PackageManifest, ValidationError> => {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(bytes) as unknown;
+  } catch (error) {
+    return Result.err(
+      new ValidationError(`${label} package manifest is malformed.`, {
+        cause: errorCause(error),
+      })
+    );
+  }
+  if (
+    !isRecord(parsed) ||
+    (parsed['name'] !== undefined && typeof parsed['name'] !== 'string') ||
+    (parsed['version'] !== undefined &&
+      typeof parsed['version'] !== 'string') ||
+    !dependencyMapIsValid(parsed['dependencies']) ||
+    !dependencyMapIsValid(parsed['devDependencies']) ||
+    !dependencyMapIsValid(parsed['optionalDependencies']) ||
+    !dependencyMapIsValid(parsed['peerDependencies'])
+  ) {
+    return Result.err(
+      new ValidationError(`${label} package manifest has an invalid shape.`)
+    );
+  }
+  return Result.ok(parsed as PackageManifest);
+};
+
+const validateExpectation = (
+  expectation: RegradePackageSourceExpectation
+): TrailsResult<void, ValidationError> => {
+  if (!packageNamePattern.test(expectation.name)) {
+    return Result.err(
+      new ValidationError(
+        'Regrade package-source proof requires one @ontrails package name.',
+        { context: { name: expectation.name } }
+      )
+    );
+  }
+  if (
+    expectation.kind === 'published' &&
+    !exactVersionPattern.test(expectation.version)
+  ) {
+    return Result.err(
+      new ValidationError(
+        'Published Regrade package-source proof requires an exact version.',
+        { context: { version: expectation.version } }
+      )
+    );
+  }
+  if (
+    expectation.kind === 'tarball' &&
+    !sha256Pattern.test(expectation.sha256)
+  ) {
+    return Result.err(
+      new ValidationError(
+        'Tarball Regrade package-source proof requires a lowercase SHA-256 digest.',
+        { context: { sha256: expectation.sha256 } }
+      )
+    );
+  }
+  if (
+    expectation.kind === 'tarball' &&
+    !isNormalizedTarballPath(expectation.path)
+  ) {
+    return Result.err(
+      new ValidationError(
+        'Tarball Regrade package-source proof requires a normalized path.',
+        { context: { path: expectation.path } }
+      )
+    );
+  }
+  return Result.ok();
+};
+
+const directSpecifier = (
+  manifest: PackageManifest,
+  name: string
+): TrailsResult<string | undefined, ConflictError> => {
+  const declarations = [
+    manifest.dependencies?.[name],
+    manifest.optionalDependencies?.[name],
+    manifest.peerDependencies?.[name],
+    manifest.devDependencies?.[name],
+  ].filter((specifier): specifier is string => specifier !== undefined);
+  if (new Set(declarations).size > 1) {
+    return Result.err(
+      new ConflictError(
+        `Downstream manifest declares conflicting sources for "${name}".`,
+        { context: { declarations, name } }
+      )
+    );
+  }
+  return Result.ok(declarations[0]);
+};
+
+const normalizedTarballDeclaration = (
+  root: string,
+  specifier: string
+): string | undefined => {
+  if (!specifier.startsWith('file:')) {
+    return undefined;
+  }
+  const locator = specifier.slice('file:'.length);
+  if (!isNormalizedTarballPath(locator)) {
+    return undefined;
+  }
+  return resolve(root, locator);
+};
+
+const findPackageRoot = async (
+  entryPath: string | undefined,
+  expectedName: string,
+  root: string
+): Promise<string | undefined> => {
+  const resolvedEntryPath =
+    entryPath === undefined ? undefined : await realpath(entryPath);
+  let searchRoot = root;
+  while (true) {
+    const candidate = join(searchRoot, 'node_modules', expectedName);
+    try {
+      const resolvedCandidate = await realpath(candidate);
+      const entryRelative =
+        resolvedEntryPath === undefined
+          ? ''
+          : relative(resolvedCandidate, resolvedEntryPath);
+      if (
+        entryRelative !== '..' &&
+        !entryRelative.startsWith(`..${sep}`) &&
+        !isAbsolute(entryRelative)
+      ) {
+        return candidate;
+      }
+    } catch {
+      // Keep walking: dependency installations can be hoisted above the root.
+    }
+    const parent = dirname(searchRoot);
+    if (parent === searchRoot) {
+      break;
+    }
+    searchRoot = parent;
+  }
+  return undefined;
+};
+
+const resolveInstalledPackage = async (
+  root: string,
+  name: string
+): Promise<
+  TrailsResult<string, NotFoundError | InternalError | ValidationError>
+> => {
+  let entryPath: string;
+  try {
+    entryPath = Bun.resolveSync(name, root);
+  } catch (error) {
+    try {
+      const packageRoot = await findPackageRoot(undefined, name, root);
+      if (packageRoot !== undefined) {
+        return Result.ok(packageRoot);
+      }
+    } catch {
+      // The normal missing-package error below owns absent direct installs.
+    }
+    return Result.err(
+      new NotFoundError(`Installed package "${name}" was not found.`, {
+        cause: errorCause(error),
+        context: { name, root },
+      })
+    );
+  }
+  try {
+    const packageRoot = await findPackageRoot(entryPath, name, root);
+    return packageRoot === undefined
+      ? Result.err(
+          new NotFoundError(
+            `Installed package root for "${name}" was not found.`,
+            {
+              context: { entryPath, name, root },
+            }
+          )
+        )
+      : Result.ok(packageRoot);
+  } catch (error) {
+    return Result.err(
+      new InternalError(`Installed package "${name}" could not be inspected.`, {
+        cause: errorCause(error),
+        context: { name, root },
+      })
+    );
+  }
+};
+
+export interface PreparedPackageSource {
+  readonly declaredSpecifier: string;
+  readonly expectedTarballPath: string | undefined;
+  readonly installedRoot: string;
+  readonly root: string;
+}
+
+export const preparePackageSource = async (params: {
+  readonly root: string;
+  readonly expected: RegradePackageSourceExpectation;
+}): Promise<TrailsResult<PreparedPackageSource, RegradePackageSourceError>> => {
+  const expectation = validateExpectation(params.expected);
+  if (expectation.isErr()) {
+    return expectation;
+  }
+  const selectedRoot = resolve(params.root);
+  let root: string;
+  try {
+    root = await realpath(selectedRoot);
+  } catch (error) {
+    return Result.err(
+      new NotFoundError('Downstream package root was not found.', {
+        cause: errorCause(error),
+        context: { root: selectedRoot },
+      })
+    );
+  }
+  let rootManifestBytes: string;
+  try {
+    rootManifestBytes = await readFile(join(root, 'package.json'), 'utf8');
+  } catch (error) {
+    return Result.err(
+      new NotFoundError('Downstream package manifest was not found.', {
+        cause: errorCause(error),
+        context: { root },
+      })
+    );
+  }
+  const parsedRootManifest = parsePackageManifest(
+    rootManifestBytes,
+    'Downstream'
+  );
+  if (parsedRootManifest.isErr()) {
+    return parsedRootManifest;
+  }
+  const declaredSpecifier = directSpecifier(
+    parsedRootManifest.value,
+    params.expected.name
+  );
+  if (declaredSpecifier.isErr()) {
+    return declaredSpecifier;
+  }
+  if (declaredSpecifier.value === undefined) {
+    return Result.err(
+      new NotFoundError(
+        `Downstream manifest does not directly declare "${params.expected.name}".`,
+        { context: { name: params.expected.name, root } }
+      )
+    );
+  }
+  const expectedTarballPath =
+    params.expected.kind === 'tarball'
+      ? resolve(root, params.expected.path)
+      : undefined;
+  const declarationMatches =
+    params.expected.kind === 'published'
+      ? declaredSpecifier.value === params.expected.version
+      : normalizedTarballDeclaration(root, declaredSpecifier.value) ===
+        expectedTarballPath;
+  if (!declarationMatches) {
+    return Result.err(
+      new ConflictError(
+        `Downstream declaration for "${params.expected.name}" does not match the selected source.`,
+        {
+          context: {
+            actual: declaredSpecifier.value,
+            expected: params.expected,
+          },
+        }
+      )
+    );
+  }
+  const installedRoot = await resolveInstalledPackage(
+    root,
+    params.expected.name
+  );
+  return installedRoot.isErr()
+    ? installedRoot
+    : Result.ok({
+        declaredSpecifier: declaredSpecifier.value,
+        expectedTarballPath,
+        installedRoot: installedRoot.value,
+        root,
+      });
+};

package/src/downstream/package-source.ts

@@ -0,0 +1,237 @@
+import {
+  ConflictError,
+  InternalError,
+  Result,
+  ValidationError,
+} from '@ontrails/core';
+import type { Result as TrailsResult, NotFoundError } from '@ontrails/core';
+import { mkdtemp, readFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import {
+  defaultArtifactAcquirer,
+  extractPackageArtifact,
+  revalidateSelectedArtifact,
+  snapshotSelectedArtifact,
+} from './package-source-artifact.js';
+import type { PackageSourceArtifactAcquirer } from './package-source-artifact.js';
+import {
+  collectRegularFiles,
+  compareInstalledFiles,
+} from './package-source-files.js';
+import {
+  exactVersionPattern,
+  parsePackageManifest,
+  preparePackageSource,
+} from './package-source-manifest.js';
+import type { PackageManifest } from './package-source-manifest.js';
+
+const errorCause = (error: unknown): Error =>
+  error instanceof Error ? error : new Error(String(error));
+
+export type RegradePackageSourceExpectation =
+  | {
+      readonly kind: 'published';
+      readonly name: string;
+      readonly version: string;
+    }
+  | {
+      readonly kind: 'tarball';
+      readonly name: string;
+      readonly path: string;
+      readonly sha256: string;
+    };
+
+export interface RegradePackageSourceEvidence {
+  readonly kind: RegradePackageSourceExpectation['kind'];
+  readonly name: string;
+  readonly version: string;
+  readonly declaredSpecifier: string;
+  readonly resolvedPackagePath: string;
+  readonly artifactSha256: string;
+  readonly contentSha256: string;
+}
+
+export type RegradePackageSourceError =
+  | ConflictError
+  | InternalError
+  | NotFoundError
+  | ValidationError;
+
+/**
+ * Test seam for deterministic published-artifact fixtures.
+ *
+ * @internal
+ */
+export const verifyDownstreamPackageSourceWithAcquirer = async (
+  params: {
+    readonly root: string;
+    readonly expected: RegradePackageSourceExpectation;
+  },
+  acquirer: PackageSourceArtifactAcquirer
+): Promise<
+  TrailsResult<RegradePackageSourceEvidence, RegradePackageSourceError>
+> => {
+  const prepared = await preparePackageSource(params);
+  if (prepared.isErr()) {
+    return prepared;
+  }
+  let tempRoot: string;
+  try {
+    tempRoot = await mkdtemp(join(tmpdir(), 'trails-regrade-package-source-'));
+  } catch (error) {
+    return Result.err(
+      new InternalError(
+        'Package source proof workspace could not be created.',
+        {
+          cause: errorCause(error),
+        }
+      )
+    );
+  }
+  try {
+    const artifact = await snapshotSelectedArtifact({
+      acquirer,
+      expected: params.expected,
+      expectedTarballPath: prepared.value.expectedTarballPath,
+      root: prepared.value.root,
+      tempRoot,
+    });
+    if (artifact.isErr()) {
+      return artifact;
+    }
+    const extracted = await extractPackageArtifact(
+      artifact.value.snapshotPath,
+      join(tempRoot, 'extracted')
+    );
+    if (extracted.isErr()) {
+      return extracted;
+    }
+    const revalidated = await revalidateSelectedArtifact(artifact.value);
+    if (revalidated.isErr()) {
+      return revalidated;
+    }
+    let artifactManifest: PackageManifest;
+    let installedManifest: PackageManifest;
+    try {
+      const [artifactManifestBytes, installedManifestBytes] = await Promise.all(
+        [
+          readFile(join(extracted.value, 'package.json'), 'utf8'),
+          readFile(join(prepared.value.installedRoot, 'package.json'), 'utf8'),
+        ]
+      );
+      const artifactParsed = parsePackageManifest(
+        artifactManifestBytes,
+        'Selected artifact'
+      );
+      if (artifactParsed.isErr()) {
+        return artifactParsed;
+      }
+      const installedParsed = parsePackageManifest(
+        installedManifestBytes,
+        'Installed'
+      );
+      if (installedParsed.isErr()) {
+        return installedParsed;
+      }
+      artifactManifest = artifactParsed.value;
+      installedManifest = installedParsed.value;
+    } catch (error) {
+      return Result.err(
+        new ValidationError(
+          'Package source manifest is malformed or missing.',
+          {
+            cause: errorCause(error),
+          }
+        )
+      );
+    }
+    const selectedVersion =
+      params.expected.kind === 'published'
+        ? params.expected.version
+        : artifactManifest.version;
+    if (
+      artifactManifest.name !== params.expected.name ||
+      artifactManifest.version !== selectedVersion ||
+      installedManifest.name !== params.expected.name ||
+      installedManifest.version !== selectedVersion
+    ) {
+      return Result.err(
+        new ConflictError('Package source name or version does not match.', {
+          context: {
+            artifact: {
+              name: artifactManifest.name,
+              version: artifactManifest.version,
+            },
+            installed: {
+              name: installedManifest.name,
+              version: installedManifest.version,
+            },
+            selected: { name: params.expected.name, version: selectedVersion },
+          },
+        })
+      );
+    }
+    if (
+      selectedVersion === undefined ||
+      !exactVersionPattern.test(selectedVersion)
+    ) {
+      return Result.err(
+        new ValidationError('Selected package artifact has no exact version.')
+      );
+    }
+    const artifactFiles = await collectRegularFiles(extracted.value);
+    if (artifactFiles.isErr()) {
+      return artifactFiles;
+    }
+    const matched = await compareInstalledFiles(
+      artifactFiles.value,
+      prepared.value.installedRoot
+    );
+    if (matched.isErr()) {
+      return matched;
+    }
+    return Result.ok({
+      artifactSha256: artifact.value.artifactSha256,
+      contentSha256: matched.value,
+      declaredSpecifier: prepared.value.declaredSpecifier,
+      kind: params.expected.kind,
+      name: params.expected.name,
+      resolvedPackagePath: prepared.value.installedRoot,
+      version: selectedVersion,
+    });
+  } catch (error) {
+    return Result.err(
+      new InternalError('Package source proof failed unexpectedly.', {
+        cause: errorCause(error),
+      })
+    );
+  } finally {
+    try {
+      await rm(tempRoot, { force: true, recursive: true });
+    } catch {
+      // Cleanup must not replace the proof result or its specific error.
+    }
+  }
+};
+
+/**
+ * Prove that one installed downstream package matches an explicitly selected
+ * published or local tarball artifact, without changing the target project.
+ *
+ * @example
+ * ```ts
+ * const proof = await verifyDownstreamPackageSource({
+ *   expected: { kind: 'published', name: '@ontrails/core', version: '0.2.0' },
+ *   root: process.cwd(),
+ * });
+ * if (proof.isErr()) throw proof.error;
+ * ```
+ */
+export const verifyDownstreamPackageSource = async (params: {
+  readonly root: string;
+  readonly expected: RegradePackageSourceExpectation;
+}): Promise<
+  TrailsResult<RegradePackageSourceEvidence, RegradePackageSourceError>
+> => verifyDownstreamPackageSourceWithAcquirer(params, defaultArtifactAcquirer);