Skip to content

Commit 06b71d4

Browse files
remarkablemarkremarkablemark
committed
docs(specify): ratify constitution v1.0.0 for React diff checker app
1 parent 17bf813 commit 06b71d4

20 files changed

Lines changed: 3556 additions & 0 deletions

‎.specify/memory/constitution.md‎

Lines changed: 151 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,151 @@
1+
<!--
2+
Sync Impact Report
3+
==================
4+
Version change: N/A → 1.0.0 (initial ratification)
5+
Modified principles: N/A (all new)
6+
Added sections:
7+
- Core Principles (5 principles)
8+
- Technology Constraints
9+
- Development Workflow
10+
- Governance
11+
Removed sections: N/A
12+
Templates requiring updates:
13+
- .specify/templates/plan-template.md ✅ aligned (Constitution Check section present)
14+
- .specify/templates/spec-template.md ✅ aligned (mandatory sections match principles)
15+
- .specify/templates/tasks-template.md ✅ aligned (test-first ordering present)
16+
- .specify/templates/checklist-template.md ✅ aligned (generic structure)
17+
Follow-up TODOs: None
18+
-->
19+
20+
# Diff Constitution
21+
22+
## Core Principles
23+
24+
### I. Client-Side Only
25+
26+
All logic MUST execute in the browser. This application is a static
27+
single-page React app with zero backend dependencies. No server-side
28+
processing, no API calls, and no external data persistence are permitted.
29+
Build output MUST be deployable to any static hosting provider.
30+
31+
**Rationale**: A diff checker is a developer utility that operates on
32+
user-provided text. Keeping it client-side ensures privacy (no data
33+
leaves the browser), eliminates infrastructure costs, and enables
34+
offline use after initial load.
35+
36+
### II. Full Test Coverage (NON-NEGOTIABLE)
37+
38+
Every component, utility, and feature MUST have 100% test coverage
39+
across statements, branches, functions, and lines. Tests MUST use
40+
Testing Library with user-event for interaction simulation. Vitest
41+
globals are the test runner. No code merges with failing tests or
42+
coverage below 100%.
43+
44+
**Rationale**: The AGENTS.md contract and CI pipeline (`npm run test:ci`)
45+
enforce 100% coverage. This is a hard gate — not aspirational.
46+
47+
### III. Accessibility First
48+
49+
All interactive elements MUST be keyboard-navigable and screen-reader
50+
compatible. Semantic HTML elements MUST be used (button, main, nav,
51+
textarea, label). ARIA attributes MUST be applied where semantic HTML
52+
alone is insufficient. Color MUST NOT be the sole means of conveying
53+
diff information.
54+
55+
**Rationale**: A diff checker is a developer tool used by people with
56+
diverse abilities. Accessibility is a functional requirement, not a
57+
polish item.
58+
59+
### IV. Type Safety
60+
61+
TypeScript strict mode MUST be enabled with no escape hatches. All
62+
component props MUST be defined with explicit interfaces. No `any`
63+
types are permitted. Type checking (`npm run lint:tsc`) MUST pass
64+
before any merge.
65+
66+
**Rationale**: Strict typing catches diff-logic edge cases at compile
67+
time (empty inputs, mismatched line counts, encoding issues) and
68+
serves as living documentation for component contracts.
69+
70+
### V. Simplicity and Performance
71+
72+
Start with the simplest implementation that satisfies requirements.
73+
No premature abstractions, no state management libraries unless
74+
justified by measured complexity. Components MUST remain small and
75+
focused. Tailwind CSS is the sole styling approach — no custom CSS
76+
files unless explicitly justified. Bundle size MUST remain minimal
77+
for fast initial load.
78+
79+
**Rationale**: A diff checker has a bounded feature set. YAGNI
80+
applies aggressively. Users expect instant interaction with pasted
81+
text — unnecessary complexity degrades both DX and UX.
82+
83+
## Technology Constraints
84+
85+
The following stack is fixed and MUST NOT be changed without a
86+
constitution amendment:
87+
88+
- **UI Library**: React 19 (functional components only, React Compiler enabled)
89+
- **Language**: TypeScript 5 (strict mode)
90+
- **Build Tool**: Vite 7
91+
- **Test Framework**: Vitest 4 with @testing-library/react and @testing-library/user-event
92+
- **Styling**: Tailwind CSS 4 (utility classes only)
93+
- **Linting**: ESLint 9 with typescript-eslint, simple-import-sort, react-hooks, tsdoc
94+
- **Formatting**: Prettier with Tailwind plugin
95+
- **Node**: 24 (per .nvmrc)
96+
- **Module System**: ESM only (`"type": "module"`)
97+
98+
Adding new runtime dependencies MUST be justified against the
99+
Simplicity principle. Dev dependencies for tooling are permitted
100+
with less scrutiny.
101+
102+
## Development Workflow
103+
104+
All code changes MUST pass these quality gates before merge:
105+
106+
1. **Lint**: `npm run lint` — zero errors, zero warnings
107+
2. **Type Check**: `npm run lint:tsc` — zero errors
108+
3. **Tests**: `npm run test:ci` — all pass with 100% coverage
109+
4. **Build**: `npm run build` — clean production build
110+
111+
Commit messages MUST follow Conventional Commits (enforced by
112+
commitlint via Husky pre-commit hooks). lint-staged runs on
113+
every commit to enforce formatting and linting on staged files.
114+
115+
Import order MUST follow simple-import-sort convention:
116+
117+
1. External libraries
118+
2. Internal absolute imports (`src/`)
119+
3. Relative imports
120+
121+
File organization MUST follow the established pattern:
122+
123+
```
124+
src/components/ComponentName/
125+
├── ComponentName.tsx
126+
├── ComponentName.types.ts (if needed)
127+
├── ComponentName.test.tsx
128+
└── index.ts
129+
```
130+
131+
## Governance
132+
133+
This constitution supersedes all ad-hoc practices. Every pull
134+
request and code review MUST verify compliance with these
135+
principles. Violations MUST be documented and justified in the
136+
PR description — unjustified violations block merge.
137+
138+
Amendments to this constitution require:
139+
140+
1. A documented rationale for the change
141+
2. An updated version number following semver (MAJOR for
142+
principle removals/redefinitions, MINOR for additions,
143+
PATCH for clarifications)
144+
3. An updated Sync Impact Report (HTML comment at top of file)
145+
4. Propagation of changes to dependent templates
146+
147+
Runtime development guidance is maintained in `AGENTS.md` at the
148+
repository root. The constitution defines principles; AGENTS.md
149+
provides tactical instructions for AI-assisted development.
150+
151+
**Version**: 1.0.0 | **Ratified**: 2026-02-07 | **Last Amended**: 2026-02-07

