Fix #6606 Distinguish global and project-level configuration files

Also refactors where:

* 'project' is used to refer to a file or directory that may not be within a project directory but within the Stack root;
* `stackYaml` is used to refer to a configuration file that may be a user-specific global one as well as a project-level one; or
* `userConfigPath` or `stackGlobalConfig` refers to the user-specific global configuration file (`userGlobalConfigFile`).

Also refactors descriptions in `stack path` to use the terminology of user-specific global configuration file or project-level configuration file (`stack.yaml`, by default).

Author: mpilgrem

.stan.toml

@@ -83,14 +83,14 @@
 
 # Anti-pattern: Data.ByteString.Char8.pack
 [[ignore]]
-  id = "OBS-STAN-0203-tuE+RG-234:21"
+  id = "OBS-STAN-0203-tuE+RG-234:24"
 # ✦ Description:   Usage of 'pack' function that doesn't handle Unicode characters
 # ✦ Category:      #AntiPattern
 # ✦ File:          src\Stack\Build\ExecutePackage.hs
 #
 #   233 ┃
-#   234 ┃   newProjectRoot <- S8.pack . toFilePath <$> view projectRootL
-#   235 ┃                     ^^^^^^^
+#   234 ┃   newConfigFileRoot <- S8.pack . toFilePath <$> view configFileRootL
+#   235 ┃                        ^^^^^^^
 
 # Anti-pattern: Data.ByteString.Char8.pack
 [[ignore]]

ChangeLog.md

@@ -78,6 +78,8 @@ Bug fixes:
   specified at the command line.
 * Fix a regression, introduced in Stack 2.11.1, that caused the `script` command
   to parse an (otherwise ignored) project-level configuration file.
+* Stack no longer makes recommendations about a project-level configuration file
+  when only a global configuration file is in use.
 
 ## v2.15.7 - 2024-05-12
 

doc/maintainers/stack_errors.md

@@ -422,6 +422,7 @@ to take stock of the errors that Stack itself can raise, by reference to the
         [S-5470] | DuplicateLocalPackageNames [(PackageName, [PackageLocation])]
         [S-6854] | BadMsysEnvironment MsysEnvironment Arch
         [S-5006] | NoDefaultMsysEnvironmentBug
+        [S-8398] | ConfigFileNotProjectLevelBug
         ~~~
 
     -   `Stack.Types.Config.ParseAbsolutePathException`

src/Stack/Build.hs

@@ -15,6 +15,7 @@ module Stack.Build
   ) where
 
 import           Data.Attoparsec.Args ( EscapingMode (Escaping), parseArgs )
+import qualified Data.Either.Extra as EE
 import           Data.List ( (\\) )
 import           Data.List.Extra ( groupSort )
 import qualified Data.Map as Map
@@ -41,7 +42,7 @@ import           Stack.Types.Build
                    )
 import           Stack.Types.Build.Exception
                    ( BuildException (..), BuildPrettyException (..) )
-import           Stack.Types.BuildConfig ( HasBuildConfig, stackYamlL )
+import           Stack.Types.BuildConfig ( HasBuildConfig, configFileL )
 import           Stack.Types.BuildOpts ( BuildOpts (..) )
 import           Stack.Types.BuildOptsCLI
                    ( BuildCommand (..), BuildOptsCLI (..), FileWatchOpts (..) )
@@ -153,11 +154,13 @@ build msetLocalFiles = do
     sourceMap <- view $ envConfigL . to (.sourceMap)
     locals <- projectLocalPackages
     depsLocals <- localDependencies
-    let allLocals = locals <> depsLocals
-
     boptsCli <- view $ envConfigL . to (.buildOptsCLI)
     -- Set local files, necessary for file watching
-    stackYaml <- view stackYamlL
+    configFile <- view configFileL
+    let allLocals = locals <> depsLocals
+        -- We are indifferent as to whether the configuration file is a
+        -- user-specifc global or a project-level one.
+        eitherConfigFile = EE.fromEither configFile
     for_ msetLocalFiles $ \setLocalFiles -> do
       files <-
         if boptsCli.watchAll
@@ -171,7 +174,7 @@ build msetLocalFiles = do
               lpFiles lp
             Just (TargetComps components) ->
               lpFilesForComponents components lp
-      liftIO $ setLocalFiles $ Set.insert stackYaml $ Set.unions files
+      liftIO $ setLocalFiles $ Set.insert eitherConfigFile $ Set.unions files
 
     checkComponentsBuildable allLocals
 

