sqlprism 1.0.1__tar.gz → 1.2.0__tar.gz

sqlprism-1.2.0/.claude/skills/creating-branches-and-prs/PR-TEMPLATE.md

@@ -0,0 +1,24 @@
+# PR Body Template
+
+```markdown
+Closes #<issue_number>
+
+## Summary
+- <what changed and why — 1-3 bullet points>
+
+## Test Plan
+| Scenario | Test | Status |
+|----------|------|--------|
+| <from issue> | `test_function_name` | <pass/fail/pending> |
+| <from issue> | `test_function_name` | <pass/fail/pending> |
+
+## Notes
+<optional: anything reviewers should know — migration steps, breaking changes, etc.>
+```
+
+## Guidelines
+
+- **Summary** should explain *why*, not just *what* — the diff shows the what
+- **Test Plan** is copied from the issue's Test Plan section, with a Status column added
+- **Closes** keyword auto-closes the linked issue on merge
+- Keep the PR scoped to one issue — if it touches multiple issues, split into multiple PRs

sqlprism-1.2.0/.claude/skills/creating-branches-and-prs/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: creating-branches-and-prs
+description: Creates git branches and GitHub pull requests following the project naming convention. Enforces the format type-issue_number-short-description for both branches and PR titles. Use when creating a branch, opening a PR, or asking about branch/PR naming.
+---
+
+# Creating Branches and PRs
+
+## Naming Convention
+
+Both branches and PR titles use the same format:
+
+```
+<type>-<issue_number>-<short-description>
+```
+
+### Rules
+
+- **Lowercase, hyphens only** — no spaces, underscores, slashes, or camelCase
+- **Type prefix** — matches the issue label
+- **Issue number** — the GitHub issue this work addresses
+- **Short description** — 2-4 words summarizing the change
+
+### Types
+
+| Type | When | Maps to label |
+|------|------|---------------|
+| `feat` | New functionality | `enhancement` |
+| `fix` | Bug fix | `bug` |
+| `chore` | Maintenance, CI, deps, migrations | `chore` |
+
+### Examples
+
+| Issue | Branch / PR title |
+|-------|-------------------|
+| #8 Add repo_type column | `chore-8-repo-type-column` |
+| #9 dbt render_models | `feat-9-dbt-render-models` |
+| #11 Indexer reindex_files | `feat-11-indexer-reindex-files` |
+| #14 Tests for reindex | `feat-14-reindex-on-save-tests` |
+
+## Creating a Branch
+
+```bash
+git checkout main
+git pull origin main
+git checkout -b <type>-<issue_number>-<short-description>
+```
+
+## Creating a PR
+
+Link the PR to its issue using `Closes #<number>` in the body. This auto-closes the issue on merge.
+
+```bash
+gh pr create \
+  --title "<type>-<issue_number>-<short-description>" \
+  --body "$(cat <<'EOF'
+Closes #<issue_number>
+
+## Summary
+<1-3 bullet points>
+
+## Test plan
+<checklist from the issue's Test Plan section>
+EOF
+)"
+```
+
+## PR Body Structure
+
+See [PR-TEMPLATE.md](PR-TEMPLATE.md) for the full template.
+
+## Validation Checklist
+
+Before creating a branch or PR, verify:
+- [ ] Type matches the issue label (`enhancement` → `feat`, `bug` → `fix`, `chore` → `chore`)
+- [ ] Issue number exists and is open
+- [ ] Branch is based on latest `main`
+- [ ] PR body includes `Closes #<number>`

sqlprism-1.2.0/.claude/skills/implementing-issues/AGENT-INSTRUCTIONS.md

@@ -0,0 +1,68 @@
+# Sub-Agent Instructions
+
+When spawning a sub-agent for a task, provide these instructions along with the task-specific context.
+
+## Prompt Template
+
+```
+You are implementing task {task_id} for issue #{issue_number} in the SQLPrism project.
+
+Tech stack: Python 3.12, DuckDB, sqlglot, FastMCP, click, pytest, uv.
+
+## Your Task
+{task_title}
+
+## Files to Modify
+{files list}
+
+## Scenarios to Satisfy
+{scenarios from the task, copied from the issue's BDD scenarios}
+
+## Done When
+{done_when}
+
+## Instructions
+
+1. Read the existing code in the files listed above before making changes
+2. Implement the changes to satisfy the scenarios
+3. If this is a test task, ensure test names match the issue's Test Plan exactly
+4. Run lint and type check to verify:
+   ```bash
+   uv run ruff check .
+   uv run ty check
+   ```
+5. Run the relevant tests to verify:
+   ```bash
+   uv run pytest {test_file} -v -k "{test_pattern}"
+   ```
+6. If lint and tests pass, commit with:
+   ```bash
+   git add {files}
+   git commit -m "{commit_message}
+
+   Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>"
+   ```
+7. If lint or tests fail, fix the issue and try again (max 3 attempts)
+8. Return a summary: what changed, tests passed/failed, any concerns
+
+## Boundaries
+- Only modify files listed in your task
+- If you need to change other files, return with a note explaining why — do not modify them
+- Do not amend or rebase existing commits
+- Do not push to remote (the main agent handles this)
+```
+
+## What the Sub-Agent Returns
+
+Each sub-agent must return a structured result:
+
+```
+Task: {task_id}
+Status: completed | failed
+Files changed: {list}
+Tests: {passed_count} passed, {failed_count} failed
+Commit: {short sha} {commit message}
+Notes: {any concerns, blockers, or scope questions}
+```
+
+The main agent uses this to update `tasks.json` and decide next steps.

