@driftdev/cli 1.13.0 → 1.14.0

package/README.md

@@ -158,7 +158,7 @@ Validate @example blocks.
 ```bash
 drift examples                # presence check
 drift examples --typecheck    # type-check examples
-drift examples --run          # execute examples
+drift examples --run          # execute examples with // => assertions
 drift examples --min 50       # fail if example coverage below 50%
 ```
 

package/dist/drift.js

@@ -737,6 +737,16 @@ function validateConfig(raw) {
       }
     }
   }
+  if (obj.examples !== undefined) {
+    if (typeof obj.examples !== "object" || obj.examples === null) {
+      errors.push('"examples" must be an object');
+    } else {
+      const examples = obj.examples;
+      if (examples.run !== undefined && typeof examples.run !== "boolean") {
+        errors.push('"examples.run" must be a boolean');
+      }
+    }
+  }
   if (errors.length > 0)
     return { ok: false, errors };
   const { $schema: _schema, ...rest } = obj;
@@ -3053,14 +3063,15 @@ function renderExamples(data) {
     lines.push("");
   }
   if (data.run) {
-    const { passed, failed, drifts, installSuccess, installError } = data.run;
+    const { passed, failed, skipped, drifts, installSuccess, installError } = data.run;
     if (!installSuccess) {
-      lines.push(indent(`${c.gray("RUNTIME")}  ${c.red("install failed")}`));
+      lines.push(indent(`${c.gray("RUNTIME")}  ${c.red("failed")}`));
       if (installError) {
         lines.push(indent(`  ${c.red(installError)}`));
       }
     } else {
-      const status = failed === 0 ? c.green(`${passed} passed`) : `${c.green(`${passed} passed`)}  ${c.red(`${failed} failed`)}`;
+      const skipBit = skipped > 0 ? `  ${c.gray(`${skipped} skipped`)}` : "";
+      const status = failed === 0 ? `${c.green(`${passed} passed`)}${skipBit}` : `${c.green(`${passed} passed`)}  ${c.red(`${failed} failed`)}${skipBit}`;
       lines.push(indent(`${c.gray("RUNTIME")}  ${status}`));
       if (drifts.length > 0) {
         const shown = drifts.slice(0, 10);
@@ -3079,7 +3090,7 @@ function renderExamples(data) {
   if (!ran.includes("typecheck") && !ran.includes("run")) {
     lines.push(indent(c.gray("Tip: drift examples --typecheck to compile-check examples")));
   } else if (!ran.includes("run")) {
-    lines.push(indent(c.gray("Tip: drift examples --run to execute examples at runtime")));
+    lines.push(indent(c.gray("Tip: drift examples --run to execute examples with // => assertions")));
   }
   lines.push("");
   return lines.join(`
@@ -3100,7 +3111,7 @@ function findPackagePath(entryFile) {
   return path22.dirname(entryFile);
 }
 function registerExamplesCommand(program) {
-  program.command("examples [entry]").description("Validate @example blocks on exports").option("--typecheck", "Type-check examples with TypeScript").option("--run", "Execute examples at runtime (implies --typecheck)").option("--all", "Run across all workspace packages").option("--private", "Include private packages in --all mode").option("--min <n>", "Minimum presence threshold (exit 1 if below)").action(async (entry, options) => {
+  program.command("examples [entry]").description("Validate @example blocks on exports").option("--typecheck", "Type-check examples with TypeScript").option("--run", "Execute examples that contain // => assertions (implies --typecheck; installs the package)").option("--yes", "Confirm execution (required when not a TTY)").option("--untrusted", "Treat the target as a third-party package (OS isolation; macOS only)").option("--all", "Run across all workspace packages").option("--private", "Include private packages in --all mode").option("--min <n>", "Minimum presence threshold (exit 1 if below)").action(async (entry, options) => {
     const startTime = Date.now();
     const version = getVersion();
     try {
@@ -3109,9 +3120,13 @@ function registerExamplesCommand(program) {
         validations.push("typecheck");
       if (options.run)
         validations.push("run");
+      const { config } = loadConfig();
       if (options.run) {
-        process.stderr.write(`⚠ --run executes code from @example blocks. Only use on trusted code.
-`);
+        const confirmed = Boolean(options.yes) || config.examples?.run === true || Boolean(process.stdin.isTTY);
+        if (!confirmed) {
+          formatError("examples", "--run requires --yes or examples.run: true in config when not running interactively", startTime, version);
+          return;
+        }
       }
       if (options.all) {
         const allPackages = discoverPackages(process.cwd());
@@ -3137,7 +3152,8 @@ function registerExamplesCommand(program) {
           const result2 = await validateExamples(exps, {
             validations,
             packagePath: packagePath2,
-            exportNames: exportNames2
+            exportNames: exportNames2,
+            untrusted: options.untrusted
           });
           const withEx = result2.presence?.withExamples ?? 0;
           const total = result2.presence?.total ?? exps.length;
@@ -3147,8 +3163,9 @@ function registerExamplesCommand(program) {
           totalAll += total;
           if (result2.typecheck && result2.typecheck.failed > 0)
             hasFailures = true;
-          if (result2.run && result2.run.failed > 0)
+          if (result2.run && (result2.run.failed > 0 || !result2.run.installSuccess)) {
             hasFailures = true;
+          }
         }
         const aggScore = totalAll > 0 ? Math.round(totalWith / totalAll * 100) : 100;
         const data = {
@@ -3164,7 +3181,6 @@ function registerExamplesCommand(program) {
           process.exitCode = 1;
         return;
       }
-      const { config } = loadConfig();
       const entryFile = entry ? path22.resolve(process.cwd(), entry) : config.entry ? path22.resolve(process.cwd(), config.entry) : detectEntry();
       const { spec } = await cachedExtract(entryFile);
       const exports = spec.exports ?? [];
@@ -3173,7 +3189,8 @@ function registerExamplesCommand(program) {
       const result = await validateExamples(exports, {
         validations,
         packagePath,
-        exportNames
+        exportNames,
+        untrusted: options.untrusted
       });
       const missingCount = result.presence?.missing?.length ?? 0;
       const failedCount = (result.typecheck?.failed ?? 0) + (result.run?.failed ?? 0);
@@ -3191,8 +3208,9 @@ function registerExamplesCommand(program) {
       }
       if (result.typecheck && result.typecheck.failed > 0)
         process.exitCode = 1;
-      if (result.run && result.run.failed > 0)
+      if (result.run && (result.run.failed > 0 || !result.run.installSuccess)) {
         process.exitCode = 1;
+      }
     } catch (err) {
       formatError("examples", err instanceof Error ? err.message : String(err), startTime, version);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@driftdev/cli",
-  "version": "1.13.0",
+  "version": "1.14.0",
   "description": "Drift CLI - detect when your docs drift from your code",
   "keywords": [
     "typescript",
@@ -47,7 +47,7 @@
   "dependencies": {
     "@driftdev/clarity-adapter": "^1.0.1",
     "@driftdev/openapi-adapter": "^1.0.1",
-    "@driftdev/sdk": "^1.13.0",
+    "@driftdev/sdk": "^1.14.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@openpkg-ts/sdk": "^0.51.0",
     "@openpkg-ts/spec": "^0.50.0",

package/schemas/drift.config.schema.json

@@ -79,6 +79,17 @@
         }
       },
       "additionalProperties": false
+    },
+    "examples": {
+      "type": "object",
+      "description": "Example execution policy",
+      "properties": {
+        "run": {
+          "type": "boolean",
+          "description": "Allow --run in non-TTY (CI) without --yes"
+        }
+      },
+      "additionalProperties": false
     }
   },
   "additionalProperties": true