aselimov/notex.nvim
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Initial vibecoded proof of concept

Browse source
This commit is contained in:
Alex Selimov 2025-10-05 20:16:33 -04:00
parent 74812459af
commit 461318a656
Signed by: aselimov
GPG key ID: 3DDB9C3E023F1F31
61 changed files with 13306 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

172
specs/002-notex-is-a/contracts/query-api.md Normal file
View file

@ -0,0 +1,172 @@
# Query API Contract
## Query Syntax
### Basic Query Structure
```
```notex-query
FROM <property_filters>
[WHERE <conditions>]
[ORDER BY <property> [ASC|DESC]]
[GROUP BY <property>]
[LIMIT <number>]
```
```
### Property Filters
```yaml
# Filter by property existence
status: # Returns documents with 'status' property
# Filter by property value
status: "draft" # Returns documents where status = "draft"
# Multiple property filters
status: "draft"
priority: "high"
tags: ["research", "urgent"]
```
### Conditions
```yaml
# Comparison operators
WHERE priority > 5
WHERE created_at >= "2024-01-01"
WHERE status != "archived"
# Logical operators
WHERE status = "active" AND priority > 3
WHERE status = "urgent" OR priority > 5
WHERE NOT status = "archived"
# String matching
WHERE title CONTAINS "important"
WHERE tags STARTS_WITH "project"
WHERE author ENDS_WITH "@company.com"
# Array operations
WHERE tags INCLUDES "urgent"
WHERE tags SIZE > 3
# Date operations
WHERE created_at BEFORE "2024-06-01"
WHERE updated_at AFTER "2024-01-01"
WHERE due_date WITHIN 7d
```
## Query Execution API
### Parse Query
**Input**: Raw query string
**Output**: Parsed query object
```lua
{
filters = {
status = "draft",
priority = "high"
},
conditions = {
type = "AND",
clauses = {
{ type = "comparison", field = "priority", operator = ">", value = 3 }
}
},
order_by = { field = "created_at", direction = "DESC" },
group_by = "status",
limit = 50
}
```
### Execute Query
**Input**: Parsed query object
**Output**: Query results
```lua
{
documents = {
{
id = "doc123",
file_path = "/path/to/document.md",
properties = {
status = "draft",
priority = "high",
created_at = "2024-03-15T10:30:00Z"
}
}
},
total_count = 1,
execution_time_ms = 45,
query_hash = "abc123def"
}
```
## Virtual Buffer API
### Create Query View
**Input**: Query results
**Output**: Virtual buffer configuration
```lua
{
buffer_id = 5,
window_id = 1002,
lines = {
"Results for: status=draft, priority=high",
"",
"| Title | Status | Priority | Created |",
"|--------------|--------|----------|-------------|",
"| Research Doc | draft | high | 2024-03-15 |"
},
mappings = {
["<CR>"] = "open_document",
["e"] = "edit_document",
["q"] = "close_query_view"
},
syntax = "notex_query_results"
}
```
### Update Document Property
**Input**: Document ID, property name, new value
**Output**: Update result
```lua
{
success = true,
document_id = "doc123",
property = "status",
old_value = "draft",
new_value = "review",
updated_file = true
}
```
## Error Handling
### Query Parse Errors
```lua
{
error_type = "parse_error",
message = "Invalid syntax at line 3: column 5",
line = 3,
column = 5,
context = "WHERE priority >"
}
```
### Query Execution Errors
```lua
{
error_type = "execution_error",
message = "Property 'nonexistent' not found in any document",
property_name = "nonexistent",
suggested_properties = {"status", "priority", "type"}
}
```
### Document Update Errors
```lua
{
error_type = "update_error",
message = "File not found or not writable",
document_id = "doc123",
file_path = "/path/to/missing.md"
}
```

108
specs/002-notex-is-a/data-model.md Normal file
View file

