swagger-digest 0.0.0-stage → 0.1.1

package/dist/cli.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/cli.js

@@ -0,0 +1,104 @@
+#!/usr/bin/env node
+import {
+  defaultFilename,
+  defaultOutputDirectory,
+  estimateTokens,
+  fetchOpenApiSpec,
+  transformOpenApiToMarkdown,
+  writeDigest
+} from "./chunk-UZQM2SHL.js";
+
+// src/cli.ts
+import { input } from "@inquirer/prompts";
+import chalk from "chalk";
+import { Command } from "commander";
+import ora from "ora";
+function validateUrl(value) {
+  try {
+    const url = new URL(value);
+    if (url.protocol !== "http:" && url.protocol !== "https:") return "Use an http:// or https:// URL.";
+    return true;
+  } catch {
+    return "Enter a valid URL, including https://.";
+  }
+}
+function isInteractive() {
+  return Boolean(process.stdin.isTTY && process.stdout.isTTY);
+}
+async function main() {
+  const program = new Command();
+  program.name("swagger-digest").description("Convert a Swagger UI page or OpenAPI URL into compact, AI-friendly Markdown.").version("0.1.1").option("-u, --url <url>", "Swagger UI page URL or direct OpenAPI spec URL").option("-d, --out-dir <directory>", "Directory where the Markdown digest will be saved").option("-f, --filename <filename>", "Output filename (defaults to <api-title>-digest.md)").option("--no-browser", "Disable the optional Playwright headless-browser fallback").addHelpText(
+    "after",
+    "\nExamples:\n  npx swagger-digest\n  npx swagger-digest --url https://petstore.swagger.io/ --out-dir ./docs\n  npx swagger-digest -u https://example.com/openapi.yaml -f payments-api.md"
+  );
+  program.parse(process.argv);
+  const options = program.opts();
+  if (!options.url && !isInteractive()) {
+    throw new Error("An interactive terminal or --url is required. Run `swagger-digest --help` for usage.");
+  }
+  const url = options.url ?? await input({
+    message: "Swagger UI or OpenAPI spec URL",
+    validate: validateUrl
+  });
+  const validUrl = validateUrl(url);
+  if (validUrl !== true) throw new Error(validUrl);
+  const outputDirectory = options.outDir ?? (isInteractive() ? await input({
+    message: "Destination directory",
+    default: defaultOutputDirectory(),
+    validate: (value) => value.trim() ? true : "Enter a destination directory."
+  }) : defaultOutputDirectory());
+  const spinner = ora({ text: "Fetching and parsing OpenAPI definition\u2026", color: "cyan" }).start();
+  let result;
+  try {
+    result = await fetchOpenApiSpec(url, { useBrowserFallback: options.browser !== false });
+  } catch (error) {
+    spinner.fail("Could not extract an OpenAPI definition");
+    throw error;
+  }
+  const title = typeof result.spec.info?.title === "string" ? result.spec.info.title : "API";
+  const markdown = transformOpenApiToMarkdown(result.spec, result.sourceUrl);
+  spinner.succeed(`Parsed ${title} (${result.retrievalMethod})`);
+  const filename = options.filename ?? (isInteractive() ? await input({
+    message: "Output filename",
+    default: defaultFilename(title),
+    validate: (value) => value.trim() ? true : "Enter a filename."
+  }) : defaultFilename(title));
+  const writeSpinner = ora({ text: "Writing Markdown digest\u2026", color: "cyan" }).start();
+  try {
+    const outputPath = await writeDigest({ markdown, directory: outputDirectory, filename });
+    writeSpinner.succeed(`Saved ${chalk.green(outputPath)}`);
+    const report = estimateTokens(markdown);
+    const endpointCount = Object.values(result.spec.paths ?? {}).reduce((count, pathItem) => {
+      if (!pathItem || typeof pathItem !== "object") return count;
+      const methods = ["get", "put", "post", "delete", "options", "head", "patch", "trace"];
+      return count + methods.filter((method) => pathItem[method] && typeof pathItem[method] === "object").length;
+    }, 0);
+    const modelCount = Object.keys(result.spec.components?.schemas ?? result.spec.definitions ?? {}).length;
+    console.log("");
+    console.log(chalk.bold("Digest summary:"));
+    console.log(`  ${chalk.dim("\u2022")} Endpoints:       ${chalk.cyan(endpointCount)} operations`);
+    if (modelCount > 0) {
+      console.log(`  ${chalk.dim("\u2022")} Data models:     ${chalk.cyan(modelCount)} schemas`);
+    }
+    console.log(`  ${chalk.dim("\u2022")} Characters:      ${chalk.dim(report.characters.toLocaleString())}`);
+    console.log("");
+    console.log(chalk.bold("Estimated token usage (5 Frontier Models):"));
+    for (const model of Object.values(report.models)) {
+      const windowLabel = model.contextWindow >= 1e6 ? `${model.contextWindow / 1e6}M` : `${model.contextWindow / 1e3}k`;
+      const paddedName = `${model.name}:`.padEnd(30, " ");
+      const tokenStr = `~${model.tokens.toLocaleString()} tokens`.padEnd(16, " ");
+      const percentStr = chalk.dim(`(${model.contextPercent}% of ${windowLabel} context)`);
+      console.log(`  ${chalk.dim("\u2022")} ${paddedName} ${chalk.green(tokenStr)} ${percentStr}`);
+    }
+    console.log("");
+  } catch (error) {
+    writeSpinner.fail("Could not write digest");
+    throw error;
+  }
+}
+main().catch((error) => {
+  const message = error instanceof Error ? error.message : String(error);
+  console.error(chalk.red(`
+Error: ${message}`));
+  process.exitCode = 1;
+});

