Skip to content

Commit e449d4a

Browse files
pashagolubpashagolub
committed
add specification
1 parent 197a101 commit e449d4a

File tree

11 files changed

+4833
-35
lines changed

11 files changed

+4833
-35
lines changed

‎.github/agents/copilot-instructions.md‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
# cybertec-pev-panel Development Guidelines
2+
3+
Auto-generated from all feature plans. Last updated: 2025-11-24
4+
5+
## Active Technologies
6+
7+
- TypeScript 5.x with strict mode enabled, targeting ES2020+ (001-grafana-explain-panel)
8+
9+
## Project Structure
10+
11+
```text
12+
src/
13+
tests/
14+
```
15+
16+
## Commands
17+
18+
npm test; npm run lint
19+
20+
## Code Style
21+
22+
TypeScript 5.x with strict mode enabled, targeting ES2020+: Follow standard conventions
23+
24+
## Recent Changes
25+
26+
- 001-grafana-explain-panel: Added TypeScript 5.x with strict mode enabled, targeting ES2020+
27+
28+
<!-- MANUAL ADDITIONS START -->
29+
<!-- MANUAL ADDITIONS END -->

‎.specify/memory/constitution.md‎

Lines changed: 147 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -1,50 +1,162 @@
1-
# [PROJECT_NAME] Constitution
2-
<!-- Example: Spec Constitution, TaskFlow Constitution, etc. -->
1+
<!--
2+
SYNC IMPACT REPORT
3+
==================
4+
Version Change: NONE → 1.0.0
5+
Constitution Type: New (Initial Ratification)
6+
7+
Principles Defined:
8+
1. Security First
9+
2. Deterministic & Production-Grade
10+
3. Bundled Dependencies
11+
4. Grafana Plugin Standards
12+
5. React-Based UI
13+
6. Clear Architecture
14+
7. Type Safety
15+
8. PEV2 Integration
16+
9. Error Handling
17+
10. Performance
18+
19+
Additional Sections:
20+
- Quality Standards
21+
- Development Workflow
22+
- Governance
23+
24+
Templates Status:
25+
✅ plan-template.md - Reviewed, no updates needed (generic template structure compatible)
26+
✅ spec-template.md - Reviewed, no updates needed (generic template structure compatible)
27+
✅ tasks-template.md - Reviewed, no updates needed (generic template structure compatible)
28+
✅ agent-file-template.md - Reviewed, no updates needed (generic template)
29+
✅ checklist-template.md - Reviewed, no updates needed (generic template)
30+
31+
Follow-up TODOs: None
32+
33+
Generated: 2025-11-24
34+
-->
35+
36+
# Grafana Panel Plugin for PostgreSQL EXPLAIN Visualization Constitution
37+
38+
**Project**: cybertec-pev-panel
39+
**Domain**: Grafana plugin development, TypeScript, React, PostgreSQL query analysis
40+
**Expert Role**: Grafana plugin engineer and TypeScript architect
341

442
## Core Principles
543

