@subhamxcod/apiguard 1.0.2

package/dist/index.d.cts

@@ -0,0 +1,204 @@
+/** Zod config schema per spec §14.3. Keys use the kebab-case spelling from the spec. */
+
+/** Internal, camelCase-shaped resolved configuration consumed by the engine/CLI. */
+interface ResolvedConfig {
+    schemaVersion: 1;
+    rules: Record<string, 'error' | 'warning' | 'info' | 'off'>;
+    ignore: {
+        paths: string[];
+        operations: string[];
+        schemas: string[];
+        changes: string[];
+        showIgnored: boolean;
+    };
+    output: {
+        format: 'terminal' | 'json' | 'markdown';
+        includeNonBreaking: boolean;
+        color: 'auto' | 'always' | 'never';
+    };
+    failOn: 'error' | 'warning' | 'never';
+    versioning: {
+        suggest: boolean;
+    };
+    loader: {
+        allowRemoteRefs: boolean;
+    };
+    github: {
+        comment: boolean;
+        checkRun: boolean;
+        updateExistingComment: boolean;
+    };
+}
+
+/** Core change taxonomy and change records per spec §4/§8. */
+type Severity = 'error' | 'warning' | 'info';
+type ChangeKind = 'addition' | 'removal' | 'modification' | 'relaxation' | 'documentation';
+/** HTTP methods recognized in location.method. */
+type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS' | 'TRACE';
+/** Where a change was found, per spec §4 taxonomy. */
+type Context = 'api' | 'operation' | 'request-body' | 'response-body' | 'request-header' | 'response-header' | 'parameter' | 'component' | 'security' | 'callback' | 'webhook';
+interface ChangeLocation {
+    /** URL path template, e.g. "/users/{id}"; '/' for api-level, '' for components. */
+    path: string;
+    method?: HttpMethod | string;
+    operationId?: string;
+    /** JSON Pointer into the OLD document (after deref where applicable). */
+    pointerOld: string;
+    /** JSON Pointer into the NEW document. */
+    pointerNew: string;
+    context: Context;
+    /** When media-type relevant, e.g. "application/json". */
+    mediaType?: string;
+    /** Response context status code, e.g. "200" | "default". */
+    statusCode?: string;
+    /** When context === 'component'. */
+    componentName?: string;
+    /** Component rules: number of operation usages found. */
+    usageCount?: number;
+}
+interface ApiChange {
+    /** stable id = sha256(...).slice(0,16) per spec §12. */
+    id: string;
+    ruleId: string;
+    severity: Severity;
+    kind: ChangeKind;
+    /** Derived: severity === 'error'. Stored per spec §8. */
+    breaking: boolean;
+    location: ChangeLocation;
+    /** Human sentence, stable template. */
+    message: string;
+    /** Required for every change. */
+    suggestion: string;
+    /** Compact raw values (never full subtrees) for the JSON reporter. */
+    oldValue?: unknown;
+    newValue?: unknown;
+    /** True only when show-ignored rendering includes a suppressed change. */
+    ignored?: boolean;
+}
+interface DiffSummary {
+    total: number;
+    bySeverity: Record<Severity, number>;
+    byKind: Record<ChangeKind, number>;
+    /** Count of ignored changes (when show-ignored enabled). */
+    ignored: number;
+}
+interface SemverAdvice {
+    bump: 'major' | 'minor' | 'patch' | 'none';
+    reason: string;
+    triggers: string[];
+}
+
+/** Per-spec metadata used by reporters, per spec §8 DiffReport sides. */
+interface SpecMeta {
+    source: string;
+    openapiVersion: string;
+    title: string;
+    sha256: string;
+}
+/** Full diff report — the machine contract (§15.1). Field order matters. */
+interface DiffReport {
+    schemaVersion: '1.0';
+    tool: {
+        name: 'apiguard';
+        version: string;
+    };
+    baseline: SpecMeta;
+    current: SpecMeta;
+    summary: DiffSummary;
+    changes: ApiChange[];
+    semver: SemverAdvice;
+    /** Present only when show-ignored is enabled. */
+    ignored?: ApiChange[];
+}
+
+interface AnalyzeOptions {
+    /** Explicit config path; otherwise discovery per §14.1. */
+    configPath?: string;
+    /** Pre-resolved config (used by the Action); overrides configPath. */
+    config?: ResolvedConfig;
+    /** Show changes suppressed by ignore rules. */
+    showIgnored?: boolean;
+}
+interface AnalyzeResult {
+    report: DiffReport;
+    ignored: ApiChange[];
+}
+/** Run the full diff pipeline over two spec files. */
+declare function analyze(baselinePath: string, currentPath: string, options?: AnalyzeOptions): Promise<AnalyzeResult>;
+
+interface ValidationIssue {
+    /** Severity class of the issue. */
+    level: 'error' | 'warning';
+    /** e.g. "spec.yaml" — rendered as `file: message` (line when known). */
+    file: string;
+    message: string;
+}
+interface ValidationResult {
+    issues: ValidationIssue[];
+    /** true when no structural (level=error) issues were found. */
+    ok: boolean;
+}
+
+type JsonValue = unknown;
+/** Resolved spec bundle: parsed document plus provenance metadata. */
+interface LoadedSpec {
+    /** Parsed document as plain JSON-compatible data. */
+    document: JsonValue;
+    /** Human-readable source label (file path or ref), used in reports. */
+    source: string;
+    /** OpenAPI version string as declared in the document (e.g. "3.0.3", "3.1.0"); '' when absent. */
+    openapiVersion: string;
+    /** Document title or '' when absent. */
+    title: string;
+    /** sha256 hex digest of the normalized document bytes. */
+    sha256: string;
+}
+/** Internal representation of a normalized spec used by the diff engine. */
+interface NormalizedSpec extends LoadedSpec {
+    /** The normalized document (types as arrays, exclusiveMin/Max numeric, etc.). */
+    normalized: JsonValue;
+}
+
+interface LoadedConfig {
+    config: ResolvedConfig;
+    /** Path of the file the config came from ('' when defaults only). */
+    sourcePath: string;
+    /** Deprecation warnings collected during load (printed to stderr by the CLI). */
+    warnings: string[];
+}
+/** Load config from an explicit path (missing file → ConfigError, exit 2). */
+declare function loadConfigFrom(explicitPath: string): LoadedConfig;
+/** Discover config per §14.1; returns defaults when nothing is found. */
+declare function discoverAndLoadConfig(opts?: {
+    explicit?: string;
+    env?: string;
+    cwd?: string;
+}): LoadedConfig;
+
+/** Semver advisor per spec §16 — pure function over the change set. */
+
+/**
+ * Decision table (§16):
+ * 1. any error → major (reason lists top ruleIds by count)
+ * 2. else any addition|removal|modification OR any warning → minor
+ * 3. else any relaxation|documentation info → patch
+ * 4. else none
+ */
+declare function suggestVersion(changes: ApiChange[]): SemverAdvice;
+
+/** Public library API per spec §18. Pure; no stdout; no process.exit. */
+
+/**
+ * Load + validate a spec (§18 `validateSpec`). Throws SpecLoadError (exit-3 class) on
+ * structural problems; returns the semantic issue list otherwise.
+ */
+declare function validateSpec(specPath: string, options?: {
+    loader?: {
+        allowRemoteRefs?: boolean;
+    };
+}): Promise<{
+    spec: NormalizedSpec;
+    validation: ValidationResult;
+}>;
+
+export { type AnalyzeOptions, type AnalyzeResult, type ApiChange, type ChangeKind, type ChangeLocation, type Context, type DiffReport, type DiffSummary, type LoadedConfig, type LoadedSpec, type NormalizedSpec, type ResolvedConfig, type SemverAdvice, type Severity, type SpecMeta, type ValidationIssue, type ValidationResult, analyze, discoverAndLoadConfig, loadConfigFrom, suggestVersion, validateSpec };

