skir-php-generator 0.1.0 → 0.3.0

package/README.md

@@ -1,13 +1,21 @@
 # Skir PHP Generator
 
-Generates framework-agnostic PHP data objects for Skir schemas.
+[![Tests](https://github.com/php-skir/skir-php-generator/actions/workflows/tests.yml/badge.svg)](https://github.com/php-skir/skir-php-generator/actions/workflows/tests.yml)
+[![Coverage](https://raw.githubusercontent.com/php-skir/skir-php-generator/badges/coverage.svg)](https://github.com/php-skir/skir-php-generator/actions/workflows/tests.yml)
+[![npm](https://img.shields.io/npm/v/skir-php-generator?label=npm&logo=npm)](https://www.npmjs.com/package/skir-php-generator)
+[![Node.js](https://img.shields.io/badge/Node.js-22%20%7C%2024-339933?logo=nodedotjs&logoColor=white)](https://nodejs.org/)
+[![License](https://img.shields.io/github/license/php-skir/skir-php-generator)](LICENSE)
 
-Generated PHP code uses `php-skir/runtime` for dense JSON serialization. If you use generated RPC clients, install `php-skir/client` as well.
+Generates framework-agnostic PHP data objects, RPC clients, and server procedure contracts from Skir schemas.
+
+Generated PHP uses `php-skir/runtime` for dense JSON, readable JSON, and binary serialization. Install `php-skir/client` when using generated RPC clients and `php-skir/server` when using generated server contracts.
+
+The npm package uses [`@php-skir/generator-core`](https://github.com/php-skir/generator-core) at generation time for schema normalization, PHP naming and imports, shared enum and RPC rendering, server manifests, and Composer configuration. This package remains the framework-agnostic adapter: it owns the standard PHP data-object representation and conversions, while `php-skir/runtime` remains the Composer dependency used by the generated PHP at runtime.
 
 ## Installation
 
 ```bash
-npm install --save-dev skir-php-generator
+npm install --save-dev skir skir-php-generator
 composer require php-skir/runtime
 ```
 
@@ -17,24 +25,104 @@ For generated typed RPC clients:
 composer require php-skir/client
 ```
 
-## Releasing
+For generated server contracts:
 
-Create a GitHub release for the version in `package.json`. The release workflow reruns type checks, build, package validation, and tests before publishing to npm with provenance. It expects an `NPM_TOKEN` repository secret.
+```bash
+composer require php-skir/server
+```
 
-## Usage with Skir
+## Configure Skir
 
-Add the generator to `skir.yml`:
+Add the PHP generator to the root `skir.yml`:
 
 ```yaml
 generators:
-  php:
-    package: skir-php-generator
-    output: generated/php
+  - mod: skir-php-generator
+    outDir: generated/php/skirout
     config:
-      namespace: App\Skir
+      namespace: Skir
+```
+
+The `generators` value uses Skir's current array syntax. Skir owns the configured `outDir` and may replace generated files there, so do not store handwritten PHP in that directory. Keep each generator in a dedicated output directory whose path ends in `/skirout`; the suffix identifies it as generator-owned output.
+
+The root namespace defaults to `Skir`, so the `config` block can be omitted when that default is suitable. Schema directories become PHP subnamespaces and output directories:
+
+```text
+skir-src/health/health.skir -> generated/php/skirout/Health/HealthRequest.php
+                            -> Skir\Health\HealthRequest
+```
+
+Only source directories become namespace segments. The `.skir` filename itself does not add a namespace segment, so `health.skir` does not produce another `Health` level.
+
+A separate `Generated` namespace segment is unnecessary. The dedicated `generated/php/skirout` directory already separates generated code from handwritten application code, while the short `Skir` namespace keeps imports clear.
+
+Every emitted PHP file contains a `DO NOT EDIT` banner. Change the `.skir` source or generator configuration and regenerate instead of editing generated PHP.
+
+## Generate and configure Composer
+
+Run generation before configuring Composer because the configurator verifies that every output directory already exists:
+
+```bash
+npx skir gen
+npx skir-php-generator configure-composer
+composer dump-autoload
 ```
 
-Then run the Skir generator command for your project.
+`configure-composer` reads `skir.yml` and `composer.json` from the current project root. It finds the exact `mod: skir-php-generator` entry, normalizes the namespace and output path, and adds the matching Composer PSR-4 mapping. It prints whether the mapping was added or already unchanged.
+
+The command only updates `composer.json`. It does not run Composer, so run `composer dump-autoload` afterward. Use `--root <dir>` for another project root or `--mod <module>` when the generator's `mod` is an exact alternative identifier such as a local file URL:
+
+```bash
+npx skir-php-generator configure-composer --root ../api --mod file:///path/to/skir-php-generator/dist/index.js
+```
+
+The operation is idempotent. An existing equivalent mapping is left byte-for-byte unchanged. If the namespace prefix already points somewhere else, the command exits with an error and does not modify `composer.json`. It also stops with a useful error when `skir.yml` or `composer.json` is missing or invalid, the matching generator configuration is missing or invalid, an output path escapes the project root, or a generated output directory does not exist.
+
+When `outDir` is an ordered array, the configurator preserves that order in Composer's array-valued PSR-4 mapping. An existing Composer path array must match the entire configured array in the same order. Any difference is a conflict: the configurator fails without appending, merging, or modifying the existing mapping.
+
+### Package script automation
+
+The workflow can be kept in `package.json`:
+
+```json
+{
+  "scripts": {
+    "skir:generate": "skir gen && skir-php-generator configure-composer"
+  }
+}
+```
+
+Then run:
+
+```bash
+npm run skir:generate
+```
+
+Refresh Composer's autoloader as a separate follow-up step:
+
+```bash
+composer dump-autoload
+```
+
+### Manual Composer mapping
+
+To configure Composer manually, map the root namespace to the same generator-owned `outDir` and include trailing slashes:
+
+```json
+{
+  "autoload": {
+    "psr-4": {
+      "Skir\\": "generated/php/skirout/"
+    }
+  }
+}
+```
+
+After editing `composer.json`, run:
+
+```bash
+composer dump-autoload
+```
 
 ## Generated PHP
 
@@ -42,71 +130,85 @@ The generator emits readonly PHP classes for Skir structs and enum wrapper class
 
 - `skirType()` for runtime type descriptors.
 - `toArray()` and `fromArray()` for PHP array conversion.
-- `toDenseJson()` and `fromDenseJson()` for dense JSON payloads.
+- `toDenseJson()` and `fromDenseJson()` for dense JSON payloads. `fromDenseJson()` also accepts readable JSON, so there is no separate `fromReadableJson()`.
+- `toReadableJson()` for readable JSON payloads.
+- `toBytes()` and `fromBytes()` for Skir binary payloads.
 - `toSkirValue()` and `fromSkirValue()` on generated enum classes.
 
-SkirRPC methods are emitted in `SkirMethods.php` as `MethodDescriptor` instances. The generator also emits a module-scoped method enum such as `AdminSkirMethod.php` for attribute-based server routing.
+```php
+$json = $user->toReadableJson();
+$user = User::fromDenseJson($json);
 
-When a module defines SkirRPC methods, the generator also emits `SkirRpcClient.php`. It wraps `Skir\Client\SkirClient` and exposes typed methods:
+$bytes = $user->toBytes();
+$user = User::fromBytes($bytes);
+```
+
+SkirRPC methods are emitted in `SkirMethods.php` as `MethodDescriptor` instances. The generator also emits a module-scoped method enum such as `AdminSkirMethod.php` for typed server routing.
+
+When a module defines SkirRPC methods, the generator emits `SkirRpcClient.php`. It wraps `Skir\Client\SkirClient` and exposes typed methods:
 
 ```php
-use App\Skir\Admin\SkirRpcClient;
+use Skir\Admin\SkirRpcClient;
 use Skir\Client\SkirClient as TransportSkirClient;
 
 $client = new SkirRpcClient(new TransportSkirClient('https://example.com/skir'));
 $user = $client->getUser($request);
 ```
 
-For servers, the generator emits `AdminSkirMethod.php`, `AbstractSkirProcedures.php`, `SkirProcedures.php`, and `SkirProcedureProvider.php`.
+For servers, the generator emits a module method enum, `AbstractSkirProcedures.php`, `SkirProcedures.php`, and `SkirProcedureProvider.php`.
 
-The recommended Laravel server path is to use the generated method enum with `php-skir/server` controller routing:
+When two generated records would otherwise use the same PHP class name in one namespace, the generator prefixes each class with its module basename to keep output deterministic.
 
-```php
-use App\Skir\Admin\AdminSkirMethod;
-use App\Skir\Admin\GetUserRequest;
-use App\Skir\Admin\User;
-use Skir\Server\Attributes\SkirMethod;
-use Skir\Server\SkirContext;
+## Validation ownership
 
-final class UserController
-{
-    #[SkirMethod(AdminSkirMethod::GetUser)]
-    public function get(GetUserRequest $request, SkirContext $context): User
-    {
-        return new User(
-            userId: $request->userId,
-            name: 'Maxim',
-        );
-    }
-}
-```
+This generator intentionally performs no application validation. In Laravel, validate untrusted input with a handwritten Form Request before constructing generated objects. In other frameworks, use that framework's validator or an application-owned validation boundary.
 
-Register the controller on a Skir endpoint:
+The generated classes describe and convert the Skir wire format; they are not an input-validation boundary. Keep validation code outside `skirout`, because Skir owns that directory and regeneration overwrites its contents.
 
-```php
-use App\Skir\Controllers\UserController;
-use Illuminate\Support\Facades\Route;
-use Skir\Server\Facades\Skir;
+## Server scaffolding manifest
 
-Route::skirRpc('/api/skir', [
-    Skir::controller(UserController::class),
-]);
-```
+Each generation run writes `skir-server-manifest.json` at the root of the configured `outDir`. For the configuration above, the path is:
 
-The method enum resolves back to `SkirMethods::getUser()`, so the Skir schema remains the source of truth while your IDE can autocomplete enum cases.
+```text
+generated/php/skirout/skir-server-manifest.json
+```
 
-The abstract procedure and interface/provider pair remain available as lower-level compatibility APIs.
+The manifest is consumed by the [`php-skir/server`](https://github.com/php-skir/server) Laravel scaffolding commands. Keep the manifest path in the server package configuration aligned with the generator `outDir`.
 
-## Namespaces and modules
+Manifest module names use the generated PHP namespace segments joined with dots: `user-profile/` becomes `UserProfile`, nested `admin/users/` becomes `Admin.Users`, and a literal `admin.users/` directory becomes `AdminUsers`. Root-level methods use the reserved `_Root` module, while a real `Root/` directory remains `Root`. These names prefix exact server method IDs such as `_Root.Health` and `UserProfile.GetProfile`. Generation fails when distinct source directories normalize to the same PHP module instead of merging them.
 
-The configured namespace defaults to `App\Skir`. Module directories become PHP subnamespaces and output directories:
+The current schema version is `1`:
 
-```text
-admin/users.skir -> App\Skir\Admin
+```json
+{
+  "version": 1,
+  "generator": "skir-php-generator",
+  "modules": [
+    {
+      "name": "Admin",
+      "methodEnum": "Skir\\Admin\\AdminSkirMethod",
+      "methods": [
+        {
+          "name": "GetUser",
+          "enumCase": "GetUser",
+          "phpMethod": "getUser",
+          "requestType": "Skir\\Admin\\GetUserRequest",
+          "requestClass": "Skir\\Admin\\GetUserRequest",
+          "responseType": "Skir\\Admin\\GetUserResponse",
+          "responseClass": "Skir\\Admin\\GetUserResponse"
+        }
+      ]
+    }
+  ]
+}
 ```
 
-When two generated records would otherwise use the same PHP class name in the same namespace, the generator prefixes the class with the module basename to keep output deterministic.
+`methodEnum` and record request and response types are fully qualified PHP names without a leading backslash. `requestClass` is non-null only when the request is a generated object/struct DTO that can be hydrated through a Form Request; enum and other value requests use `null` while `requestType` retains their PHP type. `responseClass` identifies a generated response class that can be imported. Scalar and union types use PHP type syntax and have a `null` class field. Optional object/struct requests keep their underlying DTO in `requestClass`. Names are derived from the actual generated record location, including nested and cross-module references.
+
+Run `npx skir gen` after changing a schema. No extra generator option is required to emit the manifest.
+
+## Releasing
 
-## Current scope
+`@php-skir/generator-core` is a normal semver dependency of this package. Publish the required core version first, replace any local development link with that published version, update the lockfile, and verify a clean `npm ci` before releasing this adapter.
 
-This package generates framework-agnostic PHP DTOs, method descriptors, typed client adapters, and Laravel Skir server procedure adapters. Laravel-specific data objects and server routing live in separate packages.
+Create a GitHub release for the version in `package.json`. The release workflow reruns type checks, build, package validation, and tests before publishing to npm with provenance. Configure this GitHub repository and its `release.yml` workflow as an npm trusted publisher; the workflow authenticates through OIDC and does not use a long-lived npm token.

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+import { runConfigureComposerCli } from "@php-skir/generator-core";
+import { GeneratorConfig, GENERATOR_MODULE } from "./config.js";
+async function main() {
+    try {
+        await runConfigureComposerCli({
+            argv: process.argv.slice(2),
+            bin: "skir-php-generator",
+            module: GENERATOR_MODULE,
+            parseConfig: (value) => GeneratorConfig.parse(value),
+            namespace: (config) => config.namespace,
+        });
+    }
+    catch (error) {
+        process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+        process.exitCode = 1;
+    }
+}
+void main();

package/dist/composer-autoload.d.ts

@@ -0,0 +1,2 @@
+export { ComposerAutoloadConflictError, ensureComposerPsr4Mapping, MalformedComposerPsr4PrefixError, } from "@php-skir/generator-core";
+export type { ComposerAutoloadPaths, ComposerPsr4MappingResult, } from "@php-skir/generator-core";

package/dist/composer-autoload.js

@@ -0,0 +1 @@
+export { ComposerAutoloadConflictError, ensureComposerPsr4Mapping, MalformedComposerPsr4PrefixError, } from "@php-skir/generator-core";

package/dist/config.d.ts

@@ -0,0 +1,9 @@
+import { DEFAULT_NAMESPACE, PhpNamespace } from "@php-skir/generator-core";
+import { z } from "zod";
+export declare const GENERATOR_MODULE = "skir-php-generator";
+export { DEFAULT_NAMESPACE, PhpNamespace };
+export declare const GeneratorConfig: z.ZodObject<{
+    namespace: z.ZodDefault<z.ZodString>;
+}, z.core.$strict>;
+export type GeneratorConfig = z.infer<typeof GeneratorConfig>;
+export type GeneratorConfigInput = z.input<typeof GeneratorConfig>;

package/dist/config.js

@@ -0,0 +1,7 @@
+import { DEFAULT_NAMESPACE, PhpNamespace, } from "@php-skir/generator-core";
+import { z } from "zod";
+export const GENERATOR_MODULE = "skir-php-generator";
+export { DEFAULT_NAMESPACE, PhpNamespace };
+export const GeneratorConfig = z.strictObject({
+    namespace: PhpNamespace.default(DEFAULT_NAMESPACE),
+});

package/dist/configure-composer.d.ts

@@ -0,0 +1,6 @@
+import { type ComposerPsr4MappingResult } from "@php-skir/generator-core";
+export interface ConfigureComposerOptions {
+    readonly mod?: string;
+    readonly root?: string;
+}
+export declare function configureComposer(options?: ConfigureComposerOptions): Promise<ComposerPsr4MappingResult>;

package/dist/configure-composer.js

@@ -0,0 +1,10 @@
+import { configureComposer as configureCoreComposer, } from "@php-skir/generator-core";
+import { GeneratorConfig, GENERATOR_MODULE } from "./config.js";
+export function configureComposer(options = {}) {
+    return configureCoreComposer({
+        module: options.mod ?? GENERATOR_MODULE,
+        ...(options.root === undefined ? {} : { root: options.root }),
+        parseConfig: (value) => GeneratorConfig.parse(value),
+        namespace: (config) => config.namespace,
+    });
+}

package/dist/generator.d.ts

@@ -1,65 +1,9 @@
-export interface PhpGeneratorConfig {
-    readonly namespace?: string;
-}
-export interface PhpGeneratorInput {
+import { PHP_FILE_HEADER, type CoreGeneratorInput, type GeneratedFile } from "@php-skir/generator-core";
+import { type GeneratorConfigInput } from "./config.js";
+export { PHP_FILE_HEADER };
+export type PhpGeneratorConfig = GeneratorConfigInput;
+export interface PhpGeneratorInput extends CoreGeneratorInput {
     readonly config?: PhpGeneratorConfig;
-    readonly modules: readonly SkirModule[];
-    readonly recordMap?: ReadonlyMap<string, SkirRecordLocation>;
-}
-export interface SkirModule {
-    readonly path: string;
-    readonly records?: readonly (SkirRecord | SkirRecordLocation)[];
-    readonly methods?: readonly SkirMethod[];
-}
-export interface SkirRecordLocation {
-    readonly kind: "record-location";
-    readonly record: SkirRecord;
-    readonly recordAncestors?: readonly SkirRecord[];
-    readonly modulePath?: string;
-}
-export interface SkirRecord {
-    readonly kind?: string;
-    readonly key?: unknown;
-    readonly name: string | SkirToken;
-    readonly recordType?: "struct" | "enum";
-    readonly fields?: readonly SkirField[];
-    readonly removedNumbers?: readonly number[];
-    readonly phpClassName?: string;
-}
-export type SkirField = {
-    readonly kind: "field";
-    readonly name: string | SkirToken;
-    readonly number: number;
-    readonly type?: SkirType;
-} | {
-    readonly kind: "removed";
-    readonly number: number;
-};
-export type SkirType = string | {
-    readonly kind: string;
-    readonly primitive?: string;
-    readonly item?: SkirType;
-    readonly other?: SkirType;
-    readonly key?: unknown;
-    readonly name?: string | SkirToken;
-    readonly nameParts?: readonly SkirRecordNamePart[];
-    readonly recordType?: "struct" | "enum";
-};
-export interface SkirToken {
-    readonly text: string;
-}
-export type SkirRecordNamePart = string | SkirToken | {
-    readonly token: string | SkirToken;
-};
-export interface SkirMethod {
-    readonly kind: "method";
-    readonly name: string | SkirToken;
-    readonly number: number;
-    readonly requestType?: SkirType;
-    readonly responseType?: SkirType;
-}
-export interface GeneratedFile {
-    readonly path: string;
-    readonly code: string;
 }
 export declare function generatePhpFiles(input: PhpGeneratorInput): GeneratedFile[];
+export type { GeneratedFile, SkirField, SkirMethod, SkirModule, SkirRecord, SkirRecordLocation, SkirRecordNamePart, SkirToken, SkirType, } from "@php-skir/generator-core";