#Conventions

[!NOTE] Discovery finds the system file, the global user file, and the project file in three layouts by walking up from the working directory, with local and user overrides next to the project file, an explicit project file, a stop boundary, a legacy fallback, isolated mode, environment files, and workspaces with members and key filters.

#Find a declared workspace

///|
test "inspect root evidence without selecting a member" {
  let root = @config.FileTreePath::parse("/w")
  let child = @config.FileTreePath::parse("/w/a")
  let conventions = @conventions.app_dirs("acme")
    |> @conventions.workspace
    |> @conventions.root_policy(WorkspaceFirst(@config.KeyPath::parse("workspace")))
    |> @conventions.member_loading(ExplicitOnly)
  let tree = @config.FileTree::new(complete=true)
    .with_listing(root, [{ name: "acme.toml", kind: File }, { name: "a", kind: Directory }])
    .with_listing(child, [{ name: "acme.toml", kind: File }])
    .with_file(root.child("acme.toml"), "[workspace]\nmarker='root'")
    .with_file(child.child("acme.toml"), "project.name='a'")
  let context : @config.LoadContext = {
    tree, working_dir: Some(child), platform: Some(Linux),
    env_vars: Map([]), formats: [@toml.format()],
  }
  guard conventions.roots(context) is Done(roots) else { fail("complete tree needs I/O") }
  assert_eq(roots.workspace(), Some(root))
  assert_eq(roots.nearest_project(), Some(child))
  let config = @config.build(roots.sources())
  assert_eq(@config.get_text(config, "workspace.marker"), "root")
}

#Order formats at each stage

///|
test "declare ordered groups with an application-owned workspace file" {
  let json = @conventions.Extension::parse("json")
  let toml = @conventions.Extension::parse("toml")
  let layers = @conventions.FormatLayers::new([
    @conventions.FormatGroup::new([json], supplemental=
      @conventions.SupplementalFile::new("acme-workspace.json", json)),
    @conventions.FormatGroup::new([toml]),
  ])
  let conventions = @conventions.base("acme") |> @conventions.layouts
    |> @conventions.format_layers(layers)
    |> @conventions.root_policy(WorkspaceFirst(@config.KeyPath::parse("workspace")))
  let tree = @config.FileTree::new(complete=true)
    .with_listing(@config.FileTreePath::parse("/w"), [
      { name: "acme-workspace.json", kind: File },
      { name: "acme.toml", kind: File },
    ])
    .with_file(@config.FileTreePath::parse("/w/acme-workspace.json"),
      "{workspace:{}, shared:'json', retained:true}")
    .with_file(@config.FileTreePath::parse("/w/acme.toml"), "shared='toml'")
  let builder = @config.builder() |> @config.working_dir("/w")
    |> @config.format(@toml.format()) |> @config.format(@json5.format())
    |> @conventions.add(conventions)
  guard @config.load(builder, tree) is Done(config) else { fail("complete tree") }
  assert_eq(@config.get_text(config, "shared"), "toml")
  assert_eq(@config.bind(config, "retained"), true)
}

#Walk up to the project root

/w/acme.toml          <- found: the project primary
/w/src/
/w/src/nested/        <- the working directory

///|
test "find the project file from a nested directory" {
  let builder = @config.builder()
    |> @config.working_dir("/w/src/nested")
    |> @config.format(@toml.format())
    |> @conventions.add(@conventions.app_dirs("acme"))
  let tree = @config.FileTree::new(complete=true)
    .with_listing(@config.FileTreePath::parse("/w"), [
      { name: "acme.toml", kind: File },
      { name: "src", kind: Directory },
    ])
    .with_listing(@config.FileTreePath::parse("/w/src"), [{ name: "nested", kind: Directory }])
    .with_listing(@config.FileTreePath::parse("/w/src/nested"), [])
    .with_file(@config.FileTreePath::parse("/w/acme.toml"), "project.name = \"acme\"")
  guard @config.load(builder, tree) is Done(config) else {
    fail("a complete tree never asks for files")
  }
  @expect.expect(@config.get_text(config, "project.name")).to_equal("acme")
  let project = config
    .reports()
    .iter()
    .find_first(report => report.kind == File(Workspace))
  @expect.expect(project.map(report => report.path)).to_equal(
    Some(Some("/w/acme.toml")),
  )
}

#Select a file above discovered primaries

