feat: Implement JSDoc parser and composer

- Add parser module to parse JSDoc strings into structured dictionaries.
- Add composer module to compose JSDoc strings from structured dictionaries.
- Introduce utility functions for extracting type information, merging JSDoc objects, and removing components from JSDoc objects.
- Create a command-line interface for parsing and composing JSDoc strings.
- Add tests for parser, composer, utilities, and integration to ensure functionality and correctness.
- Initialize package with pyproject.toml for packaging and distribution.

Author: sumansaurabh

Pipfile

@@ -0,0 +1,11 @@
+[[source]]
+url = "https://pypi.org/simple"
+verify_ssl = true
+name = "pypi"
+
+[packages]
+
+[dev-packages]
+
+[requires]
+python_version = "3.11"

README.md

@@ -0,0 +1,51 @@
+# JSDoc Parser
+
+A Python library for parsing and composing JSDoc strings.
+
+## Installation
+
+```bash
+pip install jsdoc-parser
+```
+
+## Usage
+
+```python
+from jsdoc_parser import parse_jsdoc, compose_jsdoc
+
+# Parse a JSDoc string into an object
+jsdoc_str = """/**
+ * Calculates the sum of two numbers
+ * @param {number} a - First number
+ * @param {number} b - Second number
+ * @returns {number} The sum of a and b
+ */"""
+
+parsed = parse_jsdoc(jsdoc_str)
+print(parsed)
+# Output: {'description': 'Calculates the sum of two numbers', 'params': [{'name': 'a', 'type': 'number', 'description': 'First number'}, {'name': 'b', 'type': 'number', 'description': 'Second number'}], 'returns': {'type': 'number', 'description': 'The sum of a and b'}}
+
+# Modify the parsed object
+parsed['params'][0]['description'] = 'Modified description'
+
+# Compose the modified object back to a JSDoc string
+new_jsdoc = compose_jsdoc(parsed)
+print(new_jsdoc)
+```
+
+## Features
+
+- Parse JSDoc strings into structured Python objects
+- Compose JSDoc objects back into properly formatted JSDoc strings
+- Support for various JSDoc tags: @param, @returns, @throws, etc.
+- Easy manipulation of JSDoc components
+
+## Contributing
+
+Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.
+
+Please make sure to update tests as appropriate.
+
+## License
+
+[MIT](https://choosealicense.com/licenses/mit/)

docstring_parser/__init__.py

@@ -0,0 +1,17 @@
+"""JSDoc parser package initialization."""
+
+from docstring_parser.parser import parse_jsdoc
+from docstring_parser.composer import compose_jsdoc
+from docstring_parser.utils import (
+    extract_type_info,
+    merge_jsdoc_objects,
+    remove_jsdoc_component
+)
+
+__all__ = [
+    'parse_jsdoc',
+    'compose_jsdoc',
+    'extract_type_info',
+    'merge_jsdoc_objects',
+    'remove_jsdoc_component'
+]

docstring_parser/cli.py

@@ -0,0 +1,98 @@
+#!/usr/bin/env python
+"""
+Command-line interface for the JSDoc parser library.
+
+This script provides a simple command-line interface for parsing and composing JSDoc strings.
+"""
+
+import argparse
+import json
+import sys
+from docstring_parser.parser import parse_jsdoc
+from docstring_parser.composer import compose_jsdoc
+from docstring_parser.utils import remove_jsdoc_component
+
+
+def main():
+    """Entry point for the command-line interface."""
+    parser = argparse.ArgumentParser(description='Parse and compose JSDoc strings')
+    subparsers = parser.add_subparsers(dest='command', required=True, help='Command to execute')
+    
+    # Parse command
+    parse_parser = subparsers.add_parser('parse', help='Parse a JSDoc string into a JSON object')
+    parse_parser.add_argument('file', type=str, nargs='?', help='File containing a JSDoc string (or use stdin)')
+    parse_parser.add_argument('-o', '--output', type=str, help='Output file (default: stdout)')
+    
+    # Compose command
+    compose_parser = subparsers.add_parser('compose', help='Compose a JSDoc string from a JSON object')
+    compose_parser.add_argument('file', type=str, nargs='?', help='JSON file containing a JSDoc object (or use stdin)')
+    compose_parser.add_argument('-o', '--output', type=str, help='Output file (default: stdout)')
+    
+    # Remove component command
+    remove_parser = subparsers.add_parser('remove', help='Remove a component from a JSDoc object')
+    remove_parser.add_argument('file', type=str, nargs='?', help='JSON file containing a JSDoc object (or use stdin)')
+    remove_parser.add_argument('-t', '--type', type=str, required=True,
+                           choices=['description', 'param', 'returns', 'throws', 'example', 'tag'],
+                           help='Type of component to remove')
+    remove_parser.add_argument('-i', '--identifier', type=str,
+                           help='Identifier of the component (e.g., param name, tag name)')
+    remove_parser.add_argument('-o', '--output', type=str, help='Output file (default: stdout)')
+    remove_parser.add_argument('-f', '--format', type=str, choices=['json', 'jsdoc'], default='json',
+                            help='Output format: json or jsdoc (default: json)')
+    
+    args = parser.parse_args()
+    
+    # Handle input
+    input_data = ''
+    if args.file:
+        with open(args.file, 'r', encoding='utf-8') as f:
+            input_data = f.read()
+    else:
+        input_data = sys.stdin.read()
+    
+    # Process commands
+    if args.command == 'parse':
+        try:
+            result = parse_jsdoc(input_data)
+            output = json.dumps(result, indent=2)
+        except Exception as e:
+            print(f"Error parsing JSDoc: {str(e)}", file=sys.stderr)
+            sys.exit(1)
+    
+    elif args.command == 'compose':
+        try:
+            jsdoc_obj = json.loads(input_data)
+            output = compose_jsdoc(jsdoc_obj)
+        except json.JSONDecodeError:
+            print("Error: Input is not valid JSON", file=sys.stderr)
+            sys.exit(1)
+        except Exception as e:
+            print(f"Error composing JSDoc: {str(e)}", file=sys.stderr)
+            sys.exit(1)
+    
+    elif args.command == 'remove':
+        try:
+            jsdoc_obj = json.loads(input_data)
+            result = remove_jsdoc_component(jsdoc_obj, args.type, args.identifier)
+            
+            if args.format == 'json':
+                output = json.dumps(result, indent=2)
+            else:  # jsdoc format
+                output = compose_jsdoc(result)
+        except json.JSONDecodeError:
+            print("Error: Input is not valid JSON", file=sys.stderr)
+            sys.exit(1)
+        except Exception as e:
+            print(f"Error removing component: {str(e)}", file=sys.stderr)
+            sys.exit(1)
+    
+    # Handle output
+    if args.output:
+        with open(args.output, 'w', encoding='utf-8') as f:
+            f.write(output)
+    else:
+        print(output)
+
+
+if __name__ == '__main__':
+    main()

docstring_parser/composer.py

@@ -0,0 +1,84 @@
+"""Composer module for JSDoc strings."""
+
+from typing import Dict, List, Any, Union
+
+
+def compose_jsdoc(jsdoc_obj: Dict[str, Any]) -> str:
+    """
+    Compose a JSDoc string from a structured dictionary.
+    
+    Args:
+        jsdoc_obj (Dict[str, Any]): The dictionary representing the JSDoc structure
+        
+    Returns:
+        str: The formatted JSDoc string
+        
+    Example:
+        >>> compose_jsdoc({'description': 'Description', 'params': [{'name': 'name', 'type': 'string', 'description': 'The name'}]})
+        '/**\\n * Description\\n * @param {string} name - The name\\n */'
+    """
+    lines = ['/**']
+    
+    # Add the description
+    if 'description' in jsdoc_obj and jsdoc_obj['description']:
+        for line in jsdoc_obj['description'].split('\n'):
+            lines.append(f' * {line}')
+        lines.append(' *')
+    
+    # Add the params
+    if 'params' in jsdoc_obj:
+        for param in jsdoc_obj['params']:
+            param_str = ' * @param'
+            
+            if 'type' in param and param['type']:
+                param_str += f' {{{param["type"]}}}'
+                
+            if 'name' in param and param['name']:
+                param_str += f' {param["name"]}'
+                
+            if 'description' in param and param['description']:
+                param_str += f' - {param["description"]}'
+                
+            lines.append(param_str)
+    
+    # Add the returns
+    if 'returns' in jsdoc_obj and jsdoc_obj['returns']:
+        returns_str = ' * @returns'
+        
+        if 'type' in jsdoc_obj['returns'] and jsdoc_obj['returns']['type']:
+            returns_str += f' {{{jsdoc_obj["returns"]["type"]}}}'
+            
+        if 'description' in jsdoc_obj['returns'] and jsdoc_obj['returns']['description']:
+            returns_str += f' {jsdoc_obj["returns"]["description"]}'
+            
+        lines.append(returns_str)
+    
+    # Add the throws
+    if 'throws' in jsdoc_obj:
+        for throws in jsdoc_obj['throws']:
+            throws_str = ' * @throws'
+            
+            if 'type' in throws and throws['type']:
+                throws_str += f' {{{throws["type"]}}}'
+                
+            if 'description' in throws and throws['description']:
+                throws_str += f' {throws["description"]}'
+                
+            lines.append(throws_str)
+    
+    # Add the examples
+    if 'examples' in jsdoc_obj:
+        for example in jsdoc_obj['examples']:
+            lines.append(f' * @example {example}')
+    
+    # Add other tags
+    if 'tags' in jsdoc_obj:
+        for tag, values in jsdoc_obj['tags'].items():
+            for value in values:
+                lines.append(f' * @{tag} {value}')
+    
+    # Add the closing marker
+    lines.append(' */')
+    
+    # Return the composed JSDoc string
+    return '\n'.join(lines)