@ojiepermana/angular 22.1.11 → 22.1.13

package/sdk/README.md

@@ -0,0 +1,212 @@
+# @ojiepermana/angular/sdk
+
+OpenAPI 3.x → Angular SDK generator for the `@ojiepermana/angular` design system.
+Source lives in [`library/sdk`](.); it ships as the `sdk` subpath of the single
+`@ojiepermana/angular` package, and its schematic collection is the package's own
+`ng add` / `ng generate` collection.
+
+It generates a **lightweight Angular SDK** from any OpenAPI 3.x spec (including 3.2.0):
+typed `HttpClient` services, tree-shakeable fn modules, optional metadata
+(permissions / validators), and a navigation tree.
+
+## What the published package exposes
+
+The package root exposes the **typed config surface** — the contract you author your
+`sdk.config.json` against — as an ESM Angular package-format entry point:
+
+```ts
+import {
+  resolveConfig,
+  resolveTarget,
+  type SdkConfig,
+  type SdkTargetConfig,
+  type SdkOutputMode,
+  type SdkFeatureFlags,
+} from '@ojiepermana/angular/sdk';
+```
+
+The same npm artifact also includes the compiled generator and its Angular schematic collection.
+The package root is ESM; only the internal `schematics/` and `src/` runtime trees are scoped as
+CommonJS so Angular DevKit can load their factories with `require()`.
+
+The source layout is:
+
+| Path                 | Role                                                                                             |
+| -------------------- | ------------------------------------------------------------------------------------------------ |
+| `src/config/`        | Config schema + loader (JSONC, `.js`/`.cjs`) — `resolveConfig` / `resolveTarget`                 |
+| `src/parser/`        | OpenAPI → intermediate representation (`bundle`, `ir`, `types`)                                  |
+| `src/emit/`          | One emitter per concern (models, operations, services, client, metadata, navigation, public-api) |
+| `src/layout/`        | Post-emit transforms (e.g. `per-domain` split-by-domain reorganisation)                          |
+| `src/render/`        | Template rendering                                                                               |
+| `src/writer/`        | Output-mode wrappers (standalone / library / secondary-entrypoint)                               |
+| `src/engine.ts`      | `generate(target, workspaceRoot)` — runs the full pipeline for one target                        |
+| `schematics/init/`   | Scaffolds `config/sdk.config.json` from [`sdk.config.example.json`](sdk.config.example.json)     |
+| `schematics/sdk/`    | Runs the generator and writes files into the Angular CLI `Tree`                                  |
+| `schematics/ng-add/` | `ng add` support — installs peer deps                                                            |
+| `bin/`               | Ignored build scratch for compiled `src/` + `schematics/`; copied into the package during build  |
+
+## Config shape
+
+A single config file drives one or more generation targets:
+
+```jsonc
+{
+  "targets": [
+    {
+      "input": "./openapi.yaml",
+      "output": "./sdk",
+      "mode": "library", // "standalone" | "library" | "secondary-entrypoint"
+      "clientName": "Api",
+      "packageName": "@my-scope/sdk", // used in "library" mode
+      "packageVersion": "0.0.1", // used in "library" mode
+      "rootUrl": "", // optional; empty string means same-origin requests
+      "splitByDomain": true, // optional; defaults true for "library", false otherwise
+      "splitDepth": "service", // "service" (default) | "tag"
+      "features": {
+        "models": true,
+        "operations": true,
+        "services": true,
+        "client": true,
+        "metadata": true,
+        "navigation": true,
+      },
+    },
+  ],
+}
+```
+
+Multiple targets are supported — one config run can emit several SDKs. See
+[`sdk.config.example.json`](sdk.config.example.json) for the canonical template the
+`init` schematic scaffolds.
+
+If `rootUrl` is omitted or left empty, the generated SDK uses same-origin requests by
+default. Consumer apps can override it at runtime with `provideApiConfiguration(...)`.
+
+### Runtime base URL
+
+The generated SDK does not read `sdk.config.json` at runtime. The value of
+`targets[].rootUrl` is only used during code generation to seed the default
+`ApiConfiguration.rootUrl` value.
+
+- `rootUrl: ""` or omitted: requests use the current origin, for example
+  `/api/users` on the same host as the Angular app.
+- `rootUrl: "https://api.example.com"`: the generated SDK defaults to that
+  absolute backend URL.
+- Runtime override: consumer apps can replace the default by providing a new
+  value during bootstrap.
+
+```ts
+import { bootstrapApplication } from '@angular/platform-browser';
+import { provideHttpClient } from '@angular/common/http';
+
+import { AppComponent } from './app/app.component';
+import { provideApiConfiguration } from '@my-scope/sdk';
+
+bootstrapApplication(AppComponent, {
+  providers: [provideHttpClient(), provideApiConfiguration('https://api.example.com')],
+});
+```
+
+For standalone generated output inside the same workspace, import
+`provideApiConfiguration` from the generated SDK barrel instead of an npm package path.
+
+## Output modes
+
+| Mode                   | What it emits                                                                                                                                                      | Use when…                                                                              |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------- |
+| `standalone`           | A plain folder (no `ng-package.json`).                                                                                                                             | You consume the SDK via path alias / `tsconfig.paths` inside the same app.             |
+| `library`              | Split-by-domain output plus package metadata and nested `ng-package.json` manifests for secondary entrypoints.                                                     | You want a buildable/publishable Angular package with efficient deep imports.          |
+| `secondary-entrypoint` | Standalone output **plus** a minimal `ng-package.json` pointing at `public-api.ts`, plus nested `ng-package.json` files for split-by-domain secondary entrypoints. | You drop the folder inside an existing library so ng-packagr picks it up as a subpath. |
+
+In `library` mode, output also includes `tsconfig.lib.json` and `tsconfig.lib.prod.json`.
+`ng-package.dest` defaults to `dist/<output-folder-name>`.
+
+## Per-domain layout
+
+By default, standalone and secondary-entrypoint targets emit a flat layout
+(`models/`, `fn/`, `services/`, … all at the output root). `mode: "library"`
+defaults to `splitByDomain: true` so the generated package is split into
+secondary entrypoints immediately. You can still set `splitByDomain: false` if
+you need the older flat library shape. Cross-domain models and client primitives
+land in `shared/`.
+
+`splitDepth` controls granularity. It is only read when `splitByDomain` is `true`.
+
+| `splitDepth` | Folder strategy                                                                                                  | Example (spec with tags `Access/Role`, `Access/Permission`, `Storage/GCS`, `Storage/S3`, `Auth`)                                         |
+| ------------ | ---------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| `service`    | One folder per **root** tag (each tag's `parent` chain collapses to its root). One folder per backend service.   | `access/` (holds Role + Permission + Role-Permission + …), `storage/` (holds GCS + S3), `auth/`, `shared/`, root `public-api.ts`         |
+| `tag`        | One folder per **leaf** tag, nested under the parent chain. Keeps fine-grained separation while staying grouped. | `access/role/`, `access/permission/`, `access/role-permission/`, `storage/gcs/`, `storage/s3/`, `auth/`, `shared/`, root `public-api.ts` |
+
+Every domain folder contains `services/`, `fn/`, `models/`, `permissions/`,
+and its own `public-api.ts`. The root still owns the aggregate metadata barrel:
+`metadata.ts`, `openapi-helpers.ts`, and `permissions/index.ts` stay at the SDK
+root so `shared/` never depends on sibling domains. In standalone and
+secondary-entrypoint modes, the root `public-api.ts` aggregates `shared`, root
+metadata helpers, and every domain for convenience. In library mode, domain
+exports stay in their secondary entrypoints so consumers deep import the domain
+they need.
+
+Model ownership rule (per-domain mode):
+
+- A model used by exactly one domain → emitted inside that domain's `models/`.
+- A model shared across two or more domains → emitted inside `shared/models/`.
+- Client primitives (`ApiConfiguration`, `BaseService`, `RequestBuilder`,
+  `StrictHttpResponse`, `Api`), shared metadata types, validators, and
+  navigation always live under `shared/`.
+- Aggregate metadata helpers (`metadata.ts`, `openapi-helpers.ts`) and the
+  top-level `permissions/index.ts` stay at the SDK root.
+
+Example consumption when using `mode: 'library'`:
+
+```ts
+import { RoleService } from '@my-scope/sdk/access';
+import { ApprovalInstanceService, SubmitRequest } from '@my-scope/sdk/approval';
+import { GCSService } from '@my-scope/sdk/storage'; // splitDepth: 'service'
+import { GCSService } from '@my-scope/sdk/storage/gcs'; // splitDepth: 'tag'
+```
+
+## Feature flags
+
+All default to `true`. Turn off anything you don't need to shrink the output.
+
+| Flag         | Emits                                                                                      |
+| ------------ | ------------------------------------------------------------------------------------------ |
+| `models`     | `models/*.ts` — flat interfaces, enum aliases, array aliases.                              |
+| `operations` | `fn/<tag>/<operation-id>.ts` — tree-shakeable request functions with `.PATH`.              |
+| `services`   | `services/<tag>.service.ts` — Angular 22 `@Service()` wrappers.                            |
+| `client`     | `api-configuration.ts`, `base-service.ts`, `request-builder.ts`, `api.ts`.                 |
+| `metadata`   | `permissions/*`, `validators/*`, `metadata.ts`, `openapi-helpers.ts`.                      |
+| `navigation` | `api.navigation.ts` — `NavigationItem[]` ready for `NavigationService.registerItems(...)`. |
+
+## Pipeline
+
+```text
+sdk.config.json → loader → spec (YAML/JSON) → IR → emitters → layout → writer → Angular CLI Tree
+```
+
+### Output ownership and safe cleanup
+
+Each generated output directory contains `.ojiepermana-sdk-manifest.json` with
+the relative files owned by the generator. A later run deletes stale files only
+when they were recorded in that manifest; unrelated source and documentation in
+the same directory are preserved.
+
+The schematic rejects output at the workspace root, outside the workspace, or
+inside `.git`/`node_modules`, and rejects absolute, traversing, duplicate, and
+reserved virtual paths. It also refuses to overwrite an unmanaged file whose
+content differs. On the first managed run, identical existing files are adopted;
+move conflicting manual files (or regenerate into a clean directory) before
+running again. Angular CLI `--dry-run` previews the complete Tree transaction.
+
+## Generated runtime conventions
+
+- Tree-shakeable: `import { listUsers } from './sdk/fn/user/list-users'` pulls only one HTTP call.
+- Services: every operation gets `op()` (body `Observable<T>`) and `op$Response()` (full `StrictHttpResponse<T>`).
+- `RequestBuilder` is intentionally minimal — no `style`/`explode` logic — to keep the output lightweight.
+- All files carry a `DO NOT EDIT` banner and `/* eslint-disable */`.
+
+## Support and security
+
+The SDK follows the Node engine range in its package manifest and targets Angular 22 output. See
+the bundled `SUPPORT.md`. Report suspected vulnerabilities privately using the instructions in the
+bundled `SECURITY.md`. This package is MIT licensed; see the bundled `LICENSE`.

package/sdk/schematics/collection.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "../../../node_modules/@angular-devkit/schematics/collection-schema.json",
+  "schematics": {
+    "ng-add": {
+      "factory": "./ng-add/index#ngAdd",
+      "schema": "./ng-add/schema.json",
+      "description": "Install @ojiepermana/angular/sdk and align its peer dependencies."
+    },
+    "init": {
+      "factory": "./init/index#init",
+      "schema": "./init/schema.json",
+      "description": "Create an sdk.config.json at the workspace root."
+    },
+    "sdk": {
+      "factory": "./sdk/index#sdk",
+      "schema": "./sdk/schema.json",
+      "description": "Generate an Angular SDK from an OpenAPI spec using sdk.config.json."
+    }
+  }
+}

