Skip to content

Commit f405c46

Browse files
MearmanMearman
committed
docs(jsdoc): add @example tags to speckit library functions
1 parent 726ac35 commit f405c46

4 files changed

Lines changed: 204 additions & 0 deletions

File tree

‎src/speckit/generate.ts‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,10 @@ import { textToString } from "../text.js";
1212
* @param doc - The document to search.
1313
* @param id - The node ID to find.
1414
* @returns The matching node, or null.
15+
* @example
16+
* ```ts
17+
* findNode(doc, "D1")
18+
* ```
1519
*/
1620
function findNode(doc: SysProMDocument, id: string): Node | null {
1721
return doc.nodes.find((n) => n.id === id) ?? null;
@@ -22,6 +26,10 @@ function findNode(doc: SysProMDocument, id: string): Node | null {
2226
* @param doc - The document to search.
2327
* @param type - The node type to filter by.
2428
* @returns Matching nodes.
29+
* @example
30+
* ```ts
31+
* const decisions = findNodesByType(doc, "decision");
32+
* ```
2533
*/
2634
function findNodesByType(doc: SysProMDocument, type: string): Node[] {
2735
return doc.nodes.filter((n) => n.type === type);
@@ -33,6 +41,10 @@ function findNodesByType(doc: SysProMDocument, type: string): Node[] {
3341
* @param fromId - Source node ID.
3442
* @param relationType - Optional relationship type filter.
3543
* @returns Matching relationships.
44+
* @example
45+
* ```ts
46+
* const rels = findRelationshipsFrom(doc, "D1", "affects");
47+
* ```
3648
*/
3749
function findRelationshipsFrom(
3850
doc: SysProMDocument,
@@ -52,6 +64,10 @@ function findRelationshipsFrom(
5264
* @param toId - Target node ID.
5365
* @param relationType - Optional relationship type filter.
5466
* @returns Matching relationships.
67+
* @example
68+
* ```ts
69+
* const rels = findRelationshipsTo(doc, "INV1", "must_preserve");
70+
* ```
5571
*/
5672
function findRelationshipsTo(
5773
doc: SysProMDocument,
@@ -70,6 +86,10 @@ function findRelationshipsTo(
7086
* Looks for patterns like "P1", "P2", "Priority: P1", etc.
7187
* @param node - The node to extract priority from.
7288
* @returns Priority string (e.g. "P1").
89+
* @example
90+
* ```ts
91+
* const priority = extractPriority(node);
92+
* ```
7393
*/
7494
function extractPriority(node: Node): string {
7595
const text = [
@@ -88,6 +108,10 @@ function extractPriority(node: Node): string {
88108
* Extract numeric suffix from an ID (e.g., "PREFIX-SPEC-001" -> "001").
89109
* @param id - The node ID.
90110
* @returns The numeric suffix.
111+
* @example
112+
* ```ts
113+
* getIdSuffix("FEAT-SPEC-001"); // => "001"
114+
* ```
91115
*/
92116
function getIdSuffix(id: string): string {
93117
const parts = id.split("-");
@@ -98,6 +122,10 @@ function getIdSuffix(id: string): string {
98122
* Parse tasks from a change node's plan array.
99123
* @param node - The change node.
100124
* @returns Array of task descriptions and done flags.
125+
* @example
126+
* ```ts
127+
* const tasks = parseTasks(changeNode);
128+
* ```
101129
*/
102130
function parseTasks(node: Node): { description: string; done: boolean }[] {
103131
return (node.plan ?? []).map((task) => ({
@@ -110,6 +138,10 @@ function parseTasks(node: Node): { description: string; done: boolean }[] {
110138
* Format the status for spec output: "proposed" -> "Draft", etc.
111139
* @param status - The node status string.
112140
* @returns Formatted status label.
141+
* @example
142+
* ```ts
143+
* formatStatus("proposed"); // => "Draft"
144+
* ```
113145
*/
114146
function formatStatus(status?: string): string {
115147
if (!status) return "Draft";
@@ -130,6 +162,10 @@ function formatStatus(status?: string): string {
130162
* @param doc - The SysProM document.
131163
* @param prefix - ID prefix identifying nodes to include.
132164
* @returns The generated markdown.
165+
* @example
166+
* ```ts
167+
* const md = generateConstitution(doc, "FEAT");
168+
* ```
133169
*/
134170
export function generateConstitution(
135171
doc: SysProMDocument,
@@ -224,6 +260,10 @@ export function generateConstitution(
224260
* @param doc - The SysProM document.
225261
* @param prefix - ID prefix identifying nodes to include.
226262
* @returns The generated markdown.
263+
* @example
264+
* ```ts
265+
* const md = generateSpec(doc, "FEAT");
266+
* ```
227267
*/
228268
export function generateSpec(doc: SysProMDocument, prefix: string): string {
229269
const specId = `${prefix}-SPEC`;
@@ -369,6 +409,10 @@ export function generateSpec(doc: SysProMDocument, prefix: string): string {
369409
* @param doc - The SysProM document.
370410
* @param prefix - ID prefix identifying nodes to include.
371411
* @returns The generated markdown.
412+
* @example
413+
* ```ts
414+
* const md = generatePlan(doc, "FEAT");
415+
* ```
372416
*/
373417
export function generatePlan(doc: SysProMDocument, prefix: string): string {
374418
const implProtocolId = `${prefix}-PROT-IMPL`;
@@ -432,6 +476,10 @@ export function generatePlan(doc: SysProMDocument, prefix: string): string {
432476
* @param doc - The SysProM document.
433477
* @param prefix - ID prefix identifying nodes to include.
434478
* @returns The generated markdown.
479+
* @example
480+
* ```ts
481+
* const md = generateTasks(doc, "FEAT");
482+
* ```
435483
*/
436484
export function generateTasks(doc: SysProMDocument, prefix: string): string {
437485
const implProtocolId = `${prefix}-PROT-IMPL`;
@@ -627,6 +675,10 @@ export function generateTasks(doc: SysProMDocument, prefix: string): string {
627675
* @param doc - The SysProM document.
628676
* @param prefix - ID prefix identifying nodes to include.
629677
* @returns The generated markdown.
678+
* @example
679+
* ```ts
680+
* const md = generateChecklist(doc, "FEAT");
681+
* ```
630682
*/
631683
export function generateChecklist(
632684
doc: SysProMDocument,
@@ -700,6 +752,10 @@ export function generateChecklist(
700752
* @param doc - The SysProM document.
701753
* @param outputDir - Output directory path.
702754
* @param prefix - ID prefix identifying nodes to include.
755+
* @example
756+
* ```ts
757+
* generateSpecKitProject(doc, "./output", "FEAT");
758+
* ```
703759
*/
704760
export function generateSpecKitProject(
705761
doc: SysProMDocument,

‎src/speckit/parse.ts‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,10 @@ interface CheckboxItem {
4040
* Parse markdown content into a hierarchical section tree by heading level.
4141
* @param body - Markdown body text.
4242
* @returns The result.
43+
* @example
44+
* ```ts
45+
* const sections = parseSections(markdownBody);
46+
* ```
4347
*/
4448
function parseSections(body: string): Section[] {
4549
const lines = body.split("\n");
@@ -91,6 +95,10 @@ function parseSections(body: string): Section[] {
9195
* Extract bold key-value pairs from markdown like "**Key**: value" or "**Key**: value text".
9296
* @param content - Markdown file content.
9397
* @returns The result.
98+
* @example
99+
* ```ts
100+
* const meta = parseFrontMatterish(content);
101+
* ```
94102
*/
95103
function parseFrontMatterish(content: string): Record<string, string> {
96104
const result: Record<string, string> = {};
@@ -111,6 +119,10 @@ function parseFrontMatterish(content: string): Record<string, string> {
111119
* Parse checkbox lines like "- [x] ID text" or "- [ ] ID text".
112120
* @param body - Markdown body text.
113121
* @returns The result.
122+
* @example
123+
* ```ts
124+
* const items = parseCheckboxes(body);
125+
* ```
114126
*/
115127
function parseCheckboxes(body: string): CheckboxItem[] {
116128
const items: CheckboxItem[] = [];
@@ -137,6 +149,10 @@ function parseCheckboxes(body: string): CheckboxItem[] {
137149
* Flatten all sections in the tree into a single array for easier searching.
138150
* @param sections - Parsed section tree.
139151
* @returns The result.
152+
* @example
153+
* ```ts
154+
* const flat = flattenSections(sections);
155+
* ```
140156
*/
141157
function flattenSections(sections: Section[]): Section[] {
142158
const result: Section[] = [];
@@ -153,6 +169,10 @@ function flattenSections(sections: Section[]): Section[] {
153169
* @param sections - Parsed section tree.
154170
* @param predicate - Filter function.
155171
* @returns The result.
172+
* @example
173+
* ```ts
174+
* const s = findSection(sections, (h) => h.startsWith("Phase"));
175+
* ```
156176
*/
157177
function findSection(
158178
sections: Section[],
@@ -165,6 +185,10 @@ function findSection(
165185
* Convert status-like strings to NodeStatus. Recognizes common spec-kit patterns.
166186
* @param value - Raw status string.
167187
* @returns The result.
188+
* @example
189+
* ```ts
190+
* mapStatusValue("Draft"); // => "proposed"
191+
* ```
168192
*/
169193
function mapStatusValue(value: string): NodeStatus {
170194
const lower = value.toLowerCase().trim();
@@ -195,6 +219,10 @@ function mapStatusValue(value: string): NodeStatus {
195219
* @param body - Markdown body text.
196220
* @param key - Front-matter key to extract.
197221
* @returns The result.
222+
* @example
223+
* ```ts
224+
* extractValue(body, "Created"); // => "2025-01-01"
225+
* ```
198226
*/
199227
function extractValue(body: string, key: string): string | undefined {
200228
const pattern = new RegExp(`^\\*\\*${key}\\*\\*:\\s*(.+)$`, "m");
@@ -211,6 +239,10 @@ function extractValue(body: string, key: string): string | undefined {
211239
* @param content - Markdown file content.
212240
* @param idPrefix - ID prefix for generated nodes.
213241
* @returns The result.
242+
* @example
243+
* ```ts
244+
* const result = parseConstitution(content, "FEAT");
245+
* ```
214246
*/
215247
export function parseConstitution(
216248
content: string,
@@ -326,6 +358,10 @@ export function parseConstitution(
326358
* @param content - Markdown file content.
327359
* @param idPrefix - ID prefix for generated nodes.
328360
* @returns The result.
361+
* @example
362+
* ```ts
363+
* const result = parseSpec(content, "FEAT");
364+
* ```
329365
*/
330366
export function parseSpec(content: string, idPrefix: string): ParseResult {
331367
const sections = parseSections(content);
@@ -544,6 +580,10 @@ export function parseSpec(content: string, idPrefix: string): ParseResult {
544580
* @param content - Markdown file content.
545581
* @param idPrefix - ID prefix for generated nodes.
546582
* @returns The result.
583+
* @example
584+
* ```ts
585+
* const result = parsePlan(content, "FEAT");
586+
* ```
547587
*/
548588
export function parsePlan(content: string, idPrefix: string): ParseResult {
549589
const sections = parseSections(content);
@@ -655,6 +695,10 @@ export function parsePlan(content: string, idPrefix: string): ParseResult {
655695
* @param content - Markdown file content.
656696
* @param idPrefix - ID prefix for generated nodes.
657697
* @returns The result.
698+
* @example
699+
* ```ts
700+
* const result = parseTasks(content, "FEAT");
701+
* ```
658702
*/
659703
export function parseTasks(content: string, idPrefix: string): ParseResult {
660704
const sections = parseSections(content);
@@ -787,6 +831,10 @@ export function parseTasks(content: string, idPrefix: string): ParseResult {
787831
* @param content - Markdown file content.
788832
* @param idPrefix - ID prefix for generated nodes.
789833
* @returns The result.
834+
* @example
835+
* ```ts
836+
* const result = parseChecklist(content, "FEAT");
837+
* ```
790838
*/
791839
export function parseChecklist(content: string, idPrefix: string): ParseResult {
792840
const sections = parseSections(content);
@@ -854,6 +902,10 @@ export function parseChecklist(content: string, idPrefix: string): ParseResult {
854902
* @param idPrefix - ID prefix for generated nodes.
855903
* @param constitutionPath - Path to constitution.md, or undefined.
856904
* @returns The parsed SysProM document.
905+
* @example
906+
* ```ts
907+
* const doc = parseSpecKitFeature("./features/auth", "AUTH");
908+
* ```
857909
*/
858910
export function parseSpecKitFeature(
859911
featureDir: string,

0 commit comments

Comments
 (0)