cartographing-kittens 0.1.0__tar.gz

cartographing_kittens-0.1.0/.claude-plugin/marketplace.json

@@ -0,0 +1,33 @@
+{
+  "name": "cartographing-kitties",
+  "owner": {
+    "name": "Kakise",
+    "url": "https://a-smol-cat.fr"
+  },
+  "metadata": {
+    "description": "Plugin marketplace for Claude Code and Codex extensions",
+    "version": "1.0.0"
+  },
+  "plugins": [
+    {
+      "name": "cartograph",
+      "description": "AST-powered codebase intelligence for AI coding agents — dependency mapping, impact analysis, and semantic search via tree-sitter parsing and SQLite graph storage.",
+      "author": {
+        "name": "Kakise",
+        "url": "https://a-smol-cat.fr",
+        "email": "cartographing-kittens@a-smol-cat.fr"
+      },
+      "homepage": "https://github.com/Kakise/cartographing-kitties-plugin",
+      "tags": [
+        "ai-powered",
+        "codebase-intelligence",
+        "dependency-mapping",
+        "impact-analysis",
+        "semantic-search",
+        "tree-sitter",
+        "sqlite-graph-storage"
+      ],
+      "source": "./plugins/cartograph"
+    }
+  ]
+}

cartographing_kittens-0.1.0/.copier-answers.yml

@@ -0,0 +1,9 @@
+# Changes here will be overwritten by Copier. Do not edit manually.
+_commit: v0.2.25
+_src_path: gh:jlevy/simple-modern-uv
+package_author_email: cartographing-kittens@a-smol-cat.fr
+package_author_name: Kakise
+package_description: AST-powered codebase intelligence framework for AI coding agents
+package_github_org: Kakise
+package_module: cartograph
+package_name: cartographing-kittens

cartographing_kittens-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,96 @@
+name: CI
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+    branches: ["main"]
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          version: "0.10.2"
+          enable-cache: true
+          python-version: "3.13"
+
+      - name: Set up Python
+        run: uv python install
+
+      - name: Install all dependencies
+        run: uv sync --all-extras
+
+      - name: Run pre-commit
+        uses: pre-commit/action@v3.0.1
+
+  test:
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
+
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          version: "0.10.2"
+          enable-cache: true
+          python-version: ${{ matrix.python-version }}
+
+      - name: Set up Python
+        run: uv python install
+
+      - name: Install all dependencies
+        run: uv sync --all-extras
+
+      - name: Run tests
+        run: uv run pytest
+
+  validate-plugin:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Validate plugin.json
+        run: python -c "import json, sys; d=json.load(open('plugins/cartograph/.claude-plugin/plugin.json')); assert 'name' in d; assert 'mcpServers' in d; print('plugin.json valid')"
+
+      - name: Validate marketplace.json
+        run: python -c "import json, sys; d=json.load(open('.claude-plugin/marketplace.json')); assert 'name' in d; assert 'plugins' in d; print('marketplace.json valid')"
+
+      - name: Validate skill files exist
+        run: |
+          count=$(find plugins/cartograph/skills -mindepth 1 -maxdepth 1 -type d -exec test -f {}/SKILL.md \; -print | wc -l | tr -d ' ')
+          echo "Found $count skills"
+          if [ "$count" -lt 9 ]; then
+            echo "ERROR: Expected at least 9 skills, found $count"
+            find plugins/cartograph/skills -mindepth 1 -maxdepth 1 -type d | sort
+            exit 1
+          fi
+          echo "All skill files present"
+
+      - name: Validate agent files exist
+        run: |
+          count=$(find plugins/cartograph/agents -name '*.md' -type f | wc -l | tr -d ' ')
+          echo "Found $count agents"
+          if [ "$count" -lt 9 ]; then
+            echo "ERROR: Expected at least 9 agents, found $count"
+            find plugins/cartograph/agents -name '*.md' -type f | sort
+            exit 1
+          fi
+          echo "All agent files present"