sqlprism-1.2.0/.claude/skills/implementing-issues/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: implementing-issues
+description: Implements a GitHub issue end-to-end. Reads the issue, creates a branch and PR, breaks work into tasks saved to plans/, executes tasks in parallel via sub-agents, and commits after each task. Use when the user says /implement, asks to work on an issue, or references an issue number to start implementing.
+---
+
+# Implementing Issues
+
+## Workflow
+
+Copy this checklist and track progress:
+
+```
+Implementation Progress:
+- [ ] Step 1: Read issue and understand scope
+- [ ] Step 2: Create branch and draft PR
+- [ ] Step 3: Break down into tasks
+- [ ] Step 4: Execute tasks (parallel where possible)
+- [ ] Step 5: Verify and finalize
+```
+
+## Step 1: Read Issue
+
+```bash
+gh issue view <number> --json title,body,labels,milestone
+```
+
+Extract from the issue body:
+- **Scenarios** — the acceptance criteria
+- **Test Plan** — test function names and files
+- **Dependencies** — blocked by / blocks
+
+If the issue is blocked by open issues, stop and inform the user.
+
+## Step 2: Create Branch and Draft PR
+
+Follow the branch/PR naming convention: `<type>-<issue_number>-<short-description>`
+
+Type mapping: `enhancement` → `feat`, `bug` → `fix`, `chore` → `chore`
+
+```bash
+git checkout main && git pull origin main
+git checkout -b <type>-<number>-<description>
+git push -u origin <type>-<number>-<description>
+```
+
+Create a **draft PR** immediately so progress is visible:
+
+```bash
+gh pr create --draft \
+  --title "<type>-<number>-<description>" \
+  --body "$(cat <<'EOF'
+Closes #<number>
+
+## Summary
+- <to be updated on completion>
+
+## Test Plan
+<copy Test Plan table from issue, add Status column set to pending>
+EOF
+)"
+```
+
+## Step 3: Break Down into Tasks
+
+Analyze the issue scenarios and create a task breakdown. Save to `.claude/plans/<issue_number>/tasks.json`.
+
+```bash
+mkdir -p .claude/plans/<issue_number>
+```
+
+See [TASK-FORMAT.md](TASK-FORMAT.md) for the JSON schema and decomposition rules.
+
+**Key rules:**
+- Each task maps to one or more scenarios from the issue
+- Tasks that touch different files/modules can run in parallel
+- Tests are a separate task per module, but run after implementation tasks
+- Every task has a clear "done when" that maps back to a scenario
+
+## Step 4: Execute Tasks
+
+Read `.claude/plans/<issue_number>/tasks.json` and identify which tasks can run in parallel (no shared files, no dependency between them).
+
+For each task, spawn a sub-agent with:
+- The task description and acceptance criteria from tasks.json
+- The relevant scenario(s) from the issue
+- The specific files to create/modify
+- Instructions to commit when done (see [AGENT-INSTRUCTIONS.md](AGENT-INSTRUCTIONS.md))
+
+**Parallel execution rules:**
+- Tasks in the same `parallel_group` run simultaneously
+- Tasks with `depends_on` wait for dependencies to complete
+- After each sub-agent finishes, update tasks.json status
+
+```bash
+# After each task completes, update the task status
+# The sub-agent commits its own changes
+```
+
+## Step 5: Verify and Finalize
+
+After all tasks complete:
+
+```bash
+# Run linter and type checker — must pass before PR is marked ready
+uv run ruff check .
+uv run ty check
+
+# Run full test suite
+uv run pytest tests/ -v
+
+# Update the draft PR to ready
+gh pr ready <pr_number>
+```
+
+If ruff, ty, or tests fail, fix the issues and commit before marking the PR ready.
+
+Update the PR body with final summary and test plan status.
+
+## Boundaries
+
+**Always:**
+- Create `.claude/plans/<issue_number>/tasks.json` before writing any code
+- Commit after each task (not one big commit at the end)
+- Run tests after implementation tasks before marking complete
+- Run `uv run ruff check .` and `uv run ty check` before marking PR ready — lint and type check must pass
+- Update tasks.json status as tasks complete
+
+**Ask first:**
+- If a task requires changing files not mentioned in the issue
+- If dependencies need updating
+- If the issue scope seems larger than expected
+
+**Never:**
+- Skip creating the task plan
+- Modify files outside the task's listed scope without flagging it
+- Force push or amend commits from other sub-agents
+- Mark the PR as ready without passing tests

