Skip to content

Commit 92ec250

Browse files
Cod-e-CodesCod-e-Codes
committed
docs: update README for Rust-based architecture
1 parent 2b5dac6 commit 92ec250

File tree

1 file changed

+106
-64
lines changed

1 file changed

+106
-64
lines changed

‎README.md‎

Lines changed: 106 additions & 64 deletions
Original file line numberDiff line numberDiff line change
@@ -4,106 +4,148 @@
44
[![Contributions welcome](https://img.shields.io/badge/contributions-welcome-brightgreen.svg)](CONTRIBUTING.md)
55
[![Code of Conduct](https://img.shields.io/badge/code%20of%20conduct-Contributor%20Covenant-blueviolet.svg)](CODE_OF_CONDUCT.md)
66

7-
> **🚀 Rust Summarizer Branch**: This branch replaces the Python summarizer with a high-performance Rust implementation, providing 10-50x faster processing and eliminating Python dependencies.
8-
9-
<!-- Note: Issue/PR/commit badges require a public repo and are omitted for privacy. -->
7+
**CodeSleuth** is a high-performance, multi-language code intelligence CLI tool designed for legacy COBOL analysis. Built with Rust and Go, it provides fast parsing, comprehensive analysis, and actionable insights for enterprise codebases.
108

119
---
1210

13-
**CodeSleuth** is a modern, multi-language code intelligence CLI tool focused on COBOL analysis. It combines a fast Rust parser, a Go CLI, and a Rust Markdown summarizer to provide actionable, human-friendly reports for legacy codebases.
11+
## 🚀 Features
12+
13+
- **⚡ High-Performance Parsing:** Rust-based COBOL parser with 10-50x faster processing
14+
- **📊 Comprehensive Analysis:** Program structure, data division, procedure logic, call/control flow, and I/O analysis
15+
- **📝 Rich Markdown Reports:** Detailed summaries with Mermaid diagrams for call and control flow visualization
16+
- **🔍 Dead Code Detection:** Identifies unused paragraphs and variables
17+
- **🏗️ Modular Architecture:** Clean separation between parser, CLI, and summarizer components
18+
- **🔧 Modern CLI:** Intuitive command-line interface with verbose/debug options
19+
- **🛡️ Security Focused:** Comprehensive security policy and responsible disclosure
20+
- **🔄 CI/CD Ready:** Automated testing and linting via GitHub Actions
1421

1522
---
1623

17-
## Features
18-
- **COBOL Parsing:** Extracts program structure, data division, procedure logic, call/control flow, and I/O.
19-
- **Markdown Summaries:** Generates clear, sectioned Markdown reports with Mermaid diagrams for call and control flow.
20-
- **Dead Code Detection:** Lists unused paragraphs and variables.
21-
- **Extensible Pipeline:** Modular Rust, Go, and Python components.
22-
- **Modern CLI:** Easy to use, with verbose/debug options.
23-
- **Security Policy:** See [SECURITY.md](SECURITY.md)
24-
- **Continuous Integration:** Automated tests and linting via GitHub Actions.
24+
## 🛠️ Architecture
25+
26+
CodeSleuth uses a modern, efficient architecture:
27+
28+
- **Rust Parser** (`parser/`): Fast COBOL parsing and IR generation
29+
- **Rust Summarizer** (`summarizer/`): High-performance Markdown report generation
30+
- **Go CLI** (`cmd/`): User-friendly command-line interface
31+
- **Cross-platform:** Works on Windows, macOS, and Linux
2532

2633
---
2734

28-
## Quickstart
35+
## 📦 Installation
2936

30-
### 1. Clone the Repo
31-
```sh
37+
### Prerequisites
38+
39+
- **Rust** (1.70+): [Install via rustup.rs](https://rustup.rs/)
40+
- **Go** (1.21+): [Download from golang.org](https://golang.org/dl/)
41+
- **Optional:** [Graphviz](https://graphviz.gitlab.io/) for advanced graph rendering
42+
43+
### Build from Source
44+
45+
```bash
46+
# Clone the repository
3247
git clone https://github.com/Cod-e-Codes/codesleuth.git
3348
cd codesleuth
34-
```
3549

36-
### 2. Install Requirements
37-
- **Rust** (for the parser and summarizer): https://rustup.rs/
38-
- **Go** (for the CLI): https://golang.org/dl/
39-
- (Optional) [Graphviz](https://graphviz.gitlab.io/) for advanced graph rendering
40-
41-
### 3. Build the Rust Components
42-
```sh
43-
# Build the parser
44-
cd parser
45-
cargo build --release
46-
cd ..
47-
48-
# Build the summarizer
49-
cd summarizer
50-
cargo build --release
51-
cd ..
50+
# Build Rust components
51+
cd parser && cargo build --release && cd ..
52+
cd summarizer && cargo build --release && cd ..
53+
54+
# Build Go CLI
55+
cd cmd && go build -o codesleuth && cd ..
5256
```
5357

54-
### 4. Build the Go CLI
55-
```sh
56-
cd cmd
57-
go build -o codesleuth.exe
58-
cd ..
58+
---
59+
60+
## 🚀 Quick Start
61+
62+
```bash
63+
# Analyze a COBOL file or directory
64+
./cmd/codesleuth analyze --verbose path/to/your/cobol/files
65+
66+
# Generate a report file
67+
./cmd/codesleuth analyze test-cobol/ > analysis_report.md
5968
```
6069

61-
**Note:** The Go CLI now calls the Rust summarizer instead of Python, providing better performance and eliminating Python dependencies.
70+
### Example Output
71+
72+
CodeSleuth generates comprehensive Markdown reports including:
73+
74+
- **Program Information:** Name, author, date, comments
75+
- **Data Division:** Working storage and file section analysis
76+
- **Procedure Division:** Paragraph structure and statement analysis
77+
- **Call Graph:** Visual representation of program flow
78+
- **Control Flow:** Detailed execution path analysis
79+
- **Variable Usage:** Read/write analysis for all variables
80+
- **Dead Code Detection:** Unused paragraphs and variables
6281

63-
### 5. Run CodeSleuth
64-
```sh
65-
./cmd/codesleuth.exe analyze --verbose path/to/your/cobol/files
82+
---
83+
84+
## 📋 Usage Examples
85+
86+
```bash
87+
# Analyze a single file
88+
./cmd/codesleuth analyze program.cbl
89+
90+
# Analyze entire directory with verbose output
91+
./cmd/codesleuth analyze --verbose /path/to/cobol/projects/
92+
93+
# Generate report to file
94+
./cmd/codesleuth analyze legacy-system/ > system_analysis.md
95+
96+
# Analyze with debug information
97+
./cmd/codesleuth analyze --verbose --debug complex-program.cbl
6698
```
6799

68100
---
69101

70-
## Usage
71-
- Analyze a COBOL directory:
72-
```sh
73-
./cmd/codesleuth.exe analyze --verbose test-cobol/
74-
```
75-
- The tool will print Markdown summaries to the console.
76-
- You can redirect output to a file:
77-
```sh
78-
./cmd/codesleuth.exe analyze test-cobol/ > summary.md
79-
```
102+
## 🔧 Configuration
103+
104+
CodeSleuth is designed to work out-of-the-box with minimal configuration. The tool automatically detects COBOL files (`.cob`, `.cbl`, `.cobol`) and generates appropriate analysis reports.
80105

81106
---
82107

83-
## Security
108+
## 🤝 Contributing
109+
110+
We welcome contributions! Please see our [Contributing Guidelines](CONTRIBUTING.md) for details on:
84111

85-
If you discover a security vulnerability, please see [SECURITY.md](SECURITY.md) for responsible disclosure guidelines.
112+
- Code style and standards
113+
- Testing requirements
114+
- Pull request process
115+
- Issue reporting
86116

87117
---
88118

89-
## Continuous Integration
119+
## 🛡️ Security
90120

91-
This project uses GitHub Actions for automated testing and linting. See `.github/workflows/ci.yml` for details.
121+
Found a security vulnerability? Please review our [Security Policy](SECURITY.md) for responsible disclosure guidelines.
92122

93123
---
94124

95-
## Contributing
96-
Pull requests, issues, and suggestions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
125+
## 📄 License
126+
127+
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
97128

98129
---
99130

100-
## License
101-
MIT License. See [LICENSE](LICENSE).
131+
## 🔗 Links
132+
133+
- [GitHub Repository](https://github.com/Cod-e-Codes/codesleuth)
134+
- [Rust Programming Language](https://www.rust-lang.org/)
135+
- [Go Programming Language](https://golang.org/)
136+
- [COBOL Resources](https://www.microfocus.com/en-us/products/cobol/overview)
137+
138+
---
139+
140+
## 📈 Performance
141+
142+
CodeSleuth's Rust-based architecture provides significant performance improvements:
143+
144+
- **10-50x faster** than Python-based alternatives
145+
- **Lower memory usage** for large codebases
146+
- **Faster startup times** with compiled binaries
147+
- **Better concurrency** for parallel processing
102148

103149
---
104150

105-
## Links
106-
- [GitHub Repo](https://github.com/Cod-e-Codes/codesleuth)
107-
- [Rust](https://www.rust-lang.org/)
108-
- [Go](https://golang.org/)
109-
- [Python](https://python.org/)
151+
*Built with ❤️ for the enterprise development community.*

0 commit comments

Comments
 (0)