package/dist/index.d.ts

@@ -0,0 +1,204 @@
+/** Zod config schema per spec §14.3. Keys use the kebab-case spelling from the spec. */
+
+/** Internal, camelCase-shaped resolved configuration consumed by the engine/CLI. */
+interface ResolvedConfig {
+    schemaVersion: 1;
+    rules: Record<string, 'error' | 'warning' | 'info' | 'off'>;
+    ignore: {
+        paths: string[];
+        operations: string[];
+        schemas: string[];
+        changes: string[];
+        showIgnored: boolean;
+    };
+    output: {
+        format: 'terminal' | 'json' | 'markdown';
+        includeNonBreaking: boolean;
+        color: 'auto' | 'always' | 'never';
+    };
+    failOn: 'error' | 'warning' | 'never';
+    versioning: {
+        suggest: boolean;
+    };
+    loader: {
+        allowRemoteRefs: boolean;
+    };
+    github: {
+        comment: boolean;
+        checkRun: boolean;
+        updateExistingComment: boolean;
+    };
+}
+
+/** Core change taxonomy and change records per spec §4/§8. */
+type Severity = 'error' | 'warning' | 'info';
+type ChangeKind = 'addition' | 'removal' | 'modification' | 'relaxation' | 'documentation';
+/** HTTP methods recognized in location.method. */
+type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS' | 'TRACE';
+/** Where a change was found, per spec §4 taxonomy. */
+type Context = 'api' | 'operation' | 'request-body' | 'response-body' | 'request-header' | 'response-header' | 'parameter' | 'component' | 'security' | 'callback' | 'webhook';
+interface ChangeLocation {
+    /** URL path template, e.g. "/users/{id}"; '/' for api-level, '' for components. */
+    path: string;
+    method?: HttpMethod | string;
+    operationId?: string;
+    /** JSON Pointer into the OLD document (after deref where applicable). */
+    pointerOld: string;
+    /** JSON Pointer into the NEW document. */
+    pointerNew: string;
+    context: Context;
+    /** When media-type relevant, e.g. "application/json". */
+    mediaType?: string;
+    /** Response context status code, e.g. "200" | "default". */
+    statusCode?: string;
+    /** When context === 'component'. */
+    componentName?: string;
+    /** Component rules: number of operation usages found. */
+    usageCount?: number;
+}
+interface ApiChange {
+    /** stable id = sha256(...).slice(0,16) per spec §12. */
+    id: string;
+    ruleId: string;
+    severity: Severity;
+    kind: ChangeKind;
+    /** Derived: severity === 'error'. Stored per spec §8. */
+    breaking: boolean;
+    location: ChangeLocation;
+    /** Human sentence, stable template. */
+    message: string;
+    /** Required for every change. */
+    suggestion: string;
+    /** Compact raw values (never full subtrees) for the JSON reporter. */
+    oldValue?: unknown;
+    newValue?: unknown;
+    /** True only when show-ignored rendering includes a suppressed change. */
+    ignored?: boolean;
+}
+interface DiffSummary {
+    total: number;
+    bySeverity: Record<Severity, number>;
+    byKind: Record<ChangeKind, number>;
+    /** Count of ignored changes (when show-ignored enabled). */
+    ignored: number;
+}
+interface SemverAdvice {
+    bump: 'major' | 'minor' | 'patch' | 'none';
+    reason: string;
+    triggers: string[];
+}
+
+/** Per-spec metadata used by reporters, per spec §8 DiffReport sides. */
+interface SpecMeta {
+    source: string;
+    openapiVersion: string;
+    title: string;
+    sha256: string;
+}
+/** Full diff report — the machine contract (§15.1). Field order matters. */
+interface DiffReport {
+    schemaVersion: '1.0';
+    tool: {
+        name: 'apiguard';
+        version: string;
+    };
+    baseline: SpecMeta;
+    current: SpecMeta;
+    summary: DiffSummary;
+    changes: ApiChange[];
+    semver: SemverAdvice;
+    /** Present only when show-ignored is enabled. */
+    ignored?: ApiChange[];
+}
+
+interface AnalyzeOptions {
+    /** Explicit config path; otherwise discovery per §14.1. */
+    configPath?: string;
+    /** Pre-resolved config (used by the Action); overrides configPath. */
+    config?: ResolvedConfig;
+    /** Show changes suppressed by ignore rules. */
+    showIgnored?: boolean;
+}
+interface AnalyzeResult {
+    report: DiffReport;
+    ignored: ApiChange[];
+}
+/** Run the full diff pipeline over two spec files. */
+declare function analyze(baselinePath: string, currentPath: string, options?: AnalyzeOptions): Promise<AnalyzeResult>;
+
+interface ValidationIssue {
+    /** Severity class of the issue. */
+    level: 'error' | 'warning';
+    /** e.g. "spec.yaml" — rendered as `file: message` (line when known). */
+    file: string;
+    message: string;
+}
+interface ValidationResult {
+    issues: ValidationIssue[];
+    /** true when no structural (level=error) issues were found. */
+    ok: boolean;
+}
+
+type JsonValue = unknown;
+/** Resolved spec bundle: parsed document plus provenance metadata. */
+interface LoadedSpec {
+    /** Parsed document as plain JSON-compatible data. */
+    document: JsonValue;
+    /** Human-readable source label (file path or ref), used in reports. */
+    source: string;
+    /** OpenAPI version string as declared in the document (e.g. "3.0.3", "3.1.0"); '' when absent. */
+    openapiVersion: string;
+    /** Document title or '' when absent. */
+    title: string;
+    /** sha256 hex digest of the normalized document bytes. */
+    sha256: string;
+}
+/** Internal representation of a normalized spec used by the diff engine. */
+interface NormalizedSpec extends LoadedSpec {
+    /** The normalized document (types as arrays, exclusiveMin/Max numeric, etc.). */
+    normalized: JsonValue;
+}
+
+interface LoadedConfig {
+    config: ResolvedConfig;
+    /** Path of the file the config came from ('' when defaults only). */
+    sourcePath: string;
+    /** Deprecation warnings collected during load (printed to stderr by the CLI). */
+    warnings: string[];
+}
+/** Load config from an explicit path (missing file → ConfigError, exit 2). */
+declare function loadConfigFrom(explicitPath: string): LoadedConfig;
+/** Discover config per §14.1; returns defaults when nothing is found. */
+declare function discoverAndLoadConfig(opts?: {
+    explicit?: string;
+    env?: string;
+    cwd?: string;
+}): LoadedConfig;
+
+/** Semver advisor per spec §16 — pure function over the change set. */
+
+/**
+ * Decision table (§16):
+ * 1. any error → major (reason lists top ruleIds by count)
+ * 2. else any addition|removal|modification OR any warning → minor
+ * 3. else any relaxation|documentation info → patch
+ * 4. else none
+ */
+declare function suggestVersion(changes: ApiChange[]): SemverAdvice;
+
+/** Public library API per spec §18. Pure; no stdout; no process.exit. */
+
+/**
+ * Load + validate a spec (§18 `validateSpec`). Throws SpecLoadError (exit-3 class) on
+ * structural problems; returns the semantic issue list otherwise.
+ */
+declare function validateSpec(specPath: string, options?: {
+    loader?: {
+        allowRemoteRefs?: boolean;
+    };
+}): Promise<{
+    spec: NormalizedSpec;
+    validation: ValidationResult;
+}>;
+
+export { type AnalyzeOptions, type AnalyzeResult, type ApiChange, type ChangeKind, type ChangeLocation, type Context, type DiffReport, type DiffSummary, type LoadedConfig, type LoadedSpec, type NormalizedSpec, type ResolvedConfig, type SemverAdvice, type Severity, type SpecMeta, type ValidationIssue, type ValidationResult, analyze, discoverAndLoadConfig, loadConfigFrom, suggestVersion, validateSpec };