///|
test "select JSON over TOML without losing TOML-only settings" {
  let layers = @conventions.FormatLayers::new([
    @conventions.FormatGroup::new([@conventions.Extension::parse("json")]),
    @conventions.FormatGroup::new([@conventions.Extension::parse("toml")]),
  ])
  let conventions = @conventions.base("acme") |> @conventions.layouts
    |> @conventions.format_layers(layers)
    |> @conventions.selected_file_policy(Overlay)
  let tree = @config.FileTree::new(complete=true)
    .with_listing(@config.FileTreePath::parse("/w"), [
      { name: "acme.json", kind: File }, { name: "acme.toml", kind: File },
    ])
    .with_file(@config.FileTreePath::parse("/w/acme.json"), "{shared:'json'}")
    .with_file(@config.FileTreePath::parse("/w/acme.toml"), "shared='toml'\nretained=true")
  let builder = @config.builder() |> @config.working_dir("/w")
    |> @config.format(@json5.format()) |> @config.format(@toml.format())
    |> @conventions.add(conventions, options=
      @conventions.DiscoveryOptions::new(config=Explicit("./acme.json")))
  guard @config.load(builder, tree) is Done(config) else { fail("complete tree") }
  assert_eq(@config.get_text(config, "shared"), "json")
  assert_eq(@config.bind(config, "retained"), true)
  assert_eq(config.reports().filter(report => report.status is Loaded)
    .map(report => report.priority), [300, 325])
}

#Stop boundary and isolated mode

///|
test "a test root keeps files above it out" {
  let builder = @config.builder()
    |> @config.working_dir("/tmp/case/src")
    |> @config.format(@toml.format())
    |> @conventions.add(
      @conventions.app_dirs("acme") |> @conventions.boundary("/tmp/case"),
    )
  let tree = @config.FileTree::new(complete=true)
    .with_listing(@config.FileTreePath::parse("/tmp"), [
      { name: "acme.toml", kind: File },
      { name: "case", kind: Directory },
    ])
    .with_listing(@config.FileTreePath::parse("/tmp/case"), [{ name: "src", kind: Directory }])
    .with_listing(@config.FileTreePath::parse("/tmp/case/src"), [])
  guard @config.load(builder, tree) is Done(config) else {
    fail("a complete tree never asks for files")
  }
  let project = config
    .reports()
    .iter()
    .find_first(report => report.kind == File(Workspace))
  @expect.expect(project.map(report => report.status)).to_equal(Some(NotFound))
}

#System and global user directories

• The file name in each directory is <app>.<ext>.
• An empty variable counts as unset. XDG_CONFIG_HOME counts only when it is absolute, and it has no effect on Windows.
• The user configuration directory and the application home are one global source. Two global files are Ambiguous.
• On Windows, \ becomes / in each variable. An absolute Windows path starts with a drive and a separator (C:/) or with //server/share; C:foo is not absolute. A relative value joins the working directory.

///|
test "the global candidates come from the variable set of the run" {
  let builder = @config.builder()
    |> @config.working_dir("/w")
    |> @config.platform(Linux)
    |> @config.env_vars({ "HOME": "/home/alice", "ACME_HOME": "/opt/acme" })
    |> @config.format(@toml.format())
    |> @conventions.add(@conventions.app_dirs("acme"))
  guard @config.load(builder, @config.FileTree::new(complete=true))
    is Done(config) else {
    fail("a complete tree never asks for files")
  }
  let global = config
    .reports()
    .iter()
    .find_first(report => report.kind == File(Global))
  @expect.expect(global.map(report => report.candidates)).to_equal(
    Some(["/home/alice/.config/acme/acme.toml", "/opt/acme/acme.toml"]),
  )
}

#Overrides next to the project file

///|
test "the user override wins over the project file" {
  let builder = @config.builder()
    |> @config.working_dir("/w")
    |> @config.format(@toml.format())
    |> @conventions.add(@conventions.app_dirs("acme"))
  let tree = @config.FileTree::new(complete=true)
    .with_listing(@config.FileTreePath::parse("/w"), [
      { name: "acme.toml", kind: File },
      { name: "acme.user.toml", kind: File },
    ])
    .with_file(@config.FileTreePath::parse("/w/acme.toml"), "ui.theme = \"shared\"")
    .with_file(@config.FileTreePath::parse("/w/acme.user.toml"), "ui.theme = \"personal\"")
  guard @config.load(builder, tree) is Done(config) else {
    fail("a complete tree never asks for files")
  }
  @expect.expect(@config.get_text(config, "ui.theme")).to_equal("personal")
}

