@omnifyjp/omnify 5.8.20 → 5.8.22

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@omnifyjp/omnify",
-  "version": "5.8.20",
+  "version": "5.8.22",
   "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": "5.8.20",
-    "@omnifyjp/omnify-darwin-x64": "5.8.20",
-    "@omnifyjp/omnify-linux-x64": "5.8.20",
-    "@omnifyjp/omnify-linux-arm64": "5.8.20",
-    "@omnifyjp/omnify-win32-x64": "5.8.20"
+    "@omnifyjp/omnify-darwin-arm64": "5.8.22",
+    "@omnifyjp/omnify-darwin-x64": "5.8.22",
+    "@omnifyjp/omnify-linux-x64": "5.8.22",
+    "@omnifyjp/omnify-linux-arm64": "5.8.22",
+    "@omnifyjp/omnify-win32-x64": "5.8.22"
   }
 }

package/ts-dist/php/architecture-doc-generator.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Architecture documentation generator. Issue #102 v5.8.21.
+ *
+ * Auto-emits a `docs/contributing/omnify-architecture.md` (or whichever
+ * path the project configured) describing the project's Omnify layout:
+ *
+ *   - Two-layer structure (auto-gen base zone + project-owned editable)
+ *   - Per-schema FQN reference table (computed from schemas.json + the
+ *     project's resolved codegen config)
+ *   - Hard rules + anti-patterns the project must follow
+ *   - Astrotomic translatable hookup, Pivot/Translation always-grouped
+ *
+ * The content is fully derivable from the codegen state — every Omnify
+ * project hand-wrote some version of this doc and let it drift the
+ * moment a schema changed. Auto-generating it keeps the doc
+ * consistent with the actual file layout, version after version.
+ */
+import { SchemaReader } from './schema-reader.js';
+import type { GeneratedFile, PhpConfig } from './types.js';
+/** Generate `omnify-architecture.md` describing the project's Omnify layout. */
+export declare function generateArchitectureDoc(reader: SchemaReader, config: PhpConfig): GeneratedFile[];

package/ts-dist/php/architecture-doc-generator.js

@@ -0,0 +1,156 @@
+/**
+ * Architecture documentation generator. Issue #102 v5.8.21.
+ *
+ * Auto-emits a `docs/contributing/omnify-architecture.md` (or whichever
+ * path the project configured) describing the project's Omnify layout:
+ *
+ *   - Two-layer structure (auto-gen base zone + project-owned editable)
+ *   - Per-schema FQN reference table (computed from schemas.json + the
+ *     project's resolved codegen config)
+ *   - Hard rules + anti-patterns the project must follow
+ *   - Astrotomic translatable hookup, Pivot/Translation always-grouped
+ *
+ * The content is fully derivable from the codegen state — every Omnify
+ * project hand-wrote some version of this doc and let it drift the
+ * moment a schema changed. Auto-generating it keeps the doc
+ * consistent with the actual file layout, version after version.
+ */
+import { toPascalCase } from './naming-helper.js';
+import { baseFile, nestByGroup } from './types.js';
+/** Generate `omnify-architecture.md` describing the project's Omnify layout. */
+export function generateArchitectureDoc(reader, config) {
+    const schemas = reader.getProjectVisibleObjectSchemas();
+    const allSchemaNames = Object.keys(schemas).sort();
+    if (allSchemaNames.length === 0)
+        return [];
+    // Group schemas by yaml group folder.
+    const byGroup = new Map();
+    for (const name of allSchemaNames) {
+        const schema = schemas[name];
+        const group = schema.group ?? '_root';
+        const arr = byGroup.get(group) ?? [];
+        arr.push(name);
+        byGroup.set(group, arr);
+    }
+    const groups = Array.from(byGroup.keys()).sort();
+    const lines = [];
+    // ── Header ────────────────────────────────────────────────────────────────
+    const today = new Date().toISOString().slice(0, 10);
+    lines.push('---');
+    lines.push('title: Omnify Architecture (auto-generated)');
+    lines.push(`generated_at: ${today}`);
+    lines.push('generated_by: omnify');
+    lines.push(`schema_count: ${allSchemaNames.length}`);
+    lines.push(`group_count: ${groups.length}`);
+    lines.push('---');
+    lines.push('');
+    lines.push('# Omnify Architecture');
+    lines.push('');
+    lines.push('> AUTO-GENERATED — do not edit. Regenerate via `omnify generate`.');
+    lines.push('');
+    lines.push('This project follows the Omnify v5.8.x canonical Laravel layout. The');
+    lines.push('`app/Omnify/` zone is owned by the codegen; `app/Models/`, `app/Http/`,');
+    lines.push('`app/Services/`, `app/Policies/` are project-owned and extend the');
+    lines.push('auto-gen bases.');
+    lines.push('');
+    // ── Layer map ─────────────────────────────────────────────────────────────
+    lines.push('## Layer map');
+    lines.push('');
+    lines.push('| Layer | Auto-gen base | User-editable (Laravel-canonical) |');
+    lines.push('|-------|---------------|-----------------------------------|');
+    lines.push(`| Model | \`${config.models.basePath}/<Group>/<Name>.php\` | \`${config.models.userEditablePath}/<Name>.php\` (FLAT) |`);
+    lines.push(`| Translation | \`${config.models.basePath}/Translation/<Name>Translation.php\` | \`${config.models.userEditablePath}/Translation/<Name>Translation.php\` |`);
+    lines.push(`| Pivot | \`${config.models.basePath}/Pivot/<Name>.php\` | \`${config.models.userEditablePath}/Pivot/<Name>.php\` |`);
+    lines.push(`| Enum | \`${config.globalEnums.path}/<Name>Enum.php\` | _(no user-editable)_ |`);
+    lines.push(`| Request | \`${config.requests.basePath}/<Group>/<Name>StoreRequest.php\` | \`${config.requests.userEditablePath}/<Name>StoreRequest.php\` (FLAT) |`);
+    lines.push(`| Resource | \`${config.resources.basePath}/<Group>/<Name>Resource.php\` | \`${config.resources.userEditablePath}/<Name>Resource.php\` (FLAT) |`);
+    lines.push(`| Service | \`${config.services.basePath}/<Group>/<Name>Service.php\` | \`${config.services.userEditablePath}/<Name>Service.php\` (FLAT) |`);
+    lines.push(`| Policy | \`${config.policies.basePath}/<Group>/<Name>Policy.php\` | \`${config.policies.userEditablePath}/<Name>Policy.php\` (FLAT) |`);
+    lines.push('');
+    // ── Per-schema FQN reference ──────────────────────────────────────────────
+    lines.push('## Schema → Base FQN reference');
+    lines.push('');
+    lines.push('Every schema in the project, organized by YAML group folder. The');
+    lines.push('FQN columns are the **base** classes — extend these from your');
+    lines.push('user-editable wrappers.');
+    lines.push('');
+    for (const group of groups) {
+        const groupNames = byGroup.get(group).sort();
+        const heading = group === '_root' ? '_ungrouped_' : group;
+        lines.push(`### ${heading} (${groupNames.length} schema${groupNames.length === 1 ? '' : 's'})`);
+        lines.push('');
+        lines.push('| Schema | Model base | Service base | Resource base | Request base | Policy base |');
+        lines.push('|---|---|---|---|---|---|');
+        for (const name of groupNames) {
+            const schema = schemas[name];
+            const modelName = toPascalCase(name);
+            const groupSegment = schema.group;
+            const isPivot = schema.kind === 'pivot';
+            const nestNs = (baseNs) => {
+                if (config.structure === 'modular')
+                    return baseNs;
+                if (isPivot)
+                    return `${baseNs}\\Pivot`;
+                if (groupSegment) {
+                    return nestByGroup({ path: '', namespace: baseNs }, groupSegment).namespace;
+                }
+                return baseNs;
+            };
+            const modelFqn = `${nestNs(config.models.baseNamespace)}\\${modelName}${config.models.flatBase ? '' : 'BaseModel'}`;
+            const serviceFqn = `${nestNs(config.services.baseNamespace)}\\${modelName}Service${config.services.flatBase ? '' : 'Base'}`;
+            const resourceFqn = `${nestNs(config.resources.baseNamespace)}\\${modelName}Resource${config.resources.flatBase ? '' : 'Base'}`;
+            const requestFqn = `${nestNs(config.requests.baseNamespace)}\\${modelName}StoreRequest${config.requests.flatBase ? '' : 'Base'}`;
+            const policyFqn = `${nestNs(config.policies.baseNamespace)}\\${modelName}Policy${config.policies.flatBase ? '' : 'Base'}`;
+            lines.push(`| ${modelName} | \`${modelFqn}\` | \`${serviceFqn}\` | \`${resourceFqn}\` | \`${requestFqn}\` | \`${policyFqn}\` |`);
+        }
+        lines.push('');
+    }
+    // ── Hard rules ────────────────────────────────────────────────────────────
+    lines.push('## Hard rules');
+    lines.push('');
+    lines.push('1. **Never edit anything under the `Omnify/` auto-gen zone.** Files');
+    lines.push('   here carry a `DO NOT EDIT` header and are overwritten on every');
+    lines.push('   `omnify generate`.');
+    lines.push('2. **Schema-derived classes MUST extend the omnify base.** Do not');
+    lines.push('   extend `Eloquent\\Model`, `JsonResource`, `FormRequest`, etc.');
+    lines.push('   directly when a base exists for that schema.');
+    lines.push('3. **User-editable lives at canonical Laravel paths** — flat at the');
+    lines.push('   top level (`app/Models/<Name>.php`, NOT `app/Models/<Group>/<Name>.php`).');
+    lines.push('4. **Custom (non-schema) classes go in subfolders**, not at the FLAT');
+    lines.push('   top (`app/Services/Auth/PasswordResetService.php`, etc.).');
+    lines.push('5. **Translation / Pivot / Enum always grouped** — even when other');
+    lines.push('   layers are flat, these three keep their dedicated subfolder.');
+    lines.push('6. **`config/translatable.php` must set `translation_model_namespace`**');
+    lines.push(`   to \`${config.models.userEditableNamespace}\\Translation\` so Astrotomic auto-resolves.`);
+    lines.push('');
+    // ── Anti-patterns ─────────────────────────────────────────────────────────
+    lines.push('## Anti-patterns');
+    lines.push('');
+    lines.push('- Editing files under the `Omnify/` auto-gen zone');
+    lines.push('- Re-declaring `$table` / `$fillable` / `$casts` in user-editable');
+    lines.push('  models (duplicates schema, drifts on next regeneration)');
+    lines.push('- Importing the auto-gen base namespace directly from controllers /');
+    lines.push('  services when a user-editable wrapper exists');
+    lines.push('- Adding manual `Gate::policy()` registrations for schema-derived');
+    lines.push('  models (Laravel auto-discovery handles them)');
+    lines.push('- Writing the same schema definition twice (once in YAML, once');
+    lines.push('  hand-written)');
+    lines.push('- Putting custom (non-schema) resources at the FLAT top-level path');
+    lines.push('');
+    // ── Footer ────────────────────────────────────────────────────────────────
+    lines.push('## Regenerate');
+    lines.push('');
+    lines.push('```bash');
+    lines.push('omnify generate');
+    lines.push('```');
+    lines.push('');
+    lines.push(`Last updated: ${today} by omnify.`);
+    lines.push('');
+    // Honor `rootPath` so monorepo layouts (`rootPath: backend`) get the
+    // doc emitted under `backend/docs/contributing/...` like the rest of
+    // the codegen output.
+    const docPath = config.rootPath
+        ? `${config.rootPath}/docs/contributing/omnify-architecture.md`
+        : 'docs/contributing/omnify-architecture.md';
+    return [baseFile(docPath, lines.join('\n'))];
+}

package/ts-dist/php/index.js

@@ -36,6 +36,7 @@ import { generateServices } from './service-generator.js';
 import { generateRoutes } from './route-generator.js';
 import { generateEnums } from './enum-generator.js';
 import { generateOpenApi } from './openapi-generator.js';
+import { generateArchitectureDoc } from './architecture-doc-generator.js';
 export { derivePhpConfig } from './types.js';
 /** Generate all PHP files from schemas.json data. */
 export function generatePhp(data, overrides) {
@@ -104,5 +105,11 @@ export function generatePhp(data, overrides) {
     files.push(...generateResources(reader, config));
     files.push(...generateFactories(reader, config));
     files.push(...generatePolicies(reader, config));
+    // Issue #102 v5.8.21: emit `docs/contributing/omnify-architecture.md`
+    // describing the project's resolved Omnify layout — layer paths,
+    // per-schema FQN reference, hard rules, anti-patterns. Pure additive;
+    // no behavior change for existing consumers, and the doc updates
+    // automatically as schemas / config change so it never drifts.
+    files.push(...generateArchitectureDoc(reader, config));
     return files;
 }

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

@@ -200,9 +200,21 @@ function warnLegacyServiceKeys(name, schema) {
     }
 }
 function generateForSchema(name, schema, reader, config) {
+    // Issue #101 v5.8.22: only emit the service BASE. The user-editable
+    // service stub is pure scaffolding (extends base, no body) for every
+    // schema in every project — 290+ noise files in a typical project.
+    // Consumers inject the BASE FQN directly:
+    //
+    //     public function __construct(
+    //         private \App\Omnify\Services\<Group>\<Name>ServiceBase \$service,
+    //     ) {}
+    //
+    // When custom logic IS needed, the dev creates the editable file by
+    // hand under the `userEditablePath` (`app/Services/<Name>Service.php`)
+    // — Laravel autoloads it like any other class. Omnify won't recreate
+    // it on subsequent generates because we no longer emit it at all.
     return [
         generateBaseService(name, schema, reader, config),
-        generateUserService(name, schema, config),
     ];
 }
 /**

package/ts-dist/php/sibling-skip.d.ts

@@ -38,5 +38,15 @@ export declare function findAppRootAncestor(filePath: string): string | null;
  * Scan `rootDir` recursively for a file whose basename matches
  * `baseName`, excluding `excludePath` itself. Returns the first
  * match's full path or null.
+ *
+ * Issue #99 v5.8.19 follow-up: skip the auto-gen `Omnify/` subtree
+ * (its files are codegen output, not project-owned siblings) so the
+ * editable layer at `app/Models/<Name>.php` doesn't get blocked by
+ * the sibling base at `app/Omnify/Models/<Group>/<Name>.php` under
+ * canonical+flatBase layout. Project-owned siblings under
+ * `app/Services/Omnify/<Name>Service.php` (v4 wrapper layout) DO still
+ * trigger a skip because they live OUTSIDE the auto-gen zone — the
+ * skip rule is "any directory whose name starts with `Omnify` is
+ * codegen-owned", which matches `Omnify/`, `OmnifyBase/`, etc.
  */
 export declare function findSiblingWithSameBasename(rootDir: string, baseName: string, excludePath: string): string | null;

package/ts-dist/php/sibling-skip.js

@@ -52,6 +52,16 @@ export function findAppRootAncestor(filePath) {
  * Scan `rootDir` recursively for a file whose basename matches
  * `baseName`, excluding `excludePath` itself. Returns the first
  * match's full path or null.
+ *
+ * Issue #99 v5.8.19 follow-up: skip the auto-gen `Omnify/` subtree
+ * (its files are codegen output, not project-owned siblings) so the
+ * editable layer at `app/Models/<Name>.php` doesn't get blocked by
+ * the sibling base at `app/Omnify/Models/<Group>/<Name>.php` under
+ * canonical+flatBase layout. Project-owned siblings under
+ * `app/Services/Omnify/<Name>Service.php` (v4 wrapper layout) DO still
+ * trigger a skip because they live OUTSIDE the auto-gen zone — the
+ * skip rule is "any directory whose name starts with `Omnify` is
+ * codegen-owned", which matches `Omnify/`, `OmnifyBase/`, etc.
  */
 export function findSiblingWithSameBasename(rootDir, baseName, excludePath) {
     let scanned = 0;
@@ -82,6 +92,15 @@ export function findSiblingWithSameBasename(rootDir, baseName, excludePath) {
                 continue;
             }
             if (stats.isDirectory()) {
+                // Skip the auto-gen `app/Omnify/` zone — its files are codegen
+                // outputs, not user-owned siblings. Detect via "directory is
+                // named `Omnify` AND its parent is named `app`": this catches
+                // the canonical `app/Omnify/` zone but does NOT skip
+                // `app/Services/Omnify/` (a v4 wrapper layout where `Omnify`
+                // is project-owned and should still trigger sibling-skip per
+                // issue #99 v5.8.19).
+                if (entry === 'Omnify' && basename(dir) === 'app')
+                    continue;
                 stack.push(fullPath);
             }
             else if (entry === baseName && fullPath !== excludePath) {