Validate migrated documentation provenance

Author: thomashoneyman

docgen/README.md

@@ -36,6 +36,9 @@ Package metadata always comes from the canonical `purs.json` stored in the
 registry tarball. Historical Pursuit JSON is used during migration only for
 compiler-produced documentation and resolution data; it is not an alternative
 source for package identity, metadata, dependencies, or source files.
+Migration accepts its exact resolutions and module ownership only when they are
+consistent with the canonical manifest; inconsistent artifacts must be
+regenerated through the registry documentation pipeline.
 
 The main modules are:
 

docgen/src/Registry/Docgen/Convert.purs

@@ -15,12 +15,15 @@ import Data.Maybe (Maybe(..), fromMaybe)
 import Data.Newtype (unwrap)
 import Data.String as String
 import Data.Traversable (traverse)
+import Data.Tuple (Tuple(..))
 import Registry.Docgen.Docs (DataConstructorName(..), DocChildDeclaration(..), DocChildDeclarationInfo(..), DocConstraint(..), DocDeclaration(..), DocDeclarationInfo(..), DocModule(..), DocPackage(..), DocReexport(..), DocType(..), ForallBinding(..), FunDep(..), Ident(..), InfixAlias(..), IntLiteral(..), ModuleName(..), OperatorName(..), Qualified(..), RawRange(..), Readme, RowLabel(..), RowRep, SourceArtifact, SourceSpan(..), StringLiteral, TypeName(..), TypeVar(..), ValueName(..), isPrim, schemaVersion)
 import Registry.Docgen.Legacy.Docs (InPackage(..))
 import Registry.Docgen.Legacy.Docs as L
 import Registry.LimitedString as LimitedString
 import Registry.Manifest (Manifest(..))
+import Registry.PackageName (PackageName)
 import Registry.PackageName as PackageName
+import Registry.Range (Range)
 import Registry.Range as Range
 import Registry.Version as Version
 import Safe.Coerce (coerce)
@@ -35,13 +38,14 @@ fromLegacyPackage
      }
   -> L.DocPackage
   -> Either String DocPackage
-fromLegacyPackage input (L.DocPackage pkg@{ packageMeta: L.DocPackageMeta meta }) = do
-  let Manifest manifest = input.manifest
+fromLegacyPackage input@{ manifest: Manifest manifest } (L.DocPackage pkg@{ packageMeta: L.DocPackageMeta meta }) = do
   if meta.name /= manifest.name then
     Left $ "Legacy documentation package " <> PackageName.print meta.name <> " does not match manifest package " <> PackageName.print manifest.name
   else if pkg.version /= manifest.version then
     Left $ "Legacy documentation version " <> Version.print pkg.version <> " does not match manifest version " <> Version.print manifest.version
   else do
+    _ <- traverse validateDependency (Map.toUnfoldable manifest.dependencies :: Array (Tuple PackageName Range))
+    _ <- traverse validateModuleOwner (Map.toUnfoldable pkg.moduleMap :: Array (Tuple ModuleName PackageName))
     compilerVersion <- Version.parse pkg.compilerVersion
     modules <- traverse convertModule pkg.modules
     pure $ DocPackage
@@ -61,6 +65,18 @@ fromLegacyPackage input (L.DocPackage pkg@{ packageMeta: L.DocPackageMeta meta }
       , version: manifest.version
       }
   where
+  validateDependency (Tuple dependency range) = case Map.lookup dependency pkg.resolvedDependencies of
+    Nothing ->
+      Left $ "Legacy documentation is missing an exact resolution for manifest dependency " <> PackageName.print dependency
+    Just resolved | not (Range.includes range resolved) ->
+      Left $ "Legacy documentation resolves " <> PackageName.print dependency <> "@" <> Version.print resolved <> " outside manifest range " <> Range.print range
+    Just _ ->
+      Right unit
+
+  validateModuleOwner (Tuple moduleName owner)
+    | owner == manifest.name || Map.member owner pkg.resolvedDependencies = Right unit
+    | otherwise = Left $ "Legacy documentation attributes module " <> unwrap moduleName <> " to unresolved package " <> PackageName.print owner
+
   convertModule legacy@(L.DocModule { name })
     | isPrim name = Right $ fromLegacyModule sourcePaths legacy
     | otherwise = case Map.lookup name sourcePaths of

docgen/test/Test/Registry/Docgen.purs

@@ -106,6 +106,7 @@ main = runSpecAndExitProcess [ consoleReporter ] do
       let Manifest manifest = undefinedManifest
       let canonicalDescription = Utils.fromRight "description" $ LimitedString.parse "Canonical package metadata"
       let manifestDependencies = Map.singleton (packageName "prelude") (range ">=4.0.0 <5.0.0")
+      let L.DocPackage legacyPackage = legacy
       let
         authoritativeManifest = Manifest $ manifest
           { dependencies = manifestDependencies
@@ -114,14 +115,26 @@ main = runSpecAndExitProcess [ consoleReporter ] do
           , location = Git { url: "https://example.com/undefined.git", subdir: Nothing }
           , ref = "release-1.0.2"
           }
-      case Convert.fromLegacyPackage (conversionInput { manifest = authoritativeManifest }) legacy of
+      let legacyWithResolution = L.DocPackage $ legacyPackage { resolvedDependencies = Map.singleton (packageName "prelude") (version "4.1.0") }
+      case Convert.fromLegacyPackage (conversionInput { manifest = authoritativeManifest }) legacyWithResolution of
         Right (DocPackage convertedPackage) -> do
           convertedPackage.dependencies `Assert.shouldEqual` Map.singleton (packageName "prelude") (RawRange ">=4.0.0 <5.0.0")
           convertedPackage.description `Assert.shouldEqual` Just "Canonical package metadata"
           convertedPackage.license `Assert.shouldEqual` (Utils.fromRight "license" $ License.parse "BSD-3-Clause")
           convertedPackage.location `Assert.shouldEqual` Git { url: "https://example.com/undefined.git", subdir: Nothing }
           convertedPackage.locationRef `Assert.shouldEqual` Just "release-1.0.2"
         Left err -> Assert.fail $ "Failed to convert historical fixture with authoritative manifest: " <> err
+      case Convert.fromLegacyPackage (conversionInput { manifest = authoritativeManifest }) legacy of
+        Left err -> shouldContainString err "missing an exact resolution for manifest dependency prelude"
+        Right _ -> Assert.fail "Conversion unexpectedly accepted a missing direct resolution"
+      let outOfRange = L.DocPackage $ legacyPackage { resolvedDependencies = Map.singleton (packageName "prelude") (version "3.0.0") }
+      case Convert.fromLegacyPackage (conversionInput { manifest = authoritativeManifest }) outOfRange of
+        Left err -> shouldContainString err "prelude@3.0.0 outside manifest range >=4.0.0 <5.0.0"
+        Right _ -> Assert.fail "Conversion unexpectedly accepted an out-of-range direct resolution"
+      let unknownOwner = L.DocPackage $ legacyPackage { moduleMap = Map.singleton (ModuleName "Dependency") (packageName "other") }
+      case Convert.fromLegacyPackage conversionInput unknownOwner of
+        Left err -> shouldContainString err "module Dependency to unresolved package other"
+        Right _ -> Assert.fail "Conversion unexpectedly accepted an unresolved module owner"
       let mismatchedManifest = Manifest $ manifest { name = packageName "other" }
       case Convert.fromLegacyPackage (conversionInput { manifest = mismatchedManifest }) legacy of
         Left err -> shouldContainString err "does not match manifest package other"