logseq-matryca-parser 1.4.2__tar.gz → 1.7.0__tar.gz

{logseq_matryca_parser-1.4.2 → logseq_matryca_parser-1.7.0}/.cursorignore

@@ -1,5 +1,5 @@
 # .cursorignore
-# (Nota: Cursor ignora già automaticamente tutto ciò che è nel .gitignore)
+# Note: Cursor already ignores everything listed in .gitignore.
 
 # =========================
 # Python & Virtual Environments
@@ -27,10 +27,10 @@ build/
 *.egg-info/
 
 # =========================
-# Lockfiles (Letali per il Codebase Indexing)
+# Lockfiles (harmful to codebase indexing)
 # =========================
-# I lockfile devono stare su Git, ma l'IA non deve MAI leggerli,
-# sono solo un muro di versioni incomprensibili.
+# Lockfiles belong in Git, but the AI should never read them because they are
+# only a wall of dependency versions with no useful semantic context.
 poetry.lock
 uv.lock
 package-lock.json
@@ -38,36 +38,36 @@ yarn.lock
 pnpm-lock.yaml
 
 # =========================
-# Output AI e Report (Evitare loop di contesto)
+# AI Outputs and Reports (avoid context loops)
 # =========================
-# Se committi per sbaglio un output, non vogliamo che Cursor lo studi.
+# If an output is committed accidentally, keep it out of the code index.
 repomix-output.*
 output_langchain/
 mappa_cervello.html
 
 # =========================
-# Dati di Test e Fixtures Mock
+# Test Data and Mock Fixtures
 # =========================