‎.specify/scripts/bash/check-prerequisites.sh‎

Lines changed: 166 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,166 @@
1+
#!/usr/bin/env bash
2+
3+
# Consolidated prerequisite checking script
4+
#
5+
# This script provides unified prerequisite checking for Spec-Driven Development workflow.
6+
# It replaces the functionality previously spread across multiple scripts.
7+
#
8+
# Usage: ./check-prerequisites.sh [OPTIONS]
9+
#
10+
# OPTIONS:
11+
# --json Output in JSON format
12+
# --require-tasks Require tasks.md to exist (for implementation phase)
13+
# --include-tasks Include tasks.md in AVAILABLE_DOCS list
14+
# --paths-only Only output path variables (no validation)
15+
# --help, -h Show help message
16+
#
17+
# OUTPUTS:
18+
# JSON mode: {"FEATURE_DIR":"...", "AVAILABLE_DOCS":["..."]}
19+
# Text mode: FEATURE_DIR:... \n AVAILABLE_DOCS: \n ✓/✗ file.md
20+
# Paths only: REPO_ROOT: ... \n BRANCH: ... \n FEATURE_DIR: ... etc.
21+
22+
set -e
23+
24+
# Parse command line arguments
25+
JSON_MODE=false
26+
REQUIRE_TASKS=false
27+
INCLUDE_TASKS=false
28+
PATHS_ONLY=false
29+
30+
for arg in "$@"; do
31+
case "$arg" in
32+
--json)
33+
JSON_MODE=true
34+
;;
35+
--require-tasks)
36+
REQUIRE_TASKS=true
37+
;;
38+
--include-tasks)
39+
INCLUDE_TASKS=true
40+
;;
41+
--paths-only)
42+
PATHS_ONLY=true
43+
;;
44+
--help|-h)
45+
cat << 'EOF'
46+
Usage: check-prerequisites.sh [OPTIONS]
47+
48+
Consolidated prerequisite checking for Spec-Driven Development workflow.
49+
50+
OPTIONS:
51+
--json Output in JSON format
52+
--require-tasks Require tasks.md to exist (for implementation phase)
53+
--include-tasks Include tasks.md in AVAILABLE_DOCS list
54+
--paths-only Only output path variables (no prerequisite validation)
55+
--help, -h Show this help message
56+
57+
EXAMPLES:
58+
# Check task prerequisites (plan.md required)
59+
./check-prerequisites.sh --json
60+
61+
# Check implementation prerequisites (plan.md + tasks.md required)
62+
./check-prerequisites.sh --json --require-tasks --include-tasks
63+
64+
# Get feature paths only (no validation)
65+
./check-prerequisites.sh --paths-only
66+
67+
EOF
68+
exit 0
69+
;;
70+
*)
71+
echo "ERROR: Unknown option '$arg'. Use --help for usage information." >&2
72+
exit 1
73+
;;
74+
esac
75+
done
76+
77+
# Source common functions
78+
SCRIPT_DIR="$(CDPATH="" cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
79+
source "$SCRIPT_DIR/common.sh"
80+
81+
# Get feature paths and validate branch
82+
eval $(get_feature_paths)
83+
check_feature_branch "$CURRENT_BRANCH" "$HAS_GIT" || exit 1
84+
85+
# If paths-only mode, output paths and exit (support JSON + paths-only combined)
86+
if $PATHS_ONLY; then
87+
if $JSON_MODE; then
88+
# Minimal JSON paths payload (no validation performed)
89+
printf '{"REPO_ROOT":"%s","BRANCH":"%s","FEATURE_DIR":"%s","FEATURE_SPEC":"%s","IMPL_PLAN":"%s","TASKS":"%s"}\n' \
90+
"$REPO_ROOT" "$CURRENT_BRANCH" "$FEATURE_DIR" "$FEATURE_SPEC" "$IMPL_PLAN" "$TASKS"
91+
else
92+
echo "REPO_ROOT: $REPO_ROOT"
93+
echo "BRANCH: $CURRENT_BRANCH"
94+
echo "FEATURE_DIR: $FEATURE_DIR"
95+
echo "FEATURE_SPEC: $FEATURE_SPEC"
96+
echo "IMPL_PLAN: $IMPL_PLAN"
97+
echo "TASKS: $TASKS"
98+
fi
99+
exit 0
100+
fi
101+
102+
# Validate required directories and files
103+
if [[ ! -d "$FEATURE_DIR" ]]; then
104+
echo "ERROR: Feature directory not found: $FEATURE_DIR" >&2
105+
echo "Run /speckit.specify first to create the feature structure." >&2
106+
exit 1
107+
fi
108+
109+
if [[ ! -f "$IMPL_PLAN" ]]; then
110+
echo "ERROR: plan.md not found in $FEATURE_DIR" >&2
111+
echo "Run /speckit.plan first to create the implementation plan." >&2
112+
exit 1
113+
fi
114+
115+
# Check for tasks.md if required
116+
if $REQUIRE_TASKS && [[ ! -f "$TASKS" ]]; then
117+
echo "ERROR: tasks.md not found in $FEATURE_DIR" >&2
118+
echo "Run /speckit.tasks first to create the task list." >&2
119+
exit 1
120+
fi
121+
122+
# Build list of available documents
123+
docs=()
124+
125+
# Always check these optional docs
126+
[[ -f "$RESEARCH" ]] && docs+=("research.md")
127+
[[ -f "$DATA_MODEL" ]] && docs+=("data-model.md")
128+
129+
# Check contracts directory (only if it exists and has files)
130+
if [[ -d "$CONTRACTS_DIR" ]] && [[ -n "$(ls -A "$CONTRACTS_DIR" 2>/dev/null)" ]]; then
131+
docs+=("contracts/")
132+
fi
133+
134+
[[ -f "$QUICKSTART" ]] && docs+=("quickstart.md")
135+
136+
# Include tasks.md if requested and it exists
137+
if $INCLUDE_TASKS && [[ -f "$TASKS" ]]; then
138+
docs+=("tasks.md")
139+
fi
140+
141+
# Output results
142+
if $JSON_MODE; then
143+
# Build JSON array of documents
144+
if [[ ${#docs[@]} -eq 0 ]]; then
145+
json_docs="[]"
146+
else
147+
json_docs=$(printf '"%s",' "${docs[@]}")
148+
json_docs="[${json_docs%,}]"
149+
fi
150+
151+
printf '{"FEATURE_DIR":"%s","AVAILABLE_DOCS":%s}\n' "$FEATURE_DIR" "$json_docs"
152+
else
153+
# Text output
154+
echo "FEATURE_DIR:$FEATURE_DIR"
155+
echo "AVAILABLE_DOCS:"
156+
157+
# Show status of each potential document
158+
check_file "$RESEARCH" "research.md"
159+
check_file "$DATA_MODEL" "data-model.md"
160+
check_dir "$CONTRACTS_DIR" "contracts/"
161+
check_file "$QUICKSTART" "quickstart.md"
162+
163+
if $INCLUDE_TASKS; then
164+
check_file "$TASKS" "tasks.md"
165+
fi
166+
fi

0 commit comments

Comments
 (0)