logseq-matryca-parser 1.4.0__tar.gz → 1.4.1__tar.gz

{logseq_matryca_parser-1.4.0 → logseq_matryca_parser-1.4.1}/CHANGELOG.md

@@ -7,6 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.4.1] - 2026-06-24
+
+### Added
+
+- **Test coverage (wave 1)** — Community contribution ([#42](https://github.com/MarcoPorcellato/logseq-matryca-parser/pull/42)): **107** new pytest cases (**378** total) across parser helpers (`normalize_logseq_timestamp`, `clean_node_content`), `logseq_paths` fallbacks, exception hierarchy, `extract_changelog` release script, KINETIC per-command `--help`, `agent-read --query`, and direct `ObsidianForgeVisitor` tests. New modules: `tests/test_exceptions.py`, `tests/test_extract_changelog.py`. Closes [#21](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/21)–[#24](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/24), [#27](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/27), [#30](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/30)–[#32](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/32).
+- **Good first issues (wave 2)** — Ten new contributor tasks ([#43](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/43)–[#52](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/52)) indexed as GFI-17–GFI-26 in [`docs/GOOD_FIRST_ISSUES.md`](docs/GOOD_FIRST_ISSUES.md); wave-1 GFI items marked complete.
+
+### Changed
+
+- **Contributor docs** — [`README.md`](README.md), [`docs/README.md`](docs/README.md), [`CONTRIBUTING.md`](CONTRIBUTING.md), [`SECURITY.md`](SECURITY.md), and [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) harmonized for **v1.4.1** (test count, issue index range, supported versions).
+
 ## [1.4.0] - 2026-06-23
 
 ### Added

{logseq_matryca_parser-1.4.0 → logseq_matryca_parser-1.4.1}/CONTRIBUTING.md

@@ -15,7 +15,7 @@ User-facing behavior is documented in:
 - [`README.md`](README.md) — overview, quickstart, and feature matrix
 - [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) — LOGOS, SYNAPSE, `LogseqGraph`, agents, and data flow
 - [`docs/logseq_ast_primer.md`](docs/logseq_ast_primer.md) — Logseq Spatial Markdown domain rules
-- [`CHANGELOG.md`](CHANGELOG.md) — shipped releases (current: **1.4.0**) and **Unreleased** changes (Keep a Changelog)
+- [`CHANGELOG.md`](CHANGELOG.md) — shipped releases (current: **1.4.1**) and **Unreleased** changes (Keep a Changelog)
 - [`docs/RELEASE_PROCESS.md`](docs/RELEASE_PROCESS.md) — version bump, tag, and PyPI publish checklist
 - [`docs/CODEQL.md`](docs/CODEQL.md) — CodeQL default setup (no custom `codeql.yml`)
 - [`docs/GOOD_FIRST_ISSUES.md`](docs/GOOD_FIRST_ISSUES.md) — curated starter tasks for new contributors
@@ -44,7 +44,7 @@ New to the codebase? Start here:
 2. **Comment on the issue** so others know you are working on it.
 3. **Set up** with `uv sync --all-extras` and confirm `make all` is green on `main`.
 4. **Branch** using `feat/…`, `test/…`, or `docs/…` naming (see workflow below).
-5. **Submit** a PR that links the issue (`Fixes #123`).
+5. **Submit** one PR per issue, branched from `main` (`Fixes #123`).
 
 Tier 1 tasks are **test-only** — no parser changes, ideal for learning `CliRunner` and pytest patterns in `tests/`. Tier 2 is documentation. Tier 3 adds small CLI or FORGE features with explicit acceptance criteria.
 
@@ -124,6 +124,8 @@ CI runs the same commands as your local environment: `uv sync --all-extras`, the
 make all
 ```
 
+As of **v1.4.1**, `make test` runs **378** pytest cases with **≥80%** line coverage on `src/logseq_matryca_parser` (currently ~**90%**). New contributors should mirror patterns in [`docs/GOOD_FIRST_ISSUES.md`](docs/GOOD_FIRST_ISSUES.md) and the module map in that file’s **Test suite** section.
+
 Or run each step individually:
 
 ```bash
@@ -150,9 +152,9 @@ We follow [Conventional Commits](https://www.conventionalcommits.org/). Your com
 
 ### 6. Submit a Pull Request (PR)
 
-- Push your branch and open a PR against the `main` branch.
+- Push your branch and open a PR against the `main` branch (**one issue per PR**).
 - Describe why the change is needed.
-- Link the relevant Issue (e.g., `Fixes #123`).
+- Link the relevant Issue (e.g., `Fixes #123`). **One issue per PR** — do not stack multiple issues on a single branch.
 - Ensure all GitHub Actions (CI) checks pass.
 
 ---

{logseq_matryca_parser-1.4.0 → logseq_matryca_parser-1.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: logseq-matryca-parser
-Version: 1.4.0
+Version: 1.4.1
 Summary: The Logos Protocol: Deterministic Logseq AST parsing for Matryca.ai.
 Project-URL: Homepage, https://github.com/MarcoPorcellato/logseq-matryca-parser
 Project-URL: Repository, https://github.com/MarcoPorcellato/logseq-matryca-parser
@@ -53,7 +53,7 @@ Description-Content-Type: text/markdown
 [![Status: Stable](https://img.shields.io/badge/Status-Stable-22c55e.svg?style=flat-square)](#)
 ![Origin: Matryca.ai](https://img.shields.io/badge/Origin-Matryca.ai-gold?style=for-the-badge)
 
-**v1.4.0** — Robustness & graph-integrity release: 31 bug-hunt fixes, canonical page iteration, case-insensitive tag/search, live watcher delete/move, SYNAPSE embed safety (see [CHANGELOG](CHANGELOG.md)) — **271 tests**.
+**v1.4.1** — Test-hardening patch: **378 tests** (+107), community coverage for parser helpers, CLI agents, FORGE visitors, and wave-2 good-first issues ([#43](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/43)–[#52](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/52)) — no production API changes (see [CHANGELOG](CHANGELOG.md)).
 
 > *Turning a forest of local plain-text files into a unified semantic powerhouse.*
 
@@ -147,6 +147,18 @@ Logseq Matryca Parser is a deterministic **Stack-Machine engine** that acts as t
 
 ---
 
+## ⚡ Release highlights (v1.4.1)
+
+Patch release — contributor test coverage and onboarding refresh. **No intentional changes** to parser, graph, or CLI runtime behavior.
+
+| Area | Change |
+| :--- | :--- |
+| **Test suite** | **378** pytest cases (**+107** vs v1.4.0): `normalize_logseq_timestamp`, `clean_node_content`, `logseq_paths` fallbacks, exception hierarchy, `extract_changelog` script, KINETIC `--help`, `agent-read --query`, direct `ObsidianForgeVisitor` tests ([#42](https://github.com/MarcoPorcellato/logseq-matryca-parser/pull/42)). |
+| **New test modules** | `tests/test_exceptions.py`, `tests/test_extract_changelog.py`. |
+| **Contributor index** | [`docs/GOOD_FIRST_ISSUES.md`](docs/GOOD_FIRST_ISSUES.md) wave 2 ([#43](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/43)–[#52](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/52)); wave-1 items marked complete. |
+
+---
+
 ## ⚡ Release highlights (v1.4.0)
 
 Minor release — graph integrity, export hygiene, and parser hardening from the local static-analysis bug hunt (waves 1–8). No intentional breaking changes to default parse behavior.
@@ -361,7 +373,7 @@ Marker syntax (`[#A]`, `SCHEDULED: <...>`, `DEADLINE: <...>`) is stripped from `
 ## 🛠️ Quickstart
 
 ```bash
-# Install from PyPI (latest: v1.4.0)
+# Install from PyPI (latest: v1.4.1)
 uv pip install logseq-matryca-parser
 
 # Optional: filesystem watcher for live incremental graph updates
@@ -458,7 +470,7 @@ We welcome issues, pull requests, and constructive feedback.
 
 | Resource | Link |
 | :--- | :--- |
-| **Good first issues** | [docs/GOOD_FIRST_ISSUES.md](docs/GOOD_FIRST_ISSUES.md) — starter tasks ([#19](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/19)–[#34](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/34)) |
+| **Good first issues** | [docs/GOOD_FIRST_ISSUES.md](docs/GOOD_FIRST_ISSUES.md) — starter tasks ([#19](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/19)–[#52](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/52)) |
 | **Contributing** | [CONTRIBUTING.md](CONTRIBUTING.md) — setup, tests, PR workflow |
 | **Cookbook** | [docs/COOKBOOK.md](docs/COOKBOOK.md) — integration recipes (Synapse, graph query, watcher) |
 | **Documentation index** | [docs/README.md](docs/README.md) — active vs historical docs |

{logseq_matryca_parser-1.4.0 → logseq_matryca_parser-1.4.1}/README.md

@@ -12,7 +12,7 @@
 [![Status: Stable](https://img.shields.io/badge/Status-Stable-22c55e.svg?style=flat-square)](#)
 ![Origin: Matryca.ai](https://img.shields.io/badge/Origin-Matryca.ai-gold?style=for-the-badge)
 
-**v1.4.0** — Robustness & graph-integrity release: 31 bug-hunt fixes, canonical page iteration, case-insensitive tag/search, live watcher delete/move, SYNAPSE embed safety (see [CHANGELOG](CHANGELOG.md)) — **271 tests**.
+**v1.4.1** — Test-hardening patch: **378 tests** (+107), community coverage for parser helpers, CLI agents, FORGE visitors, and wave-2 good-first issues ([#43](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/43)–[#52](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/52)) — no production API changes (see [CHANGELOG](CHANGELOG.md)).
 
 > *Turning a forest of local plain-text files into a unified semantic powerhouse.*
 
@@ -106,6 +106,18 @@ Logseq Matryca Parser is a deterministic **Stack-Machine engine** that acts as t
 
 ---
 
+## ⚡ Release highlights (v1.4.1)
+
+Patch release — contributor test coverage and onboarding refresh. **No intentional changes** to parser, graph, or CLI runtime behavior.
+
+| Area | Change |
+| :--- | :--- |
+| **Test suite** | **378** pytest cases (**+107** vs v1.4.0): `normalize_logseq_timestamp`, `clean_node_content`, `logseq_paths` fallbacks, exception hierarchy, `extract_changelog` script, KINETIC `--help`, `agent-read --query`, direct `ObsidianForgeVisitor` tests ([#42](https://github.com/MarcoPorcellato/logseq-matryca-parser/pull/42)). |
+| **New test modules** | `tests/test_exceptions.py`, `tests/test_extract_changelog.py`. |
+| **Contributor index** | [`docs/GOOD_FIRST_ISSUES.md`](docs/GOOD_FIRST_ISSUES.md) wave 2 ([#43](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/43)–[#52](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/52)); wave-1 items marked complete. |
+
+---
+
 ## ⚡ Release highlights (v1.4.0)
 
 Minor release — graph integrity, export hygiene, and parser hardening from the local static-analysis bug hunt (waves 1–8). No intentional breaking changes to default parse behavior.
@@ -320,7 +332,7 @@ Marker syntax (`[#A]`, `SCHEDULED: <...>`, `DEADLINE: <...>`) is stripped from `
 ## 🛠️ Quickstart
 
 ```bash
-# Install from PyPI (latest: v1.4.0)
+# Install from PyPI (latest: v1.4.1)
 uv pip install logseq-matryca-parser
 
 # Optional: filesystem watcher for live incremental graph updates
@@ -417,7 +429,7 @@ We welcome issues, pull requests, and constructive feedback.
 
 | Resource | Link |
 | :--- | :--- |
-| **Good first issues** | [docs/GOOD_FIRST_ISSUES.md](docs/GOOD_FIRST_ISSUES.md) — starter tasks ([#19](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/19)–[#34](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/34)) |
+| **Good first issues** | [docs/GOOD_FIRST_ISSUES.md](docs/GOOD_FIRST_ISSUES.md) — starter tasks ([#19](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/19)–[#52](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/52)) |
 | **Contributing** | [CONTRIBUTING.md](CONTRIBUTING.md) — setup, tests, PR workflow |
 | **Cookbook** | [docs/COOKBOOK.md](docs/COOKBOOK.md) — integration recipes (Synapse, graph query, watcher) |
 | **Documentation index** | [docs/README.md](docs/README.md) — active vs historical docs |

{logseq_matryca_parser-1.4.0 → logseq_matryca_parser-1.4.1}/SECURITY.md

@@ -6,8 +6,8 @@ Security fixes are provided **only for the latest released version** on [PyPI](h
 
 | Version | Supported |
 | ------- | --------- |
-| **1.4.0** (latest) | Yes |
-| Older releases | No |
+| **1.4.1** (latest) | Yes |
+| 1.4.0 and older | No |
 
 We recommend always running the current release and upgrading promptly when a security advisory is published.
 

{logseq_matryca_parser-1.4.0 → logseq_matryca_parser-1.4.1}/docs/ARCHITECTURE.md

@@ -557,7 +557,11 @@ Recursive and character-budget chunkers assume **approximately flat prose**. Log
 | :--- | :--- |
 | [`logseq_ast_primer.md`](logseq_ast_primer.md) | Before touching parser or serialization behavior |
 | [`COOKBOOK.md`](COOKBOOK.md) | Integration examples (Synapse, `LogseqGraph`, watcher) |
-| [`GOOD_FIRST_ISSUES.md`](GOOD_FIRST_ISSUES.md) | Picking a first PR ([#19](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/19)–[#34](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/34)) |
-| [`README.md`](README.md) | Documentation index (active vs historical) |
-| [`../CONTRIBUTING.md`](../CONTRIBUTING.md) | `uv` setup, `make all`, PR checklist |
+| [`GOOD_FIRST_ISSUES.md`](GOOD_FIRST_ISSUES.md) | Picking a first PR ([#19](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/19)–[#52](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/52)); wave 1 tests landed in **v1.4.1** |
+| [`README.md`](README.md) | Project overview and quickstart |
+| [`../CONTRIBUTING.md`](../CONTRIBUTING.md) | `uv` setup, `make all` (**378** pytest, ~**90%** coverage), PR checklist |
 | [`design-docs/README.md`](design-docs/README.md) | Warning before using historical DDD blueprints |
+
+### Quality gate (v1.4.1)
+
+Local and CI parity: `uv sync --all-extras` → `make lint` → `make check` → `make test`. The test gate enforces **≥80%** coverage on `src/logseq_matryca_parser` with **378** pytest cases as of **v1.4.1** (community wave 1 via [#42](https://github.com/MarcoPorcellato/logseq-matryca-parser/pull/42)). Dedicated modules: `tests/test_exceptions.py`, `tests/test_extract_changelog.py` — see [`GOOD_FIRST_ISSUES.md`](GOOD_FIRST_ISSUES.md) § Test suite.

{logseq_matryca_parser-1.4.0 → logseq_matryca_parser-1.4.1}/docs/BUG_HUNT_REPORT.md

@@ -5,7 +5,9 @@
 **Strumenti:** analisi statica locale (graph-based), `make all`, `scripts/debug_pre_release.py`, probe Python ad hoc  
 **Riferimenti architetturali:** [Clean Architecture](https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html) (R. C. Martin), [`ARCHITECTURE.md`](ARCHITECTURE.md)
 
-> **Stato risoluzione (2026-06-23):** tutti i **BUG-001…031** e le limitazioni **LIM-001/002** sono stati affrontati nel codice (vedi `CHANGELOG.md` `[Unreleased]`). **DEBT-001** (`iter_canonical_pages`, `page_for_node`) è implementato; debito architetturale residuo (SRP su `kinetic.py`, OCP embed strategy) resta backlog non bloccante.
+> **Stato risoluzione (2026-06-23):** tutti i **BUG-001…031** e le limitazioni **LIM-001/002** sono stati affrontati nel codice (vedi `CHANGELOG.md` **v1.4.0**). **DEBT-001** (`iter_canonical_pages`, `page_for_node`) è implementato; debito architetturale residuo (SRP su `kinetic.py`, OCP embed strategy) resta backlog non bloccante.
+>
+> **Aggiornamento test (2026-06-24, v1.4.1):** GFI-04 (`logseq_paths` fallback), GFI-14 (`normalize_logseq_timestamp`), GFI-03/05/06/09/12/13 e suite totale **378** pytest — vedi `CHANGELOG.md` **v1.4.1**.
 
 ---
 
@@ -13,8 +15,8 @@
 
 | Metrica | Esito |
 | :--- | :--- |
-| `make all` (Ruff + Mypy + 271 pytest) | **PASS** |
-| Coverage | **89.25%** (soglia 80%) |
+| `make all` (Ruff + Mypy + 378 pytest) | **PASS** |
+| Coverage | **90.18%** (soglia 80%; **378** pytest, v1.4.1) |
 | Round-trip corpus (`debug_pre_release.py`) | **19/19 OK** |
 | analisi statica `check` (cicli IMPORTS) | **0 cicli** |
 | analisi statica index | `logseq-matryca-parser` — 1074 embeddings, commit `7d3f77b` |
@@ -855,7 +857,7 @@ page_title_to_relative_path('') → PosixPath('untitled.md')
 write_logseq_page(page, dest) → scrive su pages/untitled.md (non crash)
 ```
 
-Comportamento diverso dalla nota precedente (non più `Errno 21` su path vuoto grazie al fallback `untitled.md`). Resta ambiguo per vault reali. Copertura test assente (GFI-04).
+Comportamento diverso dalla nota precedente (non più `Errno 21` su path vuoto grazie al fallback `untitled.md`). Resta ambiguo per vault reali. **Copertura:** GFI-04 chiuso in **v1.4.1** (`tests/test_logseq_paths.py`).
 
 ---
 
@@ -871,7 +873,7 @@ Valutazione secondo i principi di R. C. Martin, senza implicare che il codice si
 | **ISP** | Adapter SYNAPSE accede a `graph._page_for_node` (privato) | `synapse.py` L222 | Esporre `graph.page_for_node()` pubblico o protocol `GraphLookup`. |
 | **DIP** | Import lazy `logseq_paths` dentro metodo entity | `logos_core.py` L144 | Accettabile per evitare cicli; alternativa: spostare `resolve_asset_path` in use case layer. |
 | **Boundaries** | `assert bm is not None` in produzione | `synapse.py` L171, L190 | Sostituire con guard espliciti (Clean Code: fail fast leggibile, no assert in `-O`). |
-| **Error handling** | `except ValueError: pass` in normalizzazione timestamp | `logos_parser.py` L500 | Accettabile come fallback chain; aggiungere test GFI-14. |
+| **Error handling** | `except ValueError: pass` in normalizzazione timestamp | `logos_parser.py` L500 | Accettabile come fallback chain; **GFI-14 chiuso in v1.4.1** (`tests/test_logos_parser.py`). |
 | **ISP / encapsulation** | Consumer iterano `graph.pages.values()` raw | `kinetic.py`, `graph.py` | `iter_canonical_pages()` — DEBT-001; radice di BUG-002/006/007. |
 | **Use case completeness** | Nessun ramo *delete* in invalidazione incrementale | `graph.py` L641 | BUG-005; watcher senza delete/move — BUG-014 |
 
@@ -895,7 +897,7 @@ Linee non coperte con **alto rischio funzionale** (non solo numeri):
 | `logseq_markdown.py` | round-trip 4-space indent | **Alto** — BUG-021 |
 | `graph.py` | ghost nodes in search/query/agent-read | **Alto** — BUG-022 (con BUG-010) |
 | `kinetic.py` | `_export_langchain_enriched` alias dupes | **Alto** — BUG-006 |
-| `logseq_paths.py` | titolo vuoto, fallback graph root | **Basso** — GFI-04 |
+| `logseq_paths.py` | titolo vuoto, fallback graph root | **Risolto (v1.4.1)** — GFI-04 |
 
 ---
 
@@ -919,7 +921,7 @@ Linee non coperte con **alto rischio funzionale** (non solo numeri):
 | P3 | BUG-004 | Decisione ISO vs `%W` + doc/test | 1 h |
 | P4 | BUG-008, BUG-009, BUG-015, BUG-018–020, BUG-024–025, BUG-028–031 | case/`#`/namespace; export dup; asset path | backlog |
 | P5 | Debito | `graph.page_for_node` pubblico; rimuovere `assert` | 2 h |
-| P6 | Coverage | Chiudere GFI-01, GFI-02, GFI-14 | backlog |
+| P6 | Coverage | Chiudere GFI-01, GFI-02; wave 2 ([#43](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/43)–[#52](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/52)) | backlog |
 
 Dopo ogni fix: `make all` + `refresh dell'indice locale` + `impact` sul simbolo modificato.
 

{logseq_matryca_parser-1.4.0 → logseq_matryca_parser-1.4.1}/docs/CODEQL.md

@@ -1,6 +1,6 @@
 # CodeQL code scanning
 
-**Logseq Matryca Parser** (v1.4.0+) uses **GitHub CodeQL default setup** for static analysis (SAST) on Python.
+**Logseq Matryca Parser** (v1.4.1+) uses **GitHub CodeQL default setup** for static analysis (SAST) on Python.
 
 ## Why there is no `codeql.yml` workflow
 

{logseq_matryca_parser-1.4.0 → logseq_matryca_parser-1.4.1}/docs/COOKBOOK.md

@@ -127,7 +127,28 @@ if broken:
         print("broken ref in", node.clean_text)
 ```
 
-**CLI tip:** run `matryca-parse export` after `load_directory` — KINETIC scans canonical pages internally (v1.4.0).
+**CLI tip:** run `matryca-parse export` after `load_directory` — KINETIC scans canonical pages internally (since v1.4.0).
+
+---
+
+## Recipe 6 — Contributor test patterns
+
+Pick a scoped task from [`GOOD_FIRST_ISSUES.md`](GOOD_FIRST_ISSUES.md) (wave 2: [#43](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/43)–[#52](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/52)), then mirror nearby tests:
+
+```bash
+uv sync --all-extras
+make all   # 378 pytest cases, ≥80% coverage gate
+```
+
+| Pattern | Example module | Test file |
+| :--- | :--- | :--- |
+| Pure helper | `normalize_logseq_timestamp` | `tests/test_logos_parser.py` |
+| CLI `--help` / errors | `kinetic.py` | `tests/test_kinetic.py` |
+| FORGE visitor | `ObsidianForgeVisitor` | `tests/test_forge.py` |
+| Release script | `scripts/extract_changelog.py` | `tests/test_extract_changelog.py` |
+| Exception hierarchy | `exceptions.py` | `tests/test_exceptions.py` |
+
+Test-only PRs should not change runtime behavior — update `CHANGELOG.md` under `[Unreleased]` only when user-visible behavior changes.
 
 ---
 

{logseq_matryca_parser-1.4.0 → logseq_matryca_parser-1.4.1}/docs/GOOD_FIRST_ISSUES.md

@@ -7,7 +7,7 @@ Welcome! These tasks are scoped for a **first pull request** — mostly tests an
 1. Read [`CONTRIBUTING.md`](../CONTRIBUTING.md), [`ARCHITECTURE.md`](ARCHITECTURE.md) (skim the module map), and [`logseq_ast_primer.md`](logseq_ast_primer.md) if you touch parsing.
 2. Run `uv sync --all-extras` then `make all` to confirm a green baseline.
 3. Comment on the GitHub issue you want to claim so we avoid duplicate work.
-4. Open a PR linking the issue (`Fixes #NNN`).
+4. Open **one PR per issue**, branched from `main` (`Fixes #NNN`).
 
 Integrators may prefer [`COOKBOOK.md`](COOKBOOK.md) for copy-paste recipes before picking a code task.
 
@@ -23,10 +23,18 @@ Ideal first PR: no production code changes, copy patterns from nearby tests.
 | :--- | :--- | :--- | :--- |
 | GFI-01 | `test(kinetic): add CLI error-path coverage for missing graph and optional deps` | pytest, Typer | [#19](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/19) |
 | GFI-02 | `test(kinetic): cover agent-write validation errors` | pytest, CLI | [#20](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/20) |
-| GFI-03 | `test: add dedicated tests for exception hierarchy` | pytest | [#21](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/21) |
-| GFI-04 | `test(logseq_paths): cover empty title and fallback graph-root derivation` | pytest | [#22](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/22) |
-| GFI-05 | `test: add unit tests for extract_changelog release helper` | pytest | [#23](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/23) |
-| GFI-06 | `test(agent): add CLI test for agent-read --query filter` | pytest, CLI | [#24](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/24) |
+| GFI-03 | `test: add dedicated tests for exception hierarchy` | pytest | [#21](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/21) ✅ |
+| GFI-04 | `test(logseq_paths): cover empty title and fallback graph-root derivation` | pytest | [#22](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/22) ✅ |
+| GFI-05 | `test: add unit tests for extract_changelog release helper` | pytest | [#23](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/23) ✅ |
+| GFI-06 | `test(agent): add CLI test for agent-read --query filter` | pytest, CLI | [#24](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/24) ✅ |
+| GFI-17 | `test(logseq_markdown): unit tests for detect_tab_size_from_markdown` | pytest | [#43](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/43) |
+| GFI-18 | `test(synapse): table-driven tests for _strip_markdown_for_embedding` | pytest | [#44](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/44) |
+| GFI-19 | `test(graph): unit tests for _normalize_relative_link_target helper` | pytest | [#45](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/45) |
+| GFI-20 | `test(extract_changelog): cover main() CLI exit codes and stdout` | pytest | [#47](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/47) |
+| GFI-21 | `test(agent_writer): cover LogseqConfigReader format_timestamp and config fallback` | pytest, CLI | [#48](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/48) |
+| GFI-22 | `test(lens): classify journal and project nodes in GraphVisualizer` | pytest | [#49](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/49) |
+| GFI-23 | `test(graph): unit tests for backlink alias token helpers` | pytest | [#50](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/50) |
+| GFI-24 | `test(synapse): direct build_synapse_metadata schema coverage` | pytest | [#51](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/51) |
 
 ---
 
@@ -36,7 +44,7 @@ Ideal first PR: no production code changes, copy patterns from nearby tests.
 | :--- | :--- | :--- | :--- |
 | GFI-07 | `docs: add examples cookbook for common integration recipes` | Markdown, Python snippets | [#25](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/25) *(initial [`COOKBOOK.md`](COOKBOOK.md) landed — extend or polish)* |
 | GFI-08 | `docs: add docs/README.md index warning about historical design-docs` | Markdown | [#26](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/26) *(index exists — verify links and `design-docs/README.md`)* |
-| GFI-09 | `test(kinetic): assert per-command --help renders without error` | pytest, Typer | [#27](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/27) |
+| GFI-09 | `test(kinetic): assert per-command --help renders without error` | pytest, Typer | [#27](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/27) ✅ |
 | GFI-10 | `docs(examples): translate run_demo.py comments to English and align with package imports` | Python, docs | [#28](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/28) *(done in repo — close if satisfied)* |
 
 ---
@@ -46,9 +54,11 @@ Ideal first PR: no production code changes, copy patterns from nearby tests.
 | ID | Title | Skills | Issue |
 | :--- | :--- | :--- | :--- |
 | GFI-11 | `feat(cli): add scan --broken-refs flag using LogseqGraph.get_broken_references()` | Typer, graph API | [#29](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/29) |
-| GFI-12 | `test(forge): add direct ObsidianForgeVisitor visitor tests` | pytest, FORGE | [#30](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/30) |
-| GFI-13 | `test(parser): table-driven tests for clean_node_content helper` | pytest | [#31](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/31) |
-| GFI-14 | `test(parser): unit tests for normalize_logseq_timestamp edge inputs` | pytest | [#32](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/32) |
+| GFI-12 | `test(forge): add direct ObsidianForgeVisitor visitor tests` | pytest, FORGE | [#30](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/30) ✅ |
+| GFI-13 | `test(parser): table-driven tests for clean_node_content helper` | pytest | [#31](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/31) ✅ |
+| GFI-14 | `test(parser): unit tests for normalize_logseq_timestamp edge inputs` | pytest | [#32](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/32) ✅ |
+| GFI-25 | `test(forge): direct MarkdownForgeVisitor property and id filtering` | pytest, FORGE | [#46](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/46) |
+| GFI-26 | `test(forge): direct JSONForgeVisitor nested stack behavior` | pytest, FORGE | [#52](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/52) |
 
 ---
 
@@ -61,6 +71,36 @@ Ideal first PR: no production code changes, copy patterns from nearby tests.
 
 ---
 
+## Recommended starter pack (wave 2)
+
+Best first picks from the new batch — pure helpers or clear fixtures:
+
+| Priority | ID | Why |
+| :---: | :--- | :--- |
+| 1 | GFI-19 ([#45](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/45)) | Pure function, parametrized table |
+| 2 | GFI-18 ([#44](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/44)) | Pure regex helper, high clarity |
+| 3 | GFI-17 ([#43](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/43)) | Small markdown utility, no graph I/O |
+| 4 | GFI-25 ([#46](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/46)) | Mirrors merged Obsidian visitor tests |
+| 5 | GFI-20 ([#47](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/47)) | Extends existing `test_extract_changelog.py` |
+
+---
+
+## Test suite (v1.4.1)
+
+| Module | Test file |
+| :--- | :--- |
+| Parser (LOGOS) | `tests/test_logos_parser.py` |
+| Graph & watcher | `tests/test_graph.py` |
+| SYNAPSE adapters | `tests/test_synapse.py` |
+| FORGE exporters | `tests/test_forge.py` |
+| KINETIC CLI | `tests/test_kinetic.py` |
+| Agent read/write | `tests/test_agent_press.py`, `tests/test_agent_writer.py` |
+| Paths & markdown | `tests/test_logseq_paths.py`, `tests/test_logseq_markdown.py` |
+| Release helpers | `tests/test_extract_changelog.py`, `tests/test_package_version.py` |
+| Exceptions | `tests/test_exceptions.py` |
+
+Run the full gate: `make all` (**378** pytest cases as of **v1.4.1**).
+
 ## Out of scope for a first PR
 
 - Changes to Pydantic models in `logos_core.py` (open a design issue first).

{logseq_matryca_parser-1.4.0 → logseq_matryca_parser-1.4.1}/docs/README.md

@@ -8,8 +8,8 @@ Use this page to find **active** documentation. Files under [`design-docs/`](des
 | :--- | :--- | :--- |
 | [`ARCHITECTURE.md`](ARCHITECTURE.md) | Contributors, integrators | LOGOS, SYNAPSE, `LogseqGraph`, agents, data flow |
 | [`logseq_ast_primer.md`](logseq_ast_primer.md) | Parser contributors | Logseq Spatial Markdown domain rules |
-| [`GOOD_FIRST_ISSUES.md`](GOOD_FIRST_ISSUES.md) | New contributors | Curated starter tasks ([#19](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/19)–[#34](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/34)) |
-| [`COOKBOOK.md`](COOKBOOK.md) | Integrators | Copy-paste recipes (Synapse, graph query, watcher, agents) |
+| [`GOOD_FIRST_ISSUES.md`](GOOD_FIRST_ISSUES.md) | New contributors | Curated starter tasks ([#19](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/19)–[#52](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/52); wave 1 landed in **v1.4.1**) |
+| [`COOKBOOK.md`](COOKBOOK.md) | Integrators | Copy-paste recipes (Synapse, graph query, watcher, agents, contributor test patterns) |
 | [`RELEASE_PROCESS.md`](RELEASE_PROCESS.md) | Maintainers | Semver, tag, and PyPI publish checklist |
 | [`CODEQL.md`](CODEQL.md) | Maintainers | CodeQL default setup notes |
 | [`BUG_HUNT_REPORT.md`](BUG_HUNT_REPORT.md) | Maintainers, contributors | Local static analysis bug audit (Clean Architecture lens, runtime evidence) |

{logseq_matryca_parser-1.4.0 → logseq_matryca_parser-1.4.1}/docs/logseq_ast_primer.md

@@ -215,7 +215,7 @@ If you feed Logseq Markdown into `RecursiveCharacterTextSplitter` (LangChain) or
 
 The **Logos Protocol** solves this by walking the AST deterministically, isolating properties, shielding dead-zone literals, and using the `SYNAPSE` adapter to export native LangChain `Document` or LlamaIndex `TextNode` objects. Every generated object retains its exact hierarchical lineage in the metadata, feeding your local LLM perfectly structured data.
 
-For vault-wide navigation (aliases, backlinks, namespace shadowing, assets), load the graph with **`LogseqGraph`** — see the [README](../README.md) and [CHANGELOG](../CHANGELOG.md) (graph parity from **v1.2.0**; **v1.3.0** adds watcher debounce, `strict_refs`, public API exports, and LlamaIndex spatial relationships; **v1.4.0** adds canonical page iteration, case-insensitive tag/search, watcher delete/move handling, and SYNAPSE embed safety).
+For vault-wide navigation (aliases, backlinks, namespace shadowing, assets), load the graph with **`LogseqGraph`** — see the [README](../README.md) and [CHANGELOG](../CHANGELOG.md) (graph parity from **v1.2.0**; **v1.3.0** adds watcher debounce, `strict_refs`, public API exports, and LlamaIndex spatial relationships; **v1.4.0** adds canonical page iteration, case-insensitive tag/search, watcher delete/move handling, and SYNAPSE embed safety; **v1.4.1** adds community test coverage for parser helpers, CLI agents, and FORGE visitors — **378** pytest cases, no runtime API changes).
 
 ---
 

{logseq_matryca_parser-1.4.0 → logseq_matryca_parser-1.4.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "logseq-matryca-parser"
-version = "1.4.0"
+version = "1.4.1"
 description = "The Logos Protocol: Deterministic Logseq AST parsing for Matryca.ai."
 readme = "README.md"
 requires-python = ">=3.12"

{logseq_matryca_parser-1.4.0 → logseq_matryca_parser-1.4.1}/src/logseq_matryca_parser/__init__.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 import sys
 
-__version__ = "1.4.0"
+__version__ = "1.4.1"
 
 from .agent_press import SessionAliasRegistry
 from .agent_writer import LogseqConfigReader, logseq_agent_write

{logseq_matryca_parser-1.4.0 → logseq_matryca_parser-1.4.1}/tests/test_agent_press.py

@@ -165,3 +165,60 @@ def test_agent_write_cli_splices_via_alias_state(tmp_path: Path) -> None:
 
     updated = (pages / "Write.md").read_text(encoding="utf-8")
     assert "Child from agent-write" in updated
+
+
+def test_agent_read_cli_query_filter_finds_matching_blocks(tmp_path: Path) -> None:
+    """``agent-read --query`` prints only blocks containing the search term."""
+    graph_root = tmp_path / "graph"
+    pages = graph_root / "pages"
+    pages.mkdir(parents=True)
+    (graph_root / "journals").mkdir()
+
+    (pages / "alpha.md").write_text(
+        "- Needle in a haystack #tag-a\n"
+        "  - Nested needle block\n",
+        encoding="utf-8",
+    )
+    (pages / "beta.md").write_text(
+        "- Irrelevant content #tag-b\n"
+        "  - Should not appear\n",
+        encoding="utf-8",
+    )
+
+    result = runner.invoke(
+        app,
+        ["agent-read", str(graph_root), "--query", "needle"],
+    )
+
+    assert result.exit_code == 0
+    # Plain text — no Rich markup
+    assert "\x1b[" not in result.output
+    # X-Ray alias format [0], [1]
+    assert "[0]" in result.output
+    assert "Needle in a haystack" in result.output
+    assert "Nested needle block" in result.output
+    # Non-matching blocks are excluded
+    assert "Irrelevant content" not in result.output
+    assert "Should not appear" not in result.output
+
+    # Alias state saved for agent-write chaining
+    state_path = graph_root / ".matryca_xray_state.json"
+    assert state_path.is_file()
+    restored = SessionAliasRegistry.load_from_disk(state_path)
+    assert restored.resolve_alias(0) is not None
+
+
+def test_agent_read_cli_query_no_matches_exits_cleanly(tmp_path: Path) -> None:
+    """``agent-read --query`` with no matches exits 0 and prints nothing."""
+    graph_root = tmp_path / "graph"
+    pages = graph_root / "pages"
+    pages.mkdir(parents=True)
+    (graph_root / "journals").mkdir()
+    (pages / "only.md").write_text("- Just some text\n", encoding="utf-8")
+
+    result = runner.invoke(
+        app,
+        ["agent-read", str(graph_root), "--query", "nonexistent"],
+    )
+
+    assert result.exit_code == 0

logseq_matryca_parser-1.4.1/tests/test_exceptions.py

@@ -0,0 +1,62 @@
+"""Dedicated tests for the parser exception hierarchy (issue #21).
+
+Verifies that all domain exceptions inherit from LogseqParserError and
+that each class can be instantiated with a message string.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from logseq_matryca_parser.exceptions import (
+    BlockReferenceError,
+    LogseqIndentationError,
+    LogseqParserError,
+)
+
+
+class TestExceptionHierarchy:
+    """Structural assertions on the exception class hierarchy."""
+
+    def test_block_reference_error_is_subclass_of_logseq_parser_error(self):
+        """BlockReferenceError must inherit from the base parser exception."""
+        assert issubclass(BlockReferenceError, LogseqParserError)
+
+    def test_logseq_indentation_error_is_subclass_of_logseq_parser_error(self):
+        """LogseqIndentationError must inherit from LogseqParserError.
+
+        Note: LogseqIndentationError is reserved for a future strict
+        indentation mode and is not raised by the parser today.
+        """
+        assert issubclass(LogseqIndentationError, LogseqParserError)
+
+    def test_base_exception_is_standard_exception(self):
+        """LogseqParserError itself inherits from built-in Exception."""
+        assert issubclass(LogseqParserError, Exception)
+
+
+class TestExceptionInstantiation:
+    """Behavioural assertions — can instantiate and use as exceptions."""
+
+    def test_block_reference_error_can_be_raised_and_caught(self):
+        with pytest.raises(BlockReferenceError, match="test error"):
+            raise BlockReferenceError("test error")
+
+    def test_block_reference_error_is_caught_by_base_class(self):
+        """Catching LogseqParserError also catches BlockReferenceError."""
+        with pytest.raises(LogseqParserError):
+            raise BlockReferenceError("caught by base")
+
+    def test_logseq_indentation_error_can_be_raised_and_caught(self):
+        """LogseqIndentationError accepts a message like other exceptions."""
+        with pytest.raises(LogseqIndentationError, match="indent"):
+            raise LogseqIndentationError("broken indent")
+
+    def test_logseq_indentation_error_is_caught_by_base_class(self):
+        """Catching LogseqParserError also catches LogseqIndentationError."""
+        with pytest.raises(LogseqParserError):
+            raise LogseqIndentationError("caught by base")
+
+    def test_base_exception_stores_message(self):
+        exc = LogseqParserError("base message")
+        assert str(exc) == "base message"