diff --git a/.github/workflows/run_tests.yml b/.github/workflows/run_tests.yml index aaf16ff..50cbd4c 100644 --- a/.github/workflows/run_tests.yml +++ b/.github/workflows/run_tests.yml @@ -30,8 +30,9 @@ jobs: - name: Run tests with coverage run: | - # Run pytest on the entire tests directory - # Generate coverage report for specified source directories - # Report missing lines directly in the terminal output - python -m pytest tests/ --cov=spice --cov=cli --cov=utils --cov=parser --cov=lexers --cov-report=term-missing + python -m pytest tests/ \ + --cov=spice --cov=cli --cov=utils --cov=parser --cov=lexers \ + --cov-report=term-missing \ + --cov-report=xml # <-- this line generates coverage.xml + diff --git a/docs/.gitignore b/docs/.gitignore index b512c09..ef0f5f9 100644 --- a/docs/.gitignore +++ b/docs/.gitignore @@ -1 +1,2 @@ -node_modules \ No newline at end of file +node_modules +.docusaurus \ No newline at end of file diff --git a/docs/docusaurus.config.js b/docs/docusaurus.config.js index 5c0df3e..d579f95 100644 --- a/docs/docusaurus.config.js +++ b/docs/docusaurus.config.js @@ -33,7 +33,7 @@ const config = { // my site is not chinese. but thank you for the heads up i18n: { defaultLocale: 'en', - locales: ['en'], + locales: ['en', 'pt-BR'], }, presets: [ @@ -88,12 +88,17 @@ const config = { position: 'left', label: 'Documentation', }, + { + type: 'localeDropdown', + position: 'left', + }, // {to: '/blog', label: 'Blog', position: 'left'}, // Blog disabled { href: 'https://github.com/spicecodecli/spicecode', label: 'GitHub', position: 'right', }, + ], }, footer: { diff --git a/docs/i18n/pt-BR/docusaurus-plugin-content-docs/current/api/analyzers.md b/docs/i18n/pt-BR/docusaurus-plugin-content-docs/current/api/analyzers.md new file mode 100644 index 0000000..d0eb511 --- /dev/null +++ b/docs/i18n/pt-BR/docusaurus-plugin-content-docs/current/api/analyzers.md @@ -0,0 +1,63 @@ +--- +sidebar_position: 3 +--- + +# API Reference: Analyzers Module (`spice/analyzers`) + +The `spice/analyzers` module is where the core logic for extracting metrics and insights from the parsed source code resides. After the `lexers` module tokenizes the code and the `parser` module constructs an Abstract Syntax Tree (AST) or similar structured representation, the individual analyzer components within this module are invoked. Each analyzer is designed to traverse the AST (or work with the token stream directly for simpler metrics) and calculate specific characteristics of the code. They embody the specialized senses of SpiceCode, each focused on detecting a particular aspect of code quality, structure, or style. + +## Purpose of Code Analysis + +While the parser verifies the grammatical correctness of the code, the analyzers perform semantic analysis and metric calculation. They examine the structure represented by the AST to understand *what* the code does and *how* it is written. The goal is to produce objective measurements and qualitative assessments that help developers understand maintainability, complexity, adherence to conventions, and potential areas for improvement. + +## Structure of the `spice/analyzers` Module + +The `spice/analyzers` directory contains individual Python files, each typically implementing a specific analysis metric or a closely related group of metrics: + +``` +spice/ +├── __init__.py +├── analyze.py # Main analysis orchestration logic? +└── analyzers/ + ├── __init__.py + ├── count_comment_lines.py + ├── count_comment_ratio.py + ├── count_external_dependencies.py + ├── count_functions.py + ├── count_inline_comments.py + ├── count_lines.py + ├── count_method_type.py + └── indentation.py +``` + +### `analyze.py` (within `spice/`) + +While not strictly inside the `analyzers` subdirectory, the `analyze.py` file likely plays a crucial role in orchestrating the analysis process. It might contain the main function or class that: + +1. Takes the file path as input. +2. Invokes the appropriate lexer and parser based on the language. +3. Receives the resulting AST or token stream. +4. Instantiates and runs the relevant analyzers from the `spice/analyzers` directory, passing the AST/tokens to them. +5. Collects the results from each analyzer. +6. Formats and returns the final analysis report (either for display, JSON output, or export). + +### Individual Analyzer Files (within `spice/analyzers/`) + +Each `.py` file within the `spice/analyzers` subdirectory represents a distinct analysis capability. Examples include: + +* **`count_lines.py`:** Implements the logic to count total, code, and blank lines, likely by processing the raw source text or token stream. +* **`count_comment_lines.py`, `count_inline_comments.py`, `count_comment_ratio.py`:** These implement the various comment-related metrics. They would typically traverse the AST or token stream, identifying comment nodes/tokens and comparing their counts/positions relative to code lines. +* **`count_functions.py`:** Traverses the AST to find and count nodes representing function or method definitions (e.g., `FunctionDefinition` nodes). +* **`count_method_type.py`:** Analyzes function/method definition nodes in the AST to categorize them based on language-specific features (e.g., class methods, static methods, constructors). +* **`count_external_dependencies.py`:** Scans the AST for import/require/use statements to identify and count external dependencies. +* **`indentation.py`:** Analyzes the token stream or AST to check for consistent use of whitespace for indentation, flagging inconsistencies based on language conventions. + +Each analyzer file typically defines a function or class that takes the AST (or token stream/source text) as input and returns the calculated metric(s). They often rely on traversing the AST structure using patterns like the Visitor pattern to efficiently inspect relevant nodes. + +## Usage within SpiceCode + +When the `spice analyze` or `spice export` command is executed, the main analysis orchestrator (`spice/analyze.py`) identifies the language, parses the code, and then invokes the appropriate set of analyzers from this directory. If the user selected specific analyses interactively, only those corresponding analyzers are run. If `--all` is used or the command is `export`, all applicable analyzers for the language are executed. + +The results from each analyzer are collected and aggregated into a final report, which is then presented to the user or saved to a file in the specified format. + +This modular structure makes the analysis framework extensible. Adding a new analysis metric typically involves creating a new Python file within the `spice/analyzers` directory, implementing the logic to calculate the metric (usually by traversing the AST), and integrating it into the orchestration process in `spice/analyze.py`. This design promotes separation of concerns and makes it easier to maintain and enhance SpiceCode's analytical capabilities. diff --git a/docs/i18n/pt-BR/docusaurus-plugin-content-docs/current/api/lexers.md b/docs/i18n/pt-BR/docusaurus-plugin-content-docs/current/api/lexers.md new file mode 100644 index 0000000..48f3cc8 --- /dev/null +++ b/docs/i18n/pt-BR/docusaurus-plugin-content-docs/current/api/lexers.md @@ -0,0 +1,61 @@ +--- +sidebar_position: 1 +--- + +# API Reference: Lexers Module (`lexers`) + +Central to SpiceCode's ability to understand source code across different languages is the `lexers` module. This package contains the fundamental components responsible for the first phase of code analysis: lexical analysis, or tokenization. Unlike tools that rely on external libraries or language-specific compilers, SpiceCode employs its own set of native lexers, meticulously crafted for each supported language. This approach ensures independence, consistency, and fine-grained control over how source code is interpreted at the most basic level, much like a Fremen relies on their own senses and knowledge rather than off-world instruments. + +## Purpose of Lexical Analysis + +Lexical analysis is the process of reading the sequence of characters that make up the source code and converting them into a sequence of meaningful symbols called tokens. These tokens represent the building blocks of the language, such as keywords (`def`, `class`, `func`), identifiers (variable names, function names), operators (`+`, `=`, `==`), literals (numbers, strings), punctuation (parentheses, commas), and comments. This stream of tokens is then passed to the parser for the next stage of analysis (syntactic analysis). + +## Structure of the `lexers` Module + +The `lexers` module is organized to support multiple languages in a modular fashion: + +``` +lexers/ +├── __init__.py +├── token.py # Defines the base Token class +├── golang/ +│ ├── __init__.py +│ └── golexer.py # Lexer implementation for Go +├── javascript/ +│ ├── __init__.py +│ └── javascriptlexer.py # Lexer implementation for JavaScript +├── python/ +│ ├── __init__.py +│ └── pythonlexer.py # Lexer implementation for Python +└── ruby/ + ├── __init__.py + └── rubylexer.py # Lexer implementation for Ruby +``` + +### `token.py` + +This file defines the fundamental `Token` class (or a similar structure). Each token generated by a lexer is typically an instance of this class (or a named tuple/dataclass), containing information such as: + +* **Type:** The category of the token (e.g., KEYWORD, IDENTIFIER, OPERATOR, STRING_LITERAL, COMMENT, WHITESPACE, EOF - End Of File). +* **Value:** The actual text sequence from the source code that constitutes the token (e.g., `"def"`, `"myVariable"`, `"+"`, `"# This is a comment"`). +* **Line Number:** The line in the source file where the token begins. +* **Column Number:** The column position on the line where the token begins. + +This structured token information is essential for the parser and subsequent analyzers. + +### Language-Specific Lexer Modules (`golang`, `javascript`, `python`, `ruby`) + +Each subdirectory within `lexers` corresponds to a supported programming language and contains the specific lexer implementation for that language. + +* **`golexer.py` (in `golang/`):** Implements the lexical analysis logic specific to the Go language syntax, handling its keywords, operators, comments (`//`, `/* */`), string literals, numeric literals, etc. +* **`javascriptlexer.py` (in `javascript/`):** Implements the lexer for JavaScript, recognizing its keywords, operators, comments (`//`, `/* */`), various literal types (including template literals and regex literals), and syntax features. +* **`pythonlexer.py` (in `python/`):** Implements the lexer for Python, paying close attention to its keywords, operators, comments (`#`), string formats (f-strings, raw strings), numeric literals, and crucially, handling indentation and dedentation as significant tokens. +* **`rubylexer.py` (in `ruby/`):** Implements the lexer for Ruby, identifying its keywords (including block terminators like `end`), operators, comments (`#`), symbols, string literals, heredocs, and other syntactic elements. + +Each language-specific lexer class typically inherits from a base lexer class or follows a common interface, taking the source code string as input and providing an iterator or method to yield tokens one by one until the end of the file is reached. + +## Usage within SpiceCode + +The appropriate lexer is selected dynamically based on the detected language of the input file (usually determined by the file extension via the `utils.get_lang` and `utils.get_lexer` utilities). The chosen lexer processes the source code, and the resulting stream of tokens is fed into the `parser` module to build a structured representation (like an AST) for further analysis by the modules in `spice/analyzers`. + +Understanding the role and structure of the `lexers` module is key for contributors looking to extend SpiceCode's language support or refine the analysis for existing languages. It represents the critical first step in SpiceCode's journey from raw source code to actionable insights. diff --git a/docs/i18n/pt-BR/docusaurus-plugin-content-docs/current/api/parser.md b/docs/i18n/pt-BR/docusaurus-plugin-content-docs/current/api/parser.md new file mode 100644 index 0000000..658eda8 --- /dev/null +++ b/docs/i18n/pt-BR/docusaurus-plugin-content-docs/current/api/parser.md @@ -0,0 +1,56 @@ +--- +sidebar_position: 2 +--- + +# API Reference: Parser Module (`parser`) + +Following the lexical analysis phase performed by the `lexers` module, the resulting stream of tokens is passed to the `parser` module. This module is responsible for syntactic analysis – the process of analyzing the sequence of tokens to determine the grammatical structure of the source code according to the rules of the specific programming language. The parser effectively checks if the token stream forms a valid program and typically constructs a data structure, often an Abstract Syntax Tree (AST), that represents the hierarchical structure of the code. This structured representation is crucial for the subsequent semantic analysis and metric calculation performed by the `spice/analyzers`. + +Similar to the lexers, SpiceCode employs a native parsing approach, meaning it does not rely on external parsing libraries or language-specific compilers to generate ASTs. This ensures self-sufficiency and allows for tailored parsing logic suited to SpiceCode's specific analysis needs. + +## Purpose of Syntactic Analysis + +Syntactic analysis, or parsing, takes the flat sequence of tokens from the lexer and organizes them into a hierarchical structure that reflects the code's logical organization. It verifies that the code adheres to the language's grammar rules (e.g., ensuring parentheses are balanced, statements are correctly formed, keywords are used appropriately). The primary output of this phase in many compilers and analysis tools is an AST. An AST abstracts away much of the source code's superficial syntax (like parentheses or commas) and represents the essential structural elements (like function definitions, loops, conditional statements, expressions) and their relationships. + +## Structure of the `parser` Module + +The `parser` module within SpiceCode likely contains the core parsing logic and potentially definitions for the AST nodes: + +``` +parser/ +├── __init__.py +├── ast.py # Defines the nodes for the Abstract Syntax Tree (AST) +└── parser.py # Contains the main Parser class and parsing logic +``` + +### `ast.py` + +This file is expected to define the various types of nodes that make up the Abstract Syntax Tree. An AST is a tree representation of the code's structure. Each node in the tree represents a construct occurring in the source code. For example, there might be node classes for: + +* **Program/Module:** The root node representing the entire file. +* **FunctionDefinition:** Representing a function or method definition, potentially containing nodes for parameters, return type, and the function body. +* **ClassDefinition:** Representing a class definition. +* **IfStatement:** Representing an if-else conditional structure. +* **ForLoop/WhileLoop:** Representing loop constructs. +* **Assignment:** Representing an assignment operation. +* **VariableDeclaration:** Representing variable declarations. +* **Expression Nodes:** Representing various kinds of expressions (e.g., BinaryOperation, FunctionCall, Literal, VariableReference). + +Each AST node class would typically store relevant information about the construct it represents (e.g., a FunctionDefinition node might store the function name, parameter list, and a list of statements in its body). + +### `parser.py` + +This file likely contains the main `Parser` class (or equivalent logic). The parser takes the stream of tokens generated by a language-specific lexer as input. It implements parsing algorithms (e.g., recursive descent, or using a parser generator pattern) to consume the tokens and build the AST according to the grammar rules of the target language. + +The parser needs to handle the specific syntax of each supported language (Go, JavaScript, Python, Ruby). This might involve: + +* A single `Parser` class with methods that adapt based on the detected language. +* Or potentially separate parser implementations or configurations for each language, although the file structure suggests a more unified approach. + +The parser interacts closely with the `ast.py` module, creating instances of the appropriate AST node classes as it recognizes grammatical structures in the token stream. It also performs error handling, reporting syntax errors if the token sequence violates the language's grammar rules. + +## Usage within SpiceCode + +After a lexer tokenizes the input source file, the `parser` module is invoked with this token stream. The parser constructs the AST. This AST is then passed to the various analyzers located in the `spice/analyzers` directory. The analyzers traverse this AST, extracting information and calculating metrics based on the structure and content represented by the tree nodes. For example, the `count_functions` analyzer would traverse the AST looking for `FunctionDefinition` nodes. + +The `parser` module, along with the `ast.py` definitions, forms the bridge between the raw text of the source code and the structured understanding required for meaningful analysis. Its native implementation is key to SpiceCode's self-contained nature and its ability to provide consistent analysis across different programming languages. diff --git a/docs/i18n/pt-BR/docusaurus-plugin-content-docs/current/api/utils.md b/docs/i18n/pt-BR/docusaurus-plugin-content-docs/current/api/utils.md new file mode 100644 index 0000000..e308fa0 --- /dev/null +++ b/docs/i18n/pt-BR/docusaurus-plugin-content-docs/current/api/utils.md @@ -0,0 +1,56 @@ +--- +sidebar_position: 4 +--- + +# API Reference: Utilities Module (`utils`) + +The `utils` module in SpiceCode serves as a collection of helper functions and utility classes that support various operations across the application, particularly within the Command Line Interface (CLI) and the core analysis pipeline. These utilities handle common tasks such as language detection, dynamic loading of components (like lexers), and potentially managing translations or configurations. They encapsulate reusable logic, promoting cleaner code and easier maintenance throughout the SpiceCode project, acting like the essential tools and techniques a Fremen uses for efficient survival in the desert. + +## Purpose of Utility Functions + +Utility modules are common in software projects to house functions or classes that perform general-purpose tasks not specific to a single core component like the lexer, parser, or a specific analyzer. They help avoid code duplication and provide standardized ways to handle recurring operations. + +## Structure of the `utils` Module + +Based on the repository structure, the `utils` module likely contains several Python files, each focused on a specific utility function: + +``` +utils/ +├── __init__.py +├── get_lang.py # Utility for detecting language from filename +├── get_lexer.py # Utility for dynamically getting the lexer instance +└── get_translation.py # Utility for handling internationalization/translations +``` + +### `get_lang.py` + +This utility is crucial for the analysis pipeline. Its primary function is likely to determine the programming language of a source code file based on its file extension. For example, it would map `.py` to Python, `.js` to JavaScript, `.rb` to Ruby, and `.go` to Go. This detection mechanism allows SpiceCode to select the correct lexer and apply the appropriate analysis rules for the given file. + +* **Input:** Typically takes a filename (string) as input. +* **Output:** Returns an identifier representing the detected language (e.g., a string like "python", "javascript", or perhaps an enum value). +* **Logic:** Contains a mapping from file extensions (like `.py`, `.js`) to language identifiers. + +### `get_lexer.py` + +Once the language is detected by `get_lang.py`, this utility is responsible for dynamically importing and instantiating the corresponding language-specific lexer class from the `lexers` module. This avoids having to hardcode imports for every possible lexer in the main analysis logic. + +* **Input:** Takes the language identifier (as returned by `get_lang.py`) as input. +* **Output:** Returns an instance of the appropriate lexer class (e.g., an instance of `PythonLexer` from `lexers.python.pythonlexer`). +* **Logic:** Uses the language identifier to construct the path to the correct lexer module, imports it dynamically (e.g., using `importlib`), and instantiates the lexer class defined within that module. + +### `get_translation.py` + +This utility likely handles the internationalization (i18n) features of the SpiceCode CLI. It provides a way to retrieve translated strings for messages, prompts, and labels displayed to the user, based on the currently configured language setting (which might be managed via the `spice translate` command). + +* **Input:** Might take a key or identifier for the desired text snippet and potentially the target language code. +* **Output:** Returns the translated string for the given key in the target language. +* **Logic:** Accesses translation files (e.g., `.po`, `.json`, or other formats stored possibly within `cli/translations`) and retrieves the appropriate string based on the current language configuration. + +## Usage within SpiceCode + +These utilities are used extensively throughout the application: + +* `get_lang` and `get_lexer` are fundamental to the `spice analyze` and `spice export` commands, enabling the core analysis pipeline to adapt to different input file types. +* `get_translation` is used by the CLI components (likely within the `cli` module) to display user-facing text in the selected language, enhancing usability for a global audience. + +By centralizing these common tasks within the `utils` module, SpiceCode maintains a cleaner architecture and simplifies the process of adding support for new languages or extending functionality that requires language detection or translation services. diff --git a/docs/i18n/pt-BR/docusaurus-plugin-content-docs/current/architecture.md b/docs/i18n/pt-BR/docusaurus-plugin-content-docs/current/architecture.md new file mode 100644 index 0000000..7600281 --- /dev/null +++ b/docs/i18n/pt-BR/docusaurus-plugin-content-docs/current/architecture.md @@ -0,0 +1,38 @@ +--- +sidebar_position: 6 # Adjust position as needed relative to API and Contributing +--- + +# Architecture Overview + +Understanding the internal architecture of SpiceCode provides valuable context for both users seeking to grasp its capabilities and contributors aiming to extend or modify the tool. SpiceCode is designed with a modular architecture, emphasizing separation of concerns and leveraging native components for core language processing tasks. This approach ensures self-sufficiency and allows for consistent analysis across different programming languages, much like the well-defined ecological and social structures that allow life to thrive on Arrakis. + +## Core Components and Workflow + +The analysis process in SpiceCode follows a well-defined pipeline, involving several key modules working in concert: + +1. **Command Line Interface (`cli` module):** This is the primary user entry point. It parses user commands (e.g., `spice analyze`, `spice export`), arguments (like file paths, `--all`, `--format`), and options. It orchestrates the overall workflow based on the user's request and handles user interaction, including displaying results and managing language settings (using `utils.get_translation`). + +2. **Language Detection (`utils.get_lang`):** When an analysis or export command is issued for a specific file, the CLI first utilizes this utility to determine the programming language based on the file's extension (e.g., `.py` -> Python). + +3. **Lexer Selection (`utils.get_lexer`):** Based on the detected language, this utility dynamically loads and instantiates the appropriate language-specific lexer from the `lexers` module (e.g., `PythonLexer` for Python). + +4. **Lexical Analysis (`lexers` module):** The selected native lexer reads the source code file character by character and transforms it into a linear sequence of tokens (e.g., keywords, identifiers, operators, literals), as defined in `lexers.token`. This is the first stage of understanding the code's basic elements. + +5. **Syntactic Analysis (`parser` module):** The stream of tokens generated by the lexer is fed into the native parser (`parser.parser`). The parser checks if the token sequence conforms to the grammatical rules of the specific language. If the syntax is valid, the parser constructs an Abstract Syntax Tree (AST), a hierarchical representation of the code's structure, using node definitions from `parser.ast`. + +6. **Analysis Orchestration (`spice.analyze` - inferred):** A central component, likely within the `spice` package (e.g., `spice.analyze.py`), takes the generated AST. This orchestrator determines which specific analyzers from the `spice/analyzers` directory are applicable and required (based on language and user flags like `--all` or interactive selection). + +7. **Metric Calculation (`spice/analyzers` module):** The orchestrator invokes the selected analyzers, passing the AST to them. Each analyzer (e.g., `count_lines.py`, `count_functions.py`) traverses the AST, examining specific nodes and structures to calculate its designated metric(s). + +8. **Result Aggregation:** The analysis orchestrator collects the results (metrics) returned by each individual analyzer. + +9. **Output/Export (`cli` module):** The aggregated results are passed back to the CLI module. The CLI then formats these results for display in the terminal (potentially using translations from `utils.get_translation`) or uses specific export logic (likely within `cli.commands.export`) to generate output files in the requested format (JSON, CSV, Markdown, HTML). + +## Key Design Principles + +* **Modularity:** Each phase of the process (lexing, parsing, analyzing, CLI interaction) is handled by distinct modules, promoting separation of concerns. +* **Native Implementation:** Core language processing (lexing and parsing) is handled by custom-built components within SpiceCode, eliminating external dependencies for these critical tasks. +* **Extensibility:** The structure, particularly within `lexers` and `spice/analyzers`, is designed to facilitate the addition of support for new languages or new analysis metrics by adding new modules following the established patterns. +* **Dynamic Loading:** Utilities like `get_lexer` allow the system to adapt dynamically to different languages without requiring hardcoded conditional logic for every supported language in the main pipeline. + +This architecture provides a robust and maintainable foundation for SpiceCode, enabling it to deliver consistent and insightful code analysis across a growing range of programming languages. diff --git a/docs/i18n/pt-BR/docusaurus-plugin-content-docs/current/contributing/guidelines.md b/docs/i18n/pt-BR/docusaurus-plugin-content-docs/current/contributing/guidelines.md new file mode 100644 index 0000000..68e416a --- /dev/null +++ b/docs/i18n/pt-BR/docusaurus-plugin-content-docs/current/contributing/guidelines.md @@ -0,0 +1,40 @@ +--- +sidebar_position: 1 # Position within the Contributing category if it existed, or adjust main sidebar position +--- + +# Contributing to SpiceCode + +We appreciate your interest in contributing to SpiceCode! Like the Fremen who value collaboration for the survival and prosperity of their sietch, community involvement is vital for the long-term health and evolution of open-source projects. + +## Current Project Status: College Assignment + +At this time, SpiceCode is actively being developed as part of a college assignment. Due to the specific requirements and evaluation criteria associated with this academic context, **we are currently unable to accept external contributions** in the form of code pull requests, feature additions, or significant refactoring. + +This temporary restriction allows the core development team to focus on meeting the project's academic objectives and ensures that the work submitted for evaluation accurately reflects the efforts of the students involved. We understand this might be disappointing for those eager to contribute immediately, and we value your understanding and patience. + +## Future Plans: Open Sourcing Contributions + +Our vision for SpiceCode extends beyond the current academic requirements. We are passionate about the potential of this tool and **fully intend to open the project to community contributions in the future**, likely after the completion of the assignment phase. + +Once we transition to a fully open contribution model, we plan to adopt standard open-source practices, including: + +* **Issue Tracking:** Utilizing GitHub Issues for bug reports, feature requests, and discussions. +* **Pull Requests:** Following the standard fork-and-pull-request workflow for code contributions. +* **Code Style Guidelines:** Establishing clear coding standards to ensure consistency. +* **Testing Requirements:** Defining expectations for unit and integration tests accompanying new code. +* **Code of Conduct:** Maintaining a welcoming and respectful environment for all contributors (referencing the existing `CODE_OF_CONDUCT.md`). + +We are excited about the prospect of building a vibrant community around SpiceCode and leveraging collective expertise to enhance its capabilities. + +## How You Can Help Now + +Even though direct code contributions are currently paused, you can still engage with the project in valuable ways: + +* **Use SpiceCode:** Install the tool and use it on your own projects. Real-world usage is the best way to uncover potential issues or areas for improvement. +* **Report Bugs:** If you encounter any problems or unexpected behavior, please report them by creating an issue on the [SpiceCode GitHub Issues page](https://github.com/spicecodecli/spicecode/issues). Detailed bug reports are incredibly helpful. +* **Suggest Features:** Do you have ideas for new analysis metrics, supported languages, or CLI improvements? Share your suggestions by opening an issue. +* **Provide Feedback:** General feedback on the tool's usability, documentation clarity, or overall concept is always welcome via GitHub Issues. + +Your feedback and bug reports during this phase will be invaluable as we refine SpiceCode and prepare it for wider community involvement. + +Thank you again for your interest in SpiceCode. We look forward to the time when we can welcome your contributions more directly! diff --git a/docs/i18n/pt-BR/docusaurus-plugin-content-docs/current/getting-started/installation.md b/docs/i18n/pt-BR/docusaurus-plugin-content-docs/current/getting-started/installation.md new file mode 100644 index 0000000..494c6c7 --- /dev/null +++ b/docs/i18n/pt-BR/docusaurus-plugin-content-docs/current/getting-started/installation.md @@ -0,0 +1,79 @@ +--- +sidebar_position: 1 +--- + +# Installation Guide + +Embarking on your journey with SpiceCode requires preparing your development environment, much like a Fremen meticulously readies their gear before venturing into the vast deserts of Arrakis. This guide provides detailed instructions to ensure SpiceCode is correctly installed and ready for use on your system. The installation process is designed to be straightforward, leveraging standard Python package management tools. + +## Prerequisites + +Before you can install SpiceCode, there are a couple of essential prerequisites that must be met. Firstly, you need a working installation of Python on your system. SpiceCode is built upon Python, making it a fundamental requirement, akin to the necessity of water for life in the desert. Ensure that Python is not only installed but also correctly configured in your system's PATH environment variable, allowing you to execute Python commands from your terminal. Secondly, you will need access to a command-line terminal or prompt. This interface serves as your primary means of interacting with SpiceCode, your personal thopter for navigating the complexities of your codebase. Most operating systems (Windows, macOS, Linux) provide a built-in terminal application. + +## Standard Installation using PIP + +The most common and recommended method for installing SpiceCode is by using PIP, the standard package installer for Python. This method fetches the latest stable release directly from the Python Package Index (PyPI) and handles the installation process automatically. Open your terminal and execute the following command: + +```bash +pip install spicecode +``` + +Executing this command instructs PIP to download the SpiceCode package and its dependencies, installing them into your Python environment. Upon successful completion, the `spice` command should become available in your terminal session, ready to be invoked like a Fremen drawing their crysknife – swift and precise. + +## Installation from Source Code + +For developers who prefer to build the tool directly from its source code, perhaps for development purposes or to access the very latest, unreleased changes, installation from the source repository is also possible. This process mirrors the Fremen tradition of crafting their own tools and equipment from available resources. + +First, you need to obtain a local copy of the source code. Clone the official SpiceCode repository from GitHub using Git: + +```bash +git clone https://github.com/spicecodecli/spicecode.git +``` + +Once the repository is cloned, navigate into the newly created `spicecode` directory using your terminal: + +```bash +cd spicecode +``` + +It is highly recommended to create and activate a Python virtual environment within this directory. Virtual environments provide isolation, preventing conflicts between project dependencies and your global Python installation. Create a virtual environment named `venv` (or any name you prefer): + +```bash +python -m venv venv +``` + +Activate the virtual environment. The activation command differs slightly depending on your operating system: + +On **Windows** (using Command Prompt or PowerShell): +```bash +.\venv\Scripts\activate +``` + +On **Linux or macOS** (using bash or zsh): +```bash +source ./venv/bin/activate +``` + +With the virtual environment active (you should see its name, like `(venv)`, prepended to your terminal prompt), install the necessary dependencies listed in the `requirements.txt` file: + +```bash +pip install -r requirements.txt +``` + +Finally, install SpiceCode in "editable" mode. This mode links the installed package directly to your source code directory, meaning any changes you make to the code are immediately reflected when you run the `spice` command, without needing to reinstall. + +```bash +pip install -e . +``` + +Following these steps ensures that you have a development-ready installation of SpiceCode, built directly from the source, empowering you to explore and potentially contribute to its evolution. + +## Verifying the Installation + +Regardless of the installation method chosen, it is crucial to verify that SpiceCode has been installed correctly and is accessible from your terminal. Execute the version command: + +```bash +spice version +``` + +If the installation was successful, this command will output the currently installed version number of SpiceCode. Seeing this confirmation signifies that the spice is indeed flowing through your system, and you are prepared to begin analyzing your code with the power and precision of a seasoned desert navigator. diff --git a/docs/i18n/pt-BR/docusaurus-plugin-content-docs/current/getting-started/quick-start.md b/docs/i18n/pt-BR/docusaurus-plugin-content-docs/current/getting-started/quick-start.md new file mode 100644 index 0000000..221699a --- /dev/null +++ b/docs/i18n/pt-BR/docusaurus-plugin-content-docs/current/getting-started/quick-start.md @@ -0,0 +1,82 @@ +--- +sidebar_position: 2 +--- + +# Quick Start Guide + +Now that SpiceCode is installed on your system, you are ready to take your first steps into analyzing code, much like a Fremen taking their initial strides across the vast desert sands under the twin moons of Arrakis. This quick start guide will walk you through the fundamental commands and demonstrate a basic analysis workflow, allowing you to quickly experience the core capabilities of SpiceCode. + +## Verifying Your Setup + +Before diving into analysis, it's always a good practice to ensure the tool is responding correctly. As covered in the installation guide, you can confirm SpiceCode is operational by checking its version: + +```bash +spice version +``` + +This command should return the installed version number. Additionally, SpiceCode includes a simple greeting command, a ritualistic acknowledgment like a Fremen salute, which can also serve as a basic check: + +```bash +spice hello +``` + +Executing this should display a welcoming message, confirming the CLI is responsive. + +## Performing Your First Analysis + +The primary function of SpiceCode is code analysis. Let's perform a basic analysis on a sample code file. If you don't have a readily available file in one of the supported languages (Python, JavaScript, Ruby, Go), you can quickly create one. For instance, create a simple Python file named `example.py` with the following content: + +```python +# This is a simple Python script +def greet(name): + """This function greets the user.""" + message = f"Hello, {name}! Welcome to SpiceCode." + print(message) + +if __name__ == "__main__": + # Get user input + user_name = input("Enter your name: ") # Inline comment + greet(user_name) +``` + +Now, navigate your terminal to the directory containing `example.py` and run the basic analysis command: + +```bash +spice analyze example.py +``` + +Upon executing this command, SpiceCode will parse the `example.py` file using its native Python lexer and parser. It will then present you with an interactive menu, listing the various analysis metrics available for this file type. This menu allows you to select specific analyses you are interested in, offering a targeted approach to understanding your code. + +## Running All Analyses + +If you prefer to run all available analyses for a file without the interactive menu, you can use the `--all` flag. This is akin to a Fremen performing a comprehensive scan of their surroundings. + +```bash +spice analyze example.py --all +``` + +This command will execute every applicable analyzer on `example.py` and output the results directly to your terminal. The output will typically include metrics such as line counts (total, code, comments), function complexity, comment ratio, indentation analysis, and more, depending on the language and the specific analyzers implemented. + +## Exporting Analysis Results + +Often, you'll want to save the analysis results for later review, documentation, or integration into other processes. SpiceCode provides the `export` command for this purpose, allowing you to preserve the valuable insights gathered, much like Fremen carefully store water. + +To export the full analysis results of `example.py` to a Markdown file named `analysis_report.md`, you would run: + +```bash +spice export example.py --format markdown --output analysis_report.md +``` + +This command performs all analyses (similar to `analyze --all`) and then writes the formatted results to the specified output file. Besides Markdown (`markdown`), you can export results to JSON (`json`), CSV (`csv`), and HTML (`html`) formats by changing the `--format` argument accordingly. For example, to get a JSON output: + +```bash +spice export example.py --format json --output analysis_results.json +``` + +This JSON output is particularly useful for programmatic consumption of the analysis data. + +## Exploring Further + +This quick start guide has introduced you to the fundamental operations of SpiceCode: verifying installation, running basic and comprehensive analyses, and exporting the results. You have now taken your first successful steps into the world of SpiceCode analysis. + +The subsequent sections of this documentation delve deeper into the various commands, options, specific analyzers, supported languages, and the underlying architecture of the tool. Continue your exploration to fully harness the power of SpiceCode, mastering its capabilities just as Paul Atreides learned to master the ways of the desert and the power of the spice. diff --git a/docs/i18n/pt-BR/docusaurus-plugin-content-docs/current/intro.md b/docs/i18n/pt-BR/docusaurus-plugin-content-docs/current/intro.md new file mode 100644 index 0000000..5a8c56e --- /dev/null +++ b/docs/i18n/pt-BR/docusaurus-plugin-content-docs/current/intro.md @@ -0,0 +1,19 @@ +--- +sidebar_position: 1 +--- + +# Introduction to SpiceCode + +Welcome to the official documentation for SpiceCode, a powerful and versatile command-line interface (CLI) tool designed for the next generation of code analysis. Drawing inspiration from the intricate world of Dune, SpiceCode aims to provide developers with the insights needed to navigate the complex landscapes of modern software development. Just as the spice melange unlocks prescience and understanding on Arrakis, SpiceCode empowers you to delve deep into your codebase, uncovering valuable patterns, metrics, and opportunities for improvement across multiple programming languages. + +SpiceCode is engineered with a core focus on simplicity, efficiency, and self-reliance. It provides a comprehensive suite of analysis capabilities without relying on external parsing libraries. All language lexers and parsers for the supported languages—Python, JavaScript, Ruby, and Go—are meticulously crafted and maintained natively within the SpiceCode project. This approach ensures a consistent analysis experience and grants us full control over the interpretation and evaluation of code structures. + +This documentation serves as your comprehensive guide to mastering SpiceCode. Whether you are an end-user developer seeking to enhance the quality and maintainability of your projects, or a potential contributor looking to understand the inner workings and extend the capabilities of the tool, you will find detailed information herein. We cover everything from initial setup and basic usage to advanced analysis techniques, API references, architectural insights, and contribution guidelines. Our goal is to equip you with the knowledge to leverage SpiceCode effectively, transforming it from a simple tool into an indispensable part of your development workflow, much like a Fremen utilizes their crysknife and stillsuit for survival and mastery in the harsh desert environment. + +## Core Philosophy and Key Features + +SpiceCode operates on the principle that deep code understanding should be accessible and straightforward. The tool is built to provide meaningful analysis without unnecessary complexity. It examines your source code files directly, applying a range of analytical techniques to extract quantitative and qualitative data about code structure, style, and potential areas of concern. This allows developers at all skill levels, from novices taking their first steps into coding to seasoned veterans managing large-scale systems, to gain a clearer picture of their work and make informed decisions about refactoring, optimization, and adherence to best practices. + +Several key features distinguish SpiceCode as a valuable asset in a developer's toolkit. It offers in-depth analysis capabilities, going beyond simple linting to provide detailed metrics concerning code complexity, comment density, function length, naming conventions, and more. This multi-faceted approach gives a holistic view of code health. Furthermore, SpiceCode boasts native support for popular programming languages including Python, JavaScript, Ruby, and Go, with dedicated lexers and parsers ensuring accurate and language-specific analysis. The command-line interface is designed to be intuitive and user-friendly, making powerful analysis accessible through simple commands. For integration with other development tools and workflows, SpiceCode allows analysis results to be exported in various standard formats such as JSON, CSV, Markdown, and HTML. Recognizing the global nature of software development, the interface also includes support for multiple languages, making it accessible to a wider audience. + +Think of clean, well-structured code as the vital "water of life" within your project's ecosystem. SpiceCode acts as your essential stillsuit, helping you conserve this precious resource by identifying inefficiencies, promoting clarity, and ultimately optimizing the quality and longevity of your codebase. Prepare to harness the power of the spice and elevate your code to new heights. diff --git a/docs/i18n/pt-BR/docusaurus-plugin-content-docs/current/intro_template.md b/docs/i18n/pt-BR/docusaurus-plugin-content-docs/current/intro_template.md new file mode 100644 index 0000000..45e8604 --- /dev/null +++ b/docs/i18n/pt-BR/docusaurus-plugin-content-docs/current/intro_template.md @@ -0,0 +1,47 @@ +--- +sidebar_position: 1 +--- + +# Tutorial Intro + +Let's discover **Docusaurus in less than 5 minutes**. + +## Getting Started + +Get started by **creating a new site**. + +Or **try Docusaurus immediately** with **[docusaurus.new](https://docusaurus.new)**. + +### What you'll need + +- [Node.js](https://nodejs.org/en/download/) version 18.0 or above: + - When installing Node.js, you are recommended to check all checkboxes related to dependencies. + +## Generate a new site + +Generate a new Docusaurus site using the **classic template**. + +The classic template will automatically be added to your project after you run the command: + +```bash +npm init docusaurus@latest my-website classic +``` + +You can type this command into Command Prompt, Powershell, Terminal, or any other integrated terminal of your code editor. + +The command also installs all necessary dependencies you need to run Docusaurus. + +## Start your site + +Run the development server: + +```bash +cd my-website +npm run start +``` + +The `cd` command changes the directory you're working with. In order to work with your newly created Docusaurus site, you'll need to navigate the terminal there. + +The `npm run start` command builds your website locally and serves it through a development server, ready for you to view at http://localhost:3000/. + +Open `docs/intro.md` (this page) and edit some lines: the site **reloads automatically** and displays your changes. diff --git a/docs/i18n/pt-BR/docusaurus-plugin-content-docs/current/languages/go.md b/docs/i18n/pt-BR/docusaurus-plugin-content-docs/current/languages/go.md new file mode 100644 index 0000000..5171601 --- /dev/null +++ b/docs/i18n/pt-BR/docusaurus-plugin-content-docs/current/languages/go.md @@ -0,0 +1,56 @@ +--- +sidebar_position: 1 +--- + +# Go Language Support + +SpiceCode provides robust, native support for analyzing Go (Golang) source code files, typically identified by the `.go` extension. Recognizing Go's increasing popularity for building efficient and concurrent systems, SpiceCode includes a dedicated lexer and parser specifically designed to understand Go's syntax and structure. This allows for accurate and insightful analysis without relying on external tools or libraries, ensuring a self-contained and consistent experience, much like the Fremen rely on their own deep knowledge of the desert rather than off-world technologies. + +## Native Lexer and Parser + +The cornerstone of Go support in SpiceCode is its custom-built lexer (`golexer.py` within the `lexers/golang` directory) and the corresponding parsing logic integrated into the main parser module. This native implementation meticulously processes Go source code, tokenizing keywords, identifiers, operators, literals, and comments according to the Go language specification. The parser then constructs an internal representation (like an Abstract Syntax Tree or similar structure) of the code, enabling the various analyzers to operate effectively. + +This native approach offers several advantages: + +1. **Accuracy:** The lexer and parser are tailored specifically for Go syntax, leading to more precise analysis compared to generic tools. +2. **Independence:** SpiceCode does not require users to have Go compilers or external Go analysis tools installed on their system to analyze `.go` files. +3. **Consistency:** The analysis process remains consistent with how other languages are handled within SpiceCode, providing a unified user experience. + +## Applicable Analyzers + +Most of SpiceCode's standard analyzers are applicable to Go code, leveraging the output of the native lexer and parser. When you analyze a `.go` file, you can expect metrics from analyzers such as: + +* **Line Counts (`count_lines`):** Provides total, code, and blank line counts. +* **Comment Analysis (`count_comment_lines`, `count_inline_comments`, `count_comment_ratio`):** Analyzes single-line (`//`) and multi-line (`/* ... */`) comments, including their ratio to code lines. +* **Function Analysis (`count_functions`):** Identifies and counts `func` declarations. +* **Dependency Analysis (`count_external_dependencies`):** Counts `import` statements to gauge reliance on external packages. +* **Indentation Analysis (`indentation`):** Checks for consistent use of tabs (standard in Go) for indentation. + +Specific analyzers like `count_method_type` might have Go-specific interpretations, potentially distinguishing between regular functions and methods associated with structs. + +## Example Analysis + +Consider a simple Go file named `hello.go`: + +```go +package main + +import "fmt" + +// Greet generates a greeting message. +func Greet(name string) string { + // Return a formatted string + return fmt.Sprintf("Hello, %s! Welcome from Go.", name) +} + +func main() { + message := Greet("Go Developer") + fmt.Println(message) // Print the greeting +} +``` + +Running `spice analyze hello.go --all` would invoke the Go lexer and parser, followed by the applicable analyzers. The output would provide metrics detailing line counts, comment statistics (including the function comment and inline comments), the number of functions (`Greet` and `main`), the number of external dependencies (`fmt`), and indentation consistency. + +Similarly, `spice export hello.go --format json --output hello_report.json` would generate a structured JSON report containing these metrics. + +SpiceCode's dedicated support for Go ensures that developers working with this powerful language can benefit from the same level of detailed analysis and insight available for other supported languages, helping maintain code quality and consistency within their Go projects. diff --git a/docs/i18n/pt-BR/docusaurus-plugin-content-docs/current/languages/javascript.md b/docs/i18n/pt-BR/docusaurus-plugin-content-docs/current/languages/javascript.md new file mode 100644 index 0000000..bd5814b --- /dev/null +++ b/docs/i18n/pt-BR/docusaurus-plugin-content-docs/current/languages/javascript.md @@ -0,0 +1,74 @@ +--- +sidebar_position: 2 +--- + +# JavaScript Language Support + +SpiceCode offers comprehensive, native analysis capabilities for JavaScript code, commonly found in files with the `.js` extension. As JavaScript remains a cornerstone of web development and beyond, SpiceCode incorporates a dedicated lexer and parser specifically engineered to handle its dynamic nature and syntax nuances. This built-in support ensures that JavaScript projects can be analyzed accurately and efficiently without external dependencies, providing developers with valuable insights derived directly from their source code, much like a Fremen relies on their innate understanding of the desert rhythms. + +## Native Lexer and Parser + +At the heart of SpiceCode's JavaScript support is its custom lexer (`javascriptlexer.py` located in `lexers/javascript`) and the integrated parsing logic. This native implementation is designed to tokenize JavaScript code accurately, recognizing keywords, identifiers, operators, literals (including string, number, boolean, null, undefined, regex), and comments (both single-line `//` and multi-line `/* ... */`). The parser subsequently builds an internal representation of the code structure, which serves as the foundation for the various analysis modules. + +Key benefits of this native approach include: + +1. **Precision:** Tailored specifically for JavaScript syntax (including common ES features), leading to more reliable analysis than generic tools might provide. +2. **Self-Sufficiency:** SpiceCode analyzes `.js` files directly without needing Node.js or other JavaScript runtimes/tools installed on the system. +3. **Uniformity:** The analysis process aligns with how SpiceCode handles other supported languages, offering a consistent user experience across different codebases. + +## Applicable Analyzers + +The majority of SpiceCode's standard analyzers are fully compatible with JavaScript code, utilizing the detailed information provided by the native lexer and parser. When analyzing a `.js` file, you can leverage analyzers such as: + +* **Line Counts (`count_lines`):** Delivers total, code, and blank line metrics. +* **Comment Analysis (`count_comment_lines`, `count_inline_comments`, `count_comment_ratio`):** Quantifies comment usage and density. +* **Function Analysis (`count_functions`):** Counts `function` declarations, function expressions, and potentially arrow functions, depending on implementation depth. +* **Dependency Analysis (`count_external_dependencies`):** Identifies and counts `require()` calls or `import` statements to assess external module usage. +* **Indentation Analysis (`indentation`):** Checks for consistent indentation patterns (commonly spaces in JavaScript development). +* **Method Type Analysis (`count_method_type`):** May distinguish between regular functions, methods within classes, constructors, etc., providing insights into object-oriented or prototype-based structures. + +## Example Analysis + +Consider this simple JavaScript file, `calculator.js`: + +```javascript +// Simple calculator functions + +/* + * Adds two numbers. + */ +function add(a, b) { + // Return the sum + return a + b; +} + +class Calculator { + constructor() { + this.result = 0; + } + + // Method to multiply + multiply(a, b) { + this.result = a * b; + return this.result; // Return calculation + } +} + +const sum = add(5, 3); // Example usage +console.log(`Sum: ${sum}`); + +const calc = new Calculator(); +console.log(`Product: ${calc.multiply(5, 3)}`); +``` + +Running `spice analyze calculator.js --all` would trigger the JavaScript lexer and parser. The subsequent analysis would yield metrics on line counts, comment types and ratio, the number of functions/methods (`add`, `constructor`, `multiply`), dependency counts (potentially identifying `require` or `import` if used), and indentation consistency. + +Exporting these results, for instance to HTML: + +```bash +spice export calculator.js --format html --output calculator_report.html +``` + +This would generate an HTML document detailing all the gathered metrics for easy viewing and sharing. + +SpiceCode's dedicated JavaScript support empowers developers to apply consistent code analysis practices to their JavaScript projects, helping to ensure code quality, maintainability, and adherence to best practices within the dynamic world of JavaScript development. diff --git a/docs/i18n/pt-BR/docusaurus-plugin-content-docs/current/languages/python.md b/docs/i18n/pt-BR/docusaurus-plugin-content-docs/current/languages/python.md new file mode 100644 index 0000000..e02b1a8 --- /dev/null +++ b/docs/i18n/pt-BR/docusaurus-plugin-content-docs/current/languages/python.md @@ -0,0 +1,78 @@ +--- +sidebar_position: 3 +--- + +# Python Language Support + +SpiceCode provides first-class, native support for analyzing Python source code files, which conventionally use the `.py` extension. As Python continues to be a dominant language in diverse fields like web development, data science, scripting, and automation, SpiceCode includes a meticulously crafted lexer and parser specifically designed to handle Python's syntax, including its significant whitespace rules. This built-in capability allows for deep and accurate analysis of Python code without requiring external Python interpreters or analysis libraries, ensuring a self-contained and consistent analysis process, much like the Fremen rely on their deep-seated understanding of Arrakis' ecology. + +## Native Lexer and Parser + +The foundation of Python support within SpiceCode is its custom lexer (`pythonlexer.py` found in `lexers/python`) and the associated parsing logic. This native implementation is carefully constructed to tokenize Python code correctly, recognizing keywords, identifiers, operators, literals (strings, numbers, lists, tuples, dictionaries, etc.), and comments (`#`). Crucially, it also handles Python's indentation rules, which define code blocks. The parser uses this token stream to build an internal representation of the Python code's structure, enabling effective analysis by the various SpiceCode modules. + +This native approach yields significant benefits: + +1. **Accuracy:** The lexer and parser are specifically designed for Python 3 syntax, leading to precise understanding of code structure, including indentation sensitivity. +2. **Independence:** SpiceCode can analyze `.py` files without needing a Python interpreter installed on the system (beyond the Python environment needed to run SpiceCode itself) or relying on external Python static analysis tools. +3. **Consistency:** The analysis methodology remains uniform with other languages supported by SpiceCode, providing a cohesive user experience. + +## Applicable Analyzers + +Nearly all of SpiceCode's standard analyzers are applicable to Python code, leveraging the detailed structural information provided by the native lexer and parser. When analyzing a `.py` file, you can expect insights from analyzers such as: + +* **Line Counts (`count_lines`):** Provides the standard breakdown of total, code, and blank lines. +* **Comment Analysis (`count_comment_lines`, `count_inline_comments`, `count_comment_ratio`):** Analyzes the usage and density of `#` comments. +* **Function and Method Analysis (`count_functions`, `count_method_type`):** Counts `def` statements (functions and methods) and potentially analyzes characteristics like class methods, static methods, or dunder methods based on naming conventions. +* **Dependency Analysis (`count_external_dependencies`):** Counts `import` and `from ... import` statements to gauge the reliance on external or standard library modules. +* **Indentation Analysis (`indentation`):** Critically important for Python, this analyzer verifies the consistency of indentation (typically 4 spaces per level) used for defining code blocks. + +## Example Analysis + +Let's consider a simple Python file, `utils.py`: + +```python +# Utility functions for data processing +import json + +DEFAULT_FACTOR = 10 + +def process_data(data, factor=None): # Process incoming data + """Processes the input data using a factor.""" + if factor is None: + factor = DEFAULT_FACTOR + + processed = [item * factor for item in data] + # Log processing (example) + print(f"Processed {len(data)} items with factor {factor}") + return processed + +class DataHandler: + def __init__(self, source_file): + self.source = source_file + self.data = self._load_data() + + def _load_data(self): + # Private helper method to load data + try: + with open(self.source, 'r') as f: + return json.load(f) + except FileNotFoundError: + print(f"Error: File not found - {self.source}") + return [] + + def run_processing(self, factor=None): + return process_data(self.data, factor) + +``` + +Running `spice analyze utils.py --all` would engage the Python lexer and parser. The analyzers would then report on line counts, comment usage (including docstrings and inline comments), the number of functions/methods (`process_data`, `__init__`, `_load_data`, `run_processing`), the external dependency (`json`), and the consistency of indentation throughout the file. + +Exporting these findings, for example, to CSV: + +```bash +spice export utils.py --format csv --output utils_metrics.csv +``` + +This command would generate a `utils_metrics.csv` file containing the structured analysis results, suitable for import into spreadsheets or databases. + +SpiceCode's robust, native support for Python allows developers to seamlessly integrate detailed code analysis into their Python workflows, promoting higher code quality, better maintainability, and adherence to best practices within their Python projects. diff --git a/docs/i18n/pt-BR/docusaurus-plugin-content-docs/current/languages/ruby.md b/docs/i18n/pt-BR/docusaurus-plugin-content-docs/current/languages/ruby.md new file mode 100644 index 0000000..b2756c4 --- /dev/null +++ b/docs/i18n/pt-BR/docusaurus-plugin-content-docs/current/languages/ruby.md @@ -0,0 +1,76 @@ +--- +sidebar_position: 4 +--- + +# Ruby Language Support + +SpiceCode extends its analytical capabilities to Ruby, a dynamic, open-source programming language known for its focus on simplicity and productivity, often identified by the `.rb` file extension. Recognizing Ruby's continued relevance in web development (particularly with frameworks like Ruby on Rails), scripting, and automation, SpiceCode features a dedicated, native lexer and parser designed specifically for Ruby's elegant syntax. This ensures that Ruby projects can be analyzed thoroughly and accurately within the SpiceCode ecosystem without reliance on external Ruby interpreters or analysis tools, providing a self-sufficient analysis environment akin to the resourcefulness of the Fremen in the harsh Arrakis climate. + +## Native Lexer and Parser + +The core of Ruby support in SpiceCode lies in its custom-built lexer (`rubylexer.py` within the `lexers/ruby` directory) and the integrated parsing logic. This native implementation is carefully crafted to tokenize Ruby source code, correctly identifying keywords (like `def`, `class`, `module`, `end`), identifiers, operators, literals (strings, symbols, numbers, arrays, hashes), and comments (`#`). The parser utilizes this token stream to construct an internal representation of the Ruby code's structure, enabling the various SpiceCode analyzers to perform meaningful evaluations. + +Advantages of this native approach include: + +1. **Accuracy:** The lexer and parser are tailored to Ruby's specific syntax rules, leading to a more precise understanding of the code structure compared to generic parsing methods. +2. **Independence:** SpiceCode can analyze `.rb` files without requiring a Ruby runtime environment to be installed on the user's system (beyond the Python environment needed for SpiceCode itself). +3. **Consistency:** The analysis process for Ruby aligns seamlessly with how SpiceCode handles Python, JavaScript, and Go, offering a unified and predictable user experience across different language projects. + +## Applicable Analyzers + +Most of SpiceCode's standard suite of analyzers are effective on Ruby code, drawing upon the structural information provided by the native lexer and parser. When analyzing a `.rb` file, users can benefit from insights generated by analyzers such as: + +* **Line Counts (`count_lines`):** Delivers the standard metrics for total, code, and blank lines. +* **Comment Analysis (`count_comment_lines`, `count_inline_comments`, `count_comment_ratio`):** Analyzes the frequency and placement of `#` comments. +* **Function/Method Analysis (`count_functions`, `count_method_type`):** Counts `def` statements within classes, modules, or at the top level. It might also differentiate between instance methods, class methods, etc., based on definitions. +* **Dependency Analysis (`count_external_dependencies`):** Tracks `require` and `load` statements to measure the code's reliance on external gems or standard libraries. +* **Indentation Analysis (`indentation`):** Checks for consistent indentation, which, while not syntactically mandatory like in Python, is crucial for readability in Ruby (typically 2 spaces). + +## Example Analysis + +Consider this simple Ruby file, `greeter.rb`: + +```ruby +# A simple Ruby class for greetings +require 'json' # Example dependency + +class Greeter + attr_reader :name + + # Initialize with a name + def initialize(name) + @name = name + end + + def greet + # Generate a greeting message + message = "Hello, #{@name}! Welcome from Ruby." + puts message # Output the message + return message + end + + # Class method example + def self.default_greeting + puts "Standard Ruby greeting!" + end +end + +# Script execution +if __FILE__ == $0 + greeter = Greeter.new("Ruby Enthusiast") + greeter.greet + Greeter.default_greeting +end +``` + +Running `spice analyze greeter.rb --all` would utilize the Ruby lexer and parser. The analyzers would then provide metrics on line counts, comment usage, the number of methods (`initialize`, `greet`, `default_greeting`), the external dependency (`json`), and indentation consistency. + +To save these results, for instance, in Markdown format: + +```bash +spice export greeter.rb --format markdown --output greeter_analysis.md +``` + +This command generates a `greeter_analysis.md` file containing a human-readable report of the analysis metrics. + +SpiceCode's dedicated native support for Ruby ensures that developers working within the Ruby ecosystem can leverage detailed, consistent code analysis to maintain high standards of code quality, readability, and maintainability in their projects. diff --git a/docs/i18n/pt-BR/docusaurus-plugin-content-docs/current/tutorial-basics/_category_.json b/docs/i18n/pt-BR/docusaurus-plugin-content-docs/current/tutorial-basics/_category_.json new file mode 100644 index 0000000..2e6db55 --- /dev/null +++ b/docs/i18n/pt-BR/docusaurus-plugin-content-docs/current/tutorial-basics/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "Tutorial - Basics", + "position": 2, + "link": { + "type": "generated-index", + "description": "5 minutes to learn the most important Docusaurus concepts." + } +} diff --git a/docs/i18n/pt-BR/docusaurus-plugin-content-docs/current/tutorial-basics/congratulations.md b/docs/i18n/pt-BR/docusaurus-plugin-content-docs/current/tutorial-basics/congratulations.md new file mode 100644 index 0000000..04771a0 --- /dev/null +++ b/docs/i18n/pt-BR/docusaurus-plugin-content-docs/current/tutorial-basics/congratulations.md @@ -0,0 +1,23 @@ +--- +sidebar_position: 6 +--- + +# Congratulations! + +You have just learned the **basics of Docusaurus** and made some changes to the **initial template**. + +Docusaurus has **much more to offer**! + +Have **5 more minutes**? Take a look at **[versioning](../tutorial-extras/manage-docs-versions.md)** and **[i18n](../tutorial-extras/translate-your-site.md)**. + +Anything **unclear** or **buggy** in this tutorial? [Please report it!](https://github.com/facebook/docusaurus/discussions/4610) + +## What's next? + +- Read the [official documentation](https://docusaurus.io/) +- Modify your site configuration with [`docusaurus.config.js`](https://docusaurus.io/docs/api/docusaurus-config) +- Add navbar and footer items with [`themeConfig`](https://docusaurus.io/docs/api/themes/configuration) +- Add a custom [Design and Layout](https://docusaurus.io/docs/styling-layout) +- Add a [search bar](https://docusaurus.io/docs/search) +- Find inspirations in the [Docusaurus showcase](https://docusaurus.io/showcase) +- Get involved in the [Docusaurus Community](https://docusaurus.io/community/support) diff --git a/docs/i18n/pt-BR/docusaurus-plugin-content-docs/current/tutorial-basics/create-a-blog-post.md b/docs/i18n/pt-BR/docusaurus-plugin-content-docs/current/tutorial-basics/create-a-blog-post.md new file mode 100644 index 0000000..550ae17 --- /dev/null +++ b/docs/i18n/pt-BR/docusaurus-plugin-content-docs/current/tutorial-basics/create-a-blog-post.md @@ -0,0 +1,34 @@ +--- +sidebar_position: 3 +--- + +# Create a Blog Post + +Docusaurus creates a **page for each blog post**, but also a **blog index page**, a **tag system**, an **RSS** feed... + +## Create your first Post + +Create a file at `blog/2021-02-28-greetings.md`: + +```md title="blog/2021-02-28-greetings.md" +--- +slug: greetings +title: Greetings! +authors: + - name: Joel Marcey + title: Co-creator of Docusaurus 1 + url: https://github.com/JoelMarcey + image_url: https://github.com/JoelMarcey.png + - name: Sébastien Lorber + title: Docusaurus maintainer + url: https://sebastienlorber.com + image_url: https://github.com/slorber.png +tags: [greetings] +--- + +Congratulations, you have made your first post! + +Feel free to play around and edit this post as much as you like. +``` + +A new blog post is now available at [http://localhost:3000/blog/greetings](http://localhost:3000/blog/greetings). diff --git a/docs/i18n/pt-BR/docusaurus-plugin-content-docs/current/tutorial-basics/create-a-document.md b/docs/i18n/pt-BR/docusaurus-plugin-content-docs/current/tutorial-basics/create-a-document.md new file mode 100644 index 0000000..c22fe29 --- /dev/null +++ b/docs/i18n/pt-BR/docusaurus-plugin-content-docs/current/tutorial-basics/create-a-document.md @@ -0,0 +1,57 @@ +--- +sidebar_position: 2 +--- + +# Create a Document + +Documents are **groups of pages** connected through: + +- a **sidebar** +- **previous/next navigation** +- **versioning** + +## Create your first Doc + +Create a Markdown file at `docs/hello.md`: + +```md title="docs/hello.md" +# Hello + +This is my **first Docusaurus document**! +``` + +A new document is now available at [http://localhost:3000/docs/hello](http://localhost:3000/docs/hello). + +## Configure the Sidebar + +Docusaurus automatically **creates a sidebar** from the `docs` folder. + +Add metadata to customize the sidebar label and position: + +```md title="docs/hello.md" {1-4} +--- +sidebar_label: 'Hi!' +sidebar_position: 3 +--- + +# Hello + +This is my **first Docusaurus document**! +``` + +It is also possible to create your sidebar explicitly in `sidebars.js`: + +```js title="sidebars.js" +export default { + tutorialSidebar: [ + 'intro', + // highlight-next-line + 'hello', + { + type: 'category', + label: 'Tutorial', + items: ['tutorial-basics/create-a-document'], + }, + ], +}; +``` diff --git a/docs/i18n/pt-BR/docusaurus-plugin-content-docs/current/tutorial-basics/create-a-page.md b/docs/i18n/pt-BR/docusaurus-plugin-content-docs/current/tutorial-basics/create-a-page.md new file mode 100644 index 0000000..20e2ac3 --- /dev/null +++ b/docs/i18n/pt-BR/docusaurus-plugin-content-docs/current/tutorial-basics/create-a-page.md @@ -0,0 +1,43 @@ +--- +sidebar_position: 1 +--- + +# Create a Page + +Add **Markdown or React** files to `src/pages` to create a **standalone page**: + +- `src/pages/index.js` → `localhost:3000/` +- `src/pages/foo.md` → `localhost:3000/foo` +- `src/pages/foo/bar.js` → `localhost:3000/foo/bar` + +## Create your first React Page + +Create a file at `src/pages/my-react-page.js`: + +```jsx title="src/pages/my-react-page.js" +import React from 'react'; +import Layout from '@theme/Layout'; + +export default function MyReactPage() { + return ( + +

