skir-php-generator 0.1.0 → 0.3.0

package/dist/index.d.ts

@@ -1,16 +1,12 @@
 import { type CodeGenerator } from "skir-internal";
-import { z } from "zod";
+import { GeneratorConfig } from "./config.js";
 import { generatePhpFiles } from "./generator.js";
-declare const Config: z.ZodObject<{
-    namespace: z.ZodDefault<z.ZodString>;
-}, z.core.$strict>;
-type Config = z.infer<typeof Config>;
-declare class PhpGenerator implements CodeGenerator<Config> {
+declare class PhpGenerator implements CodeGenerator<GeneratorConfig> {
     readonly id = "skir-php-generator";
-    readonly configType: z.ZodObject<{
-        namespace: z.ZodDefault<z.ZodString>;
-    }, z.core.$strict>;
-    generateCode(input: CodeGenerator.Input<Config>): CodeGenerator.Output;
+    readonly configType: CodeGenerator<GeneratorConfig>["configType"];
+    generateCode(input: CodeGenerator.Input<GeneratorConfig>): CodeGenerator.Output;
 }
 export declare const GENERATOR: PhpGenerator;
 export { generatePhpFiles };
+export { StandardPhpTarget } from "./target.js";
+export default GENERATOR;

package/dist/index.js

@@ -1,11 +1,8 @@
-import { z } from "zod";
+import { GeneratorConfig, GENERATOR_MODULE } from "./config.js";
 import { generatePhpFiles } from "./generator.js";
-const Config = z.strictObject({
-    namespace: z.string().default("App\\Skir"),
-});
 class PhpGenerator {
-    id = "skir-php-generator";
-    configType = Config;
+    id = GENERATOR_MODULE;
+    configType = GeneratorConfig;
     generateCode(input) {
         return {
             files: generatePhpFiles(input),
@@ -14,3 +11,5 @@ class PhpGenerator {
 }
 export const GENERATOR = new PhpGenerator();
 export { generatePhpFiles };
+export { StandardPhpTarget } from "./target.js";
+export default GENERATOR;

package/dist/server-manifest.d.ts

@@ -0,0 +1,17 @@
+import type { GeneratedFile } from "./generator.js";
+export declare const SERVER_MANIFEST_VERSION = 1;
+export interface ServerManifestMethod {
+    readonly name: string;
+    readonly enumCase: string;
+    readonly phpMethod: string;
+    readonly requestType: string;
+    readonly requestClass: string | null;
+    readonly responseType: string;
+    readonly responseClass: string | null;
+}
+export interface ServerManifestModule {
+    readonly name: string;
+    readonly methodEnum: string;
+    readonly methods: readonly ServerManifestMethod[];
+}
+export declare function generateServerManifestFile(generator: string, modules: readonly ServerManifestModule[]): GeneratedFile;

package/dist/server-manifest.js

@@ -0,0 +1,11 @@
+export const SERVER_MANIFEST_VERSION = 1;
+export function generateServerManifestFile(generator, modules) {
+    return {
+        path: "skir-server-manifest.json",
+        code: `${JSON.stringify({
+            version: SERVER_MANIFEST_VERSION,
+            generator,
+            modules,
+        }, null, 2)}\n`,
+    };
+}

package/dist/target.d.ts

@@ -0,0 +1,20 @@
+import { type GeneratedFile, type NormalizedRecord, type NormalizedType, type PhpTargetAdapter, type RenderContext, type StructRenderRequest } from "@php-skir/generator-core";
+export declare class StandardPhpTarget implements PhpTargetAdapter {
+    readonly id = "skir-php-generator";
+    recordClassName(record: NormalizedRecord): string;
+    renderStruct({ record, context }: StructRenderRequest): GeneratedFile;
+    phpType(type: NormalizedType, context: RenderContext): string;
+    toSkirExpression(type: NormalizedType, expression: string, context: RenderContext): string;
+    fromSkirExpression(type: NormalizedType, expression: string, context: RenderContext): string;
+    clientResponseExpression(type: NormalizedType, expression: string, context: RenderContext): string;
+    manifestObjectClass(type: NormalizedType, context: RenderContext): string | null;
+    private renderConstructor;
+    private renderSkirType;
+    private renderToArray;
+    private renderFromArray;
+    private renderToDenseJson;
+    private renderFromDenseJson;
+    private renderToReadableJson;
+    private renderToBytes;
+    private renderFromBytes;
+}

package/dist/target.js

@@ -0,0 +1,317 @@
+import { importClass, importClassAs, indent, renderPhpFile, toClassName, toPhpNamespaceSegment, toPropertyName, } from "@php-skir/generator-core";
+import { GENERATOR_MODULE } from "./config.js";
+export class StandardPhpTarget {
+    id = GENERATOR_MODULE;
+    recordClassName(record) {
+        return toClassName(record.qualifiedName);
+    }
+    renderStruct({ record, context }) {
+        if (record.recordType !== "struct") {
+            throw new Error(`Cannot render non-struct record ${record.identity} as a struct.`);
+        }
+        const className = classNameForRecord(record, context);
+        const binaryFormat = importClass(context.imports, "Skir\\Runtime\\BinaryFormat");
+        const denseJson = importClass(context.imports, "Skir\\Runtime\\DenseJson");
+        const fieldClass = importClass(context.imports, "Skir\\Runtime\\Field");
+        const readableJson = importClass(context.imports, "Skir\\Runtime\\ReadableJson");
+        const typeClass = importClass(context.imports, "Skir\\Runtime\\Type");
+        const fields = record.fields.filter(isStructField);
+        const constructor = this.renderConstructor(fields, context);
+        const members = [
+            constructor,
+            this.renderSkirType(record, context, fieldClass, typeClass),
+            this.renderToArray(fields, context),
+            this.renderFromArray(className, fields, context),
+            this.renderToDenseJson(denseJson),
+            this.renderFromDenseJson(className, denseJson),
+            this.renderToReadableJson(readableJson),
+            this.renderToBytes(binaryFormat),
+            this.renderFromBytes(className, binaryFormat),
+        ].filter((member) => member !== null);
+        const body = [
+            `final readonly class ${className}`,
+            "{",
+            ...members.flatMap((member, index) => index === 0
+                ? [indent(member)]
+                : ["", indent(member)]),
+            "}",
+        ].join("\n");
+        return {
+            path: outputPath(context, `${className}.php`),
+            code: renderPhpFile({
+                namespace: context.namespace,
+                imports: renderStandardUseStatements(context),
+                body,
+            }),
+        };
+    }
+    phpType(type, context) {
+        if (type.kind === "bool") {
+            return "bool";
+        }
+        if (type.kind === "int32" || type.kind === "timestamp") {
+            return "int";
+        }
+        if (type.kind === "int64" || type.kind === "hash64") {
+            return "int|string";
+        }
+        if (type.kind === "float32" || type.kind === "float64") {
+            return "float";
+        }
+        if (type.kind === "string" || type.kind === "bytes") {
+            return "string";
+        }
+        if (type.kind === "array") {
+            return "array";
+        }
+        if (type.kind === "optional") {
+            return nullablePhpType(this.phpType(type.inner, context));
+        }
+        if (type.kind === "record") {
+            return recordTypeClassName(type, context);
+        }
+        return "mixed";
+    }
+    toSkirExpression(type, expression, context) {
+        if (type.kind === "record") {
+            return type.recordType === "enum"
+                ? `${expression}->toSkirValue()`
+                : `${expression}->toArray()`;
+        }
+        if (type.kind === "optional") {
+            if (type.inner.kind === "record" || type.inner.kind === "array") {
+                return `${expression} === null ? null : ${this.toSkirExpression(type.inner, expression, context)}`;
+            }
+            return expression;
+        }
+        if (type.kind === "array") {
+            if (type.item.kind === "record"
+                || type.item.kind === "optional"
+                || type.item.kind === "array") {
+                return `array_map(fn (mixed $item): mixed => ${this.toSkirExpression(type.item, "$item", context)}, ${expression})`;
+            }
+        }
+        return expression;
+    }
+    fromSkirExpression(type, expression, context) {
+        if (type.kind === "record") {
+            const className = recordTypeClassName(type, context);
+            return type.recordType === "enum"
+                ? `${className}::fromSkirValue(${expression})`
+                : `${className}::fromArray(${expression})`;
+        }
+        if (type.kind === "optional") {
+            if (type.inner.kind === "record" || type.inner.kind === "array") {
+                return `${expression} === null ? null : ${this.fromSkirExpression(type.inner, expression, context)}`;
+            }
+            return expression;
+        }
+        if (type.kind === "array") {
+            if (type.item.kind === "record"
+                || type.item.kind === "optional"
+                || type.item.kind === "array") {
+                return `array_map(fn (mixed $item): mixed => ${this.fromSkirExpression(type.item, "$item", context)}, ${expression})`;
+            }
+        }
+        return expression;
+    }
+    clientResponseExpression(type, expression, context) {
+        return this.fromSkirExpression(type, expression, context);
+    }
+    manifestObjectClass(type, context) {
+        if (type.kind !== "record") {
+            return null;
+        }
+        return fullyQualifiedRecordClassName(type, context);
+    }
+    renderConstructor(fields, context) {
+        if (fields.length === 0) {
+            return null;
+        }
+        return [
+            "public function __construct(",
+            ...fields.map((field) => (`    public ${this.phpType(field.type, context)} $${toPropertyName(field.name)},`)),
+            ") {}",
+        ].join("\n");
+    }
+    renderSkirType(record, context, fieldClass, typeClass) {
+        const entries = record.fields.map((field) => {
+            if (field.kind === "removed") {
+                return `    ${fieldClass}::removed(${field.number}),`;
+            }
+            if (!field.hasPayload) {
+                throw new Error(`Struct field ${field.name} in ${record.identity} has no payload type.`);
+            }
+            return `    ${fieldClass}::value('${field.name}', ${field.number}, ${runtimeTypeExpression(field.type, context, this, typeClass)}),`;
+        }).join("\n");
+        return [
+            `public static function skirType(): ${typeClass}`,
+            "{",
+            `    return ${typeClass}::struct([`,
+            entries,
+            "    ]);",
+            "}",
+        ].join("\n");
+    }
+    renderToArray(fields, context) {
+        return [
+            "/** @return array<string, mixed> */",
+            "public function toArray(): array",
+            "{",
+            "    return [",
+            ...fields.map((field) => {
+                const property = toPropertyName(field.name);
+                return `        '${field.name}' => ${this.toSkirExpression(field.type, `$this->${property}`, context)},`;
+            }),
+            "    ];",
+            "}",
+        ].join("\n");
+    }
+    renderFromArray(className, fields, context) {
+        return [
+            "/** @param array<string, mixed> $data */",
+            `public static function fromArray(array $data): ${className}`,
+            "{",
+            "    return new self(",
+            ...fields.map((field) => (`        ${toPropertyName(field.name)}: ${this.fromSkirExpression(field.type, `$data['${field.name}']`, context)},`)),
+            "    );",
+            "}",
+        ].join("\n");
+    }
+    renderToDenseJson(denseJson) {
+        return [
+            "public function toDenseJson(): string",
+            "{",
+            `    return ${denseJson}::toJson(self::skirType(), $this->toArray());`,
+            "}",
+        ].join("\n");
+    }
+    renderFromDenseJson(className, denseJson) {
+        return [
+            `public static function fromDenseJson(string $json): ${className}`,
+            "{",
+            `    return self::fromArray(${denseJson}::fromJson(self::skirType(), $json));`,
+            "}",
+        ].join("\n");
+    }
+    renderToReadableJson(readableJson) {
+        return [
+            "public function toReadableJson(): string",
+            "{",
+            `    return ${readableJson}::toJson(self::skirType(), $this->toArray());`,
+            "}",
+        ].join("\n");
+    }
+    renderToBytes(binaryFormat) {
+        return [
+            "public function toBytes(): string",
+            "{",
+            `    return ${binaryFormat}::encode(self::skirType(), $this->toArray());`,
+            "}",
+        ].join("\n");
+    }
+    renderFromBytes(className, binaryFormat) {
+        return [
+            `public static function fromBytes(string $bytes): ${className}`,
+            "{",
+            `    return self::fromArray(${binaryFormat}::decode(self::skirType(), $bytes));`,
+            "}",
+        ].join("\n");
+    }
+}
+function nullablePhpType(type) {
+    const unionMembers = type.split("|");
+    if (type === "mixed" || type.startsWith("?") || unionMembers.includes("null")) {
+        return type;
+    }
+    return unionMembers.length === 1 ? `?${type}` : `${type}|null`;
+}
+function isStructField(field) {
+    return field.kind === "field" && field.hasPayload;
+}
+function runtimeTypeExpression(type, context, adapter, typeClass) {
+    if (type.kind === "array") {
+        return `${typeClass}::array(${runtimeTypeExpression(type.item, context, adapter, typeClass)})`;
+    }
+    if (type.kind === "optional") {
+        return `${typeClass}::optional(${runtimeTypeExpression(type.inner, context, adapter, typeClass)})`;
+    }
+    if (type.kind === "record") {
+        return `${adapter.phpType(type, context)}::skirType()`;
+    }
+    return `${typeClass}::${type.kind}()`;
+}
+function classNameForRecord(record, context) {
+    const className = context.names.namesByIdentity.get(record.identity);
+    if (className === undefined) {
+        throw new Error(`No PHP class name was resolved for struct ${record.identity}.`);
+    }
+    return className;
+}
+function recordTypeClassName(type, context) {
+    const className = context.names.namesByIdentity.get(type.recordIdentity);
+    if (className === undefined) {
+        throw new Error(`No PHP class name was resolved for record ${type.recordIdentity}.`);
+    }
+    const namespace = recordNamespace(type.recordIdentity, context.rootNamespace);
+    if (namespace === context.namespace) {
+        return className;
+    }
+    const fullyQualifiedClassName = canonicalRecordClassName(namespace, className);
+    const isReserved = [...context.imports.reservedNames].some((reservedName) => (reservedName.toLowerCase() === className.toLowerCase()));
+    if (isReserved) {
+        return `\\${fullyQualifiedClassName}`;
+    }
+    const existingImport = [...context.imports.imports.entries()]
+        .find(([localName]) => localName.toLowerCase() === className.toLowerCase());
+    if (existingImport === undefined) {
+        return importClassAs(context.imports, fullyQualifiedClassName, className);
+    }
+    return existingImport[1].toLowerCase() === fullyQualifiedClassName.toLowerCase()
+        ? existingImport[0]
+        : `\\${fullyQualifiedClassName}`;
+}
+function fullyQualifiedRecordClassName(type, context) {
+    const className = context.names.namesByIdentity.get(type.recordIdentity);
+    if (className === undefined) {
+        throw new Error(`No PHP class name was resolved for record ${type.recordIdentity}.`);
+    }
+    return canonicalRecordClassName(recordNamespace(type.recordIdentity, context.rootNamespace), className);
+}
+function canonicalRecordClassName(namespace, className) {
+    const fullyQualifiedClassName = `${namespace}\\${className}`.replace(/^\\+/u, "");
+    const parts = fullyQualifiedClassName.split("\\");
+    if (parts.some((part) => !/^[A-Za-z_][A-Za-z0-9_]*$/u.test(part))) {
+        throw new Error(`Invalid normalized PHP record class name ${fullyQualifiedClassName}.`);
+    }
+    if (parts.at(-1) !== className) {
+        throw new Error(`Invalid normalized PHP record basename ${className}.`);
+    }
+    return fullyQualifiedClassName;
+}
+function recordNamespace(recordIdentity, rootNamespace) {
+    const separatorIndex = recordIdentity.lastIndexOf("::");
+    if (separatorIndex === -1) {
+        throw new Error(`Invalid normalized record identity ${recordIdentity}.`);
+    }
+    const modulePath = recordIdentity.slice(0, separatorIndex);
+    const namespaceSegments = modulePath
+        .split("/")
+        .slice(0, -1)
+        .map((segment) => toPhpNamespaceSegment(segment))
+        .filter((segment) => segment !== "");
+    return [rootNamespace, ...namespaceSegments]
+        .filter((segment) => segment !== "")
+        .join("\\");
+}
+function outputPath(context, fileName) {
+    return context.pathPrefix === "" ? fileName : `${context.pathPrefix}/${fileName}`;
+}
+function renderStandardUseStatements(context) {
+    return [...context.imports.imports.entries()].map(([alias, fullyQualifiedClassName]) => {
+        const shortName = fullyQualifiedClassName.split("\\").at(-1);
+        return alias === shortName
+            ? `use ${fullyQualifiedClassName};`
+            : `use ${fullyQualifiedClassName} as ${alias};`;
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skir-php-generator",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Skir code generator for standard PHP data objects.",
   "type": "module",
   "license": "MIT",
@@ -29,21 +29,31 @@
     ".": "./dist/index.js"
   },
   "types": "./dist/index.d.ts",
+  "bin": {
+    "skir-php-generator": "./dist/cli.js"
+  },
   "files": [
     "dist"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "prepack": "npm run build",
+    "pretest:coverage": "npm run build",
     "pack:dry-run": "npm pack --dry-run --cache .npm-cache",
     "test": "vitest run",
+    "test:coverage": "vitest run --coverage --coverage.reporter=json-summary --coverage.include=src/**/*.ts",
     "typecheck": "tsc -p tsconfig.json --noEmit"
   },
   "dependencies": {
+    "@php-skir/generator-core": "^0.2.0",
+    "jsonc-parser": "^3.3.1",
     "skir-internal": "^0.2.21",
+    "yaml": "^2.9.0",
     "zod": "^4.0.0"
   },
   "devDependencies": {
+    "@types/node": "^22.20.1",
+    "@vitest/coverage-v8": "^4.1.10",
     "skir": "^1.2.19",
     "typescript": "^5.9.0",
     "vitest": "^4.0.0"