pi-usereq 0.36.0 → 0.37.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +552 -546
- package/README.md +260 -421
- package/package.json +46 -46
package/README.md
CHANGED
|
@@ -1,421 +1,260 @@
|
|
|
1
|
-
# PI-useReq/pi-usereq (0.
|
|
2
|
-
|
|
3
|
-
<p align="center">
|
|
4
|
-
<img src="https://img.shields.io/badge/
|
|
5
|
-
<img src="https://img.shields.io/badge/
|
|
6
|
-
<img src="https://img.shields.io/badge/
|
|
7
|
-
<img src="https://img.shields.io/badge/
|
|
8
|
-
|
|
9
|
-
</p>
|
|
10
|
-
|
|
11
|
-
<p align="center">
|
|
12
|
-
<strong>
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
</p>
|
|
16
|
-
|
|
17
|
-
<p align="center">
|
|
18
|
-
<a href="#quick-start">Quick Start</a> |
|
|
19
|
-
<a href="#feature-highlights">Feature Highlights</a> |
|
|
20
|
-
<a href="#
|
|
21
|
-
<a href="#default-workflow">Default Workflow</a> |
|
|
22
|
-
<a href="#
|
|
23
|
-
<a href="#
|
|
24
|
-
<a href="#
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
<
|
|
29
|
-
<br>
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
## Requirements
|
|
36
|
-
|
|
37
|
-
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
-
|
|
158
|
-
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
-
|
|
188
|
-
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
-
|
|
194
|
-
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
-
|
|
200
|
-
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
-
|
|
217
|
-
-
|
|
218
|
-
-
|
|
219
|
-
-
|
|
220
|
-
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
-
|
|
243
|
-
-
|
|
244
|
-
|
|
245
|
-
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
npm run cli -- --enable-static-check "Python=Command,ruff,check" --here --static-check
|
|
262
|
-
```
|
|
263
|
-
|
|
264
|
-
Supported top-level CLI switches include:
|
|
265
|
-
|
|
266
|
-
- `--base <path>`
|
|
267
|
-
- `--here`
|
|
268
|
-
- `--verbose`
|
|
269
|
-
- `--enable-line-numbers`
|
|
270
|
-
- `--enable-static-check LANG=Command,CMD[,PARAM...]` (repeatable)
|
|
271
|
-
- `--files-tokens FILE...`
|
|
272
|
-
- `--files-summarize FILE...`
|
|
273
|
-
- `--files-compress FILE...`
|
|
274
|
-
- `--files-find TAG PATTERN FILE...`
|
|
275
|
-
- `--summarize`
|
|
276
|
-
- `--compress`
|
|
277
|
-
- `--find TAG PATTERN`
|
|
278
|
-
- `--tokens`
|
|
279
|
-
- `--files-static-check FILE...`
|
|
280
|
-
- `--static-check`
|
|
281
|
-
- `--test-static-check dummy ...`
|
|
282
|
-
- `--test-static-check command <cmd> ...`
|
|
283
|
-
|
|
284
|
-
CLI naming note: the standalone CLI uses <code>--files-find</code> / <code>--find</code>, while the extension tool surface uses <code>files-search</code> / <code>search</code>.
|
|
285
|
-
|
|
286
|
-
### Offline debug utilities
|
|
287
|
-
|
|
288
|
-
#### `scripts/pi-usereq-debug.sh`
|
|
289
|
-
|
|
290
|
-
The bash wrapper provides convenience subcommands for offline extension replay:
|
|
291
|
-
|
|
292
|
-
- `inspect`
|
|
293
|
-
- `session`
|
|
294
|
-
- `command <name>`
|
|
295
|
-
- `prompt <name>`
|
|
296
|
-
- `tool <name>`
|
|
297
|
-
- `sdk`
|
|
298
|
-
- `raw ...`
|
|
299
|
-
|
|
300
|
-
Examples:
|
|
301
|
-
|
|
302
|
-
```bash
|
|
303
|
-
./scripts/pi-usereq-debug.sh inspect --format pretty
|
|
304
|
-
./scripts/pi-usereq-debug.sh session --format json
|
|
305
|
-
./scripts/pi-usereq-debug.sh prompt analyze --args "Inspect prompt rendering"
|
|
306
|
-
./scripts/pi-usereq-debug.sh tool files-search --args 'FUNCTION ^run src/index.ts --enable-line-numbers'
|
|
307
|
-
```
|
|
308
|
-
|
|
309
|
-
#### `scripts/debug-extension.ts`
|
|
310
|
-
|
|
311
|
-
The lower-level TypeScript harness supports:
|
|
312
|
-
|
|
313
|
-
- `inspect`
|
|
314
|
-
- `session-start`
|
|
315
|
-
- `command`
|
|
316
|
-
- `tool`
|
|
317
|
-
- `sdk-smoke`
|
|
318
|
-
|
|
319
|
-
It accepts `--cwd`, `--extension`, `--format`, `--name`, `--args`, `--params`, `--event-payload`, `--select`, and `--input`.
|
|
320
|
-
|
|
321
|
-
## Extension Side Features
|
|
322
|
-
|
|
323
|
-
### Configuration UI
|
|
324
|
-
|
|
325
|
-
`/pi-usereq` exposes these top-level controls:
|
|
326
|
-
|
|
327
|
-
- `Document directory`
|
|
328
|
-
- `Source-code directories`
|
|
329
|
-
- `Unit tests directory`
|
|
330
|
-
- `Auto git commit`
|
|
331
|
-
- `Git worktree`
|
|
332
|
-
- `Worktree prefix`
|
|
333
|
-
- `Language static code checkers`
|
|
334
|
-
- `Enable tools`
|
|
335
|
-
- `Notifications`
|
|
336
|
-
- `Debug`
|
|
337
|
-
- `Show local configuration`
|
|
338
|
-
- `Show global configuration`
|
|
339
|
-
- `Reset defaults`
|
|
340
|
-
|
|
341
|
-
Configuration persistence is split across:
|
|
342
|
-
|
|
343
|
-
- local project file: `.pi-usereq.json`
|
|
344
|
-
- global file: `~/.config/pi-usereq/config.json`
|
|
345
|
-
|
|
346
|
-
### Status footer
|
|
347
|
-
|
|
348
|
-
The extension status line renders:
|
|
349
|
-
|
|
350
|
-
- extension name and version
|
|
351
|
-
- workflow state
|
|
352
|
-
- current Git branch
|
|
353
|
-
- context-usage gauge
|
|
354
|
-
- elapsed timing fields
|
|
355
|
-
- active runtime sound level
|
|
356
|
-
|
|
357
|
-
### Sound
|
|
358
|
-
|
|
359
|
-
Notification sound behavior is user-visible in two separate ways:
|
|
360
|
-
|
|
361
|
-
- <strong>Persisted boot sound level</strong>: configurable in `Notifications` as `none`, `low`, `mid`, or `high`
|
|
362
|
-
- <strong>Active runtime sound level</strong>: cycled at runtime with the configured shortcut
|
|
363
|
-
|
|
364
|
-
Default sound-toggle shortcut:
|
|
365
|
-
|
|
366
|
-
```text
|
|
367
|
-
alt+s
|
|
368
|
-
```
|
|
369
|
-
|
|
370
|
-
Cycle order:
|
|
371
|
-
|
|
372
|
-
```text
|
|
373
|
-
none -> low -> mid -> high -> none
|
|
374
|
-
```
|
|
375
|
-
|
|
376
|
-
Changing the shortcut updates configuration immediately, but the extension asks you to run `/reload` before the new binding is applied.
|
|
377
|
-
|
|
378
|
-
### Notifications
|
|
379
|
-
|
|
380
|
-
The Notifications menu manages three transport families:
|
|
381
|
-
|
|
382
|
-
- command notification (`notify-send` by default)
|
|
383
|
-
- sound notification (`paplay` commands by default)
|
|
384
|
-
- Pushover delivery
|
|
385
|
-
|
|
386
|
-
Each transport has completed/interrupted/failed event toggles.
|
|
387
|
-
|
|
388
|
-
Pushover behavior:
|
|
389
|
-
|
|
390
|
-
- stays disabled until both credential fields are populated
|
|
391
|
-
- exposes priority `Normal` or `High`
|
|
392
|
-
- exposes configurable title/text templates
|
|
393
|
-
- supports escaped control-sequence editing for the text field
|
|
394
|
-
|
|
395
|
-
Default templates:
|
|
396
|
-
|
|
397
|
-
```text
|
|
398
|
-
Pushover title: %%PROMT%% @ %%BASE%% [%%TIME%%]
|
|
399
|
-
Pushover text : %%RESULT%%\n%%ARGS%%
|
|
400
|
-
```
|
|
401
|
-
|
|
402
|
-
## Note on Git usage
|
|
403
|
-
|
|
404
|
-
pi-usereq owns visible Git behavior for prompt-backed workflows and for the dedicated direct commands.
|
|
405
|
-
|
|
406
|
-
- Prompt-backed `/req-*` workflows validate that the current project is inside a Git repository.
|
|
407
|
-
- Prompt-backed workflows can use generated worktrees when:
|
|
408
|
-
- `Auto git commit` is `enable`
|
|
409
|
-
- `Git worktree` is `enable`
|
|
410
|
-
- If `Auto git commit` is disabled, effective worktree usage is forced to `disable`.
|
|
411
|
-
- Generated worktree names use the configurable `Worktree prefix` (`PI-useReq-` by default).
|
|
412
|
-
- `/req-references` does <strong>not</strong> create a worktree; it writes `REFERENCES.md`, stages only that file, commits it, and verifies the repository is clean afterward.
|
|
413
|
-
- `/req-reset` removes generated worktrees and matching branches and restores the original base-path when prompt recovery data is available.
|
|
414
|
-
- The extension status footer exposes workflow-state transitions while these Git-backed flows run.
|
|
415
|
-
|
|
416
|
-
Practical guidance:
|
|
417
|
-
|
|
418
|
-
- Start from the intended repository and branch.
|
|
419
|
-
- Keep the working tree clean before launching mutation workflows.
|
|
420
|
-
- Review generated changes before relying on the resulting commit history.
|
|
421
|
-
- Use `/req-reset` if a worktree-backed run leaves recoverable state behind.
|
|
1
|
+
# PI-useReq/pi-usereq (0.37.0)
|
|
2
|
+
|
|
3
|
+
<p align="center">
|
|
4
|
+
<img src="https://img.shields.io/badge/python-3.11%2B-3776AB?style=flat-square&logo=python&logoColor=white" alt="Python 3.11+">
|
|
5
|
+
<img src="https://img.shields.io/badge/license-GPL--3.0-491?style=flat-square" alt="License: GPL-3.0">
|
|
6
|
+
<img src="https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-6A7EC2?style=flat-square&logo=terminal&logoColor=white" alt="Platforms">
|
|
7
|
+
<img src="https://img.shields.io/badge/docs-live-b31b1b" alt="Docs">
|
|
8
|
+
<img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json" alt="uv">
|
|
9
|
+
</p>
|
|
10
|
+
|
|
11
|
+
<p align="center">
|
|
12
|
+
<strong>TODO: complete with one line project descrition.</strong><br>
|
|
13
|
+
TODO: complete with complete molti-line project descrition.<br>
|
|
14
|
+
This allows them to be run both as a Python package (installed as <b>req</b>, <b>usereq</b>, or <b>use-req</b>) and directly using <b>uvx</b>.
|
|
15
|
+
</p>
|
|
16
|
+
|
|
17
|
+
<p align="center">
|
|
18
|
+
<a href="#quick-start">Quick Start</a> |
|
|
19
|
+
<a href="#feature-highlights">Feature Highlights</a> |
|
|
20
|
+
<a href="#prompts-and-agents">Prompts and Agents</a> |
|
|
21
|
+
<a href="#default-workflow">Default Workflow</a> |
|
|
22
|
+
<a href="#supported-clis-agents-and-extensions">Supported CLIs, Agents, and Extensions</a> |
|
|
23
|
+
<a href="#known-issues">Known Issues</a> |
|
|
24
|
+
<a href="#legacy-mode">Legacy Mode</a>
|
|
25
|
+
</p>
|
|
26
|
+
<p align="center">
|
|
27
|
+
<br>
|
|
28
|
+
🚧 <strong>DRAFT</strong>: 👾 Alpha Development 👾 - Work in Progress 🏗️ 🚧<br>
|
|
29
|
+
⚠️ <strong>IMPORTANT NOTICE</strong>: Created itself with <a href="https://github.com/Ogekuri/PI-useReq"><strong>PI-useReq/pi-usereq</strong></a> 🤖✨ ⚠️<br>
|
|
30
|
+
<br>
|
|
31
|
+
<p>
|
|
32
|
+
|
|
33
|
+
|
|
34
|
+
|
|
35
|
+
## Requirements
|
|
36
|
+
|
|
37
|
+
- TODO: complete the bulle list with requiremets
|
|
38
|
+
|
|
39
|
+
|
|
40
|
+
## Feature Highlights
|
|
41
|
+
- TODO: complete the bulle list with feature highlights
|
|
42
|
+
|
|
43
|
+
|
|
44
|
+
## Extension Custom Commands
|
|
45
|
+
|
|
46
|
+
TODO: complete table with the extension custom commands
|
|
47
|
+
|
|
48
|
+
| Prompt | Description |
|
|
49
|
+
| --- | --- |
|
|
50
|
+
| `write` | Produce a *SRS* draft based on the User Request description |
|
|
51
|
+
| `create` | Write a *Software Requirements Specification* using the project's source code |
|
|
52
|
+
| `recreate` | Reorganize and update the *Software Requirements Specification* based on source code analysis (preserve requirement IDs) |
|
|
53
|
+
| `renumber` | Deterministically renumber requirement IDs in the *Software Requirements Specification* without changing requirement text or order |
|
|
54
|
+
| `analyze` | Produce an analysis report |
|
|
55
|
+
| `change` | Update the requirements and implement the corresponding changes |
|
|
56
|
+
| `check` | Run the requirements check |
|
|
57
|
+
| `cover` | Implement minimal changes to cover uncovered existing requirements |
|
|
58
|
+
| `fix` | Fix a defect without changing the requirements |
|
|
59
|
+
| `implement` | Implement source code from requirements (from scratch) |
|
|
60
|
+
| `new` | Implement a new requirement and the corresponding source code changes |
|
|
61
|
+
| `refactor` | Perform a refactor without changing the requirements |
|
|
62
|
+
| `readme` | Write `README.md` from user-visible implementation evidence |
|
|
63
|
+
| `req-references` | Write a `REFERENCES.md` using the project's source code |
|
|
64
|
+
| `workflow` | Write a `WORKFLOW.md` using the project's source code |
|
|
65
|
+
| `flowchart` | Write a `FLOWCHART.md` using the project's source code |
|
|
66
|
+
|
|
67
|
+
|
|
68
|
+
## Default Workflow
|
|
69
|
+
|
|
70
|
+
Click to zoom flowchart image.
|
|
71
|
+
|
|
72
|
+
[](https://raw.githubusercontent.com/Ogekuri/PI-useReq/refs/heads/master/images/flowchart-bw.svg)
|
|
73
|
+
|
|
74
|
+
|
|
75
|
+
## Project's Documentation
|
|
76
|
+
|
|
77
|
+
|
|
78
|
+
### Project's Tree
|
|
79
|
+
|
|
80
|
+
TODO: update/rewrite the project tree
|
|
81
|
+
|
|
82
|
+
```text
|
|
83
|
+
.
|
|
84
|
+
├── .req/
|
|
85
|
+
│ └── useReq/req files
|
|
86
|
+
├── docs/
|
|
87
|
+
│ ├── FLOWCHART.md
|
|
88
|
+
│ ├── REQUIREMENTS.md
|
|
89
|
+
│ ├── REFERENCES.md
|
|
90
|
+
│ └── WORKFLOW.md
|
|
91
|
+
├── guidelines/
|
|
92
|
+
│ └── User's guidelines
|
|
93
|
+
├── src/
|
|
94
|
+
│ └── Source code
|
|
95
|
+
└── tests/
|
|
96
|
+
└── Unit tests suite
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
## Install/Uninstall
|
|
100
|
+
|
|
101
|
+
### Install
|
|
102
|
+
|
|
103
|
+
TODO: complete installation istructions
|
|
104
|
+
|
|
105
|
+
Install:
|
|
106
|
+
```bash
|
|
107
|
+
pi install npm:pi-usereq
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
Or via git:
|
|
111
|
+
```bash
|
|
112
|
+
pi install git:github.com/Ogekuri/PI-useReq
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
Reload Pi.
|
|
116
|
+
|
|
117
|
+
|
|
118
|
+
### Uninstall
|
|
119
|
+
|
|
120
|
+
TODO: complete uninstall istructions
|
|
121
|
+
|
|
122
|
+
```bash
|
|
123
|
+
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
## Quick Start
|
|
127
|
+
|
|
128
|
+
TODO: complete/reeview with a quick start guide with a complete quick start guide
|
|
129
|
+
|
|
130
|
+
1. Install extension, tun pi-dev CLI
|
|
131
|
+
2. Use `/req-write` or `/req-create` to create requirements
|
|
132
|
+
3. Use `/req-implement` to implement source-code from requirements, or `/req-cover` to cover new requirements (documentation).
|
|
133
|
+
4. Use `/req-workflow`, `/req-flowchart`, and/or `/req-references` to update project's documentation.
|
|
134
|
+
5. Start to use `/req-change`, `/req-new`, and `/req-fix`.
|
|
135
|
+
|
|
136
|
+
## Extension Usage
|
|
137
|
+
|
|
138
|
+
TODO: document all extension features in details
|
|
139
|
+
|
|
140
|
+
### Extension Custom Commands
|
|
141
|
+
|
|
142
|
+
TODO: complete with the extension custom commands full documentation
|
|
143
|
+
|
|
144
|
+
### Extension Custom Tools
|
|
145
|
+
|
|
146
|
+
TODO: complete with the extension custom tools full documentasions
|
|
147
|
+
|
|
148
|
+
- Count tokens and chars for the given files
|
|
149
|
+
`files-tokens FILE [FILE ...]`
|
|
150
|
+
|
|
151
|
+
- Generate LLM summary markdown for the given files
|
|
152
|
+
`files-summarize FILE [FILE ...]`
|
|
153
|
+
|
|
154
|
+
- Generate compressed output for the given files
|
|
155
|
+
`files-compress FILE [FILE ...]`
|
|
156
|
+
|
|
157
|
+
- Find and extract specific constructs from the given files
|
|
158
|
+
`files-find TAG PATTERN FILE [FILE ...]`
|
|
159
|
+
|
|
160
|
+
- Run static analysis on the given files using tools configured in `.req/config.json`
|
|
161
|
+
`files-static-check FILE [FILE ...]`
|
|
162
|
+
|
|
163
|
+
- Count tokens and chars for canonical docs files in configured `docs-dir` (`REQUIREMENTS.md`, `WORKFLOW.md`, `REFERENCES.md`).
|
|
164
|
+
`tokens`
|
|
165
|
+
|
|
166
|
+
- Generate LLM summary markdown for source files selected by `git ls-files cached others exclude-standard` under configured `src-dir` directories.
|
|
167
|
+
`summarize`
|
|
168
|
+
|
|
169
|
+
- Generate compressed output for source files selected by `git ls-files cached others exclude-standard` under configured `src-dir` directories.
|
|
170
|
+
`compress`
|
|
171
|
+
|
|
172
|
+
- Find and extract specific constructs from source files selected by `git ls-files cached others exclude-standard` under configured `src-dir` directories.
|
|
173
|
+
`find TAG PATTERN`
|
|
174
|
+
|
|
175
|
+
- Run static analysis on source files selected by `git ls-files cached others exclude-standard` under configured `src-dir` directories (plus configured `tests-dir`, excluding `fixtures/`).
|
|
176
|
+
`static-check`
|
|
177
|
+
|
|
178
|
+
- Check repository integrity for the configured git path: clean working tree and valid HEAD.
|
|
179
|
+
`git-check`
|
|
180
|
+
|
|
181
|
+
- Check canonical docs presence in configured `docs-dir`: `REQUIREMENTS.md`, `WORKFLOW.md`, `REFERENCES.md`.
|
|
182
|
+
`docs-check`
|
|
183
|
+
|
|
184
|
+
- Create an isolated git worktree and branch with the provided name; also copies `.req/`, active provider directories, and `.venv` (when present) into the new worktree context.
|
|
185
|
+
`git-wt-create WT_NAME`
|
|
186
|
+
|
|
187
|
+
- Remove the git worktree and branch identified by name.
|
|
188
|
+
`git-wt-delete WT_NAME`
|
|
189
|
+
|
|
190
|
+
- Print the configured `git-path` value from `.req/config.json`; if `.req/config.json` is missing, the command fails with `Error: .req/config.json not found in the project root`.
|
|
191
|
+
`git-path`
|
|
192
|
+
|
|
193
|
+
- Print the configured `base-path` value from `.req/config.json`; if `.req/config.json` is missing, the command fails with `Error: .req/config.json not found in the project root`.
|
|
194
|
+
`get-base-path`
|
|
195
|
+
|
|
196
|
+
|
|
197
|
+
- Add `enable-line-numbers` to include `<n>:` prefixes in `files-compress`, `compress`, `files-find`, and `find` output.
|
|
198
|
+
|
|
199
|
+
- Test static check configuration and execution (standalone).
|
|
200
|
+
`test-static-check {dummy,pylance,ruff,command} [FILES...]`
|
|
201
|
+
|
|
202
|
+
#### Supported <TAG> in `find` commands
|
|
203
|
+
|
|
204
|
+
- **Python**: CLASS, FUNCTION, DECORATOR, IMPORT, VARIABLE
|
|
205
|
+
- **C**: STRUCT, UNION, ENUM, TYPEDEF, MACRO, FUNCTION, IMPORT, VARIABLE
|
|
206
|
+
- **C++**: CLASS, STRUCT, ENUM, NAMESPACE, FUNCTION, MACRO, IMPORT, TYPE_ALIAS
|
|
207
|
+
- **C#**: CLASS, INTERFACE, STRUCT, ENUM, NAMESPACE, FUNCTION, PROPERTY, IMPORT, DECORATOR, CONSTANT
|
|
208
|
+
- **Rust**: FUNCTION, STRUCT, ENUM, TRAIT, IMPL, MODULE, MACRO, CONSTANT, TYPE_ALIAS, IMPORT, DECORATOR
|
|
209
|
+
- **JavaScript**: CLASS, FUNCTION, COMPONENT, CONSTANT, IMPORT, MODULE
|
|
210
|
+
- **TypeScript**: INTERFACE, TYPE_ALIAS, ENUM, CLASS, FUNCTION, NAMESPACE, MODULE, IMPORT, DECORATOR
|
|
211
|
+
- **Java**: CLASS, INTERFACE, ENUM, FUNCTION, IMPORT, MODULE, DECORATOR, CONSTANT
|
|
212
|
+
- **Go**: FUNCTION, METHOD, STRUCT, INTERFACE, TYPE_ALIAS, CONSTANT, IMPORT, MODULE
|
|
213
|
+
- **Ruby**: CLASS, MODULE, FUNCTION, CONSTANT, IMPORT, DECORATOR
|
|
214
|
+
- **PHP**: CLASS, INTERFACE, TRAIT, FUNCTION, NAMESPACE, IMPORT, CONSTANT
|
|
215
|
+
- **Swift**: CLASS, STRUCT, ENUM, PROTOCOL, EXTENSION, FUNCTION, IMPORT, CONSTANT, VARIABLE
|
|
216
|
+
- **Kotlin**: CLASS, INTERFACE, ENUM, FUNCTION, CONSTANT, VARIABLE, MODULE, IMPORT, DECORATOR
|
|
217
|
+
- **Scala**: CLASS, TRAIT, MODULE, FUNCTION, CONSTANT, VARIABLE, TYPE_ALIAS, IMPORT
|
|
218
|
+
- **Lua**: FUNCTION, VARIABLE
|
|
219
|
+
- **Shell**: FUNCTION, VARIABLE, IMPORT
|
|
220
|
+
- **Perl**: FUNCTION, MODULE, IMPORT, CONSTANT
|
|
221
|
+
- **Haskell**: MODULE, TYPE_ALIAS, STRUCT, CLASS, FUNCTION, IMPORT
|
|
222
|
+
- **Zig**: FUNCTION, STRUCT, ENUM, UNION, CONSTANT, VARIABLE, IMPORT
|
|
223
|
+
- **Elixir**: MODULE, FUNCTION, PROTOCOL, IMPL, STRUCT, IMPORT
|
|
224
|
+
|
|
225
|
+
### Extension Side Features
|
|
226
|
+
|
|
227
|
+
TODO: complete with extension side defatures
|
|
228
|
+
|
|
229
|
+
#### Sound
|
|
230
|
+
|
|
231
|
+
TODO: complete with sound extension feature description
|
|
232
|
+
|
|
233
|
+
## Note on Git usage
|
|
234
|
+
|
|
235
|
+
TODO: review and rewrite git section according extension features.
|
|
236
|
+
|
|
237
|
+
This section describes the Git behavior when executing the commands provided by the scripts.
|
|
238
|
+
|
|
239
|
+
- Required state before execution:
|
|
240
|
+
- Execute commands from a working branch (not in detached HEAD).
|
|
241
|
+
- Preferably, the working tree should be clean: avoid unintended changes in the repository before starting the scripts.
|
|
242
|
+
- Save all files and verify that you are in the correct project directory.
|
|
243
|
+
- **IMPORTANT:** in clude on repository the directory configured in the extension.
|
|
244
|
+
|
|
245
|
+
- What the scripts do to the repository:
|
|
246
|
+
- The scripts may modify, create, or remove files in the working tree (files on disk).
|
|
247
|
+
- They do not modify Git history (HEAD), branches, or tags automatically.
|
|
248
|
+
- The index (staging area) and history remain unchanged until the user manually performs staging/commit operations.
|
|
249
|
+
|
|
250
|
+
- How to commit (recommended practice):
|
|
251
|
+
- Review changes generated by the scripts before including them in a commit.
|
|
252
|
+
- Manually add files to commit using `git add <file...>`.
|
|
253
|
+
- Execute the commit with a structured message, for example:
|
|
254
|
+
`git commit -m "change(<COMPONENT>): <SHORT-DESCRIPTION> [<DATE>]"`.
|
|
255
|
+
- Staging and commit operations are under the user's control; the scripts do not perform automatic commits or update Git references.
|
|
256
|
+
|
|
257
|
+
- Practical warnings:
|
|
258
|
+
- Do not use destructive commands (e.g., `git reset --hard`, `git clean -fd`) to "clean" the repository without verifying the impact.
|
|
259
|
+
- If you prefer to isolate changes, execute commands in a branch or a copy of the repository.
|
|
260
|
+
|