@shanyucoder/flowgrid 0.1.0

package/adapters/laravel/php/src/ProjectResolver.php

@@ -0,0 +1,100 @@
+<?php
+
+declare(strict_types=1);
+
+namespace FlowGrid\Laravel\UnitGen;
+
+final class ProjectResolver
+{
+    /**
+     * @return array{targetRoot: string, laravelRoot: string, framework: string, profile: string}
+     */
+    public static function resolve(): array
+    {
+        $configured = getenv('FLOWGRID_PROJECT_ROOT');
+        if ($configured === false || $configured === '') {
+            throw new \RuntimeException('FLOWGRID_PROJECT_ROOT is required for Laravel generation');
+        }
+
+        $target = realpath($configured) ?: $configured;
+        $candidates = [$target, $target.DIRECTORY_SEPARATOR.'src'];
+        $laravelRoot = null;
+        foreach ($candidates as $candidate) {
+            if (
+                is_file($candidate.DIRECTORY_SEPARATOR.'artisan')
+                && is_file($candidate.DIRECTORY_SEPARATOR.'composer.json')
+            ) {
+                $laravelRoot = $candidate;
+                break;
+            }
+        }
+
+        if ($laravelRoot === null) {
+            throw new \RuntimeException(
+                "Laravel project not found under {$target}; expected artisan + composer.json at root or src/"
+            );
+        }
+
+        $composer = json_decode(
+            (string) file_get_contents($laravelRoot.DIRECTORY_SEPARATOR.'composer.json'),
+            true,
+            512,
+            JSON_THROW_ON_ERROR
+        );
+        $packages = array_merge($composer['require'] ?? [], $composer['require-dev'] ?? []);
+        $framework = $packages['laravel/framework'] ?? null;
+        if ($framework === null) {
+            throw new \RuntimeException('Target composer.json does not require laravel/framework');
+        }
+        if (!preg_match('/(^|[^\d])12(?:\.|[^\d]|$)/', (string) $framework)) {
+            throw new \RuntimeException(
+                "Laravel adapter profile modules-v1 requires Laravel 12 (found {$framework})"
+            );
+        }
+        if (!isset($packages['nwidart/laravel-modules'])) {
+            throw new \RuntimeException(
+                'Laravel adapter profile modules-v1 requires nwidart/laravel-modules'
+            );
+        }
+
+        return [
+            'targetRoot' => $target,
+            'laravelRoot' => $laravelRoot,
+            'framework' => (string) $framework,
+            'profile' => 'modules-v1',
+        ];
+    }
+
+    public static function assertContained(string $root, string $candidate, string $label = 'path'): string
+    {
+        $base = realpath($root) ?: $root;
+        $resolved = realpath(dirname($candidate));
+        $resolved = $resolved !== false
+            ? $resolved.DIRECTORY_SEPARATOR.basename($candidate)
+            : $candidate;
+        $baseNorm = rtrim(str_replace('\\', '/', $base), '/');
+        $candNorm = str_replace('\\', '/', $resolved);
+        if ($candNorm !== $baseNorm && !str_starts_with($candNorm, $baseNorm.'/')) {
+            throw new \RuntimeException("{$label} escapes target root: {$candidate}");
+        }
+
+        return $resolved;
+    }
+
+    public static function engineRoot(): string
+    {
+        return dirname(__DIR__);
+    }
+
+    public static function adapterRoot(): string
+    {
+        // adapters/laravel/php → adapters/laravel; or src/.flowgrid → parent product
+        $engine = self::engineRoot();
+        $parent = dirname($engine);
+        if (is_dir($parent.DIRECTORY_SEPARATOR.'registries')) {
+            return $parent;
+        }
+
+        return $engine;
+    }
+}

package/adapters/laravel/php/src/SpecExtract.php