#An explicit project file

#Environments

• The name matches exactly, so acme.production.toml is not the file for Production.
• An environment file alone does not mark a project root.
• Two environment files for one project file, such as acme.Production.toml and acme.Production.yaml, are Ambiguous.
• The system file, the global user file, a legacy file and an explicit file outside the standard layouts have no environment file.

///|
test "the environment file of the run wins over the project file" {
  let conventions = @conventions.app_dirs("acme")
    |> @conventions.environments(default="Development")
  let vars = { "ACME_ENVIRONMENT": "Production", "ACME_UI__THEME": "dark" }
  let builder = @config.builder()
    |> @config.working_dir("/w")
    |> @config.env_vars(vars)
    |> @config.format(@toml.format())
    |> @conventions.add(conventions)
    |> @config.env(prefix="ACME", reserved=["ACME_ENVIRONMENT", "ACME_HOME"])
  let tree = @config.FileTree::new(complete=true)
    .with_listing(@config.FileTreePath::parse("/w"), [
      { name: "acme.toml", kind: File },
      { name: "acme.Production.toml", kind: File },
    ])
    .with_file(@config.FileTreePath::parse("/w/acme.toml"), "log.level = \"info\"")
    .with_file(@config.FileTreePath::parse("/w/acme.Production.toml"), "log.level = \"warn\"")
  guard @config.load(builder, tree) is Done(config) else {
    fail("a complete tree never asks for files")
  }
  @expect.expect(@conventions.environment_name(conventions, vars)).to_equal(
    Some("Production"),
  )
  @expect.expect(@config.get_text(config, "log.level")).to_equal("warn")
  @expect.expect(@config.get_text(config, "ui.theme")).to_equal("dark")
  // The reserved names give no configuration key.
  @expect.expect(config.get(@config.KeyPath::parse("environment"))).to_equal(
    None,
  )
}

#Choose the parts

///|
test "remove the system part, or build from single parts" {
  // No system file, for a tool that never installs machine-wide.
  let tool = @conventions.app_dirs("acme") |> @conventions.without(SystemDir)
  // Only the project file in three layouts and a user override.
  let minimal = @conventions.base("acme")
    |> @conventions.layouts
    |> @conventions.user_overrides
  let kinds = (conventions : @conventions.Conventions) => {
    let builder = @config.builder()
      |> @config.working_dir("/w")
      |> @config.platform(Linux)
      |> @config.env_vars({ "HOME": "/home/alice" })
      |> @config.format(@toml.format())
      |> @conventions.add(conventions)
    let tree = @config.FileTree::new(complete=true)
      .with_listing(@config.FileTreePath::parse("/w"), [{ name: "acme.toml", kind: File }])
      .with_file(@config.FileTreePath::parse("/w/acme.toml"), "a = 1")
    guard @config.load(builder, tree) is Done(config) else {
      fail("a complete tree never asks for files")
    }
    config.reports().map(report => report.kind.report_name())
  }
  @expect.expect(kinds(tool)).to_equal([
    "global", "project", "local-override", "user-override",
  ])
  @expect.expect(kinds(minimal)).to_equal(["project", "user-override"])
}

#Workspaces and members

/w/acme.toml                        <- workspace primary: members = ["packages/*"]
/w/acme.user.toml                   <- workspace user override
/w/packages/billing/acme.toml       <- member primary
/w/packages/billing/acme.user.toml  <- member user override, which wins
/w/packages/billing/src/            <- the working directory

