@openpkg-ts/cli 0.9.3 → 0.11.0

package/dist/index.js

@@ -5,32 +5,49 @@ import fs from "node:fs";
 import path from "node:path";
 import { parseArgs } from "node:util";
 import {
+  calculateNextVersion,
+  categorizeBreakingChanges,
   createDocs,
   diffSpecs,
   extractSpec,
+  getAvailableVersions,
+  getValidationErrors,
   listExports,
+  loadConfig,
+  mergeConfig,
   recommendSemverBump
 } from "@openpkg-ts/sdk";
 var HELP = `openpkg - extract TypeScript API specs and generate docs
 
 Usage:
-  openpkg spec <entry.ts> [-o spec.json]
+  openpkg spec <entry.ts> [-o spec.json] [--follow-external <pkg,...>]
   openpkg docs <entry.ts | spec.json> [-f md|html|json] [-o out]
   openpkg list <entry.ts> [--json]
-  openpkg diff <old.json> <new.json>
+  openpkg validate <spec.json>
+  openpkg diff <old.json> <new.json> [--json]
 
 Commands:
-  spec    Extract an OpenPkg spec from a TypeScript entry point
-  docs    Generate docs from an entry point or an existing spec file
-  list    List exports (name, kind, location)
-  diff    Compare two spec files and recommend a semver bump
+  spec      Extract an OpenPkg spec from a TypeScript entry point
+  docs      Generate docs from an entry point or an existing spec file
+  list      List exports (name, kind, location)
+  validate  Validate a spec file against the OpenPkg meta-schema
+  diff      Compare two spec files and recommend a semver bump
 
 Options:
-  -o, --output   Write to file instead of stdout
-  -f, --format   docs output format: md (default), html, json
-      --json     list output as JSON
-  -h, --help     Show this help
-  -v, --version  Show version
+  -o, --output            Write to file instead of stdout
+  -f, --format            docs output format: md (default), html, json
+      --json              list/diff output as JSON
+      --follow-external   Expand types from these packages (comma-separated,
+                          globs ok: "@ai-sdk/*"). Default: stub externals.
+      --follow-external-all   Expand every external package (use with care)
+      --only              Only extract these exports (comma-separated, * ok)
+      --ignore            Ignore these exports (comma-separated, * ok)
+  -h, --help              Show this help
+  -v, --version           Show version
+
+Config: reads openpkg.config.json (or package.json "openpkg" field) from the
+cwd. Flags override the file. Example openpkg.config.json:
+  { "followExternal": ["@acme/payment-kit", "@ai-sdk/*"] }
 `;
 function fail(message) {
   console.error(`error: ${message}`);
@@ -59,17 +76,59 @@ function reportDiagnostics(diagnostics) {
     process.exit(1);
   }
 }
+function toList(value) {
+  if (!value)
+    return;
+  const items = value.split(",").map((s) => s.trim()).filter(Boolean);
+  return items.length > 0 ? items : undefined;
+}
+function reportStubbedExternals(spec) {
+  const counts = new Map;
+  for (const t of spec.types ?? []) {
+    if (!t.external)
+      continue;
+    const pkg = t.schema?.["x-ts-package"];
+    const key = typeof pkg === "string" ? pkg : "(unknown origin)";
+    counts.set(key, (counts.get(key) ?? 0) + 1);
+  }
+  if (counts.size === 0)
+    return;
+  const summary = [...counts.entries()].sort((a, b) => b[1] - a[1]).map(([pkg, n]) => `${pkg} (${n})`).join(", ");
+  console.error(`external types stubbed from: ${summary}`);
+  console.error("  → add package names to followExternal (config or --follow-external) to expand them");
+}
 async function specCommand(args) {
   const { values, positionals } = parseArgs({
     args,
-    options: { output: { type: "string", short: "o" } },
+    options: {
+      output: { type: "string", short: "o" },
+      "follow-external": { type: "string" },
+      "follow-external-all": { type: "boolean" },
+      only: { type: "string" },
+      ignore: { type: "string" }
+    },
     allowPositionals: true
   });
   const entryFile = positionals[0];
   if (!entryFile)
     fail("spec requires an entry file (openpkg spec src/index.ts)");
-  const { spec, diagnostics } = await extractSpec({ entryFile });
+  const fileConfig = loadConfig(process.cwd());
+  const cliConfig = {
+    followExternal: values["follow-external-all"] ? true : toList(values["follow-external"]),
+    only: toList(values.only),
+    ignore: toList(values.ignore)
+  };
+  const config = mergeConfig(fileConfig, cliConfig);
+  const { spec, diagnostics } = await extractSpec({
+    entryFile,
+    followExternal: config.followExternal,
+    only: config.only,
+    ignore: config.ignore,
+    externals: config.externals
+  });
   reportDiagnostics(diagnostics);
+  if (!config.followExternal)
+    reportStubbedExternals(spec);
   write(JSON.stringify(spec, null, 2), values.output);
 }
 async function docsCommand(args) {
@@ -130,12 +189,67 @@ function readSpecFile(file) {
     fail(`failed to read spec file ${file}: ${err instanceof Error ? err.message : String(err)}`);
   }
 }