sqlprism-1.2.0/.claude/skills/implementing-issues/TASK-FORMAT.md

@@ -0,0 +1,94 @@
+# Task Format
+
+## Schema: `.claude/plans/<issue_number>/tasks.json`
+
+```json
+{
+  "issue": 9,
+  "title": "Add render_models() with --select support to dbt renderer",
+  "branch": "feat-9-dbt-render-models",
+  "tasks": [
+    {
+      "id": "T1",
+      "title": "Add render_models() method to DbtRenderer",
+      "status": "pending",
+      "parallel_group": "A",
+      "depends_on": [],
+      "files": ["src/sqlprism/renderers/dbt.py"],
+      "scenarios": [
+        "Compile a single dbt model",
+        "Compile multiple dbt models in one call",
+        "Model compilation fails"
+      ],
+      "done_when": "render_models() compiles selected models via --select and returns parsed results",
+      "commit_message": "feat(dbt): add render_models with --select support"
+    },
+    {
+      "id": "T2",
+      "title": "Ensure render_project remains unchanged",
+      "status": "pending",
+      "parallel_group": "A",
+      "depends_on": [],
+      "files": ["src/sqlprism/renderers/dbt.py"],
+      "scenarios": ["render_project remains unchanged"],
+      "done_when": "Existing render_project tests still pass with no code changes to that method",
+      "commit_message": ""
+    },
+    {
+      "id": "T3",
+      "title": "Add tests for render_models",
+      "status": "pending",
+      "parallel_group": "B",
+      "depends_on": ["T1"],
+      "files": ["tests/test_renderers.py"],
+      "scenarios": [
+        "Compile a single dbt model",
+        "Compile multiple dbt models in one call",
+        "Model compilation fails",
+        "render_project remains unchanged"
+      ],
+      "done_when": "All 4 test functions from Test Plan pass",
+      "commit_message": "test(dbt): add tests for render_models"
+    }
+  ]
+}
+```
+
+## Decomposition Rules
+
+### Sizing
+- Each task should be completable by a single sub-agent in one pass
+- If a task touches more than 3 files, split it
+- If a task has more than 4 scenarios, consider splitting by happy path vs edge cases
+
+### Parallel Groups
+- Tasks in the same `parallel_group` letter (A, B, C...) can run simultaneously
+- Group A typically has no dependencies — these run first
+- Group B depends on group A, group C on B, etc.
+- Tasks sharing the same file **cannot** be in the same parallel group
+
+### Task Types
+| Type | Parallel? | Commit? |
+|------|-----------|---------|
+| Implementation (new code) | Yes, if different files | Yes |
+| Refactor (modify existing) | Usually sequential | Yes |
+| Tests | After implementation | Yes |
+| Verification (no-op check) | With anything | No commit needed |
+
+### Status Values
+- `pending` — not started
+- `in_progress` — sub-agent working on it
+- `completed` — committed and verified
+- `failed` — sub-agent encountered an error
+- `skipped` — not needed (explain in notes)
+
+### Commit Messages
+Follow conventional commits: `<type>(<scope>): <description>`
+
+| Type | When |
+|------|------|
+| `feat` | New functionality |
+| `fix` | Bug fix |
+| `test` | Adding/updating tests |
+| `chore` | Migration, config, maintenance |
+| `refactor` | Code change that doesn't add/fix |

sqlprism-1.2.0/.claude/skills/managing-project-releases/BDD-TEMPLATE.md