My React page

+

This is a React page

+ + ); +} +``` + +A new page is now available at [http://localhost:3000/my-react-page](http://localhost:3000/my-react-page). + +## Create your first Markdown Page + +Create a file at `src/pages/my-markdown-page.md`: + +```mdx title="src/pages/my-markdown-page.md" +# My Markdown page + +This is a Markdown page +``` + +A new page is now available at [http://localhost:3000/my-markdown-page](http://localhost:3000/my-markdown-page). diff --git a/docs/i18n/pt-BR/docusaurus-plugin-content-docs/current/tutorial-basics/deploy-your-site.md b/docs/i18n/pt-BR/docusaurus-plugin-content-docs/current/tutorial-basics/deploy-your-site.md new file mode 100644 index 0000000..1c50ee0 --- /dev/null +++ b/docs/i18n/pt-BR/docusaurus-plugin-content-docs/current/tutorial-basics/deploy-your-site.md @@ -0,0 +1,31 @@ +--- +sidebar_position: 5 +--- + +# Deploy your site + +Docusaurus is a **static-site-generator** (also called **[Jamstack](https://jamstack.org/)**). + +It builds your site as simple **static HTML, JavaScript and CSS files**. + +## Build your site + +Build your site **for production**: + +```bash +npm run build +``` + +The static files are generated in the `build` folder. + +## Deploy your site + +Test your production build locally: + +```bash +npm run serve +``` + +The `build` folder is now served at [http://localhost:3000/](http://localhost:3000/). + +You can now deploy the `build` folder **almost anywhere** easily, **for free** or very small cost (read the **[Deployment Guide](https://docusaurus.io/docs/deployment)**). diff --git a/docs/i18n/pt-BR/docusaurus-plugin-content-docs/current/tutorial-basics/markdown-features.mdx b/docs/i18n/pt-BR/docusaurus-plugin-content-docs/current/tutorial-basics/markdown-features.mdx new file mode 100644 index 0000000..35e0082 --- /dev/null +++ b/docs/i18n/pt-BR/docusaurus-plugin-content-docs/current/tutorial-basics/markdown-features.mdx @@ -0,0 +1,152 @@ +--- +sidebar_position: 4 +--- + +# Markdown Features + +Docusaurus supports **[Markdown](https://daringfireball.net/projects/markdown/syntax)** and a few **additional features**. + +## Front Matter + +Markdown documents have metadata at the top called [Front Matter](https://jekyllrb.com/docs/front-matter/): + +```text title="my-doc.md" +// highlight-start +--- +id: my-doc-id +title: My document title +description: My document description +slug: /my-custom-url +--- +// highlight-end + +## Markdown heading + +Markdown text with [links](./hello.md) +``` + +## Links + +Regular Markdown links are supported, using url paths or relative file paths. + +```md +Let's see how to [Create a page](/create-a-page). +``` + +```md +Let's see how to [Create a page](./create-a-page.md). +``` + +**Result:** Let's see how to [Create a page](./create-a-page.md). + +## Images + +Regular Markdown images are supported. + +You can use absolute paths to reference images in the static directory (`static/img/docusaurus.png`): + +```md +![Docusaurus logo](/img/docusaurus.png) +``` + +![Docusaurus logo](/img/docusaurus.png) + +You can reference images relative to the current file as well. This is particularly useful to colocate images close to the Markdown files using them: + +```md +![Docusaurus logo](./img/docusaurus.png) +``` + +## Code Blocks + +Markdown code blocks are supported with Syntax highlighting. + +````md +```jsx title="src/components/HelloDocusaurus.js" +function HelloDocusaurus() { + return