@ -0,0 +1,108 @@
# Data Model: Relational Document System
## Core Entities
### Document
**Purpose**: Represents a markdown file with indexed properties
**Fields**:
- id (string): Unique identifier, typically file path hash
- file_path (string): Absolute path to markdown file
- content_hash (string): SHA256 hash of file content for change detection
- last_modified (integer): Unix timestamp of last file modification
- created_at (integer): Timestamp when document was first indexed
- updated_at (integer): Timestamp of last index update
### Property
**Purpose**: Individual key-value pairs extracted from YAML headers
**Fields**:
- id (string): Unique property identifier
- document_id (string): Foreign key to Document
- key (string): Property name from YAML header
- value (string): Serialized property value
- value_type (string): Data type (string, number, boolean, date, array)
- created_at (integer): Timestamp when property was created
- updated_at (integer): Timestamp of last property update
### Query
**Purpose**: Saved query definitions for reuse
**Fields**:
- id (string): Unique query identifier
- name (string): Human-readable query name
- definition (string): Query syntax definition
- created_at (integer): Query creation timestamp
- last_used (integer): Timestamp of last query execution
- use_count (integer): Number of times query has been executed
### Schema
**Purpose**: Metadata about property types and validation rules
**Fields**:
- property_key (string): Property name across documents
- detected_type (string): Most common data type for this property
- validation_rules (string): JSON-encoded validation rules
- document_count (integer): Number of documents containing this property
- created_at (integer): Timestamp when schema entry was created
## Relationships
### Document ↔ Property
- One-to-many: Each document has multiple properties
- Cascade delete: Properties are removed when document is deleted
### Document ↔ Query
- Many-to-many: Queries can reference multiple documents
- Junction table: QueryResults stores execution history
### Property ↔ Schema
- Many-to-one: Multiple properties with same key map to one schema entry
## Data Types
### Supported Property Types
- **string**: Text values (default type)
- **number**: Numeric values (integer or float)
- **boolean**: true/false values
- **date**: ISO 8601 date strings
- **array**: JSON-encoded arrays
- **object**: JSON-encoded objects (nested structures)
### Type Detection Logic
1. Parse YAML value using native YAML parser
2. Apply type detection rules:
- Strings matching ISO 8601 format → date
- Numeric strings without decimals → number (integer)
- Numeric strings with decimals → number (float)
- "true"/"false" (case insensitive) → boolean
- Arrays/objects → respective types
- Everything else → string
## Indexing Strategy
### Primary Indices
- documents.file_path (unique)
- properties.document_id (foreign key)
- properties.key (for property-based queries)
- queries.id (unique)
### Composite Indices
- properties(document_id, key) for fast document property lookup
- properties(key, value_type) for type-constrained queries
- queries(last_used) for recent query tracking
## Validation Rules
### Document Validation
- File must exist and be readable
- File must have valid YAML header (--- delimiters)
- YAML must parse without errors
- File must be UTF-8 encoded
### Property Validation
- Property keys must be non-empty strings
- Property values must be serializable
- Array/object values must be valid JSON
- Date values must match ISO 8601 format
### Query Validation
- Query syntax must be valid according to defined grammar
- Query must reference existing properties
- Query complexity must be within performance limits

237
specs/002-notex-is-a/plan.md Normal file
View file

