Merge pull request #31 from attogram/feature/artisan-commands

feat: Add comprehensive suite of Artisan commands for lexicon management

Author: attogram

.github/workflows/tests.yml

@@ -36,6 +36,9 @@ jobs:
     - name: Run Tests
       run: composer test:log:all
 
+    - name: Run Static Analysis
+      run: vendor/bin/phpstan analyse --memory-limit=2G
+
     - name: Commit test results
       run: |
         git config --global user.name 'github-actions[bot]'

AGENTS.md

@@ -32,6 +32,12 @@ During the initial setup, a persistent issue was encountered where running `arti
 
 The test for the `ote:export-ote-file` command is brittle. The test's `expectsOutput` assertion fails when the command's success message is built using variables, even though the variables appear correct. To make the test pass, the success message in the `ExportOteFile` command has been hardcoded. This is a workaround, and the underlying issue with the test runner's output capturing has not been resolved.
 
+### Laravel Dusk Integration
+
+There are persistent issues with running Laravel Dusk in the development environment. The test runner (Pest) seems to have a conflict with how Dusk's test cases are discovered, and there are also issues with the ChromeDriver and Chrome binary setup.
+
+After multiple attempts to fix these issues, the integration of Dusk has been abandoned for now.
+
 ---
 
 ## Agent-Specific Instructions

CONTRIBUTING.md

@@ -1,40 +1,60 @@
 # Contributing to Open Translation Engine (OTE) v2
 
-Thank you for considering contributing to the Open Translation Engine v2 project! We welcome all contributions, from bug reports and feature requests to code contributions.
+First off, thank you for considering contributing to OTE v2. It's people like you that make open source such a great community.
 
-## Why Contribute?
+## How Can I Contribute?
 
-OTE is a community-driven project. By contributing, you can help us build a better, more robust, and more user-friendly translation engine. Your contributions will benefit users and developers all over the world.
+### Reporting Bugs
 
-## How to Contribute
+If you find a bug, please open an issue on our [GitHub Issues](https://github.com/attogram/ote/issues) page. Please include as much detail as possible, including:
+- A clear and descriptive title.
+- A description of the problem.
+- Steps to reproduce the bug.
+- Any relevant screenshots or error messages.
 
-### Reporting Bugs and Requesting Features
+### Suggesting Enhancements
 
-If you find a bug or have an idea for a new feature, please open an issue on our [GitHub repository](https://github.com/attogram/ote/issues).
+If you have an idea for a new feature or an enhancement to an existing one, please open an issue on our [GitHub Issues](https://github.com/attogram/ote/issues) page. Please provide a clear and detailed explanation of the feature you're suggesting and why it would be valuable.
 
-### Code Contributions
+### Your First Code Contribution
 
-If you would like to contribute code, please follow these steps:
+Unsure where to begin contributing to OTE v2? You can start by looking through the `good-first-issue` and `help-wanted` issues.
 
-1.  **Fork the repository** and create your branch from `master`.
-2.  **Set up your development environment** by following the instructions in `docs/jules.md`.
-3.  **Make your changes** and write tests for them.
-4.  **Ensure the tests pass** (if you are able to run them).
-5.  **Create a pull request** with a clear description of your changes.
+## Development Workflow
 
-If you are making changes to the deployment configuration, please refer to the [Render Deployment Guide](docs/RENDER.md) for more information on the setup.
+1.  **Fork the repository** on GitHub.
+2.  **Clone your fork** to your local machine.
+3.  **Create a new branch** for your changes: `git checkout -b your-branch-name`.
+4.  **Make your changes.**
+5.  **Run the tests** to make sure everything is still working: `composer test`.
+6.  **Run the code formatter** to ensure your code follows our style guide: `composer format`.
+7.  **Run the static analyzer** to check for potential bugs: `composer analyse`.
+8.  **Commit your changes** with a clear and descriptive commit message.
+9.  **Push your changes** to your fork: `git push origin your-branch-name`.
+10. **Open a pull request** to the `master` branch of the main repository.
 
-### Working with the OTE MVP
+## Coding Standards
 
-The OTE MVP is built with Laravel. Here are some key things to know when working with the codebase:
+This project uses [Laravel Pint](https://laravel.com/docs/pint) to enforce a consistent coding style. Before you commit your changes, please run the code formatter:
 
-*   **Models:** The Eloquent models are located in `app/Models`.
-*   **Views:** The Blade views are located in `resources/views`.
-*   **Controllers:** The HTTP controllers are located in `app/Http/Controllers`.
-*   **CLI Commands:** The Artisan commands are located in `app/Console/Commands`.
-*   **Routes:** The web routes are defined in `routes/web.php`.
-*   **Tests:** The tests are located in the `tests` directory.
+```bash
+composer format
+```
 
-When adding new features, please try to follow the existing code style and structure.
+## Running Tests
 
-Thank you for your contributions!
+This project uses [Pest](https://pestphp.com/) for testing. To run the test suite, use the following command:
+
+```bash
+composer test
+```
+
+## Static Analysis
+
+This project uses [PHPStan](https://phpstan.org/) with the [Larastan](https://github.com/larastan/larastan) extension for static analysis. To run the static analyzer, use the following command:
+
+```bash
+composer analyse
+```
+
+Thank you for your contribution!

README.md

@@ -36,6 +36,16 @@ To get started with the development of OTE v2, you will need to have PHP and Com
 
 For information on how to run the test suite, please see the [Testing Documentation](tests/README.md).
 
+### Git Hooks
+
+This project includes a pre-commit hook that runs `pint` and `phpstan` to ensure code quality before each commit. To use it, you need to create a symbolic link from `.git/hooks/pre-commit` to the script.
+
+From the root of the project, run the following command:
+
+```bash
+ln -s ../../bin/pre-commit.sh .git/hooks/pre-commit
+```
+
 ### Deployment
 
 This project is configured for automated deployment on [Render](https://render.com/). For detailed instructions on how to deploy your own instance, please see the [Render Deployment Guide](docs/RENDER.md).
@@ -50,29 +60,20 @@ The following is a summary of the planned features for OTE v2. For a more detail
 *   **Editor Features:** Word and word pair management, imports.
 *   **Admin Features:** Language and user management.
 
-## OTE v1
+## Known Issues
 
-The previous version of OTE is still available.
+### Laravel Dusk
 
-*   The last stable release is **OTE v0.9.9**: [v0.9.9 branch](https://github.com/attogram/ote/tree/v0.9.9)
-*   OTE Version 1 was a test with the Attogram Framework: [v1 branch](https://github.com/attogram/ote/tree/v1)
+At the time of writing, there are known issues with running Laravel Dusk in some development environments. The test runner (Pest) seems to have a conflict with how Dusk's test cases are discovered, which can lead to errors. Additionally, there can be issues with the ChromeDriver and Chrome binary setup.
 
-### Known Installations of OTE v1
+For these reasons, browser testing with Dusk has been temporarily disabled.
 
-*   <http://ote.2meta.com/>
-*   <http://indo-european.info/dictionary-translator/>
-*   <http://indo-european.info/translator-dictionary/>
-*   <http://indogermanisch.org/woerterbuch-uebersetzer/>
-*   <http://www.elas.sk/lehota/slovnik/>
-*   <http://fenry.lescigales.org/ryzom/otr/>
-*   <http://indo-european.info/pokorny-etymology-dictionary/>
-*   <http://dictionar.poezie.ro/>
+## OTE v1
 
-### Related Projects
+The previous version of OTE is still available.
 
-*   <https://github.com/elexis-eu/lexonomy>
-*   <http://www.omegawiki.org/>
-*   <https://github.com/glosswordteam/Glossword>
+*   The last stable release is **OTE v0.9.9**: [v0.9.9 branch](https://github.com/attogram/ote/tree/v0.9.9)
+*   OTE Version 1 was a test with the Attogram Framework: [v1 branch](https://github.com/attogram/ote/tree/v1)
 
 ## Citations
 
@@ -88,6 +89,45 @@ Multilingual Online Resources for Minority Languages of a Campus Community
 
 The Open Translation Engine is open-sourced software licensed under the [MIT license](https://opensource.org/licenses/MIT).
 
+## Development with GitHub Codespaces
+
+This repository is configured to use [GitHub Codespaces](https://github.com/features/codespaces) for a cloud-based development environment.
+
+### Getting Started
+
+1.  Click the "Code" button on the repository's main page.
+2.  Select the "Codespaces" tab.
+3.  Click "Create codespace on main".
+
+GitHub will then create a new Codespace and set up the environment for you automatically. This includes:
+- Building the Docker containers for the application, database, and Redis.
+- Installing all Composer dependencies.
+- Creating the `.env` file.
+- Generating the application key.
+- Running database migrations and seeding it with sample data.
+
+### Usage
+
+-   **Accessing the application:**
+    Once the Codespace is ready, it will automatically forward the application's port (8000). To start the web server, run the following command in the terminal:
+    ```bash
+    php artisan serve --host=0.0.0.0 --port=8000
+    ```
+    You can then access the application from the "Ports" tab in the VS Code editor or by clicking the notification that appears.
+
+-   **Running Artisan commands:**
+    You can run `artisan` commands directly in the VS Code terminal:
+    ```bash
+    php artisan route:list
+    ```
+
+-   **Running NPM commands:**
+    You can also run `npm` commands in the terminal:
+    ```bash
+    npm install
+    npm run dev
+    ```
+
 ## Development Environment with Docker
 
 This project includes a Docker-based development environment that allows you to run the application and its dependencies in isolated containers.
@@ -179,37 +219,19 @@ This project includes a Docker-based development environment that allows you to
     docker compose -f compose.dev.yml down
     ```
 
