mod.dang

"""
A Dagger module that uses the Python SDK.
"""
type Mod {
  """
  Workspace-root-relative path of this module root.
  """
  pub rootPath: String!

  """
  The workspace this module belongs to.
  """
  let ws: Workspace!

  """
  How the engine runs this module: "generated" for an entrypoint written into
  it, "remote" for the one this SDK publishes, "runtime" for a runtime the
  manifest names. A module keeps the kind its manifest has.
  """
  pub entrypointMode: String!

  """
  Whether this generation converts a module the builtin Python runtime ran,
  whose code expects the global client.
  """
  let migrating: Boolean!

  """
  The engine version the scope's code is generated against, empty for the
  engine's own view. Only a module that keeps a runtime of its own runs on a
  version of its own, and only the caller knows which runtime the manifest
  names.
  """
  let engineVersion: String!

  """
  The module scope's clients, as the engine hands them to generation. Null
  reads them from the workspace config, for a module generated directly.
  """
  let clients: [ModuleSource!]

  """
  Module root relative to the client's cwd.
  """
  pub path: String! {
    let cwd = ws.cwd.trimPrefix("/").trimSuffix("/")
    if (rootPath == cwd) {
      "."
    } else if (cwd == "") {
      rootPath
    } else if (rootPath.trimPrefix(cwd + "/") != rootPath) {
      rootPath.trimPrefix(cwd + "/")
    } else if (rootPath == "." or cwd.trimPrefix(rootPath + "/") != cwd) {
      let depth = if (rootPath == ".") { 0 } else { rootPath.split("/").length }
      cwd.split("/").dropFirst(depth).map { segment => ".." }.join("/")
    } else {
      rootPath
    }
  }

  """
  Manage this module's Python build configuration (pyproject.toml).
  """
  pub config: ModConfig! {
    ModConfig(path: rootPath, ws: ws)
  }

  """
  Generate this module.
  """
  pub generate: Changeset! {
    generated.changes(ws)
  }

  """
  The workspace with this module's scope generated. On the static path the
  entrypoint manifest and the entrypoint are written here too, so a module
  generated directly gets the same files as one generated through the SDK
  scope.
  """
  pub generated: Workspace! {
    if (isModern == false) {
      # A pre-1.0 module is still generated by the engine's builtin Python SDK.
      # Merge, don't replace: the generated context holds only generated files.
      ws.withDirectory("/" + rootPath, ws
        .moduleSource("/" + rootPath)
        .generatedContextDirectory
        .directory(rootPath))
    } else {
      checkPython
      let scope = Scope(
        path: rootPath,
        ws: ws,
        clients: clients ?? declaredClients,
        isModule: true,
        engineVersion: engineVersion,
        migrating: migrating,
      )
      # The scope writes sdk/ whole, so an entrypoint from an earlier static
      # generation is gone unless it is written again. It also relocks
      # uv.lock, which the derived resources are checked against.
      let scoped = scope.generated
      if (entrypointMode == "generated") {
        let outside = PyprojectHelper().outsidePaths(scoped, rootPath)
        checkResourcesLoad(scoped, outside)
        let entrypointPath = vendorDirName + "/" + entrypointDirName
        entrypointManifest(scoped.withDirectory("/" + rootPath + "/" + entrypointPath, entrypointDir(scoped, patterns(outside))), entrypointPath)
      } else if (entrypointMode == "remote") {
        checkNoResources(PyprojectHelper().outsidePaths(scoped, rootPath))
        scoped
      } else {
        scoped
      }
    }
  }

  """
  Refuse a module that asks for an older Python than the SDK runs on before
  anything is written: uv would lock it to the SDK's Python, and the runtime
  would still build it on the older one, where the install fails. Beside
  checkEngine, which refuses the engine: this one reads the module, so only
  generation runs it, and config set stays open to fix the module.
  """
  let checkPython: Void {
    let refusal = PyprojectHelper().pythonRefusal(ws.directory("/" + rootPath, include: ["pyproject.toml", ".python-version"]))
    if (refusal != "") {
      raise "the module at " + rootPath + ": " + refusal + ", then run dagger generate again"
    }
    null
  }

  """
  The clients the workspace config declares on this module's scope. The
  config names a local client by its path from the workspace root, starting
  with "./", and a Git client by its ref.
  """
  let declaredClients: [ModuleSource!]! {
    ws.sdk(name: currentModule.name)
      .clients.{{name, source}}
      .filter { client => scopeOf(client.name) == rootPath }
      .map { client =>
        if (client.source.hasPrefix(".") or client.source.hasPrefix("/")) {
          ws.moduleSource("/" + scopeOf(client.source))
        } else {
          moduleSource(client.source)
        }
      }
  }

  let scopeOf(path: String!): String! {
    let trimmed = path.trimPrefix("./").trimPrefix("/").trimSuffix("/")
    if (trimmed == "") { "." } else { trimmed }
  }

  """
  Write the manifest of a static module: the name and the Dang entrypoint,
  and nothing the runtime manifest keeps. sdk-helpers owns the manifest's
  shape, so the SDK never writes the TOML itself.
  """
  let entrypointManifest(target: Workspace!, entrypointPath: String!): Workspace! {
    sdkHelpers.moduleManifest
      .withName(name: moduleName)
      .withDangEntrypoint(source: "./" + entrypointPath)
      .generate(target.withWorkdir(rootPath), lock: false, legacyJson: false)
      .withWorkdir(".")
  }

  """
  Whether this module uses the 1.0 dagger-module.toml config.
  """
  let isModern: Boolean! {
    ws.directory("/", include: [manifestPath]).exists(manifestPath)
  }

  let manifestPath: String! {
    if (rootPath == ".") { "dagger-module.toml" } else { rootPath + "/dagger-module.toml" }
  }

  let hasEntrypointManifest: Boolean! {
    isModern and ManifestToml(ws.file("/" + manifestPath).contents).hasEntrypoint
  }

  let manifestConfig: JSONValue! {
    json.withContents((JSON.encode(TOML.decode(ws.file("/" + manifestPath).contents)) :: Dagger.JSON!))
  }

  let moduleName: String! {
    if (manifestConfig.fields.contains("name")) {
      manifestConfig.field(["name"]).asString
    } else {
      raise "no module name in " + manifestPath
    }
  }


  """
  The generated workspace with the module's own manifest, entrypoint table
  taken out, which the module's container is built from.

  An engine that loads manifest version 2 would resolve the entrypoint here,
  shared or static, and build the module from source it has not generated
  yet. So the runtime manifest points back at the module being built.
  """
  let staging(target: Workspace!, outside: [String!]!): Workspace! {
    if (hasEntrypointManifest) {
      let staged = ManifestToml(ws.file("/" + manifestPath).contents).withoutEntrypoint
      let loaded = sdkHelpers.moduleManifest(loadToml: staged)
      # A static entrypoint manifest holds no runtime to fall back on.
      let runnable = if (manifestConfig.fields.contains("runtime")) {
        loaded
      } else {
        loaded.withLegacyPythonRuntime
      }
      # The build that renders the types reads the path sources outside the
      # module directory, which the entrypoint's sources will return.
      let included = outside.reduce(runnable) { manifest, pattern => manifest.withLegacyInclude(path: pattern) }
      included.withName(name: moduleName)
        .generate(target.withWorkdir(rootPath), lock: false, legacyJson: false)
        .withWorkdir(".")
    } else {
      target
    }
  }

  """
  The entrypoint the engine loads instead of calling a runtime: the module's
  own container renders its types, and the container build travels with it.
  """
  let entrypointDir(generated: Workspace!, outside: [String!]!): Directory! {
    pythonSdkRuntime
      .moduleRuntime(modSource: staging(generated, outside).moduleSource("/" + rootPath), introspectionJson: null)
      .withExec(["python", "-m", "dagger.mod", "entrypoint", "--name", moduleName, "--output", entrypointOutput] +
        outside.map { pattern => "--outside=" + pattern })
      .directory(entrypointOutput)
      .withNewFile("build.dang", buildDang)
      .withNewFile("workspace_reader.py", currentModule.source.file("runtime/workspace_reader.py").contents)
  }

  """
  runtime/build.dang with its reads of this module's source inlined, so the
  copy in a generated entrypoint needs nothing but itself and the workspace
  reader written beside it.
  """
  let buildDang: String! {
    let pins = "let defaultBaseImage: String! = \"" + imageFrom("runtime/images/base/Dockerfile") + "\"\n" +
      "  let defaultUvImage: String! = \"" + imageFrom("runtime/images/uv/Dockerfile") + "\"\n" +
      "  let workspaceReader: String! { source.file(\"" + vendorDirName + "/" + entrypointDirName + "/workspace_reader.py\").contents }"
    let inlined = currentModule.source.file("runtime/build.dang").contents
      .replaceMatches("(?s)#<externals>.*?#</externals>", pins)
    if (inlined.contains("currentModule")) {
      raise "runtime/build.dang reads currentModule outside its externals block"
    } else {
      inlined
    }
  }

  let imageFrom(path: String!): String! {
    let line = currentModule.source.file(path).contents.match("(?m)^FROM\\s+(\\S+)")
    if (line == null) {
      raise "no FROM line in " + path
    } else {
      line.captures[0] ?? ""
    }
  }

  let patterns(outside: [OutsidePath!]!): [String!]! {
    outside.map { path => path.pattern }
  }

  """
  Refuse derived resources this workspace cannot load: a path that holds no
  file, or only what .gitignore drops from a local module, loads nothing, and
  sources reads each path as a directory, which a wheel is not. A symlink is
  imported without the path it names, so a path through one is refused before
  it reads as missing or as a file.
  """
  let checkResourcesLoad(target: Workspace!, outside: [OutsidePath!]!): Void {
    outside.each { path =>
      let named = "module \"" + moduleName + "\" builds with " + path.pattern + ", which"
      let prefixes = path.rooted.split("/").reduce([] :: [String!]!) { found, part =>
        found + [if (found.length == 0) { part } else { (found[found.length - 1] ?? "") + "/" + part }]
      }
      let links = prefixes.filter { prefix =>
        target.directory("/", include: [prefix], exclude: [prefix + "/**"]).exists(prefix, expectedType: ExistsType.SYMLINK_TYPE)
      }
      if (links.length > 0) {
        raise named + " goes through the symlink " + (links[0] ?? "") + " in the workspace; outside path sources through a symlink are not supported: point the path source at the directory it names"
      }
      let selected = target.directory("/", include: [path.rooted], exclude: ["**/.git"])
      if (files(selected).length == 0) {
        raise named + " holds no file in the workspace"
      }
      if (selected.exists(path.rooted, expectedType: ExistsType.DIRECTORY_TYPE) == false) {
        raise named + " is a file; outside file sources, such as a wheel, are not supported: point the path source at a directory, such as the project that builds it"
      }
      if (files(target.directory("/", include: [path.rooted], exclude: ["**/.git"], gitignore: true)).length == 0) {
        raise named + " holds only files that .gitignore ignores"
      }
      null
    }
    null
  }

  """
  Refuse derived resources on a module that runs on an entrypoint this SDK
  does not generate into it: only that entrypoint returns them from its
  sources, so the module would fail at call time.
  """
  let checkNoResources(outside: [OutsidePath!]!): Void {
    if (outside.length > 0) {
      raise "module \"" + moduleName + "\" builds with files outside its directory (" + patterns(outside).join(", ") +
        "), which only the entrypoint this SDK generates into a module loads; it runs on the entrypoint " +
        ManifestToml(ws.file("/" + manifestPath).contents).entrypointSource + " instead"
    }
    null
  }

  """
  A directory whose files a filter removed is still listed, so it does not
  count.
  """
  let files(dir: Directory!): [String!]! {
    dir.glob("**").filter { path => path.hasSuffix("/") == false }
  }

  let vendorDirName: String! = "sdk"
  let entrypointDirName: String! = "entrypoint"
  let entrypointOutput: String! = "/dagger/entrypoint"
}