Hello, Docusaurus!

; +} +``` +```` + +```jsx title="src/components/HelloDocusaurus.js" +function HelloDocusaurus() { + return

Hello, Docusaurus!

; +} +``` + +## Admonitions + +Docusaurus has a special syntax to create admonitions and callouts: + +```md +:::tip My tip + +Use this awesome feature option + +::: + +:::danger Take care + +This action is dangerous + +::: +``` + +:::tip My tip + +Use this awesome feature option + +::: + +:::danger Take care + +This action is dangerous + +::: + +## MDX and React Components + +[MDX](https://mdxjs.com/) can make your documentation more **interactive** and allows using any **React components inside Markdown**: + +```jsx +export const Highlight = ({children, color}) => ( + { + alert(`You clicked the color ${color} with label ${children}`) + }}> + {children} + +); + +This is Docusaurus green ! + +This is Facebook blue ! +``` + +export const Highlight = ({children, color}) => ( + { + alert(`You clicked the color ${color} with label ${children}`); + }}> + {children} + +); + +This is Docusaurus green ! + +This is Facebook blue ! diff --git a/docs/i18n/pt-BR/docusaurus-plugin-content-docs/current/tutorial-extras/_category_.json b/docs/i18n/pt-BR/docusaurus-plugin-content-docs/current/tutorial-extras/_category_.json new file mode 100644 index 0000000..a8ffcc1 --- /dev/null +++ b/docs/i18n/pt-BR/docusaurus-plugin-content-docs/current/tutorial-extras/_category_.json @@ -0,0 +1,7 @@ +{ + "label": "Tutorial - Extras", + "position": 3, + "link": { + "type": "generated-index" + } +} diff --git a/docs/i18n/pt-BR/docusaurus-plugin-content-docs/current/tutorial-extras/img/docsVersionDropdown.png b/docs/i18n/pt-BR/docusaurus-plugin-content-docs/current/tutorial-extras/img/docsVersionDropdown.png new file mode 100644 index 0000000..97e4164 Binary files /dev/null and b/docs/i18n/pt-BR/docusaurus-plugin-content-docs/current/tutorial-extras/img/docsVersionDropdown.png differ diff --git a/docs/i18n/pt-BR/docusaurus-plugin-content-docs/current/tutorial-extras/img/localeDropdown.png b/docs/i18n/pt-BR/docusaurus-plugin-content-docs/current/tutorial-extras/img/localeDropdown.png new file mode 100644 index 0000000..e257edc Binary files /dev/null and b/docs/i18n/pt-BR/docusaurus-plugin-content-docs/current/tutorial-extras/img/localeDropdown.png differ diff --git a/docs/i18n/pt-BR/docusaurus-plugin-content-docs/current/tutorial-extras/manage-docs-versions.md b/docs/i18n/pt-BR/docusaurus-plugin-content-docs/current/tutorial-extras/manage-docs-versions.md new file mode 100644 index 0000000..ccda0b9 --- /dev/null +++ b/docs/i18n/pt-BR/docusaurus-plugin-content-docs/current/tutorial-extras/manage-docs-versions.md @@ -0,0 +1,55 @@ +--- +sidebar_position: 1 +--- + +# Manage Docs Versions + +Docusaurus can manage multiple versions of your docs. + +## Create a docs version + +Release a version 1.0 of your project: + +```bash +npm run docusaurus docs:version 1.0 +``` + +The `docs` folder is copied into `versioned_docs/version-1.0` and `versions.json` is created. + +Your docs now have 2 versions: + +- `1.0` at `http://localhost:3000/docs/` for the version 1.0 docs +- `current` at `http://localhost:3000/docs/next/` for the **upcoming, unreleased docs** + +## Add a Version Dropdown + +To navigate seamlessly across versions, add a version dropdown. + +Modify the `docusaurus.config.js` file: + +```js title="docusaurus.config.js" +export default { + themeConfig: { + navbar: { + items: [ + // highlight-start + { + type: 'docsVersionDropdown', + }, + // highlight-end + ], + }, + }, +}; +``` + +The docs version dropdown appears in your navbar: + +![Docs Version Dropdown](./img/docsVersionDropdown.png) + +## Update an existing version + +It is possible to edit versioned docs in their respective folder: + +- `versioned_docs/version-1.0/hello.md` updates `http://localhost:3000/docs/hello` +- `docs/hello.md` updates `http://localhost:3000/docs/next/hello` diff --git a/docs/i18n/pt-BR/docusaurus-plugin-content-docs/current/tutorial-extras/translate-your-site.md b/docs/i18n/pt-BR/docusaurus-plugin-content-docs/current/tutorial-extras/translate-your-site.md new file mode 100644 index 0000000..b5a644a --- /dev/null +++ b/docs/i18n/pt-BR/docusaurus-plugin-content-docs/current/tutorial-extras/translate-your-site.md @@ -0,0 +1,88 @@ +--- +sidebar_position: 2 +--- + +# Translate your site + +Let's translate `docs/intro.md` to French. + +## Configure i18n + +Modify `docusaurus.config.js` to add support for the `fr` locale: + +```js title="docusaurus.config.js" +export default { + i18n: { + defaultLocale: 'en', + locales: ['en', 'fr'], + }, +}; +``` + +## Translate a doc + +Copy the `docs/intro.md` file to the `i18n/fr` folder: + +```bash +mkdir -p i18n/fr/docusaurus-plugin-content-docs/current/ + +cp docs/intro.md i18n/fr/docusaurus-plugin-content-docs/current/intro.md +``` + +Translate `i18n/fr/docusaurus-plugin-content-docs/current/intro.md` in French. + +## Start your localized site + +Start your site on the French locale: + +```bash +npm run start -- --locale fr +``` + +Your localized site is accessible at [http://localhost:3000/fr/](http://localhost:3000/fr/) and the `Getting Started` page is translated. + +:::caution + +In development, you can only use one locale at a time. + +::: + +## Add a Locale Dropdown + +To navigate seamlessly across languages, add a locale dropdown. + +Modify the `docusaurus.config.js` file: + +```js title="docusaurus.config.js" +export default { + themeConfig: { + navbar: { + items: [ + // highlight-start + { + type: 'localeDropdown', + }, + // highlight-end + ], + }, + }, +}; +``` + +The locale dropdown now appears in your navbar: + +![Locale Dropdown](./img/localeDropdown.png) + +## Build your localized site + +Build your site for a specific locale: + +```bash +npm run build -- --locale fr +``` + +Or build your site to include all the locales at once: + +```bash +npm run build +``` diff --git a/docs/i18n/pt-BR/docusaurus-plugin-content-docs/current/usage/analyzers.md b/docs/i18n/pt-BR/docusaurus-plugin-content-docs/current/usage/analyzers.md new file mode 100644 index 0000000..e725a9d --- /dev/null +++ b/docs/i18n/pt-BR/docusaurus-plugin-content-docs/current/usage/analyzers.md @@ -0,0 +1,48 @@ +--- +sidebar_position: 2 +--- + +# Understanding SpiceCode Analyzers + +Beyond the core command-line operations, the true power of SpiceCode resides in its suite of code analyzers. These specialized modules delve into your source code, examining various aspects of its structure, style, and composition to provide valuable metrics and insights. Think of each analyzer as a unique Fremen sense, honed to perceive specific details within the complex environment of your codebase. This guide explores the different analyzers available within SpiceCode, explaining what each one measures and how the resulting metrics can help you improve your code quality. + +When you run the `spice analyze` command without the `--all` flag, you are presented with an interactive menu listing these analyzers. This allows you to selectively focus on specific areas of interest. Alternatively, using `spice analyze --all` or the `spice export` command runs all applicable analyzers for the given file's language. + +## Available Analyzers + +SpiceCode includes a range of analyzers designed to provide a holistic view of your code. Here is a detailed look at the standard analyzers and the information they provide: + +### Line Count Analysis (`count_lines`) + +This fundamental analyzer provides a basic but essential breakdown of the physical lines within your code file. It differentiates between the total number of lines, lines that contain actual source code (excluding comments and blank lines), and lines that are purely blank. Understanding the sheer volume of code and its density is often the first step in assessing a file's complexity and maintainability. + +* **Total Lines:** The absolute number of lines in the file. +* **Code Lines:** The number of lines containing executable code or declarations. +* **Blank Lines:** The number of lines that are empty or contain only whitespace. + +### Comment Analysis (`count_comment_lines`, `count_inline_comments`, `count_comment_ratio`) + +Effective commenting is crucial for code understanding and maintenance. SpiceCode offers several analyzers focused specifically on comments: + +* **`count_comment_lines`**: This analyzer counts the total number of lines that are dedicated solely to comments (e.g., lines starting with `#` in Python or `//` in JavaScript/Go, or block comments). +* **`count_inline_comments`**: This measures the number of comments that appear on the same line as executable code (e.g., `x = 5 # Initialize x`). While sometimes useful, excessive inline comments can sometimes indicate complex or unclear code. +* **`count_comment_ratio`**: This calculates the ratio of comment lines to code lines. It provides a quantitative measure of how well-commented the code is. While there's no single "perfect" ratio, this metric can help identify files that might be under-commented or potentially over-commented. + +### Function and Method Analysis (`count_functions`, `count_method_type`) + +Understanding the structure and complexity of functions or methods is vital for assessing modularity and potential refactoring needs. + +* **`count_functions`**: This analyzer identifies and counts the number of distinct functions or methods defined within the file. A very high number might suggest the file has too many responsibilities and could benefit from being broken down. +* **`count_method_type`**: (Details might vary by language implementation) This analyzer likely categorizes methods based on certain characteristics, potentially distinguishing between public/private methods, static methods, constructors, etc. This provides insight into the object-oriented design or structural patterns used. + +### Dependency Analysis (`count_external_dependencies`) + +Managing external dependencies is a critical aspect of software development. This analyzer identifies and counts the number of external libraries or modules imported or required by the code file. A high number of external dependencies can increase the complexity of managing the project and potentially introduce more points of failure or security vulnerabilities. It helps gauge the file's reliance on outside code. + +### Indentation Analysis (`indentation`) + +Consistent indentation is fundamental to code readability, especially in languages where indentation defines code blocks (like Python). This analyzer examines the indentation patterns used throughout the file. It typically checks for consistency (e.g., using spaces vs. tabs, consistent number of spaces per indentation level) and might flag inconsistencies or mixed indentation styles, which can hinder readability and sometimes even lead to errors in languages like Python. + +## Interpreting the Results + +The metrics provided by these analyzers offer objective data about your code. However, interpretation requires context. A high line count isn't necessarily bad if the code is well-structured and commented. A low comment ratio might be acceptable for simple, self-explanatory code but problematic for complex algorithms. Use these metrics not as absolute judgments but as indicators – flags that draw your attention to areas potentially worth investigating further. They are the subtle signs in the sand that a skilled Fremen reads to understand the environment. By regularly running these analyzers and tracking the metrics over time, you can gain valuable insights into your codebase's evolution and maintain a high standard of quality. diff --git a/docs/i18n/pt-BR/docusaurus-plugin-content-docs/current/usage/cli.md b/docs/i18n/pt-BR/docusaurus-plugin-content-docs/current/usage/cli.md new file mode 100644 index 0000000..891620d --- /dev/null +++ b/docs/i18n/pt-BR/docusaurus-plugin-content-docs/current/usage/cli.md @@ -0,0 +1,124 @@ +--- +sidebar_position: 1 +--- + +# Using the SpiceCode CLI + +Interacting with SpiceCode is primarily done through its Command Line Interface (CLI). Designed for ease of use and flexibility, the CLI provides a set of commands to perform code analysis, manage settings, and export results. This guide details the available commands and their options, empowering you to effectively wield SpiceCode like a Fremen masterfully handling their maker hooks to navigate the great sandworms. + +## Core Commands + +SpiceCode offers several core commands for basic interaction and configuration. + +### Checking the Version + +To determine the currently installed version of SpiceCode, you can use the `version` command. This is often the first step to ensure the tool is installed correctly and to know which specific release you are working with. + +```bash +spice version +``` + +Executing this command will display the version number, such as `SpiceCode version 1.0.0`. + +### Displaying a Welcome Message + +For a simple confirmation that the CLI is responsive, or just for a friendly greeting reminiscent of Fremen hospitality, you can use the `hello` command. + +```bash +spice hello +``` + +This command outputs a standard welcome message from the SpiceCode tool. + +### Configuring Language Settings + +SpiceCode supports multiple interface languages, allowing users to interact with the tool in their preferred language, much like the diverse dialects spoken across the sietches of Arrakis. The `translate` command initiates an interactive prompt to select and set the desired language for CLI output and messages. + +```bash +spice translate +``` + +Follow the on-screen prompts to choose from the available language options. + +## Code Analysis Commands + +The heart of SpiceCode lies in its ability to analyze source code. The `analyze` command is the gateway to these capabilities. + +### Basic Interactive Analysis + +To initiate an analysis on a specific source code file, use the `analyze` command followed by the path to the file. + +```bash +spice analyze path/to/your/codefile.ext +``` + +Replace `path/to/your/codefile.ext` with the actual path to the file you wish to analyze (e.g., `src/main.py`, `lib/utils.js`). When run in this basic form, SpiceCode first identifies the programming language based on the file extension. It then parses the code and presents an interactive menu listing all the analysis metrics applicable to that language. You can navigate this menu using your keyboard to select one or more specific analyses to perform. The results of the selected analyses are then displayed directly in the terminal. + +### Comprehensive Analysis (`--all`) + +If you wish to perform all available analyses for a given file without the need for interactive selection, you can append the `--all` flag to the `analyze` command. This provides a complete overview of the file's metrics in one go, similar to a Fremen conducting a thorough reconnaissance. + +```bash +spice analyze path/to/your/codefile.ext --all +``` + +This command runs every analyzer relevant to the detected language and prints a consolidated report of all results to the terminal. + +### JSON Output (`--json`) + +For scenarios where you need to programmatically process the analysis results, such as integrating SpiceCode into automated workflows or other tools, you can request the output in JSON format using the `--json` flag. + +```bash +spice analyze path/to/your/codefile.ext --json +``` + +This command performs the analysis (either interactively or with `--all` if combined) and outputs the results as a structured JSON object to the standard output. This format is ideal for parsing and further processing by scripts or applications. + +```bash +# Example combining --all and --json +spice analyze path/to/your/codefile.ext --all --json +``` + +## Exporting Analysis Results + +While the `analyze` command is useful for immediate feedback, the `export` command allows you to save comprehensive analysis results to files in various formats. This is essential for record-keeping, report generation, or sharing findings, akin to Fremen meticulously documenting their water discipline. + +The `export` command requires the path to the source file and typically involves specifying the desired output format and the path for the output file. + +```bash +spice export path/to/your/codefile.ext --format --output +``` + +- `path/to/your/codefile.ext`: The source code file to be analyzed. +- `--format `: Specifies the desired output format. Supported formats are: + - `json`: JavaScript Object Notation + - `csv`: Comma-Separated Values + - `markdown`: Markdown text format + - `html`: HTML document format +- `--output `: Specifies the file path where the results should be saved. + +**Examples:** + +Exporting analysis results to a Markdown file: +```bash +spice export src/app.go --format markdown --output reports/app_analysis.md +``` + +Exporting analysis results to a JSON file: +```bash +spice export lib/parser.rb --format json --output data/parser_metrics.json +``` + +Exporting analysis results to a CSV file: +```bash +spice export main.py --format csv --output results/main_stats.csv +``` + +Exporting analysis results to an HTML file: +```bash +spice export component.js --format html --output docs/component_report.html +``` + +The `export` command implicitly runs all applicable analyses on the specified file before generating the output in the chosen format. + +Mastering these CLI commands provides you with the fundamental skills to effectively utilize SpiceCode for understanding and improving your codebase. Explore these commands with your own projects to become as adept with SpiceCode as a Fremen is with the ways of the desert. diff --git a/docs/i18n/pt-BR/docusaurus-plugin-content-pages/markdown-page.md b/docs/i18n/pt-BR/docusaurus-plugin-content-pages/markdown-page.md new file mode 100644 index 0000000..9756c5b --- /dev/null +++ b/docs/i18n/pt-BR/docusaurus-plugin-content-pages/markdown-page.md @@ -0,0 +1,7 @@ +--- +title: Markdown page example +--- + +# Markdown page example + +You don't need React to write simple standalone pages. diff --git a/docs/i18n/pt-BR/temp.txt b/docs/i18n/pt-BR/temp.txt new file mode 100644 index 0000000..b11c8ee --- /dev/null +++ b/docs/i18n/pt-BR/temp.txt @@ -0,0 +1,2 @@ +i'm not sure what do to now the documentation doesnt cover this part +https://docusaurus.io/docs/i18n/tutorial \ No newline at end of file