@ir-kit/codegen-core 0.1.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Ahmed Rowaihi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,54 @@
+# `@ir-kit/codegen-core`
+
+Spec-agnostic codegen primitives shared by every native-SDK generator family — identifier transforms (`pascal`, `camel`, `safeIdent`, `safeCaseName`, `softCamel`, `synthName`, `avoidLeadingDigit`, `escapeIfReserved`), filesystem safety (`assertSafeOutputDir`), and project-name derivation (`defaultProjectName`). Pure functions, no spec dependencies.
+
+## Install
+
+```sh
+npm install @ir-kit/codegen-core
+```
+
+Zero runtime dependencies.
+
+## Identifier helpers
+
+```ts
+import {
+  avoidLeadingDigit,
+  camel,
+  escapeIfReserved,
+  pascal,
+  safeCaseName,
+  safeIdent,
+  softCamel,
+  synthName,
+} from "@ir-kit/codegen-core";
+
+pascal("first_name");     // "FirstName"
+camel("first_name");      // "firstName"
+softCamel("FirstName");   // "FirstName"  (preserves first-letter casing)
+camel("FirstName");       // "firstName"  (lowercases first letter)
+safeIdent("2024_release"); // "_2024Release"  (digit guard + pascal)
+safeCaseName("4xx");      // "_4xx"
+synthName("User", ["Address", "Street"]);   // "User_Address_Street"
+
+avoidLeadingDigit("2value");                // "_2value"
+escapeIfReserved("class", new Set(["class"]), (s) => `\`${s}\``);  // "`class`"
+```
+
+## Filesystem helpers
+
+```ts
+import { assertSafeOutputDir, defaultProjectName } from "@ir-kit/codegen-core";
+
+assertSafeOutputDir("./out/sdk");           // throws if outside CWD or in . / ..
+defaultProjectName("./out/petstore-sdk");   // "petstore-sdk"
+```
+
+## Status
+
+`0.1.0` — first release under the `@ir-kit/*` scope. Replaces the legacy `@ahmedrowaihi/codegen-core` (deprecated).
+
+## Repo
+
+Source at [ir-kit/ir-kit](https://github.com/ir-kit/ir-kit/tree/main/packages/shared/codegen-core).

package/dist/fs.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Refuse to wipe the current working directory or a filesystem root.
+ * `clean: true` runs `rm -rf` on the resolved output directory at the
+ * start of `generate()`, which would destroy the user's repo if they
+ * pointed `output` at `.` or `/`. Cheap guardrail with no false
+ * positives — generators always want output under a dedicated subdir.
+ */
+export declare function assertSafeOutputDir(out: string): void;
+/**
+ * Derive a project name from the output directory's basename, with
+ * non-alphanumerics collapsed to dashes. Used as the fallback for
+ * Gradle's `rootProject.name` / SwiftPM `Package(name:)` /
+ * `module name` defaults. Empty result (e.g. output is `/`) falls
+ * back to the literal `"generated-sdk"` so the build files always
+ * have a valid name slot.
+ */
+export declare function defaultProjectName(outputDir: string): string;
+//# sourceMappingURL=fs.d.ts.map

package/dist/fs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs.d.ts","sourceRoot":"","sources":["../src/fs.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAMrD;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAG5D"}

package/dist/fs.js

@@ -0,0 +1,26 @@
+import { basename, parse as parsePath } from "node:path";
+/**
+ * Refuse to wipe the current working directory or a filesystem root.
+ * `clean: true` runs `rm -rf` on the resolved output directory at the
+ * start of `generate()`, which would destroy the user's repo if they
+ * pointed `output` at `.` or `/`. Cheap guardrail with no false
+ * positives — generators always want output under a dedicated subdir.
+ */
+export function assertSafeOutputDir(out) {
+    if (out === process.cwd() || out === parsePath(out).root) {
+        throw new Error(`Refusing to clean output directory: ${out} (would wipe cwd or filesystem root). Use a dedicated subdirectory.`);
+    }
+}
+/**
+ * Derive a project name from the output directory's basename, with
+ * non-alphanumerics collapsed to dashes. Used as the fallback for
+ * Gradle's `rootProject.name` / SwiftPM `Package(name:)` /
+ * `module name` defaults. Empty result (e.g. output is `/`) falls
+ * back to the literal `"generated-sdk"` so the build files always
+ * have a valid name slot.
+ */
+export function defaultProjectName(outputDir) {
+    const base = basename(outputDir).replace(/[^A-Za-z0-9-]+/g, "-");
+    return base || "generated-sdk";
+}
+//# sourceMappingURL=fs.js.map