src/Stack/Build/ConstructPlan.hs

@@ -51,7 +51,7 @@ import           Stack.Types.Build.Exception
                    , BuildPrettyException (..), ConstructPlanException (..)
                    )
 import           Stack.Types.BuildConfig
-                   ( BuildConfig (..), HasBuildConfig (..), stackYamlL )
+                   ( BuildConfig (..), HasBuildConfig (..), configFileL )
 import           Stack.Types.BuildOpts ( BuildOpts (..) )
 import           Stack.Types.BuildOptsCLI
                    ( BuildOptsCLI (..), BuildSubset (..) )
@@ -187,13 +187,13 @@ constructPlan
                 else Map.empty
           }
       else do
-        stackYaml <- view stackYamlL
+        configFile <- view configFileL
         stackRoot <- view stackRootL
         isImplicitGlobal <-
           view $ configL . to (isPCGlobalProject . (.project))
         prettyThrowM $ ConstructPlanFailed
           errs
-          stackYaml
+          configFile
           stackRoot
           isImplicitGlobal
           parents

src/Stack/Build/ExecutePackage.hs

@@ -90,7 +90,7 @@ import qualified Stack.Types.Build as ConfigCache ( ConfigCache (..) )
 import           Stack.Types.Build.Exception
                    ( BuildException (..), BuildPrettyException (..) )
 import           Stack.Types.BuildConfig
