[Serialization] Give swiftdocs a stable version

We're committing to this as a forwards-compatible format, and in most
cases probably backwards-compatible as well!

Author: jrose-apple

include/swift/Serialization/ModuleFile.h

@@ -631,6 +631,9 @@ class ModuleFile
     theModule.reset(new ModuleFile(std::move(moduleInputBuffer),
                                    std::move(moduleDocInputBuffer),
                                    isFramework, info, extInfo));
+    assert(info.status == Status::Valid ||
+           info.status == theModule->getStatus());
+    info.status = theModule->getStatus();
     return info;
   }
 

lib/Serialization/DocFormat.h

@@ -33,6 +33,26 @@ using llvm::BCVBR;
 /// Magic number for serialized documentation files.
 const unsigned char SWIFTDOC_SIGNATURE[] = { 0xE2, 0x9C, 0xA8, 0x07 };
 
+/// Serialized swiftdoc format major version number.
+///
+/// Increment this value when making a backwards-incompatible change, which
+/// should be rare. When incrementing this value, reset SWIFTDOC_VERSION_MINOR
+/// to 0.
+const uint16_t SWIFTDOC_VERSION_MAJOR = 1;
+
+/// Serialized swiftdoc format minor version number.
+///
+/// Increment this value when making a backwards-compatible change that might
+/// be interesting to test for. However, if old swiftdoc files are fully
+/// compatible with the new change, you do not need to increment this.
+///
+/// To ensure that two separate changes don't silently get merged into one
+/// in source control, you should also update the comment to briefly
+/// describe what change you made. The content of this comment isn't important;
+/// it just ensures a conflict if two people change the module format.
+/// Don't worry about adhering to the 80-column limit for this line.
+const uint16_t SWIFTDOC_VERSION_MINOR = 1; // Last change: skipping 0 for testing purposes
+
 /// The record types within the comment block.
 ///
 /// Be very careful when changing this block; it must remain stable. Adding new

lib/Serialization/ModuleFile.cpp

@@ -129,6 +129,7 @@ static bool readOptionsBlock(llvm::BitstreamCursor &cursor,
 static ValidationInfo
 validateControlBlock(llvm::BitstreamCursor &cursor,
                      SmallVectorImpl<uint64_t> &scratch,
+                     std::pair<uint16_t, uint16_t> expectedVersion,
                      ExtendedValidationInfo *extendedInfo) {
   // The control block is malformed until we've at least read a major version
   // number.
@@ -174,18 +175,18 @@ validateControlBlock(llvm::BitstreamCursor &cursor,
       }
 
       uint16_t versionMajor = scratch[0];
-      if (versionMajor > SWIFTMODULE_VERSION_MAJOR)
+      if (versionMajor > expectedVersion.first)
         result.status = Status::FormatTooNew;
-      else if (versionMajor < SWIFTMODULE_VERSION_MAJOR)
+      else if (versionMajor < expectedVersion.first)
         result.status = Status::FormatTooOld;
       else
         result.status = Status::Valid;
 
       // Major version 0 does not have stable minor versions.
       if (versionMajor == 0) {
         uint16_t versionMinor = scratch[1];
-        if (versionMinor != SWIFTMODULE_VERSION_MINOR) {
-          if (versionMinor < SWIFTMODULE_VERSION_MINOR)
+        if (versionMinor != expectedVersion.second) {
+          if (versionMinor < expectedVersion.second)
             result.status = Status::FormatTooOld;
           else
             result.status = Status::FormatTooNew;
@@ -263,7 +264,10 @@ ValidationInfo serialization::validateSerializedAST(
 
     if (topLevelEntry.ID == CONTROL_BLOCK_ID) {
       cursor.EnterSubBlock(CONTROL_BLOCK_ID);
-      result = validateControlBlock(cursor, scratch, extendedInfo);
+      result = validateControlBlock(cursor, scratch,
+                                    {SWIFTMODULE_VERSION_MAJOR,
+                                     SWIFTMODULE_VERSION_MINOR},
+                                    extendedInfo);
       if (result.status == Status::Malformed)
         return result;
     } else {
@@ -1106,7 +1110,10 @@ bool ModuleFile::readModuleDocIfPresent() {
     case CONTROL_BLOCK_ID: {
       docCursor.EnterSubBlock(CONTROL_BLOCK_ID);
 
-      info = validateControlBlock(docCursor, scratch, /*extendedInfo*/nullptr);
+      info = validateControlBlock(docCursor, scratch,
+                                  {SWIFTDOC_VERSION_MAJOR,
+                                   SWIFTDOC_VERSION_MINOR},
+                                  /*extendedInfo*/nullptr);
       if (info.status != Status::Valid)
         return false;
       // Check that the swiftdoc is actually for this module.
@@ -1174,7 +1181,10 @@ ModuleFile::ModuleFile(
     case CONTROL_BLOCK_ID: {
       cursor.EnterSubBlock(CONTROL_BLOCK_ID);
 
-      info = validateControlBlock(cursor, scratch, extInfo);
+      info = validateControlBlock(cursor, scratch,
+                                  {SWIFTMODULE_VERSION_MAJOR,
+                                   SWIFTMODULE_VERSION_MINOR},
+                                  extInfo);
       if (info.status != Status::Valid) {
         error(info.status);
         return;

lib/Serialization/SerializeDoc.cpp

@@ -472,8 +472,7 @@ void DocSerializer::writeDocHeader() {
     control_block::TargetLayout Target(Out);
 
     auto& LangOpts = M->getASTContext().LangOpts;
-    Metadata.emit(ScratchRecord,
-                  SWIFTMODULE_VERSION_MAJOR, SWIFTMODULE_VERSION_MINOR,
+    Metadata.emit(ScratchRecord, SWIFTDOC_VERSION_MAJOR, SWIFTDOC_VERSION_MINOR,
                   /*short version string length*/0, /*compatibility length*/0,
                   version::getSwiftFullVersion(
                     LangOpts.EffectiveLanguageVersion));

test/Serialization/Inputs/swiftdoc-versions/empty-0.7.swiftdoc

@@ -0,0 +1,17 @@
+// RUN: %empty-directory(%t)
+// RUN: %target-swift-frontend -emit-module -o %t %S/../Inputs/empty.swift
+// RUN: %target-swift-frontend -typecheck -I %t %s
+
+// RUN: touch %t/empty.swiftdoc
+// RUN: %target-swift-frontend -typecheck -I %t %s -verify -show-diagnostics-after-fatal
+
+// RUN: echo -n 'a' > %t/empty.swiftdoc
+// RUN: %target-swift-frontend -typecheck -I %t %s -verify -show-diagnostics-after-fatal
+
+// RUN: echo -n 'abcd' > %t/empty.swiftdoc
+// RUN: %target-swift-frontend -typecheck -I %t %s -verify -show-diagnostics-after-fatal
+
+// RUN: echo -n 'abcde' > %t/empty.swiftdoc
+// RUN: %target-swift-frontend -typecheck -I %t %s -verify -show-diagnostics-after-fatal
+
+import empty // expected-error{{malformed module file}}