///|
test "the member file wins over the workspace file" {
  let builder = @config.builder()
    |> @config.working_dir("/w/packages/billing/src")
    |> @config.format(@toml.format())
    |> @conventions.add(@conventions.app_dirs("acme") |> @conventions.workspace)
  let tree = @config.FileTree::new(complete=true)
    .with_listing(@config.FileTreePath::parse("/w"), [
      { name: "acme.toml", kind: File },
      { name: "packages", kind: Directory },
    ])
    .with_listing(@config.FileTreePath::parse("/w/packages"), [{ name: "billing", kind: Directory }])
    .with_listing(@config.FileTreePath::parse("/w/packages/billing"), [
      { name: "acme.toml", kind: File },
      { name: "src", kind: Directory },
    ])
    .with_listing(@config.FileTreePath::parse("/w/packages/billing/src"), [])
    .with_file(@config.FileTreePath::parse("/w/acme.toml"),
      "workspace.members = [\"packages/*\"]\nui.theme = \"light\"",
    )
    .with_file(@config.FileTreePath::parse("/w/packages/billing/acme.toml"), "ui.theme = \"dark\"")
  guard @config.load(builder, tree) is Done(config) else {
    fail("a complete tree never asks for files")
  }
  @expect.expect(@config.get_text(config, "ui.theme")).to_equal("dark")
  let roles = config
    .reports()
    .filter(report => report.kind is File(Workspace | Member))
    .map(report => (report.kind, report.priority, report.path))
  @expect.expect(roles).to_equal([
    (File(Workspace), 300, Some("/w/acme.toml")),
    (File(Member), 350, Some("/w/packages/billing/acme.toml")),
  ])
}

#Key filters

///|
test "a member cannot set a workspace key and does not inherit the root project" {
  let conventions = @conventions.app_dirs("acme")
    |> @conventions.workspace
    |> @conventions.member_scope_keys(["workspace.out_dir"])
    |> @conventions.inherited_filter(["project"])
  let builder = @config.builder()
    |> @config.working_dir("/w/app")
    |> @config.format(@toml.format())
    |> @conventions.add(conventions)
  let tree = @config.FileTree::new(complete=true)
    .with_listing(@config.FileTreePath::parse("/w"), [
      { name: "acme.toml", kind: File },
      { name: "app", kind: Directory },
    ])
    .with_listing(@config.FileTreePath::parse("/w/app"), [{ name: "acme.toml", kind: File }])
    .with_file(@config.FileTreePath::parse("/w/acme.toml"),
      "workspace.members = [\"app\"]\nworkspace.out_dir = \"out\"\nproject.name = \"root\"",
    )
    .with_file(@config.FileTreePath::parse("/w/app/acme.toml"), "workspace.out_dir = \"mine\"")
  guard @config.load(builder, tree) is Done(config) else {
    fail("a complete tree never asks for files")
  }
  @expect.expect(@config.get_text(config, "workspace.out_dir")).to_equal("out")
  @expect.expect(config.get(@config.KeyPath::parse("project.name"))).to_equal(
    None,
  )
  let member_report = config
    .reports()
    .iter()
    .find_first(report => report.kind == File(Member))
  @expect.expect(member_report.map(report => report.warnings.length())).to_equal(
    Some(1),
  )
}

#Legacy fallback

#One directory at a time

///|
test "discovery asks for the listing of the working directory first" {
  let builder = @config.builder()
    |> @config.working_dir("/w/src")
    |> @config.format(@toml.format())
    |> @conventions.add(@conventions.app_dirs("acme"))
  guard @config.load(builder, @config.FileTree::new()) is Need(requests) else {
    fail("an empty tree needs a listing")
  }
  @expect.expect(requests).to_equal([
    ListDir(@config.FileTreePath::parse("/w/src")),
    ListDir(@config.FileTreePath::parse("/w/src/.acme")),
    ListDir(@config.FileTreePath::parse("/w/src/.config/acme")),
  ])
}

#Names

#Compose configuration profiles

///|
test "load controls and a profile with recorded metadata" {
  let tree = @config.FileTree::new(complete=true)
    .with_listing(@config.FileTreePath::parse("/workspace"), [
      { name: "acme.toml", kind: File },
      { name: "acme.profile.metrics.toml", kind: File },
    ])
    .with_file(@config.FileTreePath::parse("/workspace/acme.toml"),
      "[profiles]\nactive=['production']\n[profiles.groups]\nproduction=['metrics']")
    .with_file(@config.FileTreePath::parse("/workspace/acme.profile.metrics.toml"),
      "telemetry=true")
  let builder = @config.builder()
    |> @config.working_dir("/workspace") |> @config.env_vars({})
    |> @config.format(@toml.format())
    |> @conventions.add(@conventions.base("acme") |> @conventions.layouts
      |> @conventions.profiles(@profiles.Policy::new()))
  guard @config.load(builder,tree) is Done(config) else { fail("complete tree") }
  assert_true(config.profiles().contains(@config.ProfileName::parse("metrics")))
  assert_eq(config.get(@config.KeyPath::parse("profiles")),None)
}