php-sdk.dang

"""
Manage Dagger modules that use the PHP SDK.
"""
type PhpSdk {
  # Matches `"sdk": { "source": "php" }` in a legacy dagger.json.
  let legacyConfigPattern = "\"sdk\"\\s*:\\s*\\{[^}]*\"source\"\\s*:\\s*\"php\""

  # Matches a `[runtime]` table with `source = "php"` in a CLI 1.0
  # dagger-module.toml.
  let tomlConfigPattern = "\\[runtime\\][^\\[]*source\\s*=\\s*\"php\""

  let moduleConfigFilenames: [String!]! = ["dagger-module.toml", "dagger.json"]

  """
  Marker filename that skips generate when found at or above a PHP SDK module root.
  """
  pub skipGenerateFilename: String! = ".dagger-php-sdk-skip-generate"

  """
  Starter template under templates/<template> for a new module.
  """
  pub template: String! = "minimal"

  """
  The engine release a module's generated code targets: the floor or later, and
  the release this SDK generates for or earlier. Empty takes the release this SDK
  generates for.
  """
  pub targetVersion: String! = ""

  """
  Find the PHP client root containing the workspace cwd: the directory of the
  nearest composer.json, relative to the workspace root. A module's vendored
  SDK carries its own composer.json under sdk/, so the module owning it answers
  instead. Null when there is none.
  """
  pub findClientRoot(ws: Workspace!): String {
    let found = ws.findUp("composer.json")
    if (found == null) {
      null
    } else {
      let root = normalizePath(found.trimSuffix("composer.json"))
      let vendorParent = if (root == "sdk") { "." } else { root.trimSuffix("/sdk") }
      if (vendorParent != root and hasModuleConfig(ws, vendorParent)) {
        vendorParent
      } else {
        root
      }
    }
  }

  """
  Generate one SDK scope: the module at the workspace cwd, when the scope is a
  module. A scope without a module config is first seeded from the `template`
  setting, keeping the files already there, and given a dagger-module.toml. A
  self-contained module then moves to the entrypoint this SDK generates; see
  Mod.usesEntrypoint. Module clients are not generated yet.
  """
  pub generateScope(ws: Workspace!, isModule: Boolean!, name: String!, clients: [ModuleSource!]!): Workspace! {
    checkEngine
    if (clients.length > 0) {
      raise "php-sdk does not generate module clients yet"
    }

    if (isModule == false) {
      ws
    } else {
      let scope = normalizePath(ws.cwd)
      # Mod.rootPath is workspace-root-relative, so the scope is generated from
      # the root and the cwd restored afterwards: the engine rejects a result
      # whose cwd is not the scope.
      let rooted = ws.withWorkdir(".")
      let target = targetRelease("module \"" + name + "\"")
      let selectedTemplate = if (template == "") { "minimal" } else { template }
      let initialized = if (hasModuleConfig(ws, scope)) {
        rooted
      } else if (currentModule.source.exists("templates/" + selectedTemplate) == false) {
        raise "unknown init template: " + template
      } else {
        sdkHelpers.moduleManifest
          .withName(name: name)
          .withLegacyRuntime(runtime: "php", engineVersion: target)
          .generate(
            rooted.withDirectory(scope, renderedTemplate(name, selectedTemplate)).withWorkdir(scope),
            legacyJson: false,
          )
          .withWorkdir(".")
      }
      targetedMod(scope, initialized, name, "module \"" + name + "\"").generated.withWorkdir(scope)
    }
  }

  """
  The engine API version a new module declares: the last release before the
  identifier-casing cut, which dagger/dagger gates at v1.0.0-beta.26 and which
  renames core API fields and changes module naming. It stays before that cut until
  the PHP codegen is ported to those rules. Released engines compare base versions,
  so older engines load it. The module's client schema, its DAGGER_CLIENT_VERSION
  and its dang.toml use this one value. Moving it across that cut also means
  checking the naming that sdk/src/Module/EngineNaming.php mirrors.
  """
  let targetEngineVersion: String! = "v1.0.0-beta.25"

  """
  The oldest release the generated entrypoint passed on, for modules targeting
  v1.0.0-beta.21. It has not run again with the current target.
  """
  let floorEngineVersion: String! = "v1.0.0-beta.17"

  """
  Whether the running engine is below the floor. Released engines compare base
  versions, so the manifest's engineVersion does not keep an older v1.0.0
  prerelease out. A dev build or a later release is not below it.
  """
  let belowEngineFloor: Boolean! {
    let prefix = "v1.0.0-beta."
    let release = version.split("+")[0] ?? version
    let beta = release.trimPrefix(prefix)
    let floor = floorEngineVersion.trimPrefix(prefix)
    release.hasPrefix("v0.") or release.hasPrefix("v1.0.0-0") or
      (beta != release and beta.containsMatch("^[0-9]+$") and beta.padLeft(6) < floor.padLeft(6))
  }

  let checkEngine: Void {
    if (belowEngineFloor) {
      raise "php-sdk needs an engine from " + floorEngineVersion + ", and this one is " + version + ": upgrade the engine"
    }
    null
  }

  let modAt(path: String!, ws: Workspace!, name: String!, target: String! = targetEngineVersion): Mod! {
    Mod(
      rootPath: path,
      ws: ws,
      skipGenerateFilename: skipGenerateFilename,
      targetEngineVersion: target,
      givenName: name,
    )
  }

  """
  The module at path, generating for targetRelease. A pin on a module that keeps
  the PHP runtime is refused: the engine regenerates that module for its
  manifest's engineVersion.
  """
  let targetedMod(path: String!, ws: Workspace!, name: String!, subject: String!): Mod! {
    let target = targetRelease(subject)
    let mod = modAt(path, ws, name, target)
    if (targetVersion != "" and mod.skipGenerate == false and mod.usesEntrypoint == false) {
      raise subject + " pins targetVersion " + target + ", which applies to the generated entrypoint only: this module keeps the PHP runtime, which generates for the engineVersion of its manifest. Remove targetVersion from the scope's settings in dagger.toml"
    }
    mod
  }

  """
  The release a module generates for. A targetVersion this SDK cannot generate for
  is refused before anything is written.
  """
  let targetRelease(subject: String!): String! {
    if (targetVersion == "") { return targetEngineVersion }
    let fix = "Set targetVersion between " + floorEngineVersion + " and " + targetEngineVersion + " in the scope's settings in dagger.toml, or remove it"
    if (targetVersion.containsMatch(Regexp(releasePattern)) == false) {
      raise subject + " pins targetVersion " + JSON.encode(targetVersion) + ", which is not a Dagger release such as " + targetEngineVersion + ". " + fix
    }
    let bare = targetVersion.split("+")[0] ?? targetVersion
    let target = if (bare.hasPrefix("v")) { bare } else { "v" + bare }
    if (releasePrecedes(target, floorEngineVersion)) {
      raise subject + " pins targetVersion " + target + ", which this release of the PHP SDK cannot generate for: it is below " + floorEngineVersion + ", the oldest engine this SDK runs on. " + fix
    }
    if (releasePrecedes(targetEngineVersion, target)) {
      raise subject + " pins targetVersion " + target + ", which this release of the PHP SDK cannot generate for: it targets " + targetEngineVersion + " at most. " + fix + ", or install the SDK release built for " + target
    }
    target
  }

  """v?MAJOR.MINOR.PATCH, then an optional prerelease and build, as in the Go SDK."""
  let releasePattern: String! = "^v?([0-9]+)\\.([0-9]+)\\.([0-9]+)(?:-([0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*))?(?:\\+[0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*)?$"

  """Semver precedence; false when either is not a release, so an unreadable version passes."""
  let releasePrecedes(a: String!, b: String!): Boolean! {
    let pattern = Regexp(releasePattern)
    let ma = a.match(pattern)
    if (ma == null) { return false }
    let mb = b.match(pattern)
    if (mb == null) { return false }
    let ca = ma.captures
    let cb = mb.captures
    let coreA = [ca[0] ?? "", ca[1] ?? "", ca[2] ?? ""]
    let coreB = [cb[0] ?? "", cb[1] ?? "", cb[2] ?? ""]
    if (identifiersPrecede(coreA, coreB, 0)) { return true }
    if (identifiersPrecede(coreB, coreA, 0)) { return false }
    let preA = ca[3] ?? ""
    let preB = cb[3] ?? ""
    if (preA == "") {
      false
    } else if (preB == "") {
      true
    } else {
      identifiersPrecede(preA.split("."), preB.split("."), 0)
    }
  }

  """Numbers by value before words, words by ASCII, a prefix first."""
  let identifiersPrecede(a: [String!]!, b: [String!]!, i: Int!): Boolean! {
    if (i >= a.length) { return i < b.length }
    if (i >= b.length) { return false }
    let x = a[i] ?? ""
    let y = b[i] ?? ""
    if (x == y) { return identifiersPrecede(a, b, i + 1) }
    let xNumber = x.containsMatch(Regexp("^[0-9]+$"))
    let yNumber = y.containsMatch(Regexp("^[0-9]+$"))
    if (xNumber and yNumber) {
      let xDigits = x.split("").length
      let yDigits = y.split("").length
      if (xDigits == yDigits) { x < y } else { xDigits < yDigits }
    } else {
      xNumber or (yNumber == false and x < y)
    }
  }

  """
  Whether a module config exists in a workspace-root-relative directory.
  """
  let hasModuleConfig(ws: Workspace!, dir: String!): Boolean! {
    moduleConfigFilenames.filter { filename =>
      let path = if (dir == ".") { filename } else { dir + "/" + filename }
      ws.directory("/", include: [path]).exists(path)
    }.length > 0
  }

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

  """
  Return init templates tracked by this module.

  Templates live under templates/<name> and are materialized into a new module
  before generation. The `template` setting selects one; empty selects the
  default.
  """
  pub templates: [Template!]! {
    if (currentModule.source.exists("templates")) {
      let root = currentModule.source.directory("templates")
      root.entries.map { name =>
        Template(
          name: name.trimSuffix("/"),
          source: root.directory(name),
        )
      }
    } else {
      directory.entries.map { name =>
        Template(
          name: name,
          source: directory,
        )
      }
    }
  }

  """
  Return the PHP SDK module at or above a workspace path.

  When `findUp` is true, `path` may point inside the module.
  """
  pub mod(ws: Workspace!, path: String! = ".", findUp: Boolean! = true): Mod! {
    checkEngine
    let modPath = if (findUp) {
      # Pick the nearest enclosing config regardless of filename ordering.
      let foundConfigPath = moduleConfigFilenames.reduce(null) { nearest, filename =>
        let found = ws.findUp(filename, path)
        if (configHitDepth(found) > configHitDepth(nearest)) { found } else { nearest }
      }
      if (foundConfigPath == null) {
        raise "no Dagger module found containing path: " + path
      } else {
        let configPath = foundConfigPath.trimPrefix("/")
        if (isPhpConfig(ws, configPath) == false) {
          raise "Dagger module does not use the PHP SDK: " + path
        } else {
          let dir = configPath.split("/").dropLast(1).join("/")
          if (dir == "") { "." } else { dir }
        }
      }
    } else {
      normalizePath(path)
    }

    targetedMod(modPath, ws, "", "module at " + modPath)
  }

  """
  Return the depth of the directory containing a find-up result.
  """
  let configHitDepth(hit: String): Int! {
    if (hit == null) {
      -1
    } else {
      let dir = hit.split("/").dropLast(1).join("/").trimPrefix("/")
      if (dir == "") { 0 } else { dir.split("/").length }
    }
  }

  """
  Whether a module config selects the PHP runtime or the entrypoint this SDK
  generates.
  """
  let isPhpConfig(ws: Workspace!, configPath: String!): Boolean! {
    let dir = configPath.split("/").dropLast(1).join("/")
    selectsPhpRuntime(ws, configPath) or modAt(if (dir == "") { "." } else { dir }, ws, "").ownsEntrypoint
  }

  let selectsPhpRuntime(ws: Workspace!, configPath: String!): Boolean! {
    let pattern = if (configPath.trimSuffix("dagger-module.toml") != configPath) {
      tomlConfigPattern
    } else {
      legacyConfigPattern
    }
    ws
      .directory("/", include: [configPath])
      .file(configPath)
      .search(
        pattern: pattern,
        multiline: true,
        dotall: true,
        limit: 1,
      )
      .{{id}}
      .length > 0
  }

  """
  Render a PHP template with the requested module name.
  """
  let renderedTemplate(name: String!, templateName: String!): Directory! {
    container
      .from("golang:1.25-alpine")
      .withoutEntrypoint
      .withMountedCache("/go/pkg/mod", cacheVolume("go-mod"))
      .withMountedCache("/root/.cache/go-build", cacheVolume("go-build"))
      .withDirectory("/helper", currentModule.source.directory("helpers/render-template"))
      .withDirectory("/template", currentModule.source.directory("templates/" + templateName))
      .withWorkdir("/helper")
      .withExec(["go", "build", "-o", "/usr/local/bin/render-template", "."])
      .withExec(["render-template", name, "/template", "/rendered"])
      .directory("/rendered")
  }
}