package/sdk/schematics/init/index.js

@@ -0,0 +1,83 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.init = init;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const SCHEMA_MODULE_PATH = 'node_modules/@ojiepermana/angular/sdk/schematics/sdk/schema.json';
+const NEXT_COMMAND = 'ng generate @ojiepermana/angular:sdk';
+/**
+ * Default config template. The published package also ships a concrete
+ * `sdk.config.example.json`; this fallback only exists so `init` still works if
+ * the file is missing in unusual local/dev states.
+ */
+const FALLBACK_TEMPLATE = {
+    $schema: `./${SCHEMA_MODULE_PATH}`,
+    targets: [
+        {
+            input: './openapi.yaml',
+            output: './sdk',
+            mode: 'library',
+            clientName: 'Api',
+            packageName: '@my-scope/sdk',
+            packageVersion: '0.0.1',
+            rootUrl: '',
+            splitByDomain: true,
+            splitDepth: 'service',
+            features: {
+                models: true,
+                operations: true,
+                services: true,
+                client: true,
+                metadata: true,
+                navigation: true,
+            },
+        },
+    ],
+};
+function init(options = {}) {
+    return (tree, context) => {
+        const workspaceRoot = process.cwd();
+        const destRelative = options.path ?? 'config/sdk.config.json';
+        const treePath = destRelative.startsWith('/') ? destRelative : `/${destRelative}`;
+        if (tree.exists(treePath) && !options.force) {
+            throw new Error(`${destRelative} already exists. Re-run with --force to overwrite.`);
+        }
+        const content = loadTemplate(workspaceRoot, destRelative);
+        const buffer = Buffer.from(content, 'utf8');
+        if (tree.exists(treePath)) {
+            tree.overwrite(treePath, buffer);
+            context.logger.info(`[sdk:init] overwrote ${destRelative}`);
+        }
+        else {
+            tree.create(treePath, buffer);
+            context.logger.info(`[sdk:init] created ${destRelative}`);
+        }
+        context.logger.info(`[sdk:init] edit targets[].input and targets[].output, then run \`${NEXT_COMMAND}\`.`);
+    };
+}
+function loadTemplate(workspaceRoot, destRelative) {
+    const candidates = [
+        (0, node_path_1.resolve)(workspaceRoot, 'sdk.config.example.json'),
+        // The published package keeps the example at its root, two levels above
+        // `schematics/init/`.
+        (0, node_path_1.resolve)(__dirname, '../../sdk.config.example.json'),
+    ];
+    for (const candidate of candidates) {
+        try {
+            const parsed = JSON.parse((0, node_fs_1.readFileSync)(candidate, 'utf8'));
+            parsed['$schema'] = resolveSchemaPath(destRelative);
+            return `${JSON.stringify(parsed, null, 2)}\n`;
+        }
+        catch {
+            // try next
+        }
+    }
+    return `${JSON.stringify({ ...FALLBACK_TEMPLATE, $schema: resolveSchemaPath(destRelative) }, null, 2)}\n`;
+}
+function resolveSchemaPath(destRelative) {
+    return `${relativePrefix(destRelative)}${SCHEMA_MODULE_PATH}`;
+}
+function relativePrefix(destRelative) {
+    const depth = destRelative.replace(/^\/+/, '').split('/').length - 1;
+    return depth <= 0 ? './' : '../'.repeat(depth);
+}