@@ -0,0 +1,193 @@
+<?php
+
+declare(strict_types=1);
+
+namespace FlowGrid\Laravel\UnitGen;
+
+final class SpecExtract
+{
+    public static function resolveOpenApiPath(string $specFile): ?string
+    {
+        $candidate = dirname($specFile).DIRECTORY_SEPARATOR.'02-openapi.yaml';
+
+        return is_file($candidate) ? $candidate : null;
+    }
+
+    /**
+     * @param  array<string, mixed>  $spec
+     * @return array{module: string, entity: array<string, mixed>}|null
+     */
+    public static function findEntityInSpec(array $spec, string $entity): ?array
+    {
+        foreach ($spec['modules'] ?? [] as $mod) {
+            foreach ($mod['entities'] ?? [] as $ent) {
+                if (($ent['name'] ?? null) === $entity) {
+                    return ['module' => (string) ($mod['name'] ?? ''), 'entity' => $ent];
+                }
+            }
+        }
+
+        return null;
+    }
+
+    /** @param array<string, mixed> $spec @return list<string> */
+    public static function extractSearchRequestRuleKeys(array $spec, string $entity): array
+    {
+        $fromRequests = [];
+        foreach ($spec['requests'] ?? [] as $name => $def) {
+            $nameStr = (string) $name;
+            if (
+                !str_contains($nameStr, 'SearchRequest')
+                && !str_contains(strtolower($nameStr), strtolower($entity))
+            ) {
+                continue;
+            }
+            foreach ($def['fields'] ?? [] as $field) {
+                if (!empty($field['name'])) {
+                    $fromRequests[] = (string) $field['name'];
+                }
+            }
+        }
+
+        if ($fromRequests !== []) {
+            return array_values(array_unique($fromRequests));
+        }
+
+        return ['page', 'per_page', 'order_by', 'sorted_by'];
+    }
+
+    /** @param array<string, mixed> $spec */
+    public static function extractPerPageDefault(array $spec): int
+    {
+        foreach ($spec['api']['endpoints'] ?? [] as $endpoint) {
+            if (($endpoint['action'] ?? null) === 'search' && isset($endpoint['query']['perPageDefault'])) {
+                return (int) $endpoint['query']['perPageDefault'];
+            }
+        }
+
+        return 100;
+    }
+
+    /** @param array<string, mixed> $spec */
+    public static function extractSessionScopeColumn(array $spec, string $entity): ?string
+    {
+        $found = self::findEntityInSpec($spec, $entity);
+        $col = $found['entity']['scope']['bySession'] ?? null;
+
+        return $col !== null ? (string) $col : null;
+    }
+
+    /** @param array<string, mixed> $spec @return list<string> */
+    public static function extractRelationshipNames(array $spec, string $entity): array
+    {
+        $relationships = self::findEntityInSpec($spec, $entity)['entity']['relationships'] ?? [];
+        $names = [];
+        foreach ($relationships as $rel) {
+            if (!empty($rel['name'])) {
+                $names[] = (string) $rel['name'];
+            }
+        }
+
+        return $names;
+    }
+
+    /** @param array<string, mixed> $spec @return list<string> */
+    public static function extractHasManyRelationships(array $spec, string $entity): array
+    {
+        $relationships = self::findEntityInSpec($spec, $entity)['entity']['relationships'] ?? [];
+        $names = [];
+        foreach ($relationships as $rel) {
+            if (($rel['type'] ?? null) === 'hasMany' && !empty($rel['name'])) {
+                $names[] = (string) $rel['name'];
+            }
+        }
+
+        return $names;
+    }
+
+    /** @param array<string, mixed> $spec @return list<string> */
+    public static function extractResourceFieldKeys(array $spec, string $module, string $entity): array
+    {
+        $resourceName = $module.$entity.'Resource';
+        $def = $spec['responses'][$resourceName] ?? null;
+        if (!empty($def['fields']) && is_array($def['fields'])) {
+            $keys = [];
+            foreach ($def['fields'] as $field) {
+                if (!empty($field['name'])) {
+                    $keys[] = (string) $field['name'];
+                }
+            }
+
+            return $keys;
+        }
+
+        return ['id', 'name'];
+    }
+
+    /** @return list<string> */
+    public static function extractOpenApiSchemaKeys(?string $openapiPath, string $schemaName): array
+    {
+        if ($openapiPath === null || !is_file($openapiPath)) {
+            return [];
+        }
+
+        try {
+            $doc = SpecReader::parseYaml((string) file_get_contents($openapiPath));
+            $schema = $doc['components']['schemas'][$schemaName] ?? null;
+            if (!is_array($schema) || empty($schema['properties']) || !is_array($schema['properties'])) {
+                return [];
+            }
+
+            return array_map('strval', array_keys($schema['properties']));
+        } catch (\Throwable) {
+            return [];
+        }
+    }
+
+    public static function resolveOpenApiEntitySchemaName(string $module, string $entity): string
+    {
+        return $module.$entity;
+    }
+
+    /** @param array<string, mixed> $spec */
+    public static function inferModelFqcn(array $spec, string $entity, string $module): string
+    {
+        $found = self::findEntityInSpec($spec, $entity);
+        $mode = $found['entity']['mode'] ?? 'Tenant';
+        unset($module);
+
+        return 'App\\Models\\'.$mode.'\\'.$entity;
+    }
+
+    /**
+     * @param  array<string, mixed>  $spec
+     * @return array<string, mixed>
+     */
+    public static function buildBehavioralContext(array $spec, string $specFile, string $module, string $entity): array
+    {
+        $openapiPath = self::resolveOpenApiPath($specFile);
+        $openApiSchema = self::resolveOpenApiEntitySchemaName($module, $entity);
+        $openApiKeys = self::extractOpenApiSchemaKeys($openapiPath, $openApiSchema);
+        $resourceKeys = self::extractResourceFieldKeys($spec, $module, $entity);
+        $displayKeys = $openApiKeys !== [] ? $openApiKeys : $resourceKeys;
+        $hasManyRelations = self::extractHasManyRelationships($spec, $entity);
+
+        return [
+            'searchRequestClass' => $entity.'SearchRequest',
+            'searchRequestFqcn' => "Modules\\{$module}\\Http\\Requests\\{$entity}SearchRequest",
+            'ruleKeys' => self::extractSearchRequestRuleKeys($spec, $entity),
+            'perPageDefault' => self::extractPerPageDefault($spec),
+            'sessionScopeColumn' => self::extractSessionScopeColumn($spec, $entity),
+            'relationshipNames' => self::extractRelationshipNames($spec, $entity),
+            'hasManyRelations' => $hasManyRelations,
+            'resourceKeys' => $displayKeys,
+            'openApiKeys' => $displayKeys,
+            'nestedRelationKey' => $hasManyRelations[0] ?? 'managers',
+            'modelFqcn' => self::inferModelFqcn($spec, $entity, $module),
+            'entityQueryFqcn' => "Modules\\{$module}\\Http\\Queries\\{$entity}Query",
+            'entityActionFqcn' => "Modules\\{$module}\\Http\\Actions\\{$entity}Action",
+            'entityResourceFqcn' => "Modules\\{$module}\\Http\\Resources\\{$entity}Resource",
+            'openApiSchema' => $openApiSchema,
+        ];
+    }
+}

