Path-based command naming instead of summary parsing

Derive CLI command names from URL path structure instead of parsing
English summaries. Rules:
- Strip common prefix shared by endpoints in the tag
- Remove path param segments ({id})
- Nothing left: 'list' (collection) or 'view' (single resource)
- Otherwise: use remaining path segments as the name
- Fix redundancy: 'cycode groups groups' -> 'cycode groups list'
- Duplicates (deprecated endpoints) get -v2 suffix

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: MaorDavidzon

cycode/cli/apps/api/api_command.py

@@ -29,33 +29,48 @@ def _normalize_tag(tag: str) -> str:
     return re.sub(r'[^a-z0-9]+', '-', tag.lower()).strip('-')
 
 
-def _normalize_command_name(summary: str) -> str:
-    """Derive a CLI subcommand name from an endpoint summary."""
-    s = summary.strip()
-    lower = s.lower()
-
-    if lower.startswith(('get all ', 'fetch all ', 'list all ', 'retrieve a paginated list of ')):
-        return 'list'
-    if lower.startswith('list '):
-        return 'list'
-    if lower.startswith(('fetch ', 'retrieve ', 'get all')):
-        return 'list'
-
-    if re.match(r'^get\s+\w+\s+by\s+id$', lower):
-        return 'get'
-
-    if re.match(r'^(get|retrieve)\s+(a\s+)?\w+(\s+details)?$', lower):
-        return 'get'
+def _find_common_prefix(paths: list[str]) -> str:
+    """Find the longest common path prefix shared by all paths."""
+    if not paths:
+        return ''
+    if len(paths) == 1:
+        # For single-path tags, use the parent directory as prefix
+        return '/'.join(paths[0].split('/')[:-1])
+
+    common = paths[0]
+    for p in paths[1:]:
+        while not p.startswith(common + '/') and common != p:
+            common = '/'.join(common.split('/')[:-1])
+    return common
+
+
+def _path_to_command_name(path: str, common_prefix: str, has_path_params: bool) -> str:
+    """Derive a CLI command name from an API path relative to the tag's common prefix.
+
+    Rules:
+    1. Strip the common prefix shared by all endpoints in the tag
+    2. Remove path parameter segments ({id})
+    3. If nothing remains: 'list' (no path params) or 'view' (has path params)
+    4. Otherwise: use remaining segments joined with hyphens
+
+    Examples:
+        /v4/projects          (prefix=/v4/projects)  -> list
+        /v4/projects/{id}     (prefix=/v4/projects)  -> view
+        /v4/projects/assets   (prefix=/v4/projects)  -> assets
+        /v4/violations/count  (prefix=/v4/violations) -> count
+    """
+    # Strip common prefix
+    relative = path[len(common_prefix) :] if path.startswith(common_prefix) else path
+    relative = relative.strip('/')
 
-    # Take meaningful words after the verb
-    words = re.sub(r'[^a-z0-9\s]', '', lower).split()
-    skip_verbs = {'get', 'fetch', 'retrieve', 'list', 'find', 'search', 'a', 'an', 'the', 'all', 'by'}
-    meaningful = [w for w in words if w not in skip_verbs]
+    # Remove path parameter segments and empty parts
+    parts = [p for p in relative.split('/') if p and not p.startswith('{')]
 
-    if not meaningful:
-        return re.sub(r'[^a-z0-9]+', '-', lower).strip('-')
+    if not parts:
+        return 'view' if has_path_params else 'list'
 
-    return '-'.join(meaningful[:3])
+    # Join remaining segments with hyphens, normalize to kebab-case
+    return re.sub(r'[^a-z0-9]+', '-', '-'.join(parts).lower()).strip('-')
 
 
 def _param_to_option_name(name: str) -> str:
@@ -121,20 +136,29 @@ def build_api_command_groups(
 
         group = click.Group(name=tag_name, help=f'[EXPERIMENT] Cycode API: {tag}')
 
+        # Compute common prefix from all GET endpoint paths in this tag
+        get_endpoints = [ep for ep in endpoints if ep['method'] == 'get']
+        if not get_endpoints:
+            continue
+
+        clean_paths = [re.sub(r'/\{[^}]+\}', '', ep['path']) for ep in get_endpoints]
+        common_prefix = _find_common_prefix(clean_paths)
+
         used_names: dict[str, int] = {}
 
-        for endpoint in endpoints:
-            if endpoint['method'] != 'get':
-                continue
+        for endpoint in get_endpoints:
+            has_path_params = bool(endpoint['path_params'])
+            cmd_name = _path_to_command_name(endpoint['path'], common_prefix, has_path_params)
 
-            cmd_name = _normalize_command_name(endpoint['summary'])
+            # Fix redundancy: if command name matches the tag name, use list/view
+            # e.g. "cycode groups groups" -> "cycode groups list"
+            if cmd_name == tag_name or cmd_name == tag_name.replace('-', '_'):
+                cmd_name = 'view' if has_path_params else 'list'
 
+            # Handle duplicate names (e.g. deprecated + new endpoint for same resource)
             if cmd_name in used_names:
                 used_names[cmd_name] += 1
-                path_parts = endpoint['path'].strip('/').split('/')
-                suffix = path_parts[-1] if path_parts else str(used_names[cmd_name])
-                suffix = re.sub(r'[{}]', '', suffix)
-                cmd_name = f'{cmd_name}-{suffix}'
+                cmd_name = f'{cmd_name}-v{used_names[cmd_name]}'
             else:
                 used_names[cmd_name] = 1