package/dist/index.js

@@ -0,0 +1,22 @@
+import {
+  analyze,
+  discoverAndLoadConfig,
+  loadConfigFrom,
+  loadSpec,
+  suggestVersion,
+  validateSemantics
+} from "./chunk-RQVNHPHC.js";
+
+// src/index.ts
+async function validateSpec(specPath, options) {
+  const spec = await loadSpec(specPath, { loader: options?.loader });
+  const validation = validateSemantics(spec.document, specPath);
+  return { spec, validation };
+}
+export {
+  analyze,
+  discoverAndLoadConfig,
+  loadConfigFrom,
+  suggestVersion,
+  validateSpec
+};

package/dist/markdown-J2EC3VFS.js

@@ -0,0 +1,74 @@
+// src/reporters/markdown.ts
+var LABEL = {
+  error: "Breaking (errors)",
+  warning: "Warnings",
+  info: "Informational"
+};
+function truncate(s, max = 140) {
+  return s.length > max ? s.slice(0, max - 1) + "\u2026" : s;
+}
+function endpointOf(change) {
+  const loc = change.location;
+  if (loc.method) return `${loc.method} ${loc.path}`;
+  if (loc.path && loc.path !== "/") return loc.path;
+  if (loc.componentName) return loc.componentName;
+  return "API";
+}
+function renderMarkdown(report) {
+  const lines = [];
+  const breaking = report.summary.bySeverity.error;
+  lines.push(
+    breaking > 0 ? `## \u274C API Guard: ${breaking} breaking change${breaking === 1 ? "" : "s"} found` : "## \u2705 API Guard: no breaking changes"
+  );
+  lines.push("");
+  lines.push("| Rule | Severity | Endpoint | What changed | Suggestion |");
+  lines.push("|---|---|---|---|---|");
+  for (const c of report.changes) {
+    lines.push(
+      `| \`${c.ruleId}\` | ${c.severity} | ${endpointOf(c)} | ${truncate(c.message.replace(/\|/g, "\\|"))} | ${truncate(c.suggestion.replace(/\|/g, "\\|"))} |`
+    );
+  }
+  for (const sev of ["error", "warning", "info"]) {
+    const group = report.changes.filter((c) => c.severity === sev);
+    if (group.length === 0) continue;
+    lines.push("");
+    lines.push(`<details>`);
+    lines.push(`<summary>${LABEL[sev]} (${group.length})</summary>`);
+    lines.push("");
+    for (const c of group) {
+      lines.push(`#### \`${c.ruleId}\` \u2014 ${endpointOf(c)}`);
+      lines.push("");
+      lines.push(c.message);
+      lines.push("");
+      lines.push(`> **Suggestion:** ${c.suggestion}`);
+      lines.push("");
+    }
+    lines.push(`</details>`);
+  }
+  if (report.ignored && report.ignored.length > 0) {
+    lines.push("");
+    lines.push(`<details>`);
+    lines.push(`<summary>Ignored changes (${report.ignored.length})</summary>`);
+    lines.push("");
+    for (const c of report.ignored) {
+      lines.push(`- [ignored] \`${c.ruleId}\` \u2014 ${c.message}`);
+    }
+    lines.push("");
+    lines.push(`</details>`);
+  }
+  lines.push("");
+  lines.push(
+    `<sub>apiguard v${report.tool.version} \xB7 baseline ${report.baseline.sha256.slice(0, 8)} \u2192 current ${report.current.sha256.slice(0, 8)}</sub>`
+  );
+  return lines.join("\n");
+}
+function markdownBumpLine(report) {
+  const bump = report.semver.bump;
+  if (bump === "none") return null;
+  const label = bump === "major" ? "MAJOR" : bump === "minor" ? "MINOR" : "PATCH";
+  return `Suggested version bump: ${label}`;
+}
+export {
+  markdownBumpLine,
+  renderMarkdown
+};

