ai-spector 0.1.2 → 0.1.3

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.
Files changed (201) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +103 -118
  3. package/dist/cli.d.ts +3 -0
  4. package/dist/cli.d.ts.map +1 -0
  5. package/dist/cli.js +173 -0
  6. package/dist/cli.js.map +1 -0
  7. package/dist/commands/analyze.d.ts +9 -0
  8. package/dist/commands/analyze.d.ts.map +1 -0
  9. package/dist/commands/analyze.js +62 -0
  10. package/dist/commands/analyze.js.map +1 -0
  11. package/dist/commands/bootstrap.d.ts +4 -0
  12. package/dist/commands/bootstrap.d.ts.map +1 -0
  13. package/dist/commands/bootstrap.js +58 -0
  14. package/dist/commands/bootstrap.js.map +1 -0
  15. package/dist/commands/graph-impact.d.ts +10 -0
  16. package/dist/commands/graph-impact.d.ts.map +1 -0
  17. package/dist/commands/graph-impact.js +31 -0
  18. package/dist/commands/graph-impact.js.map +1 -0
  19. package/dist/commands/graph-merge.d.ts +11 -0
  20. package/dist/commands/graph-merge.d.ts.map +1 -0
  21. package/dist/commands/graph-merge.js +88 -0
  22. package/dist/commands/graph-merge.js.map +1 -0
  23. package/dist/commands/graph-query.d.ts +10 -0
  24. package/dist/commands/graph-query.d.ts.map +1 -0
  25. package/dist/commands/graph-query.js +31 -0
  26. package/dist/commands/graph-query.js.map +1 -0
  27. package/dist/commands/graph-visualize.d.ts +10 -0
  28. package/dist/commands/graph-visualize.d.ts.map +1 -0
  29. package/dist/commands/graph-visualize.js +72 -0
  30. package/dist/commands/graph-visualize.js.map +1 -0
  31. package/dist/commands/init.d.ts +6 -0
  32. package/dist/commands/init.d.ts.map +1 -0
  33. package/dist/commands/init.js +47 -0
  34. package/dist/commands/init.js.map +1 -0
  35. package/dist/commands/validate.d.ts +10 -0
  36. package/dist/commands/validate.d.ts.map +1 -0
  37. package/dist/commands/validate.js +89 -0
  38. package/dist/commands/validate.js.map +1 -0
  39. package/dist/config/load.d.ts +21 -0
  40. package/dist/config/load.d.ts.map +1 -0
  41. package/dist/config/load.js +77 -0
  42. package/dist/config/load.js.map +1 -0
  43. package/dist/config/types.d.ts +22 -0
  44. package/dist/config/types.d.ts.map +1 -0
  45. package/dist/config/types.js +2 -0
  46. package/dist/config/types.js.map +1 -0
  47. package/dist/graph/InMemoryGraph.d.ts +20 -0
  48. package/dist/graph/InMemoryGraph.d.ts.map +1 -0
  49. package/dist/graph/InMemoryGraph.js +181 -0
  50. package/dist/graph/InMemoryGraph.js.map +1 -0
  51. package/dist/graph/defaults.d.ts +10 -0
  52. package/dist/graph/defaults.d.ts.map +1 -0
  53. package/dist/graph/defaults.js +10 -0
  54. package/dist/graph/defaults.js.map +1 -0
  55. package/dist/graph/impact.d.ts +32 -0
  56. package/dist/graph/impact.d.ts.map +1 -0
  57. package/dist/graph/impact.js +88 -0
  58. package/dist/graph/impact.js.map +1 -0
  59. package/dist/graph/knowledge.d.ts +53 -0
  60. package/dist/graph/knowledge.d.ts.map +1 -0
  61. package/dist/graph/knowledge.js +79 -0
  62. package/dist/graph/knowledge.js.map +1 -0
  63. package/dist/graph/load.d.ts +4 -0
  64. package/dist/graph/load.d.ts.map +1 -0
  65. package/dist/graph/load.js +12 -0
  66. package/dist/graph/load.js.map +1 -0
  67. package/dist/graph/loadGraph.d.ts +3 -0
  68. package/dist/graph/loadGraph.d.ts.map +1 -0
  69. package/dist/graph/loadGraph.js +7 -0
  70. package/dist/graph/loadGraph.js.map +1 -0
  71. package/dist/graph/merge.d.ts +15 -0
  72. package/dist/graph/merge.d.ts.map +1 -0
  73. package/dist/graph/merge.js +63 -0
  74. package/dist/graph/merge.js.map +1 -0
  75. package/dist/graph/query.d.ts +18 -0
  76. package/dist/graph/query.d.ts.map +1 -0
  77. package/dist/graph/query.js +132 -0
  78. package/dist/graph/query.js.map +1 -0
  79. package/dist/registry/build.d.ts +3 -0
  80. package/dist/registry/build.d.ts.map +1 -0
  81. package/dist/registry/build.js +53 -0
  82. package/dist/registry/build.js.map +1 -0
  83. package/dist/registry/slug.d.ts +4 -0
  84. package/dist/registry/slug.d.ts.map +1 -0
  85. package/dist/registry/slug.js +16 -0
  86. package/dist/registry/slug.js.map +1 -0
  87. package/dist/types.d.ts +45 -0
  88. package/dist/types.d.ts.map +1 -0
  89. package/dist/types.js +2 -0
  90. package/dist/types.js.map +1 -0
  91. package/dist/util/fs.d.ts +6 -0
  92. package/dist/util/fs.d.ts.map +1 -0
  93. package/dist/util/fs.js +24 -0
  94. package/dist/util/fs.js.map +1 -0
  95. package/dist/util/paths.d.ts +16 -0
  96. package/dist/util/paths.d.ts.map +1 -0
  97. package/dist/util/paths.js +19 -0
  98. package/dist/util/paths.js.map +1 -0
  99. package/dist/visualize/html.d.ts +13 -0
  100. package/dist/visualize/html.d.ts.map +1 -0
  101. package/dist/visualize/html.js +374 -0
  102. package/dist/visualize/html.js.map +1 -0
  103. package/dist/visualize/stats.d.ts +21 -0
  104. package/dist/visualize/stats.d.ts.map +1 -0
  105. package/dist/visualize/stats.js +45 -0
  106. package/dist/visualize/stats.js.map +1 -0
  107. package/documents.json +64 -0
  108. package/package.json +52 -12
  109. package/{assets/workflow → scaffold/.ai-spector/.docflow}/config/analyze.graphify.json +10 -3
  110. package/scaffold/.ai-spector/.docflow/config/completeness-rules.basic-design.json +18 -0
  111. package/scaffold/.ai-spector/.docflow/config/dag.basic-design.json +38 -0
  112. package/{assets/workflow → scaffold/.ai-spector/.docflow}/config/dag.detail-design.json +1 -1
  113. package/{assets/workflow → scaffold/.ai-spector/.docflow}/config/dag.srs.json +1 -1
  114. package/scaffold/.ai-spector/.docflow/config/data-source.json +5 -0
  115. package/scaffold/.ai-spector/.docflow/config/index.docs.json +22 -0
  116. package/scaffold/.ai-spector/.docflow/config/workflow.dependencies.json +271 -0
  117. package/scaffold/.ai-spector/.docflow/extract/patch.example.json +20 -0
  118. package/scaffold/.ai-spector/.docflow/state.json +11 -0
  119. package/scaffold/.ai-spector/docflow.config.json +7 -0
  120. package/scaffold/.ai-spector/index/README.md +18 -0
  121. package/scaffold/.ai-spector/index/basic-design.md +5 -0
  122. package/scaffold/.ai-spector/index/srs.md +5 -0
  123. package/scaffold/.cursor/commands/_cli-failures.md +110 -0
  124. package/scaffold/.cursor/commands/_graph.md +48 -0
  125. package/scaffold/.cursor/commands/_prerequisites.md +48 -0
  126. package/scaffold/.cursor/commands/_workflow.md +50 -0
  127. package/scaffold/.cursor/commands/analyze.md +96 -0
  128. package/scaffold/.cursor/commands/generate-basic-design.md +26 -0
  129. package/scaffold/.cursor/commands/generate-detail-design.md +19 -0
  130. package/scaffold/.cursor/commands/generate-srs.md +63 -0
  131. package/scaffold/.cursor/commands/graph-impact.md +45 -0
  132. package/scaffold/.cursor/commands/index-docs.md +36 -0
  133. package/scaffold/.cursor/commands/sync-graph.md +30 -0
  134. package/scaffold/.cursor/commands/validate-graph.md +28 -0
  135. package/scaffold/.cursor/commands/visualize-graph.md +24 -0
  136. package/scaffold/.cursor/skills/ai-spector/SKILL.md +39 -0
  137. package/scaffold/docs/data-source/README.md +18 -0
  138. package/schemas/rules.impact.json +17 -0
  139. package/schemas/rules.traceability.json +30 -0
  140. package/schemas/schema.extract-patch.json +19 -0
  141. package/schemas/schema.graph.json +83 -0
  142. package/schemas/schema.knowledge.json +107 -0
  143. package/assets/cursor/commands/analyze.md +0 -39
  144. package/assets/cursor/commands/generate-detail-design.md +0 -35
  145. package/assets/cursor/commands/generate-srs.md +0 -38
  146. package/assets/cursor/skills/ai-spector/SKILL.md +0 -33
  147. package/assets/workflow/state/state.template.json +0 -26
  148. package/assets/workflow/templates/basic_design/db-design-template.md +0 -177
  149. package/assets/workflow/templates/basic_design/detail-api-template.md +0 -278
  150. package/assets/workflow/templates/basic_design/detail-screen-template.md +0 -281
  151. package/assets/workflow/templates/basic_design/list-api-template.md +0 -130
  152. package/assets/workflow/templates/basic_design/list-screen-template.md +0 -242
  153. package/assets/workflow/templates/detail_design/common/architecture-overview-template.md +0 -302
  154. package/assets/workflow/templates/detail_design/common/deployment-infrastructure-template.md +0 -461
  155. package/assets/workflow/templates/detail_design/common/error-handling-patterns-template.md +0 -460
  156. package/assets/workflow/templates/detail_design/common/integration-patterns-template.md +0 -410
  157. package/assets/workflow/templates/detail_design/common/performance-standards-template.md +0 -406
  158. package/assets/workflow/templates/detail_design/common/security-patterns-template.md +0 -395
  159. package/assets/workflow/templates/detail_design/feature-detail-design-template.md +0 -773
  160. package/assets/workflow/templates/detail_design/feature-list-template.md +0 -39
  161. package/assets/workflow/templates/srs/1-introduction.md +0 -58
  162. package/assets/workflow/templates/srs/2-overall-description.md +0 -91
  163. package/assets/workflow/templates/srs/3-use-case-detail-template.md +0 -142
  164. package/assets/workflow/templates/srs/3-use-cases.md +0 -53
  165. package/assets/workflow/templates/srs/4-system-feature-detail-template.md +0 -131
  166. package/assets/workflow/templates/srs/4-system-features-list-template.md +0 -39
  167. package/assets/workflow/templates/srs/5-data-requirements.md +0 -59
  168. package/assets/workflow/templates/srs/6-external-interfaces.md +0 -56
  169. package/assets/workflow/templates/srs/7-quality-attributes.md +0 -74
  170. package/assets/workflow/templates/srs/8-internationalization.md +0 -36
  171. package/assets/workflow/templates/srs/9-other-requirements.md +0 -46
  172. package/bin/ai-spector.js +0 -56
  173. package/bin/spec-writer.js +0 -56
  174. package/src/cli/helpers/fs.js +0 -50
  175. package/src/cli/init.js +0 -193
  176. /package/{assets/workflow → scaffold/.ai-spector/.docflow}/config/completeness-rules.detail-design.json +0 -0
  177. /package/{assets/workflow → scaffold/.ai-spector/.docflow}/config/completeness-rules.srs.json +0 -0
  178. /package/{_templates → templates}/basic_design/db-design-template.md +0 -0
  179. /package/{_templates → templates}/basic_design/detail-api-template.md +0 -0
  180. /package/{_templates → templates}/basic_design/detail-screen-template.md +0 -0
  181. /package/{_templates → templates}/basic_design/list-api-template.md +0 -0
  182. /package/{_templates → templates}/basic_design/list-screen-template.md +0 -0
  183. /package/{_templates → templates}/detail_design/common/architecture-overview-template.md +0 -0
  184. /package/{_templates → templates}/detail_design/common/deployment-infrastructure-template.md +0 -0
  185. /package/{_templates → templates}/detail_design/common/error-handling-patterns-template.md +0 -0
  186. /package/{_templates → templates}/detail_design/common/integration-patterns-template.md +0 -0
  187. /package/{_templates → templates}/detail_design/common/performance-standards-template.md +0 -0
  188. /package/{_templates → templates}/detail_design/common/security-patterns-template.md +0 -0
  189. /package/{_templates → templates}/detail_design/feature-detail-design-template.md +0 -0
  190. /package/{_templates → templates}/detail_design/feature-list-template.md +0 -0
  191. /package/{_templates → templates}/srs/1-introduction.md +0 -0
  192. /package/{_templates → templates}/srs/2-overall-description.md +0 -0
  193. /package/{_templates → templates}/srs/3-use-case-detail-template.md +0 -0
  194. /package/{_templates → templates}/srs/3-use-cases.md +0 -0
  195. /package/{_templates → templates}/srs/4-system-feature-detail-template.md +0 -0
  196. /package/{_templates → templates}/srs/4-system-features-list-template.md +0 -0
  197. /package/{_templates → templates}/srs/5-data-requirements.md +0 -0
  198. /package/{_templates → templates}/srs/6-external-interfaces.md +0 -0
  199. /package/{_templates → templates}/srs/7-quality-attributes.md +0 -0
  200. /package/{_templates → templates}/srs/8-internationalization.md +0 -0
  201. /package/{_templates → templates}/srs/9-other-requirements.md +0 -0
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 AI Spector contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,169 +1,154 @@
1
1
  # AI Spector