package/adapters/laravel/php/src/SpecReader.php

@@ -0,0 +1,57 @@
+<?php
+
+declare(strict_types=1);
+
+namespace FlowGrid\Laravel\UnitGen;
+
+final class SpecReader
+{
+    /**
+     * @return array{spec: array<string, mixed>, specFile: string, featureDir: string, raw: string}
+     */
+    public static function read(string $specPath): array
+    {
+        $absolute = realpath($specPath) ?: (string) (new \SplFileInfo($specPath))->getRealPath();
+        if ($absolute === '' || !is_file($specPath)) {
+            $absolute = (string) realpath(dirname($specPath));
+            if ($absolute === '') {
+                throw new \RuntimeException("Spec file not found: {$specPath}");
+            }
+            $absolute = $absolute.DIRECTORY_SEPARATOR.basename($specPath);
+        }
+        if (!is_file($absolute) && is_file($specPath)) {
+            $absolute = $specPath;
+        }
+        if (!is_file($absolute)) {
+            throw new \RuntimeException("Spec file not found: {$specPath}");
+        }
+
+        $raw = (string) file_get_contents($absolute);
+        $spec = self::parseYaml($raw);
+        $parent = dirname($absolute);
+        $featureDir = basename($parent) === 'backend' ? dirname($parent) : $parent;
+
+        return [
+            'spec' => $spec,
+            'specFile' => $absolute,
+            'featureDir' => $featureDir,
+            'raw' => $raw,
+        ];
+    }
+
+    /**
+     * @return array<string, mixed>
+     */
+    public static function parseYaml(string $raw): array
+    {
+        if (!class_exists(\Symfony\Component\Yaml\Yaml::class)) {
+            throw new \RuntimeException(
+                'symfony/yaml is required. Add "symfony/yaml" to the product composer.json require-dev.'
+            );
+        }
+
+        $parsed = \Symfony\Component\Yaml\Yaml::parse($raw);
+
+        return is_array($parsed) ? $parsed : [];
+    }
+}

package/adapters/laravel/php/src/TemplateRenderer.php