6-
### [PRINCIPLE_1_NAME]
7-
<!-- Example: I. Library-First -->
8-
[PRINCIPLE_1_DESCRIPTION]
9-
<!-- Example: Every feature starts as a standalone library; Libraries must be self-contained, independently testable, documented; Clear purpose required - no organizational-only libraries -->
44+
### I. Security First
45+
46+
All code MUST prioritize security above convenience. Never use unsafe HTML rendering (dangerouslySetInnerHTML), external CDN resources, iframes, or eval-based patterns. All user-provided content and PostgreSQL EXPLAIN output MUST be sanitized and validated before display. Grafana plugin sandboxing rules MUST be respected. No bypass of Content Security Policy. External scripts or resources are strictly prohibited.
47+
48+
**Rationale**: Grafana runs in enterprise environments with sensitive data. Security vulnerabilities in plugins can compromise entire Grafana installations and expose production databases.
49+
50+
### II. Deterministic & Production-Grade
51+
52+
All code MUST compile without modification and be production-ready on first delivery. TypeScript strict mode MUST be enabled with zero compilation errors. No experimental features, unstable APIs, or "it works on my machine" patterns. Code MUST be fully typed, documented, and tested before delivery. No placeholder implementations or TODOs in production code.
53+
54+
**Rationale**: Plugin failures in production can impact monitoring and observability. Deterministic behavior ensures reliability and reduces operational risk.
55+
56+
### III. Bundled Dependencies
57+
58+
All dependencies MUST be bundled within the plugin distribution. Zero external CDN usage. Zero runtime fetching of libraries, fonts, or resources. Plugin MUST work in air-gapped environments, VPNs, and restricted networks. PEV2 library and all its dependencies MUST be fully bundled using webpack or the Grafana build toolchain.
59+
60+
**Rationale**: Enterprise Grafana installations often run in isolated networks. External dependencies create failure points and security risks.
61+
62+
### IV. Grafana Plugin Standards
63+
64+
Strictly follow Grafana plugin guidelines, conventions, and best practices. Use official Grafana APIs, lifecycle hooks, and data models. Adhere to plugin.json schema requirements. Follow Grafana's theming system and design patterns. Use @grafana/data for data transformation, @grafana/runtime for runtime services, and @grafana/ui for all UI components.
65+
66+
**Rationale**: Grafana provides battle-tested patterns. Deviating from standards creates maintenance burden and compatibility issues across Grafana versions.
67+
68+
### V. React-Based UI
69+
70+
All UI components MUST be React-based using @grafana/ui components. No vanilla JavaScript DOM manipulation, jQuery, or imperative DOM updates. Leverage Grafana's theme-aware components for consistency. Use React hooks and functional components as the primary pattern. No class components unless required by third-party integration.
71+
72+
**Rationale**: React provides predictable UI updates and integrates seamlessly with Grafana's rendering pipeline. @grafana/ui ensures visual consistency and theme compatibility.
73+
74+
### VI. Clear Architecture
75+
76+
Favor explicitness over magic. Clear separation of concerns between data fetching, transformation, and presentation. Self-documenting code structure with intuitive file organization. Avoid overly clever abstractions or hidden dependencies. Each module should have a single, clear responsibility.
77+
78+
**Rationale**: Plugins may be maintained by teams unfamiliar with the original implementation. Clear architecture reduces onboarding time and maintenance cost.
79+
80+
### VII. Type Safety
1081

11-
### [PRINCIPLE_2_NAME]
12-
<!-- Example: II. CLI Interface -->
13-
[PRINCIPLE_2_DESCRIPTION]
14-
<!-- Example: Every library exposes functionality via CLI; Text in/out protocol: stdin/args → stdout, errors → stderr; Support JSON + human-readable formats -->
82+
Leverage TypeScript fully. No 'any' types unless absolutely necessary (document justification). Comprehensive interfaces for all data structures. Use strict TypeScript compiler options. Type all props, state, events, and API responses. Define explicit types for PostgreSQL EXPLAIN JSON structures.
1583

16-
### [PRINCIPLE_3_NAME]
17-
<!-- Example: III. Test-First (NON-NEGOTIABLE) -->
18-
[PRINCIPLE_3_DESCRIPTION]
19-
<!-- Example: TDD mandatory: Tests written → User approved → Tests fail → Then implement; Red-Green-Refactor cycle strictly enforced -->
84+
**Rationale**: Type safety catches bugs at compile time, provides IDE autocompletion, and serves as living documentation of data contracts.
2085

21-
### [PRINCIPLE_4_NAME]
22-
<!-- Example: IV. Integration Testing -->
23-
[PRINCIPLE_4_DESCRIPTION]
24-
<!-- Example: Focus areas requiring integration tests: New library contract tests, Contract changes, Inter-service communication, Shared schemas -->
86+
### VIII. PEV2 Integration
2587

26-
### [PRINCIPLE_5_NAME]
27-
<!-- Example: V. Observability, VI. Versioning & Breaking Changes, VII. Simplicity -->
28-
[PRINCIPLE_5_DESCRIPTION]
29-
<!-- Example: Text I/O ensures debuggability; Structured logging required; Or: MAJOR.MINOR.BUILD format; Or: Start simple, YAGNI principles -->
88+
Integrate the PEV2 (Postgres EXPLAIN Visualizer 2) library for EXPLAIN visualization while maintaining security and bundling requirements. PEV2 MUST be bundled, not loaded from CDN. Any required modifications to PEV2 MUST preserve its core visualization logic. Encapsulate PEV2 within a React component wrapper that handles Grafana-specific concerns (theming, data transformation, error handling).
3089

31-
## [SECTION_2_NAME]
32-
<!-- Example: Additional Constraints, Security Requirements, Performance Standards, etc. -->
90+
**Rationale**: PEV2 is the proven standard for PostgreSQL EXPLAIN visualization. Proper integration ensures users get expert-level query analysis while maintaining plugin security and reliability standards.
3391

34-
[SECTION_2_CONTENT]
35-
<!-- Example: Technology stack requirements, compliance standards, deployment policies, etc. -->
92+
### IX. Error Handling
3693

