@openzeppelin/upgrades-core 1.46.0 → 1.47.0

package/src/storage/compare.ts

@@ -203,12 +203,11 @@ export class StorageLayoutComparator {
       original.label !== updated.renamedFrom &&
       (updated.label !== original.label ||
         (updated.renamedFrom !== undefined && updated.renamedFrom !== original.renamedFrom));
-    const typeChange =
-      !this.isRetypedFromOriginal(original, updated) &&
-      this.getTypeChange(original.type, updated.type, { allowAppend: false });
+    const retypedFromOriginal = this.isRetypedFromOriginal(original, updated);
+    const typeChange = !retypedFromOriginal && this.getTypeChange(original.type, updated.type, { allowAppend: false });
     const layoutChange = this.getLayoutChange(original, updated);
 
-    if (updated.retypedFrom && layoutChange && (!layoutChange.uncertain || !layoutChange.knownCompatible)) {
+    if (retypedFromOriginal && layoutChange && (!layoutChange.uncertain || !layoutChange.knownCompatible)) {
       return { kind: 'layoutchange', original, updated, change: layoutChange, cost: LAYOUTCHANGE_COST };
     } else if (nameChange && endMatchesGap(original, updated)) {
       // original is a gap that was consumed by a non-gap ending at the same slot, which is safe

package/src/storage/extract.ts

@@ -8,12 +8,14 @@ import {
   TypeName,
 } from 'solidity-ast';
 import { isNodeType, findAll, ASTDereferencer } from 'solidity-ast/utils';
-import { StorageLayout, StructMember, TypeItem, isStructMembers, EnumMember } from './layout';
+import { StorageLayout, StorageField, StructMember, TypeItem, isStructMembers, EnumMember } from './layout';
 import { normalizeTypeIdentifier } from '../utils/type-id';
 import { SrcDecoder } from '../src-decoder';
 import { mapValues } from '../utils/map-values';
 import { pick } from '../utils/pick';
 import { execall } from '../utils/execall';
+import { ANNOTATION_REGEX, getDocumentation } from '../utils/annotations';
+import { StructDocsResolver } from '../utils/struct-member-docs';
 import { loadNamespaces } from './namespace';
 import { UpgradesError } from '../error';
 import { resolveBaseSlot } from '../utils/erc7201-builtin';
@@ -28,6 +30,7 @@ export interface CompilationContext {
   deref: ASTDereferencer;
   contractDef: ContractDefinition;
   storageLayout?: StorageLayout;
+  structDocs?: StructDocsResolver;
 }
 
 export function extractStorageLayout(
@@ -36,6 +39,7 @@ export function extractStorageLayout(
   deref: ASTDereferencer,
   storageLayout?: StorageLayout,
   namespacedContext?: CompilationContext,
+  structDocs?: StructDocsResolver,
 ): StorageLayout {
   const layout: StorageLayout = { storage: [], types: {}, layoutVersion: currentLayoutVersion, flat: false };
 
@@ -72,7 +76,7 @@ export function extractStorageLayout(
       const { varDecl, contract } = origin;
       const { renamedFrom, retypedFrom } = getRetypedRenamed(varDecl);
       // Solc layout doesn't bring members for enums so we get them using the ast method
-      loadLayoutType(varDecl.typeName, layout, deref);
+      loadLayoutType(varDecl.typeName, layout, deref, structDocs);
       const { label, offset, slot, type } = storage;
       const src = decodeSrc(varDecl);
       layout.storage.push({ label, offset, slot, type, contract, src, retypedFrom, renamedFrom });
@@ -93,13 +97,13 @@ export function extractStorageLayout(
             renamedFrom,
           });
 
-          loadLayoutType(varDecl.typeName, layout, deref);
+          loadLayoutType(varDecl.typeName, layout, deref, structDocs);
         }
       }
     }
   }
 
-  const origContext = { deref, contractDef, storageLayout };
+  const origContext = { deref, contractDef, storageLayout, structDocs };
   loadNamespaces(decodeSrc, layout, origContext, namespacedContext);
 
   return layout;
@@ -201,7 +205,12 @@ function getOriginContract(contract: ContractDefinition, astId: number | undefin
   }
 }
 
