@openzeppelin/upgrades-core 1.26.1 → 1.27.0

package/src/cli/validate.test.ts

@@ -0,0 +1,112 @@
+import test from 'ava';
+
+import minimist from 'minimist';
+import { getFunctionArgs, withDefaults } from './validate';
+import sinon from 'sinon';
+import { errorKinds } from '../validate/run';
+
+test.afterEach.always(() => {
+  sinon.restore();
+});
+
+test('getFunctionArgs - invalid command', t => {
+  const parsedArgs = minimist(['invalid']);
+  const extraArgs = parsedArgs._;
+  t.throws(() => getFunctionArgs(parsedArgs, extraArgs), {
+    message: `Invalid command: invalid. Supported commands are: validate`,
+  });
+});
+
+test('getFunctionArgs - invalid options', async t => {
+  const parsedArgs = minimist(['validate', 'build-info.json', '--foo', '--bar', 'xyz']);
+  const extraArgs = parsedArgs._;
+  t.throws(() => getFunctionArgs(parsedArgs, extraArgs), {
+    message: `Invalid options: foo, bar`,
+  });
+});
+
+test('getFunctionArgs - command only', t => {
+  const parsedArgs = minimist(['validate']);
+  const extraArgs = parsedArgs._;
+  const functionArgs = getFunctionArgs(parsedArgs, extraArgs);
+  if (functionArgs === undefined) {
+    t.fail();
+  } else {
+    t.is(functionArgs.buildInfoDir, undefined);
+    t.is(functionArgs.opts.unsafeAllowRenames, false);
+    t.is(functionArgs.opts.unsafeSkipStorageCheck, false);
+    t.is(functionArgs.opts.unsafeAllowCustomTypes, false);
+    t.is(functionArgs.opts.unsafeAllowLinkedLibraries, false);
+    t.deepEqual(functionArgs.opts.unsafeAllow, []);
+  }
+});
+
+test('getFunctionArgs - command with arg', t => {
+  const parsedArgs = minimist(['validate', 'build-info.json']);
+  const extraArgs = parsedArgs._;
+  const functionArgs = getFunctionArgs(parsedArgs, extraArgs);
+  if (functionArgs === undefined) {
+    t.fail();
+  } else {
+    t.is(functionArgs.buildInfoDir, 'build-info.json');
+    t.is(functionArgs.opts.unsafeAllowRenames, false);
+    t.is(functionArgs.opts.unsafeSkipStorageCheck, false);
+    t.is(functionArgs.opts.unsafeAllowCustomTypes, false);
+    t.is(functionArgs.opts.unsafeAllowLinkedLibraries, false);
+    t.deepEqual(functionArgs.opts.unsafeAllow, []);
+  }
+});
+
+test('withDefaults - empty', t => {
+  const parsedArgs = minimist(['validate', 'build-info.json']);
+  const opts = withDefaults(parsedArgs);
+  t.is(opts.unsafeAllowRenames, false);
+  t.is(opts.unsafeSkipStorageCheck, false);
+  t.is(opts.unsafeAllowCustomTypes, false);
+  t.is(opts.unsafeAllowLinkedLibraries, false);
+  t.deepEqual(opts.unsafeAllow, []);
+});
+
+test('withDefaults - some', t => {
+  const parsedArgs = minimist([
+    'validate',
+    'build-info.json',
+    '--unsafeAllowRenames',
+    '--unsafeAllow',
+    'selfdestruct, delegatecall,constructor',
+  ]);
+  const opts = withDefaults(parsedArgs);
+  t.is(opts.unsafeAllowRenames, true);
+  t.is(opts.unsafeSkipStorageCheck, false);
+  t.is(opts.unsafeAllowCustomTypes, false);
+  t.is(opts.unsafeAllowLinkedLibraries, false);
+  t.deepEqual(opts.unsafeAllow, ['selfdestruct', 'delegatecall', 'constructor']);
+});
+
+test('withDefaults - all', t => {
+  const parsedArgs = minimist([
+    'validate',
+    'build-info.json',
+    '--unsafeAllowRenames',
+    '--unsafeSkipStorageCheck',
+    '--unsafeAllowCustomTypes',
+    '--unsafeAllowLinkedLibraries',
+    '--unsafeAllow',
+    ...errorKinds,
+  ]);
+  const opts = withDefaults(parsedArgs);
+  t.is(opts.unsafeAllowRenames, true);
+  t.is(opts.unsafeSkipStorageCheck, true);
+  t.is(opts.unsafeAllowCustomTypes, true);
+  t.is(opts.unsafeAllowLinkedLibraries, true);
+  t.true(opts.unsafeAllow.every((kind: string) => errorKinds.includes(kind as typeof errorKinds[number])));
+});
+
+test('withDefaults - invalid unsafeAllow', t => {
+  const parsedArgs = minimist(['validate', 'build-info.json', '--unsafeAllow', 'foo']);
+  t.throws(() => withDefaults(parsedArgs), {
+    message: `Invalid option: --unsafeAllow "foo". Supported values for the --unsafeAllow option are: ${errorKinds.join(
+      ', ',
+    )}`,
+  });
+});