-                   ( BuildConfig (..), HasBuildConfig (..), projectRootL )
+                   ( BuildConfig (..), HasBuildConfig (..), configFileRootL )
 import           Stack.Types.BuildOpts
                    ( BenchmarkOpts (..), BuildOpts (..), HaddockOpts (..)
                    , TestOpts (..)
@@ -231,7 +231,7 @@ ensureConfig newConfigCache pkgDir buildOpts announce cabal cabalFP task = do
           (guard . isDoesNotExistError)
           (getFileStatus (toFilePath setupConfigfp))
   newSetupConfigMod <- getNewSetupConfigMod
-  newProjectRoot <- S8.pack . toFilePath <$> view projectRootL
+  newConfigFileRoot <- S8.pack . toFilePath <$> view configFileRootL
   -- See https://github.com/commercialhaskell/stack/issues/3554. This can be
   -- dropped when Stack drops support for GHC < 8.4.
   taskAnyMissingHackEnabled <-
@@ -271,7 +271,7 @@ ensureConfig newConfigCache pkgDir buildOpts announce cabal cabalFP task = do
              /= Just (ignoreComponents newConfigCache)
           || mOldCabalMod /= Just newCabalMod
           || mOldSetupConfigMod /= newSetupConfigMod
-          || mOldProjectRoot /= Just newProjectRoot
+          || mOldProjectRoot /= Just newConfigFileRoot
 
   when task.buildTypeConfig $
     -- When build-type is Configure, we need to have a configure script in the
@@ -312,7 +312,7 @@ ensureConfig newConfigCache pkgDir buildOpts announce cabal cabalFP task = do
     -- our config mod file is newer than the file above, but this seems
     -- reasonable too.
     getNewSetupConfigMod >>= writeSetupConfigMod pkgDir
-    writePackageProjectRoot pkgDir newProjectRoot
+    writePackageProjectRoot pkgDir newConfigFileRoot
   pure needConfig
 
 -- | Make a padded prefix for log messages

src/Stack/Clean.hs

@@ -18,7 +18,7 @@ import           Stack.Constants.Config ( rootDistDirFromDir, workDirFromDir )
 import           Stack.Prelude
 import           Stack.Runners ( ShouldReexec (..), withConfig )
 import           Stack.Types.BuildConfig
-                   ( BuildConfig (..), HasBuildConfig (..), getProjectWorkDir )
+                   ( BuildConfig (..), HasBuildConfig (..), getWorkDir )
 import           Stack.Types.Config ( Config )
 import           Stack.Types.Runner ( Runner )
 import           Stack.Types.SourceMap ( SMWanted (..), ppRoot )
@@ -94,5 +94,5 @@ dirsToDelete cleanOpts = do
         xs -> throwM (NonLocalPackages xs)
     CleanFull -> do
       pkgWorkDirs <- mapM (workDirFromDir . ppRoot) $ Map.elems packages
-      projectWorkDir <- getProjectWorkDir
+      projectWorkDir <- getWorkDir
       pure (projectWorkDir : pkgWorkDirs)

src/Stack/Config.hs

@@ -42,6 +42,7 @@ import           Data.Array.IArray ( (!), (//) )
 import qualified Data.ByteString as S
 import           Data.ByteString.Builder ( byteString )
 import           Data.Coerce ( coerce )
+import qualified Data.Either.Extra as EE
 import qualified Data.IntMap as IntMap
 import qualified Data.Map as Map
 import qualified Data.Map.Merge.Strict as MS
@@ -272,15 +273,16 @@ getLatestSnapshot = do
 configFromConfigMonoid ::
      (HasRunner env, HasTerm env)
   => Path Abs Dir -- ^ Stack root, e.g. ~/.stack
-  -> Path Abs File -- ^ user config file path, e.g. ~/.stack/config.yaml
+  -> Path Abs File
+     -- ^ User-specific global configuration file.
   -> Maybe AbstractSnapshot
   -> ProjectConfig (Project, Path Abs File)
   -> ConfigMonoid
   -> (Config -> RIO env a)
   -> RIO env a
 configFromConfigMonoid
   stackRoot
-  userConfigPath
+  userGlobalConfigFile
   snapshot
   project
   configMonoid
@@ -565,7 +567,7 @@ configFromConfigMonoid
             (stackRoot </> relFileStorage)
             ( \userStorage -> inner Config
                 { workDir
-                , userConfigPath
+                , userGlobalConfigFile
                 , build
                 , docker
                 , nix
@@ -771,16 +773,16 @@ withBuildConfig inner = do
        <> " specified on command line"
     makeConcreteSnapshot aSnapshot
 
-  (project', stackYaml) <- case config.project of
+  (project', configFile) <- case config.project of
     PCProject (project, fp) -> do
       forM_ project.userMsg prettyWarnS
-      pure (project, fp)
+      pure (project, Right fp)
     PCNoProject extraDeps -> do
       p <-
         case mSnapshot of
           Nothing -> throwIO NoSnapshotWhenUsingNoProject
           Just _ -> getEmptyProject mSnapshot extraDeps
-      pure (p, config.userConfigPath)
+      pure (p, Left config.userGlobalConfigFile)
     PCGlobalProject -> do
       logDebug "Run from outside a project, using implicit global project config"
       destDir <- getImplicitGlobalProjectDir config
@@ -803,7 +805,7 @@ withBuildConfig inner = do
                   <> " from implicit global project's config file: "
                   <> fromString dest'
               Just _ -> pure ()
-          pure (project, dest)
+          pure (project, Right dest)
         else do
           prettyInfoL
             [ flow "Writing the configuration file for the implicit \
@@ -816,10 +818,10 @@ withBuildConfig inner = do
           p <- getEmptyProject mSnapshot []
           liftIO $ do
             writeBinaryFileAtomic dest $ byteString $ S.concat
-              [ "# This is the implicit global project's config file, which is only used when\n"
-              , "# 'stack' is run outside of a real project. Settings here do _not_ act as\n"
+              [ "# This is the implicit global project's configuration file, which is only used\n"
+              , "# when 'stack' is run outside of a real project. Settings here do _not_ act as\n"
               , "# defaults for all projects. To change Stack's default settings, edit\n"
-              , "# '", encodeUtf8 (T.pack $ toFilePath config.userConfigPath), "' instead.\n"
+              , "# '", encodeUtf8 (T.pack $ toFilePath config.userGlobalConfigFile), "' instead.\n"
               , "#\n"
               , "# For more information about Stack's configuration, see\n"
               , "# http://docs.haskellstack.org/en/stable/yaml_configuration/\n"
@@ -829,29 +831,31 @@ withBuildConfig inner = do
               "This is the implicit global project, which is " <>
               "used only when 'stack' is run\noutside of a " <>
               "real project.\n"
-          pure (p, dest)
+          pure (p, Right dest)
   mcompiler <- view $ globalOptsL . to (.compiler)
   let project :: Project
       project = project'
         { Project.compiler = mcompiler <|> project'.compiler
         , Project.snapshot = fromMaybe project'.snapshot mSnapshot
         }
+      -- We are indifferent as to whether the configuration file is a
+      -- user-specific global or a project-level one.
+      eitherConfigFile = EE.fromEither configFile
   extraPackageDBs <- mapM resolveDir' project.extraPackageDBs
 
-  smWanted <- lockCachedWanted stackYaml project.snapshot $
-    fillProjectWanted stackYaml config project
+  smWanted <- lockCachedWanted eitherConfigFile project.snapshot $
+    fillProjectWanted eitherConfigFile config project
 
-  -- Unfortunately redoes getProjectWorkDir, since we don't have a BuildConfig
-  -- yet
+  -- Unfortunately redoes getWorkDir, since we don't have a BuildConfig yet
   workDir <- view workDirL
-  let projectStorageFile = parent stackYaml </> workDir </> relFileStorage
+  let projectStorageFile = parent eitherConfigFile </> workDir </> relFileStorage
 
   initProjectStorage projectStorageFile $ \projectStorage -> do
     let bc = BuildConfig
           { config
           , smWanted
           , extraPackageDBs
-          , stackYaml
+          , configFile
           , curator = project.curator
           , projectStorage
           }
@@ -891,18 +895,20 @@ withBuildConfig inner = do
 
 fillProjectWanted ::
      (HasLogFunc env, HasPantryConfig env, HasProcessContext env)
-  => Path Abs t
+  => Path Abs File
+     -- ^ Location of the configuration file, which may be either a
+     -- user-specific global or a project-level one.
   -> Config
   -> Project
   -> Map RawPackageLocationImmutable PackageLocationImmutable
   -> WantedCompiler
   -> Map PackageName (Bool -> RIO env DepPackage)
   -> RIO env (SMWanted, [CompletedPLI])
-fillProjectWanted stackYamlFP config project locCache snapCompiler snapPackages = do
+fillProjectWanted configFile config project locCache snapCompiler snapPackages = do
   let bopts = config.build
 
   packages0 <- for project.packages $ \fp@(RelFilePath t) -> do
-    abs' <- resolveDir (parent stackYamlFP) (T.unpack t)
+    abs' <- resolveDir (parent configFile) (T.unpack t)
     let resolved = ResolvedPath fp abs'
     pp <- mkProjectPackage YesPrintWarnings resolved bopts.buildHaddocks
     pure (pp.projectCommon.name, pp)

src/Stack/ConfigCmd.hs

@@ -105,7 +105,7 @@ cfgCmdSet cmd = do
             fmap (</> stackDotYaml) (getImplicitGlobalProjectDir conf)
           PCNoProject _extraDeps -> throwIO NoProjectConfigAvailable
           -- maybe modify the ~/.stack/config.yaml file instead?
-      CommandScopeGlobal -> pure conf.userConfigPath
+      CommandScopeGlobal -> pure conf.userGlobalConfigFile
   rawConfig <- liftIO (readFileUtf8 (toFilePath configFilePath))
   config <- either throwM pure (Yaml.decodeEither' $ encodeUtf8 rawConfig)
   newValue <- cfgCmdSetValue (parent configFilePath) cmd

src/Stack/Constants/Config.hs

@@ -26,7 +26,7 @@ module Stack.Constants.Config
 import           Path ( (</>), mkRelDir, mkRelFile, parseRelDir )
 import           Stack.Constants ( relDirDist, relDirGhci, relDirHpc )
 import           Stack.Prelude
-import           Stack.Types.BuildConfig ( HasBuildConfig, projectRootL )
+import           Stack.Types.BuildConfig ( HasBuildConfig, configFileRootL )
 import           Stack.Types.Compiler ( compilerVersionString )
 import           Stack.Types.CompilerPaths ( compilerVersionL )
 import           Stack.Types.Config ( Config, HasConfig, stackRootL, workDirL )
@@ -37,15 +37,15 @@ import           Stack.Types.EnvConfig
 objectInterfaceDirL :: HasBuildConfig env => Getting r env (Path Abs Dir)
 objectInterfaceDirL = to $ \env -> -- FIXME is this idiomatic lens code?
   let workDir = view workDirL env
-      root = view projectRootL env
-  in  root </> workDir </> $(mkRelDir "odir/")
+      configFileRoot = view configFileRootL env
+  in  configFileRoot </> workDir </> $(mkRelDir "odir/")
 
 -- | GHCi files directory.
 ghciDirL :: HasBuildConfig env => Getting r env (Path Abs Dir)
 ghciDirL = to $ \env -> -- FIXME is this idiomatic lens code?
   let workDir = view workDirL env
-      root = view projectRootL env
-  in  root </> workDir </> relDirGhci
+      configFileRoot = view configFileRootL env
+  in  configFileRoot </> workDir </> relDirGhci
 
 -- | The directory containing the files used for dirtiness check of source
 -- files.