package/sdk/schematics/init/schema.json

@@ -0,0 +1,19 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema",
+  "$id": "SdkInitSchema",
+  "title": "Initialize SDK generator config",
+  "type": "object",
+  "properties": {
+    "path": {
+      "type": "string",
+      "description": "Path (relative to workspace root) where the config file will be created.",
+      "default": "config/sdk.config.json"
+    },
+    "force": {
+      "type": "boolean",
+      "description": "Overwrite the file if it already exists.",
+      "default": false
+    }
+  },
+  "required": []
+}

package/sdk/schematics/ng-add/index.js

@@ -0,0 +1,147 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ngAdd = ngAdd;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const tasks_1 = require("@angular-devkit/schematics/tasks");
+const semver_1 = require("semver");
+function ngAdd(options = {}) {
+    return (tree, context) => {
+        const manifest = loadLibraryManifest();
+        const requiredDependencies = collectRequiredDependencies(manifest);
+        if (requiredDependencies.length === 0) {
+            context.logger.warn('[ng-add] @ojiepermana/angular declares no peer dependencies.');
+            return;
+        }
+        const workspacePackageJson = readWorkspacePackageJson(tree);
+        workspacePackageJson.dependencies ??= {};
+        let changed = false;
+        for (const dependency of requiredDependencies) {
+            const existingDependency = findExistingDependency(workspacePackageJson, dependency.name);
+            if (existingDependency) {
+                if (shouldUpdateDependency(existingDependency.version, dependency.version)) {
+                    const section = workspacePackageJson[existingDependency.section] ?? {};
+                    section[dependency.name] = dependency.version;
+                    workspacePackageJson[existingDependency.section] = section;
+                    changed = true;
+                    context.logger.info(`[ng-add] updated ${dependency.name} from ${existingDependency.version} to ${dependency.version} in ${existingDependency.section}.`);
+                }
+                else {
+                    context.logger.info(`[ng-add] keeping existing ${dependency.name}@${existingDependency.version} from ${existingDependency.section}.`);
+                }
+                continue;
+            }
+            workspacePackageJson.dependencies[dependency.name] = dependency.version;
+            changed = true;
+            context.logger.info(`[ng-add] added ${dependency.name}@${dependency.version}.`);
+        }
+        if (!changed) {
+            context.logger.info('[ng-add] Required dependencies are already present.');
+            return;
+        }
+        workspacePackageJson.dependencies = sortSection(workspacePackageJson.dependencies);
+        writeWorkspacePackageJson(tree, workspacePackageJson);
+        if (!options.skipInstall) {
+            context.addTask(new tasks_1.NodePackageInstallTask());
+        }
+    };
+}
+/**
+ * Use the package manifest as the source of truth so ng-add stays aligned with
+ * the published peerDependencies and ng-update packageGroup metadata.
+ */
+function loadLibraryManifest() {
+    // Walk up from the compiled schematic (…/<pkg>/sdk/schematics/ng-add/) to the
+    // package root. ng-packagr also drops a `module`/`typings` stub manifest into
+    // every entry point directory, so the walk skips any manifest without a
+    // `name` and stops at the real package manifest.
+    for (const candidate of ancestorManifests(__dirname)) {
+        const manifest = JSON.parse((0, node_fs_1.readFileSync)(candidate, 'utf8'));
+        if (typeof manifest.name === 'string')
+            return manifest;
+    }
+    const workspaceManifest = (0, node_path_1.resolve)(process.cwd(), 'node_modules/@ojiepermana/angular/package.json');
+    if ((0, node_fs_1.existsSync)(workspaceManifest)) {
+        return JSON.parse((0, node_fs_1.readFileSync)(workspaceManifest, 'utf8'));
+    }
+    throw new Error('Could not locate the @ojiepermana/angular package manifest for ng-add.');
+}
+function ancestorManifests(from) {
+    const manifests = [];
+    let directory = from;
+    for (;;) {
+        const candidate = (0, node_path_1.resolve)(directory, 'package.json');
+        if ((0, node_fs_1.existsSync)(candidate))
+            manifests.push(candidate);
+        const parent = (0, node_path_1.dirname)(directory);
+        if (parent === directory)
+            return manifests;
+        directory = parent;
+    }
+}
+function collectRequiredDependencies(manifest) {
+    const peerDependencies = manifest.peerDependencies ?? {};
+    const packageGroup = normalizePackageGroup(manifest['ng-update']?.packageGroup);
+    return Object.keys(peerDependencies)
+        .sort((left, right) => left.localeCompare(right))
+        .map((name) => ({
+        name,
+        version: packageGroup[name] ?? peerDependencies[name],
+    }));
+}
+function normalizePackageGroup(packageGroup) {
+    if (!packageGroup) {
+        return {};
+    }
+    if (Array.isArray(packageGroup)) {
+        return {};
+    }
+    return packageGroup;
+}
+function readWorkspacePackageJson(tree) {
+    const buffer = tree.read('/package.json');
+    if (!buffer) {
+        throw new Error('No package.json found at the workspace root.');
+    }
+    return JSON.parse(buffer.toString('utf8'));
+}
+function writeWorkspacePackageJson(tree, packageJson) {
+    const content = `${JSON.stringify(packageJson, null, 2)}\n`;
+    if (tree.exists('/package.json')) {
+        tree.overwrite('/package.json', content);
+    }
+    else {
+        tree.create('/package.json', content);
+    }
+}
+function findExistingDependency(packageJson, dependencyName) {
+    const sections = [
+        'dependencies',
+        'devDependencies',
+        'peerDependencies',
+        'optionalDependencies',
+    ];
+    for (const section of sections) {
+        const version = packageJson[section]?.[dependencyName];
+        if (version) {
+            return { section, version };
+        }
+    }
+    return null;
+}
+function shouldUpdateDependency(existingVersion, requiredVersion) {
+    const existing = (0, semver_1.validRange)(existingVersion);
+    const required = (0, semver_1.validRange)(requiredVersion);
+    if (!existing || !required) {
+        return false;
+    }
+    const existingMinimum = (0, semver_1.minVersion)(existing);
+    const requiredMinimum = (0, semver_1.minVersion)(required);
+    if (!existingMinimum || !requiredMinimum) {
+        return false;
+    }
+    return existingMinimum.compare(requiredMinimum) < 0;
+}
+function sortSection(section) {
+    return Object.fromEntries(Object.entries(section).sort(([left], [right]) => left.localeCompare(right)));
+}

package/sdk/schematics/ng-add/schema.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "http://json-schema.org/schema",
+  "$id": "NgAddSchema",
+  "title": "@ojiepermana/angular ng-add options",
+  "type": "object",
+  "properties": {
+    "skipInstall": {
+      "type": "boolean",
+      "default": false,
+      "description": "Skip installing dependencies after updating package.json."
+    }
+  },
+  "additionalProperties": false
+}

package/sdk/schematics/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}