feat: capability can apply to entire permission class (#36)

* feat: update stubs to follow patterns

* feat: capability can apply to entire permission class

Author: shavonn

src/Attributes/Capability.php

@@ -9,17 +9,26 @@
 /**
  * Assigns a permission to a capability during sync.
  *
- * Multiple Capability attributes can be applied to assign a permission to multiple capabilities.
+ * Can be applied at the class level to assign all permissions in the class to a capability,
+ * or at the constant level for individual permissions. Multiple attributes can be applied
+ * to assign a permission to multiple capabilities.
  *
- * @example
+ * @example Class-level (all permissions inherit):
+ * #[Capability('user-management')]
+ * class UserPermissions
+ * {
+ *     public const VIEW = 'user:view';
+ *     public const EDIT = 'user:edit';
+ * }
+ * @example Constant-level:
  * #[Capability('user-management')]
  * public const VIEW = 'user:view';
- *
+ * @example Multiple capabilities:
  * #[Capability('user-management')]
  * #[Capability('reporting')]
  * public const EXPORT = 'user:export';
  */
-#[Attribute(Attribute::TARGET_CLASS_CONSTANT | Attribute::IS_REPEATABLE)]
+#[Attribute(Attribute::TARGET_CLASS | Attribute::TARGET_CLASS_CONSTANT | Attribute::IS_REPEATABLE)]
 final readonly class Capability
 {
     public function __construct(

src/CodeFirst/DefinitionDiscoverer.php

@@ -155,6 +155,7 @@ private function extractPermissionsFromClass(ReflectionClass $class): array
         $classGuard = $this->getClassGuard($class);
         $classLabel = $this->getClassAttribute($class, Label::class)?->value;
         $classDescription = $this->getClassAttribute($class, Description::class)?->value;
+        $classCapabilities = $this->getClassCapabilityNames($class);
 
         foreach ($class->getReflectionConstants(ReflectionClassConstant::IS_PUBLIC) as $constant) {
             $value = $constant->getValue();
@@ -166,14 +167,15 @@ private function extractPermissionsFromClass(ReflectionClass $class): array
             $labelAttr = $this->getConstantAttribute($constant, Label::class);
             $descAttr = $this->getConstantAttribute($constant, Description::class);
             $contextAttr = $this->getConstantAttribute($constant, Context::class);
+            $constantCapabilities = $this->getCapabilityNames($constant);
 
             $definitions[] = PermissionDefinition::fromAttributes([
                 'name' => $value,
                 'guard' => $classGuard,
                 'label' => $labelAttr !== null ? $labelAttr->value : $classLabel,
                 'description' => $descAttr !== null ? $descAttr->value : $classDescription,
                 'context' => $contextAttr?->modelClass,
-                'capabilities' => $this->getCapabilityNames($constant),
+                'capabilities' => array_unique(array_merge($classCapabilities, $constantCapabilities)),
                 'source_class' => $class->getName(),
                 'source_constant' => $constant->getName(),
             ]);
@@ -321,4 +323,20 @@ private function getCapabilityNames(ReflectionClassConstant $constant): array
             $attributes
         );
     }
+
+    /**
+     * Get all capability names from a class's Capability attributes.
+     *
+     * @param  ReflectionClass<object>  $class
+     * @return array<string>
+     */
+    private function getClassCapabilityNames(ReflectionClass $class): array
+    {
+        $attributes = $class->getAttributes(CapabilityAttribute::class);
+
+        return array_map(
+            fn ($attr) => $attr->newInstance()->name,
+            $attributes
+        );
+    }
 }

stubs/capability.stub

@@ -11,7 +11,7 @@ use OffloadProject\Mandate\Attributes\Label;
 #[Guard('{{ guard }}')]
 final class {{ class }}
 {
-    #[Label('{{ capability }} Management')]
+    #[Label('Manage {{ capability }}')]
     #[Description('Manage {{ capability }} resources')]
-    public const MANAGE = '{{ capability }}-management';
+    public const MANAGE = 'manage-{{ capability }}';
 }

stubs/permission.stub

@@ -11,19 +11,23 @@ use OffloadProject\Mandate\Attributes\Label;
 #[Guard('{{ guard }}')]
 final class {{ class }}
 {
+    #[Label('View any {{ resource }}')]
+    #[Description('View any {{ resource }} records')]
+    public const VIEW_ANY = '{{ resource }}:view_any';
+
     #[Label('View {{ resource }}')]
-    #[Description('View {{ resource }} records')]
-    public const VIEW = '{{ resource }}.view';
+    #[Description('View {{ resource }} record')]
+    public const VIEW = '{{ resource }}:view';
 
     #[Label('Create {{ resource }}')]
     #[Description('Create new {{ resource }} records')]
-    public const CREATE = '{{ resource }}.create';
+    public const CREATE = '{{ resource }}:create';
 
     #[Label('Update {{ resource }}')]
     #[Description('Update existing {{ resource }} records')]
-    public const UPDATE = '{{ resource }}.update';
+    public const UPDATE = '{{ resource }}:update';
 
     #[Label('Delete {{ resource }}')]
     #[Description('Delete {{ resource }} records')]
-    public const DELETE = '{{ resource }}.delete';
+    public const DELETE = '{{ resource }}:delete';
 }

tests/Fixtures/CodeFirst/UserPermissions.php

@@ -0,0 +1,24 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OffloadProject\Mandate\Tests\Fixtures\CodeFirst;
+
+use OffloadProject\Mandate\Attributes\Capability;
+use OffloadProject\Mandate\Attributes\Guard;
+use OffloadProject\Mandate\Attributes\Label;
+
+#[Guard('web')]
+#[Capability('user-management')]
+class UserPermissions
+{
+    #[Label('View Users')]
+    public const VIEW = 'user:view';
+
+    #[Label('Edit Users')]
+    public const EDIT = 'user:edit';
+
+    #[Label('Delete Users')]
+    #[Capability('admin-only')]
+    public const DELETE = 'user:delete';
+}

tests/Unit/CodeFirst/DefinitionDiscovererTest.php

@@ -64,6 +64,25 @@
 
             expect($permissions)->toBeEmpty();
         });
+
+        it('extracts capabilities from class-level attribute', function () {
+            $permissions = $this->discoverer->discoverPermissions($this->fixturesPath);
+
+            $viewPermission = $permissions->first(fn (PermissionDefinition $p) => $p->name === 'user:view');
+            $editPermission = $permissions->first(fn (PermissionDefinition $p) => $p->name === 'user:edit');
+
+            expect($viewPermission->capabilities)->toBe(['user-management']);
+            expect($editPermission->capabilities)->toBe(['user-management']);
+        });
+
+        it('merges class-level and constant-level capabilities', function () {
+            $permissions = $this->discoverer->discoverPermissions($this->fixturesPath);
+
+            $deletePermission = $permissions->first(fn (PermissionDefinition $p) => $p->name === 'user:delete');
+
+            expect($deletePermission->capabilities)->toContain('user-management', 'admin-only');
+            expect(count($deletePermission->capabilities))->toBe(2);
+        });
     });
 
     describe('discoverRoles', function () {