package/dist/fs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs.js","sourceRoot":"","sources":["../src/fs.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,KAAK,IAAI,SAAS,EAAE,MAAM,WAAW,CAAC;AAEzD;;;;;;GAMG;AACH,MAAM,UAAU,mBAAmB,CAAC,GAAW;IAC7C,IAAI,GAAG,KAAK,OAAO,CAAC,GAAG,EAAE,IAAI,GAAG,KAAK,SAAS,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;QACzD,MAAM,IAAI,KAAK,CACb,uCAAuC,GAAG,qEAAqE,CAChH,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,kBAAkB,CAAC,SAAiB;IAClD,MAAM,IAAI,GAAG,QAAQ,CAAC,SAAS,CAAC,CAAC,OAAO,CAAC,iBAAiB,EAAE,GAAG,CAAC,CAAC;IACjE,OAAO,IAAI,IAAI,eAAe,CAAC;AACjC,CAAC"}

package/dist/identifiers.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Identifier transforms shared by every native-SDK generator. All
+ * functions here are pure string ↔ string — they do *not* know about
+ * any target language's reserved-word set or visibility rules. Each
+ * generator layers its own `paramIdent` / `exportedIdent` /
+ * `enumEntryIdent` on top, calling these as primitives.
+ *
+ * The pascal regex deliberately strips both leading and trailing
+ * non-alphanumeric runs so identifiers like `timeframe[]` (PHP-style
+ * array param names from real-world specs) become `Timeframe`, not
+ * `TimeframeNullNull` or similar. Wire-level names are unaffected —
+ * generators preserve the original param.name when emitting the URL.
+ */
+export declare function pascal(s: string): string;
+export declare function camel(s: string): string;
+/** PascalCase, prepended with `_` if it would otherwise start with a
+ *  digit. Used wherever a type-name slot can't begin with a number. */
+export declare function safeIdent(s: string): string;
+/** camelCase, prepended with `_` if it would otherwise start with a
+ *  digit. Used for enum case names where the source is numeric. */
+export declare function safeCaseName(s: string): string;
+/**
+ * Camel-like transform that PRESERVES the first character's casing —
+ * collapses non-alnum word boundaries and uppercases the following
+ * character. Diverges from `camel()` in that it does NOT lowercase
+ * the leading letter, so `softCamel("FirstName")` stays `"FirstName"`
+ * while `camel("FirstName")` returns `"firstName"`. Used by emitters
+ * that want to respect user-given casing on parameter identifiers
+ * while still normalising word boundaries (snake_case → camelCase but
+ * already-cased inputs pass through).
+ */
+export declare function softCamel(s: string): string;
+/** Prepend `_` when the string would otherwise start with a digit;
+ *  pass through unchanged otherwise. Most identifier-safe transforms
+ *  end with this guard. */
+export declare function avoidLeadingDigit(s: string): string;
+/** Wrap a name through a target-specific escape iff it collides with
+ *  the target's reserved-keyword set. Centralises the
+ *  `RESERVED.has(name) ? escape(name) : name` pattern each emitter's
+ *  `paramIdent` open-coded. */
+export declare function escapeIfReserved(name: string, reserved: ReadonlySet<string>, escape: (name: string) => string): string;
+/**
+ * Build a synthetic top-level type name for an inline schema, owned
+ * by some declared type. The owner part stays as-is so collisions
+ * across owners are impossible (`User_Address` vs `Order_Address`).
+ * Path segments get pascal'd individually so `["properties","streetName"]`
+ * collapses to `User_Properties_StreetName` rather than running the
+ * pascal regex over the joined string.
+ */
+export declare function synthName(owner: string, path: ReadonlyArray<string>): string;
+//# sourceMappingURL=identifiers.d.ts.map

