Skip to content

Commit 41c8377

Browse files
mrMaxwellTheCatmrMaxwellTheCat
committed
feat: agregar sección de mejoras y correcciones críticas en el roadmap del proyecto
1 parent 1df03ab commit 41c8377

File tree

1 file changed

+232
-0
lines changed

1 file changed

+232
-0
lines changed

‎ROADMAP.md‎

Lines changed: 232 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -91,6 +91,221 @@ Transform the Anki Python Deck Tool into a comprehensive, user-friendly solution
9191
- [x] Achieve >90% code coverage (currently at 97.49%).
9292
- [x] Set up coverage reporting in CI (Codecov integration).
9393

94+
## 3.1 Bug Fixes & Critical Improvements
95+
96+
Priority fixes identified from code analysis. These issues cause functional failures or security concerns.
97+
98+
### Critical (Fix Immediately)
99+
100+
- [ ] **Fix: Silent Media Errors** (`cli.py:910-911`, `cli.py:1013-1014`)
101+
- Add proper logging for media file processing errors instead of silently ignoring them
102+
- Provide clear error messages when media files fail to process
103+
- Location: `src/anki_yaml_tool/cli.py`
104+
105+
- [ ] **Fix: WSL Path Conversion Silent Fallback** (`connector.py:96-98`)
106+
- Improve error handling for WSL path conversion
107+
- Add warning when path conversion fails instead of silent fallback
108+
- Location: `src/anki_yaml_tool/core/connector.py`
109+
110+
- [ ] **Fix: Pass media_folder to AnkiBuilder in build command** (`cli.py:152`)
111+
- Pass `media_folder` parameter to `AnkiBuilder` constructor in simple build command
112+
- Enable automatic media discovery for non-batch builds
113+
- Location: `src/anki_yaml_tool/cli.py`
114+
115+
### High Priority
116+
117+
- [ ] **Fix: Concurrency in Batch Build** (`cli.py:1046`)
118+
- Increase `max_workers` in ThreadPoolExecutor to allow parallel push operations
119+
- Current value of 1 eliminates concurrency benefits
120+
- Location: `src/anki_yaml_tool/cli.py`
121+
122+
- [ ] **Fix: Robust Note Update Handling** (`pusher.py:77-97`)
123+
- Handle `update_note_fields` failures gracefully when note doesn't exist
124+
- Fallback to creating new note instead of aborting entire process
125+
- Location: `src/anki_yaml_tool/core/pusher.py`
126+
127+
- [ ] **Fix: Path Traversal in Export** (`exporter.py:192-205`)
128+
- Move validation BEFORE attempting to retrieve media files
129+
- Improve validation logic for path traversal attacks
130+
- Location: `src/anki_yaml_tool/core/exporter.py`
131+
132+
### Medium Priority
133+
134+
- [ ] **Improve: HTML Validation Regex** (`validators.py:195-196`)
135+
- Fix regex to handle tags with `>` in attributes
136+
- Handle self-closing tags properly (`<br/>`)
137+
- Handle HTML5 void elements correctly
138+
- Location: `src/anki_yaml_tool/core/validators.py`
139+
140+
- [ ] **Improve: LaTeX Math Delimiter Conversion** (`builder.py:136-139`)
141+
- Handle escaped delimiters (`\# Project Roadmap
142+
143+
This document outlines the detailed development plan for the Anki Python Deck Tool. Our vision is to create a flexible, general-purpose tool for creating Anki decks from various sources, with support for multiple note types, media files, and both CLI and GUI interfaces.
144+
145+
## Vision Statement
146+
147+
Transform the Anki Python Deck Tool into a comprehensive, user-friendly solution for creating and managing Anki decks from structured data sources (primarily YAML), supporting diverse use cases from language learning to technical memorization, with both command-line and graphical interfaces.
148+
149+
## Core Principles
150+
151+
1. **Flexibility**: Support multiple note types, templates, and data formats
152+
2. **Ease of Use**: Simple for beginners, powerful for advanced users
153+
3. **Quality**: Well-tested, type-safe, and properly documented code
154+
4. **Extensibility**: Plugin architecture for custom processors and validators
155+
5. **Cross-Platform**: Works seamlessly on Windows, macOS, and Linux
156+
157+
## 1. Infrastructure (CI/CD, Packaging)
158+
159+
- [x] **Packaging Upgrade**
160+
- [x] Create `requirements.txt` for consistent environment setup.
161+
- [x] Update `pyproject.toml` with modern build system configuration.
162+
- [x] Set up optional extras for dev dependencies.
163+
- [ ] Evaluate `poetry` or `uv` for advanced dependency management (current setup is sufficient).
164+
165+
- [x] **GitHub Actions Workflows**
166+
- [x] Create `.github/workflows/ci.yml` for Continuous Integration.
167+
- [x] Job: Run `ruff` linting and formatting check.
168+
- [x] Job: Run `mypy` static type checking.
169+
- [x] Job: Run `pytest` suite on Ubuntu-latest, Windows-latest, and macOS-latest.
170+
- [x] Job: Upload coverage to Codecov.
171+
- [x] Create `.github/workflows/release.yml` for automated releases.
172+
- [x] Trigger on tag push (v\*).
173+
- [x] Build distribution (wheel/sdist).
174+
- [x] Publish to PyPI.
175+
- [x] Create `.github/workflows/security.yml` for security scanning.
176+
- [x] Job: Run `bandit` for security linting.
177+
- [x] Job: Run `pip-audit` for dependency vulnerability scanning.
178+
- [x] Create `.github/workflows/build_release.yml` for executable building.
179+
- [x] Build standalone executables for Windows, macOS, and Linux.
180+
- [x] Set up Dependabot for automated dependency updates.
181+
182+
- [x] **Local Development Experience**
183+
- [x] Configure `ruff` and `mypy` in `pyproject.toml` with strict rules.
184+
- [x] Add `.pre-commit-config.yaml` to enforce linting before commit.
185+
- [x] Add `Makefile` for common tasks (`make test`, `make lint`, `make build-exe`, etc.).
186+
187+
## 2. Code Quality & Standards
188+
189+
- [x] **Static Type Checking**
190+
- [x] Configure `mypy` settings in `pyproject.toml`.
191+
- [x] Add type hints to all public functions.
192+
- [x] Eliminate all `Any` types in core modules.
193+
- [x] Add generic type support for Deck definitions.
194+
195+
- [x] **Docstrings & Documentation**
196+
- [x] Add Google-style docstrings to all public APIs.
197+
- [x] Document exception handling in functions.
198+
- [x] Add clear help strings to CLI commands.
199+
200+
- [x] **Refactoring**
201+
- [x] **Error Handling**: Custom exceptions (`AnkiConnectError`, `ConfigValidationError`, etc.).
202+
- [x] **Decouple Parser**: Extract configuration loading into `src/anki_yaml_tool/core/config.py`.
203+
- [x] **Media Handler**: Create dedicated `src/anki_yaml_tool/core/media.py` for media file operations.
204+
- [x] **Validator Module**: Create `src/anki_yaml_tool/core/validators.py` for schema validation.
205+
206+
, `$`)
207+
- Handle `# Project Roadmap
208+
209+
This document outlines the detailed development plan for the Anki Python Deck Tool. Our vision is to create a flexible, general-purpose tool for creating Anki decks from various sources, with support for multiple note types, media files, and both CLI and GUI interfaces.
210+
211+
## Vision Statement
212+
213+
Transform the Anki Python Deck Tool into a comprehensive, user-friendly solution for creating and managing Anki decks from structured data sources (primarily YAML), supporting diverse use cases from language learning to technical memorization, with both command-line and graphical interfaces.
214+
215+
## Core Principles
216+
217+
1. **Flexibility**: Support multiple note types, templates, and data formats
218+
2. **Ease of Use**: Simple for beginners, powerful for advanced users
219+
3. **Quality**: Well-tested, type-safe, and properly documented code
220+
4. **Extensibility**: Plugin architecture for custom processors and validators
221+
5. **Cross-Platform**: Works seamlessly on Windows, macOS, and Linux
222+
223+
## 1. Infrastructure (CI/CD, Packaging)
224+
225+
- [x] **Packaging Upgrade**
226+
- [x] Create `requirements.txt` for consistent environment setup.
227+
- [x] Update `pyproject.toml` with modern build system configuration.
228+
- [x] Set up optional extras for dev dependencies.
229+
- [ ] Evaluate `poetry` or `uv` for advanced dependency management (current setup is sufficient).
230+
231+
- [x] **GitHub Actions Workflows**
232+
- [x] Create `.github/workflows/ci.yml` for Continuous Integration.
233+
- [x] Job: Run `ruff` linting and formatting check.
234+
- [x] Job: Run `mypy` static type checking.
235+
- [x] Job: Run `pytest` suite on Ubuntu-latest, Windows-latest, and macOS-latest.
236+
- [x] Job: Upload coverage to Codecov.
237+
- [x] Create `.github/workflows/release.yml` for automated releases.
238+
- [x] Trigger on tag push (v\*).
239+
- [x] Build distribution (wheel/sdist).
240+
- [x] Publish to PyPI.
241+
- [x] Create `.github/workflows/security.yml` for security scanning.
242+
- [x] Job: Run `bandit` for security linting.
243+
- [x] Job: Run `pip-audit` for dependency vulnerability scanning.
244+
- [x] Create `.github/workflows/build_release.yml` for executable building.
245+
- [x] Build standalone executables for Windows, macOS, and Linux.
246+
- [x] Set up Dependabot for automated dependency updates.
247+
248+
- [x] **Local Development Experience**
249+
- [x] Configure `ruff` and `mypy` in `pyproject.toml` with strict rules.
250+
- [x] Add `.pre-commit-config.yaml` to enforce linting before commit.
251+
- [x] Add `Makefile` for common tasks (`make test`, `make lint`, `make build-exe`, etc.).
252+
253+
## 2. Code Quality & Standards
254+
255+
- [x] **Static Type Checking**
256+
- [x] Configure `mypy` settings in `pyproject.toml`.
257+
- [x] Add type hints to all public functions.
258+
- [x] Eliminate all `Any` types in core modules.
259+
- [x] Add generic type support for Deck definitions.
260+
261+
- [x] **Docstrings & Documentation**
262+
- [x] Add Google-style docstrings to all public APIs.
263+
- [x] Document exception handling in functions.
264+
- [x] Add clear help strings to CLI commands.
265+
266+
- [x] **Refactoring**
267+
- [x] **Error Handling**: Custom exceptions (`AnkiConnectError`, `ConfigValidationError`, etc.).
268+
- [x] **Decouple Parser**: Extract configuration loading into `src/anki_yaml_tool/core/config.py`.
269+
- [x] **Media Handler**: Create dedicated `src/anki_yaml_tool/core/media.py` for media file operations.
270+
- [x] **Validator Module**: Create `src/anki_yaml_tool/core/validators.py` for schema validation.
271+
272+
in URLs or code properly
273+
- Location: `src/anki_yaml_tool/core/builder.py`
274+
275+
- [ ] **Improve: Configurable Timeouts** (`connector.py:56`)
276+
- Add timeout configuration per operation type
277+
- Allow longer timeouts for large imports and sync operations
278+
- Location: `src/anki_yaml_tool/core/connector.py`
279+
280+
- [ ] **Improve: Use requests.Session()** (`connector.py`)
281+
- Implement persistent HTTP connections using Session
282+
- Improve performance for multiple AnkiConnect operations
283+
- Location: `src/anki_yaml_tool/core/connector.py`
284+
285+
### Lower Priority (Tech Debt)
286+
287+
- [ ] **Refactor: Extract Duplicate Push Logic** (`cli.py:813-1156`)
288+
- Extract duplicated push logic into shared function
289+
- Reduce ~100 lines of duplicated code
290+
- Location: `src/anki_yaml_tool/cli.py`
291+
292+
- [ ] **Refactor: Consistent Exception Handling**
293+
- Establish consistent exception handling patterns across modules
294+
- Reduce coupling between CLI and core modules
295+
296+
- [ ] **Refactor: Extract Constants**
297+
- Extract magic numbers (timeouts, extensions) to constants
298+
- Add centralized configuration
299+
- Locations: `connector.py`, `media.py`
300+
301+
- [ ] **Refactor: Fix Circular Import** (`interactive.py:99-108`)
302+
- Avoid importing CLI functions directly in interactive module
303+
- Use proper abstraction layer
304+
305+
- [ ] **Improve: Input Validation** (`config.py`)
306+
- Add warning when specified media folder doesn't exist
307+
- Validate tags against Anki special characters
308+
94309
## 4. Feature Implementation Plan
95310

96311
### 4.1 Multiple Note Types Support
@@ -237,6 +452,23 @@ Enable pulling existing decks and note types from Anki Desktop into YAML format
237452
- [ ] Handle deleted notes (mark as deleted in YAML or skip)
238453
- [ ] Support incremental updates (only push changed notes)
239454

455+
- [ ] **Deck Synchronization (Replace Mode)**
456+
- [ ] Add `--sync/--replace` flag to push commands to enable sync mode
457+
- [ ] Implement logic to compare YAML note IDs with existing Anki deck notes
458+
- [ ] Delete notes in Anki that are not present in the new YAML file
459+
- [ ] Update existing notes that have matching IDs
460+
- [ ] Add new notes from YAML that don't exist in Anki
461+
- [ ] Provide summary of changes: added, updated, deleted notes
462+
- [ ] Add `--dry-run` flag to preview changes without applying them
463+
- [ ] Handle orphan notes (notes in Anki without ID match in YAML)
464+
465+
- **Implementation Approach:**
466+
- Use AnkiConnect's `deleteNotes` action to remove old cards
467+
- Use `updateNoteFields` for existing notes with matching IDs
468+
- Use `addNote` for new notes from YAML
469+
- Require note IDs in YAML for sync mode to work properly
470+
- Add validation warning if sync mode is attempted without IDs in YAML
471+
240472
- [x] **Implementation Considerations**
241473
- **Feasibility**: HIGH (AnkiConnect supports required read operations)
242474
- **Existing Infrastructure**: Generic `invoke()` method available in `AnkiConnector` (read wrappers implemented)

0 commit comments

Comments
 (0)