swagger-digest 0.0.0-stage → 0.1.2

package/dist/cli.d.ts

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

package/dist/cli.js

@@ -0,0 +1,240 @@
+#!/usr/bin/env node
+import {
+  VERSION,
+  defaultFilename,
+  defaultOutputDirectory,
+  estimateTokens,
+  fetchOpenApiSpec,
+  transformOpenApiToMarkdown,
+  writeDigest
+} from "./chunk-CBSDTIKN.js";
+
+// src/cli.ts
+import { input } from "@inquirer/prompts";
+import chalk from "chalk";
+import { Command } from "commander";
+import ora from "ora";
+
+// src/headers.ts
+var HEADER_NAME_PATTERN = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
+function validateHeaderName(name) {
+  if (!name) throw new Error('Header name must not be empty. Expected "Name: value".');
+  if (/[\r\n]/.test(name)) {
+    throw new Error(`Invalid header name: header names must not contain CR/LF characters.`);
+  }
+  if (!HEADER_NAME_PATTERN.test(name)) {
+    throw new Error(`Invalid header name "${name}": use a valid HTTP header token (letters, digits and -_).`);
+  }
+}
+function validateHeaderValue(name, value) {
+  if (/[\r\n]/.test(value)) {
+    throw new Error(`Invalid value for header "${name}": values must not contain CR/LF.`);
+  }
+  if (/\0/.test(value)) {
+    throw new Error(`Invalid value for header "${name}": values must not contain NUL bytes.`);
+  }
+}
+function parseHeaderArgument(raw) {
+  const separator = raw.indexOf(":");
+  if (separator === -1) {
+    if (/[\r\n]/.test(raw)) {
+      throw new Error(`Invalid header: names and values must not contain CR/LF.`);
+    }
+    throw new Error(`Invalid header \u2014 expected "Name: value" format (for example "Authorization: Bearer <token>").`);
+  }
+  const name = raw.slice(0, separator).trim();
+  const value = raw.slice(separator + 1).trim();
+  validateHeaderName(name);
+  validateHeaderValue(name, value);
+  return { [name.toLowerCase()]: value };
+}
+function parseHeaderPairs(raw) {
+  const result = {};
+  for (const line of raw.split(/\r?\n/)) {
+    if (!line.trim()) continue;
+    Object.assign(result, parseHeaderArgument(line));
+  }
+  return result;
+}
+function mergeHeaders(...sources) {
+  const result = {};
+  for (const source of sources) {
+    if (!source) continue;
+    for (const [name, value] of Object.entries(source)) {
+      if (/[\r\n]/.test(name) || /[\r\n]/.test(value)) {
+        throw new Error(`Invalid header "${name}": CR/LF is not allowed in header names or values.`);
+      }
+      result[name.toLowerCase()] = value;
+    }
+  }
+  return result;
+}
+
+// src/cli.ts
+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);
+}
+function parseMaxBytes(value) {
+  if (value === void 0) return void 0;
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed <= 0 || !Number.isInteger(parsed)) {
+    throw new Error(`Invalid --max-bytes value: ${value}. Use a positive integer number of bytes.`);
+  }
+  return parsed;
+}
+function parseMaxTokens(value) {
+  if (value === void 0) return void 0;
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed <= 0 || !Number.isInteger(parsed)) {
+    throw new Error(`Invalid --max-tokens value: ${value}. Use a positive integer number of tokens.`);
+  }
+  return parsed;
+}
+function collectOption(value, previous) {
+  return [...previous ?? [], value];
+}
+function buildRequestHeaders(options) {
+  const fromEnv = process.env.SWAGGER_DIGEST_HEADER ? parseHeaderPairs(process.env.SWAGGER_DIGEST_HEADER) : {};
+  const fromFlags = (options.headers ?? []).map(parseHeaderArgument);
+  const cookieHeader = options.cookie !== void 0 ? parseHeaderArgument(`Cookie: ${options.cookie}`) : {};
+  return mergeHeaders(fromEnv, ...fromFlags, cookieHeader);
+}
+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(VERSION).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").option("--max-bytes <bytes>", "Maximum response size in bytes (default 10000000 = 10 MB)", "10000000").option(
+    '-H, --header <"Name: value">',
+    "Custom request header, repeatable. Sent only to the URL you supplied.",
+    collectOption,
+    []
+  ).option("--cookie <string>", "Convenience for a Cookie request header (same-origin scoping applies)").option("--include-tag <tag>", "Keep only operations with this tag, repeatable", collectOption, []).option("--exclude-tag <tag>", "Drop operations with this tag, repeatable", collectOption, []).option("--path-prefix <prefix>", "Keep only operations whose path starts with this prefix").option("--max-tokens <n>", "Trim the digest until the approximate token estimate fits this budget").option("--spec <url>", "Explicit OpenAPI spec URL; overrides discovery from the Swagger UI page").option("--stdout", "Print the digest to standard output instead of writing a file").addHelpText(
+    "after",
+    [
+      "",
+      "Examples:",
+      "  npx swagger-digest",
+      "  npx swagger-digest --url https://petstore.swagger.io/ --out-dir ./docs",
+      "  npx swagger-digest -u https://example.com/openapi.yaml -f payments-api.md",
+      '  npx swagger-digest -u https://api.example.com/swagger-ui -H "Authorization: Bearer <token>"',
+      "",
+      "Authentication:",
+      "  -H/--header and --cookie values are sent ONLY to the origin of --url.",
+      '  You can also set SWAGGER_DIGEST_HEADER with newline-separated "Name: value" pairs;',
+      "  -H flags override it on conflicts. Avoid passing secrets on the command line if",
+      "  your shell saves history \u2014 prefer the environment variable.",
+      "",
+      "Filtering and token budget:",
+      "  --include-tag/--exclude-tag/--path-prefix remove operations (and the data",
+      "  models only they referenced) before rendering.",
+      "  --max-tokens trims the digest in this order until the estimate fits:",
+      "  1. drop declared example payloads \u2192 2. shorten descriptions \u2192",
+      "  3. collapse parameter/response detail per tag (lowest-priority tag first:",
+      "  the tag that appears last in the document is collapsed first) \u2192",
+      '  4. keep only the Quick index entries. A "Trimmed" note records what was',
+      "  removed. The estimator is a heuristic, NOT tokenizer-accurate \u2014 treat the",
+      "  budget as a guide, not a guarantee."
+    ].join("\n")
+  );
+  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);
+  if (options.stdout && (options.outDir !== void 0 || options.filename !== void 0)) {
+    throw new Error(
+      "--stdout cannot be combined with --out-dir or --filename: it prints the digest to standard output instead of writing a file. Drop --stdout, or remove --out-dir/--filename."
+    );
+  }
+  const outputDirectory = options.outDir ?? (isInteractive() && !options.stdout ? await input({
+    message: "Destination directory",
+    default: defaultOutputDirectory(),
+    validate: (value) => value.trim() ? true : "Enter a destination directory."
+  }) : defaultOutputDirectory());
+  const maxBytes = parseMaxBytes(options.maxBytes);
+  const requestHeaders = buildRequestHeaders(options);
+  const spinner = ora({ text: "Fetching and parsing OpenAPI definition\u2026", color: "cyan" }).start();
+  let result;
+  try {
+    result = await fetchOpenApiSpec(url, {
+      useBrowserFallback: options.browser !== false,
+      maxBytes,
+      headers: requestHeaders,
+      specUrl: options.spec,
+      warn: (message) => console.error(chalk.yellow(`Warning: ${message}`))
+    });
+  } 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, {
+    includeTags: options.includeTag,
+    excludeTags: options.excludeTag,
+    pathPrefix: options.pathPrefix,
+    maxTokens: parseMaxTokens(options.maxTokens),
+    onWarning: (message) => console.error(chalk.yellow(`Warning: ${message}`))
+  });
+  spinner.succeed(`Parsed ${title} (${result.retrievalMethod})`);
+  if (options.stdout) {
+    process.stdout.write(markdown);
+    return;
+  }
+  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"];
+      const operations = pathItem;
+      return count + methods.filter((method) => operations[method] && typeof operations[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 (approximate):"));
+    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,95 @@
+type JsonObject = Record<string, any>;
+interface FetchOptions {
+    timeoutMs?: number;
+    useBrowserFallback?: boolean;
+    /** Maximum response body size in bytes (default 10 MB). */
+    maxBytes?: number;
+    /** Maximum number of redirects to follow (default 5). */
+    maxRedirects?: number;
+    /** Opt-in: reject hostnames resolving to private/loopback/metadata addresses. */
+    blockPrivateNetworks?: boolean;
+    /** Timeout for fallback-path probes (default 5000ms; main requests use timeoutMs). */
+    probeTimeoutMs?: number;
+    /**
+     * Custom request headers (e.g. Authorization or Cookie). These are sent ONLY
+     * to the origin of the URL passed to fetchOpenApiSpec; cross-origin requests
+     * (including cross-origin redirects and third-party browser requests) never
+     * receive them.
+     */
+    headers?: Record<string, string>;
+    /** Receives non-fatal notices, e.g. headers withheld on a cross-origin fetch. */
+    warn?: (message: string) => void;
+    /**
+     * Explicit spec URL that overrides discovery entirely: it is fetched first
+     * (with the same header scoping as the main URL) and the page is never
+     * consulted when it parses successfully.
+     */
+    specUrl?: string;
+}
+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;
+
+interface TransformOptions {
+    /** Keep only operations carrying at least one of these tags. Repeatable. */
+    includeTags?: string[];
+    /** Drop operations carrying any of these tags. Repeatable. */
+    excludeTags?: string[];
+    /** Keep only operations whose path starts with this prefix. */
+    pathPrefix?: string;
+    /**
+     * Trim the digest until the (approximate, heuristic) token estimate fits this
+     * budget. The estimator is not tokenizer-accurate; treat the budget as a guide.
+     */
+    maxTokens?: number;
+    /** Receives non-fatal notices, e.g. unknown tag names. */
+    onWarning?: (message: string) => void;
+}
+/** Convert an OpenAPI 2.0, 3.0, or 3.1 document to a compact Markdown digest. */
+declare function transformOpenApiToMarkdown(spec: JsonObject, sourceUrl?: string, options?: TransformOptions): 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;
+    };
+}
+/**
+ * Produces ROUGH token-count estimates for Markdown/code. The numbers are a
+ * heuristic (word + symbol density with per-model multipliers), not accurate
+ * tokenizer counts — use them as an order-of-magnitude guide only.
+ */
+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, TransformOptions };

package/dist/index.js

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

package/package.json

@@ -1,6 +1,84 @@
 {
   "name": "swagger-digest",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.2",
+  "description": "Turn Swagger UI pages and OpenAPI specs into compact, AI-friendly Markdown API digests.",
+  "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 test"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "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": [
+    "openapi",
+    "swagger",
+    "markdown",
+    "llm",
+    "ai-coding-agent",
+    "cli"
+  ],
+  "license": "MIT"
+}