@openzeppelin/upgrades-core 1.35.1 → 1.37.0

package/src/cli/cli.test.ts.md

@@ -19,7 +19,9 @@ Generated by [AVA](https://avajs.dev).
       --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.␊
-      --unsafeAllow "<VALIDATION_ERRORS>"  Selectively disable one or more validation errors. Comma-separated list with one or more of the following: state-variable-assignment, state-variable-immutable, external-library-linking, struct-definition, enum-definition, constructor, delegatecall, selfdestruct, missing-public-upgradeto, internal-function-storage␊
+      --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: state-variable-assignment, state-variable-immutable, external-library-linking, struct-definition, enum-definition, constructor, delegatecall, selfdestruct, missing-public-upgradeto, internal-function-storage␊
       --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.␊
     `
@@ -39,7 +41,9 @@ Generated by [AVA](https://avajs.dev).
       --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.␊
-      --unsafeAllow "<VALIDATION_ERRORS>"  Selectively disable one or more validation errors. Comma-separated list with one or more of the following: state-variable-assignment, state-variable-immutable, external-library-linking, struct-definition, enum-definition, constructor, delegatecall, selfdestruct, missing-public-upgradeto, internal-function-storage␊
+      --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: state-variable-assignment, state-variable-immutable, external-library-linking, struct-definition, enum-definition, constructor, delegatecall, selfdestruct, missing-public-upgradeto, internal-function-storage␊
       --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.␊
     `
@@ -187,6 +191,22 @@ Generated by [AVA](https://avajs.dev).
 
 ## validate - single contract, reference
 
+> Snapshot 1
+
+    `Stdout:  ✘  contracts/test/cli/Validate.sol:BecomesBadLayout (upgrades from contracts/test/cli/Validate.sol:StorageV1)␊
+    ␊
+          StorageV1: Deleted \`x\`␊
+            > Keep the variable even if unused␊
+          ␊
+          StorageV1: Deleted \`__gap\`␊
+            > Keep the variable even if unused␊
+    ␊
+    FAILED␊
+    ␊
+    Stderr: `
+
+## validate - single contract, reference with same build info dir
+
 > Snapshot 1
 
     `Stdout:  ✘  contracts/test/cli/Validate.sol:BecomesBadLayout (upgrades from contracts/test/cli/Validate.sol:StorageV1)␊
@@ -304,3 +324,234 @@ Generated by [AVA](https://avajs.dev).
     ␊
     SUCCESS␊
     `
+
+## validate - references other build info dir by command - ok
+
+> Snapshot 1
+
+    {
+      stderr: '',
+      stdout: ` ✔  contracts/test/cli/ValidateBuildInfoV2_Ok.sol:MyContract (upgrades from build-info-v1:contracts/test/cli/ValidateBuildInfoV1.sol:MyContract)␊
+      ␊
+      SUCCESS␊
+      `,
+    }
+
+## validate - references other build info dir by command with fully qualified names - ok
+
+> Snapshot 1
+
+    {
+      stderr: '',
+      stdout: ` ✔  contracts/test/cli/ValidateBuildInfoV2_Ok.sol:MyContract (upgrades from build-info-v1:contracts/test/cli/ValidateBuildInfoV1.sol:MyContract)␊
+      ␊
+      SUCCESS␊
+      `,
+    }
+
+## validate - references other build info dir by command - bad
+
+> Snapshot 1
+
+    `Stdout:  ✘  contracts/test/cli/ValidateBuildInfoV2_Bad.sol:MyContract (upgrades from build-info-v1:contracts/test/cli/ValidateBuildInfoV1.sol:MyContract)␊
+    ␊
+          MyContract: Deleted \`y\`␊
+            > Keep the variable even if unused␊
+          ␊
+          contracts/test/cli/ValidateBuildInfoV2_Bad.sol:6: Upgraded \`__gap\` to an incompatible type␊
+            - Bad storage gap resize from 48 to 49␊
+              Size cannot increase␊
+    ␊
+    FAILED␊
+    ␊
+    Stderr: `
+
+## validate - references other build info dir by command with fully qualified names - bad
+
+> Snapshot 1
+
+    `Stdout:  ✘  contracts/test/cli/ValidateBuildInfoV2_Bad.sol:MyContract (upgrades from build-info-v1:contracts/test/cli/ValidateBuildInfoV1.sol:MyContract)␊
+    ␊
+          MyContract: Deleted \`y\`␊
+            > Keep the variable even if unused␊
+          ␊
+          contracts/test/cli/ValidateBuildInfoV2_Bad.sol:6: Upgraded \`__gap\` to an incompatible type␊
+            - Bad storage gap resize from 48 to 49␊
+              Size cannot increase␊
+    ␊
+    FAILED␊
+    ␊
+    Stderr: `
+
+## validate - references multiple build info dirs by annotation
+
+> Snapshot 1
+
+    `Stdout:  ✘  contracts/test/cli/ValidateBuildInfoV2_Branch_Bad.sol:MyContract (upgrades from build-info-v2:contracts/test/cli/ValidateBuildInfoV2_Ok.sol:MyContract)␊
+    ␊
+          contracts/test/cli/ValidateBuildInfoV2_Branch_Bad.sol:8: Renamed \`z\` to \`zBranch\`␊
+    ␊
+     ✔  contracts/test/cli/ValidateBuildInfoV2_Branch_Ok.sol:MyContract (upgrades from build-info-v1:contracts/test/cli/ValidateBuildInfoV1.sol:MyContract)␊
+    ␊
+    FAILED (2 upgradeable contracts detected, 1 passed, 1 failed)␊
+    ␊
+    Stderr: `
+
+## validate - references multiple build info dirs by annotation - same arg multiple times
+
+> Snapshot 1
+
+    `Stdout:  ✘  contracts/test/cli/ValidateBuildInfoV2_Branch_Bad.sol:MyContract (upgrades from build-info-v2:contracts/test/cli/ValidateBuildInfoV2_Ok.sol:MyContract)␊
+    ␊
+          contracts/test/cli/ValidateBuildInfoV2_Branch_Bad.sol:8: Renamed \`z\` to \`zBranch\`␊
+    ␊
+     ✔  contracts/test/cli/ValidateBuildInfoV2_Branch_Ok.sol:MyContract (upgrades from build-info-v1:contracts/test/cli/ValidateBuildInfoV1.sol:MyContract)␊
+    ␊
+    FAILED (2 upgradeable contracts detected, 1 passed, 1 failed)␊
+    ␊
+    Stderr: `
+
+## validate - references other build info dir by annotation - ok
+
+> Snapshot 1
+
+    {
+      stderr: '',
+      stdout: ` ✔  contracts/test/cli/ValidateBuildInfoV2_Annotation_Ok.sol:MyContract (upgrades from build-info-v1:contracts/test/cli/ValidateBuildInfoV1.sol:MyContract)␊
+      ␊
+      SUCCESS␊
+      `,
+    }
+
+## validate - references other build info dir by annotation - bad
+
+> Snapshot 1
+
+    `Stdout:  ✘  contracts/test/cli/ValidateBuildInfoV2_Annotation_Bad.sol:MyContract (upgrades from build-info-v1:contracts/test/cli/ValidateBuildInfoV1.sol:MyContract)␊
+    ␊
+          MyContract: Deleted \`y\`␊
+            > Keep the variable even if unused␊
+          ␊
+          contracts/test/cli/ValidateBuildInfoV2_Annotation_Bad.sol:7: Upgraded \`__gap\` to an incompatible type␊
+            - Bad storage gap resize from 48 to 49␊
+              Size cannot increase␊
+    ␊
+    FAILED␊
+    ␊
+    Stderr: `
+
+## validate - excludes by pattern - no match
+
+> Snapshot 1
+
+    `Stdout:  ✘  contracts/test/cli/excludes/UsesAbstractUUPS.sol:UsesAbstractUUPS␊
+    ␊
+          contracts/test/cli/excludes/UsesAbstractUUPS.sol:9: Contract \`UsesAbstractUUPS\` has a constructor␊
+              Define an initializer instead␊
+              https://zpl.in/upgrades/error-001␊
+          ␊
+          contracts/test/cli/excludes/AbstractUUPS.sol:11: Contract \`AbstractUUPS\` has a constructor␊
+              Define an initializer instead␊
+              https://zpl.in/upgrades/error-001␊
+          ␊
+          contracts/test/cli/excludes/AbstractUUPS.sol:9: Variable \`z\` is immutable and will be initialized on the implementation␊
+              If by design, annotate with '@custom:oz-upgrades-unsafe-allow state-variable-immutable'␊
+          Otherwise, consider a constant variable or use a mutable variable instead␊
+              https://zpl.in/upgrades/error-005␊
+          ␊
+          contracts/test/cli/excludes/Abstract2.sol:7: Contract \`Abstract2\` has a constructor␊
+              Define an initializer instead␊
+              https://zpl.in/upgrades/error-001␊
+          ␊
+          contracts/test/cli/excludes/Abstract2.sol:5: Variable \`y\` is immutable and will be initialized on the implementation␊
+              If by design, annotate with '@custom:oz-upgrades-unsafe-allow state-variable-immutable'␊
+          Otherwise, consider a constant variable or use a mutable variable instead␊
+              https://zpl.in/upgrades/error-005␊
+          ␊
+          contracts/test/cli/excludes/Abstract1.sol:7: Contract \`Abstract1\` has a constructor␊
+              Define an initializer instead␊
+              https://zpl.in/upgrades/error-001␊
+          ␊
+          contracts/test/cli/excludes/Abstract1.sol:5: Variable \`x\` is immutable and will be initialized on the implementation␊
+              If by design, annotate with '@custom:oz-upgrades-unsafe-allow state-variable-immutable'␊
+          Otherwise, consider a constant variable or use a mutable variable instead␊
+              https://zpl.in/upgrades/error-005␊
+    ␊
+    FAILED (1 upgradeable contract detected, 0 passed, 1 failed)␊
+    ␊
+    Stderr: `
+
+## validate - excludes by pattern - some match
+
+> Snapshot 1
+
+    `Stdout:  ✘  contracts/test/cli/excludes/UsesAbstractUUPS.sol:UsesAbstractUUPS␊
+    ␊
+          contracts/test/cli/excludes/UsesAbstractUUPS.sol:9: Contract \`UsesAbstractUUPS\` has a constructor␊
+              Define an initializer instead␊
+              https://zpl.in/upgrades/error-001␊
+    ␊
+    FAILED (1 upgradeable contract detected, 0 passed, 1 failed)␊
+    ␊
+    Stderr: `
+
+## validate - excludes by pattern - all match
+
+> Snapshot 1
+
+    {
+      stderr: '',
+      stdout: `No upgradeable contracts detected.␊
+      `,
+    }
+
+## validate - excludes by pattern - all match using commas within glob
+
+> Snapshot 1
+
+    {
+      stderr: '',
+      stdout: `No upgradeable contracts detected.␊
+      `,
+    }
+
+## validate - exclude passed multiple times
+
+> Snapshot 1
+
+    {
+      stderr: '',
+      stdout: `No upgradeable contracts detected.␊
+      `,
+    }
+
+## validate - excludes UpgradeableBeacon and its parents by default
+
+> Snapshot 1
+
+    `Stdout:  ✘  contracts/test/cli/excludes/V2Bad1.sol:V2Bad1 (upgrades from contracts/test/cli/excludes/V1.sol:V1)␊
+    ␊
+          V1: Deleted \`x\`␊
+            > Keep the variable even if unused␊
+    ␊
+     ✘  contracts/test/cli/excludes/V2Bad2.sol:V2Bad2 (upgrades from contracts/test/cli/excludes/V1.sol:V1)␊
+    ␊
+          V1: Deleted \`x\`␊
+            > Keep the variable even if unused␊
+    ␊
+    FAILED (2 upgradeable contracts detected, 0 passed, 2 failed)␊
+    ␊
+    Stderr: `
+
+## validate - excludes UpgradeableBeacon and its parents by default, and excludes one contract from layout comparisions
+
+> Snapshot 1
+
+    `Stdout:  ✘  contracts/test/cli/excludes/V2Bad2.sol:V2Bad2 (upgrades from contracts/test/cli/excludes/V1.sol:V1)␊
+    ␊
+          V1: Deleted \`x\`␊
+            > Keep the variable even if unused␊
+    ␊
+    FAILED (1 upgradeable contract detected, 0 passed, 1 failed)␊
+    ␊
+    Stderr: `

package/src/cli/validate/build-info-file.ts

@@ -49,6 +49,11 @@ export interface BuildInfoFile {
    * The Solidity compiler output JSON object.
    */
   output: SolcOutput;
+
+  /**
+   * Short name of the build info dir containing this file.
+   */
+  dirShortName: string;
 }
 
 /**
@@ -57,13 +62,18 @@ export interface BuildInfoFile {
  * @param buildInfoDir Build info directory, or undefined to use the default Hardhat or Foundry build-info dir.
  * @returns The build info files with Solidity compiler input and output.
  */
-export async function getBuildInfoFiles(buildInfoDir?: string) {
+export async function getBuildInfoFiles(buildInfoDir?: string): Promise<BuildInfoFile[]> {
   const dir = await findDir(buildInfoDir);
+  const shortName = path.basename(dir);
   const jsonFiles = await getJsonFiles(dir);
-  return await readBuildInfo(jsonFiles);
+
+  return await readBuildInfo(jsonFiles, shortName);
 }
 
-async function findDir(buildInfoDir: string | undefined) {
+/**
+ * Finds the build info dir if provided, otherwise finds the default Hardhat or Foundry build info dir. Throws an error if no build info files were found in the expected dir.
+ */
+async function findDir(buildInfoDir?: string): Promise<string> {
   if (buildInfoDir !== undefined && !(await hasJsonFiles(buildInfoDir))) {
     throw new ValidateCommandError(
       `The directory '${buildInfoDir}' does not exist or does not contain any build info files.`,
@@ -123,7 +133,7 @@ async function getJsonFiles(dir: string): Promise<string[]> {
   return jsonFiles.map(file => path.join(dir, file));
 }
 
-async function readBuildInfo(buildInfoFilePaths: string[]) {
+async function readBuildInfo(buildInfoFilePaths: string[], dirShortName: string) {
   const buildInfoFiles: BuildInfoFile[] = [];
 
   for (const buildInfoFilePath of buildInfoFilePaths) {
@@ -143,6 +153,7 @@ async function readBuildInfo(buildInfoFilePaths: string[]) {
         input: buildInfoJson.input,
         output: buildInfoJson.output,
         solcVersion: buildInfoJson.solcVersion,
+        dirShortName: dirShortName,
       });
     }
   }

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

@@ -4,7 +4,6 @@ import {
   getContractVersion,
   getStorageLayout,
   ValidationOptions,
-  withValidationDefaults,
   Version,
   ValidationData,
   ValidateUpgradeSafetyOptions,
@@ -17,7 +16,10 @@ import { getUpgradeabilityAssessment } from './upgradeability-assessment';
 import { SourceContract } from './validations';
 import { LayoutCompatibilityReport } from '../../storage/report';
 import { indent } from '../../utils/indent';
-import { SpecifiedContracts } from './validate-upgrade-safety';
+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);
@@ -58,29 +69,32 @@ export class UpgradeableContractReport implements Report {
 }
 
 /**
- * Gets upgradeble contract reports for the upgradeable contracts in the given set of source contracts.
+ * Gets upgradeble contract reports for the upgradeable contracts in the set of source contracts at dictionary key ''.
+ * Reference contracts can come from source contracts at the corresponding dictionary key.
  * Only contracts that are detected as upgradeable will be included in the reports.
  * Reports include upgradeable contracts regardless of whether they pass or fail upgrade safety checks.
  *
- * @param sourceContracts The source contracts to check, which must include all contracts that are referenced by the given contracts. Can also include non-upgradeable contracts, which will be ignored.
+ * @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(
-  sourceContracts: SourceContract[],
+  buildInfoDictionary: BuildInfoDictionary,
   opts: Required<ValidateUpgradeSafetyOptions>,
   specifiedContracts?: SpecifiedContracts,
+  exclude?: string[],
 ) {
   const upgradeableContractReports: UpgradeableContractReport[] = [];
 
   const contractsToReport: SourceContract[] =
-    specifiedContracts !== undefined ? [specifiedContracts.contract] : sourceContracts;
+    specifiedContracts !== undefined ? [specifiedContracts.contract] : buildInfoDictionary[''];
 
   for (const sourceContract of contractsToReport) {
     const upgradeabilityAssessment = getUpgradeabilityAssessment(
       sourceContract,
-      sourceContracts,
+      buildInfoDictionary,
       specifiedContracts?.reference,
     );
     if (opts.requireReference && upgradeabilityAssessment.referenceContract === undefined) {
@@ -90,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);
@@ -118,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;
@@ -129,8 +166,12 @@ function getUpgradeableContractReport(
     const referenceVersion = getContractVersion(referenceContract.validationData, referenceContract.fullyQualifiedName);
     const referenceLayout = getStorageLayout(referenceContract.validationData, referenceVersion);
 
-    reference = referenceContract.fullyQualifiedName;
-    storageLayoutReport = getStorageUpgradeReport(referenceLayout, layout, withValidationDefaults(opts));
+    if (referenceContract.buildInfoDirShortName !== contract.buildInfoDirShortName) {
+      reference = `${referenceContract.buildInfoDirShortName}:${referenceContract.fullyQualifiedName}`;
+    } else {
+      reference = referenceContract.fullyQualifiedName;
+    }
+    storageLayoutReport = getStorageUpgradeReport(referenceLayout, layout, opts);
   }
 
   return new UpgradeableContractReport(contract.fullyQualifiedName, reference, standaloneReport, storageLayoutReport);
@@ -139,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/find-contract.ts

@@ -1,4 +1,6 @@
+import { assert } from '../../utils/assert';
 import { ValidateCommandError } from './error';
+import { BuildInfoDictionary } from './validate-upgrade-safety';
 import { SourceContract } from './validations';
 
 export class ReferenceContractNotFound extends Error {
@@ -12,7 +14,12 @@ export class ReferenceContractNotFound extends Error {
    */
   readonly origin?: string;
 
-  constructor(reference: string, origin?: string) {
+  /**
+   * Build info directories that were also searched.
+   */
+  readonly buildInfoDirs?: string[];
+
+  constructor(reference: string, origin?: string, buildInfoDirs?: string[]) {
     const msg =
       origin !== undefined
         ? `Could not find contract ${reference} referenced in ${origin}.`
@@ -20,11 +27,30 @@ export class ReferenceContractNotFound extends Error {
     super(msg);
     this.reference = reference;
     this.origin = origin;
+    this.buildInfoDirs = buildInfoDirs;
   }
 }
 
-export function findContract(contractName: string, origin: SourceContract | undefined, allContracts: SourceContract[]) {
-  const foundContracts = allContracts.filter(c => c.fullyQualifiedName === contractName || c.name === contractName);
+export function findContract(
+  contractName: string,
+  origin: SourceContract | undefined,
+  buildInfoDictionary: BuildInfoDictionary,
+  onlyMainBuildInfoDir = false,
+) {
+  const foundContracts: SourceContract[] = [];
+  if (onlyMainBuildInfoDir) {
+    if (hasBuildInfoDirWithContractName(contractName) || hasBuildInfoDirWithFullyQualifiedName(contractName)) {
+      throw new ValidateCommandError(
+        `Contract ${contractName} must be specified without a build info directory name`,
+        () => `Build info directory names can only be specified for reference contracts.`,
+      );
+    }
+    foundContracts.push(...buildInfoDictionary[''].filter(c => isMatchFound(contractName, c, '')));
+  } else {
+    for (const [dir, contracts] of Object.entries(buildInfoDictionary)) {
+      foundContracts.push(...contracts.filter(c => isMatchFound(contractName, c, dir)));
+    }
+  }
 
   if (foundContracts.length > 1) {
     const msg =
@@ -39,6 +65,26 @@ export function findContract(contractName: string, origin: SourceContract | unde
   } else if (foundContracts.length === 1) {
     return foundContracts[0];
   } else {
-    throw new ReferenceContractNotFound(contractName, origin?.fullyQualifiedName);
+    throw new ReferenceContractNotFound(contractName, origin?.fullyQualifiedName, Object.keys(buildInfoDictionary));
+  }
+}
+
+function isMatchFound(contractName: string, foundContract: SourceContract, buildInfoDirShortName: string): boolean {
+  let prefix = '';
+  if (buildInfoDirShortName.length > 0) {
+    assert(foundContract.buildInfoDirShortName === buildInfoDirShortName);
+    prefix = `${buildInfoDirShortName}:`;
   }
+  return (
+    `${prefix}${foundContract.fullyQualifiedName}` === contractName || `${prefix}${foundContract.name}` === contractName
+  );
+}
+
+function hasBuildInfoDirWithContractName(contractName: string): boolean {
+  return contractName.split(':').length === 2 && !contractName.includes('.sol:');
+}
+
+function hasBuildInfoDirWithFullyQualifiedName(contractName: string): boolean {
+  const tokens = contractName.split(':');
+  return tokens.length === 3 && tokens[1].endsWith('.sol');
 }

package/src/cli/validate/upgradeability-assessment.ts

@@ -2,6 +2,7 @@ import { getAnnotationArgs, getDocumentation, hasAnnotationTag } from '../../uti
 import { inferInitializable, inferUUPS } from '../../validate/query';
 import { ValidateCommandError } from './error';
 import { findContract } from './find-contract';
+import { BuildInfoDictionary } from './validate-upgrade-safety';
 import { SourceContract } from './validations';
 
 interface AnnotationAssessment {
@@ -17,7 +18,7 @@ export interface UpgradeabilityAssessment {
 
 export function getUpgradeabilityAssessment(
   contract: SourceContract,
-  allContracts: SourceContract[],
+  buildInfoDictionary: BuildInfoDictionary,
   overrideReferenceContract?: SourceContract,
 ): UpgradeabilityAssessment {
   const fullContractName = contract.fullyQualifiedName;
@@ -29,7 +30,7 @@ export function getUpgradeabilityAssessment(
 
   let referenceContract = overrideReferenceContract;
   if (referenceContract === undefined && annotationAssessment.referenceName !== undefined) {
-    referenceContract = findContract(annotationAssessment.referenceName, contract, allContracts);
+    referenceContract = findContract(annotationAssessment.referenceName, contract, buildInfoDictionary);
   }
 
   let isReferenceUUPS = false;

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

@@ -100,7 +100,7 @@ test('invalid annotation args - upgrades', async t => {
 
 test('findSpecifiedContracts - requireReference option without contract', async t => {
   try {
-    findSpecifiedContracts([], withCliDefaults({ requireReference: true }));
+    findSpecifiedContracts({}, withCliDefaults({ requireReference: true }));
   } catch (e: any) {
     t.true(
       e.message.includes(