package/dist/identifiers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identifiers.d.ts","sourceRoot":"","sources":["../src/identifiers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAMxC;AAED,wBAAgB,KAAK,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAGvC;AAED;uEACuE;AACvE,wBAAgB,SAAS,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAE3C;AAED;mEACmE;AACnE,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAE9C;AAED;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAE3C;AAED;;2BAE2B;AAC3B,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED;;;+BAG+B;AAC/B,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,WAAW,CAAC,MAAM,CAAC,EAC7B,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GAC/B,MAAM,CAER;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,MAAM,CAE5E"}

package/dist/identifiers.js

@@ -0,0 +1,72 @@
+/**
+ * Identifier transforms shared by every native-SDK generator. All
+ * functions here are pure string ↔ string — they do *not* know about
+ * any target language's reserved-word set or visibility rules. Each
+ * generator layers its own `paramIdent` / `exportedIdent` /
+ * `enumEntryIdent` on top, calling these as primitives.
+ *
+ * The pascal regex deliberately strips both leading and trailing
+ * non-alphanumeric runs so identifiers like `timeframe[]` (PHP-style
+ * array param names from real-world specs) become `Timeframe`, not
+ * `TimeframeNullNull` or similar. Wire-level names are unaffected —
+ * generators preserve the original param.name when emitting the URL.
+ */
+export function pascal(s) {
+    return s
+        .replace(/^[^a-zA-Z0-9]+/, "")
+        .replace(/[^a-zA-Z0-9]+$/, "")
+        .replace(/[^a-zA-Z0-9]+(.)/g, (_, c) => c.toUpperCase())
+        .replace(/^./, (c) => c.toUpperCase());
+}
+export function camel(s) {
+    const p = pascal(s);
+    return p.length > 0 ? p[0].toLowerCase() + p.slice(1) : p;
+}
+/** PascalCase, prepended with `_` if it would otherwise start with a
+ *  digit. Used wherever a type-name slot can't begin with a number. */
+export function safeIdent(s) {
+    return avoidLeadingDigit(pascal(s));
+}
+/** camelCase, prepended with `_` if it would otherwise start with a
+ *  digit. Used for enum case names where the source is numeric. */
+export function safeCaseName(s) {
+    return avoidLeadingDigit(camel(s));
+}
+/**
+ * Camel-like transform that PRESERVES the first character's casing —
+ * collapses non-alnum word boundaries and uppercases the following
+ * character. Diverges from `camel()` in that it does NOT lowercase
+ * the leading letter, so `softCamel("FirstName")` stays `"FirstName"`
+ * while `camel("FirstName")` returns `"firstName"`. Used by emitters
+ * that want to respect user-given casing on parameter identifiers
+ * while still normalising word boundaries (snake_case → camelCase but
+ * already-cased inputs pass through).
+ */
+export function softCamel(s) {
+    return s.replace(/[^a-zA-Z0-9]+(.)/g, (_, c) => c.toUpperCase());
+}
+/** Prepend `_` when the string would otherwise start with a digit;
+ *  pass through unchanged otherwise. Most identifier-safe transforms
+ *  end with this guard. */
+export function avoidLeadingDigit(s) {
+    return /^[0-9]/.test(s) ? `_${s}` : s;
+}
+/** Wrap a name through a target-specific escape iff it collides with
+ *  the target's reserved-keyword set. Centralises the
+ *  `RESERVED.has(name) ? escape(name) : name` pattern each emitter's
+ *  `paramIdent` open-coded. */
+export function escapeIfReserved(name, reserved, escape) {
+    return reserved.has(name) ? escape(name) : name;
+}
+/**
+ * Build a synthetic top-level type name for an inline schema, owned
+ * by some declared type. The owner part stays as-is so collisions
+ * across owners are impossible (`User_Address` vs `Order_Address`).
+ * Path segments get pascal'd individually so `["properties","streetName"]`
+ * collapses to `User_Properties_StreetName` rather than running the
+ * pascal regex over the joined string.
+ */
+export function synthName(owner, path) {
+    return [owner, ...path.map(pascal)].join("_");
+}
+//# sourceMappingURL=identifiers.js.map

