@vfarcic/dot-ai 0.34.0 → 0.36.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/README.md +61 -72
- package/dist/core/doc-discovery.d.ts +38 -0
- package/dist/core/doc-discovery.d.ts.map +1 -0
- package/dist/core/doc-discovery.js +231 -0
- package/dist/core/doc-testing-session.d.ts +109 -0
- package/dist/core/doc-testing-session.d.ts.map +1 -0
- package/dist/core/doc-testing-session.js +747 -0
- package/dist/core/doc-testing-types.d.ts +125 -0
- package/dist/core/doc-testing-types.d.ts.map +1 -0
- package/dist/core/doc-testing-types.js +53 -0
- package/dist/core/error-handling.d.ts +14 -14
- package/dist/core/error-handling.d.ts.map +1 -1
- package/dist/core/error-handling.js +43 -31
- package/dist/core/kubernetes-utils.d.ts +0 -3
- package/dist/core/kubernetes-utils.d.ts.map +1 -1
- package/dist/core/kubernetes-utils.js +40 -8
- package/dist/core/schema.d.ts.map +1 -1
- package/dist/core/schema.js +12 -6
- package/dist/core/solution-utils.d.ts +6 -0
- package/dist/core/solution-utils.d.ts.map +1 -1
- package/dist/core/solution-utils.js +26 -0
- package/dist/interfaces/cli.d.ts +1 -0
- package/dist/interfaces/cli.d.ts.map +1 -1
- package/dist/interfaces/cli.js +76 -1
- package/dist/interfaces/mcp.d.ts.map +1 -1
- package/dist/interfaces/mcp.js +10 -2
- package/dist/tools/generate-manifests.js +1 -1
- package/dist/tools/test-docs.d.ts +21 -0
- package/dist/tools/test-docs.d.ts.map +1 -0
- package/dist/tools/test-docs.js +349 -0
- package/package.json +4 -1
- package/prompts/doc-testing-done.md +51 -0
- package/prompts/doc-testing-fix.md +120 -0
- package/prompts/doc-testing-scan.md +140 -0
- package/prompts/doc-testing-test-section.md +239 -0
package/README.md
CHANGED
|
@@ -6,43 +6,62 @@
|
|
|
6
6
|
|
|
7
7
|
</div>
|
|
8
8
|
|
|
9
|
-
DevOps AI Toolkit
|
|
9
|
+
DevOps AI Toolkit provides two powerful AI-driven capabilities: **Kubernetes deployment recommendations** that discover your cluster's capabilities and suggest optimal deployment approaches, and **automated documentation testing** that validates documentation accuracy by executing commands and testing examples.
|
|
10
10
|
|
|
11
11
|
## Who is this for?
|
|
12
12
|
|
|
13
|
+
### Kubernetes Deployment
|
|
13
14
|
- **Developers**: Deploy applications without needing deep Kubernetes expertise
|
|
14
|
-
- **AI Agents**: Integrate with Claude Code, Cursor, or VS Code for conversational deployments
|
|
15
15
|
- **Platform Engineers**: *(Coming Soon)* Governance, policy enforcement, and organizational compliance features
|
|
16
16
|
|
|
17
|
+
### Documentation Testing
|
|
18
|
+
- **Documentation Maintainers**: Automatically validate documentation accuracy and catch outdated content
|
|
19
|
+
- **Technical Writers**: Identify which sections need updates and prioritize work effectively
|
|
20
|
+
- **Open Source Maintainers**: Ensure documentation works correctly for new contributors
|
|
21
|
+
|
|
22
|
+
### AI Integration
|
|
23
|
+
- **AI Agents**: Integrate both capabilities with Claude Code, Cursor, or VS Code for conversational workflows
|
|
24
|
+
|
|
17
25
|
## Key Features
|
|
18
26
|
|
|
27
|
+
### Kubernetes Deployment Intelligence
|
|
19
28
|
🔍 **Smart Discovery**: Automatically finds all available resources and operators in your cluster
|
|
20
29
|
🤖 **AI Recommendations**: Get deployment suggestions tailored to your specific cluster setup
|
|
21
|
-
⚡ **Two Usage Modes**: Use directly via CLI or integrate with AI development tools
|
|
22
30
|
🔧 **Operator-Aware**: Leverages custom operators and CRDs when available
|
|
23
31
|
🚀 **Complete Workflow**: From discovery to deployment with automated Kubernetes integration
|
|
24
32
|
|
|
33
|
+
### Documentation Testing & Validation
|
|
34
|
+
📖 **Automated Testing**: Validates documentation by executing commands and testing examples
|
|
35
|
+
🔍 **Two-Phase Validation**: Tests both functionality (does it work?) and semantic accuracy (are descriptions truthful?)
|
|
36
|
+
🛠️ **Fix Application**: User-driven selection and application of recommended documentation improvements
|
|
37
|
+
💾 **Session Management**: Resumable testing workflows for large documentation sets
|
|
38
|
+
|
|
39
|
+
### AI Integration
|
|
40
|
+
⚡ **MCP Integration**: Works seamlessly with Claude Code, Cursor, or VS Code through Model Context Protocol
|
|
41
|
+
🤖 **Conversational Interface**: Natural language interaction for both deployment and documentation testing workflows
|
|
42
|
+
|
|
25
43
|
## Quick Start
|
|
26
44
|
|
|
27
45
|
### Prerequisites
|
|
28
|
-
- **Node.js 18+** and **kubectl** configured with cluster access
|
|
29
|
-
- **Claude API key** (required for AI recommendations)
|
|
30
46
|
|
|
31
|
-
|
|
47
|
+
**For both features:**
|
|
48
|
+
- **Claude API key** (required for AI analysis)
|
|
49
|
+
- Get your API key from [Anthropic Console](https://console.anthropic.com/)
|
|
50
|
+
- Set it as environment variable: `export ANTHROPIC_API_KEY=your_api_key_here`
|
|
32
51
|
|
|
33
|
-
**For
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
52
|
+
**For Kubernetes deployment recommendations:**
|
|
53
|
+
- **kubectl** configured with cluster access
|
|
54
|
+
- Verify cluster access with: `kubectl get nodes`
|
|
55
|
+
- Should show your cluster nodes without authentication errors
|
|
56
|
+
<!-- dotai-ignore: kubectl requirement not verifiable in current environment -->
|
|
37
57
|
|
|
38
|
-
|
|
39
|
-
|
|
58
|
+
**For documentation testing:**
|
|
59
|
+
- **Documentation files** to test (Markdown, HTML, etc.)
|
|
60
|
+
- **File system access** to the documentation you want to validate
|
|
40
61
|
|
|
41
|
-
|
|
42
|
-
dot-ai --version
|
|
43
|
-
```
|
|
62
|
+
### Installation
|
|
44
63
|
|
|
45
|
-
|
|
64
|
+
DevOps AI Toolkit is designed to be used through AI development tools via MCP (Model Context Protocol). No direct installation needed - simply configure your AI tool to connect to the MCP server.
|
|
46
65
|
|
|
47
66
|
### Choose Your Usage Path
|
|
48
67
|
|
|
@@ -59,7 +78,7 @@ Perfect for conversational deployments with AI agents:
|
|
|
59
78
|
"env": {
|
|
60
79
|
"ANTHROPIC_API_KEY": "your_key_here",
|
|
61
80
|
"DOT_AI_SESSION_DIR": "./tmp/sessions",
|
|
62
|
-
"KUBECONFIG": "
|
|
81
|
+
"KUBECONFIG": "~/.kube/config"
|
|
63
82
|
}
|
|
64
83
|
}
|
|
65
84
|
}
|
|
@@ -67,20 +86,21 @@ Perfect for conversational deployments with AI agents:
|
|
|
67
86
|
```
|
|
68
87
|
|
|
69
88
|
**Environment Variables:**
|
|
70
|
-
- `ANTHROPIC_API_KEY`: Required for AI
|
|
71
|
-
- `DOT_AI_SESSION_DIR`: Required session directory (
|
|
72
|
-
- `KUBECONFIG`: Optional kubeconfig path (
|
|
89
|
+
- `ANTHROPIC_API_KEY`: Required for AI analysis (both features)
|
|
90
|
+
- `DOT_AI_SESSION_DIR`: Required session directory (relative paths are relative to where the AI agent is started)
|
|
91
|
+
- `KUBECONFIG`: Optional kubeconfig path for Kubernetes deployments (adjust to your actual kubeconfig location, defaults to `~/.kube/config`)
|
|
73
92
|
|
|
74
93
|
2. **Start Claude Code with MCP enabled:**
|
|
75
94
|
```bash
|
|
76
|
-
# Create session directory (relative to
|
|
95
|
+
# Create session directory (relative to the project)
|
|
77
96
|
mkdir -p tmp/sessions
|
|
97
|
+
|
|
78
98
|
claude
|
|
79
99
|
```
|
|
80
100
|
|
|
81
|
-
3. **Use conversational
|
|
101
|
+
3. **Use conversational workflows:**
|
|
82
102
|
|
|
83
|
-
**Example
|
|
103
|
+
**Example: Kubernetes Deployment**
|
|
84
104
|
```
|
|
85
105
|
User: I want to deploy a web application to my cluster
|
|
86
106
|
|
|
@@ -98,63 +118,31 @@ Agent: Perfect! Generating manifests and deploying now...
|
|
|
98
118
|
Agent: ✅ Successfully deployed! Your application is running.
|
|
99
119
|
```
|
|
100
120
|
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
For scripting and direct usage (requires global installation):
|
|
121
|
+
**Example: Documentation Testing**
|
|
122
|
+
```
|
|
123
|
+
User: I want to test my README.md file to make sure all the examples work
|
|
105
124
|
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
mkdir -p tmp/sessions
|
|
125
|
+
Agent: I'll help you test your README.md for accuracy. Let me start a documentation testing session.
|
|
126
|
+
[Uses testDocs tool]
|
|
109
127
|
|
|
110
|
-
|
|
111
|
-
dot-ai recommend --intent "deploy a web application" --session-dir tmp/sessions
|
|
128
|
+
Agent: Found 6 testable sections in your README. Testing installation instructions...
|
|
112
129
|
|
|
113
|
-
|
|
114
|
-
|
|
130
|
+
✅ npm install command works correctly
|
|
131
|
+
❌ Configuration example has wrong port number (8080 vs 3000)
|
|
132
|
+
⚠️ Claims "works out of the box" but requires additional setup
|
|
115
133
|
|
|
116
|
-
|
|
117
|
-
dot-ai answer-question --solution-id sol_xxx --stage required --answers {...} --session-dir tmp/sessions
|
|
118
|
-
dot-ai answer-question --solution-id sol_xxx --stage basic --answers {} --session-dir tmp/sessions
|
|
119
|
-
dot-ai answer-question --solution-id sol_xxx --stage advanced --answers {} --session-dir tmp/sessions
|
|
120
|
-
dot-ai answer-question --solution-id sol_xxx --stage open --answers {"open":"N/A"} --session-dir tmp/sessions
|
|
134
|
+
Which issues would you like me to help you fix?
|
|
121
135
|
|
|
122
|
-
|
|
123
|
-
dot-ai generate-manifests --solution-id sol_xxx --session-dir tmp/sessions
|
|
136
|
+
User: Fix the port number directly in the doc, and I'll create a GitHub issue for the setup requirements.
|
|
124
137
|
|
|
125
|
-
|
|
126
|
-
dot-ai deploy-manifests --solution-id sol_xxx --session-dir tmp/sessions
|
|
138
|
+
Agent: ✅ Documentation testing complete! Fixed 1 issue directly, 1 issue tracked externally.
|
|
127
139
|
```
|
|
128
140
|
|
|
129
|
-
📖 **[Complete
|
|
130
|
-
|
|
131
|
-
## Troubleshooting
|
|
141
|
+
📖 **[Complete MCP Setup Guide →](docs/mcp-setup.md)** - Detailed configuration, troubleshooting, and examples
|
|
132
142
|
|
|
133
|
-
### Installation Issues
|
|
134
143
|
|
|
135
|
-
**Package not found:**
|
|
136
|
-
```bash
|
|
137
|
-
# If you get "package not found" errors:
|
|
138
|
-
npm cache clean --force
|
|
139
|
-
npm install -g @vfarcic/dot-ai
|
|
140
|
-
```
|
|
141
144
|
|
|
142
|
-
|
|
143
|
-
```bash
|
|
144
|
-
# Use npm's recommended approach for global packages:
|
|
145
|
-
mkdir ~/.npm-global
|
|
146
|
-
npm config set prefix '~/.npm-global'
|
|
147
|
-
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
|
|
148
|
-
source ~/.bashrc
|
|
149
|
-
npm install -g @vfarcic/dot-ai
|
|
150
|
-
```
|
|
151
|
-
|
|
152
|
-
### CLI Issues
|
|
153
|
-
|
|
154
|
-
**"dot-ai: command not found":**
|
|
155
|
-
- Ensure global installation: `npm install -g @vfarcic/dot-ai`
|
|
156
|
-
- Check PATH includes npm global bin: `npm config get prefix`
|
|
157
|
-
- Verify installation: `npm list -g @vfarcic/dot-ai`
|
|
145
|
+
## Troubleshooting
|
|
158
146
|
|
|
159
147
|
### MCP Issues
|
|
160
148
|
|
|
@@ -171,8 +159,9 @@ npm install -g @vfarcic/dot-ai
|
|
|
171
159
|
## Documentation
|
|
172
160
|
|
|
173
161
|
### 🚀 Getting Started
|
|
174
|
-
- **[
|
|
175
|
-
- **[MCP
|
|
162
|
+
- **[MCP Setup Guide](docs/mcp-setup.md)** - AI tools integration (Claude Code, Cursor)
|
|
163
|
+
- **[MCP Recommendation Guide](docs/mcp-recommendation-guide.md)** - Kubernetes deployment recommendations
|
|
164
|
+
- **[MCP Documentation Testing Guide](docs/mcp-documentation-testing-guide.md)** - Automated documentation validation
|
|
176
165
|
|
|
177
166
|
### 👩💻 Development
|
|
178
167
|
- **[API Reference](docs/API.md)** - TypeScript interfaces and programmatic usage
|
|
@@ -192,7 +181,7 @@ npm install -g @vfarcic/dot-ai
|
|
|
192
181
|
- **[Next Steps & Roadmap](docs/NEXT_STEPS.md)** - Planned features and future vision
|
|
193
182
|
|
|
194
183
|
**Quick Navigation:**
|
|
195
|
-
- **New to DevOps AI Toolkit?** → Start with [
|
|
184
|
+
- **New to DevOps AI Toolkit?** → Start with [MCP Setup Guide](docs/mcp-setup.md)
|
|
196
185
|
- **Building integrations?** → See [API Reference](docs/API.md)
|
|
197
186
|
- **Contributing code?** → Read [Development Guide](docs/DEVELOPMENT.md)
|
|
198
187
|
- **Understanding architecture?** → Check [Design Overview](docs/design.md)
|
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Documentation File Discovery
|
|
3
|
+
*
|
|
4
|
+
* Discovers documentation files in a project with configurable patterns
|
|
5
|
+
* and intelligent priority ordering.
|
|
6
|
+
*/
|
|
7
|
+
export interface DiscoveredFile {
|
|
8
|
+
path: string;
|
|
9
|
+
name: string;
|
|
10
|
+
priority: number;
|
|
11
|
+
category: 'readme' | 'common' | 'docs' | 'other';
|
|
12
|
+
relativePath: string;
|
|
13
|
+
}
|
|
14
|
+
export declare class DocDiscovery {
|
|
15
|
+
private readonly ignoredDirs;
|
|
16
|
+
/**
|
|
17
|
+
* Get file pattern from CLI args or environment variable
|
|
18
|
+
*/
|
|
19
|
+
getFilePattern(args: any): string;
|
|
20
|
+
/**
|
|
21
|
+
* Discover documentation files in the project
|
|
22
|
+
*/
|
|
23
|
+
discoverFiles(baseDir?: string, pattern?: string): Promise<DiscoveredFile[]>;
|
|
24
|
+
/**
|
|
25
|
+
* Calculate priority for file ordering
|
|
26
|
+
* Lower numbers = higher priority
|
|
27
|
+
*/
|
|
28
|
+
private calculatePriority;
|
|
29
|
+
/**
|
|
30
|
+
* Categorize file by type
|
|
31
|
+
*/
|
|
32
|
+
private categorizeFile;
|
|
33
|
+
/**
|
|
34
|
+
* Format discovered files for display
|
|
35
|
+
*/
|
|
36
|
+
formatForDisplay(files: DiscoveredFile[]): string;
|
|
37
|
+
}
|
|
38
|
+
//# sourceMappingURL=doc-discovery.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"doc-discovery.d.ts","sourceRoot":"","sources":["../../src/core/doc-discovery.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,QAAQ,GAAG,QAAQ,GAAG,MAAM,GAAG,OAAO,CAAC;IACjD,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,WAAW,CAa1B;IAEF;;OAEG;IACH,cAAc,CAAC,IAAI,EAAE,GAAG,GAAG,MAAM;IAajC;;OAEG;IACG,aAAa,CAAC,OAAO,GAAE,MAAsB,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;IAoCjG;;;OAGG;IACH,OAAO,CAAC,iBAAiB;IA2CzB;;OAEG;IACH,OAAO,CAAC,cAAc;IAiCtB;;OAEG;IACH,gBAAgB,CAAC,KAAK,EAAE,cAAc,EAAE,GAAG,MAAM;CA0DlD"}
|
|
@@ -0,0 +1,231 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
/**
|
|
3
|
+
* Documentation File Discovery
|
|
4
|
+
*
|
|
5
|
+
* Discovers documentation files in a project with configurable patterns
|
|
6
|
+
* and intelligent priority ordering.
|
|
7
|
+
*/
|
|
8
|
+
var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
|
|
9
|
+
if (k2 === undefined) k2 = k;
|
|
10
|
+
var desc = Object.getOwnPropertyDescriptor(m, k);
|
|
11
|
+
if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
|
|
12
|
+
desc = { enumerable: true, get: function() { return m[k]; } };
|
|
13
|
+
}
|
|
14
|
+
Object.defineProperty(o, k2, desc);
|
|
15
|
+
}) : (function(o, m, k, k2) {
|
|
16
|
+
if (k2 === undefined) k2 = k;
|
|
17
|
+
o[k2] = m[k];
|
|
18
|
+
}));
|
|
19
|
+
var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
|
|
20
|
+
Object.defineProperty(o, "default", { enumerable: true, value: v });
|
|
21
|
+
}) : function(o, v) {
|
|
22
|
+
o["default"] = v;
|
|
23
|
+
});
|
|
24
|
+
var __importStar = (this && this.__importStar) || (function () {
|
|
25
|
+
var ownKeys = function(o) {
|
|
26
|
+
ownKeys = Object.getOwnPropertyNames || function (o) {
|
|
27
|
+
var ar = [];
|
|
28
|
+
for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
|
|
29
|
+
return ar;
|
|
30
|
+
};
|
|
31
|
+
return ownKeys(o);
|
|
32
|
+
};
|
|
33
|
+
return function (mod) {
|
|
34
|
+
if (mod && mod.__esModule) return mod;
|
|
35
|
+
var result = {};
|
|
36
|
+
if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
|
|
37
|
+
__setModuleDefault(result, mod);
|
|
38
|
+
return result;
|
|
39
|
+
};
|
|
40
|
+
})();
|
|
41
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
42
|
+
exports.DocDiscovery = void 0;
|
|
43
|
+
const path = __importStar(require("path"));
|
|
44
|
+
const glob_1 = require("glob");
|
|
45
|
+
class DocDiscovery {
|
|
46
|
+
ignoredDirs = [
|
|
47
|
+
'node_modules',
|
|
48
|
+
'.git',
|
|
49
|
+
'dist',
|
|
50
|
+
'build',
|
|
51
|
+
'.next',
|
|
52
|
+
'target',
|
|
53
|
+
'bin',
|
|
54
|
+
'obj',
|
|
55
|
+
'.vscode',
|
|
56
|
+
'.idea',
|
|
57
|
+
'coverage',
|
|
58
|
+
'.nyc_output'
|
|
59
|
+
];
|
|
60
|
+
/**
|
|
61
|
+
* Get file pattern from CLI args or environment variable
|
|
62
|
+
*/
|
|
63
|
+
getFilePattern(args) {
|
|
64
|
+
// Priority: CLI argument > environment variable > default
|
|
65
|
+
if (args.filePattern) {
|
|
66
|
+
return args.filePattern;
|
|
67
|
+
}
|
|
68
|
+
if (process.env.DOT_AI_DOC_PATTERN) {
|
|
69
|
+
return process.env.DOT_AI_DOC_PATTERN;
|
|
70
|
+
}
|
|
71
|
+
return '**/*.md';
|
|
72
|
+
}
|
|
73
|
+
/**
|
|
74
|
+
* Discover documentation files in the project
|
|
75
|
+
*/
|
|
76
|
+
async discoverFiles(baseDir = process.cwd(), pattern) {
|
|
77
|
+
const filePattern = pattern || '**/*.md';
|
|
78
|
+
try {
|
|
79
|
+
// Use glob to find files matching the pattern
|
|
80
|
+
const files = await (0, glob_1.glob)(filePattern, {
|
|
81
|
+
cwd: baseDir,
|
|
82
|
+
ignore: this.ignoredDirs.map(dir => `${dir}/**`),
|
|
83
|
+
nodir: true,
|
|
84
|
+
dot: false
|
|
85
|
+
});
|
|
86
|
+
// Convert to DiscoveredFile objects
|
|
87
|
+
const discoveredFiles = files.map((file) => {
|
|
88
|
+
const fullPath = path.join(baseDir, file);
|
|
89
|
+
const relativePath = file;
|
|
90
|
+
const name = path.basename(file);
|
|
91
|
+
return {
|
|
92
|
+
path: fullPath,
|
|
93
|
+
name,
|
|
94
|
+
priority: this.calculatePriority(relativePath, name),
|
|
95
|
+
category: this.categorizeFile(relativePath, name),
|
|
96
|
+
relativePath
|
|
97
|
+
};
|
|
98
|
+
});
|
|
99
|
+
// Sort by priority (lower number = higher priority)
|
|
100
|
+
return discoveredFiles.sort((a, b) => a.priority - b.priority);
|
|
101
|
+
}
|
|
102
|
+
catch (error) {
|
|
103
|
+
console.error('Error discovering documentation files:', error);
|
|
104
|
+
return [];
|
|
105
|
+
}
|
|
106
|
+
}
|
|
107
|
+
/**
|
|
108
|
+
* Calculate priority for file ordering
|
|
109
|
+
* Lower numbers = higher priority
|
|
110
|
+
*/
|
|
111
|
+
calculatePriority(relativePath, fileName) {
|
|
112
|
+
const lowerPath = relativePath.toLowerCase();
|
|
113
|
+
const lowerName = fileName.toLowerCase();
|
|
114
|
+
// README files get highest priority
|
|
115
|
+
if (lowerName.startsWith('readme')) {
|
|
116
|
+
if (lowerName === 'readme.md')
|
|
117
|
+
return 1;
|
|
118
|
+
return 2;
|
|
119
|
+
}
|
|
120
|
+
// Common documentation files
|
|
121
|
+
const commonDocs = [
|
|
122
|
+
'contributing.md',
|
|
123
|
+
'changelog.md',
|
|
124
|
+
'changes.md',
|
|
125
|
+
'getting-started.md',
|
|
126
|
+
'getting_started.md',
|
|
127
|
+
'quickstart.md',
|
|
128
|
+
'installation.md',
|
|
129
|
+
'setup.md',
|
|
130
|
+
'usage.md',
|
|
131
|
+
'api.md',
|
|
132
|
+
'license.md'
|
|
133
|
+
];
|
|
134
|
+
if (commonDocs.includes(lowerName)) {
|
|
135
|
+
return 10 + commonDocs.indexOf(lowerName);
|
|
136
|
+
}
|
|
137
|
+
// Files in docs directory
|
|
138
|
+
if (lowerPath.includes('docs/') || lowerPath.includes('doc/') || lowerPath.includes('documentation/')) {
|
|
139
|
+
return 100;
|
|
140
|
+
}
|
|
141
|
+
// Root level files
|
|
142
|
+
if (!lowerPath.includes('/')) {
|
|
143
|
+
return 200;
|
|
144
|
+
}
|
|
145
|
+
// Everything else
|
|
146
|
+
return 1000;
|
|
147
|
+
}
|
|
148
|
+
/**
|
|
149
|
+
* Categorize file by type
|
|
150
|
+
*/
|
|
151
|
+
categorizeFile(relativePath, fileName) {
|
|
152
|
+
const lowerPath = relativePath.toLowerCase();
|
|
153
|
+
const lowerName = fileName.toLowerCase();
|
|
154
|
+
if (lowerName.startsWith('readme')) {
|
|
155
|
+
return 'readme';
|
|
156
|
+
}
|
|
157
|
+
const commonDocs = [
|
|
158
|
+
'contributing.md',
|
|
159
|
+
'changelog.md',
|
|
160
|
+
'changes.md',
|
|
161
|
+
'getting-started.md',
|
|
162
|
+
'getting_started.md',
|
|
163
|
+
'quickstart.md',
|
|
164
|
+
'installation.md',
|
|
165
|
+
'setup.md',
|
|
166
|
+
'usage.md',
|
|
167
|
+
'api.md',
|
|
168
|
+
'license.md'
|
|
169
|
+
];
|
|
170
|
+
if (commonDocs.includes(lowerName)) {
|
|
171
|
+
return 'common';
|
|
172
|
+
}
|
|
173
|
+
if (lowerPath.includes('docs/') || lowerPath.includes('doc/') || lowerPath.includes('documentation/')) {
|
|
174
|
+
return 'docs';
|
|
175
|
+
}
|
|
176
|
+
return 'other';
|
|
177
|
+
}
|
|
178
|
+
/**
|
|
179
|
+
* Format discovered files for display
|
|
180
|
+
*/
|
|
181
|
+
formatForDisplay(files) {
|
|
182
|
+
if (files.length === 0) {
|
|
183
|
+
return 'No documentation files found matching the pattern.';
|
|
184
|
+
}
|
|
185
|
+
const defaultFile = files[0]; // Highest priority file
|
|
186
|
+
let output = `Found ${files.length} documentation file${files.length === 1 ? '' : 's'}:\n\n`;
|
|
187
|
+
// Group by category
|
|
188
|
+
const categories = {
|
|
189
|
+
readme: files.filter(f => f.category === 'readme'),
|
|
190
|
+
common: files.filter(f => f.category === 'common'),
|
|
191
|
+
docs: files.filter(f => f.category === 'docs'),
|
|
192
|
+
other: files.filter(f => f.category === 'other')
|
|
193
|
+
};
|
|
194
|
+
if (categories.readme.length > 0) {
|
|
195
|
+
output += '**README Files:**\n';
|
|
196
|
+
categories.readme.forEach(file => {
|
|
197
|
+
const isDefault = file === defaultFile ? ' (default)' : '';
|
|
198
|
+
output += `- ${file.relativePath}${isDefault}\n`;
|
|
199
|
+
});
|
|
200
|
+
output += '\n';
|
|
201
|
+
}
|
|
202
|
+
if (categories.common.length > 0) {
|
|
203
|
+
output += '**Common Documentation:**\n';
|
|
204
|
+
categories.common.forEach(file => {
|
|
205
|
+
const isDefault = file === defaultFile ? ' (default)' : '';
|
|
206
|
+
output += `- ${file.relativePath}${isDefault}\n`;
|
|
207
|
+
});
|
|
208
|
+
output += '\n';
|
|
209
|
+
}
|
|
210
|
+
if (categories.docs.length > 0) {
|
|
211
|
+
output += '**Documentation Directory:**\n';
|
|
212
|
+
categories.docs.forEach(file => {
|
|
213
|
+
const isDefault = file === defaultFile ? ' (default)' : '';
|
|
214
|
+
output += `- ${file.relativePath}${isDefault}\n`;
|
|
215
|
+
});
|
|
216
|
+
output += '\n';
|
|
217
|
+
}
|
|
218
|
+
if (categories.other.length > 0) {
|
|
219
|
+
output += '**Other Files:**\n';
|
|
220
|
+
categories.other.forEach(file => {
|
|
221
|
+
const isDefault = file === defaultFile ? ' (default)' : '';
|
|
222
|
+
output += `- ${file.relativePath}${isDefault}\n`;
|
|
223
|
+
});
|
|
224
|
+
output += '\n';
|
|
225
|
+
}
|
|
226
|
+
output += `\nDefault selection: **${defaultFile.relativePath}**\n`;
|
|
227
|
+
output += `\nTo test a specific file, use: \`--file path/to/file.md\``;
|
|
228
|
+
return output;
|
|
229
|
+
}
|
|
230
|
+
}
|
|
231
|
+
exports.DocDiscovery = DocDiscovery;
|
|
@@ -0,0 +1,109 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Documentation Testing Session Manager
|
|
3
|
+
*
|
|
4
|
+
* Handles creating, loading, saving, and managing documentation validation sessions.
|
|
5
|
+
* Uses the existing session directory infrastructure from session-utils.ts.
|
|
6
|
+
*/
|
|
7
|
+
import { ValidationSession, ValidationPhase, WorkflowStep, DocumentSection, SectionStatus, FixableItem } from './doc-testing-types';
|
|
8
|
+
export declare class DocTestingSessionManager {
|
|
9
|
+
/**
|
|
10
|
+
* Create a new validation session
|
|
11
|
+
*/
|
|
12
|
+
createSession(filePath: string, args: any): ValidationSession;
|
|
13
|
+
/**
|
|
14
|
+
* Load existing session
|
|
15
|
+
*/
|
|
16
|
+
loadSession(sessionId: string, args: any): ValidationSession | null;
|
|
17
|
+
/**
|
|
18
|
+
* Save session state
|
|
19
|
+
*/
|
|
20
|
+
saveSession(session: ValidationSession, args: any): void;
|
|
21
|
+
/**
|
|
22
|
+
* Get universal agent instructions for documentation testing workflow
|
|
23
|
+
*/
|
|
24
|
+
private getAgentInstructions;
|
|
25
|
+
/**
|
|
26
|
+
* Get next workflow step for AI agent
|
|
27
|
+
*/
|
|
28
|
+
getNextStep(sessionId: string, args: any, phaseOverride?: ValidationPhase): WorkflowStep | null;
|
|
29
|
+
/**
|
|
30
|
+
* Handle done phase - mark session as completed and provide summary
|
|
31
|
+
*/
|
|
32
|
+
private getDonePhaseStep;
|
|
33
|
+
/**
|
|
34
|
+
* Generate final session summary for done phase
|
|
35
|
+
*/
|
|
36
|
+
private generateFinalSummary;
|
|
37
|
+
/**
|
|
38
|
+
* Get all active sessions
|
|
39
|
+
*/
|
|
40
|
+
getActiveSessions(args: any): ValidationSession[];
|
|
41
|
+
private generateSessionId;
|
|
42
|
+
/**
|
|
43
|
+
* Load phase prompt from file (following CLAUDE.md pattern)
|
|
44
|
+
*/
|
|
45
|
+
private loadPhasePrompt;
|
|
46
|
+
private getNextPhase;
|
|
47
|
+
private getRemainingPhases;
|
|
48
|
+
/**
|
|
49
|
+
* Update the status of a specific section
|
|
50
|
+
*/
|
|
51
|
+
updateSectionStatus(sessionId: string, sectionId: string, status: SectionStatus, args: any): void;
|
|
52
|
+
/**
|
|
53
|
+
* Get sections for a session
|
|
54
|
+
*/
|
|
55
|
+
getSections(sessionId: string, args: any): DocumentSection[] | null;
|
|
56
|
+
/**
|
|
57
|
+
* Get the next test phase step - handles section-by-section testing
|
|
58
|
+
*/
|
|
59
|
+
private getTestPhaseStep;
|
|
60
|
+
/**
|
|
61
|
+
* Find the next section that needs testing
|
|
62
|
+
*/
|
|
63
|
+
private getNextSectionToTest;
|
|
64
|
+
/**
|
|
65
|
+
* Get remaining sections that need testing
|
|
66
|
+
*/
|
|
67
|
+
private getRemainingTestSections;
|
|
68
|
+
/**
|
|
69
|
+
* Load section-specific test prompt
|
|
70
|
+
*/
|
|
71
|
+
private loadSectionTestPrompt;
|
|
72
|
+
/**
|
|
73
|
+
* Convert string arrays to FixableItem arrays with generated IDs
|
|
74
|
+
*/
|
|
75
|
+
private convertToFixableItems;
|
|
76
|
+
/**
|
|
77
|
+
* Store test results for a specific section
|
|
78
|
+
*/
|
|
79
|
+
storeSectionTestResults(sessionId: string, sectionId: string, results: string, args: any): void;
|
|
80
|
+
/**
|
|
81
|
+
* Process scan results by converting section titles into DocumentSection objects
|
|
82
|
+
*/
|
|
83
|
+
processScanResults(sessionId: string, sectionTitles: string[], args: any): void;
|
|
84
|
+
/**
|
|
85
|
+
* Generate status summary for fix phase
|
|
86
|
+
*/
|
|
87
|
+
private generateStatusSummary;
|
|
88
|
+
/**
|
|
89
|
+
* Generate formatted list of pending/failed items for fix phase
|
|
90
|
+
*/
|
|
91
|
+
private generatePendingItemsList;
|
|
92
|
+
/**
|
|
93
|
+
* Update the status of a specific FixableItem by ID
|
|
94
|
+
*/
|
|
95
|
+
updateFixableItemStatus(sessionId: string, itemId: number, status: 'fixed' | 'deferred' | 'failed', explanation?: string, args?: any): void;
|
|
96
|
+
/**
|
|
97
|
+
* Update multiple FixableItem statuses at once
|
|
98
|
+
*/
|
|
99
|
+
updateMultipleFixableItemStatuses(sessionId: string, updates: Array<{
|
|
100
|
+
itemId: number;
|
|
101
|
+
status: 'fixed' | 'deferred' | 'failed';
|
|
102
|
+
explanation?: string;
|
|
103
|
+
}>, args?: any): void;
|
|
104
|
+
/**
|
|
105
|
+
* Get all FixableItems with pending or failed status
|
|
106
|
+
*/
|
|
107
|
+
getPendingFixableItems(sessionId: string, args?: any): FixableItem[];
|
|
108
|
+
}
|
|
109
|
+
//# sourceMappingURL=doc-testing-session.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"doc-testing-session.d.ts","sourceRoot":"","sources":["../../src/core/doc-testing-session.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,OAAO,EACL,iBAAiB,EACjB,eAAe,EAEf,YAAY,EACZ,eAAe,EACf,aAAa,EAEb,WAAW,EACZ,MAAM,qBAAqB,CAAC;AAE7B,qBAAa,wBAAwB;IAEnC;;OAEG;IACH,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,GAAG,iBAAiB;IAyB7D;;OAEG;IACH,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,GAAG,iBAAiB,GAAG,IAAI;IAiBnE;;OAEG;IACH,WAAW,CAAC,OAAO,EAAE,iBAAiB,EAAE,IAAI,EAAE,GAAG,GAAG,IAAI;IASxD;;OAEG;IACH,OAAO,CAAC,oBAAoB;IA0B5B;;OAEG;IACH,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,aAAa,CAAC,EAAE,eAAe,GAAG,YAAY,GAAG,IAAI;IAyC/F;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAkCxB;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAqD5B;;OAEG;IACH,iBAAiB,CAAC,IAAI,EAAE,GAAG,GAAG,iBAAiB,EAAE;IAyBjD,OAAO,CAAC,iBAAiB;IAMzB;;OAEG;IACH,OAAO,CAAC,eAAe;IAoDvB,OAAO,CAAC,YAAY;IAMpB,OAAO,CAAC,kBAAkB;IAQ1B;;OAEG;IACH,mBAAmB,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,EAAE,IAAI,EAAE,GAAG,GAAG,IAAI;IAejG;;OAEG;IACH,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,GAAG,eAAe,EAAE,GAAG,IAAI;IAMnE;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAgFxB;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAoB5B;;OAEG;IACH,OAAO,CAAC,wBAAwB;IAShC;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAgC7B;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAkB7B;;OAEG;IACH,uBAAuB,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,GAAG,IAAI;IAsD/F;;OAEG;IACH,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,GAAG,GAAG,IAAI;IA4B/E;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAuC7B;;OAEG;IACH,OAAO,CAAC,wBAAwB;IAmDhC;;OAEG;IACH,uBAAuB,CACrB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,OAAO,GAAG,UAAU,GAAG,QAAQ,EACvC,WAAW,CAAC,EAAE,MAAM,EACpB,IAAI,CAAC,EAAE,GAAG,GACT,IAAI;IAoCP;;OAEG;IACH,iCAAiC,CAC/B,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,KAAK,CAAC;QACb,MAAM,EAAE,MAAM,CAAC;QACf,MAAM,EAAE,OAAO,GAAG,UAAU,GAAG,QAAQ,CAAC;QACxC,WAAW,CAAC,EAAE,MAAM,CAAC;KACtB,CAAC,EACF,IAAI,CAAC,EAAE,GAAG,GACT,IAAI;IA4CP;;OAEG;IACH,sBAAsB,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,GAAG,GAAG,WAAW,EAAE;CAqBrE"}
|