-# Se hai dei file Markdown o JSON enormi che usi solo per testare il parser,
-# a Git servono, ma all'IA confondono solo le idee.
+# Large Markdown or JSON fixtures may belong in Git for parser tests, but they
+# should not consume indexing context.
 tests/fixtures/*.json
 tests/fixtures/*.edn
 tests/fixtures/*.md
 *.csv
 
 # =========================
-# Assets Vettoriali
+# Vector Assets
 # =========================
-# Le immagini PNG/JPG Cursor le ignora da solo, ma gli SVG sono file di testo!
-# Se l'IA legge un SVG, legge migliaia di coordinate matematiche inutili.
+# PNG and JPG files are ignored automatically, while SVG files are text and can
+# add thousands of irrelevant coordinate values to the index.
 *.svg
 
 # =========================
-# File di Configurazione Editor
+# Editor Configuration Files
 # =========================
 .vscode/
 .idea/
 .clinerules
 
-# Esclude lo storico delle metriche per preservare il contesto LLM
-metrics/history.json
+# Exclude historical metrics to preserve LLM context.
+metrics/history.json

logseq_matryca_parser-1.7.0/.github/ISSUE_TEMPLATE/clean_architecture.yml

@@ -0,0 +1,61 @@
+name: Clean Architecture slice
+description: Structural refactor or layer-boundary work (Uncle Bob contract)
+title: "refactor: "
+labels:
+  - architecture
+  - clean-code
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Use this template for SRP/OCP/ISP/DIP slices. SSOT: [CLEAN_CODE_ARCHITECTURE.md](https://github.com/MarcoPorcellato/logseq-matryca-parser/blob/main/docs/CLEAN_CODE_ARCHITECTURE.md)
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem
+      description: Operator- or maintainer-visible issue in one paragraph
+    validations:
+      required: true
+  - type: textarea
+    id: lens
+    attributes:
+      label: Clean Architecture lens
+      description: "Table: Ring | SOLID violation | dependency-rule note"
+      value: |
+        | Ring | SOLID | Dependency rule |
+        |------|-------|-----------------|
+        | | | |
+    validations:
+      required: true
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Reproduction
+      description: Minimal markdown fixture, Python probe, or import-graph note
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected vs actual
+      description: Precise strings, counts, or module boundaries
+    validations:
+      required: true
+  - type: textarea
+    id: fix
+    attributes:
+      label: Suggested fix
+      description: Stay inside the correct ring; no drive-by refactors
+    validations:
+      required: true
+  - type: textarea
+    id: dod
+    attributes:
+      label: Definition of Done
+      value: |
+        - [ ] `make all` passes (Ruff, Mypy, pytest ≥80% coverage)
+        - [ ] `make vendor-name-check` passes
+        - [ ] `CHANGELOG.md` updated if operator-visible
+        - [ ] `docs/quality/CLEAN_ARCH_BACKLOG.md` updated if DEBT item closed
+    validations:
+      required: true

{logseq_matryca_parser-1.4.2 → logseq_matryca_parser-1.7.0}/.github/ISSUE_TEMPLATE/config.yml

@@ -1,5 +1,8 @@
 blank_issues_enabled: false
 contact_links:
+  - name: Clean Architecture epic (v1.6)
+    url: https://github.com/MarcoPorcellato/logseq-matryca-parser/blob/main/docs/quality/GITHUB_CLEAN_ARCH_ROADMAP.md
+    about: Milestone, project board, and phase issues for Uncle Bob v1.6 work
   - name: Security vulnerability
     url: https://github.com/MarcoPorcellato/logseq-matryca-parser/security/policy
     about: Report a security issue privately — do not open a public issue

logseq_matryca_parser-1.7.0/.github/clean_arch_issue_numbers.txt

@@ -0,0 +1,7 @@
+milestone=2
+EPIC=78
+PHASE0=79
+PHASE1=80
+PHASE3A=81
+PHASE3B=82
+PHASE4=83

{logseq_matryca_parser-1.4.2 → logseq_matryca_parser-1.7.0}/.github/dependabot.yml

@@ -1,12 +1,12 @@
 version: 2
 updates:
-  # Mantiene aggiornate le dipendenze Python (legge il pyproject.toml)
+  # Keep Python dependencies current (reads pyproject.toml).
   - package-ecosystem: "pip"
     directory: "/"
     schedule:
       interval: "weekly"
 
-  # Mantiene aggiornate le GitHub Actions (legge il tuo .github/workflows/ci.yml)
+  # Keep GitHub Actions current (reads .github/workflows/ci.yml).
   - package-ecosystem: "github-actions"
     directory: "/"
     schedule:

{logseq_matryca_parser-1.4.2 → logseq_matryca_parser-1.7.0}/.github/labels.yml

@@ -36,3 +36,11 @@
 - name: forge
   color: bfd4f2
   description: FORGE exporters and visitors
+
+- name: clean-code
+  color: "0e8a16"
+  description: Clean Architecture / SOLID slice — Uncle Bob contract
+
+- name: architecture
+  color: "5319e7"
+  description: Layer boundaries, dependency rule, structural refactor

logseq_matryca_parser-1.7.0/.github/scripts/create_clean_arch_issues.sh

@@ -0,0 +1,277 @@
+#!/usr/bin/env bash
+# Bootstrap Clean Architecture v1.6 milestone, epic, and phase issues.
+# Run from repo root: bash .github/scripts/create_clean_arch_issues.sh
+set -euo pipefail
+ROOT="$(cd "$(dirname "$0")/../.." && pwd)"
+cd "$ROOT"
+
+REPO="${GITHUB_REPOSITORY:-MarcoPorcellato/logseq-matryca-parser}"
+MILESTONE_TITLE="v1.6 — Clean Architecture & Code Quality"
+OUT="$ROOT/.github/clean_arch_issue_numbers.txt"
+: > "$OUT"
+
+milestone_number() {
+  gh api "repos/${REPO}/milestones" --paginate \
+    --jq ".[] | select(.title==\"${MILESTONE_TITLE}\") | .number" | head -1
+}
+
+ensure_milestone() {
+  local num
+  num=$(milestone_number || true)
+  if [[ -n "${num}" ]]; then
+    echo "Milestone exists: #${num} (${MILESTONE_TITLE})"
+    echo "milestone=${num}" >> "$OUT"
+    return
+  fi
+  num=$(gh api "repos/${REPO}/milestones" -f title="${MILESTONE_TITLE}" \
+    -f description="Uncle Bob rings, layer CI, KINETIC/SYNAPSE SRP-OCP slices. SSOT: docs/CLEAN_CODE_ARCHITECTURE.md. Target: v1.6.0." \
+    --jq '.number')
+  echo "Created milestone #${num}: ${MILESTONE_TITLE}"
+  echo "milestone=${num}" >> "$OUT"
+}
+
+create_issue() {
+  local id="$1"
+  local title="$2"
+  local labels="$3"
+  local body_file="$4"
+  local url
+  url=$(gh issue create --title "$title" --label "$labels" --body-file "$body_file")
+  local num="${url##*/}"
+  local ms
+  ms=$(milestone_number)
+  if [[ -n "${ms}" ]]; then
+    gh api -X PATCH "repos/${REPO}/issues/${num}" -f milestone="${ms}" >/dev/null
+  fi
+  echo "$id=${num}" >> "$OUT"
+  echo "Created ${id} -> #${num}"
+}
+
+BODY_DIR=$(mktemp -d)
+trap 'rm -rf "$BODY_DIR"' EXIT
+
+ensure_milestone
+
+# Epic
+cat > "$BODY_DIR/epic.md" <<'EOF'
+## Goal
+
+Ship the v1.6 Clean Architecture contract: SSOT documentation, import-boundary CI, KINETIC export extraction, SYNAPSE embed OCP, graph ISP public API, and a KINETIC command slice.
+
+## Clean Architecture lens
+
+| Ring | Modules touched |
+|------|-----------------|
+| Entities | `logos_core` (unchanged in v1) |
+| Use cases | `graph`, `logos_parser` (no FSM refactor) |
+| Adapters | `synapse`, `forge`, `kinetic_export` |
+| Drivers | `kinetic`, `kinetic_commands` |
+
+## Phases (child issues)
+
+Update checkboxes when each phase merges:
+
+- [ ] Phase 0 — docs SSOT + layer CI + vendor-name-check
+- [ ] Phase 1 — `kinetic_export.py` (DEBT-005)
+- [ ] Phase 2 — SYNAPSE embed OCP (DEBT-006) — #70
+- [ ] Phase 3 — `iter_attached_nodes()` + `kinetic_commands.py`
+- [ ] Phase 4 — hardening + v1 closure
+
+## SSOT
+
+- [`docs/CLEAN_CODE_ARCHITECTURE.md`](https://github.com/MarcoPorcellato/logseq-matryca-parser/blob/main/docs/CLEAN_CODE_ARCHITECTURE.md)
+- [`docs/quality/CLEAN_ARCH_BACKLOG.md`](https://github.com/MarcoPorcellato/logseq-matryca-parser/blob/main/docs/quality/CLEAN_ARCH_BACKLOG.md)
+- [`docs/quality/GITHUB_CLEAN_ARCH_ROADMAP.md`](https://github.com/MarcoPorcellato/logseq-matryca-parser/blob/main/docs/quality/GITHUB_CLEAN_ARCH_ROADMAP.md)
+
+## Out of scope (v2 epic)
+
+- `logos_parser.py` split (1439 lines, CRITICAL hub — do not refactor in v1.6)
+- Hexagonal `domain/ports.py`
+- Vendor AST indexer in CI (Ghost Tooling policy)
+
+## Definition of Done
+
+- [ ] All phase issues closed
+- [ ] `make all` green on `main`
+- [ ] `CHANGELOG.md` ready for v1.6.0
+- [ ] Milestone closed after tag `v1.6.0`
+EOF
+create_issue "EPIC" "Epic: Clean Architecture v1.6 — documentation, layer CI, and SRP/OCP slices" "architecture,enhancement" "$BODY_DIR/epic.md"
+
+# Phase 0
+cat > "$BODY_DIR/phase0.md" <<'EOF'
+## Problem
+
+Contributors lack a single Uncle Bob SSOT, automated layer-boundary tests, and a vendor-free code-audit runbook. Two small DIP/SRP slices are already implemented locally but not tracked on `main`.
+
+## Clean Architecture lens
+
+| Ring | SOLID | Dependency rule |
+|------|-------|-----------------|
+| Drivers / use cases | SRP, DIP | Public graph API for watcher; remove dead kinetic helper |
+| CI (tests) | — | Inner rings must not import frameworks |
+
+## Deliverables
+
+- [ ] `docs/CLEAN_CODE_ARCHITECTURE.md` — rings, SOLID, module map
+- [ ] `tests/test_layer_boundary.py` — import-boundary gate
+- [ ] `scripts/check_vendor_free_docs.sh` + `make vendor-name-check`
+- [ ] `docs/internal/LOCAL_CODE_STUDY.md` — maintainer runbook (generic terminology)
+- [ ] Public `LogseqGraph.is_tracked_markdown_path()` (closes #68)
+- [ ] Remove dead `_parse_graph` from `kinetic.py` (closes #67)
+
+## Reproduction
+
+```bash
+uv run pytest tests/test_layer_boundary.py -q
+make vendor-name-check
+```
+
+## Expected vs actual
+
+- **Expected:** `make all` passes; zero vendor tool names in public docs.
+- **Actual (pre-merge):** slices exist only in working tree.
+
+## Definition of Done
+
+- [ ] `make all` passes
+- [ ] `CHANGELOG.md` updated under `[Unreleased]`
+- [ ] PR body: `Fixes #67`, `Fixes #68`, links epic
+EOF
+create_issue "PHASE0" "docs: Clean Architecture SSOT, layer CI, and code-audit runbook" "architecture,clean-code,documentation" "$BODY_DIR/phase0.md"
+
+# Phase 1
+cat > "$BODY_DIR/phase1.md" <<'EOF'
+## Problem
+
+`kinetic.py` mixes Typer wiring with five `_export_*` handlers (~700 lines). Export formats cannot be extended without editing the driver module (SRP / OCP violation).
+
+## Clean Architecture lens
+
+| Ring | SOLID | Dependency rule |
+|------|-------|-----------------|
+| Drivers | SRP, OCP | `kinetic.py` orchestrates; `kinetic_export.py` owns format handlers |
+| Adapters | — | Handlers may call `forge`, `synapse` via public APIs |
+
+## Suggested fix
+
+1. Create `src/logseq_matryca_parser/kinetic_export.py`
+2. Move `_export_json`, `_export_markdown`, `_export_obsidian`, `_export_langchain`, etc.
+3. Registry or dispatcher in `kinetic.export()` — no behavior change
+4. Extend `tests/test_layer_boundary.py` for the new module
+
+## Reproduction
+
+```bash
+uv run matryca-parse export --help
+make check
+```
+
+## Expected vs actual
+
+- **Expected:** identical CLI output and exit codes; `kinetic.py` shrinks materially.
+- **Actual:** all export logic inline in `kinetic.py`.
+
+## Definition of Done
+
+- [ ] `make all` passes
+- [ ] `tests/test_kinetic.py` unchanged behavior
+- [ ] `docs/quality/CLEAN_ARCH_BACKLOG.md` — DEBT-005 closed
+- [ ] `CHANGELOG.md` if operator-visible
+
+**Tracking:** DEBT-005
+EOF
+create_issue "PHASE1" "refactor(kinetic): extract export handlers to kinetic_export.py (SRP)" "architecture,clean-code,cli,enhancement" "$BODY_DIR/phase1.md"
+
+# Phase 3a — iter_attached_nodes
+cat > "$BODY_DIR/phase3a.md" <<'EOF'
+## Problem
+
+`LogseqGraph._iter_attached_nodes()` is private but is the correct ISP surface for consumers that must skip orphan ghost nodes. Callers risk using `graph.pages` or `_node_registry` directly.
+
+## Clean Architecture lens
+
+| Ring | SOLID | Dependency rule |
+|------|-------|-----------------|
+| Use cases | ISP | Public iterator; private implementation unchanged |
+| Adapters | DIP | `agent_read`, LENS, SYNAPSE should prefer public API |
+
+## Suggested fix
+
+- Add `LogseqGraph.iter_attached_nodes() -> Iterator[LogseqNode]` (public)
+- Delegate from existing private method
+- Deprecation comment on leaky patterns in docstring only
+
+## Reproduction
+
+```python
+from logseq_matryca_parser.graph import LogseqGraph
+g = LogseqGraph.load_directory("path/to/vault")
+list(g.iter_attached_nodes())
+```
+
+## Definition of Done
+
+- [ ] Public method documented in `CLEAN_CODE_ARCHITECTURE.md` module map
+- [ ] `make all` passes
+- [ ] No new `graph.pages` iteration in drivers without `iter_canonical_pages()`
+EOF
+create_issue "PHASE3A" "refactor(graph): public iter_attached_nodes() (ISP)" "architecture,clean-code,enhancement" "$BODY_DIR/phase3a.md"
+
+# Phase 3b — kinetic_commands
+cat > "$BODY_DIR/phase3b.md" <<'EOF'
+## Problem
+
+After Phase 1 export extraction, `kinetic.py` still hosts many Typer subcommands (scan, visualize, agent-write, demo). The driver module remains above the ~550-line SRP threshold.
+
+## Clean Architecture lens
+
+| Ring | SOLID | Dependency rule |
+|------|-------|-----------------|
+| Drivers | SRP | `kinetic.py` = app factory + shared helpers; `kinetic_commands.py` = command handlers |
+
+## Suggested fix
+
+- Extract command groups to `kinetic_commands.py`
+- `kinetic.py` registers commands via imports
+- Extend `tests/test_layer_boundary.py` if needed
+
+## Related
+
+- #61 — replace production `assert` in `agent_write` (include in same PR if still present)
+
+## Definition of Done
+
+- [ ] `make all` passes
+- [ ] `tests/test_kinetic.py` green
+- [ ] `kinetic.py` line count ≤ 550 post-extraction
+EOF
+create_issue "PHASE3B" "refactor(kinetic): extract subcommands to kinetic_commands.py (SRP)" "architecture,clean-code,cli,enhancement" "$BODY_DIR/phase3b.md"
+
+# Phase 4
+cat > "$BODY_DIR/phase4.md" <<'EOF'
+## Problem
+
+v1.6 documentation and backlog need final cross-links; epic checklist must close; README/COOKBOOK should point to the Uncle Bob SSOT.
+
+## Deliverables
+
+- [ ] README + COOKBOOK links to `docs/CLEAN_CODE_ARCHITECTURE.md`
+- [ ] `docs/quality/CLEAN_ARCH_BACKLOG.md` — v1 structural items marked complete
+- [ ] Close epic issue
+- [ ] `CHANGELOG.md` release notes draft for v1.6.0 (no autonomous tag)
+
+## Definition of Done
+
+- [ ] `make all` passes
+- [ ] Epic checklist complete
+- [ ] Milestone ready to close after release tag
+EOF
+create_issue "PHASE4" "chore: Clean Architecture v1 hardening + README/COOKBOOK links" "architecture,clean-code,documentation" "$BODY_DIR/phase4.md"
+
+echo ""
+echo "=== Issue numbers written to ${OUT} ==="
+cat "$OUT"
+echo ""
+echo "Next: assign milestone to existing #70, #71, #61 via gh issue edit"
+echo "Create GitHub Project: gh project create --title 'Logseq Parser — Clean Architecture v1.6' --owner MarcoPorcellato"

logseq_matryca_parser-1.7.0/.github/workflows/ci.yml

@@ -0,0 +1,83 @@
+name: Logos Protocol CI
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: [ "3.12", "3.13" ]
+
+    steps:
+    - name: Checkout Code
+      uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+      with:
+        python-version: ${{ matrix.python-version }}
+        enable-cache: true
+
+    - name: Sync dependencies
+      run: uv sync --all-extras
+
+    - name: Audit dependencies
+      run: |
+        uv export --no-dev --no-emit-workspace --no-hashes -o "${{ runner.temp }}/requirements-audit.txt"
+        uv run pip-audit -r "${{ runner.temp }}/requirements-audit.txt"
+
+    - name: Lint
+      run: make lint
+
+    - name: Type check
+      run: make check
+
+    - name: Test
+      run: make test
+
+    - name: Documentation check (non-mutating)
+      run: make docs-check
+
+    - name: Verify checkout unchanged
+      run: make verify-clean
+
+  package-contract:
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout Code
+      uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+      with:
+        python-version: "3.12"
+        enable-cache: true
+
+    - name: Build wheel and source distribution
+      run: uv build --out-dir dist-contract
+
+    - name: Verify wheel metadata and PEP 561 marker
+      run: uv run python scripts/check_wheel_contract.py dist-contract/*.whl
+
+    - name: Verify distribution metadata
+      run: uvx --from twine==6.2.0 twine check dist-contract/*
+
+    - name: Verify downstream typing from the wheel
+      run: |
+        uv venv "${{ runner.temp }}/typing-venv"
+        uv pip install --python "${{ runner.temp }}/typing-venv/bin/python" mypy dist-contract/*.whl
+        cd "${{ runner.temp }}"
+        "${{ runner.temp }}/typing-venv/bin/python" -m mypy --strict "${{ github.workspace }}/tests/typing_samples/public_api.py"

{logseq_matryca_parser-1.4.2 → logseq_matryca_parser-1.7.0}/.github/workflows/daily-metrics.yml

@@ -2,8 +2,8 @@ name: Daily Metrics Saver
 
 on:
   schedule:
-    - cron: '0 3 * * *' # Gira ogni giorno alle 03:00 UTC
-  workflow_dispatch: # Permette l'avvio manuale con un click
+    - cron: '0 3 * * *' # Runs daily at 03:00 UTC.
+  workflow_dispatch: # Allows one-click manual runs.
 
 concurrency:
   group: daily-metrics-${{ github.repository }}
@@ -13,7 +13,7 @@ permissions:
   contents: write
 
 env:
-  # Forza l'ambiente di esecuzione su Node.js 24 per prevenire i warning di deprecazione di giugno 2026
+  # Force the Node.js 24 runtime to prevent the June 2026 deprecation warnings.
   FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
 
 jobs:
@@ -21,12 +21,12 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout Repository
-        uses: actions/checkout@v7
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           fetch-depth: 0
 
       - name: Set up Python
-        uses: actions/setup-python@v6
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
         with:
           python-version: '3.12'