package/src/cli/validate.ts

@@ -0,0 +1,134 @@
+import minimist from 'minimist';
+
+import { ValidateUpgradeSafetyOptions, validateUpgradeSafety } from '.';
+import { withValidationDefaults } from '..';
+import { ValidationError, errorKinds } from '../validate/run';
+import debug from '../utils/debug';
+
+const USAGE = 'Usage: npx @openzeppelin/upgrades-core validate [<BUILD_INFO_DIR>] [<OPTIONS>]';
+const DETAILS = `
+Detects upgradeable contracts from a build info directory and validates whether they are upgrade safe.
+
+Arguments:
+  <BUILD_INFO_DIR>  Optional path to the build info directory which contains JSON files with Solidity compiler input and output. Defaults to 'artifacts/build-info' for Hardhat projects or 'out/build-info' for Foundry projects. If your project uses a custom output directory, you must specify its build info directory here.
+
+Options:
+  --unsafeAllow "<VALIDATION_ERRORS>"  Selectively disable one or more validation errors. Comma-separated list with one or more of the following: ${errorKinds.join(
+    ', ',
+  )}
+  --unsafeAllowRenames  Configure storage layout check to allow variable renaming.
+  --unsafeSkipStorageCheck  Skips checking for storage layout compatibility errors. This is a dangerous option meant to be used as a last resort.`;
+
+export async function main(args: string[]): Promise<void> {
+  const { parsedArgs, extraArgs } = parseArgs(args);
+
+  if (!help(parsedArgs, extraArgs)) {
+    const functionArgs = getFunctionArgs(parsedArgs, extraArgs);
+    const result = await validateUpgradeSafety(functionArgs.buildInfoDir, functionArgs.opts);
+    console.log(result.explain());
+    process.exitCode = result.ok ? 0 : 1;
+  }
+}
+
+function parseArgs(args: string[]) {
+  const parsedArgs = minimist(args, {
+    boolean: [
+      'help',
+      'unsafeAllowRenames',
+      'unsafeSkipStorageCheck',
+      'unsafeAllowCustomTypes',
+      'unsafeAllowLinkedLibraries',
+    ],
+    string: ['unsafeAllow'],
+    alias: { h: 'help' },
+  });
+  const extraArgs = parsedArgs._;
+  debug('parsedArgs', parsedArgs);
+  return { parsedArgs, extraArgs };
+}
+
+function help(parsedArgs: minimist.ParsedArgs, extraArgs: string[]): boolean {
+  if (extraArgs.length === 0 || parsedArgs['help']) {
+    console.log(USAGE);
+    console.log(DETAILS);
+    return true;
+  } else {
+    return false;
+  }
+}
+
+interface FunctionArgs {
+  buildInfoDir?: string;
+  opts: Required<ValidateUpgradeSafetyOptions>;
+}
+
+/**
+ * Gets and validates function arguments and options.
+ * @returns Function arguments
+ * @throws Error if any arguments or options are invalid.
+ */
+export function getFunctionArgs(parsedArgs: minimist.ParsedArgs, extraArgs: string[]): FunctionArgs {
+  if (extraArgs.length === 0) {
+    throw new Error('Missing command. Supported commands are: validate');
+  } else if (extraArgs[0] !== 'validate') {
+    throw new Error(`Invalid command: ${extraArgs[0]}. Supported commands are: validate`);
+  } else if (extraArgs.length > 2) {
+    throw new Error('The validate command takes only one argument: the build info directory.');
+  } else {
+    const buildInfoDir = extraArgs.length === 1 ? undefined : extraArgs[1];
+    const opts = withDefaults(parsedArgs);
+    return { buildInfoDir, opts };
+  }
+}
+
+function validateOptions(parsedArgs: minimist.ParsedArgs) {
+  const invalidArgs = Object.keys(parsedArgs).filter(
+    key =>
+      ![
+        'help',
+        'h',
+        '_',
+        'unsafeAllowRenames',
+        'unsafeSkipStorageCheck',
+        'unsafeAllowCustomTypes',
+        'unsafeAllowLinkedLibraries',
+        'unsafeAllow',
+      ].includes(key),
+  );
+  if (invalidArgs.length > 0) {
+    throw new Error(`Invalid options: ${invalidArgs.join(', ')}`);
+  }
+}
+
+function getUnsafeAllowKinds(unsafeAllow: string | undefined): ValidationError['kind'][] {
+  type errorKindsType = typeof errorKinds[number];
+
+  if (unsafeAllow === undefined) {
+    return [];
+  }
+
+  const unsafeAllowTokens: string[] = unsafeAllow.split(/[\s,]+/);
+  if (unsafeAllowTokens.some(token => !errorKinds.includes(token as errorKindsType))) {
+    // This includes empty strings
+    throw new Error(
+      `Invalid option: --unsafeAllow "${unsafeAllow}". Supported values for the --unsafeAllow option are: ${errorKinds.join(
+        ', ',
+      )}`,
+    );
+  }
+  return unsafeAllowTokens as errorKindsType[];
+}
+
+export function withDefaults(parsedArgs: minimist.ParsedArgs): Required<ValidateUpgradeSafetyOptions> {
+  validateOptions(parsedArgs);
+
+  const allOpts: Required<ValidateUpgradeSafetyOptions> = {
+    unsafeAllowRenames: parsedArgs['unsafeAllowRenames'],
+    unsafeSkipStorageCheck: parsedArgs['unsafeSkipStorageCheck'],
+    unsafeAllowCustomTypes: parsedArgs['unsafeAllowCustomTypes'],
+    unsafeAllowLinkedLibraries: parsedArgs['unsafeAllowLinkedLibraries'],
+    unsafeAllow: getUnsafeAllowKinds(parsedArgs['unsafeAllow']),
+  };
+
+  return withValidationDefaults(allOpts);
+}

