@openpkg-ts/cli 0.4.2 → 0.5.1

package/dist/bin/openpkg.js

@@ -11,7 +11,7 @@ import { Command as Command10 } from "commander";
 // package.json
 var package_default = {
   name: "@openpkg-ts/cli",
-  version: "0.4.2",
+  version: "0.5.1",
   description: "CLI for OpenPkg TypeScript API extraction and documentation generation",
   homepage: "https://github.com/ryanwaits/openpkg-ts#readme",
   repository: {
@@ -34,8 +34,8 @@ var package_default = {
     test: "bun test"
   },
   dependencies: {
-    "@openpkg-ts/adapters": "^0.3.1",
-    "@openpkg-ts/sdk": "^0.32.1",
+    "@openpkg-ts/adapters": "^0.3.2",
+    "@openpkg-ts/sdk": "^0.33.1",
     commander: "^14.0.0"
   },
   devDependencies: {
@@ -264,18 +264,45 @@ function loadJSON(filePath) {
   return JSON.parse(content);
 }
 function createDiagnosticsCommand() {
-  return new Command4("diagnostics").description("Analyze spec for quality issues (missing docs, deprecated without reason)").argument("<spec>", "Path to spec file (JSON)").action(async (specPath) => {
+  return new Command4("diagnostics").description("Analyze spec for quality issues (missing docs, deprecated without reason)").argument("<spec>", "Path to spec file (JSON)").option("--verbose", "Show detailed information including skipped export details").action(async (specPath, options) => {
     try {
       const spec = loadJSON(specPath);
       const diagnostics = analyzeSpec(spec);
+      const generation = spec.generation;
+      const skipped = generation?.skipped ?? [];
+      const externalExports = spec.exports.filter((e) => e.kind === "external");
+      const byReason = {};
+      for (const skip of skipped) {
+        byReason[skip.reason] = (byReason[skip.reason] ?? 0) + 1;
+      }
       const result = {
         summary: {
           total: diagnostics.missingDescriptions.length + diagnostics.deprecatedNoReason.length + diagnostics.missingParamDocs.length,
           missingDescriptions: diagnostics.missingDescriptions.length,
           deprecatedNoReason: diagnostics.deprecatedNoReason.length,
-          missingParamDocs: diagnostics.missingParamDocs.length
+          missingParamDocs: diagnostics.missingParamDocs.length,
+          ...skipped.length > 0 && { skippedExports: skipped.length },
+          ...externalExports.length > 0 && { externalExports: externalExports.length }
+        },
+        diagnostics,
+        ...skipped.length > 0 && {
+          skippedExports: {
+            total: skipped.length,
+            byReason,
+            ...options.verbose && { details: skipped }
+          }
         },
-        diagnostics
+        ...externalExports.length > 0 && {
+          externalExports: {
+            count: externalExports.length,
+            ...options.verbose && {
+              details: externalExports.map((e) => ({
+                name: e.name,
+                package: e.source?.package
+              }))
+            }
+          }
+        }
       };
       console.log(JSON.stringify(result, null, 2));
       process.exit(0);
@@ -562,7 +589,11 @@ function createSemverCommand() {
 // src/commands/snapshot.ts
 import * as fs8 from "node:fs";
 import * as path8 from "node:path";
-import { extractSpec } from "@openpkg-ts/sdk";
+import {
+  extractSpec,
+  loadConfig,
+  mergeConfig
+} from "@openpkg-ts/sdk";
 import { Command as Command8 } from "commander";
 function parseFilter(value) {
   if (!value)
@@ -579,8 +610,21 @@ function formatDiagnostics(diagnostics) {
   }));
 }
 function createSnapshotCommand() {
-  return new Command8("snapshot").description("Generate full OpenPkg spec from TypeScript entry point").argument("<entry>", "Entry point file path").option("-o, --output <file>", "Output file (default: openpkg.json, use - for stdout)", "openpkg.json").option("--max-depth <n>", "Max type depth (default: 4)", "4").option("--skip-resolve", "Skip external type resolution").option("--runtime", "Enable Standard Schema runtime extraction").option("--only <exports>", "Filter exports (comma-separated, wildcards supported)").option("--ignore <exports>", "Ignore exports (comma-separated, wildcards supported)").option("--verify", "Exit 1 if any exports fail").option("--verbose", "Show detailed output including skipped exports").option("--include-private", "Include private/protected class members").action(async (entry, options) => {
+  return new Command8("snapshot").description(`Generate full OpenPkg spec from TypeScript entry point
+
+` + `Config: Reads from openpkg.config.json or package.json "openpkg" field.
+` + "CLI flags override config file settings.").argument("<entry>", "Entry point file path").option("-o, --output <file>", "Output file (default: openpkg.json, use - for stdout)", "openpkg.json").option("--max-depth <n>", "Max type depth (default: 4)", "4").option("--skip-resolve", "Skip external type resolution").option("--runtime", "Enable Standard Schema runtime extraction").option("--only <exports>", "Filter exports (comma-separated, wildcards supported)").option("--ignore <exports>", "Ignore exports (comma-separated, wildcards supported)").option("--verify", "Exit 1 if any exports fail").option("--verbose", "Show detailed output including skipped exports").option("--include-private", "Include private/protected class members").option("--external-include <patterns...>", "Resolve re-exports from these packages (globs supported)").option("--external-exclude <patterns...>", "Never resolve from these packages").option("--external-depth <n>", "Max transitive depth for external resolution (default: 1)", "1").action(async (entry, options) => {
     const entryFile = path8.resolve(entry);
+    const entryDir = path8.dirname(entryFile);
+    const fileConfig = loadConfig(entryDir);
+    const cliConfig = options.externalInclude ? {
+      externals: {
+        include: options.externalInclude,
+        exclude: options.externalExclude,
+        depth: parseInt(options.externalDepth ?? "1", 10)
+      }
+    } : {};
+    const mergedConfig = mergeConfig(fileConfig, cliConfig);
     const extractOptions = {
       entryFile,
       maxTypeDepth: parseInt(options.maxDepth ?? "4", 10),
@@ -588,10 +632,12 @@ function createSnapshotCommand() {
       schemaExtraction: options.runtime ? "hybrid" : "static",
       only: parseFilter(options.only),
       ignore: parseFilter(options.ignore),
-      includePrivate: options.includePrivate
+      includePrivate: options.includePrivate,
+      ...mergedConfig.externals && { externals: mergedConfig.externals }
     };
     try {
       const result = await extractSpec(extractOptions);
+      const externalExports = result.spec.exports.filter((e) => e.kind === "external");
       const summary = {
         exports: result.spec.exports.length,
         types: result.spec.types?.length ?? 0,
@@ -607,6 +653,17 @@ function createSnapshotCommand() {
             }
           }
         },
+        ...externalExports.length > 0 && {
+          external: {
+            count: externalExports.length,
+            ...options.verbose && {
+              exports: externalExports.map((e) => ({
+                name: e.name,
+                package: e.source?.package
+              }))
+            }
+          }
+        },
         ...result.runtimeSchemas && {
           runtime: {
             extracted: result.runtimeSchemas.extracted,
@@ -616,6 +673,31 @@ function createSnapshotCommand() {
         }
       };
       console.error(JSON.stringify(summary, null, 2));
+      if (externalExports.length > 0 || (result.verification?.skipped ?? 0) > 0) {
+        console.error("");
+        if (externalExports.length > 0) {
+          if (options.verbose) {
+            console.error(`⚠ ${externalExports.length} external re-export(s) (install dependencies for full type info):`);
+            for (const exp of externalExports) {
+              console.error(`  - ${exp.name} from "${exp.source?.package}"`);
+            }
+          } else {
+            console.error(`⚠ ${externalExports.length} external re-export(s) (install dependencies for full type info)`);
+          }
+        }
+        const skipped = result.verification?.details.skipped ?? [];
+        if (skipped.length > 0) {
+          if (options.verbose) {
+            console.error(`⚠ ${skipped.length} export(s) skipped:`);
+            for (const skip of skipped) {
+              const pkgInfo = skip.package ? ` from "${skip.package}"` : "";
+              console.error(`  - ${skip.name} (${skip.reason})${pkgInfo}`);
+            }
+          } else {
+            console.error(`⚠ ${skipped.length} export(s) skipped (use --verbose for details)`);
+          }
+        }
+      }
       if (options.verify && result.verification && result.verification.failed > 0) {
         const errorOutput = {
           error: "Export verification failed",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openpkg-ts/cli",
-  "version": "0.4.2",
+  "version": "0.5.1",
   "description": "CLI for OpenPkg TypeScript API extraction and documentation generation",
   "homepage": "https://github.com/ryanwaits/openpkg-ts#readme",
   "repository": {
@@ -23,8 +23,8 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@openpkg-ts/adapters": "^0.3.1",
-    "@openpkg-ts/sdk": "^0.32.1",
+    "@openpkg-ts/adapters": "^0.3.2",
+    "@openpkg-ts/sdk": "^0.33.1",
     "commander": "^14.0.0"
   },
   "devDependencies": {