package/dist/identifiers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"identifiers.js","sourceRoot":"","sources":["../src/identifiers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,MAAM,CAAC,CAAS;IAC9B,OAAO,CAAC;SACL,OAAO,CAAC,gBAAgB,EAAE,EAAE,CAAC;SAC7B,OAAO,CAAC,gBAAgB,EAAE,EAAE,CAAC;SAC7B,OAAO,CAAC,mBAAmB,EAAE,CAAC,CAAC,EAAE,CAAS,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC;SAC/D,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC;AAC3C,CAAC;AAED,MAAM,UAAU,KAAK,CAAC,CAAS;IAC7B,MAAM,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;IACpB,OAAO,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAE,CAAC,WAAW,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAC7D,CAAC;AAED;uEACuE;AACvE,MAAM,UAAU,SAAS,CAAC,CAAS;IACjC,OAAO,iBAAiB,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;AACtC,CAAC;AAED;mEACmE;AACnE,MAAM,UAAU,YAAY,CAAC,CAAS;IACpC,OAAO,iBAAiB,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;AACrC,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,SAAS,CAAC,CAAS;IACjC,OAAO,CAAC,CAAC,OAAO,CAAC,mBAAmB,EAAE,CAAC,CAAC,EAAE,CAAS,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC;AAC3E,CAAC;AAED;;2BAE2B;AAC3B,MAAM,UAAU,iBAAiB,CAAC,CAAS;IACzC,OAAO,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;AACxC,CAAC;AAED;;;+BAG+B;AAC/B,MAAM,UAAU,gBAAgB,CAC9B,IAAY,EACZ,QAA6B,EAC7B,MAAgC;IAEhC,OAAO,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;AAClD,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,SAAS,CAAC,KAAa,EAAE,IAA2B;IAClE,OAAO,CAAC,KAAK,EAAE,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAChD,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { assertSafeOutputDir, defaultProjectName } from "./fs.js";
+export { avoidLeadingDigit, camel, escapeIfReserved, pascal, safeCaseName, safeIdent, softCamel, synthName, } from "./identifiers.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAClE,OAAO,EACL,iBAAiB,EACjB,KAAK,EACL,gBAAgB,EAChB,MAAM,EACN,YAAY,EACZ,SAAS,EACT,SAAS,EACT,SAAS,GACV,MAAM,kBAAkB,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export { assertSafeOutputDir, defaultProjectName } from "./fs.js";
+export { avoidLeadingDigit, camel, escapeIfReserved, pascal, safeCaseName, safeIdent, softCamel, synthName, } from "./identifiers.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAClE,OAAO,EACL,iBAAiB,EACjB,KAAK,EACL,gBAAgB,EAChB,MAAM,EACN,YAAY,EACZ,SAAS,EACT,SAAS,EACT,SAAS,GACV,MAAM,kBAAkB,CAAC"}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@ir-kit/codegen-core",
+  "version": "0.1.0",
+  "description": "Spec-agnostic codegen primitives shared by OpenAPI and AsyncAPI generator families — identifier transforms (pascal/camel/safeIdent), filesystem safety, project-name derivation. Pure functions, no spec dependencies.",
+  "keywords": [
+    "codegen",
+    "openapi",
+    "asyncapi",
+    "sdk",
+    "shared",
+    "identifiers"
+  ],
+  "homepage": "https://github.com/ir-kit/ir-kit/tree/main/packages/shared/codegen-core",
+  "bugs": {
+    "url": "https://github.com/ir-kit/ir-kit/issues"
+  },
+  "license": "MIT",
+  "author": {
+    "name": "Ahmed Rowaihi",
+    "email": "ahmedrowaihi@gmail.com"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ir-kit/ir-kit.git",
+    "directory": "packages/shared/codegen-core"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "LICENSE.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "devDependencies": {
+    "@types/node": "^22",
+    "vitest": "^4.0.0",
+    "@ir-kit/tsconfig": "0.0.0"
+  },
+  "engines": {
+    "node": ">=20.19.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "dev": "tsc -p tsconfig.build.json --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests"
+  }
+}