package/src/index.ts

@@ -55,3 +55,5 @@ export {
   PrepareUpgradeRequiresKindError,
   assertNotProxy,
 } from './usage-error';
+
+export { ValidateUpgradeSafetyOptions, validateUpgradeSafety, ProjectReport, ReferenceContractNotFound } from './cli';

package/src/manifest.test.ts

@@ -104,7 +104,8 @@ test.serial('rename manifest', async t => {
   await deleteManifests(t, id);
 });
 
-test.serial('rename hardhat from unknown to dev manifest', async t => {
+// This test is not working on some Linux configurations ('EXDEV: cross-device link not permitted')
+test.skip('rename hardhat from unknown to dev manifest', async t => {
   const id = 31337;
 
   await deleteFile(t, `.openzeppelin/unknown-${id}.json`);

package/src/utils/annotations.ts

@@ -0,0 +1,47 @@
+import { execall } from './execall';
+import { Node } from 'solidity-ast/node';
+
+/**
+ * Get args from the doc string matching the given tag.
+ *
+ * @param doc The doc string to parse
+ * @param tag The tag to match
+ * @param supportedArgs The list of supported args, or undefined if all args are supported
+ */
+export function getAnnotationArgs(doc: string, tag: string, supportedArgs?: readonly string[]) {
+  const result: string[] = [];
+  for (const { groups } of execall(
+    /^\s*(?:@(?<title>\w+)(?::(?<tag>[a-z][a-z-]*))? )?(?<args>(?:(?!^\s*@\w+)[^])*)/m,
+    doc,
+  )) {
+    if (groups && groups.title === 'custom' && groups.tag === tag) {
+      const trimmedArgs = groups.args.trim();
+      if (trimmedArgs.length > 0) {
+        result.push(...trimmedArgs.split(/\s+/));
+      }
+    }
+  }
+
+  if (supportedArgs !== undefined) {
+    result.forEach(arg => {
+      if (!supportedArgs.includes(arg)) {
+        throw new Error(`NatSpec: ${tag} argument not recognized: ${arg}`);
+      }
+    });
+  }
+
+  return result;
+}
+
+/**
+ * Get the documentation string for the given node.
+ * @param node The node
+ * @returns The documentation string, or an empty string if the node has no documentation
+ */
+export function getDocumentation(node: Node) {
+  if ('documentation' in node) {
+    return typeof node.documentation === 'string' ? node.documentation : node.documentation?.text ?? '';
+  } else {
+    return '';
+  }
+}

package/src/utils/contract-name.ts

@@ -0,0 +1,3 @@
+export function getFullyQualifiedName(source: string, contractName: string) {
+  return `${source}:${contractName}`;
+}

package/src/validate/index.ts

@@ -12,6 +12,7 @@ export {
   getErrors,
   isUpgradeSafe,
   inferProxyKind,
+  inferInitializable,
 } from './query';
 export { UpgradeableContractErrorReport } from './report';
 

package/src/validate/query.ts

@@ -1,5 +1,5 @@
 import { Version, getVersion } from '../version';
-import { ValidationRunData, ValidationError, isOpcodeError } from './run';
+import { ValidationRunData, ValidationError, isOpcodeError, ContractValidation } from './run';
 import { StorageLayout } from '../storage/layout';
 import { unlinkBytecode } from '../link-refs';
 import { ValidationOptions, processExceptions } from './overrides';
@@ -186,13 +186,26 @@ export function isUpgradeSafe(data: ValidationData, version: Version): boolean {
   return getErrors(dataV3, version).length == 0;
 }
 
+export function inferUUPS(runValidation: ValidationRunData, fullContractName: string): boolean {
+  const methods = getAllMethods(runValidation, fullContractName);
+  return methods.includes(upgradeToSignature);
+}
+
 export function inferProxyKind(data: ValidationData, version: Version): ProxyDeployment['kind'] {
   const dataV3 = normalizeValidationData(data);
   const [fullContractName, runValidation] = getContractNameAndRunValidation(dataV3, version);
-  const methods = getAllMethods(runValidation, fullContractName);
-  if (methods.includes(upgradeToSignature)) {
+  if (inferUUPS(runValidation, fullContractName)) {
     return 'uups';
   } else {
     return 'transparent';
   }
 }
+
+/**
+ * Whether the contract inherits any contract named "Initializable"
+ * @param contractValidation The validation result for the contract
+ * @return true if the contract inheritss any contract whose fully qualified name ends with ":Initializable"
+ */
+export function inferInitializable(contractValidation: ContractValidation) {
+  return contractValidation.inherit.some(c => c.endsWith(':Initializable'));
+}

package/src/validate/run.ts

@@ -11,6 +11,8 @@ import { Version, getVersion } from '../version';
 import { extractLinkReferences, LinkReference } from '../link-refs';
 import { extractStorageLayout } from '../storage/extract';
 import { StorageLayout } from '../storage/layout';
+import { getFullyQualifiedName } from '../utils/contract-name';
+import { getAnnotationArgs as getSupportedAnnotationArgs, getDocumentation } from '../utils/annotations';
 
 export type ValidationRunData = Record<string, ContractValidation>;
 
@@ -26,7 +28,7 @@ export interface ContractValidation {
   solcVersion?: string;
 }
 
-const errorKinds = [
+export const errorKinds = [
   'state-variable-assignment',
   'state-variable-immutable',
   'external-library-linking',
@@ -92,52 +94,18 @@ interface ValidationErrorUpgradeability extends ValidationErrorBase {
   kind: 'missing-public-upgradeto';
 }
 
-function* execall(re: RegExp, text: string) {
-  re = new RegExp(re, re.flags + (re.sticky ? '' : 'y'));
-  while (true) {
-    const match = re.exec(text);
-    if (match && match[0] !== '') {
-      yield match;
-    } else {
-      break;
-    }
-  }
-}
-
 function getAllowed(node: Node, reachable: boolean): string[] {
   if ('documentation' in node) {
     const tag = `oz-upgrades-unsafe-allow${reachable ? '-reachable' : ''}`;
-    const doc = typeof node.documentation === 'string' ? node.documentation : node.documentation?.text ?? '';
+    const doc = getDocumentation(node);
     return getAnnotationArgs(doc, tag);
   } else {
     return [];
   }
 }
 
-/**
- * Get args from the doc string matching the given tag
- */
 export function getAnnotationArgs(doc: string, tag: string) {
-  const result: string[] = [];
-  for (const { groups } of execall(
-    /^\s*(?:@(?<title>\w+)(?::(?<tag>[a-z][a-z-]*))? )?(?<args>(?:(?!^\s*@\w+)[^])*)/m,
-    doc,
-  )) {
-    if (groups && groups.title === 'custom' && groups.tag === tag) {
-      const trimmedArgs = groups.args.trim();
-      if (trimmedArgs.length > 0) {
-        result.push(...trimmedArgs.split(/\s+/));
-      }
-    }
-  }
-
-  result.forEach(arg => {
-    if (!(errorKinds as readonly string[]).includes(arg)) {
-      throw new Error(`NatSpec: ${tag} argument not recognized: ${arg}`);
-    }
-  });
-
-  return result;
+  return getSupportedAnnotationArgs(doc, tag, errorKinds);
 }
 
 function skipCheckReachable(error: string, node: Node): boolean {
@@ -149,10 +117,6 @@ function skipCheck(error: string, node: Node): boolean {
   return getAllowed(node, false).includes(error) || getAllowed(node, true).includes(error);
 }
 
-function getFullyQualifiedName(source: string, contractName: string) {
-  return `${source}:${contractName}`;
-}
-
 export function validate(solcOutput: SolcOutput, decodeSrc: SrcDecoder, solcVersion?: string): ValidationRunData {
   const validation: ValidationRunData = {};
   const fromId: Record<number, string> = {};