cartographing_kittens-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,43 @@
+name: Publish
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  build-and-publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+      contents: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          version: "0.10.2"
+          enable-cache: true
+          python-version: "3.12"
+
+      - name: Set up Python
+        run: uv python install
+
+      - name: Install all dependencies
+        run: uv sync --all-extras
+
+      - name: Run tests
+        run: uv run pytest
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to PyPI
+        run: uv publish --trusted-publishing always
+
+      - name: Validate plugin structure
+        run: python -c "import json; d=json.load(open('plugins/cartograph/.claude-plugin/plugin.json')); assert 'name' in d; assert 'mcpServers' in d; print('Plugin structure valid')"

cartographing_kittens-0.1.0/.gitignore

@@ -0,0 +1,35 @@
+# Cartograph database files
+.cartograph/
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+*.egg
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# uv
+.uv/

cartographing_kittens-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,23 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.1
+    hooks:
+      - id: ruff
+        args: [--fix]
+        exclude: ^tests/
+      - id: ruff-format
+        exclude: ^tests/
+
+  - repo: https://github.com/codespell-project/codespell
+    rev: v2.4.1
+    hooks:
+      - id: codespell
+        additional_dependencies: [tomli]
+        args: [src]
+
+  - repo: https://github.com/DetachHead/basedpyright-pre-commit-mirror
+    rev: 1.38.0
+    hooks:
+      - id: basedpyright
+        args: [--level, error]
+        exclude: ^tests/

cartographing_kittens-0.1.0/.python-version

@@ -0,0 +1 @@
+3.11

cartographing_kittens-0.1.0/CLAUDE.md