package/dist/index.d.ts

@@ -0,0 +1,55 @@
+type JsonObject = Record<string, any>;
+interface FetchOptions {
+    timeoutMs?: number;
+    useBrowserFallback?: boolean;
+}
+interface FetchResult {
+    spec: JsonObject;
+    sourceUrl: string;
+    retrievalMethod: 'direct-spec' | 'html-config' | 'inline-spec' | 'fallback-path' | 'headless-browser';
+}
+
+declare function isOpenApiSpec(value: unknown): value is JsonObject;
+/** Parse JSON or YAML and reject arbitrary documents that are not OpenAPI/Swagger specs. */
+declare function parseSpecText(text: string, source?: string): JsonObject;
+/** Resolve a Swagger UI page or a direct OpenAPI JSON/YAML URL into a parsed spec. */
+declare function fetchOpenApiSpec(input: string, options?: FetchOptions): Promise<FetchResult>;
+
+declare function toTypeScriptIdentifier(value: string): string;
+/** Convert an OpenAPI 2.0, 3.0, or 3.1 document to a compact Markdown digest. */
+declare function transformOpenApiToMarkdown(spec: JsonObject, sourceUrl?: string): string;
+
+interface ModelTokenEstimate {
+    name: string;
+    tokens: number;
+    contextWindow: number;
+    contextPercent: number;
+}
+interface DigestTokenReport {
+    characters: number;
+    models: {
+        claude: ModelTokenEstimate;
+        openai: ModelTokenEstimate;
+        gemini: ModelTokenEstimate;
+        deepseek: ModelTokenEstimate;
+        llama: ModelTokenEstimate;
+    };
+}
+/**
+ * Estimates token counts for Markdown/code across 5 frontier model tokenizers.
+ * Accurately models differences between cl100k/o200k, Claude BPE, SentencePiece 256k, and 128k BPE.
+ */
+declare function estimateTokens(text: string): DigestTokenReport;
+
+declare function defaultOutputDirectory(): string;
+declare function defaultFilename(apiTitle?: string): string;
+declare function resolveOutputDirectory(directory: string, cwd?: string): string;
+declare function normalizeFilename(filename: string, fallback?: string): string;
+declare function writeDigest(options: {
+    markdown: string;
+    directory: string;
+    filename: string;
+}): Promise<string>;
+
+export { defaultFilename, defaultOutputDirectory, estimateTokens, fetchOpenApiSpec, isOpenApiSpec, normalizeFilename, parseSpecText, resolveOutputDirectory, toTypeScriptIdentifier, transformOpenApiToMarkdown, writeDigest };
+export type { DigestTokenReport, FetchOptions, FetchResult, JsonObject, ModelTokenEstimate };

package/dist/index.js

@@ -0,0 +1,26 @@
+import {
+  defaultFilename,
+  defaultOutputDirectory,
+  estimateTokens,
+  fetchOpenApiSpec,
+  isOpenApiSpec,
+  normalizeFilename,
+  parseSpecText,
+  resolveOutputDirectory,
+  toTypeScriptIdentifier,
+  transformOpenApiToMarkdown,
+  writeDigest
+} from "./chunk-UZQM2SHL.js";
+export {
+  defaultFilename,
+  defaultOutputDirectory,
+  estimateTokens,
+  fetchOpenApiSpec,
+  isOpenApiSpec,
+  normalizeFilename,
+  parseSpecText,
+  resolveOutputDirectory,
+  toTypeScriptIdentifier,
+  transformOpenApiToMarkdown,
+  writeDigest
+};

package/package.json

@@ -1,6 +1,86 @@
 {
   "name": "swagger-digest",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Interactive CLI that converts Swagger UI pages and OpenAPI specs into compact Markdown for AI coding agents.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "swagger-digest": "dist/cli.js"
+  },
+  "author": "VladLegkowski <VladLegkowski@users.noreply.github.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/VladLegkowski/swagger-digest.git"
+  },
+  "homepage": "https://github.com/VladLegkowski/swagger-digest#readme",
+  "bugs": {
+    "url": "https://github.com/VladLegkowski/swagger-digest/issues"
+  },
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts src/cli.ts --format esm --dts --clean",
+    "dev": "tsx src/cli.ts",
+    "start": "node dist/cli.js",
+    "typecheck": "tsc --noEmit",
+    "test": "npm run typecheck && tsx --test test/*.test.ts",
+    "check:exports": "publint",
+    "lint": "eslint .",
+    "prepare": "husky",
+    "prepack": "npm run build",
+    "prepublishOnly": "npm run build && npm test && npm run lint"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "dependencies": {
+    "@inquirer/prompts": "^7.3.2",
+    "chalk": "^5.4.1",
+    "cheerio": "^1.0.0",
+    "commander": "^13.1.0",
+    "ora": "^8.2.0",
+    "yaml": "^2.7.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.0",
+    "eslint": "^9.27.0",
+    "husky": "^9.1.7",
+    "lint-staged": "^17.6.0",
+    "prettier": "^3.9.10",
+    "publint": "^0.3.25",
+    "tsup": "^9.0.0",
+    "tsx": "^4.19.4",
+    "typescript": "^5.8.3",
+    "typescript-eslint": "^8.32.0"
+  },
+  "peerDependencies": {
+    "playwright": "^1.50.0"
+  },
+  "peerDependenciesMeta": {
+    "playwright": {
+      "optional": true
+    }
+  },
+  "keywords": [
+    "swagger",
+    "openapi",
+    "cli",
+    "ai",
+    "llm",
+    "markdown",
+    "docs",
+    "ai-coding-agent"
+  ],
+  "license": "MIT"
+}