@openzeppelin/upgrades-core 1.36.0 → 1.37.0

package/src/cli/validate/contract-report.ts

@@ -4,7 +4,6 @@ import {
   getContractVersion,
   getStorageLayout,
   ValidationOptions,
-  withValidationDefaults,
   Version,
   ValidationData,
   ValidateUpgradeSafetyOptions,
@@ -18,6 +17,9 @@ import { SourceContract } from './validations';
 import { LayoutCompatibilityReport } from '../../storage/report';
 import { indent } from '../../utils/indent';
 import { BuildInfoDictionary, SpecifiedContracts } from './validate-upgrade-safety';
+import { minimatch } from 'minimatch';
+import { ValidateCommandError } from './error';
+import { defaultExclude } from './default-exclude';
 
 /**
  * Report for an upgradeable contract.
@@ -29,7 +31,16 @@ export class UpgradeableContractReport implements Report {
     readonly reference: string | undefined,
     readonly standaloneReport: UpgradeableContractErrorReport,
     readonly storageLayoutReport: LayoutCompatibilityReport | undefined,
-  ) {}
+  ) {
+    if (reference === contract) {
+      throw new ValidateCommandError(
+        `The contract ${contract} must not use itself as a reference for storage layout comparisons.`,
+        () => `\
+If this is the first version of your contract, do not specify a reference.
+If this is a subsequent version, keep the previous version of the contract in another file and specify that as the reference, or specify a reference from another build info directory containing the previous version. If you do not have the previous version available, you can skip the storage layout check using the \`unsafeSkipStorageCheck\` option, which is a dangerous option meant to be used as a last resort.`,
+      );
+    }
+  }
 
   get ok(): boolean {
     return this.standaloneReport.ok && (this.storageLayoutReport === undefined || this.storageLayoutReport.ok);
@@ -66,12 +77,14 @@ export class UpgradeableContractReport implements Report {
  * @param buildInfoDictionary Dictionary of build info directories and the source contracts they contain.
  * @param opts The validation options.
  * @param specifiedContracts If provided, only the specified contract (upgrading from its reference contract) will be reported.
+ * @param exclude Exclude validations for contracts in source file paths that match any of the given glob patterns.
  * @returns The upgradeable contract reports.
  */
 export function getContractReports(
   buildInfoDictionary: BuildInfoDictionary,
   opts: Required<ValidateUpgradeSafetyOptions>,
   specifiedContracts?: SpecifiedContracts,
+  exclude?: string[],
 ) {
   const upgradeableContractReports: UpgradeableContractReport[] = [];
 
@@ -91,20 +104,43 @@ export function getContractReports(
     } else if (specifiedContracts !== undefined || upgradeabilityAssessment.upgradeable) {
       const reference = upgradeabilityAssessment.referenceContract;
       const kind = upgradeabilityAssessment.uups ? 'uups' : 'transparent';
-      const report = getUpgradeableContractReport(sourceContract, reference, { ...opts, kind: kind });
+      const report = getUpgradeableContractReport(sourceContract, reference, { ...opts, kind: kind }, exclude);
       if (report !== undefined) {
         upgradeableContractReports.push(report);
+      } else if (specifiedContracts !== undefined) {
+        // If there was no report for the specified contract, it was excluded or is abstract.
+        const userAction =
+          exclude !== undefined
+            ? `Ensure the contract is not abstract and is not excluded by the exclude option.`
+            : `Ensure the contract is not abstract.`;
+        throw new ValidateCommandError(
+          `No validation report found for contract ${specifiedContracts.contract.fullyQualifiedName}`,
+          () => userAction,
+        );
       }
     }
   }
+
   return upgradeableContractReports;
 }
 