@@ -0,0 +1,158 @@
+# Cartograph
+
+AST-powered codebase intelligence framework for AI coding agents.
+
+## Architecture
+
+| Layer | Location | Purpose |
+|-------|----------|---------|
+| Parsing | `src/cartograph/parsing/` | Tree-sitter AST extraction for Python, TypeScript, JavaScript |
+| Indexing | `src/cartograph/indexing/` | File discovery, incremental change detection, cross-file resolution |
+| Storage | `src/cartograph/storage/` | SQLite graph database with FTS5 search and recursive CTE traversal |
+| Annotation | `src/cartograph/annotation/` | LLM-driven semantic enrichment (summaries, tags, roles) |
+| MCP Server | `src/cartograph/server/` | FastMCP server — 9 tools, 3 prompts |
+| Server Tools | `src/cartograph/server/tools/` | Tool implementations (index, query, analysis, annotate) |
+| Server Prompts | `src/cartograph/server/prompts/` | Prompt implementations (explore, refactor, annotate) |
+
+## Conventions
+
+- Qualified names use `::` separator: `module.path::ClassName::method_name`
+- Edge kinds: `imports`, `calls`, `inherits`, `contains`, `depends_on`
+- Node kinds: `module`, `class`, `function`, `method`, `variable`
+- Graph stored at `.cartograph/graph.db` in project root
+- Indexing is incremental by default — only changed files are re-parsed
+
+## Plugin Structure (Marketplace Layout)
+
+```
+plugins/
+  cartograph/                    # Plugin root (marketplace layout)
+    .claude-plugin/plugin.json   # Plugin manifest (uvx-based MCP server)
+    skills/
+      cartograph/                # Router skill — delegates to sub-skills
+        SKILL.md
+        references/
+          tool-reference.md      # Detailed tool parameter docs
+          annotation-workflow.md # Annotation workflow guide
+      cartograph-explore/        # Structural exploration
+      cartograph-impact/         # Impact analysis and refactoring
+      cartograph-annotate/       # Annotation workflow
+      cartograph-brainstorm/     # Requirements gathering with research swarms
+      cartograph-plan/           # Technical planning with 4 research agents
+      cartograph-work/           # Execution with Cartograph-first workers
+      cartograph-review/         # Multi-agent review with structural analysis
+      cartograph-lfg/            # Full autonomous pipeline (plan → work → review)
+    agents/
+      cartograph-annotator.md    # Batch annotation specialist
+      cartograph-researcher.md   # General codebase researcher
+      cartograph-pattern-analyst.md # Pattern and convention finder
+      cartograph-impact-analyst.md  # Blast radius analyzer
+      cartograph-flow-analyzer.md   # Call chain and data flow tracer
+      cartograph-correctness-reviewer.md # Logic errors, edge cases (always-on)
+      cartograph-testing-reviewer.md     # Test coverage gaps (always-on)
+      cartograph-impact-reviewer.md      # Blast radius review (conditional)
+      cartograph-structure-reviewer.md   # Architecture review (conditional)
+src/cartograph/                  # Python source (MCP server + core library)
+tests/                           # Test suite
+```
+
+## Workflow Pipeline
+
+```
+cartograph:brainstorm → cartograph:plan → cartograph:work → cartograph:review
+```
+
+Or use `cartograph:lfg` for full autonomous execution (plan → work → review).
+
+### When to use each skill
+
+| Situation | Skill |
+|-----------|-------|
+| Exploring code structure | `cartograph:explore` |
+| Understanding change impact | `cartograph:impact` |
+| Enabling semantic search | `cartograph:annotate` |
+| Gathering requirements for a feature | `cartograph:brainstorm` |
+| Planning implementation | `cartograph:plan` |
+| Building features | `cartograph:work` |
+| Reviewing code changes | `cartograph:review` |
+| Full autonomous pipeline | `cartograph:lfg` |
+
+### How skills dispatch agents
+
+**cartograph:brainstorm** dispatches in parallel:
+- `cartograph-researcher` (architecture, stack)
+- `cartograph-pattern-analyst` (existing patterns)
+
+**cartograph:plan** dispatches in parallel:
+- `cartograph-researcher` (architecture)
+- `cartograph-pattern-analyst` (patterns)
+- `cartograph-flow-analyzer` (call chains)
+- `cartograph-impact-analyst` (blast radius)
+
+**cartograph:work** dispatches workers per implementation unit:
+- Each worker calls `get_file_structure` + `query_node` before implementing
+- Independent units run as parallel swarm
+
+**cartograph:review** dispatches in parallel:
+- `cartograph-correctness-reviewer` (always)
+- `cartograph-testing-reviewer` (always)
+- `cartograph-impact-reviewer` (when 3+ files changed)
+- `cartograph-structure-reviewer` (when new files created)
+
+## Agent Output Contracts
+
+Research agents return structured text summaries with:
+- Technology & stack, architecture, patterns, key files, dependencies, conventions
+
+Review agents return JSON:
+```json
+{
+  "reviewer": "agent-name",
+  "findings": [{
+    "severity": "P0|P1|P2|P3",
+    "category": "...",
+    "location": "file:line",
+    "issue": "description",
+    "guidance": "how to fix",
+    "confidence": 0.85,
+    "autofix_class": "safe_auto|gated_auto|manual|advisory"
+  }],
+  "summary": "overall assessment"
+}
+```
+
+## Cartograph-First Principle
+
+All agents and skills use Cartograph MCP tools as primary codebase intelligence:
+
+| Need | Tool | NOT |
+|------|------|----|
+| Understand a file's structure | `get_file_structure` | Reading entire file |
+| Find what depends on X | `find_dependents` | Grep for import statements |
+| Understand a symbol | `query_node` | Grep for the name |
+| Find code by domain | `search` (after annotation) | Grep for keywords |
+| Assess change impact | `find_dependents` + `find_dependencies` | Manual file reading |
+
+Fall back to grep/glob only for text-literal searches (error messages, string constants, TODOs).
+
+## Development
+
+```bash
+uv sync --all-extras          # Install dependencies
+uv run pytest                 # Run tests
+uv run ruff check src/        # Lint
+uv run ruff format --check src/  # Format check
+uv run basedpyright --level error  # Type check
+uv run codespell src          # Spell check
+```
+
+## MCP Server (local dev)
+
+```bash
+uv run python -m cartograph.server.main   # Start server via stdio
+```
+
+## Testing
+
+Tests live in `tests/`. Fixtures in `tests/fixtures/` are sample projects — not test modules.
+Run with `uv run pytest`. CI matrix tests Python 3.11-3.14.

cartographing_kittens-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kakise
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.