Promote staging to production (100a545)

openlayer-java-core/src/main/kotlin/com/openlayer/api/models/backgroundtasks/BackgroundTaskRetrieveParams.kt

@@ -9,13 +9,7 @@ import java.util.Objects
 import java.util.Optional
 import kotlin.jvm.optionals.getOrNull
 
-/**
- * Retrieve a background task's status, progress and results.
- *
- * Endpoints that cannot answer within one request queue a task and hand back its id -- for example
- * `POST /frameworks/{frameworkId}/export`. Poll this endpoint until `complete` is `true`, then read
- * what the task produced from `outputs`.
- */
+/** Retrieve a background task's status and outputs. */
 class BackgroundTaskRetrieveParams
 private constructor(
     private val taskId: String?,

openlayer-java-core/src/main/kotlin/com/openlayer/api/models/backgroundtasks/BackgroundTaskRetrieveResponse.kt

@@ -18,6 +18,10 @@ import java.util.Objects
 import java.util.Optional
 import kotlin.jvm.optionals.getOrNull
 
+/**
+ * A job queued by an endpoint that can't answer within one request, such as a framework export.
+ * Poll it until `complete` is `true`, then read what it produced from `outputs`.
+ */
 class BackgroundTaskRetrieveResponse
 @JsonCreator(mode = JsonCreator.Mode.DISABLED)
 private constructor(

openlayer-java-core/src/main/kotlin/com/openlayer/api/models/commits/CommitRetrieveParams.kt

@@ -9,7 +9,7 @@ import java.util.Objects
 import java.util.Optional
 import kotlin.jvm.optionals.getOrNull
 
-/** Retrieve a project version (commit) by its id. */
+/** Retrieve a project commit. */
 class CommitRetrieveParams
 private constructor(
     private val projectVersionId: String?,

openlayer-java-core/src/main/kotlin/com/openlayer/api/models/governance/frameworks/FrameworkCreateParams.kt

@@ -23,16 +23,7 @@ import java.util.Objects
 import java.util.Optional
 import kotlin.jvm.optionals.getOrNull
 
-/**
- * Create a custom governance framework in a workspace.
- *
- * Use this to track compliance against an internal policy, or against a standard Openlayer does not
- * ship as a built-in framework. A new framework starts with no rules -- add them from the Openlayer
- * app, or map an existing rule to it.
- *
- * A framework is created disabled unless you pass `enabled: true`. While it is disabled its rules
- * are not evaluated and do not count towards compliance.
- */
+/** Create a custom framework in a workspace. */
 class FrameworkCreateParams
 private constructor(
     private val workspaceId: String?,

openlayer-java-core/src/main/kotlin/com/openlayer/api/models/governance/frameworks/FrameworkCreateResponse.kt

@@ -21,6 +21,10 @@ import java.util.Objects
 import java.util.Optional
 import kotlin.jvm.optionals.getOrNull
 
+/**
+ * A set of rules, drawn from a regulation, a standard, or your own internal policy, that Openlayer
+ * tracks compliance against. Openlayer ships built-in frameworks, and you can create your own.
+ */
 class FrameworkCreateResponse
 @JsonCreator(mode = JsonCreator.Mode.DISABLED)
 private constructor(
@@ -205,7 +209,8 @@ private constructor(
     fun href(): Optional<String> = href.getOptional("href")
 
     /**
-     * Whether the framework definition is managed by Openlayer and cannot be edited.
+     * Whether the framework definition is managed by Openlayer. For these frameworks only
+     * `enabled`, `tags`, and `projectSelector` can be changed.
      *
      * @throws OpenlayerInvalidDataException if the JSON field has an unexpected type (e.g. if the
      *   server responded with an unexpected value).
@@ -621,7 +626,10 @@ private constructor(
          */
         fun href(href: JsonField<String>) = apply { this.href = href }
 
-        /** Whether the framework definition is managed by Openlayer and cannot be edited. */
+        /**
+         * Whether the framework definition is managed by Openlayer. For these frameworks only
+         * `enabled`, `tags`, and `projectSelector` can be changed.
+         */
         fun immutable(immutable: Boolean) = immutable(JsonField.of(immutable))
 
         /**

openlayer-java-core/src/main/kotlin/com/openlayer/api/models/governance/frameworks/FrameworkExportParams.kt

@@ -19,26 +19,7 @@ import java.util.Objects
 import java.util.Optional
 import kotlin.jvm.optionals.getOrNull
 
-/**
- * Export a framework's evidence and progress as an audit-ready zip archive.
- *
- * The archive holds every evidence file uploaded against the framework's evidence-based rules, a
- * markdown report of the framework's progress and the status of all its rules (broken down by
- * documentation section when the framework has documents), and CSV manifests of rules and evidence
- * with SHA-256 checksums.
- *
- * Send `projectId` to export one project's compliance with the framework. Omit it for the
- * workspace-wide view across every project in the framework, including workspace-scoped rules.
- *
- * The export runs as a background task, so this returns `202` immediately. To collect the archive:
- * 1. Poll `GET /background-tasks/{taskId}` with the returned `taskResultId` until `complete` is
- *    `true`.
- * 2. Read `outputs.storageUri` off that task.
- * 3. Exchange it for a download link at `GET /storage/presigned-url?storageUri=<uri>`.
- *
- * Rate limited to 2 requests per minute per framework. Asking for an export while an identical one
- * is still queued returns that task rather than starting a second one.
- */
+/** Export a framework as an audit-ready zip archive. */
 class FrameworkExportParams
 private constructor(
     private val frameworkId: String?,
@@ -50,7 +31,8 @@ private constructor(
     fun frameworkId(): Optional<String> = Optional.ofNullable(frameworkId)
 
     /**
-     * Scope the export to this project. It must belong to the framework.
+     * Scope the export to this project. It must belong to the framework. Omit it for the
+     * workspace-wide view across every project in the framework, including workspace-scoped rules.
      *
      * @throws OpenlayerInvalidDataException if the JSON field has an unexpected type (e.g. if the
      *   server responded with an unexpected value).
@@ -112,7 +94,11 @@ private constructor(
          */
         fun body(body: Body) = apply { this.body = body.toBuilder() }
 
-        /** Scope the export to this project. It must belong to the framework. */
+        /**
+         * Scope the export to this project. It must belong to the framework. Omit it for the
+         * workspace-wide view across every project in the framework, including workspace-scoped
+         * rules.
+         */
         fun projectId(projectId: String?) = apply { body.projectId(projectId) }
 
         /** Alias for calling [Builder.projectId] with `projectId.orElse(null)`. */
@@ -285,7 +271,9 @@ private constructor(
         ) : this(projectId, mutableMapOf())
 
         /**
-         * Scope the export to this project. It must belong to the framework.
+         * Scope the export to this project. It must belong to the framework. Omit it for the
+         * workspace-wide view across every project in the framework, including workspace-scoped
+         * rules.
          *
          * @throws OpenlayerInvalidDataException if the JSON field has an unexpected type (e.g. if
          *   the server responded with an unexpected value).
@@ -329,7 +317,11 @@ private constructor(
                 additionalProperties = body.additionalProperties.toMutableMap()
             }
 
-            /** Scope the export to this project. It must belong to the framework. */
+            /**
+             * Scope the export to this project. It must belong to the framework. Omit it for the
+             * workspace-wide view across every project in the framework, including workspace-scoped
+             * rules.
+             */
             fun projectId(projectId: String?) = projectId(JsonField.ofNullable(projectId))
 
             /** Alias for calling [Builder.projectId] with `projectId.orElse(null)`. */

openlayer-java-core/src/main/kotlin/com/openlayer/api/models/governance/frameworks/FrameworkListParams.kt

@@ -14,13 +14,7 @@ import java.util.Objects
 import java.util.Optional
 import kotlin.jvm.optionals.getOrNull
 
-/**
- * List the governance frameworks in a workspace.
- *
- * A framework is a set of rules -- drawn from a regulation, a standard, or your own internal policy
- * -- that Openlayer tracks compliance against. Use this endpoint to find the framework you want to
- * report on, then read its rules and rule results.
- */
+/** List the frameworks in a workspace. */
 class FrameworkListParams
 private constructor(
     private val workspaceId: String?,

openlayer-java-core/src/main/kotlin/com/openlayer/api/models/governance/frameworks/FrameworkListProjectRuleStatsParams.kt

@@ -13,12 +13,7 @@ import java.util.Objects
 import java.util.Optional
 import kotlin.jvm.optionals.getOrNull
 
-/**
- * Get a compliance roll-up for a framework, one row per project it applies to.
- *
- * Each row counts the project's rule results by status, so you can report on where a framework is
- * complete and where it is not without fetching every individual rule result.
- */
+/** List a framework's compliance stats per project. */
 class FrameworkListProjectRuleStatsParams
 private constructor(
     private val frameworkId: String?,

openlayer-java-core/src/main/kotlin/com/openlayer/api/models/governance/frameworks/FrameworkListProjectRuleStatsResponse.kt

@@ -182,6 +182,7 @@ private constructor(
     internal fun validity(): Int =
         (items.asKnown().getOrNull()?.sumOf { it.validity().toInt() } ?: 0)
 
+    /** One project's rule result counts by status, for a single framework. */
     class Item
     @JsonCreator(mode = JsonCreator.Mode.DISABLED)
     private constructor(

openlayer-java-core/src/main/kotlin/com/openlayer/api/models/governance/frameworks/FrameworkListProjectsParams.kt

@@ -9,12 +9,7 @@ import java.util.Objects
 import java.util.Optional
 import kotlin.jvm.optionals.getOrNull
 
-/**
- * List the projects a framework applies to.
- *
- * Which projects a framework covers is determined by its `projectSelector`. A framework with an
- * empty selector applies to every project in the workspace.
- */
+/** List the projects a framework applies to. */
 class FrameworkListProjectsParams
 private constructor(
     private val frameworkId: String?,

openlayer-java-core/src/main/kotlin/com/openlayer/api/models/governance/frameworks/FrameworkListResponse.kt

@@ -180,6 +180,11 @@ private constructor(
     internal fun validity(): Int =
         (items.asKnown().getOrNull()?.sumOf { it.validity().toInt() } ?: 0)
 
+    /**
+     * A set of rules, drawn from a regulation, a standard, or your own internal policy, that
+     * Openlayer tracks compliance against. Openlayer ships built-in frameworks, and you can create
+     * your own.
+     */
     class Item
     @JsonCreator(mode = JsonCreator.Mode.DISABLED)
     private constructor(
@@ -368,7 +373,8 @@ private constructor(
         fun href(): Optional<String> = href.getOptional("href")
 
         /**
-         * Whether the framework definition is managed by Openlayer and cannot be edited.
+         * Whether the framework definition is managed by Openlayer. For these frameworks only
+         * `enabled`, `tags`, and `projectSelector` can be changed.
          *
          * @throws OpenlayerInvalidDataException if the JSON field has an unexpected type (e.g. if
          *   the server responded with an unexpected value).
@@ -806,7 +812,10 @@ private constructor(
              */
             fun href(href: JsonField<String>) = apply { this.href = href }
 
-            /** Whether the framework definition is managed by Openlayer and cannot be edited. */
+            /**
+             * Whether the framework definition is managed by Openlayer. For these frameworks only
+             * `enabled`, `tags`, and `projectSelector` can be changed.
+             */
             fun immutable(immutable: Boolean) = immutable(JsonField.of(immutable))
 
             /**

openlayer-java-core/src/main/kotlin/com/openlayer/api/models/governance/frameworks/FrameworkListRulesParams.kt

@@ -9,13 +9,7 @@ import java.util.Objects
 import java.util.Optional
 import kotlin.jvm.optionals.getOrNull
 
-/**
- * List the rules that belong to a framework.
- *
- * To read the compliance status of these rules, use
- * [List rule results](/api-reference/rest/governance/list-rule-results) with the `frameworkId`
- * filter, or fetch the results of an individual rule.
- */
+/** List the rules in a framework. */
 class FrameworkListRulesParams
 private constructor(
     private val frameworkId: String?,