37-
## [SECTION_3_NAME]
38-
<!-- Example: Development Workflow, Review Process, Quality Gates, etc. -->
94+
Robust error boundaries at component boundaries. Graceful degradation when EXPLAIN data is malformed or incomplete. User-friendly error messages that guide users to resolution (e.g., "Invalid EXPLAIN JSON format. Ensure query returns EXPLAIN (FORMAT JSON) output"). All errors logged with sufficient context for debugging. No silent failures or generic error messages.
3995

40-
[SECTION_3_CONTENT]
41-
<!-- Example: Code review requirements, testing gates, deployment approval process, etc. -->
96+
**Rationale**: Query analysis involves parsing complex JSON from diverse PostgreSQL versions. Clear error messages reduce support burden and improve user experience.
97+
98+
### X. Performance
99+
100+
Efficient rendering for large EXPLAIN plans (1000+ nodes). Proper React optimization (memoization, virtualization for large trees). Minimal bundle size where possible without sacrificing functionality or bundling requirements. Lazy loading of PEV2 visualization logic if beneficial. Avoid unnecessary re-renders or computation.
101+
102+
**Rationale**: PostgreSQL EXPLAIN plans can be very large. Poor performance degrades the user experience and can make the plugin unusable for complex queries.
103+
104+
## Quality Standards
105+
106+
All code MUST meet the following quality gates before delivery:
107+
108+
- **Compilation**: Zero TypeScript errors with strict mode enabled
109+
- **Runtime**: No console errors or warnings in browser developer tools
110+
- **UI**: Responsive design supporting Grafana's responsive breakpoints
111+
- **Accessibility**: Keyboard navigation support, ARIA labels where appropriate
112+
- **Compatibility**: Works with Grafana 10.4.0+ and modern browsers (Chrome, Firefox, Safari, Edge)
113+
- **Documentation**: Clear README with setup instructions, usage examples, and troubleshooting guide
114+
115+
## Development Workflow
116+
117+
### Constitution Check Gates
118+
119+
Before any feature implementation:
120+
121+
1. **Security Review**: Verify no unsafe patterns (innerHTML, external resources, eval)
122+
2. **Dependency Audit**: Confirm all dependencies are bundled, no CDN usage
123+
3. **Type Safety Check**: Ensure strict TypeScript, no 'any' types without justification
124+
4. **Grafana Standards**: Verify use of official Grafana APIs and @grafana/ui components
125+
5. **Error Handling**: Confirm error boundaries and user-friendly error messages
126+
6. **Performance**: Validate rendering performance with sample large EXPLAIN plans
127+
128+
Re-check after design phase before implementation begins.
129+
130+
### Code Review Requirements
131+
132+
- All PRs MUST pass constitution compliance checks
133+
- Type safety verified (no 'any' escapes without documentation)
134+
- Security patterns validated (no unsafe HTML, external resources)
135+
- Error handling coverage confirmed
136+
- Performance impact assessed for large EXPLAIN plans
42137

43138
## Governance
44-
<!-- Example: Constitution supersedes all other practices; Amendments require documentation, approval, migration plan -->
45139

46-
[GOVERNANCE_RULES]
47-
<!-- Example: All PRs/reviews must verify compliance; Complexity must be justified; Use [GUIDANCE_FILE] for runtime development guidance -->
140+
This constitution supersedes all other development practices. Any deviation MUST be explicitly documented and justified with rationale.
141+
142+
### Amendment Process
143+
144+
- Constitution amendments require version bump and documentation update
145+
- Breaking changes to principles require major version increment
146+
- New principles or expanded guidance require minor version increment
147+
- Clarifications and wording improvements require patch version increment
148+
- All amendments MUST include Sync Impact Report at top of file
149+
150+
### Versioning Policy
151+
152+
Constitution follows semantic versioning (MAJOR.MINOR.PATCH):
153+
154+
- **MAJOR**: Backward incompatible governance changes or principle removals/redefinitions
155+
- **MINOR**: New principles added or materially expanded guidance
156+
- **PATCH**: Clarifications, wording improvements, non-semantic refinements
157+
158+
### Compliance Review
159+
160+
All feature specifications, implementation plans, and task lists MUST reference constitution principles. Violations MUST be tracked in Complexity Tracking section with explicit justification.
48161

49-
**Version**: [CONSTITUTION_VERSION] | **Ratified**: [RATIFICATION_DATE] | **Last Amended**: [LAST_AMENDED_DATE]
50-
<!-- Example: Version: 2.1.1 | Ratified: 2025-06-13 | Last Amended: 2025-07-16 -->
162+
**Version**: 1.0.0 | **Ratified**: 2025-11-24 | **Last Amended**: 2025-11-24