+function pickVersion(spec) {
+  const declared = spec?.openpkg;
+  if (typeof declared === "string" && getAvailableVersions().includes(declared)) {
+    return declared;
+  }
+  return "latest";
+}
+function readValidSpecFile(file) {
+  const parsed = readSpecFile(file);
+  const errors = getValidationErrors(parsed, pickVersion(parsed));
+  if (errors.length > 0) {
+    const details = errors.map((e) => `  ${e.instancePath || "/"} ${e.message}`).join(`
+`);
+    fail(`invalid spec ${file}:
+${details}`);
+  }
+  return parsed;
+}
+function validateCommand(args) {
+  const [file] = args;
+  if (!file)
+    fail("validate requires a spec file (openpkg validate spec.json)");
+  const spec = readSpecFile(file);
+  const errors = getValidationErrors(spec, pickVersion(spec));
+  if (errors.length === 0) {
+    console.log(`${file}: valid`);
+    return;
+  }
+  for (const e of errors) {
+    console.error(`${e.instancePath || "/"} ${e.message}`);
+  }
+  process.exit(1);
+}
 function diffCommand(args) {
-  const [oldFile, newFile] = args;
+  const { values, positionals } = parseArgs({
+    args,
+    options: { json: { type: "boolean" } },
+    allowPositionals: true
+  });
+  const [oldFile, newFile] = positionals;
   if (!oldFile || !newFile)
     fail("diff requires two spec files (openpkg diff old.json new.json)");
-  const diff = diffSpecs(readSpecFile(oldFile), readSpecFile(newFile));
+  const oldSpec = readValidSpecFile(oldFile);
+  const newSpec = readValidSpecFile(newFile);
+  const diff = diffSpecs(oldSpec, newSpec);
   const recommendation = recommendSemverBump(diff);
+  const oldVersion = newSpec?.meta?.version;
+  const nextVersion = oldVersion ? calculateNextVersion(oldVersion, recommendation.bump) : undefined;
+  if (values.json) {
+    console.log(JSON.stringify({
+      breaking: diff.breaking,
+      nonBreaking: diff.nonBreaking,
+      docsOnly: diff.docsOnly,
+      categorized: categorizeBreakingChanges(diff.breaking, oldSpec, newSpec),
+      recommendation,
+      ...nextVersion ? { nextVersion } : {}
+    }, null, 2));
+    if (diff.breaking.length)
+      process.exitCode = 2;
+    return;
+  }
   const section = (title, items) => {
     if (!items.length)
       return;
@@ -151,6 +265,8 @@ function diffCommand(args) {
   }
   console.log(`
 Recommended bump: ${recommendation.bump} (${recommendation.reason})`);
+  if (nextVersion)
+    console.log(`Next version: ${nextVersion}`);
   if (diff.breaking.length)
     process.exitCode = 2;
 }
@@ -166,6 +282,9 @@ async function main() {
     case "list":
       await listCommand(rest);
       break;
+    case "validate":
+      validateCommand(rest);
+      break;
     case "diff":
       diffCommand(rest);
       break;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openpkg-ts/cli",
-  "version": "0.9.3",
+  "version": "0.11.0",
   "description": "CLI for OpenPkg - extract TypeScript API specs and generate docs",
   "keywords": [
     "openpkg",
@@ -35,7 +35,7 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@openpkg-ts/sdk": "^0.46.0"
+    "@openpkg-ts/sdk": "^0.48.0"
   },
   "devDependencies": {
     "@types/bun": "latest",