@omnifyjp/omnify 3.4.0 → 3.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@omnifyjp/omnify",
-  "version": "3.4.0",
+  "version": "3.6.0",
   "description": "Schema-driven code generation for Laravel, TypeScript, and SQL",
   "license": "MIT",
   "repository": {
@@ -36,10 +36,10 @@
     "zod": "^3.24.0"
   },
   "optionalDependencies": {
-    "@omnifyjp/omnify-darwin-arm64": "3.4.0",
-    "@omnifyjp/omnify-darwin-x64": "3.4.0",
-    "@omnifyjp/omnify-linux-x64": "3.4.0",
-    "@omnifyjp/omnify-linux-arm64": "3.4.0",
-    "@omnifyjp/omnify-win32-x64": "3.4.0"
+    "@omnifyjp/omnify-darwin-arm64": "3.6.0",
+    "@omnifyjp/omnify-darwin-x64": "3.6.0",
+    "@omnifyjp/omnify-linux-x64": "3.6.0",
+    "@omnifyjp/omnify-linux-arm64": "3.6.0",
+    "@omnifyjp/omnify-win32-x64": "3.6.0"
   }
 }

package/ts-dist/php/enum-generator.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Generates PHP enum classes for `kind: enum` schemas.
+ *
+ * Issue #34: every enum schema becomes a self-contained PHP 8.1+ backed enum
+ * placed in the global Omnify enums namespace (default `App\Omnify\Enums`).
+ * Localized labels from the schema are embedded as a `LABELS` constant so
+ * the generated enum is usable without setting up Laravel translation files.
+ *
+ * Class name convention: `{SchemaName}Enum.php` (e.g. schema `MenuStatus` →
+ * `MenuStatusEnum`). The trailing `Enum` suffix is intentional — it prevents
+ * collisions with model classes of the same base name and signals "this is an
+ * enum class" at every callsite (`MenuStatusEnum::Draft`).
+ */
+import { SchemaReader } from './schema-reader.js';
+import type { GeneratedFile, PhpConfig } from './types.js';
+/** Generate one PHP enum class for each `kind: enum` schema. */
+export declare function generateEnums(reader: SchemaReader, config: PhpConfig): GeneratedFile[];
+/** Convert a schema name (e.g. `MenuStatus`) to its enum class name (`MenuStatusEnum`). */
+export declare function enumClassName(schemaName: string): string;

package/ts-dist/php/enum-generator.js