-export function loadLayoutType(typeName: TypeName | null | undefined, layout: StorageLayout, deref: ASTDereferencer) {
+export function loadLayoutType(
+  typeName: TypeName | null | undefined,
+  layout: StorageLayout,
+  deref: ASTDereferencer,
+  structDocs?: StructDocsResolver,
+) {
   // Note: A UserDefinedTypeName can also refer to a ContractDefinition but we won't care about those.
   const derefUserDefinedType = deref(['StructDefinition', 'EnumDefinition', 'UserDefinedValueTypeDefinition']);
 
@@ -224,6 +233,10 @@ export function loadLayoutType(typeName: TypeName | null | undefined, layout: St
         layout.types[type].underlying = typeDef.underlyingType.typeDescriptions.typeIdentifier ?? undefined;
       } else {
         layout.types[type].members ??= getTypeMembers(typeDef);
+        if (typeDef.nodeType === 'StructDefinition' && structDocs !== undefined) {
+          // Add annotations whether the members came from the compiler's storage layout or from the AST above
+          setStructMemberAnnotations(layout.types[type], structDocs(typeDef));
+        }
       }
 
       // Recursively look for the types referenced in this definition and add them to the queue.
@@ -238,22 +251,46 @@ export function loadLayoutType(typeName: TypeName | null | undefined, layout: St
 }
 
 function getRetypedRenamed(varDecl: VariableDeclaration) {
+  return getRetypedRenamedFromDoc(getDocumentation(varDecl));
+}
+
+export function getRetypedRenamedFromDoc(doc: string) {
   let retypedFrom, renamedFrom;
-  if ('documentation' in varDecl) {
-    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,
-    )) {
-      if (groups?.title === 'custom') {
-        if (groups.tag === 'oz-retyped-from') {
-          retypedFrom = groups.args.trim();
-        } else if (groups.tag === 'oz-renamed-from') {
-          renamedFrom = groups.args.trim();
-        }
+  for (const { groups } of execall(ANNOTATION_REGEX, doc)) {
+    if (groups?.title === 'custom') {
+      if (groups.tag === 'oz-retyped-from') {
+        retypedFrom = groups.args.trim();
+      } else if (groups.tag === 'oz-renamed-from') {
+        renamedFrom = groups.args.trim();
       }
     }
   }
   return { retypedFrom, renamedFrom };
 }
+
+/**
+ * Sets `renamedFrom` and `retypedFrom` on the given layout field (a namespace member or a member of a struct type)
+ * from the annotations in that member's NatSpec, for the storage layout comparison to use. Each field is only set if
+ * the NatSpec has the corresponding annotation, so unannotated members have no `renamedFrom` or `retypedFrom` key.
+ */
+export function setMemberAnnotations(field: StorageField, docs: Map<string, string>) {
+  const doc = docs.get(field.label);
+  if (doc !== undefined) {
+    const { retypedFrom, renamedFrom } = getRetypedRenamedFromDoc(doc);
+    if (retypedFrom !== undefined) {
+      field.retypedFrom = retypedFrom;
+    }
+    if (renamedFrom !== undefined) {
+      field.renamedFrom = renamedFrom;
+    }
+  }
+}
+
+function setStructMemberAnnotations(typeItem: TypeItem, docs: Map<string, string> | undefined) {
+  if (docs !== undefined) {
+    assert(typeItem.members !== undefined && isStructMembers(typeItem.members));
+    for (const member of typeItem.members) {
+      setMemberAnnotations(member, docs);
+    }
+  }
+}

package/src/storage/namespace.ts

@@ -5,7 +5,7 @@ import { StorageItem, StorageLayout, TypeItem, isStructMembers } from './layout'
 import { SrcDecoder } from '../src-decoder';
 import { getAnnotationArgs, getDocumentation, hasAnnotationTag } from '../utils/annotations';
 import { Node } from 'solidity-ast/node';
-import { CompilationContext, getTypeMembers, loadLayoutType } from './extract';
+import { CompilationContext, getTypeMembers, loadLayoutType, setMemberAnnotations } from './extract';
 import { UpgradesError } from '../error';
 import * as versions from 'compare-versions';
 import { calculateERC7201StorageLocation, ERC7201_FORMULA_PREFIX } from '../utils/erc7201';
@@ -49,7 +49,9 @@ export function loadNamespaces(
   const linearized = namespacedLinearized ?? origLinearized;
   for (const [i, contractDef] of linearized.entries()) {
     const origContractDef = origLinearized[i];
-    const contractContext = { ...context, contractDef };
+    // Member documentation is read from the original sources, so the resolver comes from the original context
+    // even when the namespaced context is used to look up the structs.
+    const contractContext = { ...context, contractDef, structDocs: origContext.structDocs };
     addContractNamespacesWithSrc(
       namespacesWithSrc,
       decodeSrc,
@@ -248,6 +250,7 @@ function getNamespacedStorageItems(
   origContractDef: ContractDefinition,
 ): StorageItem[] {
   const storageItems: StorageItem[] = [];
+  const docs = context.structDocs === undefined ? undefined : context.structDocs(node);
 
   for (const astMember of getTypeMembers(node, { typeName: true })) {
     const item: StorageItem = {
@@ -257,6 +260,10 @@ function getNamespacedStorageItems(
       src: decodeSrc({ src: getOriginalMemberSrc(node.canonicalName, astMember.label, origContractDef) }),
     };
 
+    if (docs !== undefined) {
+      setMemberAnnotations(item, docs);
+    }
+
     const layoutMember = findLayoutStructMember(
       context.storageLayout?.types ?? {},
       node.canonicalName,
@@ -272,7 +279,7 @@ function getNamespacedStorageItems(
 
     // If context is namespaced, we have storage layout, and this will fill in enum members just like in extractStorageLayout.
     // If context is original, this will add the types from the namespace structs to the layout.
-    loadLayoutType(astMember.typeName, layout, context.deref);
+    loadLayoutType(astMember.typeName, layout, context.deref, context.structDocs);
   }
   return storageItems;
 }

package/src/storage/report-rename-retype.test.ts

@@ -9,6 +9,8 @@ import { getStorageUpgradeErrors } from '.';
 
 interface Context {
   extractStorageLayout: (contract: string) => ReturnType<typeof extractStorageLayout>;
+  // Without the compiler's storage layout, the variables have no slots
+  extractStorageLayoutWithoutSlots: (contract: string) => ReturnType<typeof extractStorageLayout>;
 }
 
 const test = _test as TestFn<Context>;
@@ -50,6 +52,8 @@ test.before(async t => {
 
   t.context.extractStorageLayout = name =>
     extractStorageLayout(contracts[name], dummyDecodeSrc, deref[name], storageLayout[name]);
+  t.context.extractStorageLayoutWithoutSlots = name =>
+    extractStorageLayout(contracts[name], dummyDecodeSrc, deref[name]);
 });
 
 function getReport(original: StorageLayout, updated: StorageLayout) {
@@ -130,3 +134,40 @@ test('retype with layout change', t => {
   t.false(report.ok);
   t.snapshot(report.explain());
 });
+
+test('retype without layout info', t => {
+  // Without slots, a retype is uncertain unless the types are known to be compatible
+  const v1 = t.context.extractStorageLayoutWithoutSlots('NonHardcodedRetypeV1');
+  const v2 = t.context.extractStorageLayoutWithoutSlots('NonHardcodedRetypeV2');
+  const report = getReport(v1, v2);
+  t.false(report.ok);
+  t.true(report.explain().includes('Layout could have changed for `a` (address -> bytes20)'), report.explain());
+
+  const compatibleV1 = t.context.extractStorageLayoutWithoutSlots('RetypeV1');
+  const compatibleV2 = t.context.extractStorageLayoutWithoutSlots('RetypeV2');
+  t.true(getReport(compatibleV1, compatibleV2).ok);
+});
+
+test('kept retype annotation without layout info', t => {
+  // Upgrading from and to the same contract: `a` stays `bytes20` and keeps its `@custom:oz-retyped-from address`
+  // annotation from an earlier retype, which doesn't apply to this upgrade
+  const original = t.context.extractStorageLayoutWithoutSlots('NonHardcodedRetypeV2');
+  const updated = t.context.extractStorageLayoutWithoutSlots('NonHardcodedRetypeV2');
+  t.true(getReport(original, updated).ok);
+});
+
+test('rename annotation without rename', t => {
+  const v1 = t.context.extractStorageLayout('StaleRenameV1');
+  const v2 = t.context.extractStorageLayout('StaleRenameV2');
+  const report = getReport(v1, v2);
+  t.false(report.ok);
+  t.is(
+    report.explain(),
+    "file.sol:1: `y` has a '@custom:oz-renamed-from x' annotation, but it was not renamed\n" +
+      '  > If the annotation is left over from an earlier upgrade, remove it.',
+  );
+
+  // A rename to a different name is reported as such
+  const renamed = getReport(v1, t.context.extractStorageLayout('RenameV1'));
+  t.is(renamed.explain(), 'file.sol:1: Renamed `y` to `x`');
+});

package/src/storage/report.ts

@@ -109,8 +109,16 @@ function explainStorageOperation(op: StorageOperation<StorageField>, ctx: Storag
     case 'finishgap':
       return `Converted end of storage gap ${label(op.original)} to ${label(op.updated)}`;
 
-    case 'rename':
+    case 'rename': {
+      if (op.original.label === op.updated.label && op.updated.renamedFrom !== undefined) {
+        // The field keeps its name, so the annotation describes a rename that did not happen in this upgrade
+        return printWithHints({
+          title: `${label(op.updated)} has a '@custom:oz-renamed-from ${op.updated.renamedFrom}' annotation, but it was not renamed`,
+          hints: ['If the annotation is left over from an earlier upgrade, remove it.'],
+        });
+      }
       return `Renamed ${label(op.original)} to ${label(op.updated)}`;
+    }
 
     case 'replace':
       return `Replaced ${label(op.original)} with ${label(op.updated)} of incompatible type`;

package/src/storage-namespaced-renamed-retyped.test.ts

@@ -0,0 +1,338 @@
+import _test, { ExecutionContext, TestFn } from 'ava';
+import { artifacts, run } from 'hardhat';
+import {
+  TASK_COMPILE_SOLIDITY_GET_SOLC_BUILD,
+  TASK_COMPILE_SOLIDITY_RUN_SOLC,
+  TASK_COMPILE_SOLIDITY_RUN_SOLCJS,
+} from 'hardhat/builtin-tasks/task-names';
+import { SolcBuild } from 'hardhat/types/builtin-tasks';
+
+import { SolcInput, SolcOutput } from './solc-api';
+import { validate, ValidationRunData } from './validate';
+import { withValidationDefaults } from './validate/overrides';
+import { solcInputOutputDecoder } from './src-decoder';
+import { makeNamespacedInput, trySanitizeNatSpec } from './utils/make-namespaced';
+import { getStorageUpgradeErrors, getStorageUpgradeReport } from './storage';
+import { StorageLayout, isStructMembers } from './storage/layout';
+import { stabilizeStorageLayout } from './utils/stabilize-layout';
+
+const source = 'contracts/test/NamespacedRenamedRetyped.sol';
+const crossFileSource = 'contracts/test/NamespacedCrossFile.sol';
+
+interface Context {
+  input: SolcInput;
+  output: SolcOutput;
+  namespacedOutput: SolcOutput;
+  solcVersion: string;
+  validation: ValidationRunData;
+  // Validation without the namespaced compilation, as with the build info files of the CLI, so that namespace members
+  // have no slots
+  validationWithoutSlots: ValidationRunData;
+  // Validation of the fixture whose namespace has a member of a struct type from another source file
+  crossFile: { output: SolcOutput; validation: ValidationRunData };
+}
+
+const test = _test as TestFn<Context>;
+
+test.before(async t => {
+  const { input, output, solcVersion } = await getBuildInfo(`${source}:NamespacedRenamedRetypedV1`);
+  const namespacedOutput = await compileNamespaced(input, output, solcVersion);
+  const decodeSrc = solcInputOutputDecoder(input, output);
+  t.context.input = input;
+  t.context.output = output;
+  t.context.namespacedOutput = namespacedOutput;
+  t.context.solcVersion = solcVersion;
+  t.context.validation = validate(output, decodeSrc, solcVersion, input, namespacedOutput);
+  t.context.validationWithoutSlots = validate(output, decodeSrc, solcVersion, input);
+
+  const crossFile = await getBuildInfo(`${crossFileSource}:NamespacedCrossFileV1`);
+  t.context.crossFile = {
+    output: crossFile.output,
+    validation: await validateWithNamespacedOutput(crossFile.input, crossFile.output, crossFile.solcVersion),
+  };
+});
+
+async function getBuildInfo(contract: string) {
+  const buildInfo = await artifacts.getBuildInfo(contract);
+  if (buildInfo === undefined) {
+    throw new Error(`Build info not found for ${contract}`);
+  }
+  return buildInfo;
+}
+
+/**
+ * Compiles the namespaced input for the given compilation, following the same steps as the Hardhat plugin.
+ */
+async function compileNamespaced(input: SolcInput, output: SolcOutput, solcVersion: string) {
+  const namespacedInput = await trySanitizeNatSpec(makeNamespacedInput(input, output, solcVersion), solcVersion);
+  return hardhatCompile(namespacedInput, solcVersion);
+}
+
+/**
+ * Validates with a namespaced compilation.
+ */
+async function validateWithNamespacedOutput(input: SolcInput, output: SolcOutput, solcVersion: string) {
+  const namespacedOutput = await compileNamespaced(input, output, solcVersion);
+  return validate(output, solcInputOutputDecoder(input, output), solcVersion, input, namespacedOutput);
+}
+
+/**
+ * Compiles the fixture again from the given source content and validates with a namespaced compilation.
+ */
+async function compileAndValidate(input: SolcInput, content: string, solcVersion: string) {
+  const newInput = { ...input, sources: { [source]: { content } } };
+  const output = await hardhatCompile(newInput, solcVersion);
+  return validateWithNamespacedOutput(newInput, output, solcVersion);
+}
+
+async function hardhatCompile(input: SolcInput, solcVersion: string): Promise<SolcOutput> {
+  const solcBuild: SolcBuild = await run(TASK_COMPILE_SOLIDITY_GET_SOLC_BUILD, {
+    quiet: true,
+    solcVersion,
+  });
+
+  const output: SolcOutput = solcBuild.isSolcJs
+    ? await run(TASK_COMPILE_SOLIDITY_RUN_SOLCJS, { input, solcJsPath: solcBuild.compilerPath })
+    : await run(TASK_COMPILE_SOLIDITY_RUN_SOLC, { input, solcPath: solcBuild.compilerPath });
+
+  const errors = output.errors?.filter(e => e.severity === 'error');
+  if (errors !== undefined && errors.length > 0) {
+    throw new Error(errors.map(e => e.formattedMessage).join('\n'));
+  }
+  return output;
+}
+
+function getLayout(validation: ValidationRunData, contract: string): StorageLayout {
+  return validation[`${source}:${contract}`].layout;
+}
+
+function assertAnnotationsApplied(t: ExecutionContext<Context>, validation: ValidationRunData) {
+  const v1 = getLayout(validation, 'NamespacedRenamedRetypedV1');
+  const v2 = getLayout(validation, 'NamespacedRenamedRetypedV2');
+  t.deepEqual(getStorageUpgradeErrors(v1, v2), []);
+  assertExactMap(t, getLayout(validation, 'NamespacedExactMap'));
+}
+
+function assertExactMap(t: ExecutionContext<Context>, layout: StorageLayout) {
+  const items = layout.namespaces?.['erc7201:example.exact'];
+  if (items === undefined) {
+    throw new Error('Namespace not found');
+  }
+  t.is(items.length, 6);
+  for (const item of items) {
+    t.is(item.renamedFrom, `old_${item.label}`);
+    t.is(item.retypedFrom, undefined);
+    // Slots come from the namespaced compilation
+    t.not(item.slot, undefined);
+  }
+
+  // The struct used inside the namespace is looked up through the namespaced compilation
+  const members = Object.values(layout.types).find(type => type.label === 'struct NamespacedExactMap.Inner')?.members;
+  if (members === undefined || !isStructMembers(members)) {
+    throw new Error('Struct members not found');
+  }
+  t.is(members.length, 3);
+  for (const member of members) {
+    t.is(member.renamedFrom, `old_${member.label}`);
+    t.is(member.retypedFrom, undefined);
+    t.not(member.slot, undefined);
+  }
+}
+
+test('layout', t => {
+  t.snapshot(stabilizeStorageLayout(getLayout(t.context.validation, 'NamespacedRenamedRetypedV2')));
+});
+
+test('upgrade ok', t => {
+  assertAnnotationsApplied(t, t.context.validation);
+});
+
+test('inherited namespace upgrade ok', t => {
+  const v1 = getLayout(t.context.validation, 'NamespacedRenamedRetypedInheritedV1');
+  const v2 = getLayout(t.context.validation, 'NamespacedRenamedRetypedInheritedV2');
+  t.deepEqual(getStorageUpgradeErrors(v1, v2), []);
+});
+
+test('wrong retype', t => {
+  const v1 = getLayout(t.context.validation, 'NamespacedBadV1');
+  const v2 = getLayout(t.context.validation, 'NamespacedWrongRetypeV2');
+  t.like(getStorageUpgradeErrors(v1, v2), {
+    length: 1,
+    0: { kind: 'typechange', original: { label: 'x' }, updated: { label: 'x', retypedFrom: 'address' } },
+  });
+});
+
+test('annotation on the wrong member', t => {
+  // The annotation makes `x` match the original `y` with a different type, and `x` and `z` are left unmatched
+  const v1 = getLayout(t.context.validation, 'NamespacedBadV1');
+  const v2 = getLayout(t.context.validation, 'NamespacedWrongMemberV2');
+  t.like(getStorageUpgradeErrors(v1, v2), {
+    length: 3,
+    0: { kind: 'delete', original: { label: 'x' } },
+    1: { kind: 'typechange', original: { label: 'y' }, updated: { label: 'x', renamedFrom: 'y' } },
+    2: { kind: 'insert', updated: { label: 'z' } },
+  });
+});
+
+test('stale rename annotation', t => {
+  const v1 = getLayout(t.context.validation, 'NamespacedBadV1');
+  const v2 = getLayout(t.context.validation, 'NamespacedStaleRenameV2');
+  t.like(getStorageUpgradeErrors(v1, v2), {
+    length: 1,
+    0: { kind: 'rename', original: { label: 'y' }, updated: { label: 'y', renamedFrom: 'q' } },
+  });
+});
+
+test('unannotated rename and retype', t => {
+  const v1 = getLayout(t.context.validation, 'NamespacedBadV1');
+  const v2 = getLayout(t.context.validation, 'NamespacedUnannotatedV2');
+  t.like(getStorageUpgradeErrors(v1, v2), {
+    length: 2,
+    0: { kind: 'typechange', original: { label: 'x' }, updated: { label: 'x' } },
+    1: { kind: 'rename', original: { label: 'y' }, updated: { label: 'z' } },
+  });
+});
+
+test('namespaced output with different source ids', t => {
+  const { input, output, namespacedOutput, solcVersion } = t.context;
+  const sources = Object.fromEntries(
+    Object.entries(namespacedOutput.sources).map(([path, s]) => [path, { ...s, id: s.id + 1 }]),
+  );
+  t.throws(
+    () => validate(output, solcInputOutputDecoder(input, output), solcVersion, input, { ...namespacedOutput, sources }),
+    { message: /Source ids differ between the solc output and the namespaced solc output/ },
+  );
+});
+
+test('two annotated namespaces in one contract', t => {
+  const v1 = getLayout(t.context.validation, 'NamespacedTwoV1');
+  const v2 = getLayout(t.context.validation, 'NamespacedTwoV2');
+  t.like(v2.namespaces, {
+    'erc7201:example.first': {
+      length: 2,
+      0: { label: 'x', retypedFrom: 'bytes32' },
+      1: { label: 'y', renamedFrom: 'oldY' },
+    },
+    'erc7201:example.second': {
+      length: 2,
+      0: { label: 'f', retypedFrom: 'uint8' },
+      1: { label: 'g', renamedFrom: 'oldG' },
+    },
+  });
+  t.deepEqual(getStorageUpgradeErrors(v1, v2), []);
+});
+
+test('kept retype annotation', t => {
+  const v1 = getLayout(t.context.validation, 'NamespacedKeptRetypeV1');
+  const v2 = getLayout(t.context.validation, 'NamespacedKeptRetypeV2');
+  t.like(v2.namespaces, { 'erc7201:example.main': { length: 1, 0: { label: 'x', retypedFrom: 'uint8', slot: '0' } } });
+  t.deepEqual(getStorageUpgradeErrors(v1, v2), []);
+});
+
+test('kept retype annotation without layout info', t => {
+  const v1 = getLayout(t.context.validationWithoutSlots, 'NamespacedKeptRetypeV1');
+  const v2 = getLayout(t.context.validationWithoutSlots, 'NamespacedKeptRetypeV2');
+  t.like(v2.namespaces, {
+    'erc7201:example.main': { length: 1, 0: { label: 'x', retypedFrom: 'uint8', slot: undefined } },
+  });
+  t.deepEqual(getStorageUpgradeErrors(v1, v2), []);
+});
+
+test('retype without layout info', t => {
+  // A retype that is not known to be compatible is uncertain without slots
+  const v1 = getLayout(t.context.validationWithoutSlots, 'NamespacedBadV1');
+  const v2 = getLayout(t.context.validationWithoutSlots, 'NamespacedRetypeV2');
+  const report = getStorageUpgradeReport(v1, v2, withValidationDefaults({}));
+  t.false(report.ok);
+  t.true(
+    report.explain().includes('Layout could have changed for `x` (bytes32 -> struct TransientSlot.TBytes32)'),
+    report.explain(),
+  );
+});
+
+test('wrong retype without layout info', t => {
+  const v1 = getLayout(t.context.validationWithoutSlots, 'NamespacedBadV1');
+  const v2 = getLayout(t.context.validationWithoutSlots, 'NamespacedWrongRetypeV2');
+  t.like(getStorageUpgradeErrors(v1, v2), {
+    length: 1,
+    0: { kind: 'typechange', original: { label: 'x' }, updated: { label: 'x', retypedFrom: 'address' } },
+  });
+});
+
+test('retype with layout change', t => {
+  // A retype annotation that names the original type does not allow the member's size to change
+  const v1 = getLayout(t.context.validation, 'NamespacedRetypeLayoutChangeV1');
+  const v2 = getLayout(t.context.validation, 'NamespacedRetypeLayoutChangeV2');
+  t.like(getStorageUpgradeErrors(v1, v2), {
+    length: 1,
+    0: {
+      kind: 'layoutchange',
+      original: { label: 'y' },
+      updated: { label: 'y', retypedFrom: 'uint256' },
+      change: { bytes: { from: '32', to: '16' } },
+    },
+  });
+});
+
+test('struct from another source file', t => {
+  // The annotations on the members of the struct are read from the source file that defines it
+  const { output, validation } = t.context.crossFile;
+  t.not(output.sources['contracts/test/NamespacedCrossFileStruct.sol'].id, 0);
+  const v1 = validation[`${crossFileSource}:NamespacedCrossFileV1`].layout;
+  const v2 = validation[`${crossFileSource}:NamespacedCrossFileV2`].layout;
+  t.like(v2.namespaces, { 'erc7201:example.main': { length: 1, 0: { label: 'data', slot: '0' } } });
+  const members = Object.values(v2.types).find(type => type.label === 'struct CrossFileV2.Data')?.members;
+  if (members === undefined || !isStructMembers(members)) {
+    throw new Error('Struct members not found');
+  }
+  t.like(members, {
+    length: 2,
+    0: { label: 'a', retypedFrom: 'bytes32', slot: '0' },
+    1: { label: 'c', renamedFrom: 'b', slot: '1' },
+  });
+  t.deepEqual(getStorageUpgradeErrors(v1, v2), []);
+});
+
+/**
+ * Validates the fixture compiled again with the given line endings.
+ */
+async function validateWithLineEndings(t: ExecutionContext<Context>, lineEnding: string) {
+  const content = t.context.input.sources[source].content;
+  if (content === undefined) {
+    throw new Error('Unexpected fixture content');
+  }
+  return compileAndValidate(t.context.input, content.replace(/\r\n|\r|\n/g, lineEnding), t.context.solcVersion);
+}
+
+test('CRLF line endings', async t => {
+  assertAnnotationsApplied(t, await validateWithLineEndings(t, '\r\n'));
+});
+
+test('CR line endings', async t => {
+  assertAnnotationsApplied(t, await validateWithLineEndings(t, '\r'));
+});
+
+test('solc 0.8.20', async t => {
+  const content = t.context.input.sources[source].content;
+  if (content === undefined) {
+    throw new Error('Unexpected fixture content');
+  }
+  const validation = await compileAndValidate(t.context.input, content, '0.8.20');
+  assertAnnotationsApplied(t, validation);
+});
+
+test('stale rename annotation report', t => {
+  const v1 = getLayout(t.context.validation, 'NamespacedBadV1');
+  const v2 = getLayout(t.context.validation, 'NamespacedStaleRenameV2');
+  const report = getStorageUpgradeReport(v1, v2, withValidationDefaults({}));
+  t.false(report.ok);
+  const items = v2.namespaces?.['erc7201:example.main'];
+  if (items === undefined) {
+    throw new Error('Namespace not found');
+  }
+  t.is(
+    report.explain(),
+    `${items[1].src}: \`y\` has a '@custom:oz-renamed-from q' annotation, but it was not renamed\n` +
+      '  > If the annotation is left over from an earlier upgrade, remove it.',
+  );
+});