@@ -0,0 +1,107 @@
+# BDD Issue Template
+
+Every issue follows this structure. Scenarios double as acceptance criteria AND test case specifications.
+
+## Template
+
+```markdown
+## Description
+Brief context: what is being done and why.
+
+## Scenarios
+
+### Scenario: <descriptive name — the happy path>
+**Given** <precondition or initial state>
+**When** <action or event>
+**Then** <expected outcome>
+**And** <additional assertions if needed>
+
+### Scenario: <edge case or error path>
+**Given** <precondition>
+**When** <action>
+**Then** <expected behavior>
+
+### Scenario: <another edge case>
+...
+
+## Test Plan
+
+| Scenario | Test | File |
+|----------|------|------|
+| <scenario name> | `test_<descriptive_function_name>` | `tests/<test_file>.py` |
+| <scenario name> | `test_<descriptive_function_name>` | `tests/<test_file>.py` |
+
+## Dependencies
+- Blocked by: #<issue_number>, #<issue_number>
+- Blocks: #<issue_number>
+
+## Notes
+Implementation hints, links to plan sections, design decisions.
+```
+
+## Writing Good Scenarios
+
+### DO
+- Name scenarios descriptively: `Scenario: File outside any configured repo is skipped`
+- Keep each scenario focused on one behavior
+- Include both happy path and error/edge case scenarios
+- Use concrete values in examples: `"stg_orders.sql"` not `"a file"`
+- Write scenarios that translate directly to test functions
+
+### DON'T
+- Don't write vague scenarios: `Scenario: It works correctly`
+- Don't combine multiple behaviors in one scenario
+- Don't skip edge cases — they're where bugs hide
+- Don't write implementation details in Given/When/Then — describe behavior
+
+## Scenario Categories
+
+Each issue should cover these categories where applicable:
+
+1. **Happy path** — the normal, expected use case
+2. **Error handling** — what happens when things fail
+3. **Edge cases** — boundary conditions, empty inputs, concurrent access
+4. **Backwards compatibility** — existing behavior remains unchanged
+5. **Integration** — how this interacts with adjacent components
+
+## Example
+
+```markdown
+## Description
+Add checksum-based skip logic to avoid re-parsing unchanged files during reindex.
+
+## Scenarios
+
+### Scenario: Unchanged file is skipped
+**Given** a file `stg_orders.sql` already indexed with checksum `abc123`
+**When** `reindex_files()` is called and the file still has checksum `abc123`
+**Then** no parse or database write occurs
+**And** the file appears in the result as `skipped: unchanged`
+
+### Scenario: Changed file is reindexed
+**Given** a file `stg_orders.sql` indexed with checksum `abc123`
+**When** the file content changes (new checksum `def456`) and `reindex_files()` is called
+**Then** the file is re-parsed and the graph is updated
+**And** the stored checksum is updated to `def456`
+
+### Scenario: New file has no previous checksum
+**Given** a file `new_model.sql` that has never been indexed
+**When** `reindex_files()` is called
+**Then** the file is parsed and inserted
+**And** no checksum comparison is attempted
+
+## Test Plan
+
+| Scenario | Test | File |
+|----------|------|------|
+| Unchanged file is skipped | `test_reindex_unchanged_file_skipped` | `tests/test_indexer.py` |
+| Changed file is reindexed | `test_reindex_changed_file_updates_graph` | `tests/test_indexer.py` |
+| New file has no previous checksum | `test_reindex_new_file_no_checksum_check` | `tests/test_indexer.py` |
+
+## Dependencies
+- Blocked by: #8
+- Blocks: #12
+
+## Notes
+Checksum uses SHA-256 of file content. Stored in the `files` table.
+```

sqlprism-1.2.0/.claude/skills/managing-project-releases/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: managing-project-releases
+description: Decomposes features or releases into BDD-formatted GitHub issues with Given/When/Then scenarios and test cases. Creates milestones, assigns labels, and adds issues to the project board. Use when starting a new release, planning a feature, or creating issue tickets.
+---
+
+# Managing Project Releases
+
+## Context
+
+- **GitHub repo:** darkcofy/sqlprism
+- **GitHub Project:** SQLPrism (project number 1, owner darkcofy)
+- **Labels:** `enhancement`, `bug`, `chore` (no sizing labels)
+- **Branch convention:** `feat-<name>`, `fix-<name>`, `chore-<name>`
+
+## Workflow
+
+1. **Read the implementation plan** for the release from `.claude/plans/`
+2. **Create a milestone** named after the release version (e.g., `v1.0.1`)
+3. **Decompose into issues** — one per logical unit of work
+4. **Write each issue in BDD format** — see [BDD-TEMPLATE.md](BDD-TEMPLATE.md)
+5. **Add all issues** to the GitHub Project board
+6. **Update dependency references** with actual issue numbers after creation
+
+## Issue Decomposition Guidelines
+
+Break work into issues that are:
+- **Independent where possible** — parallelizable steps get separate issues
+- **Ordered by dependency** — identify what blocks what
+- **Testable** — every issue has BDD scenarios that become test cases
+- **Single responsibility** — one issue = one logical change
+
+Group by layer, not by file. Example layers:
+- Schema/migration changes
+- Renderer/parser changes
+- Core logic (indexer, engine)
+- API/tool surface (MCP tools, CLI commands)
+- Tests (can be a single issue or per-layer)
+
+## Creating Issues
+
+```bash
+gh issue create \
+  --milestone "<version>" \
+  --label "<type>" \
+  --title "<concise title>" \
+  --body "$(cat <<'EOF'
+<BDD body — see BDD-TEMPLATE.md>
+EOF
+)"
+```
+
+After creating all issues, add them to the project:
+
+```bash
+gh project item-add 1 --owner darkcofy --url "<issue_url>"
+```
+
+Then update dependency cross-references to use actual issue numbers.
+
+## Creating Milestones
+
+```bash
+gh api repos/darkcofy/sqlprism/milestones \
+  -f title="<version>" \
+  -f description="<one-line summary>" \
+  -f state="open"
+```
+
+## Label Selection
+
+| Label | When to use |
+|-------|------------|
+| `enhancement` | New features, new capabilities |
+| `bug` | Fixing broken behavior |
+| `chore` | Migrations, CI, deps, refactors |