package/package.json

@@ -0,0 +1,84 @@
+{
+  "name": "@subhamxcod/apiguard",
+  "version": "1.0.2",
+  "description": "Detect breaking changes between OpenAPI specifications (3.0 & 3.1) so API contracts never silently break downstream consumers.",
+  "type": "module",
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
+  "packageManager": "pnpm@12.3.4",
+  "publishConfig": {
+    "access": "public"
+  },
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "esbuild"
+    ]
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/subhamxaura/apiguard.git"
+  },
+  "bin": {
+    "apiguard": "./dist/cli/main.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "build:action": "esbuild src/github/action-entry.ts --bundle --platform=node --target=node20 --outfile=dist/index.cjs --minify",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "format:check": "prettier --check .",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:e2e": "vitest run --config vitest.e2e.config.ts",
+    "coverage": "vitest run --coverage",
+    "docs:rules": "tsx scripts/generate-rules-docs.ts",
+    "bench": "tsx scripts/bench.ts",
+    "gen-fixtures": "tsx scripts/gen-fixtures.ts"
+  },
+  "dependencies": {
+    "@actions/core": "^1.11.1",
+    "@actions/github": "^6.0.1",
+    "@apidevtools/swagger-parser": "^12.1.0",
+    "commander": "^14.0.2",
+    "micromatch": "^4.0.8",
+    "yaml": "^2.8.1",
+    "zod": "^4.1.13"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@semantic-release/changelog": "^7.0.0",
+    "@semantic-release/commit-analyzer": "^13.0.1",
+    "@semantic-release/exec": "^7.1.0",
+    "@semantic-release/git": "^11.0.1",
+    "@semantic-release/github": "^12.0.9",
+    "@semantic-release/npm": "^13.1.5",
+    "@semantic-release/release-notes-generator": "^14.1.1",
+    "@types/micromatch": "^4.0.10",
+    "@types/node": "^24.9.1",
+    "@vitest/coverage-v8": "^4.0.3",
+    "esbuild": "^0.27.0",
+    "eslint": "^9.39.0",
+    "eslint-config-prettier": "^10.1.8",
+    "prettier": "^3.6.2",
+    "semantic-release": "^25.0.9",
+    "tsup": "^8.5.0",
+    "tsx": "^4.20.6",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.46.2",
+    "vitest": "^4.0.3"
+  }
+}