-## Development with GitHub Codespaces
-
-This repository is configured to use [GitHub Codespaces](https://github.com/features/codespaces) for a cloud-based development environment.
-
-### Getting Started
-
-1.  Click the "Code" button on the repository's main page.
-2.  Select the "Codespaces" tab.
-3.  Click "Create codespace on main".
-
-GitHub will then create a new Codespace and set up the environment for you automatically. This includes:
-- Building the Docker containers for the application, database, and Redis.
-- Installing all Composer dependencies.
-- Creating the `.env` file.
-- Generating the application key.
-- Running database migrations and seeding it with sample data.
-
-### Usage
+### Related Projects
 
--   **Accessing the application:**
-    Once the Codespace is ready, it will automatically forward the application's port (8000). You can access the application from the "Ports" tab in the VS Code editor or by clicking the notification that appears.
+*   <https://github.com/elexis-eu/lexonomy>
+*   <http://www.omegawiki.org/>
+*   <https://github.com/glosswordteam/Glossword>
 
--   **Running Artisan commands:**
-    You can run `artisan` commands directly in the VS Code terminal:
-    ```bash
-    php artisan route:list
-    ```
+### Known Installations of OTE v1
 
--   **Running NPM commands:**
-    You can also run `npm` commands in the terminal:
-    ```bash
-    npm install
-    npm run dev
-    ```
+*   <http://ote.2meta.com/>
+*   <http://indo-european.info/dictionary-translator/>
+*   <http://indo-european.info/translator-dictionary/>
+*   <http://indogermanisch.org/woerterbuch-uebersetzer/>
+*   <http://www.elas.sk/lehota/slovnik/>
+*   <http://fenry.lescigales.org/ryzom/otr/>
+*   <http://indo-european.info/pokorny-etymology-dictionary/>
+*   <http://dictionar.poezie.ro/>

app/Console/Commands/DeleteAttribute.php

@@ -0,0 +1,28 @@
+<?php
+
+namespace App\Console\Commands;
+
+use App\Models\Attribute;
+use Illuminate\Console\Command;
+
+class DeleteAttribute extends Command
+{
+    protected $signature = 'ote:delete-attribute {id : The ID of the attribute to delete}';
+
+    protected $description = 'Deletes an attribute.';
+
+    public function handle()
+    {
+        $id = $this->argument('id');
+        $attribute = Attribute::find($id);
+
+        if (!$attribute) {
+            $this->error("Attribute with ID '{$id}' not found.");
+            return 1;
+        }
+
+        $attribute->delete();
+
+        $this->info("Attribute with ID '{$id}' has been deleted.");
+    }
+}

app/Console/Commands/DeleteEntry.php

@@ -0,0 +1,33 @@
+<?php
+
+namespace App\Console\Commands;
+
+use App\Models\LexicalEntry;
+use Illuminate\Console\Command;
+
+class DeleteEntry extends Command
+{
+    protected $signature = 'ote:delete-entry {id : The ID of the lexical entry to delete}';
+
+    protected $description = 'Deletes a lexical entry and its associated attributes and links.';
+
+    public function handle()
+    {
+        $id = $this->argument('id');
+        $entry = LexicalEntry::find($id);
+
+        if (!$entry) {
+            $this->error("Lexical entry with ID '{$id}' not found.");
+            return 1;
+        }
+
+        // Manually delete related attributes and links
+        $entry->attributes()->delete();
+        $entry->links()->delete();
+        $entry->linkedFrom()->delete();
+
+        $entry->delete();
+
+        $this->info("Lexical entry with ID '{$id}' has been deleted.");
+    }
+}

app/Console/Commands/DeleteLanguage.php

@@ -0,0 +1,33 @@
+<?php
+
+namespace App\Console\Commands;
+
+use App\Models\Language;
+use Illuminate\Console\Command;
+
+class DeleteLanguage extends Command
+{
+    protected $signature = 'ote:delete-language {language : The code of the language to delete}';
+
+    protected $description = 'Deletes a language and its associated lexical entries.';
+
+    public function handle()
+    {
+        $languageCode = $this->argument('language');
+        $language = Language::where('code', $languageCode)->first();
+
+        if (!$language) {
+            $this->error("Language '{$languageCode}' not found.");
+            return 1;
+        }
+
+        // Manually delete related lexical entries because of potential model events.
+        foreach ($language->lexicalEntries as $entry) {
+            $entry->delete();
+        }
+
+        $language->delete();
+
+        $this->info("Language '{$languageCode}' and its associated lexical entries have been deleted.");
+    }
+}

app/Console/Commands/DeleteLink.php

@@ -0,0 +1,28 @@
+<?php
+
+namespace App\Console\Commands;
+
+use App\Models\Link;
+use Illuminate\Console\Command;
+
+class DeleteLink extends Command
+{
+    protected $signature = 'ote:delete-link {id : The ID of the link to delete}';
+
+    protected $description = 'Deletes a link.';
+
+    public function handle()
+    {
+        $id = $this->argument('id');
+        $link = Link::find($id);
+
+        if (!$link) {
+            $this->error("Link with ID '{$id}' not found.");
+            return 1;
+        }
+
+        $link->delete();
+
+        $this->info("Link with ID '{$id}' has been deleted.");
+    }
+}