Add Read more URL to Role.updateCurrentEnvironmentPermissions and tests

Add JSDoc Read more URL to updateCurrentEnvironmentPermissions so it gets
grouped under /role/update by extractResourcesEndpointMethods. Add tests
for extractAllMethodNames on roles and extractResourcesEndpointMethods.

Author: stefanoverna

packages/cma-client-analysis/__tests__/code-analysis.test.ts

@@ -1,8 +1,10 @@
 import assert from 'node:assert';
+import type { ResourcesEndpoint } from '@datocms/rest-api-reference';
 import {
   type CmaClientProgram,
   extractAllMethodNames,
   extractMethodSignature,
+  extractResourcesEndpointMethods,
   extractTypeDependencies,
   getCmaClientProgram,
 } from '../src';
@@ -51,6 +53,19 @@ describe('TypeScript Compiler API - Unit Tests', () => {
       expect(methodNames).toContain('updateFromUrl');
     }, 10000);
 
+    it('should extract all method names from roles resource including special methods', () => {
+      const { checker, clientClass } = cma;
+
+      const methodNames = extractAllMethodNames(checker, clientClass, 'roles');
+
+      expect(methodNames).toBeDefined();
+      expect(methodNames.length).toBeGreaterThan(0);
+      expect(methodNames).toContain('create');
+      expect(methodNames).toContain('update');
+      expect(methodNames).toContain('duplicate');
+      expect(methodNames).toContain('updateCurrentEnvironmentPermissions');
+    }, 10000);
+
     it('should return empty array for invalid resource', () => {
       const { checker, clientClass } = cma;
 
@@ -199,6 +214,89 @@ describe('TypeScript Compiler API - Unit Tests', () => {
     }, 10000);
   });
 
+  describe('extractResourcesEndpointMethods', () => {
+    // Minimal endpoint shape: extractResourcesEndpointMethods only reads
+    // `namespace` and `docUrl`. Cast through unknown to avoid spelling out
+    // every required field on ResourcesEndpoint.
+    const makeEndpoint = (
+      namespace: string,
+      docUrl: string,
+    ): ResourcesEndpoint => ({ namespace, docUrl }) as unknown as ResourcesEndpoint;
+
+    it('groups items.list/rawList/listPagedIterator/rawListPagedIterator under /item/instances', () => {
+      const { checker, clientClass } = cma;
+
+      const methods = extractResourcesEndpointMethods(
+        checker,
+        clientClass,
+        makeEndpoint(
+          'items',
+          'https://www.datocms.com/docs/content-management-api/resources/item/instances',
+        ),
+      );
+
+      const names = methods.map((m) => m.name).sort();
+      expect(names).toEqual(
+        [
+          'list',
+          'listPagedIterator',
+          'rawList',
+          'rawListPagedIterator',
+        ].sort(),
+      );
+
+      for (const m of methods) {
+        expect(m.functionDefinition).toContain(m.name);
+        expect(m.referencedTypes.size).toBeGreaterThan(0);
+      }
+    }, 10000);
+
+    it('groups roles.update and rawUpdate under /role/update', () => {
+      const { checker, clientClass } = cma;
+
+      const methods = extractResourcesEndpointMethods(
+        checker,
+        clientClass,
+        makeEndpoint(
+          'roles',
+          'https://www.datocms.com/docs/content-management-api/resources/role/update',
+        ),
+      );
+
+      const names = methods.map((m) => m.name).sort();
+      expect(names).toContain('update');
+      expect(names).toContain('rawUpdate');
+      expect(names).toContain('updateCurrentEnvironmentPermissions');
+    }, 10000);
+
+    it('returns empty array for an unknown docUrl', () => {
+      const { checker, clientClass } = cma;
+
+      const methods = extractResourcesEndpointMethods(
+        checker,
+        clientClass,
+        makeEndpoint('items', 'https://example.invalid/does/not/exist'),
+      );
+
+      expect(methods).toEqual([]);
+    }, 10000);
+
+    it('returns empty array for an unknown namespace', () => {
+      const { checker, clientClass } = cma;
+
+      const methods = extractResourcesEndpointMethods(
+        checker,
+        clientClass,
+        makeEndpoint(
+          'invalid_resource_xyz',
+          'https://www.datocms.com/docs/content-management-api/resources/item/instances',
+        ),
+      );
+
+      expect(methods).toEqual([]);
+    }, 10000);
+  });
+
   describe('extractTypeDependencies', () => {
     it('should handle empty type list', () => {
       const { program, checker } = cma;

packages/cma-client/src/resources/Role.ts

@@ -95,6 +95,8 @@ function applyChanges<T extends Record<PropertyKey, unknown>>(
 export default class RoleResource extends BaseRole {
   /**
    * Applies a set of changes to the permissions of the current environment
+   *
+   * Read more: https://www.datocms.com/docs/content-management-api/resources/role/update
    */
   async updateCurrentEnvironmentPermissions(
     roleId: string | ApiTypes.RoleData,