sqlprism-1.2.0/.claude/skills/reviewing-prs/COMMENT-TEMPLATE.md

@@ -0,0 +1,78 @@
+# PR Comment Template
+
+The synthesized review posted to GitHub follows this format exactly.
+
+## Template
+
+```markdown
+## PR Review — #<number>
+
+### Critical
+| Reviewer | File:Line | Finding | Suggestion |
+|----------|-----------|---------|------------|
+| <SWE/DE/QA> | `path:line` | description | fix |
+
+### Warnings
+| Reviewer | File:Line | Finding | Suggestion |
+|----------|-----------|---------|------------|
+| <SWE/DE/QA> | `path:line` | description | fix |
+
+### Suggestions
+| Reviewer | File:Line | Finding | Suggestion |
+|----------|-----------|---------|------------|
+| <SWE/DE/QA> | `path:line` | description | fix |
+
+### Test Coverage
+- [ ] All scenarios from issue Test Plan have corresponding tests
+- [ ] Edge cases covered
+- [ ] No regression risk identified
+
+### Summary
+<2-3 sentence synthesis: overall assessment, key risks, recommendation>
+
+---
+*Reviewed by: SWE, Data Engineer, QA Engineer*
+*🤖 Generated with [Claude Code](https://claude.com/claude-code)*
+```
+
+## Rules
+
+- **Deduplicate**: if two reviewers flag the same issue, list it once and credit both
+- **Order by severity**: critical first, then warnings, then suggestions
+- **Omit empty sections**: if no criticals, remove the Critical table entirely
+- **Keep it scannable**: no prose paragraphs in the tables, save that for Summary
+- **Link to lines**: use `path:line` format so GitHub renders clickable links in the diff
+
+## Example
+
+```markdown
+## PR Review — #9
+
+### Critical
+| Reviewer | File:Line | Finding | Suggestion |
+|----------|-----------|---------|------------|
+| DE | `src/sqlprism/renderers/dbt.py:87` | `--select` flag placed before `compile` subcommand — dbt ignores it | Move `--select` after `compile`: `dbt compile --select model` |
+
+### Warnings
+| Reviewer | File:Line | Finding | Suggestion |
+|----------|-----------|---------|------------|
+| SWE | `src/sqlprism/renderers/dbt.py:92` | No timeout on subprocess call — could hang indefinitely | Add `timeout=300` to `subprocess.run()` |
+| QA | `tests/test_renderers.py` | No test for compilation timeout scenario | Add `test_dbt_render_models_timeout` |
+
+### Suggestions
+| Reviewer | File:Line | Finding | Suggestion |
+|----------|-----------|---------|------------|
+| SWE | `src/sqlprism/renderers/dbt.py:95` | Hardcoded `target/compiled/` path | Extract to constant `_DBT_COMPILED_DIR` |
+
+### Test Coverage
+- [x] All scenarios from issue #9 Test Plan have corresponding tests
+- [ ] Edge cases covered — missing: timeout, empty model list
+- [x] No regression risk identified
+
+### Summary
+The `--select` flag ordering is a blocking issue — dbt silently ignores it, so no models actually compile. The subprocess timeout is a real risk in CI. Otherwise solid implementation with good test coverage.
+
+---
+*Reviewed by: SWE, Data Engineer, QA Engineer*
+*🤖 Generated with [Claude Code](https://claude.com/claude-code)*
+```