@@ -0,0 +1,165 @@
+/**
+ * Generates PHP enum classes for `kind: enum` schemas.
+ *
+ * Issue #34: every enum schema becomes a self-contained PHP 8.1+ backed enum
+ * placed in the global Omnify enums namespace (default `App\Omnify\Enums`).
+ * Localized labels from the schema are embedded as a `LABELS` constant so
+ * the generated enum is usable without setting up Laravel translation files.
+ *
+ * Class name convention: `{SchemaName}Enum.php` (e.g. schema `MenuStatus` →
+ * `MenuStatusEnum`). The trailing `Enum` suffix is intentional — it prevents
+ * collisions with model classes of the same base name and signals "this is an
+ * enum class" at every callsite (`MenuStatusEnum::Draft`).
+ */
+import { toPascalCase } from './naming-helper.js';
+import { baseFile, resolveGlobalEnumPath, resolveGlobalEnumNamespace } from './types.js';
+/** Generate one PHP enum class for each `kind: enum` schema. */
+export function generateEnums(reader, config) {
+    const files = [];
+    for (const [name, schema] of Object.entries(reader.getEnumSchemas())) {
+        // Skip package-owned enums — those are generated by their owning package's
+        // codegen, not the host project's. Mirrors how object schemas are filtered
+        // by `getProjectObjectSchemas()` elsewhere.
+        if (schema.package != null)
+            continue;
+        files.push(generateEnumClass(name, schema, config));
+    }
+    return files;
+}
+function generateEnumClass(name, schema, config) {
+    const className = enumClassName(name);
+    const namespace = resolveGlobalEnumNamespace(config, config.models.namespace);
+    const values = (schema.values ?? []);
+    const cases = values.map(v => buildCase(v));
+    const labelsConst = buildLabelsConstant(values);
+    const content = `<?php
+
+namespace ${namespace};
+
+/**
+ * ${name}${schema.displayName ? ` — ${pickDefaultLabel(schema.displayName)}` : ''}
+ *
+ * DO NOT EDIT - This file is auto-generated by Omnify.
+ * Any changes will be overwritten on next generation.
+ *
+ * @generated by omnify
+ */
+enum ${className}: string
+{
+${cases.map(c => `    ${c}`).join('\n')}
+
+${labelsConst}
+
+    /**
+     * Get the localized label for this enum case.
+     *
+     * Falls back to the configured app fallback locale, then any defined
+     * locale, then the raw value if no labels were declared in the schema.
+     */
+    public function label(?string $locale = null): string
+    {
+        $locale = $locale ?? app()->getLocale();
+        $labels = static::LABELS[$this->value] ?? [];
+
+        return $labels[$locale]
+            ?? $labels[config('app.fallback_locale', 'en')]
+            ?? $labels[array_key_first($labels) ?? 'en']
+            ?? $this->value;
+    }
+
+    /**
+     * Get all enum values as a flat list.
+     *
+     * @return array<int, string>
+     */
+    public static function values(): array
+    {
+        return array_column(self::cases(), 'value');
+    }
+
+    /**
+     * Get an array of value → localized label suitable for select dropdowns.
+     *
+     * @return array<string, string>
+     */
+    public static function options(?string $locale = null): array
+    {
+        $out = [];
+        foreach (self::cases() as $case) {
+            $out[$case->value] = $case->label($locale);
+        }
+        return $out;
+    }
+}
+`;
+    return baseFile(resolveGlobalEnumPath(config, `${className}.php`, config.models.path), content);
+}
+/** Convert a schema name (e.g. `MenuStatus`) to its enum class name (`MenuStatusEnum`). */
+export function enumClassName(schemaName) {
+    const pascal = toPascalCase(schemaName);
+    return pascal.endsWith('Enum') ? pascal : `${pascal}Enum`;
+}
+/** Build a single `case Foo = 'foo';` line from a schema enum value. */
+function buildCase(v) {
+    const value = v.value;
+    return `case ${toPhpCaseName(value)} = '${escapePhpString(value)}';`;
+}
+/**
+ * Convert an enum value into a valid PHP case identifier. PHP case names must
+ * start with a letter or underscore and contain only `[A-Za-z0-9_]`. We map
+ * everything else through PascalCase and prefix a digit-leading name with
+ * `Case` so it's still legal.
+ */
+function toPhpCaseName(value) {
+    const cleaned = value
+        .replace(/[^A-Za-z0-9_]+/g, '_')
+        .split('_')
+        .filter(Boolean)
+        .map(part => part.charAt(0).toUpperCase() + part.slice(1))
+        .join('');
+    if (!cleaned)
+        return 'Unknown';
+    return /^[0-9]/.test(cleaned) ? `Case${cleaned}` : cleaned;
+}
+/** Build the `LABELS` constant containing every locale label for every value. */
+function buildLabelsConstant(values) {
+    const lines = [];
+    lines.push('    /**');
+    lines.push('     * Localized labels for each case, embedded directly so the generated enum');
+    lines.push('     * is self-contained and works without Laravel translation files.');
+    lines.push('     *');
+    lines.push('     * @var array<string, array<string, string>>');
+    lines.push('     */');
+    lines.push('    public const LABELS = [');
+    for (const v of values) {
+        const rawLabel = v.label;
+        // `label` can be either a plain string or a `{locale: text}` map. Normalize.
+        const labels = typeof rawLabel === 'string'
+            ? { en: rawLabel }
+            : (rawLabel ?? {});
+        const entries = Object.entries(labels);
+        if (entries.length === 0) {
+            lines.push(`        '${escapePhpString(v.value)}' => [],`);
+            continue;
+        }
+        const inner = entries
+            .map(([loc, txt]) => `'${escapePhpString(loc)}' => '${escapePhpString(String(txt))}'`)
+            .join(', ');
+        lines.push(`        '${escapePhpString(v.value)}' => [${inner}],`);
+    }
+    lines.push('    ];');
+    return lines.join('\n');
+}
+/** Pick a sensible default label from a localized string for the doc comment. */
+function pickDefaultLabel(displayName) {
+    if (typeof displayName === 'string')
+        return displayName;
+    return (displayName.en ??
+        displayName.ja ??
+        Object.values(displayName)[0] ??
+        '');
+}
+/** Escape single quotes and backslashes for inclusion in a PHP single-quoted string. */
+function escapePhpString(value) {
+    return value.replace(/\\/g, '\\\\').replace(/'/g, "\\'");
+}

package/ts-dist/php/file-model-generator.js

@@ -5,7 +5,7 @@
  * - FileStatusEnum.php (base, always overwritten)
  * - FileLocales.php (base, always overwritten)
  */
-import { baseFile, userFile, resolveModularBasePath, resolveModularBaseNamespace, resolveSharedBaseNamespace } from './types.js';
+import { baseFile, userFile, resolveModularBasePath, resolveModularBaseNamespace, resolveSharedBaseNamespace, resolveGlobalEnumPath, resolveGlobalEnumNamespace, resolveGlobalTraitNamespace, } from './types.js';
 /** Generate all File model infrastructure files. */
 export function generateFileModels(reader, config) {
     if (!reader.hasFileProperties())
@@ -96,9 +96,10 @@ class FileResource extends FileResourceBase
 function generateFileBaseModel(config, defaultDisk) {
     const baseNamespace = resolveModularBaseNamespace(config, 'File', 'Models', config.models.baseNamespace);
     const localesNamespace = resolveModularBaseNamespace(config, 'File', 'Locales', config.models.baseNamespace + '\\Locales');
-    const traitsNamespace = resolveSharedBaseNamespace(config, 'Traits', config.models.baseNamespace + '\\Traits');
+    // Issue #33: HasLocalizedDisplayName is a global Omnify trait — see trait-generator.ts.
+    const traitsNamespace = resolveGlobalTraitNamespace(config, config.models.baseNamespace + '\\Traits');
     const sharedModelsNamespace = resolveSharedBaseNamespace(config, 'Models', config.models.baseNamespace);
-    const enumNamespace = resolveModularBaseNamespace(config, 'File', 'Enums', config.models.namespace);
+    const enumNamespace = resolveGlobalEnumNamespace(config, config.models.namespace);
     const modelNamespace = config.models.namespace;
     const content = `<?php
 
@@ -334,7 +335,10 @@ class File extends FileBaseModel
     return userFile(`${config.models.path}/File.php`, content);
 }
 function generateFileStatusEnum(config) {
-    const modelNamespace = resolveModularBaseNamespace(config, 'File', 'Enums', config.models.namespace);
+    // Issue #33: FileStatusEnum belongs to the Omnify file-attachment subsystem,
+    // not to a user-defined "File" schema, so it lives in the global enums
+    // folder rather than under `Modules/File/Enums/`.
+    const modelNamespace = resolveGlobalEnumNamespace(config, config.models.namespace);
     const content = `<?php
 
 namespace ${modelNamespace};
@@ -372,7 +376,7 @@ enum FileStatusEnum: string
     }
 }
 `;
-    return baseFile(resolveModularBasePath(config, 'File', 'Enums', 'FileStatusEnum.php', config.models.path), content);
+    return baseFile(resolveGlobalEnumPath(config, 'FileStatusEnum.php', config.models.path), content);
 }
 function generateFileLocales(config, locales) {
     const baseNamespace = resolveModularBaseNamespace(config, 'File', 'Locales', config.models.baseNamespace + '\\Locales');

package/ts-dist/php/file-trait-generator.js

@@ -1,11 +1,13 @@
 /**
  * Generates the HasFiles trait for models with File-type properties.
  */
-import { baseFile, resolveModularBasePath, resolveModularBaseNamespace } from './types.js';
+import { baseFile, resolveGlobalTraitPath, resolveGlobalTraitNamespace, resolveGlobalEnumNamespace, } from './types.js';
 /** Generate the HasFiles trait. */
 export function generateFileTrait(config) {
-    const traitsNamespace = resolveModularBaseNamespace(config, 'File', 'Traits', config.models.baseNamespace + '\\Traits');
-    const enumNamespace = resolveModularBaseNamespace(config, 'File', 'Enums', config.models.namespace);
+    // Issue #33: HasFiles is a global Omnify trait — not scoped to any user
+    // schema — so it lives in the dedicated global traits folder.
+    const traitsNamespace = resolveGlobalTraitNamespace(config, config.models.baseNamespace + '\\Traits');
+    const enumNamespace = resolveGlobalEnumNamespace(config, config.models.namespace);
     const modelNamespace = config.models.namespace;
     const content = `<?php
 
@@ -92,6 +94,6 @@ trait HasFiles
 }
 `;
     return [
-        baseFile(resolveModularBasePath(config, 'File', 'Traits', 'HasFiles.php', config.models.basePath + '/Traits'), content),
+        baseFile(resolveGlobalTraitPath(config, 'HasFiles.php', config.models.basePath + '/Traits'), content),
     ];
 }

package/ts-dist/php/index.js

@@ -30,6 +30,7 @@ import { baseFile } from './types.js';
 import { generateControllers } from './controller-generator.js';
 import { generateServices } from './service-generator.js';
 import { generateRoutes } from './route-generator.js';
+import { generateEnums } from './enum-generator.js';
 export { derivePhpConfig } from './types.js';
 /** Generate all PHP files from schemas.json data. */
 export function generatePhp(data, overrides) {
@@ -61,6 +62,8 @@ export function generatePhp(data, overrides) {
         files.push(...generateServices(reader, config));
         files.push(...generateRoutes(reader, config));
     }
+    // Issue #34: every `kind: enum` schema becomes a global PHP enum class.
+    files.push(...generateEnums(reader, config));
     // Per-schema files
     files.push(...generateLocales(reader, config));
     files.push(...generateModels(reader, config));

package/ts-dist/php/model-generator.js

@@ -4,7 +4,8 @@
 import { toPascalCase, toSnakeCase, toCamelCase } from './naming-helper.js';
 import { toCast, toPhpDocType, isHiddenByDefault } from './type-mapper.js';
 import { buildRelation } from './relation-builder.js';
-import { baseFile, userFile, resolveModularBasePath, resolveModularBaseNamespace, resolveSharedBaseNamespace } from './types.js';
+import { baseFile, userFile, resolveModularBasePath, resolveModularBaseNamespace, resolveSharedBaseNamespace, resolveGlobalTraitNamespace, resolveGlobalEnumNamespace, } from './types.js';
+import { enumClassName } from './enum-generator.js';
 /** Generate base model and user model for all project-owned object schemas,
  *  plus user models for package schemas (extending the package model). */
 export function generateModels(reader, config) {
@@ -35,7 +36,8 @@ function generateBaseModel(name, schema, reader, config) {
     const modelName = toPascalCase(name);
     const baseNamespace = resolveModularBaseNamespace(config, name, 'Models', config.models.baseNamespace);
     const localesNamespace = resolveModularBaseNamespace(config, name, 'Locales', config.models.baseNamespace + '\\Locales');
-    const traitsNamespace = resolveSharedBaseNamespace(config, 'Traits', config.models.baseNamespace + '\\Traits');
+    // Issue #33: HasLocalizedDisplayName is a global Omnify trait, not a per-shared module file.
+    const traitsNamespace = resolveGlobalTraitNamespace(config, config.models.baseNamespace + '\\Traits');
     const sharedModelsNamespace = resolveSharedBaseNamespace(config, 'Models', config.models.baseNamespace);
     const modelNamespace = config.models.namespace;
     const options = schema.options ?? {};
@@ -70,7 +72,7 @@ function generateBaseModel(name, schema, reader, config) {
     const fillable = buildFillable(properties, expandedProperties, propertyOrder);
     const hidden = buildHidden(properties, expandedProperties, propertyOrder);
     const appends = buildAppends(expandedProperties);
-    const casts = buildCasts(properties, expandedProperties, propertyOrder, reader);
+    const casts = buildCasts(properties, expandedProperties, propertyOrder, reader, config);
     const relations = buildRelations(name, properties, propertyOrder, modelNamespace, reader);
     const accessors = buildAccessors(expandedProperties);
     const fileAccessors = hasFiles ? buildFileAccessors(properties, propertyOrder, modelNamespace) : '';
@@ -252,9 +254,14 @@ function buildImports(baseNamespace, modelName, hasSoftDelete, isAuthenticatable
     lines.push(`use ${traitsNamespace || baseNamespace + '\\Traits'}\\HasLocalizedDisplayName;`);
     lines.push(`use ${localesNamespace || baseNamespace + '\\Locales'}\\${modelName}Locales;`);
     if (hasFiles) {
-        // HasFiles lives in File module, not Shared
+        // Issue #33 followup: HasFiles is a global Omnify trait — see
+        // file-trait-generator.ts. The trait now lives at
+        // `app/Omnify/Traits/HasFiles.php` (namespace `App\Omnify\Traits`),
+        // not under per-module `Modules/File/Traits/`. The import statement
+        // here must match, otherwise generated models crash with
+        // `Trait "App\Omnify\Modules\File\Traits\HasFiles" not found`.
         const fileTraitsNs = config
-            ? resolveModularBaseNamespace(config, 'File', 'Traits', baseNamespace + '\\Traits')
+            ? resolveGlobalTraitNamespace(config, baseNamespace + '\\Traits')
             : (traitsNamespace || baseNamespace + '\\Traits');
         lines.push(`use ${fileTraitsNs}\\HasFiles;`);
         if (modelNamespace) {
@@ -422,13 +429,29 @@ function buildAppends(expandedProperties) {
         return '';
     return appends.map(a => `        '${a}',`).join('\n') + '\n';
 }
-function buildCasts(properties, expandedProperties, propertyOrder, reader) {
+function buildCasts(properties, expandedProperties, propertyOrder, reader, config) {
     const casts = [];
+    // Issue #34: cast `EnumRef` properties to their generated PHP enum class.
+    // Use a fully-qualified `\Namespace\FooEnum::class` reference so we don't
+    // need to track imports — Laravel resolves the enum cast by class name.
+    const globalEnumNs = config
+        ? resolveGlobalEnumNamespace(config, config.models.namespace)
+        : '';
     for (const propName of propertyOrder) {
         const prop = properties[propName];
         if (!prop)
             continue;
         const type = prop['type'] ?? 'String';
+        // EnumRef → cast to generated enum class (only when the referenced enum
+        // schema actually exists; otherwise fall through to a plain string).
+        if (type === 'EnumRef') {
+            const enumName = prop['enum'];
+            if (typeof enumName === 'string' && reader.getSchema(enumName)?.kind === 'enum' && globalEnumNs) {
+                const snakeName = toSnakeCase(propName);
+                casts.push(`'${snakeName}' => \\${globalEnumNs}\\${enumClassName(enumName)}::class,`);
+                continue;
+            }
+        }
         if (type === 'Association') {
             const relation = prop['relation'] ?? '';
             if (relation === 'ManyToOne') {

package/ts-dist/php/trait-generator.js

@@ -1,10 +1,13 @@
 /**
  * Port of TraitGenerator.php — generates HasLocalizedDisplayName trait.
  */
-import { baseFile, resolveSharedBasePath, resolveSharedBaseNamespace } from './types.js';
+import { baseFile, resolveGlobalTraitPath, resolveGlobalTraitNamespace } from './types.js';
 /** Generate the HasLocalizedDisplayName trait. */
 export function generateTrait(config) {
-    const ns = resolveSharedBaseNamespace(config, 'Traits', config.models.baseNamespace + '\\Traits');
+    // Issue #33: HasLocalizedDisplayName is a global Omnify trait shared across
+    // all schemas, so it belongs in the global traits folder, not under any
+    // single schema's `Modules/{Schema}/Traits/` subfolder.
+    const ns = resolveGlobalTraitNamespace(config, config.models.baseNamespace + '\\Traits');
     const content = `<?php
 
 namespace ${ns};