‎specs/001-grafana-explain-panel/checklists/requirements.md‎

Lines changed: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,98 @@
1+
# Specification Quality Checklist: Grafana PostgreSQL Explain Visualizer Panel Plugin
2+
3+
**Purpose**: Validate specification completeness and quality before proceeding to planning
4+
**Created**: 2025-11-24
5+
**Feature**: [spec.md](../spec.md)
6+
7+
## Content Quality
8+
9+
- [x] No implementation details (languages, frameworks, APIs)
10+
- [x] Focused on user value and business needs
11+
- [x] Written for non-technical stakeholders
12+
- [x] All mandatory sections completed
13+
14+
## Requirement Completeness
15+
16+
- [x] No [NEEDS CLARIFICATION] markers remain
17+
- [x] Requirements are testable and unambiguous
18+
- [x] Success criteria are measurable
19+
- [x] Success criteria are technology-agnostic (no implementation details)
20+
- [x] All acceptance scenarios are defined
21+
- [x] Edge cases are identified
22+
- [x] Scope is clearly bounded
23+
- [x] Dependencies and assumptions identified
24+
25+
## Feature Readiness
26+
27+
- [x] All functional requirements have clear acceptance criteria
28+
- [x] User scenarios cover primary flows
29+
- [x] Feature meets measurable outcomes defined in Success Criteria
30+
- [x] No implementation details leak into specification
31+
32+
## Validation Notes
33+
34+
### Content Quality Review
35+
✅ **PASS**: Specification focuses on WHAT and WHY without prescribing HOW. Technical details (React, Vue, TypeScript) are mentioned only in Architecture section where they are requirements, not implementation choices.
36+
37+
✅ **PASS**: All user scenarios describe value propositions and business needs clearly.
38+
39+
✅ **PASS**: Language is accessible to database administrators, performance engineers, and product managers.
40+
41+
✅ **PASS**: All mandatory sections (User Scenarios, Requirements, Success Criteria) are complete.
42+
43+
### Requirement Completeness Review
44+
✅ **PASS**: No [NEEDS CLARIFICATION] markers present. All requirements are definitive.
45+
46+
✅ **PASS**: All 50 functional requirements are testable with clear acceptance criteria. Examples:
47+
- FR-001: Can test by providing JSON EXPLAIN output and verifying acceptance
48+
- FR-003: Can test by providing both formats and verifying auto-detection
49+
- FR-025: Can test by providing invalid data and checking error message
50+
51+
✅ **PASS**: Success criteria include specific metrics:
52+
- SC-001: "within 3 seconds" - measurable time
53+
- SC-002: "up to 1,000 nodes" - measurable capacity
54+
- SC-008: "under 2MB" - measurable size
55+
56+
✅ **PASS**: Success criteria avoid implementation language:
57+
- Good: "Users can identify the most expensive query operation within 10 seconds"
58+
- Good: "Panel correctly renders execution plans"
59+
- Avoids: API response times, database queries, framework-specific metrics
60+
61+
✅ **PASS**: All 5 user stories include detailed acceptance scenarios with Given-When-Then format.
62+
63+
✅ **PASS**: Edge cases section covers 9 specific scenarios with expected behaviors.
64+
65+
✅ **PASS**: Out of Scope section clearly defines boundaries (11 excluded items).
66+
67+
✅ **PASS**: Dependencies and Assumptions sections identify all external factors.
68+
69+
### Feature Readiness Review
70+
✅ **PASS**: Each functional requirement maps to user scenarios and success criteria.
71+
72+
✅ **PASS**: User scenarios cover all primary flows:
73+
- Core visualization (P1)
74+
- Format conversion (P2)
75+
- Data source flexibility (P1)
76+
- Configuration (P3)
77+
- Responsive behavior (P3)
78+
79+
✅ **PASS**: 10 success criteria provide comprehensive measurable outcomes covering performance, compatibility, and usability.
80+
81+
✅ **PASS**: Architecture section describes component structure without implementation specifics - focuses on layers and responsibilities rather than code organization.
82+
83+
## Overall Assessment
84+
85+
**Status**: ✅ READY FOR PLANNING
86+
87+
All quality checks pass. The specification is:
88+
- Complete and unambiguous
89+
- Focused on user value and business requirements
90+
- Free of implementation details in requirement sections
91+
- Measurable and testable
92+
- Properly scoped with clear boundaries
93+
94+
**Recommendation**: Proceed to `/speckit.plan` phase.
95+
96+
## Changelog
97+
98+
- 2025-11-24: Initial validation - All checks passed

0 commit comments

Comments
 (0)