@ -0,0 +1,237 @@
# Implementation Plan: Relational Document System for Neovim
**Branch**: `002-notex-is-a` | **Date**: 2025-10-03 | **Spec**: /specs/002-notex-is-a/spec.md
**Input**: Feature specification from `/specs/002-notex-is-a/spec.md`
## Execution Flow (/plan command scope)
```
1. Load feature spec from Input path
→ If not found: ERROR "No feature spec at {path}"
2. Fill Technical Context (scan for NEEDS CLARIFICATION)
→ Detect Project Type from file system structure or context (web=frontend+backend, mobile=app+api)
→ Set Structure Decision based on project type
3. Fill the Constitution Check section based on the content of the constitution document.
4. Evaluate Constitution Check section below
→ If violations exist: Document in Complexity Tracking
→ If no justification possible: ERROR "Simplify approach first"
→ Update Progress Tracking: Initial Constitution Check
5. Execute Phase 0 → research.md
→ If NEEDS CLARIFICATION remain: ERROR "Resolve unknowns"
6. Execute Phase 1 → contracts, data-model.md, quickstart.md, agent-specific template file (e.g., `CLAUDE.md` for Claude Code, `.github/copilot-instructions.md` for GitHub Copilot, `GEMINI.md` for Gemini CLI, `QWEN.md` for Qwen Code, or `AGENTS.md` for all other agents).
7. Re-evaluate Constitution Check section
→ If new violations: Refactor design, return to Phase 1
→ Update Progress Tracking: Post-Design Constitution Check
8. Plan Phase 2 → Describe task generation approach (DO NOT create tasks.md)
9. STOP - Ready for /tasks command
```
**IMPORTANT**: The /plan command STOPS at step 7. Phases 2-4 are executed by other commands:
- Phase 2: /tasks command creates tasks.md
- Phase 3-4: Implementation execution (manual or via tools)
## Summary
A Neovim plugin that provides a relational document system similar to Notion, enabling users to query, filter, and view markdown documents based on YAML header properties through custom syntax and virtual buffers.
## Technical Context
**Language/Version**: Lua (Neovim compatible)
**Primary Dependencies**: SQLite (for performant indexing and querying)
**Storage**: SQLite database + markdown files with YAML headers
**Testing**: busted (Lua testing framework)
**Target Platform**: Neovim
**Project Type**: Single project (Neovim plugin)
**Performance Goals**: Query execution <100ms, indexing thousands of documents
**Constraints**: Non-blocking queries, minimal dependencies, Lua-only implementation
**Scale/Scope**: Support libraries of several thousand markdown documents
## Constitution Check
*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
* **I. Clean Code**: Is the proposed code structure and design clean and maintainable?
* **II. Functional Style**: Does the design favor functional approaches for data transformation?
* **III. Descriptive Coding**: Is the naming of components and files descriptive and self-documenting?
* **IV. Test-First Development**: Are comprehensive tests planned before implementation?
* **V. Performance by Design**: Are performance considerations adequately addressed?
## Project Structure
### Documentation (this feature)
```
specs/[###-feature]/
├── plan.md # This file (/plan command output)
├── research.md # Phase 0 output (/plan command)
├── data-model.md # Phase 1 output (/plan command)
├── quickstart.md # Phase 1 output (/plan command)
├── contracts/ # Phase 1 output (/plan command)
└── tasks.md # Phase 2 output (/tasks command - NOT created by /plan)
```
### Source Code (repository root)
```
lua/
└── notex/
├── init.lua # Plugin entry point and setup
├── database/
│ ├── init.lua # Database connection and initialization
│ ├── schema.lua # Database schema management
│ └── migrations.lua # Database migration handling
├── parser/
│ ├── init.lua # Document parsing coordination
│ ├── yaml.lua # YAML header extraction and parsing
│ └── markdown.lua # Markdown content processing
├── query/
│ ├── init.lua # Query engine coordination
│ ├── parser.lua # Query syntax parsing
│ ├── executor.lua # Query execution logic
│ └── builder.lua # SQL query construction
├── ui/
│ ├── init.lua # UI coordination
│ ├── buffer.lua # Virtual buffer management
│ ├── view.lua # Query result visualization
│ └── editor.lua # Inline editing interface
├── index/
│ ├── init.lua # Document indexing coordination
│ ├── scanner.lua # File system scanning
│ └── updater.lua # Incremental index updates
└── utils/
├── init.lua # Utility functions
├── date.lua # Date parsing and formatting
├── types.lua # Type detection and conversion
└── validation.lua # Data validation helpers
tests/
├── unit/ # Unit tests for individual modules
│ ├── database/
│ ├── parser/
│ ├── query/
│ ├── ui/
│ ├── index/
│ └── utils/
├── integration/ # Integration tests for workflows
│ ├── test_query_workflow.lua
│ ├── test_document_indexing.lua
│ └── test_virtual_buffer.lua
└── contract/ # Contract tests from API definitions
├── test_query_api.lua
└── test_document_api.lua
```
**Structure Decision**: Single project structure optimized for Neovim plugin architecture with clear separation of concerns across domains (database, parsing, querying, UI, indexing).
## Phase 0: Outline & Research
1. **Extract unknowns from Technical Context** above:
- For each NEEDS CLARIFICATION → research task
- For each dependency → best practices task
- For each integration → patterns task
2. **Generate and dispatch research agents**:
```
For each unknown in Technical Context:
Task: "Research {unknown} for {feature context}"
For each technology choice:
Task: "Find best practices for {tech} in {domain}"
```
3. **Consolidate findings** in `research.md` using format:
- Decision: [what was chosen]
- Rationale: [why chosen]
- Alternatives considered: [what else evaluated]
**Output**: research.md with all NEEDS CLARIFICATION resolved
## Phase 1: Design & Contracts
*Prerequisites: research.md complete*
1. **Extract entities from feature spec** → `data-model.md`:
- Entity name, fields, relationships
- Validation rules from requirements
- State transitions if applicable
2. **Generate API contracts** from functional requirements:
- For each user action → endpoint
- Use standard REST/GraphQL patterns
- Output OpenAPI/GraphQL schema to `/contracts/`
3. **Generate contract tests** from contracts:
- One test file per endpoint
- Assert request/response schemas
- Tests must fail (no implementation yet)
4. **Extract test scenarios** from user stories:
- Each story → integration test scenario
- Quickstart test = story validation steps
5. **Update agent file incrementally** (O(1) operation):
- Run `.specify/scripts/bash/update-agent-context.sh claude`
**IMPORTANT**: Execute it exactly as specified above. Do not add or remove any arguments.
- If exists: Add only NEW tech from current plan
- Preserve manual additions between markers
- Update recent changes (keep last 3)
- Keep under 150 lines for token efficiency
- Output to repository root
**Output**: data-model.md, /contracts/*, failing tests, quickstart.md, agent-specific file
## Phase 2: Task Planning Approach
*This section describes what the /tasks command will do - DO NOT execute during /plan*
**Task Generation Strategy**:
- Load `.specify/templates/tasks-template.md` as base
- Generate tasks from Phase 1 design docs (contracts, data model, quickstart)
- Query API contract → query parsing and execution test tasks [P]
- Database schema models → schema and migration tasks [P]
- Document parser contracts → YAML parsing and indexing tasks [P]
- UI contracts → virtual buffer and view tasks [P]
- Quickstart scenarios → integration test tasks
- Implementation tasks to make tests pass
**Ordering Strategy**:
- TDD order: Tests before implementation
- Dependency order: Database → Parser → Query → UI → Integration
- Mark [P] for parallel execution (independent files)
**Estimated Output**: 28-32 numbered, ordered tasks in tasks.md covering:
- Database setup and schema (4-5 tasks)
- Document parsing and indexing (6-7 tasks)
- Query parsing and execution (6-7 tasks)
- Virtual buffer UI (5-6 tasks)
- Integration and testing (4-5 tasks)
- Documentation and polish (3-4 tasks)
**IMPORTANT**: This phase is executed by the /tasks command, NOT by /plan
## Phase 3+: Future Implementation
*These phases are beyond the scope of the /plan command*
**Phase 3**: Task execution (/tasks command creates tasks.md)
**Phase 4**: Implementation (execute tasks.md following constitutional principles)
**Phase 5**: Validation (run tests, execute quickstart.md, performance validation)
## Complexity Tracking
*Fill ONLY if Constitution Check has violations that must be justified*
| Violation | Why Needed | Simpler Alternative Rejected Because |
|-----------|------------|-------------------------------------|
| [e.g., 4th project] | [current need] | [why 3 projects insufficient] |
| [e.g., Repository pattern] | [specific problem] | [why direct DB access insufficient] |
## Progress Tracking
*This checklist is updated during execution flow*
**Phase Status**:
- [x] Phase 0: Research complete (/plan command)
- [x] Phase 1: Design complete (/plan command)
- [x] Phase 2: Task planning complete (/plan command - describe approach only)
- [ ] Phase 3: Tasks generated (/tasks command)
- [ ] Phase 4: Implementation complete
- [ ] Phase 5: Validation passed
**Gate Status**:
- [x] Initial Constitution Check: PASS
- [x] Post-Design Constitution Check: PASS
- [x] All NEEDS CLARIFICATION resolved
- [x] Complexity deviations documented
---
*Based on Constitution v1.0.0 - See `/memory/constitution.md`*

192
specs/002-notex-is-a/quickstart.md Normal file
View file

@ -0,0 +1,192 @@
# Quickstart Guide: Notex Relational Document System
## Installation
1. Install the plugin using your preferred Neovim plugin manager
2. Ensure SQLite is available on your system
3. Restart Neovim to load the plugin
## Initial Setup
### 1. Index Your Documents
```vim
"Notex will automatically scan for markdown files in your workspace
"You can also manually trigger indexing:
:NotexIndex /path/to/your/documents
```
### 2. Create Your First Query
Open a markdown file and add a query block:
```markdown
# My Project Dashboard
```notex-query
status: "active"
priority: "high"
ORDER BY created_at DESC
```
```
### 3. View Query Results
- Hover over the query block with your cursor
- Press `<leader>q` to open the query in a virtual buffer
- The results will show all matching documents in a table format
## Basic Usage
### Querying Documents
#### Simple Property Filter
```markdown
```notex-query
status: "draft"
```
```
#### Multiple Properties
```markdown
```notex-query
status: "active"
priority: "high"
tags: ["urgent", "review"]
```
```
#### Advanced Filtering
```markdown
```notex-query
FROM priority: "high"
WHERE created_at >= "2024-01-01"
ORDER BY due_date ASC
LIMIT 10
```
```
### Working with Query Results
#### Open Documents
- Move cursor to any row in the results table
- Press `<Enter>` to open the document in a new split
- Press `o` to open in a new tab
#### Edit Properties
- Press `e` on any result row to enter edit mode
- Change property values directly in the table
- Press `<Enter>` to save changes to the source document
#### Save Queries
- Press `s` to save the current query for reuse
- Give your query a name like "My Active Tasks"
- Access saved queries with `:NotexQueries`
## Document Properties
### YAML Header Format
```yaml
---
title: "Project Documentation"
status: "active"
priority: "high"
tags: ["documentation", "project"]
created_at: "2024-03-15"
due_date: "2024-04-01"
assignee: "john@example.com"
progress: 75
---
```
### Supported Property Types
- **Text**: "draft", "documentation", "john@example.com"
- **Numbers**: 75, 1.5, -10
- **Booleans**: true, false
- **Dates**: "2024-03-15", "2024-03-15T10:30:00Z"
- **Arrays**: ["tag1", "tag2"], [1, 2, 3]
## Advanced Features
### Query Conditions
```markdown
```notex-query
WHERE priority > 5 AND status != "archived"
WHERE tags INCLUDES "urgent"
WHERE created_at BEFORE "2024-01-01"
WHERE title CONTAINS "important"
```
```
### Grouping and Aggregation
```markdown
```notex-query
GROUP BY status
ORDER BY priority DESC
```
```
### Custom Query Shortcuts
Add to your Neovim config:
```vim
lua
vim.keymap.set('n', '<leader>qt', ':NotexQuery<CR>')
vim.keymap.set('n', '<leader>qr', ':NotexRefresh<CR>')
vim.keymap.set('n', '<leader>qs', ':NotexSaveQuery<CR>')
```
## Testing Your Setup
### 1. Create Test Documents
Create two markdown files with YAML headers:
`doc1.md`:
```yaml
---
title: "First Document"
status: "draft"
priority: "high"
tags: ["test"]
---
```
`doc2.md`:
```yaml
---
title: "Second Document"
status: "review"
priority: "medium"
tags: ["test", "review"]
---
```
### 2. Create Test Query
```markdown
```notex-query
tags: "test"
```
```
### 3. Verify Results
The query should return both documents in a table format.
## Troubleshooting
### Query Not Working
- Check that YAML headers are properly formatted with `---` delimiters
- Ensure property names in queries match exactly with YAML keys
- Verify that documents have been indexed (`:NotexStatus`)
### Performance Issues
- Use more specific filters to reduce result sets
- Consider adding `LIMIT` to large queries
- Check `:NotexStatus` for indexing performance metrics
### File Not Found Errors
- Ensure file paths in your workspace are accessible
- Check file permissions for read/write access
- Run `:NotexReindex` to refresh the document database
## Next Steps
- Explore the query syntax documentation for advanced filtering
- Set up custom query templates for common workflows
- Integrate with your existing Neovim workflow and plugins
- Share queries with your team for consistent document management

43
specs/002-notex-is-a/research.md Normal file
View file

@ -0,0 +1,43 @@
# Research: Relational Document System for Neovim
## SQLite Integration
**Decision**: Use lsqlite3 for SQLite database operations
**Rationale**: lsqlite3 is the most mature and widely used SQLite binding for Lua, with excellent Neovim compatibility and minimal dependencies
**Alternatives considered**:
- lua-sqlite3 (less mature, fewer updates)
- Custom file-based indexing (limited query capabilities)
## YAML Parsing
**Decision**: Use lyaml for YAML header parsing
**Rationale**: lyaml provides robust YAML parsing with proper error handling for malformed headers, essential for document reliability
**Alternatives considered**:
- Custom regex parsing (brittle, fails with complex YAML)
- yaml.lua (less maintained than lyaml)
## Virtual Buffer Management
**Decision**: Use Neovim's native nvim_buf_ API
**Rationale**: Native API provides the most seamless integration with Neovim's buffer system, ensuring compatibility with existing plugins and user workflows
**Alternatives considered**:
- Floating windows (less persistent, not ideal for editing)
- External terminal buffers (breaks Neovim integration)
## Query Syntax Design
**Decision**: Custom block syntax similar to code blocks
**Rationale**: Block syntax is familiar to markdown users and provides clear delimiters for query parsing while maintaining readability
**Alternatives considered**:
- Inline syntax (cluttered, hard to parse)
- Special comments (not intuitive for query visualization)
## Performance Optimization
**Decision**: Hybrid indexing approach (SQLite + in-memory cache)
**Rationale**: SQLite provides persistent storage and complex query capabilities, while in-memory caching ensures sub-100ms response times for frequently accessed data
**Alternatives considered**:
- Pure file-based indexing (slow for large document sets)
- Pure in-memory (data loss on restart)
## Testing Framework
**Decision**: busted with nvim-test plugin
**Rationale**: busted provides comprehensive testing capabilities with good async support, while nvim-test enables Neovim-specific testing scenarios
**Alternatives considered**:
- luaunit (limited Neovim integration)
- Custom testing harness (maintenance overhead)

123
specs/002-notex-is-a/spec.md Normal file
View file

@ -0,0 +1,123 @@
# Feature Specification: Relational Document System for Neovim
**Feature Branch**: `002-notex-is-a`
**Created**: 2025-10-03
**Status**: Draft
**Input**: User description: "Notex is a relational database plugin that mimics notion databases. This should define a custom query syntax. When mousing over the custom syntax, this should open virtual buffer that shows an editable view into the database. This database should summarize properties of markdown documents that are defined in a yaml header. This project should leverage sqlite database to improve performance"
## Execution Flow (main)
```
1. Parse user description from Input
→ If empty: ERROR "No feature description provided"
2. Extract key concepts from description
→ Identify: actors, actions, data, constraints
3. For each unclear aspect:
→ Mark with [NEEDS CLARIFICATION: specific question]
4. Fill User Scenarios & Testing section
→ If no clear user flow: ERROR "Cannot determine user scenarios"
5. Generate Functional Requirements
→ Each requirement must be testable
→ Mark ambiguous requirements
6. Identify Key Entities (if data involved)
7. Run Review Checklist
→ If any [NEEDS CLARIFICATION]: WARN "Spec has uncertainties"
→ If implementation details found: ERROR "Remove tech details"
8. Return: SUCCESS (spec ready for planning)
```
---
## ⚡ Quick Guidelines
- ✅ Focus on WHAT users need and WHY
- ❌ Avoid HOW to implement (no tech stack, APIs, code structure)
- 👥 Written for business stakeholders, not developers
### Section Requirements
- **Mandatory sections**: Must be completed for every feature
- **Optional sections**: Include only when relevant to the feature
- When a section doesn't apply, remove it entirely (don't leave as "N/A")
### For AI Generation
When creating this spec from a user prompt:
1. **Mark all ambiguities**: Use [NEEDS CLARIFICATION: specific question] for any assumption you'd need to make
2. **Don't guess**: If the prompt doesn't specify something (e.g., "login system" without auth method), mark it
3. **Think like a tester**: Every vague requirement should fail the "testable and unambiguous" checklist item
4. **Common underspecified areas**:
- User types and permissions
- Data retention/deletion policies
- Performance targets and scale
- Error handling behaviors
- Integration requirements
- Security/compliance needs
---
## User Scenarios & Testing *(mandatory)*
### Primary User Story
As a Neovim user, I want to work with my markdown documents as if they were entries in a relational database similar to Notion, so that I can query, filter, and view my documents based on their properties without leaving my editor.
### Acceptance Scenarios
1. **Given** I have markdown documents with YAML headers, **When** I write a custom query syntax in my buffer, **Then** hovering over it should display a virtual buffer with the query results
2. **Given** I'm viewing query results in a virtual buffer, **When** I modify the data, **Then** the changes should be reflected in the underlying markdown documents
3. **Given** I have multiple markdown documents, **When** I execute a query, **Then** the system should return results based on the YAML header properties
4. **Given** I define a custom query, **When** I save the query, **Then** I should be able to reuse it later
### Edge Cases
- What happens when markdown documents have malformed or missing YAML headers?
- How does system handle queries that return no results?
- What happens when multiple documents have conflicting property definitions?
- How does system handle very large document collections?
- What happens when the virtual buffer is edited while the underlying files are changed externally?
## Requirements *(mandatory)*
### Functional Requirements
- **FR-001**: System MUST parse YAML headers from markdown documents to extract document properties
- **FR-002**: System MUST provide a custom query syntax for filtering and organizing documents
- **FR-003**: Users MUST be able to hover over query syntax to see results in a virtual buffer
- **FR-004**: Query results MUST be editable and changes must propagate back to source documents
- **FR-005**: System MUST maintain a performant index of document properties for fast querying
- **FR-006**: Users MUST be able to save and reuse common queries
- **FR-007**: System MUST support filtering documents by any property defined in YAML headers
- **FR-008**: Virtual buffer views MUST support sorting and grouping of query results
### Key Entities
- **Document**: Represents a markdown file with YAML header properties and content
- **Query**: Defines filtering criteria and display options for documents
- **Property**: Individual key-value pairs extracted from YAML headers
- **View**: Virtual buffer representation of query results
- **Schema**: Defines the structure and types of properties across documents
---
## Review & Acceptance Checklist
*GATE: Automated checks run during main() execution*
### Content Quality
- [x] No implementation details (languages, frameworks, APIs)
- [x] Focused on user value and business needs
- [x] Written for non-technical stakeholders
- [x] All mandatory sections completed
### Requirement Completeness
- [x] No [NEEDS CLARIFICATION] markers remain
- [x] Requirements are testable and unambiguous
- [x] Success criteria are measurable
- [x] Scope is clearly bounded
- [x] Dependencies and assumptions identified
---
## Execution Status
*Updated by main() during processing*
- [x] User description parsed
- [x] Key concepts extracted
- [x] Ambiguities marked
- [x] User scenarios defined
- [x] Requirements generated
- [x] Entities identified
- [x] Review checklist passed
---

205
specs/002-notex-is-a/tasks.md Normal file
View file

@ -0,0 +1,205 @@
# Tasks: Relational Document System for Neovim
**Input**: Design documents from `/specs/002-notex-is-a/`
**Prerequisites**: plan.md (required), research.md, data-model.md, contracts/, quickstart.md
## Execution Flow (main)
```
1. Load plan.md from feature directory
→ If not found: ERROR "No implementation plan found"
→ Extract: tech stack, libraries, structure
2. Load optional design documents:
→ data-model.md: Extract entities → model tasks
→ contracts/: Each file → contract test task
→ research.md: Extract decisions → setup tasks
3. Generate tasks by category:
→ Setup: project init, dependencies, linting
→ Tests: contract tests, integration tests
→ Core: models, services, CLI commands
→ Integration: DB, middleware, logging
→ Polish: unit tests, performance, docs
4. Apply task rules:
→ Different files = mark [P] for parallel
→ Same file = sequential (no [P])
→ Tests before implementation (TDD)
5. Number tasks sequentially (T001, T002...)
6. Generate dependency graph
7. Create parallel execution examples
8. Validate task completeness:
→ All contracts have tests?
→ All entities have models?
→ All endpoints implemented?
9. Return: SUCCESS (tasks ready for execution)
```
## Format: `[ID] [P?] Description`
- **[P]**: Can run in parallel (different files, no dependencies)
- Include exact file paths in descriptions
## Path Conventions
- **Neovim plugin**: `lua/notex/`, `tests/` at repository root
- Paths shown below follow the project structure from plan.md
## Phase 3.1: Setup
- [x] T001 Create project structure per implementation plan (lua/notex/, tests/)
- [x] T002 Initialize Lua project with lsqlite3, lyaml, busted dependencies
- [x] T003 [P] Configure luacheck and stylua for Lua code formatting
## Phase 3.2: Tests First (TDD) ⚠️ MUST COMPLETE BEFORE 3.3
**CRITICAL: These tests MUST be written and MUST FAIL before ANY implementation**
- [x] T004 [P] Contract test query parsing API in tests/contract/test_query_api.lua
- [x] T005 [P] Contract test query execution API in tests/contract/test_query_api.lua
- [x] T006 [P] Contract test virtual buffer API in tests/contract/test_query_api.lua
- [x] T007 [P] Integration test document indexing workflow in tests/integration/test_document_indexing.lua
- [x] T008 [P] Integration test query workflow in tests/integration/test_query_workflow.lua
- [x] T009 [P] Integration test virtual buffer workflow in tests/integration/test_virtual_buffer.lua
## Phase 3.3: Core Implementation - Database Layer (ONLY after tests are failing)
- [x] T010 [P] Database connection module in lua/notex/database/init.lua
- [x] T011 [P] Database schema module in lua/notex/database/schema.lua
- [x] T012 [P] Database migrations module in lua/notex/database/migrations.lua
- [x] T013 Document model implementation in lua/notex/database/schema.lua
- [x] T014 Property model implementation in lua/notex/database/schema.lua
- [x] T015 Query model implementation in lua/notex/database/schema.lua
- [x] T016 Schema model implementation in lua/notex/database/schema.lua
## Phase 3.4: Core Implementation - Parser Layer
- [x] T017 [P] YAML header parser in lua/notex/parser/yaml.lua
- [x] T018 [P] Markdown content parser in lua/notex/parser/markdown.lua
- [x] T019 Parser coordination module in lua/notex/parser/init.lua
- [x] T020 Document indexing coordination in lua/notex/index/init.lua
- [x] T021 [P] File system scanner in lua/notex/index/scanner.lua
- [x] T022 [P] Incremental index updater in lua/notex/index/updater.lua
## Phase 3.5: Core Implementation - Query Layer
- [x] T023 [P] Query syntax parser in lua/notex/query/parser.lua
- [x] T024 [P] SQL query builder in lua/notex/query/builder.lua
- [x] T025 [P] Query execution engine in lua/notex/query/executor.lua
- [x] T026 Query coordination module in lua/notex/query/init.lua
## Phase 3.6: Core Implementation - UI Layer
- [x] T027 [P] Virtual buffer manager in lua/notex/ui/buffer.lua
- [x] T028 [P] Query result visualization in lua/notex/ui/view.lua
- [x] T029 [P] Inline editing interface in lua/notex/ui/editor.lua
- [x] T030 UI coordination module in lua/notex/ui/init.lua
## Phase 3.7: Core Implementation - Plugin Integration
- [ ] T031 [P] Utility functions in lua/notex/utils/init.lua
- [ ] T032 [P] Date parsing and formatting in lua/notex/utils/date.lua
- [ ] T033 [P] Type detection and conversion in lua/notex/utils/types.lua
- [ ] T034 [P] Data validation helpers in lua/notex/utils/validation.lua
- [ ] T035 Plugin entry point and setup in lua/notex/init.lua
## Phase 3.8: Integration and Error Handling
- [ ] T036 Connect database layer to parser layer
- [ ] T037 Connect parser layer to query layer
- [ ] T038 Connect query layer to UI layer
- [ ] T039 Error handling and logging integration
- [ ] T040 Performance optimization and caching
## Phase 3.9: Polish and Documentation
- [ ] T041 [P] Unit tests for utility functions in tests/unit/utils/
- [ ] T042 [P] Unit tests for database operations in tests/unit/database/
- [ ] T043 [P] Unit tests for parser functions in tests/unit/parser/
- [ ] T044 [P] Unit tests for query operations in tests/unit/query/
- [ ] T045 [P] Unit tests for UI components in tests/unit/ui/
- [ ] T046 Performance tests (<100ms query execution)
- [ ] T047 [P] Update README.md with installation and usage
- [ ] T048 [P] Create comprehensive API documentation
- [ ] T049 Remove code duplication and optimize
- [ ] T050 Run quickstart.md manual testing scenarios
## Dependencies
- Setup (T001-T003) before everything
- Tests (T004-T009) before all implementation (T010-T050)
- Database layer (T010-T016) blocks parser layer (T017-T022)
- Parser layer (T017-T022) blocks query layer (T023-T026)
- Query layer (T023-T026) blocks UI layer (T027-T030)
- UI layer (T027-T030) blocks plugin integration (T031-T035)
- Integration (T036-T040) before polish (T041-T050)
## Parallel Execution Examples
### Phase 3.2 - Contract Tests (Parallel)
```
# Launch T004-T009 together:
Task: "Contract test query parsing API in tests/contract/test_query_api.lua"
Task: "Contract test query execution API in tests/contract/test_query_api.lua"
Task: "Contract test virtual buffer API in tests/contract/test_query_api.lua"
Task: "Integration test document indexing workflow in tests/integration/test_document_indexing.lua"
Task: "Integration test query workflow in tests/integration/test_query_workflow.lua"
Task: "Integration test virtual buffer workflow in tests/integration/test_virtual_buffer.lua"
```
### Phase 3.3 - Database Models (Parallel)
```
# Launch T010-T016 together:
Task: "Database connection module in lua/notex/database/init.lua"
Task: "Database schema module in lua/notex/database/schema.lua"
Task: "Database migrations module in lua/notex/database/migrations.lua"
Task: "Document model implementation in lua/notex/database/schema.lua"
Task: "Property model implementation in lua/notex/database/schema.lua"
Task: "Query model implementation in lua/notex/database/schema.lua"
Task: "Schema model implementation in lua/notex/database/schema.lua"
```
### Phase 3.4 - Parser Components (Parallel)
```
# Launch T017-T022 together:
Task: "YAML header parser in lua/notex/parser/yaml.lua"
Task: "Markdown content parser in lua/notex/parser/markdown.lua"
Task: "File system scanner in lua/notex/index/scanner.lua"
Task: "Incremental index updater in lua/notex/index/updater.lua"
```
### Phase 3.9 - Unit Tests (Parallel)
```
# Launch T041-T045 together:
Task: "Unit tests for utility functions in tests/unit/utils/"
Task: "Unit tests for database operations in tests/unit/database/"
Task: "Unit tests for parser functions in tests/unit/parser/"
Task: "Unit tests for query operations in tests/unit/query/"
Task: "Unit tests for UI components in tests/unit/ui/"
```
## Notes
- [P] tasks = different files, no dependencies
- Verify tests fail before implementing
- Commit after each task
- Avoid: vague tasks, same file conflicts
- Follow constitutional principles: Clean Code, Functional Style, Descriptive Coding, Test-First Development, Performance by Design
## Task Generation Rules Applied
1. **From Contracts**:
- query-api.md → contract tests T004-T006 [P]
- API endpoints → implementation tasks T023-T030
2. **From Data Model**:
- Document entity → model task T013 [P]
- Property entity → model task T014 [P]
- Query entity → model task T015 [P]
- Schema entity → model task T016 [P]
3. **From Research Decisions**:
- lsqlite3 dependency → setup task T002
- lyaml dependency → parser task T017
- busted framework → test tasks T004-T009
4. **From User Stories**:
- Document indexing → integration test T007 [P]
- Query execution → integration test T008 [P]
- Virtual buffer interaction → integration test T009 [P]
- Quickstart scenarios → validation task T050
5. **Ordering Strategy**:
- Setup → Tests → Database → Parser → Query → UI → Integration → Polish
- Dependencies block parallel execution
## Validation Checklist
- [x] All contracts have corresponding tests
- [x] All entities have model tasks
- [x] All tests come before implementation
- [x] Parallel tasks truly independent
- [x] Each task specifies exact file path
- [x] No task modifies same file as another [P] task