@ojiepermana/angular 21.0.0 → 21.0.2

package/generator/api/bin/src/parser/ir.js

@@ -0,0 +1,320 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildIR = buildIR;
+const HTTP_METHODS = ['get', 'post', 'put', 'patch', 'delete', 'head', 'options'];
+/**
+ * Build the Intermediate Representation from a bundled OpenAPI document.
+ *
+ * Expectations about input:
+ *  - `$ref` strings in the form `#/components/schemas/<Name>` (or parameters).
+ *  - OpenAPI 3.0.x / 3.1.x / 3.2.x (nullable via `type: ['string', 'null']` or
+ *    `nullable: true`).
+ */
+function buildIR(doc) {
+    const info = doc.info ?? {};
+    const servers = Array.isArray(doc.servers)
+        ? doc.servers.map((s) => ({ url: String(s.url ?? ''), description: s.description }))
+        : [];
+    const tags = Array.isArray(doc.tags)
+        ? doc.tags.map((t) => ({
+            name: String(t.name),
+            parent: t.parent,
+            kind: t.kind,
+            xIcon: t['x-icon'],
+            description: t.description,
+        }))
+        : [];
+    const schemas = buildSchemas(doc.components?.schemas);
+    const operations = buildOperations(doc.paths, doc.components?.parameters);
+    const security = buildSecuritySchemes(doc.components?.securitySchemes);
+    return {
+        title: String(info.title ?? 'API'),
+        version: String(info.version ?? '0.0.0'),
+        description: info.description,
+        servers,
+        tags,
+        navigation: buildNavigation(tags),
+        schemas,
+        operations,
+        security,
+    };
+}
+// ---------------------------------------------------------------------------
+// Schemas
+// ---------------------------------------------------------------------------
+function buildSchemas(rawSchemas) {
+    if (!rawSchemas)
+        return [];
+    const names = Object.keys(rawSchemas).sort();
+    return names.map((name) => buildSchema(name, rawSchemas[name]));
+}
+function buildSchema(name, raw) {
+    const required = Array.isArray(raw?.required) ? raw.required.slice() : [];
+    const properties = {};
+    // allOf — merge inline: fold each `properties` + required lists into the parent.
+    const parts = Array.isArray(raw?.allOf) ? raw.allOf : [];
+    const mergedProps = { ...(raw?.properties ?? {}) };
+    for (const part of parts) {
+        if (part?.properties)
+            Object.assign(mergedProps, part.properties);
+        if (Array.isArray(part?.required)) {
+            for (const r of part.required)
+                if (!required.includes(r))
+                    required.push(r);
+        }
+    }
+    for (const [propName, propSchema] of Object.entries(mergedProps)) {
+        properties[propName] = buildFieldRule(propSchema, required.includes(propName));
+    }
+    // Primitive enum schemas → emit as alias.
+    const primitiveType = resolvePrimitiveType(raw);
+    if (primitiveType && Array.isArray(raw?.enum)) {
+        return {
+            name,
+            description: raw?.description,
+            required: [],
+            properties: {},
+            enumValues: raw.enum,
+        };
+    }
+    // Array alias schemas.
+    if (resolvedTypeIs(raw, 'array') && raw?.items) {
+        const itemRef = refName(raw.items?.$ref);
+        const itemType = itemRef ? undefined : resolvePrimitiveType(raw.items);
+        return {
+            name,
+            description: raw?.description,
+            required: [],
+            properties: {},
+            arrayItemRef: itemRef ?? undefined,
+            arrayItemType: itemType ?? undefined,
+        };
+    }
+    return {
+        name,
+        description: raw?.description,
+        required,
+        properties,
+    };
+}
+function buildFieldRule(raw, required) {
+    const rule = { required };
+    // $ref → named reference.
+    const ref = refName(raw?.$ref);
+    if (ref) {
+        rule.ref = ref;
+        return rule;
+    }
+    // Array with items.
+    if (resolvedTypeIs(raw, 'array') && raw?.items) {
+        rule.type = 'array';
+        const itemsRef = refName(raw.items?.$ref);
+        if (itemsRef)
+            rule.itemsRef = itemsRef;
+        else
+            rule.itemsType = resolvePrimitiveType(raw.items) ?? 'unknown';
+        const itemEnum = raw.items?.enum;
+        if (Array.isArray(itemEnum))
+            rule.enumValues = itemEnum;
+        if (raw.description)
+            rule.description = raw.description;
+        rule.nullable = isNullable(raw);
+        return rule;
+    }
+    // Primitive / object.
+    rule.type = resolvePrimitiveType(raw) ?? 'unknown';
+    rule.nullable = isNullable(raw);
+    if (raw?.format)
+        rule.format = raw.format;
+    if (raw?.description)
+        rule.description = raw.description;
+    if (typeof raw?.minLength === 'number')
+        rule.minLength = raw.minLength;
+    if (typeof raw?.maxLength === 'number')
+        rule.maxLength = raw.maxLength;
+    if (typeof raw?.minimum === 'number')
+        rule.minimum = raw.minimum;
+    if (typeof raw?.maximum === 'number')
+        rule.maximum = raw.maximum;
+    if (typeof raw?.pattern === 'string')
+        rule.pattern = raw.pattern;
+    if (Array.isArray(raw?.enum))
+        rule.enumValues = raw.enum;
+    return rule;
+}
+function resolvePrimitiveType(raw) {
+    if (!raw)
+        return undefined;
+    const t = raw.type;
+    if (Array.isArray(t)) {
+        const nonNull = t.find((x) => x !== 'null');
+        return nonNull ?? undefined;
+    }
+    if (typeof t === 'string')
+        return t;
+    return undefined;
+}
+function resolvedTypeIs(raw, target) {
+    return resolvePrimitiveType(raw) === target;
+}
+function isNullable(raw) {
+    if (raw?.nullable === true)
+        return true;
+    const t = raw?.type;
+    if (Array.isArray(t) && t.includes('null'))
+        return true;
+    return false;
+}
+function refName(ref) {
+    if (typeof ref !== 'string')
+        return undefined;
+    const idx = ref.lastIndexOf('/');
+    return idx >= 0 ? ref.slice(idx + 1) : ref;
+}
+// ---------------------------------------------------------------------------
+// Operations
+// ---------------------------------------------------------------------------
+function buildOperations(paths, sharedParams) {
+    if (!paths)
+        return [];
+    const operations = [];
+    for (const [pathKey, pathItem] of Object.entries(paths)) {
+        if (!pathItem || typeof pathItem !== 'object')
+            continue;
+        const pathLevelParams = Array.isArray(pathItem.parameters) ? pathItem.parameters : [];
+        for (const method of HTTP_METHODS) {
+            const op = pathItem[method];
+            if (!op)
+                continue;
+            operations.push(buildOperation(pathKey, method, op, pathLevelParams, sharedParams));
+        }
+    }
+    return operations.sort((a, b) => a.operationId.localeCompare(b.operationId));
+}
+function buildOperation(path, method, op, pathLevelParams, sharedParams) {
+    const tags = Array.isArray(op.tags) && op.tags.length ? op.tags.map(String) : ['Default'];
+    const params = mergeParams(pathLevelParams, op.parameters, sharedParams);
+    const body = op.requestBody;
+    const bodySchemaRef = refName(body?.content?.['application/json']?.schema?.$ref) ?? refName(body?.$ref) ?? undefined;
+    const responses = {};
+    let successStatus;
+    let successRef;
+    for (const [status, resp] of Object.entries(op.responses ?? {})) {
+        const r = resp;
+        const ref = refName(r?.content?.['application/json']?.schema?.$ref) ?? refName(r?.$ref) ?? undefined;
+        responses[status] = ref;
+        if (!successStatus && status.startsWith('2')) {
+            successStatus = status;
+            successRef = ref;
+        }
+    }
+    const securitySchemes = [];
+    if (Array.isArray(op.security)) {
+        for (const s of op.security) {
+            if (s && typeof s === 'object') {
+                for (const key of Object.keys(s)) {
+                    if (!securitySchemes.includes(key))
+                        securitySchemes.push(key);
+                }
+            }
+        }
+    }
+    const requiredPermissions = Array.isArray(op['x-required-permissions'])
+        ? op['x-required-permissions'].map(String)
+        : [];
+    const authorizationNotes = Array.isArray(op['x-authorization-notes'])
+        ? op['x-authorization-notes'].map(String)
+        : [];
+    const operationId = op.operationId ?? synthesizeOperationId(method, path);
+    return {
+        operationId,
+        method,
+        path,
+        tag: tags[0],
+        tags,
+        summary: op.summary,
+        description: op.description,
+        params,
+        bodySchemaRef,
+        bodyRequired: body?.required === true,
+        responses,
+        successStatus,
+        successRef,
+        securitySchemes,
+        requiredPermissions,
+        authorizationNotes,
+    };
+}
+function mergeParams(pathLevelParams, opParams, sharedParams) {
+    const all = [...(pathLevelParams ?? []), ...(opParams ?? [])];
+    const seen = new Set();
+    const out = [];
+    for (const raw of all) {
+        const resolved = resolveParamRef(raw, sharedParams);
+        if (!resolved?.name || !resolved?.in)
+            continue;
+        const key = `${resolved.in}:${resolved.name}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        const loc = resolved.in === 'path' || resolved.in === 'query' || resolved.in === 'header' ? resolved.in : 'query';
+        const rule = buildFieldRule(resolved.schema ?? {}, !!resolved.required);
+        out.push({
+            name: resolved.name,
+            in: loc,
+            required: !!resolved.required,
+            rule,
+        });
+    }
+    return out;
+}
+function resolveParamRef(raw, sharedParams) {
+    if (!raw)
+        return raw;
+    if (typeof raw.$ref !== 'string')
+        return raw;
+    const name = refName(raw.$ref);
+    if (!name || !sharedParams)
+        return raw;
+    return sharedParams[name] ?? raw;
+}
+function synthesizeOperationId(method, path) {
+    const cleaned = path
+        .replace(/\/+/g, '/')
+        .split('/')
+        .filter(Boolean)
+        .map((seg) => seg.replace(/^\{/, 'by-').replace(/\}$/, ''))
+        .join('-');
+    return `${method}-${cleaned || 'root'}`;
+}
+// ---------------------------------------------------------------------------
+// Security & navigation
+// ---------------------------------------------------------------------------
+function buildSecuritySchemes(raw) {
+    if (!raw)
+        return [];
+    return Object.entries(raw).map(([name, s]) => ({
+        name,
+        type: String(s.type ?? 'unknown'),
+        scheme: s.scheme,
+        bearerFormat: s.bearerFormat,
+        in: s.in,
+    }));
+}
+function buildNavigation(tags) {
+    const byName = new Map();
+    for (const t of tags) {
+        byName.set(t.name, { name: t.name, xIcon: t.xIcon, description: t.description, children: [] });
+    }
+    const roots = [];
+    for (const t of tags) {
+        const node = byName.get(t.name);
+        if (t.parent && byName.has(t.parent)) {
+            byName.get(t.parent).children.push(node);
+        }
+        else {
+            roots.push(node);
+        }
+    }
+    return roots;
+}

package/generator/api/bin/src/parser/types.js

@@ -0,0 +1,7 @@
+"use strict";
+/**
+ * Intermediate Representation (IR) that emitters consume. Keeping this thin +
+ * plain-object makes emitters trivial to unit test without pulling in an OpenAPI
+ * parser in the test path.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/generator/api/bin/src/render/template.js

@@ -0,0 +1,58 @@
+"use strict";
+/**
+ * Tiny rendering helpers. We use template literals + small utilities rather
+ * than a template engine to keep the generator dependency-free and the
+ * emitter output predictable.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.kebabCase = kebabCase;
+exports.pascalCase = pascalCase;
+exports.camelCase = camelCase;
+exports.finalize = finalize;
+exports.comment = comment;
+exports.joinBlocks = joinBlocks;
+/** kebab-case (preserving digits) — matches the naming style in `old/api/`. */
+function kebabCase(input) {
+    return String(input)
+        .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+        .replace(/([A-Z]+)([A-Z][a-z])/g, '$1-$2')
+        .replace(/[^a-zA-Z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .toLowerCase();
+}
+/** PascalCase — used for class/interface names when sanitizing tags. */
+function pascalCase(input) {
+    return String(input)
+        .replace(/[^a-zA-Z0-9]+/g, ' ')
+        .trim()
+        .split(/\s+/)
+        .filter(Boolean)
+        .map((w) => w[0].toUpperCase() + w.slice(1))
+        .join('');
+}
+/** camelCase — used for variable / method / fn names. */
+function camelCase(input) {
+    const pc = pascalCase(input);
+    return pc ? pc[0].toLowerCase() + pc.slice(1) : '';
+}
+/** Trim trailing whitespace on every line and ensure a single trailing newline. */
+function finalize(text) {
+    const trimmed = text
+        .split('\n')
+        .map((line) => line.replace(/\s+$/g, ''))
+        .join('\n')
+        .replace(/\n{3,}/g, '\n\n')
+        .replace(/^\s*\n/, '');
+    return trimmed.endsWith('\n') ? trimmed : trimmed + '\n';
+}
+/** Render an indented block-comment (1-line friendly). */
+function comment(text) {
+    if (!text)
+        return '';
+    const safe = text.replace(/\*\//g, '*\\/');
+    return `/** ${safe} */`;
+}
+/** Join non-empty blocks with a blank line between them. */
+function joinBlocks(blocks) {
+    return blocks.filter(Boolean).join('\n\n');
+}

package/generator/api/bin/src/writer/index.js

@@ -0,0 +1,69 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.writeStandalone = writeStandalone;
+exports.writeLibrary = writeLibrary;
+exports.writeSecondaryEntrypoint = writeSecondaryEntrypoint;
+const template_1 = require("../render/template");
+/**
+ * No-op writer for the standalone mode — returns emitted files unchanged. Kept
+ * as a named function so modes are composable from a single switch at the
+ * engine layer.
+ */
+function writeStandalone(files) {
+    return files;
+}
+/**
+ * Library mode: add `ng-package.json`, `package.json`, and a top-level README
+ * so the `output` folder can be built with ng-packagr directly.
+ */
+function writeLibrary(files, ir, target) {
+    const ngPackage = {
+        $schema: '../../node_modules/ng-packagr/ng-package.schema.json',
+        dest: `../dist/${target.packageName.replace(/^@/, '').replace(/\//g, '-')}`,
+        lib: { entryFile: 'public-api.ts' },
+    };
+    const pkg = {
+        name: target.packageName,
+        version: target.packageVersion,
+        description: `Generated SDK for ${ir.title} ${ir.version}`,
+        peerDependencies: {
+            '@angular/common': '>=20.0.0',
+            '@angular/core': '>=20.0.0',
+            rxjs: '>=7.0.0',
+        },
+        sideEffects: false,
+    };
+    return [
+        ...files,
+        {
+            path: 'ng-package.json',
+            content: (0, template_1.finalize)(JSON.stringify(ngPackage, null, 2)),
+        },
+        {
+            path: 'package.json',
+            content: (0, template_1.finalize)(JSON.stringify(pkg, null, 2)),
+        },
+        {
+            path: 'README.md',
+            content: (0, template_1.finalize)(`# ${target.packageName}\n\nGenerated SDK for **${ir.title}** v${ir.version}.\n\nThis folder was generated by the local SDK generator. Do not edit by hand.\n`),
+        },
+    ];
+}
+/**
+ * Secondary-entrypoint mode: same file set as standalone, plus a minimal
+ * `ng-package.json` pointing at `public-api.ts`. Meant to live **inside** an
+ * existing library (e.g. `projects/angular/sdk-api/`) so ng-packagr picks it
+ * up automatically as a secondary entrypoint of the parent library.
+ */
+function writeSecondaryEntrypoint(files, _ir, _target) {
+    const ngPackage = {
+        lib: { entryFile: 'public-api.ts' },
+    };
+    return [
+        ...files,
+        {
+            path: 'ng-package.json',
+            content: (0, template_1.finalize)(JSON.stringify(ngPackage, null, 2)),
+        },
+    ];
+}

package/generator/api/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/generator/api/schematics/sdk/schema.json

@@ -0,0 +1,19 @@
+{
+    "$schema": "http://json-schema.org/draft-07/schema",
+    "$id": "SdkGeneratorSchema",
+    "title": "Generate an Angular SDK from an OpenAPI spec",
+    "type": "object",
+    "properties": {
+        "config": {
+            "type": "string",
+            "description": "Path to sdk.config.json (defaults to ./config/sdk.config.json at workspace root).",
+            "default": "config/sdk.config.json"
+        },
+        "target": {
+            "type": "string",
+            "description": "Optional name/index of a specific target in the config to generate."
+        }
+    },
+    "required": [],
+    "additionalProperties": false
+}

package/generator/api/sdk.config.example.json

@@ -0,0 +1,22 @@
+{
+    "$schema": "./node_modules/@ojiepermana/angular/generator/api/schematics/sdk/schema.json",
+    "targets": [
+        {
+            "input": "./openapi.yaml",
+            "output": "./sdk",
+            "mode": "standalone",
+            "clientName": "Api",
+            "rootUrl": "http://127.0.0.1:8080",
+            "splitByDomain": false,
+            "splitDepth": "service",
+            "features": {
+                "models": true,
+                "operations": true,
+                "services": true,
+                "client": true,
+                "metadata": true,
+                "navigation": true
+            }
+        }
+    ]
+}

package/generator/guide/README.md

@@ -0,0 +1,84 @@
+# `@ojiepermana/angular/generator/guide`
+
+Build-time schematic that compiles a folder of Markdown files into Angular standalone components plus a nested `Routes` file.
+
+This entry point ships **no runtime code**. It is only invoked through the Angular CLI:
+
+```bash
+# 1. scaffold a config file at the workspace root
+bun run gen:guide:init
+
+# 2. edit guide.config.json (sourceDir, outputDir, ...)
+
+# 3. generate components + routes
+bun run gen:guide
+```
+
+Inside this monorepo the schematic factory is registered in the parent collection at [`projects/angular/collection.json`](../../collection.json).
+After publishing, consumers run `ng generate @ojiepermana/angular:guide` (and `:guide-init` to scaffold the config).
+
+## Config (`guide.config.json`)
+
+| Key               | Type                        | Default         | Description                                                         |
+| ----------------- | --------------------------- | --------------- | ------------------------------------------------------------------- |
+| `sourceDir`       | `string` (required)         | —               | Folder containing `.md` files. Nested folders become nested routes. |
+| `outputDir`       | `string` (required)         | —               | Destination folder for generated components and the routes file.    |
+| `routeFile`       | `string`                    | `doc.routes.ts` | File name of the generated routes file at `outputDir`.              |
+| `componentPrefix` | `string`                    | `Doc`           | Prefix on generated component class names.                          |
+| `componentStyle`  | `'none' \| 'css' \| 'scss'` | `'none'`        | Whether to emit a sibling stylesheet per component.                 |
+| `routeExportName` | `string`                    | `DOC_ROUTES`    | Identifier used for the exported `Routes` constant.                 |
+
+## Frontmatter
+
+Each `.md` file may declare YAML-style frontmatter:
+
+```md
+---
+title: Getting Started
+order: 1
+path: getting-started
+---
+
+# Hello
+```
+
+- `title` → `data.title` on the route
+- `order` → controls sibling sort order (lower comes first)
+- `path` → overrides the URL segment derived from the file name (`index.md` → empty path)
+
+## Output shape
+
+For `sourceDir: ./docs` containing `docs/intro/overview.md`:
+
+```
+<outputDir>/
+  intro/
+    overview.component.ts        // standalone @Component, OnPush, inline template
+  doc.routes.ts                  // exports DOC_ROUTES: Routes
+```
+
+Routes mirror the folder tree with lazy `loadComponent`:
+
+```ts
+export const DOC_ROUTES: Routes = [
+  {
+    path: 'intro',
+    children: [
+      {
+        path: 'overview',
+        loadComponent: () => import('./intro/overview.component').then((m) => m.DocIntroOverviewComponent),
+        data: { title: 'Overview', order: 1 },
+      },
+    ],
+  },
+];
+```
+
+Then plug into your app:
+
+```ts
+{
+  path: 'docs',
+  loadChildren: () => import('./docs/doc.routes').then((m) => m.DOC_ROUTES),
+},
+```

package/generator/guide/bin/schematics/build/index.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.build = build;
+const node_path_1 = require("node:path");
+const loader_1 = require("../../src/config/loader");
+const engine_1 = require("../../src/engine");
+function build(options = {}) {
+    return (tree, context) => {
+        const workspaceRoot = process.cwd();
+        const configPath = options.config ?? 'config/guide.config.json';
+        const config = (0, loader_1.loadConfig)(configPath, workspaceRoot);
+        const result = (0, engine_1.generate)(config, workspaceRoot);
+        writeResult(tree, workspaceRoot, result, context);
+    };
+}
+function writeResult(tree, workspaceRoot, result, context) {
+    const relOutput = (0, node_path_1.relative)(workspaceRoot, result.outputDir) || '.';
+    context.logger.info(`[guide] ${relOutput} (markdown=${result.stats.markdown}, components=${result.stats.components}, files=${result.stats.files})`);
+    for (const file of result.files) {
+        const treePath = normalizeTreePath(workspaceRoot, file.path);
+        const buffer = Buffer.from(file.content, 'utf8');
+        if (tree.exists(treePath)) {
+            tree.overwrite(treePath, buffer);
+        }
+        else {
+            tree.create(treePath, buffer);
+        }
+    }
+}
+function normalizeTreePath(workspaceRoot, path) {
+    const abs = (0, node_path_1.resolve)(workspaceRoot, path);
+    const rel = (0, node_path_1.relative)(workspaceRoot, abs);
+    const posix = rel.split(/\\+/).join('/');
+    return posix.startsWith('/') ? posix : `/${posix}`;
+}