logseq-matryca-parser 0.3.0__tar.gz

logseq_matryca_parser-0.3.0/.cursorignore

@@ -0,0 +1,45 @@
+# .cursorignore
+# (Nota: Cursor ignora già automaticamente tutto ciò che è nel .gitignore)
+
+# =========================
+# Lockfiles (Letali per il Codebase Indexing)
+# =========================
+# I lockfile devono stare su Git, ma l'IA non deve MAI leggerli, 
+# sono solo un muro di versioni incomprensibili.
+poetry.lock
+uv.lock
+package-lock.json
+yarn.lock
+pnpm-lock.yaml
+
+# =========================
+# Output AI e Report (Evitare loop di contesto)
+# =========================
+# Se committi per sbaglio un output, non vogliamo che Cursor lo studi.
+repomix-output.*
+output_langchain/
+mappa_cervello.html
+
+# =========================
+# Dati di Test e Fixtures Mock
+# =========================
+# 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.
+tests/fixtures/*.json
+tests/fixtures/*.edn
+tests/fixtures/*.md
+*.csv
+
+# =========================
+# Assets Vettoriali
+# =========================
+# 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.
+*.svg
+
+# =========================
+# File di Configurazione Editor
+# =========================
+.vscode/
+.idea/
+.clinerules

logseq_matryca_parser-0.3.0/.cursorrules

@@ -0,0 +1,5 @@
+# General Engineering Rules
+- Always use absolute imports from `logseq_matryca_parser`.
+- Every new function must have a Python type hint.
+- Use `logger.debug` for tracing the Stack-Machine state.
+- Before considering a task finished, run `make lint` via terminal.

logseq_matryca_parser-0.3.0/.github/FUNDING.yml

@@ -0,0 +1 @@
+github: [MarcoPorcellato]

logseq_matryca_parser-0.3.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,43 @@
+name: 🐛 Bug Report
+description: Create a report to help us fix parsing errors or visualizer bugs.
+title: "[BUG] "
+labels: ["bug", "triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to report a bug in the Logseq Matryca Parser! 
+        Please fill out this form as completely as possible to help us reproduce and fix the issue.
+  - type: textarea
+    id: description
+    attributes:
+      label: Bug Description
+      description: A clear and concise description of what the bug is.
+      placeholder: When I parse a page with this specific property, the AST breaks...
+    validations:
+      required: true
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Steps to Reproduce
+      description: How can we trigger this bug? Please include a minimal snippet of Logseq Markdown if possible.
+      placeholder: |
+        1. Run `matryca-parse visualize /my-graph`
+        2. Wait for the parsing phase
+        3. See error...
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected Behavior
+      description: What did you expect to happen?
+    validations:
+      required: true
+  - type: input
+    id: version
+    attributes:
+      label: Environment & Version
+      description: What version of Matryca Parser and Python are you using? (e.g., Parser v0.1.0, Python 3.12, Windows 11)
+    validations:
+      required: true

logseq_matryca_parser-0.3.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,30 @@
+name: 💡 Feature Request
+description: Suggest an idea, a new exporter, or an AI feature for the Logos Protocol.
+title: "[FEATURE] "
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Have an idea to make the Logseq Matryca Parser even better? We'd love to hear it!
+  - type: textarea
+    id: problem
+    attributes:
+      label: Is your feature request related to a problem?
+      description: A clear and concise description of what the problem is.
+      placeholder: "I'm always frustrated when..."
+    validations:
+      required: true
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed Solution
+      description: Describe the solution or new feature you'd like to see.
+      placeholder: "It would be great if the parser could export to..."
+    validations:
+      required: true
+  - type: textarea
+    id: context
+    attributes:
+      label: Additional Context
+      description: Add any other context, links to AI frameworks, or screenshots about the feature request here.

logseq_matryca_parser-0.3.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,17 @@
+## Description
+Fixes # (issue_number)
+
+## Type of change
+- [ ] 🐛 Bug fix (non-breaking change which fixes an issue)
+- [ ] ✨ New feature (non-breaking change which adds functionality)
+- [ ] 💥 Breaking change (fix or feature that would cause existing functionality to not work as expected)
+- [ ] 📚 Documentation update
+
+## 🛡️ Sovereign Developer Checklist
+- [ ] I have read the `CONTRIBUTING.md` guidelines.
+- [ ] I have executed `make all` locally, and all linters (Ruff), type-checkers (Mypy), and tests (Pytest) pass successfully.
+- [ ] I have added/updated tests for my changes (if applicable).
+- [ ] I have updated the documentation accordingly.
+- [ ] My code follows the strict typing rules (`strict=True`) of this project.
+
+## Screenshots / CLI Output (if applicable)

logseq_matryca_parser-0.3.0/.github/dependabot.yml

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

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

@@ -0,0 +1,42 @@
+name: Logos Protocol CI
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout Code
+      uses: actions/checkout@v6
+
+    - name: Set up Python 3.12
+      uses: actions/setup-python@v6
+      with:
+        python-version: "3.12"
+        cache: 'pip'
+
+    - name: Install Dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install -e ".[all]"
+        pip install pytest pytest-cov ruff mypy
+
+    - name: Lint with Ruff
+      run: |
+        ruff check .
+
+    - name: Type Checking with Mypy
+      run: |
+        mypy src/ tests/ examples/
+
+    - name: Run Pytest
+      run: |
+        pytest -v

logseq_matryca_parser-0.3.0/.github/workflows/pypi_publish.yml

@@ -0,0 +1,36 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/logseq-matryca-parser
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Install build
+        run: |
+          python -m pip install --upgrade pip
+          pip install build
+
+      - name: Build sdist and wheel
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

logseq_matryca_parser-0.3.0/.gitignore

@@ -0,0 +1,75 @@
+# =========================
+# OS / System
+# =========================
+**/.DS_Store
+**/.AppleDouble
+**/.LSOverride
+Thumbs.db
+desktop.ini
+
+# =========================
+# Python / Bytecode
+# =========================
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+
+# =========================
+# Virtual Environments & Secrets
+# =========================
+.venv/
+venv/
+env/
+.env
+.env.*
+!.env.example
+
+# =========================
+# Build & Distribution
+# =========================
+dist/
+build/
+*.egg-info/
+*.egg
+MANIFEST
+
+# =========================
+# Testing & Coverage
+# =========================
+.pytest_cache/
+.coverage
+coverage.xml
+htmlcov/
+tests/fixtures/*.json
+repomix-output.*
+
+# =========================
+# Logs & Databases (Security/Privacy)
+# =========================
+*.log
+*.sqlite
+*.sqlite3
+*.db
+
+# =========================
+# Notebooks & Data
+# =========================
+.ipynb_checkpoints/
+output_langchain/
+mappa_cervello.html
+docs/index.html
+out/graph.json
+out/graph.md
+
+# =========================
+# IDEs & Tool Caches
+# =========================
+.mypy_cache/
+.ruff_cache/
+.vscode/
+.idea/
+.rooignore
+.clinerules
+.cursor/rules/
+.cursor/

logseq_matryca_parser-0.3.0/.pre-commit-config.yaml

@@ -0,0 +1,10 @@
+repos:
+-   repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.3.5
+    hooks:
+    -   id: ruff
+        args: [ --fix ]
+-   repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.9.0
+    hooks:
+    -   id: mypy

logseq_matryca_parser-0.3.0/.repomixignore

@@ -0,0 +1,63 @@
+# .repomixignore
+
+# =========================
+# Repomix Outputs & AI Generated
+# =========================
+repomix-output.*
+output_langchain/
+mappa_cervello.html
+
+# =========================
+# Documentation (Token Optimization)
+# =========================
+docs/
+*.md
+!README.md
+!CHANGELOG.md
+!ARCHITECTURE.md
+
+# =========================
+# Third-Party Libraries & Frontend Assets (Massive Token Killers)
+# =========================
+lib/
+*.js
+*.css
+*.min.js
+
+# =========================
+# Legacy & Deprecated Code
+# =========================
+legacy/
+
+# =========================
+# Locks & Dependencies
+# =========================
+poetry.lock
+uv.lock
+package-lock.json
+yarn.lock
+pnpm-lock.yaml
+
+# =========================
+# OS / System / Python Caches
+# =========================
+**/.DS_Store
+Thumbs.db
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.venv/
+venv/
+
+# =========================
+# Token Killers (Logs, DBs, Vector Graphics)
+# =========================
+*.log
+*.sqlite
+*.sqlite3
+*.db
+*.csv
+*.svg
+tests/fixtures/*.json

logseq_matryca_parser-0.3.0/CONTRIBUTING.md

@@ -0,0 +1,122 @@
+# 🔱 Contributing to the Logos Protocol
+
+First off, thank you for considering contributing to the **Logseq Matryca Parser (Logos Protocol)**!
+
+This repository is the foundational AST engine for [Matryca.ai](https://matryca.ai), designed to preserve the spatial hierarchy of thought in Logseq graphs. We value deterministic logic, strict typing, and high performance.
+
+To maintain the architectural integrity of the project, please follow the guidelines below.
+
+---
+
+## 🏛️ Architectural Philosophy
+
+Before writing any code, please understand our core principles:
+
+1. **The Graph is Sacred:** Logos does not guess or chunk text arbitrarily. It reconstructs the exact hierarchical tree based on spatial indentation.
+2. **Deterministic Output:** Given the same `.md` file, the parser must *always* produce the exact same AST and identical UUIDs.
+3. **No Bloat:** We strictly limit external dependencies to maximize compatibility with AOT compilers (like Nuitka) and ensure blazing-fast execution.
+
+> **Note:** The `logos_core.py` module is the beating heart of the protocol. If your PR proposes changes to the Pydantic V2 models within it, please open an **Issue** for discussion first.
+
+---
+
+## 🛠️ Development Setup
+
+To set up your local environment:
+
+1. **Fork and Clone:**
+   ```bash
+   git clone https://github.com/YOUR-USERNAME/logseq-matryca-parser.git
+   cd logseq-matryca-parser
+   ```
+
+2. **Create an Isolated Environment:**
+   ```bash
+   python3 -m venv .venv
+   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+   ```
+
+3. **Install the Project in Editable Mode:**
+   *(Includes development dependencies)*
+   ```bash
+   pip install -e .
+   pip install pytest mypy ruff
+   ```
+
+---
+
+## 🚦 The Contribution Workflow
+
+### 1. Find or Create an Issue
+
+Whether it's a bug fix or a new feature (like a new exporter in `forge.py`), check the **Issues** tab first. If it's a new idea, open an Issue to discuss it with the maintainers before investing hours of work.
+
+### 2. Branch Naming Convention
+
+Create a branch from `main` using the following naming format:
+
+- `feat/your-feature-name` (for new features)
+- `bugfix/issue-number-description` (for bug fixes)
+- `docs/update-readme` (for documentation)
+
+**Example:**
+```bash
+git checkout -b feat/add-html-exporter
+```
+
+### 3. Write Code & Tests
+
+- If you fix a bug, write a unit test in `tests/` that fails without your patch and passes with it.
+- If you add a feature, ensure it is covered by a comprehensive test.
+
+### 4. Code Quality & Linting (Mandatory)
+
+We run a strict CI pipeline. Before committing, you must ensure your code passes static analysis and tests.
+
+We provide a `Makefile` to simplify running these commands. You can execute them individually or all at once:
+
+```bash
+# Run all checks (linting, static typing, and tests)
+make all
+
+# Or run them individually:
+make lint   # Check formatting and linting with Ruff
+make check  # Check static typing with Mypy
+make test   # Run unit tests with Pytest
+```
+
+Alternatively, you can run the commands directly:
+
+```bash
+# Check formatting and linting
+ruff check .
+
+# Check static typing
+mypy src/ tests/ examples/
+
+# Run tests
+pytest
+```
+
+### 5. Commit Standards
+
+We follow [Conventional Commits](https://www.conventionalcommits.org/). Your commit messages should be structured like this:
+
+- `feat(forge): add XML export functionality`
+- `fix(parser): resolve stack overflow on deep indentation`
+- `docs: update setup instructions`
+
+### 6. Submit a Pull Request (PR)
+
+- Push your branch and open a PR against the `main` branch.
+- Describe why the change is needed.
+- Link the relevant Issue (e.g., `Fixes #123`).
+- Ensure all GitHub Actions (CI) checks pass.
+
+---
+
+## 🤝 Code of Conduct
+
+We expect all contributors to maintain a professional, respectful, and constructive tone. We are building the future of sovereign knowledge management together.
+
+> *By contributing to this project, you agree that your contributions will be licensed under its Apache 2.0 License.*