@@ -99,6 +102,6 @@ trait HasLocalizedDisplayName
 }
 `;
     return [
-        baseFile(resolveSharedBasePath(config, 'Traits', 'HasLocalizedDisplayName.php', config.models.basePath + '/Traits'), content),
+        baseFile(resolveGlobalTraitPath(config, 'HasLocalizedDisplayName.php', config.models.basePath + '/Traits'), content),
     ];
 }

package/ts-dist/php/types.d.ts

@@ -16,28 +16,42 @@ export declare function userFile(path: string, content: string): GeneratedFile;
 export type BaseCategory = 'Models' | 'Controllers' | 'Requests' | 'Resources' | 'Services' | 'Enums' | 'Traits' | 'Locales' | 'Policies';
 /**
  * Resolve base file path for a schema based on structure.
- * Modular: app/Modules/{SchemaName}/{category}/{fileName}
+ * Modular: {modules.path}/{SchemaName}/{category}/{fileName}
  * Legacy: {legacyPath}/{fileName}
  */
 export declare function resolveModularBasePath(config: PhpConfig, schemaName: string, category: BaseCategory, fileName: string, legacyPath: string): string;
 /**
  * Resolve base namespace for a schema based on structure.
- * Modular: App\Modules\{SchemaName}\{Category}
+ * Modular: {modules.namespace}\{SchemaName}\{Category}
  * Legacy: {legacyNamespace}
  */
 export declare function resolveModularBaseNamespace(config: PhpConfig, schemaName: string, category: BaseCategory, legacyNamespace: string): string;
 /**
- * Resolve shared base path (for cross-module files like BaseModel, HasLocalizedDisplayName).
- * Modular: app/Modules/Shared/{category}/{fileName}
+ * Resolve shared base path (for cross-module files like BaseModel).
+ * Modular: {shared.path}/{category}/{fileName}
  * Legacy: {legacyPath}/{fileName}
  */
 export declare function resolveSharedBasePath(config: PhpConfig, category: BaseCategory, fileName: string, legacyPath: string): string;
 /**
  * Resolve shared base namespace.
- * Modular: App\Modules\Shared\{Category}
+ * Modular: {shared.namespace}\{Category}
  * Legacy: {legacyNamespace}
  */
 export declare function resolveSharedBaseNamespace(config: PhpConfig, category: BaseCategory, legacyNamespace: string): string;
+/**
+ * Resolve global Omnify enum file path. Used for system enums that aren't tied
+ * to a single user-defined schema (e.g. FileStatusEnum belongs to the Omnify
+ * file-attachment subsystem). In modular mode these live under their own
+ * top-level folder so they're easy to find. In legacy mode the original
+ * `legacyPath` is preserved for backward compat.
+ */
+export declare function resolveGlobalEnumPath(config: PhpConfig, fileName: string, legacyPath: string): string;
+/** Resolve global Omnify enum namespace. Modular: {globalEnums.namespace}. Legacy: passthrough. */
+export declare function resolveGlobalEnumNamespace(config: PhpConfig, legacyNamespace: string): string;
+/** Resolve global Omnify trait file path (HasFiles, HasLocalizedDisplayName, ...). */
+export declare function resolveGlobalTraitPath(config: PhpConfig, fileName: string, legacyPath: string): string;
+/** Resolve global Omnify trait namespace. */
+export declare function resolveGlobalTraitNamespace(config: PhpConfig, legacyNamespace: string): string;
 /** Per-target path and namespace override from codegen.laravel config. */
 export interface LaravelPathOverride {
     path?: string;
@@ -65,6 +79,26 @@ export interface LaravelCodegenOverrides {
     policy?: LaravelPathOverride;
     controller?: LaravelPathOverride;
     service?: LaravelPathOverride;
+    /**
+     * Per-schema base-class root for `structure: modular`. Default
+     * `App\Omnify\Modules` (path `app/Omnify/Modules`) so generated base classes
+     * never collide with a team's hand-written `app/Modules/` (Modular Monolith
+     * pattern is common in Laravel).
+     */
+    modules?: LaravelPathOverride;
+    /** Cross-module shared classes (e.g. `BaseModel`). Default `App\Omnify\Shared`. */
+    shared?: LaravelPathOverride;
+    /**
+     * Global Omnify enums that aren't tied to a single user-defined schema
+     * (e.g. `FileStatusEnum` for the file-attachment subsystem).
+     * Default `App\Omnify\Enums`.
+     */
+    enums?: LaravelPathOverride;
+    /**
+     * Global Omnify traits (e.g. `HasFiles`, `HasLocalizedDisplayName`).
+     * Default `App\Omnify\Traits`.
+     */
+    traits?: LaravelPathOverride;
     route?: LaravelPathOverride;
     config?: LaravelPathOverride;
     nestedset?: NestedSetOverride;
@@ -74,6 +108,35 @@ export interface PhpConfig {
     /** Filesystem prefix applied to all generated paths. Empty when not set. */
     rootPath: string;
     structure: 'legacy' | 'modular';
+    /**
+     * Modular base-class root: `{path}/{Schema}/{Layer}/...` and
+     * `{namespace}\{Schema}\{Layer}`. Only consulted in `structure: modular`.
+     */
+    modules: {
+        namespace: string;
+        path: string;
+    };
+    /** Cross-module shared root (e.g. BaseModel lives at `{shared.path}/Models/`). */
+    shared: {
+        namespace: string;
+        path: string;
+    };
+    /** Global Omnify enums (e.g. FileStatusEnum). */
+    globalEnums: {
+        namespace: string;
+        path: string;
+    };
+    /** Global Omnify traits (e.g. HasFiles, HasLocalizedDisplayName). */
+    globalTraits: {
+        namespace: string;
+        path: string;
+    };
+    /**
+     * Backward-compat alias for `modules.path`. Kept so external callers and
+     * tests that read `config.modulesPath` keep working; new code should use
+     * `config.modules.path` instead.
+     * @deprecated use `modules.path`
+     */
     modulesPath: string;
     models: {
         namespace: string;

package/ts-dist/php/types.js

@@ -11,57 +11,81 @@ export function userFile(path, content) {
 }
 /**
  * Resolve base file path for a schema based on structure.
- * Modular: app/Modules/{SchemaName}/{category}/{fileName}
+ * Modular: {modules.path}/{SchemaName}/{category}/{fileName}
  * Legacy: {legacyPath}/{fileName}
  */
 export function resolveModularBasePath(config, schemaName, category, fileName, legacyPath) {
     if (config.structure === 'modular') {
-        return `${config.modulesPath}/${schemaName}/${category}/${fileName}`;
+        return `${config.modules.path}/${schemaName}/${category}/${fileName}`;
     }
     return `${legacyPath}/${fileName}`;
 }
 /**
  * Resolve base namespace for a schema based on structure.
- * Modular: App\Modules\{SchemaName}\{Category}
+ * Modular: {modules.namespace}\{SchemaName}\{Category}
  * Legacy: {legacyNamespace}
  */
 export function resolveModularBaseNamespace(config, schemaName, category, legacyNamespace) {
     if (config.structure === 'modular') {
-        return pathToNamespace(`${stripRootPath(config, config.modulesPath)}/${schemaName}/${category}`);
+        return `${config.modules.namespace}\\${schemaName}\\${category}`;
     }
     return legacyNamespace;
 }
 /**
- * Resolve shared base path (for cross-module files like BaseModel, HasLocalizedDisplayName).
- * Modular: app/Modules/Shared/{category}/{fileName}
+ * Resolve shared base path (for cross-module files like BaseModel).
+ * Modular: {shared.path}/{category}/{fileName}
  * Legacy: {legacyPath}/{fileName}
  */
 export function resolveSharedBasePath(config, category, fileName, legacyPath) {
     if (config.structure === 'modular') {
-        return `${config.modulesPath}/Shared/${category}/${fileName}`;
+        return `${config.shared.path}/${category}/${fileName}`;
     }
     return `${legacyPath}/${fileName}`;
 }
 /**
  * Resolve shared base namespace.
- * Modular: App\Modules\Shared\{Category}
+ * Modular: {shared.namespace}\{Category}
  * Legacy: {legacyNamespace}
  */
 export function resolveSharedBaseNamespace(config, category, legacyNamespace) {
     if (config.structure === 'modular') {
-        return pathToNamespace(`${stripRootPath(config, config.modulesPath)}/Shared/${category}`);
+        return `${config.shared.namespace}\\${category}`;
     }
     return legacyNamespace;
 }
-/** Strip the configured rootPath prefix from a filesystem path. */
-function stripRootPath(config, p) {
-    if (!config.rootPath)
-        return p;
-    if (p === config.rootPath)
-        return '';
-    if (p.startsWith(`${config.rootPath}/`))
-        return p.slice(config.rootPath.length + 1);
-    return p;
+/**
+ * Resolve global Omnify enum file path. Used for system enums that aren't tied
+ * to a single user-defined schema (e.g. FileStatusEnum belongs to the Omnify
+ * file-attachment subsystem). In modular mode these live under their own
+ * top-level folder so they're easy to find. In legacy mode the original
+ * `legacyPath` is preserved for backward compat.
+ */
+export function resolveGlobalEnumPath(config, fileName, legacyPath) {
+    if (config.structure === 'modular') {
+        return `${config.globalEnums.path}/${fileName}`;
+    }
+    return `${legacyPath}/${fileName}`;
+}
+/** Resolve global Omnify enum namespace. Modular: {globalEnums.namespace}. Legacy: passthrough. */
+export function resolveGlobalEnumNamespace(config, legacyNamespace) {
+    if (config.structure === 'modular') {
+        return config.globalEnums.namespace;
+    }
+    return legacyNamespace;
+}
+/** Resolve global Omnify trait file path (HasFiles, HasLocalizedDisplayName, ...). */
+export function resolveGlobalTraitPath(config, fileName, legacyPath) {
+    if (config.structure === 'modular') {
+        return `${config.globalTraits.path}/${fileName}`;
+    }
+    return `${legacyPath}/${fileName}`;
+}
+/** Resolve global Omnify trait namespace. */
+export function resolveGlobalTraitNamespace(config, legacyNamespace) {
+    if (config.structure === 'modular') {
+        return config.globalTraits.namespace;
+    }
+    return legacyNamespace;
 }
 /** Convert a file path to a PHP namespace (e.g., app/Models/Omnify → App\Models\Omnify). */
 function pathToNamespace(p) {
@@ -124,7 +148,13 @@ const DEFAULT_CONTROLLER_PATH = 'app/Http/Controllers/Omnify';
 const DEFAULT_SERVICE_PATH = 'app/Services/Omnify';
 const DEFAULT_ROUTE_PATH = 'routes/api/omnify';
 const DEFAULT_CONFIG_FILE_PATH = 'config/omnify-schemas.php';
-const DEFAULT_MODULES_PATH = 'app/Modules';
+// Modular base-class roots — issue #33. All Omnify auto-generated code lives
+// under `app/Omnify/` so it's clearly separated from team's manual `app/Modules/`
+// (Modular Monolith pattern), and easy to gitignore / nuke as a single tree.
+const DEFAULT_MODULES_PATH = 'app/Omnify/Modules';
+const DEFAULT_SHARED_PATH = 'app/Omnify/Shared';
+const DEFAULT_GLOBAL_ENUMS_PATH = 'app/Omnify/Enums';
+const DEFAULT_GLOBAL_TRAITS_PATH = 'app/Omnify/Traits';
 /**
  * Apply a rootPath prefix to a path. Absolute paths and paths that already
  * begin with `${rootPath}/` are returned as-is, so users can mix and match
@@ -166,14 +196,21 @@ export function derivePhpConfig(overrides) {
     const { path: policyPath, namespace: policyNs } = resolvePathAndNamespace(rootPath, overrides?.policy, DEFAULT_POLICY_PATH, nsFromPath);
     const { path: controllerPath, namespace: controllerNs } = resolvePathAndNamespace(rootPath, overrides?.controller, DEFAULT_CONTROLLER_PATH, nsFromPath);
     const { path: servicePath, namespace: serviceNs } = resolvePathAndNamespace(rootPath, overrides?.service, DEFAULT_SERVICE_PATH, nsFromPath);
+    const { path: modulesPath, namespace: modulesNs } = resolvePathAndNamespace(rootPath, overrides?.modules, DEFAULT_MODULES_PATH, nsFromPath);
+    const { path: sharedPath, namespace: sharedNs } = resolvePathAndNamespace(rootPath, overrides?.shared, DEFAULT_SHARED_PATH, nsFromPath);
+    const { path: globalEnumsPath, namespace: globalEnumsNs } = resolvePathAndNamespace(rootPath, overrides?.enums, DEFAULT_GLOBAL_ENUMS_PATH, nsFromPath);
+    const { path: globalTraitsPath, namespace: globalTraitsNs } = resolvePathAndNamespace(rootPath, overrides?.traits, DEFAULT_GLOBAL_TRAITS_PATH, nsFromPath);
     const routePath = withRoot(rootPath, overrides?.route?.path ?? DEFAULT_ROUTE_PATH);
     const configFilePath = withRoot(rootPath, overrides?.config?.path ?? DEFAULT_CONFIG_FILE_PATH);
     const nestedsetNs = overrides?.nestedset?.namespace ?? 'Aimeos\\Nestedset';
     const structure = overrides?.structure ?? 'legacy';
-    const modulesPath = withRoot(rootPath, DEFAULT_MODULES_PATH);
     return {
         rootPath,
         structure,
+        modules: { namespace: modulesNs, path: modulesPath },
+        shared: { namespace: sharedNs, path: sharedPath },
+        globalEnums: { namespace: globalEnumsNs, path: globalEnumsPath },
+        globalTraits: { namespace: globalTraitsNs, path: globalTraitsPath },
         modulesPath,
         models: {
             namespace: modelNs,