@fabricorg/databricks-testkit 0.2.4 → 0.3.0

package/dist/index.js

@@ -196,7 +196,8 @@ async function runLiveSuite(spec, runtime = {}) {
     finishedAt: (/* @__PURE__ */ new Date()).toISOString(),
     success,
     required: required2,
-    results
+    results,
+    ...spec.targetPack ? { targetPack: spec.targetPack } : {}
   };
   if (spec.evidencePath)
     await writeReport(spec.evidencePath, `${JSON.stringify(evidence, null, 2)}
@@ -1072,6 +1073,529 @@ function classicComputeCheck() {
   };
 }
 
-export { appHealthCheck, assertDeltaContract, autoLoaderIngestionCheck, backupRestoreCheck, classicComputeCheck, createEphemeralLakebaseBranch, createExecutionContext, createLakebaseTestProvider, createMockDatabricksClient, customLiveCheck, dbtBuildCheck, defineLiveSuite, deleteEphemeralLakebaseBranch, deleteVolumeFile, deltaContractCheck, ensureVolumeDirectory, expectQueryToMatchGolden, expectTable, failureRecoveryCheck, jobRunCheck, lakebaseCredentialCheck, lakebaseRoundTripCheck, normalizeVolumeRoot, notebookSubmitCheck, performanceBudgetCheck, pipelineRefreshCheck, renderJUnit, resolveLakebaseProject, resolveProfile, restrictedPrincipalCheck, rollbackCheck, runLiveSuite, secretRotationCheck, secretScopeCheck, serverlessComputeCheck, sqlRoundTripCheck, toLakebaseBranchId, unityCatalogAccessCheck, uploadVolumeFile, volumeIOCheck, waitForPipelineUpdate };
+// src/target-packs.ts
+var TARGET_PACK_ID = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+function defineTargetPack(spec) {
+  if (!TARGET_PACK_ID.test(spec.id)) {
+    throw new Error(`Target pack id '${spec.id}' must be lowercase kebab-case`);
+  }
+  if (!spec.name.trim()) throw new Error(`Target pack '${spec.id}' requires a name`);
+  if (!/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(spec.version)) {
+    throw new Error(
+      `Target pack '${spec.id}' version '${spec.version}' is not semantic versioning`
+    );
+  }
+  if (spec.capabilities.length === 0) {
+    throw new Error(`Target pack '${spec.id}' must declare at least one capability`);
+  }
+  const createChecks = typeof spec.checks === "function" ? spec.checks : () => spec.checks;
+  const validateChecks = () => {
+    const checks = [...createChecks()];
+    const ids = /* @__PURE__ */ new Set();
+    for (const check of checks) {
+      if (!check.id.trim())
+        throw new Error(`Target pack '${spec.id}' contains a check without an id`);
+      if (ids.has(check.id)) {
+        throw new Error(`Target pack '${spec.id}' contains duplicate check '${check.id}'`);
+      }
+      ids.add(check.id);
+    }
+    for (const required2 of spec.requiredChecks ?? []) {
+      if (!ids.has(required2)) {
+        throw new Error(`Target pack '${spec.id}' requires unknown check '${required2}'`);
+      }
+    }
+    return checks;
+  };
+  validateChecks();
+  return Object.freeze({
+    ...spec,
+    capabilities: Object.freeze([...spec.capabilities]),
+    requiredChecks: Object.freeze([...spec.requiredChecks ?? []]),
+    requirements: Object.freeze([...spec.requirements ?? []]),
+    certificationScopes: Object.freeze([...spec.certificationScopes ?? []]),
+    checks: validateChecks
+  });
+}
+function createTargetPackRegistry(packs) {
+  const registry = /* @__PURE__ */ new Map();
+  for (const pack of packs) {
+    if (registry.has(pack.id)) throw new Error(`Duplicate target pack '${pack.id}'`);
+    registry.set(pack.id, pack);
+  }
+  return registry;
+}
+function doctorTargetPack(pack, env = process.env, requiredChecks = pack.requiredChecks ?? []) {
+  const requirements = (pack.requirements ?? []).map((requirement) => ({
+    id: requirement.id,
+    description: requirement.description,
+    satisfied: requirement.anyOf.some((name) => Boolean(env[name]?.trim())),
+    required: requirement.required !== false,
+    variables: [...requirement.anyOf]
+  }));
+  const required2 = new Set(requiredChecks);
+  const checks = pack.checks().map((check) => ({
+    id: check.id,
+    description: check.description,
+    configured: check.configured ? check.configured(env) : true,
+    required: required2.has(check.id)
+  }));
+  const known = new Set(checks.map((check) => check.id));
+  const missingRequirements = requirements.filter((requirement) => requirement.required && !requirement.satisfied).map((requirement) => requirement.id);
+  const missingRequiredChecks = [
+    ...checks.filter((check) => check.required && !check.configured).map((check) => check.id),
+    ...[...required2].filter((id) => !known.has(id))
+  ];
+  return {
+    pack: {
+      id: pack.id,
+      name: pack.name,
+      version: pack.version,
+      maturity: pack.maturity
+    },
+    ready: missingRequirements.length === 0 && missingRequiredChecks.length === 0,
+    requirements,
+    checks,
+    missingRequirements,
+    missingRequiredChecks
+  };
+}
+function defineTargetPackRun(pack, options = {}) {
+  const env = options.env ?? process.env;
+  const requiredChecks = [...options.requiredChecks ?? pack.requiredChecks ?? []];
+  const doctor = doctorTargetPack(pack, env, requiredChecks);
+  if (!doctor.ready) {
+    const missing = [...doctor.missingRequirements, ...doctor.missingRequiredChecks].join(", ");
+    throw new Error(`Target pack '${pack.id}' is not configured: ${missing}`);
+  }
+  const targetPack = evidenceMetadata(pack, env);
+  const suite = defineLiveSuite({
+    checks: pack.checks(),
+    required: requiredChecks,
+    env,
+    evidencePath: options.evidencePath,
+    junitPath: options.junitPath,
+    targetPack
+  });
+  return { pack, run: (runtime) => suite.run(runtime) };
+}
+async function runTargetPack(pack, options = {}, runtime) {
+  return defineTargetPackRun(pack, options).run(runtime);
+}
+function evidenceMetadata(pack, env) {
+  return {
+    id: pack.id,
+    name: pack.name,
+    version: pack.version,
+    maturity: pack.maturity,
+    capabilities: [...pack.capabilities],
+    ...pack.docsUrl ? { docsUrl: pack.docsUrl } : {},
+    certificationScopes: [...pack.certificationScopes ?? []],
+    target: compact({
+      cloud: env.DBX_TEST_CLOUD,
+      region: env.DBX_TEST_REGION,
+      workspace: env.DATABRICKS_HOST,
+      runtime: env.DBX_TEST_RUNTIME_VERSION,
+      compute: env.DBX_TEST_COMPUTE
+    })
+  };
+}
+function compact(value) {
+  return Object.fromEntries(
+    Object.entries(value).filter((entry) => Boolean(entry[1]))
+  );
+}
+
+// src/foundation-packs.ts
+var DOCS = "https://experiments.fabric.pro/docs/testing/target-packs/";
+var AZURE_SCOPE = "Azure Databricks live-gated; see certification evidence for exact runtime";
+var workspaceRequirement = {
+  id: "workspace",
+  description: "Databricks workspace host",
+  anyOf: ["DATABRICKS_HOST"]
+};
+var authRequirement = {
+  id: "authentication",
+  description: "Databricks OAuth, OIDC, bearer, or PAT authentication",
+  anyOf: [
+    "DATABRICKS_BEARER",
+    "DATABRICKS_TOKEN",
+    "DATABRICKS_CLIENT_ID",
+    "DATABRICKS_OIDC_TOKEN",
+    "DATABRICKS_OIDC_TOKEN_FILEPATH"
+  ],
+  secret: true
+};
+var warehouseRequirement = {
+  id: "warehouse",
+  description: "SQL warehouse ID or HTTP path",
+  anyOf: ["DATABRICKS_WAREHOUSE_ID", "DATABRICKS_HTTP_PATH"]
+};
+function createSqlDeltaFoundationPack() {
+  return defineTargetPack({
+    id: "sql-delta",
+    name: "SQL and Delta foundation",
+    description: "SQL Statement Execution, Delta contracts, performance, recovery, backup and rollback.",
+    version: "1.0.0",
+    maturity: "live-gated",
+    capabilities: [
+      "sql.statement-execution",
+      "delta.contract",
+      "delta.time-travel",
+      "performance.sql",
+      "recovery.sql",
+      "backup-restore.delta",
+      "rollback.delta"
+    ],
+    checks: () => [
+      restrictedPrincipalCheck(),
+      sqlRoundTripCheck(),
+      deltaContractCheck(),
+      serverlessComputeCheck(),
+      performanceBudgetCheck(),
+      failureRecoveryCheck(),
+      backupRestoreCheck(),
+      rollbackCheck()
+    ],
+    requiredChecks: ["sql"],
+    requirements: [workspaceRequirement, authRequirement, warehouseRequirement],
+    docsUrl: `${DOCS}#existing-foundation-to-migrate-into-packs`,
+    certificationScopes: [AZURE_SCOPE]
+  });
+}
+function createLakeflowFoundationPack() {
+  return defineTargetPack({
+    id: "lakeflow-ingestion",
+    name: "Lakeflow ingestion foundation",
+    description: "Lakeflow refresh, Volumes, Auto Loader ingestion and rescued-row evidence.",
+    version: "1.0.0",
+    maturity: "live-gated",
+    capabilities: [
+      "lakeflow.refresh",
+      "autoloader.ingestion",
+      "volumes.files",
+      "delta.rescued-data"
+    ],
+    checks: () => [
+      restrictedPrincipalCheck(),
+      pipelineRefreshCheck(),
+      volumeIOCheck(),
+      autoLoaderIngestionCheck()
+    ],
+    requiredChecks: ["pipeline"],
+    requirements: [workspaceRequirement, authRequirement],
+    docsUrl: `${DOCS}#existing-foundation-to-migrate-into-packs`,
+    certificationScopes: [AZURE_SCOPE]
+  });
+}
+function createJobsCodeFoundationPack() {
+  return defineTargetPack({
+    id: "jobs-code",
+    name: "Jobs and code foundation",
+    description: "Jobs, notebooks, dbt, serverless compute and classic compute probes.",
+    version: "1.0.0",
+    maturity: "live-gated",
+    capabilities: [
+      "jobs.run-now",
+      "jobs.submit.notebook",
+      "jobs.submit.dbt",
+      "compute.serverless",
+      "compute.classic"
+    ],
+    checks: () => [
+      restrictedPrincipalCheck(),
+      jobRunCheck(),
+      notebookSubmitCheck(),
+      dbtBuildCheck(),
+      serverlessComputeCheck(),
+      classicComputeCheck()
+    ],
+    requiredChecks: ["jobs"],
+    requirements: [workspaceRequirement, authRequirement],
+    docsUrl: `${DOCS}#existing-foundation-to-migrate-into-packs`,
+    certificationScopes: [AZURE_SCOPE]
+  });
+}
+function createUnityStorageFoundationPack() {
+  return defineTargetPack({
+    id: "unity-storage",
+    name: "Unity Catalog and storage foundation",
+    description: "Unity Catalog allow/deny, Volumes, secret metadata and secret rotation.",
+    version: "1.0.0",
+    maturity: "live-gated",
+    capabilities: [
+      "unity-catalog.permissions",
+      "volumes.files",
+      "secrets.metadata",
+      "secrets.rotation"
+    ],
+    checks: () => [
+      restrictedPrincipalCheck(),
+      unityCatalogAccessCheck(),
+      volumeIOCheck(),
+      secretScopeCheck(),
+      secretRotationCheck()
+    ],
+    requiredChecks: ["uc-grants"],
+    requirements: [workspaceRequirement, authRequirement, warehouseRequirement],
+    docsUrl: `${DOCS}#existing-foundation-to-migrate-into-packs`,
+    certificationScopes: [AZURE_SCOPE]
+  });
+}
+function createAppsOperationalFoundationPack() {
+  return defineTargetPack({
+    id: "apps-operational",
+    name: "Apps and operational data foundation",
+    description: "Databricks Apps resources and health plus Lakebase OAuth and pool refresh.",
+    version: "1.0.0",
+    maturity: "live-gated",
+    capabilities: [
+      "apps.health",
+      "apps.resources",
+      "lakebase.credentials",
+      "lakebase.round-trip",
+      "lakebase.pool-refresh"
+    ],
+    checks: () => [
+      restrictedPrincipalCheck(),
+      appHealthCheck(),
+      lakebaseCredentialCheck(),
+      lakebaseRoundTripCheck()
+    ],
+    requiredChecks: ["app"],
+    requirements: [workspaceRequirement, authRequirement],
+    docsUrl: `${DOCS}#existing-foundation-to-migrate-into-packs`,
+    certificationScopes: [AZURE_SCOPE]
+  });
+}
+function createFoundationTargetPacks() {
+  return [
+    createSqlDeltaFoundationPack(),
+    createLakeflowFoundationPack(),
+    createJobsCodeFoundationPack(),
+    createUnityStorageFoundationPack(),
+    createAppsOperationalFoundationPack()
+  ];
+}
+var foundationTargetPacks = createFoundationTargetPacks();
+var DatabricksJobsAdapter = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  async submit(request) {
+    validateJobGraph(request.tasks);
+    const response = await this.client.post(
+      "/api/2.1/jobs/runs/submit",
+      request
+    );
+    if (!response.run_id) throw new Error("Databricks Jobs submit returned no run_id");
+    return response.run_id;
+  }
+  async get(runId) {
+    const raw = await this.client.get("/api/2.1/jobs/runs/get", {
+      run_id: runId,
+      include_history: true
+    });
+    return normalizeJobRun(runId, raw);
+  }
+  async wait(runId, options = {}) {
+    const raw = await waitForDatabricksRun(this.client, runId, {
+      timeoutMs: options.timeoutMs,
+      pollIntervalMs: options.pollIntervalMs
+    });
+    return normalizeJobRun(runId, raw);
+  }
+  async cancel(runId) {
+    await this.client.post("/api/2.1/jobs/runs/cancel", { run_id: runId });
+  }
+  async repair(runId, options = {}) {
+    const response = await this.client.post("/api/2.1/jobs/runs/repair", {
+      run_id: runId,
+      ...options.latestRepairId ? { latest_repair_id: options.latestRepairId } : {},
+      ...options.rerunTasks?.length ? { rerun_tasks: options.rerunTasks } : { rerun_all_failed_tasks: true }
+    });
+    if (!response.repair_id) throw new Error("Databricks Jobs repair returned no repair_id");
+    return response.repair_id;
+  }
+};
+function validateJobGraph(tasks) {
+  if (tasks.length === 0) throw new Error("Jobs orchestration requires at least one task");
+  const keys = /* @__PURE__ */ new Set();
+  for (const task of tasks) {
+    if (!/^[A-Za-z0-9_-]{1,100}$/.test(task.task_key)) {
+      throw new Error(`Invalid task key '${task.task_key}'`);
+    }
+    if (keys.has(task.task_key)) throw new Error(`Duplicate task key '${task.task_key}'`);
+    keys.add(task.task_key);
+  }
+  const edges = /* @__PURE__ */ new Map();
+  for (const task of tasks) {
+    const dependencies = (task.depends_on ?? []).map((dependency) => dependency.task_key);
+    for (const dependency of dependencies) {
+      if (!keys.has(dependency)) {
+        throw new Error(`Task '${task.task_key}' depends on unknown task '${dependency}'`);
+      }
+      if (dependency === task.task_key) {
+        throw new Error(`Task '${task.task_key}' cannot depend on itself`);
+      }
+    }
+    edges.set(task.task_key, dependencies);
+  }
+  const visiting = /* @__PURE__ */ new Set();
+  const visited = /* @__PURE__ */ new Set();
+  const visit = (key) => {
+    if (visiting.has(key)) throw new Error(`Jobs task graph contains a cycle at '${key}'`);
+    if (visited.has(key)) return;
+    visiting.add(key);
+    for (const dependency of edges.get(key) ?? []) visit(dependency);
+    visiting.delete(key);
+    visited.add(key);
+  };
+  for (const key of keys) visit(key);
+}
+function jobsOrchestrationCheck() {
+  return {
+    id: "jobs-orchestration",
+    description: "Lakeflow Jobs multi-task orchestration reaches expected task outcomes",
+    configured: (env) => Boolean(env.DBX_TEST_JOBS_ORCHESTRATION_JSON),
+    async run({ env, client }) {
+      const configured = env.DBX_TEST_JOBS_ORCHESTRATION_JSON;
+      if (!configured) throw new Error("DBX_TEST_JOBS_ORCHESTRATION_JSON is required");
+      const spec = parseJobOrchestrationLiveSpec(configured);
+      const adapter = new DatabricksJobsAdapter(client);
+      const runId = await adapter.submit(spec.request);
+      let run = await adapter.wait(runId, {
+        timeoutMs: Number(env.DBX_TEST_TIMEOUT_MS ?? 9e5),
+        pollIntervalMs: Number(env.DBX_TEST_POLL_INTERVAL_MS ?? 1e4)
+      });
+      if (spec.repairFailedTasks && run.resultState !== "SUCCESS") {
+        const failed = run.tasks.filter((task) => task.resultState === "FAILED").map((task) => task.taskKey);
+        await adapter.repair(runId, { rerunTasks: failed.length > 0 ? failed : void 0 });
+        run = await adapter.wait(runId, {
+          timeoutMs: Number(env.DBX_TEST_TIMEOUT_MS ?? 9e5),
+          pollIntervalMs: Number(env.DBX_TEST_POLL_INTERVAL_MS ?? 1e4)
+        });
+      }
+      const expectedResult = spec.expectedResult ?? "SUCCESS";
+      if (run.resultState !== expectedResult) {
+        throw new Error(
+          `Job orchestration run ${runId} ended in ${run.resultState}, expected ${expectedResult}`
+        );
+      }
+      for (const [taskKey, expected] of Object.entries(spec.expectedTasks ?? {})) {
+        const task = run.tasks.find((candidate) => candidate.taskKey === taskKey);
+        if (!task) throw new Error(`Job orchestration result did not include task '${taskKey}'`);
+        if (task.resultState !== expected) {
+          throw new Error(`Task '${taskKey}' ended in ${task.resultState}, expected ${expected}`);
+        }
+      }
+      return {
+        runId,
+        resultState: run.resultState,
+        tasks: run.tasks
+      };
+    }
+  };
+}
+function parseJobOrchestrationLiveSpec(value) {
+  let parsed;
+  try {
+    parsed = JSON.parse(value);
+  } catch (error) {
+    throw new Error(`DBX_TEST_JOBS_ORCHESTRATION_JSON is invalid JSON: ${String(error)}`);
+  }
+  if (!parsed || typeof parsed !== "object") {
+    throw new Error("Jobs orchestration spec must be an object");
+  }
+  const spec = parsed;
+  if (!spec.request || typeof spec.request !== "object" || !Array.isArray(spec.request.tasks)) {
+    throw new Error("Jobs orchestration spec requires request.tasks");
+  }
+  validateJobGraph(spec.request.tasks);
+  return spec;
+}
+function normalizeJobRun(fallbackRunId, raw) {
+  const state = objectOf(raw.state);
+  const tasks = Array.isArray(raw.tasks) ? raw.tasks.filter(
+    (task) => Boolean(task && typeof task === "object")
+  ).map((task) => {
+    const taskState = objectOf(task.state);
+    return {
+      taskKey: String(task.task_key ?? "unknown"),
+      ...Number.isFinite(Number(task.run_id)) ? { runId: Number(task.run_id) } : {},
+      lifeCycleState: String(taskState.life_cycle_state ?? "UNKNOWN"),
+      resultState: String(taskState.result_state ?? "UNKNOWN"),
+      ...typeof taskState.state_message === "string" ? { stateMessage: taskState.state_message } : {}
+    };
+  }) : [];
+  return {
+    runId: Number(raw.run_id ?? fallbackRunId),
+    lifeCycleState: String(state.life_cycle_state ?? "UNKNOWN"),
+    resultState: String(state.result_state ?? "UNKNOWN"),
+    tasks,
+    raw
+  };
+}
+function objectOf(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+
+// src/jobs-target-pack.ts
+function createLakeflowJobsTargetPack() {
+  return defineTargetPack({
+    id: "lakeflow-jobs",
+    name: "Lakeflow Jobs orchestration",
+    description: "Typed multi-task DAG, branch/loop, retry, cancellation, repair and task-outcome validation.",
+    version: "0.1.0",
+    maturity: "shipped",
+    capabilities: [
+      "jobs.multi-task-dag",
+      "jobs.dependencies",
+      "jobs.condition-task",
+      "jobs.for-each-task",
+      "jobs.retry",
+      "jobs.cancel",
+      "jobs.repair",
+      "jobs.task-outcomes"
+    ],
+    checks: () => [restrictedPrincipalCheck(), jobRunCheck(), jobsOrchestrationCheck()],
+    requiredChecks: ["jobs-orchestration"],
+    requirements: [
+      {
+        id: "workspace",
+        description: "Databricks workspace host",
+        anyOf: ["DATABRICKS_HOST"]
+      },
+      {
+        id: "authentication",
+        description: "Databricks OAuth, OIDC, bearer, or PAT authentication",
+        anyOf: [
+          "DATABRICKS_BEARER",
+          "DATABRICKS_TOKEN",
+          "DATABRICKS_CLIENT_ID",
+          "DATABRICKS_OIDC_TOKEN",
+          "DATABRICKS_OIDC_TOKEN_FILEPATH"
+        ],
+        secret: true
+      },
+      {
+        id: "orchestration-spec",
+        description: "JSON multi-task orchestration scenario",
+        anyOf: ["DBX_TEST_JOBS_ORCHESTRATION_JSON"]
+      }
+    ],
+    docsUrl: "https://experiments.fabric.pro/docs/testing/target-packs/#pack-1--lakeflow-jobs-orchestration",
+    certificationScopes: []
+  });
+}
+
+// src/builtin-packs.ts
+function createBuiltinTargetPacks() {
+  return [...createFoundationTargetPacks(), createLakeflowJobsTargetPack()];
+}
+var builtinTargetPacks = createBuiltinTargetPacks();
+
+export { DatabricksJobsAdapter, appHealthCheck, assertDeltaContract, autoLoaderIngestionCheck, backupRestoreCheck, builtinTargetPacks, classicComputeCheck, createAppsOperationalFoundationPack, createBuiltinTargetPacks, createEphemeralLakebaseBranch, createExecutionContext, createFoundationTargetPacks, createJobsCodeFoundationPack, createLakebaseTestProvider, createLakeflowFoundationPack, createLakeflowJobsTargetPack, createMockDatabricksClient, createSqlDeltaFoundationPack, createTargetPackRegistry, createUnityStorageFoundationPack, customLiveCheck, dbtBuildCheck, defineLiveSuite, defineTargetPack, defineTargetPackRun, deleteEphemeralLakebaseBranch, deleteVolumeFile, deltaContractCheck, doctorTargetPack, ensureVolumeDirectory, expectQueryToMatchGolden, expectTable, failureRecoveryCheck, foundationTargetPacks, jobRunCheck, jobsOrchestrationCheck, lakebaseCredentialCheck, lakebaseRoundTripCheck, normalizeJobRun, normalizeVolumeRoot, notebookSubmitCheck, parseJobOrchestrationLiveSpec, performanceBudgetCheck, pipelineRefreshCheck, renderJUnit, resolveLakebaseProject, resolveProfile, restrictedPrincipalCheck, rollbackCheck, runLiveSuite, runTargetPack, secretRotationCheck, secretScopeCheck, serverlessComputeCheck, sqlRoundTripCheck, toLakebaseBranchId, unityCatalogAccessCheck, uploadVolumeFile, validateJobGraph, volumeIOCheck, waitForPipelineUpdate };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map