+/**
+ * Gets a report for an upgradeable contract.
+ * Returns undefined if the contract is excluded or is abstract.
+ */
 function getUpgradeableContractReport(
   contract: SourceContract,
   referenceContract: SourceContract | undefined,
-  opts: ValidationOptions,
+  opts: Required<ValidationOptions>,
+  exclude?: string[],
 ): UpgradeableContractReport | undefined {
+  const excludeWithDefaults = defaultExclude.concat(exclude ?? []);
+
+  if (excludeWithDefaults.some(glob => minimatch(getPath(contract.fullyQualifiedName), glob))) {
+    debug('Excluding contract: ' + contract.fullyQualifiedName);
+    return undefined;
+  }
+
   let version;
   try {
     version = getContractVersion(contract.validationData, contract.fullyQualifiedName);
@@ -119,7 +155,7 @@ function getUpgradeableContractReport(
   }
 
   debug('Checking: ' + contract.fullyQualifiedName);
-  const standaloneReport = getStandaloneReport(contract.validationData, version, opts);
+  const standaloneReport = getStandaloneReport(contract.validationData, version, opts, excludeWithDefaults);
 
   let reference: string | undefined;
   let storageLayoutReport: LayoutCompatibilityReport | undefined;
@@ -135,7 +171,7 @@ function getUpgradeableContractReport(
     } else {
       reference = referenceContract.fullyQualifiedName;
     }
-    storageLayoutReport = getStorageUpgradeReport(referenceLayout, layout, withValidationDefaults(opts));
+    storageLayoutReport = getStorageUpgradeReport(referenceLayout, layout, opts);
   }
 
   return new UpgradeableContractReport(contract.fullyQualifiedName, reference, standaloneReport, storageLayoutReport);
@@ -144,8 +180,22 @@ function getUpgradeableContractReport(
 function getStandaloneReport(
   data: ValidationData,
   version: Version,
-  opts: ValidationOptions,
+  opts: Required<ValidationOptions>,
+  excludeWithDefaults: string[],
 ): UpgradeableContractErrorReport {
-  const errors = getErrors(data, version, withValidationDefaults(opts));
-  return new UpgradeableContractErrorReport(errors);
+  const allErrors = getErrors(data, version, opts);
+
+  const includeErrors = allErrors.filter(e => {
+    const shouldExclude = excludeWithDefaults.some(glob => minimatch(getPath(e.src), glob));
+    if (shouldExclude) {
+      debug('Excluding error: ' + e.src);
+    }
+    return !shouldExclude;
+  });
+
+  return new UpgradeableContractErrorReport(includeErrors);
+}
+
+function getPath(srcOrFullyQualifiedName: string): string {
+  return srcOrFullyQualifiedName.split(':')[0];
 }

package/src/cli/validate/default-exclude.ts

@@ -0,0 +1,3 @@
+const UPGRADEABLE_BEACON = '**/contracts/proxy/beacon/UpgradeableBeacon.sol' as const;
+
+export const defaultExclude: string[] = [UPGRADEABLE_BEACON] as const;

package/src/cli/validate/validate-upgrade-safety.ts

@@ -28,6 +28,7 @@ export type SpecifiedContracts = {
  * @param reference The name or fully qualified name of the reference contract to use for storage layout comparisons. Can only be used along with `contract`. If not specified, uses the `@custom:oz-upgrades-from` annotation in the contract that is being validated.
  * @param opts Validation options, or undefined to use the default validation options.
  * @param referenceBuildInfoDirs Optional paths of additional build info directories from previous versions of the project to use for storage layout comparisons. When using this option, refer to one of these directories using prefix `<dirName>:` before the contract name or fully qualified name in the `reference` param or `@custom:oz-upgrades-from` annotation, where `<dirName>` is the directory short name. Each directory short name must be unique, including compared to the main build info directory.
+ * @param exclude Exclude validations for contracts in source file paths that match any of the given glob patterns.
  * @returns The project report.
  */
 export async function validateUpgradeSafety(
@@ -36,6 +37,7 @@ export async function validateUpgradeSafety(
   reference?: string,
   opts: ValidateUpgradeSafetyOptions = {},
   referenceBuildInfoDirs?: string[],
+  exclude?: string[],
 ): Promise<ProjectReport> {
   const allOpts = withCliDefaults(opts);
 
@@ -63,7 +65,7 @@ export async function validateUpgradeSafety(
 
   const specifiedContracts = findSpecifiedContracts(buildInfoDictionary, allOpts, contract, reference);
 
-  const contractReports = getContractReports(buildInfoDictionary, allOpts, specifiedContracts);
+  const contractReports = getContractReports(buildInfoDictionary, allOpts, specifiedContracts, exclude);
   return getProjectReport(contractReports, specifiedContracts !== undefined);
 }
 

package/src/cli/validate.test.ts

@@ -110,3 +110,25 @@ test('withDefaults - invalid unsafeAllow', t => {
     )}`,
   });
 });
+
+test('withDefaults - empty unsafeAllow', t => {
+  const parsedArgs = minimist(['validate', 'build-info.json', '--unsafeAllow']);
+  t.throws(() => withDefaults(parsedArgs), {
+    message: `Invalid option: --unsafeAllow cannot be empty`,
+  });
+});
+
+test('withDefaults - unsafeAllow multiple times', t => {
+  const parsedArgs = minimist([
+    'validate',
+    'build-info.json',
+    '--unsafeAllow',
+    'selfdestruct',
+    '--unsafeAllow',
+    'delegatecall',
+    '--unsafeAllow',
+    'constructor',
+  ]);
+  const opts = withDefaults(parsedArgs);
+  t.deepEqual(opts.unsafeAllow, ['selfdestruct', 'delegatecall', 'constructor']);
+});

package/src/cli/validate.ts

@@ -16,8 +16,9 @@ Options:
   --contract <CONTRACT>  The name or fully qualified name of the contract to validate. If not specified, all upgradeable contracts in the build info directory will be validated.
   --reference <REFERENCE_CONTRACT>  Can only be used when the --contract option is also provided. The name or fully qualified name of the reference contract to use for storage layout comparisons. If not specified, uses the @custom:oz-upgrades-from annotation if it is defined in the contract that is being validated.
   --requireReference  Can only be used when the --contract option is also provided. Not compatible with --unsafeSkipStorageCheck. If specified, requires either the --reference option to be provided or the contract to have a @custom:oz-upgrades-from annotation.
-  --referenceBuildInfoDirs  Optional paths of additional build info directories from previous versions of the project to use for storage layout comparisons. When using this option, refer to one of these directories using prefix '<dirName>:' before the contract name or fully qualified name in the --reference option or @custom:oz-upgrades-from annotation, where <dirName> is the directory short name. Each directory short name must be unique, including compared to the main build info directory.
-  --unsafeAllow "<VALIDATION_ERRORS>"  Selectively disable one or more validation errors. Comma-separated list with one or more of the following: ${errorKinds.join(
+  --referenceBuildInfoDirs "<BUILD_INFO_DIR>[,<BUILD_INFO_DIR>...]"  Optional paths of additional build info directories from previous versions of the project to use for storage layout comparisons. When using this option, refer to one of these directories using prefix '<dirName>:' before the contract name or fully qualified name in the --reference option or @custom:oz-upgrades-from annotation, where <dirName> is the directory short name. Each directory short name must be unique, including compared to the main build info directory. If passing in multiple directories, separate them with commas or call the option multiple times, once for each directory.
+  --exclude "<GLOB_PATTERN>" [--exclude "<GLOB_PATTERN>"...]  Exclude validations for contracts in source file paths that match any of the given glob patterns. For example, --exclude "contracts/mocks/**/*.sol". Does not apply to reference contracts. If passing in multiple patterns, call the option multiple times, once for each pattern.
+  --unsafeAllow "<VALIDATION_ERROR>[,<VALIDATION_ERROR>...]"  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.
@@ -34,6 +35,7 @@ export async function main(args: string[]): Promise<void> {
       functionArgs.reference,
       functionArgs.opts,
       functionArgs.referenceBuildInfoDirs,
+      functionArgs.exclude,
     );
     console.log(result.explain());
     process.exitCode = result.ok ? 0 : 1;
@@ -50,7 +52,7 @@ function parseArgs(args: string[]) {
       'unsafeAllowLinkedLibraries',
       'requireReference',
     ],
-    string: ['unsafeAllow', 'contract', 'reference', 'referenceBuildInfoDirs'],
+    string: ['unsafeAllow', 'contract', 'reference', 'referenceBuildInfoDirs', 'exclude'],
     alias: { h: 'help' },
   });
   const extraArgs = parsedArgs._;
@@ -74,6 +76,7 @@ interface FunctionArgs {
   reference?: string;
   opts: Required<ValidateUpgradeSafetyOptions>;
   referenceBuildInfoDirs?: string[];
+  exclude?: string[];
 }
 
 /**
@@ -93,7 +96,8 @@ export function getFunctionArgs(parsedArgs: minimist.ParsedArgs, extraArgs: stri
     const contract = getAndValidateString(parsedArgs, 'contract');
     const reference = getAndValidateString(parsedArgs, 'reference');
     const opts = withDefaults(parsedArgs);
-    const referenceBuildInfoDirs = getAndValidateString(parsedArgs, 'referenceBuildInfoDirs')?.split(/,+/);
+    const referenceBuildInfoDirs = getAndValidateStringArray(parsedArgs, 'referenceBuildInfoDirs', true);
+    const exclude = getAndValidateStringArray(parsedArgs, 'exclude', false);
 
     if (contract === undefined) {
       if (reference !== undefined) {
@@ -102,18 +106,45 @@ export function getFunctionArgs(parsedArgs: minimist.ParsedArgs, extraArgs: stri
         throw new Error('The --requireReference option can only be used along with the --contract option.');
       }
     }
-    return { buildInfoDir, contract, reference, opts, referenceBuildInfoDirs };
+    return { buildInfoDir, contract, reference, opts, referenceBuildInfoDirs, exclude };
   }
 }
 
 function getAndValidateString(parsedArgs: minimist.ParsedArgs, option: string): string | undefined {
   const value = parsedArgs[option];
-  if (value !== undefined && value.trim().length === 0) {
-    throw new Error(`Invalid option: --${option} cannot be empty`);
+  if (value !== undefined) {
+    assertNonEmptyString(value, option);
+  }
+  return value;
+}
+
+function getAndValidateStringArray(
+  parsedArgs: minimist.ParsedArgs,
+  option: string,
+  useCommaDelimiter: boolean,
+): string[] | undefined {
+  const value = parsedArgs[option];
+  if (value !== undefined) {
+    if (Array.isArray(value)) {
+      return value;
+    } else {
+      assertNonEmptyString(value, option);
+      if (useCommaDelimiter) {
+        return value.split(/[\s,]+/);
+      } else {
+        return [value];
+      }
+    }
   }
   return value;
 }
 
+function assertNonEmptyString(value: unknown, option: string) {
+  if (typeof value !== 'string' || value.trim().length === 0) {
+    throw new Error(`Invalid option: --${option} cannot be empty`);
+  }
+}
+
 function validateOptions(parsedArgs: minimist.ParsedArgs) {
   const invalidArgs = Object.keys(parsedArgs).filter(
     key =>
@@ -130,6 +161,7 @@ function validateOptions(parsedArgs: minimist.ParsedArgs) {
         'reference',
         'requireReference',
         'referenceBuildInfoDirs',
+        'exclude',
       ].includes(key),
   );
   if (invalidArgs.length > 0) {
@@ -137,18 +169,13 @@ function validateOptions(parsedArgs: minimist.ParsedArgs) {
   }
 }
 
-function getUnsafeAllowKinds(unsafeAllow: string | undefined): ValidationError['kind'][] {
+function getUnsafeAllowKinds(parseArgs: minimist.ParsedArgs): ValidationError['kind'][] {
   type errorKindsType = (typeof errorKinds)[number];
 
-  if (unsafeAllow === undefined) {
-    return [];
-  }
-
-  const unsafeAllowTokens: string[] = unsafeAllow.split(/[\s,]+/);
+  const unsafeAllowTokens: string[] = getAndValidateStringArray(parseArgs, 'unsafeAllow', true) ?? [];
   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(
+      `Invalid option: --unsafeAllow "${parseArgs['unsafeAllow']}". Supported values for the --unsafeAllow option are: ${errorKinds.join(
         ', ',
       )}`,
     );
@@ -164,7 +191,7 @@ export function withDefaults(parsedArgs: minimist.ParsedArgs): Required<Validate
     unsafeSkipStorageCheck: parsedArgs['unsafeSkipStorageCheck'],
     unsafeAllowCustomTypes: parsedArgs['unsafeAllowCustomTypes'],
     unsafeAllowLinkedLibraries: parsedArgs['unsafeAllowLinkedLibraries'],
-    unsafeAllow: getUnsafeAllowKinds(parsedArgs['unsafeAllow']),
+    unsafeAllow: getUnsafeAllowKinds(parsedArgs),
     requireReference: parsedArgs['requireReference'],
   };
 

package/src/storage/extract.ts

@@ -203,7 +203,8 @@ export function loadLayoutType(typeName: TypeName | null | undefined, layout: St
 function getRetypedRenamed(varDecl: VariableDeclaration) {
   let retypedFrom, renamedFrom;
   if ('documentation' in varDecl) {
-    const docs = typeof varDecl.documentation === 'string' ? varDecl.documentation : varDecl.documentation?.text ?? '';
+    const docs =
+      typeof varDecl.documentation === 'string' ? varDecl.documentation : (varDecl.documentation?.text ?? '');
     for (const { groups } of execall(
       /^\s*(?:@(?<title>\w+)(?::(?<tag>[a-z][a-z-]*))? )?(?<args>(?:(?!^\s@\w+)[^])*)/m,
       docs,

package/src/utils/annotations.ts

@@ -48,7 +48,7 @@ export function getAnnotationArgs(doc: string, tag: string, supportedArgs?: read
  */
 export function getDocumentation(node: Node) {
   if ('documentation' in node) {
-    return typeof node.documentation === 'string' ? node.documentation : node.documentation?.text ?? '';
+    return typeof node.documentation === 'string' ? node.documentation : (node.documentation?.text ?? '');
   } else {
     return '';
   }