2
2
 
3
- AI Spector is an npm-installable bootstrapper for incremental documentation workflows in Cursor.
3
+ Turn project notes and specs into structured documentation (SRS, basic design, detail design) inside [Cursor](https://cursor.com).
4
4
 
5
- 1. Analyze project sources with Graphify MCP.
6
- 2. Generate SRS documents in dependency order.
7
- 3. Generate detail design documents in dependency order.
5
+ You work with **slash commands**. The AI runs the `ai-spector` CLI behind the scenes. You only use the terminal once: **`npx ai-spector init`**.
8
6
 
9
- It is designed for part-by-part generation with parallel subagents and merge/review loops.
7
+ ---
10
8
 
11
- ## What You Get
9
+ ## How you work (Cursor-first)
12
10
 
13
- After `init`, your project has:
14
-
15
- - Cursor commands: `/analyze`, `/generate-srs`, `/generate-detail-design`
16
- - Workflow skill + configs + state files
17
- - SRS/detail design templates
18
- - Output folders for generated docs
19
- - Graphify-backed knowledge loop for incremental generation
20
-
21
- ## Quick Start
11
+ ### Once per project
22
12
 
23
13
  ```bash
24
- # in your target project
14
+ npm install ai-spector
25
15
  npx ai-spector init
26
16
  ```
27
17
 
28
- Then in Cursor chat:
18
+ Put your source files in `docs/data-source/`, open the folder in Cursor, and turn on the **ai-spector** skill.
29
19
 
30
- 1. `/analyze` (or `/analyze src docs`)
31
- 2. `/generate-srs`
32
- 3. `/generate-detail-design`
20
+ ### Then use slash commands
33
21
 
34
- ## Init Command
22
+ | You run | What happens |
23
+ |---------|----------------|
24
+ | **`/analyze`** | Builds the graph skeleton, extracts knowledge (Graphify), merges use cases & features into the graph, validates |
25
+ | **`/visualize-graph`** | Opens a browser report to inspect the graph and `knowledge.json` |
26
+ | **`/validate-graph`** | Checks the graph before generation |
27
+ | **`/generate-srs`** | Writes SRS files using graph context (not whole-folder guessing) |
28
+ | **`/generate-basic-design`** | Basic design from the graph |
29
+ | **`/generate-detail-design`** | Detail design from the graph |
30
+ | **`/graph-impact <id>`** | Shows what to regenerate after you change something |
35
31
 
36
- ```bash
37
- ai-spector init [--force] [--no-graphify] [--skip-index] [--yes]
32
+ **Typical path:**
33
+
34
+ ```text
35
+ npx ai-spector init
36
+ → add docs/data-source/
37
+ → /analyze
38
+ → /validate-graph
39
+ → /generate-srs
38
40
  ```
39
41
 
40
- Options:
42
+ Command details live in `.cursor/commands/` after `init` (start with `_workflow.md`).
41
43
 
42
- - `--force`: overwrite existing installed assets.
43
- - `--no-graphify`: skip Graphify bootstrap.
44
- - `--skip-index`: do not run initial Graphify index.
45
- - `--yes`: non-interactive mode.
44
+ If a CLI step fails during a slash command, the agent should **stop**, show you the error, and help you fix it — not bypass the tool with manual edits. See `_cli-failures.md` in your project after `init`.
46
45
 
47
- ## Command Guide
46
+ ### Why is `docs/data-source/graphify-out/` there?
48
47
 
49
- ### `/analyze [paths...]`
48
+ That folder is from **Graphify MCP** during **`/analyze`**, not from `npx ai-spector analyze`. AI Spector’s files live under `.ai-spector/` (especially `knowledge.json` and the traceability graph). You can delete `graphify-out/`; new projects gitignore it. See `docs/data-source/README.md` after `init`.
50
49
 
51
- - No args: analyze current workspace folder.
52
- - With args: analyze only provided files/folders.
53
- - Produces:
54
- - `docs/.docflow/analysis/knowledge.json`
55
- - `docs/.docflow/analysis/gaps.json`
56
- - `docs/.docflow/analysis/scope.json`
50
+ ---
57
51
 
58
- Examples:
52
+ ## What is the graph?
59
53
 
60
- ```text
61
- /analyze
62
- /analyze src
63
- /analyze src services docs/requirements
64
- ```
54
+ All structure and traceability live in one file:
65
55
 
66
- ### `/generate-srs [file]`
56
+ `.ai-spector/graph/traceability.graph.json`
67
57
 
68
- - No file: generate all pending SRS nodes by DAG wave.
69
- - With file: generate/repair one target file.
70
- - Uses existing outputs + completeness checks before writing.
58
+ - Chapters and headings **sections** in the graph
59
+ - Use cases, features, actors **domain nodes** with links (`listedIn`, `satisfies`, …)
60
+ - Files under `docs/srs/` **output** of the graph, not the source of truth
71
61
 
72
- Examples:
62
+ **Graphify** (optional MCP) only helps read `docs/data-source/` during **`/analyze`**. The graph remains canonical.
73
63
 
74
- ```text
75
- /generate-srs
76
- /generate-srs 3-use-cases.md
77
- ```
64
+ ---
78
65
 
79
- ### `/generate-detail-design [file]`
66
+ ## Requirements
80
67
 
81
- - No file: generate all pending detail design nodes by DAG wave.
82
- - With file: generate/repair one target file.
83
- - Uses SRS outputs + Graphify context.
68
+ - Node.js 20+
69
+ - [Cursor](https://cursor.com)
70
+ - Graphify MCP for **`/analyze`**
84
71
 
85
- Examples:
72
+ ---
86
73
 
87
- ```text
88
- /generate-detail-design
89
- /generate-detail-design feature-list.md
74
+ ## Try the example in this repo
75
+
76
+ For package developers:
77
+
78
+ ```bash
79
+ git clone <repo-url>
80
+ cd ai-spector
81
+ npm install && npm run build
82
+ npm run init:example
90
83
  ```
91
84
 
92
- ## Continue From Existing Files (Default Behavior)
85
+ Open **`example/`** as the Cursor workspace, add files under `example/docs/data-source/`, then run **`/analyze`** → **`/generate-srs`**.
93
86
 
94
- Generation commands always scan existing outputs first and classify files as:
87
+ See [example/README.md](example/README.md).
95
88
 
96
- - `good`
97
- - `missing_content`
98
- - `missing_file`
89
+ ---
99
90
 
100
- Default behavior:
91
+ ## Project layout (after init)
101
92
 
102
- - keep `good` files unchanged
103
- - patch `missing_content`
104
- - create `missing_file`
93
+ ```text
94
+ your-project/
95
+ .cursor/commands/ # /analyze, /generate-srs,
96
+ .cursor/skills/ai-spector/
97
+ .ai-spector/
98
+ graph/traceability.graph.json
99
+ .docflow/analysis/knowledge.json
100
+ views/graph-knowledge.html # after /visualize-graph
101
+ docs/
102
+ data-source/ # your inputs
103
+ srs/ # generated
104
+ ```
105
105
 
106
- After each generated or patched file, content is synced back to Graphify so later files can use updated context.
106
+ ---
107
107
 
108
- ## Dependency Waves
108
+ ## For developers & contributors
109
109
 
110
- SRS and detail design are generated in dependency order. Independent nodes in the same wave can run in parallel, then main agent merges/reviews before moving to the next wave.
110
+ The CLI is the engine; Cursor commands wrap it.
111
111
 
112
- ## Publish to npm
112
+ | Doc | Topic |
113
+ |-----|--------|
114
+ | [workflow-overview.md](docs/design/workflow-overview.md) | Graph-centric design |
115
+ | [traceability-graph-redesign.md](docs/design/traceability-graph-redesign.md) | Schema and roadmap |
113
116
 
114
- From this package repo:
117
+ **Build from source:**
115
118
 
116
119
  ```bash
117
- npm login
118
- npm whoami
119
- chmod +x bin/ai-spector.js
120
- npm pack --dry-run
121
- npm publish --access public
120
+ npm install && npm run build
121
+ npm run init:example
122
122
  ```
123
123
 
124
- For next releases:
124
+ **CLI reference** (normally invoked by agents, not end users):
125
+
126
+ | Command | Purpose |
127
+ |---------|---------|
128
+ | `ai-spector init` | Scaffold project |
129
+ | `ai-spector analyze` | Section tree in graph |
130
+ | `ai-spector graph merge --from-knowledge` | Domain nodes from staging |
131
+ | `ai-spector graph validate` | Rules check |
132
+ | `ai-spector graph visualize [--open]` | HTML report |
133
+ | `ai-spector graph query <id> --json` | Context for generation |
134
+ | `ai-spector graph impact <id> --json` | Regen scope |
135
+
136
+ Option: `-r <path>` to point at another project root.
137
+
138
+ ---
139
+
140
+ ## Publish to npm (maintainers)
125
141
 
126
142
  ```bash
127
- npm version patch
143
+ npm run prepublish:check # build + list tarball contents
144
+ npm login
128
145
  npm publish
129
146
  ```
130
147
 
131
- ## Installed Project Structure
148
+ Replace `milky-way-66/ai-spector` in `package.json` (`repository`, `homepage`, `bugs`) before publishing. See [PUBLISHING.md](PUBLISHING.md).
132
149
 
133
- ```text
134
- .cursor/
135
- commands/
136
- analyze.md
137
- generate-srs.md
138
- generate-detail-design.md
139
- skills/
140
- ai-spector/
141
- SKILL.md
142
-
143
- docs/
144
- _templates/
145
- srs/
146
- detail_design/
147
- basic_design/
148
- .docflow/
149
- graph/
150
- graphify-index/
151
- analysis/
152
- knowledge.json
153
- gaps.json
154
- scope.json
155
- partials/
156
- srs/
157
- detail-design/
158
- logs/
159
- config/
160
- dag.srs.json
161
- dag.detail-design.json
162
- analyze.graphify.json
163
- completeness-rules.srs.json
164
- completeness-rules.detail-design.json
165
- state.json
166
- output/
167
- srs/
168
- detail-design/
169
- ```
150
+ ---
151
+
152
+ ## License
153
+
154
+ MIT — see [LICENSE](LICENSE).
package/dist/cli.d.ts ADDED
@@ -0,0 +1,3 @@
1
+ #!/usr/bin/env node
2
+ export {};
3
+ //# sourceMappingURL=cli.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}
package/dist/cli.js ADDED
@@ -0,0 +1,173 @@
1
+ #!/usr/bin/env node
2
+ import { Command } from "commander";
3
+ import { resolve } from "node:path";
4
+ import { writeJson, readJson } from "./util/fs.js";
5
+ import { resolveProjectPaths } from "./util/paths.js";
6
+ import { buildSectionRegistry } from "./registry/build.js";
7
+ import { bootstrapFromRegistry } from "./commands/bootstrap.js";
8
+ import { validateGraph, formatIssues } from "./commands/validate.js";
9
+ import { runInit } from "./commands/init.js";
10
+ import { runAnalyzePrep } from "./commands/analyze.js";
11
+ import { runGraphQuery } from "./commands/graph-query.js";
12
+ import { runGraphImpact } from "./commands/graph-impact.js";
13
+ import { runGraphMerge } from "./commands/graph-merge.js";
14
+ import { runGraphVisualize } from "./commands/graph-visualize.js";
15
+ const program = new Command();
16
+ program
17
+ .name("ai-spector")
18
+ .description("AI Spector — init project, analyze prep, traceability graph, templates, Cursor workflow")
19
+ .version("0.1.0")
20
+ .option("-r, --root <path>", "Project root (auto-detect via .ai-spector/docflow.config.json)");
21
+ function projectRootOpt(cmd) {
22
+ return cmd.optsWithGlobals().root;
23
+ }
24
+ async function getPaths(cmd) {
25
+ return resolveProjectPaths(projectRootOpt(cmd));
26
+ }
27
+ program
28
+ .command("init")
29
+ .description("Scaffold .ai-spector, Cursor commands/skills, and docs layout")
30
+ .option("-f, --force", "Overwrite existing scaffold files")
31
+ .option("-C, --cwd <path>", "Target directory", process.cwd())
32
+ .action(async (opts) => {
33
+ await runInit({
34
+ targetDir: resolve(opts.cwd ?? process.cwd()),
35
+ force: opts.force,
36
+ });
37
+ });
38
+ program
39
+ .command("analyze")
40
+ .description("Prepare graph structure (registry + bootstrap). Normally invoked by /analyze, not the user.")
41
+ .option("--merge", "After prep, merge knowledge.json or extract/patch.json into the graph if present")
42
+ .action(async (opts, cmd) => {
43
+ await runAnalyzePrep(projectRootOpt(cmd), { merge: opts.merge });
44
+ });
45
+ const graph = program.command("graph").description("Traceability graph operations");
46
+ graph
47
+ .command("registry")
48
+ .description("Build section-registry.json from bundled SRS templates")
49
+ .action(async (_opts, cmd) => {
50
+ const paths = await getPaths(cmd);
51
+ const registry = await buildSectionRegistry(paths.root);
52
+ await writeJson(paths.registry, registry);
53
+ const total = registry.documents.reduce((n, d) => n + d.sections.length, 0);
54
+ console.log(`Wrote ${paths.registry} (${registry.documents.length} documents, ${total} sections)`);
55
+ });
56
+ graph
57
+ .command("bootstrap")
58
+ .description("Create structure nodes/edges from section registry")
59
+ .option("-i, --registry <path>", "Registry path")
60
+ .option("-o, --output <path>", "Graph output path")
61
+ .action(async (opts, cmd) => {
62
+ const paths = await getPaths(cmd);
63
+ const registryPath = opts.registry ?? paths.registry;
64
+ const graphPath = opts.output ?? paths.graph;
65
+ const registry = await readJson(registryPath);
66
+ const graph = bootstrapFromRegistry(registry);
67
+ await writeJson(graphPath, graph.toTraceabilityGraph());
68
+ console.log(`Wrote ${graphPath} (${graph.nodesById.size} nodes, ${graph.toTraceabilityGraph().edges.length} edges)`);
69
+ });
70
+ graph
71
+ .command("query <id>")
72
+ .description("Find relevant subgraph and projection paths (for IDE / generate)")
73
+ .option("-d, --direction <dir>", "out | in | both", "both")
74
+ .option("--depth <n>", "Traversal depth", "2")
75
+ .option("-e, --edges <types>", "Comma-separated edge types (default: generate set)")
76
+ .option("--json", "JSON output for agents")
77
+ .action(async (id, opts, cmd) => {
78
+ const paths = await getPaths(cmd);
79
+ await runGraphQuery({
80
+ graphPath: paths.graph,
81
+ seedId: id,
82
+ direction: opts.direction,
83
+ depth: Number(opts.depth),
84
+ edges: opts.edges,
85
+ json: opts.json,
86
+ });
87
+ });
88
+ graph
89
+ .command("impact <id>")
90
+ .description("Impact analysis: regenerate / review / downstream buckets")
91
+ .option("--change <type>", "Change type", "content_change")
92
+ .option("-o, --output <path>", "Write impact report JSON")
93
+ .option("--json", "Print JSON")
94
+ .action(async (id, opts, cmd) => {
95
+ const paths = await getPaths(cmd);
96
+ await runGraphImpact({
97
+ graphPath: paths.graph,
98
+ rulesPath: paths.rulesImpact,
99
+ originId: id,
100
+ change: opts.change,
101
+ output: opts.output,
102
+ json: opts.json,
103
+ });
104
+ });
105
+ graph
106
+ .command("merge [file]")
107
+ .description("Merge domain patch or knowledge.json into traceability graph (upsert nodes/edges)")
108
+ .option("--from-knowledge", "Read .ai-spector/.docflow/analysis/knowledge.json")
109
+ .option("-g, --graph <path>", "Graph path")
110
+ .option("-o, --write-patch <path>", "Write normalized extract patch before merge")
111
+ .option("--no-validate", "Skip validate after merge")
112
+ .option("--dry-run", "Compute merge stats without saving")
113
+ .action(async (file, opts, cmd) => {
114
+ const paths = await getPaths(cmd);
115
+ await runGraphMerge({
116
+ root: paths.root,
117
+ inputPath: file,
118
+ fromKnowledge: opts.fromKnowledge,
119
+ graphPath: opts.graph ?? paths.graph,
120
+ writePatch: opts.writePatch,
121
+ validate: !opts.noValidate,
122
+ dryRun: opts.dryRun,
123
+ });
124
+ });
125
+ graph
126
+ .command("visualize")
127
+ .description("Generate HTML report to explore graph and knowledge in a browser")
128
+ .option("-o, --output <path>", "Output HTML path")
129
+ .option("-g, --graph <path>", "Graph JSON path")
130
+ .option("--knowledge <path>", "knowledge.json path")
131
+ .option("--no-knowledge", "Omit knowledge.json from report")
132
+ .option("--open", "Open the HTML file in the default browser")
133
+ .action(async (opts, cmd) => {
134
+ const paths = await getPaths(cmd);
135
+ await runGraphVisualize({
136
+ root: paths.root,
137
+ graphPath: opts.graph ?? paths.graph,
138
+ knowledgePath: opts.knowledge,
139
+ output: opts.output,
140
+ open: opts.open,
141
+ skipKnowledge: opts.noKnowledge,
142
+ });
143
+ });
144
+ graph
145
+ .command("validate")
146
+ .description("Validate graph against bundled schema and traceability rules")
147
+ .option("-g, --graph <path>", "Graph path")
148
+ .option("-s, --schema <path>", "Schema path")
149
+ .option("--registry <path>", "Registry for REGISTRY-COMPLETE")
150
+ .option("--rules <path>", "Rules manifest path")
151
+ .action(async (opts, cmd) => {
152
+ const paths = await getPaths(cmd);
153
+ const issues = await validateGraph({
154
+ graphPath: opts.graph ?? paths.graph,
155
+ schemaPath: opts.schema ?? paths.schema,
156
+ registryPath: opts.registry ?? paths.registry,
157
+ rulesPath: opts.rules ?? paths.rulesTraceability,
158
+ });
159
+ console.log(formatIssues(issues));
160
+ const errors = issues.filter((i) => i.severity === "error");
161
+ if (errors.length > 0) {
162
+ process.exitCode = 1;
163
+ }
164
+ });
165
+ program.parseAsync(process.argv).catch((err) => {
166
+ const msg = err instanceof Error ? err.message : String(err);
167
+ console.error(msg);
168
+ console.error("");
169
+ console.error("Fix the issue above, then re-run the same command.");
170
+ console.error("In Cursor, re-run the slash command (/analyze, /validate-graph, …) — see .cursor/commands/_cli-failures.md");
171
+ process.exit(1);
172
+ });
173
+ //# sourceMappingURL=cli.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAChE,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AACrE,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAC7C,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAC1D,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAC5D,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAC1D,OAAO,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AAGlE,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;AAE9B,OAAO;KACJ,IAAI,CAAC,YAAY,CAAC;KAClB,WAAW,CACV,yFAAyF,CAC1F;KACA,OAAO,CAAC,OAAO,CAAC;KAChB,MAAM,CAAC,mBAAmB,EAAE,gEAAgE,CAAC,CAAC;AAEjG,SAAS,cAAc,CAAC,GAAY;IAClC,OAAQ,GAAG,CAAC,eAAe,EAAwB,CAAC,IAAI,CAAC;AAC3D,CAAC;AAED,KAAK,UAAU,QAAQ,CAAC,GAAY;IAClC,OAAO,mBAAmB,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC,CAAC;AAClD,CAAC;AAED,OAAO;KACJ,OAAO,CAAC,MAAM,CAAC;KACf,WAAW,CAAC,+DAA+D,CAAC;KAC5E,MAAM,CAAC,aAAa,EAAE,mCAAmC,CAAC;KAC1D,MAAM,CAAC,kBAAkB,EAAE,kBAAkB,EAAE,OAAO,CAAC,GAAG,EAAE,CAAC;KAC7D,MAAM,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE;IACrB,MAAM,OAAO,CAAC;QACZ,SAAS,EAAE,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;QAC7C,KAAK,EAAE,IAAI,CAAC,KAAK;KAClB,CAAC,CAAC;AACL,CAAC,CAAC,CAAC;AAEL,OAAO;KACJ,OAAO,CAAC,SAAS,CAAC;KAClB,WAAW,CACV,6FAA6F,CAC9F;KACA,MAAM,CACL,SAAS,EACT,kFAAkF,CACnF;KACA,MAAM,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE;IAC1B,MAAM,cAAc,CAAC,cAAc,CAAC,GAAG,CAAC,EAAE,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC;AACnE,CAAC,CAAC,CAAC;AAEL,MAAM,KAAK,GAAG,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,WAAW,CAAC,+BAA+B,CAAC,CAAC;AAEpF,KAAK;KACF,OAAO,CAAC,UAAU,CAAC;KACnB,WAAW,CAAC,wDAAwD,CAAC;KACrE,MAAM,CAAC,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE;IAC3B,MAAM,KAAK,GAAG,MAAM,QAAQ,CAAC,GAAG,CAAC,CAAC;IAClC,MAAM,QAAQ,GAAG,MAAM,oBAAoB,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACxD,MAAM,SAAS,CAAC,KAAK,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;IAC1C,MAAM,KAAK,GAAG,QAAQ,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;IAC5E,OAAO,CAAC,GAAG,CACT,SAAS,KAAK,CAAC,QAAQ,KAAK,QAAQ,CAAC,SAAS,CAAC,MAAM,eAAe,KAAK,YAAY,CACtF,CAAC;AACJ,CAAC,CAAC,CAAC;AAEL,KAAK;KACF,OAAO,CAAC,WAAW,CAAC;KACpB,WAAW,CAAC,oDAAoD,CAAC;KACjE,MAAM,CAAC,uBAAuB,EAAE,eAAe,CAAC;KAChD,MAAM,CAAC,qBAAqB,EAAE,mBAAmB,CAAC;KAClD,MAAM,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE;IAC1B,MAAM,KAAK,GAAG,MAAM,QAAQ,CAAC,GAAG,CAAC,CAAC;IAClC,MAAM,YAAY,GAAG,IAAI,CAAC,QAAQ,IAAI,KAAK,CAAC,QAAQ,CAAC;IACrD,MAAM,SAAS,GAAG,IAAI,CAAC,MAAM,IAAI,KAAK,CAAC,KAAK,CAAC;IAC7C,MAAM,QAAQ,GAAG,MAAM,QAAQ,CAAkB,YAAY,CAAC,CAAC;IAC/D,MAAM,KAAK,GAAG,qBAAqB,CAAC,QAAQ,CAAC,CAAC;IAC9C,MAAM,SAAS,CAAC,SAAS,EAAE,KAAK,CAAC,mBAAmB,EAAE,CAAC,CAAC;IACxD,OAAO,CAAC,GAAG,CACT,SAAS,SAAS,KAAK,KAAK,CAAC,SAAS,CAAC,IAAI,WAAW,KAAK,CAAC,mBAAmB,EAAE,CAAC,KAAK,CAAC,MAAM,SAAS,CACxG,CAAC;AACJ,CAAC,CAAC,CAAC;AAEL,KAAK;KACF,OAAO,CAAC,YAAY,CAAC;KACrB,WAAW,CAAC,kEAAkE,CAAC;KAC/E,MAAM,CAAC,uBAAuB,EAAE,iBAAiB,EAAE,MAAM,CAAC;KAC1D,MAAM,CAAC,aAAa,EAAE,iBAAiB,EAAE,GAAG,CAAC;KAC7C,MAAM,CACL,qBAAqB,EACrB,oDAAoD,CACrD;KACA,MAAM,CAAC,QAAQ,EAAE,wBAAwB,CAAC;KAC1C,MAAM,CAAC,KAAK,EAAE,EAAU,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE;IACtC,MAAM,KAAK,GAAG,MAAM,QAAQ,CAAC,GAAG,CAAC,CAAC;IAClC,MAAM,aAAa,CAAC;QAClB,SAAS,EAAE,KAAK,CAAC,KAAK;QACtB,MAAM,EAAE,EAAE;QACV,SAAS,EAAE,IAAI,CAAC,SAAkC;QAClD,KAAK,EAAE,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC;QACzB,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,IAAI,EAAE,IAAI,CAAC,IAAI;KAChB,CAAC,CAAC;AACL,CAAC,CAAC,CAAC;AAEL,KAAK;KACF,OAAO,CAAC,aAAa,CAAC;KACtB,WAAW,CAAC,2DAA2D,CAAC;KACxE,MAAM,CAAC,iBAAiB,EAAE,aAAa,EAAE,gBAAgB,CAAC;KAC1D,MAAM,CAAC,qBAAqB,EAAE,0BAA0B,CAAC;KACzD,MAAM,CAAC,QAAQ,EAAE,YAAY,CAAC;KAC9B,MAAM,CAAC,KAAK,EAAE,EAAU,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE;IACtC,MAAM,KAAK,GAAG,MAAM,QAAQ,CAAC,GAAG,CAAC,CAAC;IAClC,MAAM,cAAc,CAAC;QACnB,SAAS,EAAE,KAAK,CAAC,KAAK;QACtB,SAAS,EAAE,KAAK,CAAC,WAAW;QAC5B,QAAQ,EAAE,EAAE;QACZ,MAAM,EAAE,IAAI,CAAC,MAAM;QACnB,MAAM,EAAE,IAAI,CAAC,MAAM;QACnB,IAAI,EAAE,IAAI,CAAC,IAAI;KAChB,CAAC,CAAC;AACL,CAAC,CAAC,CAAC;AAEL,KAAK;KACF,OAAO,CAAC,cAAc,CAAC;KACvB,WAAW,CACV,mFAAmF,CACpF;KACA,MAAM,CAAC,kBAAkB,EAAE,mDAAmD,CAAC;KAC/E,MAAM,CAAC,oBAAoB,EAAE,YAAY,CAAC;KAC1C,MAAM,CAAC,0BAA0B,EAAE,6CAA6C,CAAC;KACjF,MAAM,CAAC,eAAe,EAAE,2BAA2B,CAAC;KACpD,MAAM,CAAC,WAAW,EAAE,oCAAoC,CAAC;KACzD,MAAM,CAAC,KAAK,EAAE,IAAwB,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE;IACpD,MAAM,KAAK,GAAG,MAAM,QAAQ,CAAC,GAAG,CAAC,CAAC;IAClC,MAAM,aAAa,CAAC;QAClB,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,SAAS,EAAE,IAAI;QACf,aAAa,EAAE,IAAI,CAAC,aAAa;QACjC,SAAS,EAAE,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,KAAK;QACpC,UAAU,EAAE,IAAI,CAAC,UAAU;QAC3B,QAAQ,EAAE,CAAC,IAAI,CAAC,UAAU;QAC1B,MAAM,EAAE,IAAI,CAAC,MAAM;KACpB,CAAC,CAAC;AACL,CAAC,CAAC,CAAC;AAEL,KAAK;KACF,OAAO,CAAC,WAAW,CAAC;KACpB,WAAW,CAAC,kEAAkE,CAAC;KAC/E,MAAM,CAAC,qBAAqB,EAAE,kBAAkB,CAAC;KACjD,MAAM,CAAC,oBAAoB,EAAE,iBAAiB,CAAC;KAC/C,MAAM,CAAC,oBAAoB,EAAE,qBAAqB,CAAC;KACnD,MAAM,CAAC,gBAAgB,EAAE,iCAAiC,CAAC;KAC3D,MAAM,CAAC,QAAQ,EAAE,2CAA2C,CAAC;KAC7D,MAAM,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE;IAC1B,MAAM,KAAK,GAAG,MAAM,QAAQ,CAAC,GAAG,CAAC,CAAC;IAClC,MAAM,iBAAiB,CAAC;QACtB,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,SAAS,EAAE,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,KAAK;QACpC,aAAa,EAAE,IAAI,CAAC,SAAS;QAC7B,MAAM,EAAE,IAAI,CAAC,MAAM;QACnB,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,aAAa,EAAE,IAAI,CAAC,WAAW;KAChC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC;AAEL,KAAK;KACF,OAAO,CAAC,UAAU,CAAC;KACnB,WAAW,CAAC,8DAA8D,CAAC;KAC3E,MAAM,CAAC,oBAAoB,EAAE,YAAY,CAAC;KAC1C,MAAM,CAAC,qBAAqB,EAAE,aAAa,CAAC;KAC5C,MAAM,CAAC,mBAAmB,EAAE,gCAAgC,CAAC;KAC7D,MAAM,CAAC,gBAAgB,EAAE,qBAAqB,CAAC;KAC/C,MAAM,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE;IAC1B,MAAM,KAAK,GAAG,MAAM,QAAQ,CAAC,GAAG,CAAC,CAAC;IAClC,MAAM,MAAM,GAAG,MAAM,aAAa,CAAC;QACjC,SAAS,EAAE,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,KAAK;QACpC,UAAU,EAAE,IAAI,CAAC,MAAM,IAAI,KAAK,CAAC,MAAM;QACvC,YAAY,EAAE,IAAI,CAAC,QAAQ,IAAI,KAAK,CAAC,QAAQ;QAC7C,SAAS,EAAE,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,iBAAiB;KACjD,CAAC,CAAC;IACH,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC,CAAC;IAClC,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,OAAO,CAAC,CAAC;IAC5D,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACtB,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;IACvB,CAAC;AACH,CAAC,CAAC,CAAC;AAEL,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;IAC7C,MAAM,GAAG,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAC7D,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACnB,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IAClB,OAAO,CAAC,KAAK,CAAC,oDAAoD,CAAC,CAAC;IACpE,OAAO,CAAC,KAAK,CAAC,4GAA4G,CAAC,CAAC;IAC5H,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}
@@ -0,0 +1,9 @@
1
+ export interface AnalyzePrepOptions {
2
+ merge?: boolean;
3
+ }
4
+ /**
5
+ * Prepare traceability graph structure (registry + bootstrap + validate).
6
+ * Semantic knowledge extraction runs in Cursor via /analyze + Graphify MCP.
7
+ */
8
+ export declare function runAnalyzePrep(root?: string, opts?: AnalyzePrepOptions): Promise<void>;
9
+ //# sourceMappingURL=analyze.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"analyze.d.ts","sourceRoot":"","sources":["../../src/commands/analyze.ts"],"names":[],"mappings":"AASA,MAAM,WAAW,kBAAkB;IACjC,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;;GAGG;AACH,wBAAsB,cAAc,CAClC,IAAI,CAAC,EAAE,MAAM,EACb,IAAI,GAAE,kBAAuB,GAC5B,OAAO,CAAC,IAAI,CAAC,CAyDf"}
@@ -0,0 +1,62 @@
1
+ import { join } from "node:path";
2
+ import { buildSectionRegistry } from "../registry/build.js";
3
+ import { bootstrapFromRegistry } from "./bootstrap.js";
4
+ import { validateGraph, formatIssues } from "./validate.js";
5
+ import { loadDocflowConfig } from "../config/load.js";
6
+ import { resolveProjectPaths } from "../util/paths.js";
7
+ import { pathExists, readJson, writeJson } from "../util/fs.js";
8
+ import { runGraphMerge } from "./graph-merge.js";
9
+ /**
10
+ * Prepare traceability graph structure (registry + bootstrap + validate).
11
+ * Semantic knowledge extraction runs in Cursor via /analyze + Graphify MCP.
12
+ */
13
+ export async function runAnalyzePrep(root, opts = {}) {
14
+ const paths = await resolveProjectPaths(root);
15
+ const { root: projectRoot } = await loadDocflowConfig(root);
16
+ const registry = await buildSectionRegistry(projectRoot);
17
+ await writeJson(paths.registry, registry);
18
+ const graph = bootstrapFromRegistry(registry);
19
+ await writeJson(paths.graph, graph.toTraceabilityGraph());
20
+ const issues = await validateGraph({
21
+ graphPath: paths.graph,
22
+ schemaPath: paths.schema,
23
+ registryPath: paths.registry,
24
+ rulesPath: paths.rulesTraceability,
25
+ });
26
+ const errors = issues.filter((i) => i.severity === "error");
27
+ if (errors.length > 0) {
28
+ console.log(formatIssues(issues));
29
+ throw new Error("Graph validation failed after analyze prep");
30
+ }
31
+ const statePath = join(projectRoot, ".ai-spector/.docflow/state.json");
32
+ const state = await readJson(statePath).catch(() => ({
33
+ version: 1,
34
+ analysis: {},
35
+ }));
36
+ const analysis = state.analysis ?? {};
37
+ analysis.graphPreparedAt = new Date().toISOString();
38
+ state.analysis = analysis;
39
+ await writeJson(statePath, state);
40
+ const total = registry.documents.reduce((n, d) => n + d.sections.length, 0);
41
+ console.log(`Graph ready: ${registry.documents.length} documents, ${total} sections`);
42
+ console.log(` registry → ${paths.registry}`);
43
+ console.log(` graph → ${paths.graph}`);
44
+ console.log("");
45
+ const knowledgePath = join(projectRoot, ".ai-spector/.docflow/analysis/knowledge.json");
46
+ const patchPath = join(projectRoot, ".ai-spector/.docflow/extract/patch.json");
47
+ if (opts.merge) {
48
+ if ((await pathExists(knowledgePath)) || (await pathExists(patchPath))) {
49
+ await runGraphMerge({ root: projectRoot });
50
+ console.log("");
51
+ console.log("Merged domain knowledge into graph.");
52
+ }
53
+ else {
54
+ console.log("");
55
+ console.log("Skip merge: no knowledge.json or extract/patch.json yet.");
56
+ }
57
+ }
58
+ console.log("");
59
+ console.log("Structure ready. In Cursor run: /analyze");
60
+ console.log("(The /analyze agent runs merge, validate, and Graphify — not you.)");
61
+ }
62
+ //# sourceMappingURL=analyze.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"analyze.js","sourceRoot":"","sources":["../../src/commands/analyze.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,4 @@
1
+ import type { SectionRegistry } from "../types.js";
2
+ import { InMemoryGraph } from "../graph/InMemoryGraph.js";
3
+ export declare function bootstrapFromRegistry(registry: SectionRegistry): InMemoryGraph;
4
+ //# sourceMappingURL=bootstrap.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"bootstrap.d.ts","sourceRoot":"","sources":["../../src/commands/bootstrap.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AA4C1D,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,eAAe,GAAG,aAAa,CA4B9E"}
@@ -0,0 +1,58 @@
1
+ import { InMemoryGraph } from "../graph/InMemoryGraph.js";
2
+ import { emptyGraph } from "../graph/load.js";
3
+ function documentNode(doc) {
4
+ return {
5
+ id: doc.documentId,
6
+ type: "document",
7
+ template: doc.template,
8
+ ...(doc.output ? { output: doc.output } : {}),
9
+ ...(doc.outputPattern ? { outputPattern: doc.outputPattern } : {}),
10
+ ...(doc.perDomain ? { perDomain: doc.perDomain } : {}),
11
+ };
12
+ }
13
+ function sectionNode(sec, documentId) {
14
+ return {
15
+ id: sec.id,
16
+ type: "section",
17
+ documentId,
18
+ heading: sec.heading,
19
+ level: sec.level,
20
+ order: sec.order,
21
+ };
22
+ }
23
+ function resolveParentId(sections, index) {
24
+ const current = sections[index];
25
+ if (current.level <= 2) {
26
+ return null;
27
+ }
28
+ for (let i = index - 1; i >= 0; i--) {
29
+ if (sections[i].level === current.level - 1) {
30
+ return sections[i].id;
31
+ }
32
+ }
33
+ return null;
34
+ }
35
+ export function bootstrapFromRegistry(registry) {
36
+ const graph = InMemoryGraph.from(emptyGraph());
37
+ for (const doc of registry.documents) {
38
+ graph.addNode(documentNode(doc));
39
+ for (let i = 0; i < doc.sections.length; i++) {
40
+ const sec = doc.sections[i];
41
+ graph.addNode(sectionNode(sec, doc.documentId));
42
+ const parentSectionId = resolveParentId(doc.sections, i);
43
+ const parentId = parentSectionId ?? doc.documentId;
44
+ const partOf = { type: "partOf", from: sec.id, to: parentId };
45
+ const contains = { type: "contains", from: parentId, to: sec.id };
46
+ graph.addEdge(partOf);
47
+ graph.addEdge(contains);
48
+ if (i > 0) {
49
+ const prev = doc.sections[i - 1];
50
+ if (prev.level === sec.level) {
51
+ graph.addEdge({ type: "follows", from: prev.id, to: sec.id });
52
+ }
53
+ }
54
+ }
55
+ }
56
+ return graph;
57
+ }
58
+ //# sourceMappingURL=bootstrap.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"bootstrap.js","sourceRoot":"","sources":["../../src/commands/bootstrap.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAC1D,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAE9C,SAAS,YAAY,CAAC,GAAoC;IACxD,OAAO;QACL,EAAE,EAAE,GAAG,CAAC,UAAU;QAClB,IAAI,EAAE,UAAU;QAChB,QAAQ,EAAE,GAAG,CAAC,QAAQ;QACtB,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC7C,GAAG,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,GAAG,CAAC,aAAa,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAClE,GAAG,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,GAAG,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACvD,CAAC;AACJ,CAAC;AAED,SAAS,WAAW,CAClB,GAAmD,EACnD,UAAkB;IAElB,OAAO;QACL,EAAE,EAAE,GAAG,CAAC,EAAE;QACV,IAAI,EAAE,SAAS;QACf,UAAU;QACV,OAAO,EAAE,GAAG,CAAC,OAAO;QACpB,KAAK,EAAE,GAAG,CAAC,KAAK;QAChB,KAAK,EAAE,GAAG,CAAC,KAAK;KACjB,CAAC;AACJ,CAAC;AAED,SAAS,eAAe,CACtB,QAAqD,EACrD,KAAa;IAEb,MAAM,OAAO,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;IAChC,IAAI,OAAO,CAAC,KAAK,IAAI,CAAC,EAAE,CAAC;QACvB,OAAO,IAAI,CAAC;IACd,CAAC;IACD,KAAK,IAAI,CAAC,GAAG,KAAK,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QACpC,IAAI,QAAQ,CAAC,CAAC,CAAC,CAAC,KAAK,KAAK,OAAO,CAAC,KAAK,GAAG,CAAC,EAAE,CAAC;YAC5C,OAAO,QAAQ,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QACxB,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,MAAM,UAAU,qBAAqB,CAAC,QAAyB;IAC7D,MAAM,KAAK,GAAG,aAAa,CAAC,IAAI,CAAC,UAAU,EAAE,CAAC,CAAC;IAE/C,KAAK,MAAM,GAAG,IAAI,QAAQ,CAAC,SAAS,EAAE,CAAC;QACrC,KAAK,CAAC,OAAO,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC;QAEjC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YAC7C,MAAM,GAAG,GAAG,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;YAC5B,KAAK,CAAC,OAAO,CAAC,WAAW,CAAC,GAAG,EAAE,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC;YAEhD,MAAM,eAAe,GAAG,eAAe,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC;YACzD,MAAM,QAAQ,GAAG,eAAe,IAAI,GAAG,CAAC,UAAU,CAAC;YAEnD,MAAM,MAAM,GAAc,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,GAAG,CAAC,EAAE,EAAE,EAAE,EAAE,QAAQ,EAAE,CAAC;YACzE,MAAM,QAAQ,GAAc,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,EAAE,GAAG,CAAC,EAAE,EAAE,CAAC;YAC7E,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;YACtB,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;YAExB,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;gBACV,MAAM,IAAI,GAAG,GAAG,CAAC,QAAQ,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;gBACjC,IAAI,IAAI,CAAC,KAAK,KAAK,GAAG,CAAC,KAAK,EAAE,CAAC;oBAC7B,KAAK,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,CAAC,EAAE,EAAE,EAAE,EAAE,GAAG,CAAC,EAAE,EAAE,CAAC,CAAC;gBAChE,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC"}