@@ -0,0 +1,134 @@
+<?php
+
+declare(strict_types=1);
+
+namespace FlowGrid\Laravel\UnitGen;
+
+final class TemplateRenderer
+{
+    public static function templatesDir(): string
+    {
+        return ProjectResolver::engineRoot().DIRECTORY_SEPARATOR.'templates';
+    }
+
+    /**
+     * @param  array<string, mixed>  $context
+     */
+    public static function render(string $templateRel, array $context): string
+    {
+        $path = self::resolveTemplatePath($templateRel);
+        $source = (string) file_get_contents($path);
+        $rendered = self::renderSource($source, $context);
+
+        return rtrim($rendered)."\n";
+    }
+
+    public static function resolveTemplatePath(string $templateRel): string
+    {
+        $dir = self::templatesDir();
+        $candidates = [$templateRel];
+        if (str_ends_with($templateRel, '.hbs')) {
+            $candidates[] = preg_replace('/\.hbs$/', '.stub', $templateRel) ?? $templateRel;
+            $candidates[] = preg_replace('/\.php\.hbs$/', '.php.stub', $templateRel) ?? $templateRel;
+        }
+
+        foreach ($candidates as $rel) {
+            $path = $dir.DIRECTORY_SEPARATOR.str_replace('/', DIRECTORY_SEPARATOR, $rel);
+            if (is_file($path)) {
+                return $path;
+            }
+        }
+
+        throw new \RuntimeException("Template not found: {$templateRel} under {$dir}");
+    }
+
+    /**
+     * Minimal Handlebars-compatible renderer for current Laravel unitgen stubs.
+     * Supports: {{var}}, {{phpFqcn var}}, {{phpStringArray var}}, {{json var}}, {{eq a b}} (unused in stubs).
+     *
+     * @param  array<string, mixed>  $context
+     */
+    public static function renderSource(string $source, array $context): string
+    {
+        return (string) preg_replace_callback(
+            '/\{\{\s*(?:(phpFqcn|phpStringArray|json|eq)\s+)?([^}]+?)\s*\}\}/',
+            static function (array $m) use ($context): string {
+                $helper = $m[1] ?? '';
+                $expr = trim($m[2]);
+                if ($helper === 'phpFqcn') {
+                    return self::phpFqcn(self::lookup($context, $expr));
+                }
+                if ($helper === 'phpStringArray') {
+                    return self::phpStringArray(self::lookup($context, $expr));
+                }
+                if ($helper === 'json') {
+                    return json_encode(self::lookup($context, $expr), JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES) ?: 'null';
+                }
+                if ($helper === 'eq') {
+                    $parts = preg_split('/\s+/', $expr) ?: [];
+
+                    return (self::lookup($context, $parts[0] ?? '') == self::lookup($context, $parts[1] ?? '')) ? '1' : '';
+                }
+
+                $value = self::lookup($context, $expr);
+                if (is_bool($value)) {
+                    return $value ? '1' : '';
+                }
+                if (is_array($value) || is_object($value)) {
+                    return json_encode($value, JSON_UNESCAPED_SLASHES) ?: '';
+                }
+
+                return (string) $value;
+            },
+            $source
+        );
+    }
+
+    /** @param array<string, mixed> $context */
+    private static function lookup(array $context, string $key): mixed
+    {
+        $key = trim($key);
+        if ($key === '') {
+            return null;
+        }
+        if (array_key_exists($key, $context)) {
+            return $context[$key];
+        }
+        // dotted path
+        $parts = explode('.', $key);
+        $cur = $context;
+        foreach ($parts as $part) {
+            if (!is_array($cur) || !array_key_exists($part, $cur)) {
+                return null;
+            }
+            $cur = $cur[$part];
+        }
+
+        return $cur;
+    }
+
+    private static function phpFqcn(mixed $fqcn): string
+    {
+        $name = (string) ($fqcn ?? '');
+        if ($name === '') {
+            return '';
+        }
+
+        return str_starts_with($name, '\\') ? $name : '\\'.$name;
+    }
+
+    private static function phpStringArray(mixed $items): string
+    {
+        $arr = is_array($items) ? $items : [];
+        $encoded = array_map(
+            static function ($item): string {
+                $s = str_replace(['\\', "'"], ['\\\\', "\\'"], (string) $item);
+
+                return "'{$s}'";
+            },
+            $arr
+        );
+
+        return '['.implode(', ', $encoded).']';
+    }
+}