docworks 0.12.0-next.1 → 0.12.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 +84 -56
- package/dist/commands/check.d.ts +3 -2
- package/dist/commands/check.d.ts.map +1 -1
- package/dist/commands/check.js +31 -12
- package/dist/commands/check.js.map +1 -1
- package/dist/commands/init.d.ts +0 -1
- package/dist/commands/init.d.ts.map +1 -1
- package/dist/commands/init.js +31 -63
- package/dist/commands/init.js.map +1 -1
- package/dist/core/validator.d.ts +3 -3
- package/dist/core/validator.d.ts.map +1 -1
- package/dist/core/validator.js +10 -29
- package/dist/core/validator.js.map +1 -1
- package/dist/index.js +5 -11
- package/dist/index.js.map +1 -1
- package/dist/providers/index.d.ts +3 -0
- package/dist/providers/index.d.ts.map +1 -0
- package/dist/providers/index.js +94 -0
- package/dist/providers/index.js.map +1 -0
- package/dist/sources/source.d.ts +5 -0
- package/dist/sources/source.d.ts.map +1 -0
- package/dist/sources/source.js +23 -0
- package/dist/sources/source.js.map +1 -0
- package/dist/types/config.d.ts +6 -7
- package/dist/types/config.d.ts.map +1 -1
- package/dist/utils/config.d.ts.map +1 -1
- package/dist/utils/config.js +8 -3
- package/dist/utils/config.js.map +1 -1
- package/dist/utils/reporter.d.ts +1 -1
- package/dist/utils/reporter.d.ts.map +1 -1
- package/dist/utils/reporter.js +18 -51
- package/dist/utils/reporter.js.map +1 -1
- package/package.json +1 -1
- package/dist/commands/test.d.ts +0 -5
- package/dist/commands/test.d.ts.map +0 -1
- package/dist/commands/test.js +0 -45
- package/dist/commands/test.js.map +0 -1
- package/dist/core/ai.d.ts +0 -2
- package/dist/core/ai.d.ts.map +0 -1
- package/dist/core/ai.js +0 -29
- package/dist/core/ai.js.map +0 -1
- package/dist/core/cache.d.ts +0 -3
- package/dist/core/cache.d.ts.map +0 -1
- package/dist/core/cache.js +0 -31
- package/dist/core/cache.js.map +0 -1
- package/dist/providers/anthropic.d.ts +0 -10
- package/dist/providers/anthropic.d.ts.map +0 -1
- package/dist/providers/anthropic.js +0 -51
- package/dist/providers/anthropic.js.map +0 -1
- package/dist/providers/base.d.ts +0 -12
- package/dist/providers/base.d.ts.map +0 -1
- package/dist/providers/base.js +0 -14
- package/dist/providers/base.js.map +0 -1
- package/dist/providers/openai.d.ts +0 -10
- package/dist/providers/openai.d.ts.map +0 -1
- package/dist/providers/openai.js +0 -42
- package/dist/providers/openai.js.map +0 -1
- package/dist/sources/base.d.ts +0 -3
- package/dist/sources/base.d.ts.map +0 -1
- package/dist/sources/base.js +0 -12
- package/dist/sources/base.js.map +0 -1
- package/dist/sources/llms-txt.d.ts +0 -9
- package/dist/sources/llms-txt.d.ts.map +0 -1
- package/dist/sources/llms-txt.js +0 -64
- package/dist/sources/llms-txt.js.map +0 -1
- package/dist/sources/local.d.ts +0 -8
- package/dist/sources/local.d.ts.map +0 -1
- package/dist/sources/local.js +0 -37
- package/dist/sources/local.js.map +0 -1
- package/templates/api.yml +0 -21
- package/templates/default.yml +0 -19
- package/templates/gitbook.yml +0 -13
- package/templates/library.yml +0 -21
- package/templates/mintlify.yml +0 -18
- package/templates/readme.yml +0 -13
package/README.md
CHANGED
|
@@ -1,19 +1,15 @@
|
|
|
1
|
-
|
|
2
|
-
<br/><br/>
|
|
1
|
+
# DocWorks
|
|
3
2
|
|
|
4
|
-
Ensure your docs work for developers and AI.
|
|
3
|
+
Ensure your docs work for developers and AI. Tests if humans and AI agents can actually accomplish tasks using your documentation.
|
|
5
4
|
|
|
6
5
|
## Quick Start
|
|
7
6
|
|
|
8
7
|
```bash
|
|
9
|
-
# Install
|
|
8
|
+
# Install
|
|
10
9
|
npm install -g docworks
|
|
11
10
|
|
|
12
|
-
# Initialize
|
|
13
|
-
docworks init
|
|
14
|
-
|
|
15
|
-
# Edit docworks.yml with your docs URL
|
|
16
|
-
# source: https://docs.yourcompany.com
|
|
11
|
+
# Initialize
|
|
12
|
+
docworks init
|
|
17
13
|
|
|
18
14
|
# Run validation
|
|
19
15
|
OPENAI_API_KEY=sk-... docworks check
|
|
@@ -21,89 +17,121 @@ OPENAI_API_KEY=sk-... docworks check
|
|
|
21
17
|
|
|
22
18
|
## How It Works
|
|
23
19
|
|
|
24
|
-
|
|
25
|
-
2. **Define journeys** - What must developers accomplish?
|
|
26
|
-
3. **AI validates** - Can these journeys be completed?
|
|
27
|
-
4. **Get results** - See what's missing
|
|
28
|
-
|
|
29
|
-
## Supported Platforms
|
|
20
|
+
DocWorks tests documentation the way developers actually use it - by having AI search and navigate your docs to answer questions:
|
|
30
21
|
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
- **GitBook** - via llms.txt
|
|
36
|
-
- **Any site with llms.txt** - [llmstxt.org](https://llmstxt.org)
|
|
37
|
-
- **Local folders** - for private docs
|
|
22
|
+
1. **AI explores your docs** - Uses web search to navigate pages
|
|
23
|
+
2. **Tracks the journey** - Records which pages were visited
|
|
24
|
+
3. **Reports confidence** - Shows how easily answers were found
|
|
25
|
+
4. **Identifies gaps** - Lists exactly what's missing
|
|
38
26
|
|
|
39
27
|
## Configuration
|
|
40
28
|
|
|
29
|
+
### Simple Questions
|
|
30
|
+
|
|
41
31
|
```yaml
|
|
42
32
|
# docworks.yml
|
|
43
|
-
source: https://docs.yourcompany.com
|
|
33
|
+
source: https://docs.yourcompany.com
|
|
34
|
+
|
|
35
|
+
questions:
|
|
36
|
+
- How do I authenticate?
|
|
37
|
+
- What are the rate limits?
|
|
38
|
+
- Where are code examples?
|
|
39
|
+
|
|
40
|
+
provider: openai
|
|
41
|
+
model: gpt-4o-mini
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
### Journey Validation
|
|
45
|
+
|
|
46
|
+
```yaml
|
|
47
|
+
source: https://docs.yourcompany.com
|
|
44
48
|
|
|
45
49
|
journeys:
|
|
46
50
|
authentication:
|
|
47
|
-
- How do I
|
|
48
|
-
-
|
|
49
|
-
-
|
|
51
|
+
- How do I get API keys?
|
|
52
|
+
- How do I authenticate requests?
|
|
53
|
+
- How do I handle token refresh?
|
|
54
|
+
|
|
55
|
+
error_handling:
|
|
56
|
+
- What are the error codes?
|
|
57
|
+
- How do I retry failed requests?
|
|
50
58
|
|
|
51
|
-
provider: openai
|
|
59
|
+
provider: openai
|
|
52
60
|
model: gpt-4o-mini
|
|
53
61
|
```
|
|
54
62
|
|
|
55
|
-
##
|
|
63
|
+
## Rich Feedback
|
|
64
|
+
|
|
65
|
+
Instead of simple YES/NO, get actionable insights:
|
|
66
|
+
|
|
67
|
+
```
|
|
68
|
+
⚠️ How do I authenticate?
|
|
69
|
+
Confidence: 60%
|
|
70
|
+
Searched: 3 pages
|
|
71
|
+
Missing:
|
|
72
|
+
- API key generation steps
|
|
73
|
+
- Token refresh documentation
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
## Multi-Model Testing
|
|
77
|
+
|
|
78
|
+
Test against multiple AI models using CI/CD:
|
|
56
79
|
|
|
57
80
|
```yaml
|
|
58
81
|
# .github/workflows/docs.yml
|
|
59
|
-
name: Documentation
|
|
82
|
+
name: Documentation Validation
|
|
60
83
|
on: [pull_request]
|
|
61
84
|
|
|
62
85
|
jobs:
|
|
63
|
-
|
|
86
|
+
validate:
|
|
87
|
+
strategy:
|
|
88
|
+
matrix:
|
|
89
|
+
include:
|
|
90
|
+
- provider: openai
|
|
91
|
+
model: gpt-4o
|
|
92
|
+
- provider: openai
|
|
93
|
+
model: gpt-4o-mini
|
|
94
|
+
- provider: anthropic
|
|
95
|
+
model: claude-3-opus
|
|
96
|
+
|
|
64
97
|
runs-on: ubuntu-latest
|
|
65
98
|
steps:
|
|
66
99
|
- uses: actions/checkout@v3
|
|
67
100
|
- run: npx docworks check
|
|
68
101
|
env:
|
|
102
|
+
PROVIDER: ${{ matrix.provider }}
|
|
103
|
+
MODEL: ${{ matrix.model }}
|
|
69
104
|
OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
|
|
105
|
+
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
|
|
70
106
|
```
|
|
71
107
|
|
|
72
|
-
##
|
|
108
|
+
## Supported Documentation
|
|
73
109
|
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
docworks init --platform mintlify
|
|
77
|
-
docworks init --platform readme
|
|
78
|
-
docworks init --platform gitbook
|
|
110
|
+
- **Public docs** - Any site with [llms.txt](https://llmstxt.org)
|
|
111
|
+
- **Platforms** - Mintlify, ReadMe, GitBook
|
|
79
112
|
|
|
80
|
-
|
|
81
|
-
docworks init --platform local
|
|
82
|
-
```
|
|
113
|
+
## Commands
|
|
83
114
|
|
|
84
|
-
|
|
115
|
+
```bash
|
|
116
|
+
# Initialize config
|
|
117
|
+
docworks init
|
|
85
118
|
|
|
86
|
-
|
|
119
|
+
# Validate all journeys
|
|
120
|
+
docworks check
|
|
87
121
|
|
|
88
|
-
|
|
89
|
-
|
|
122
|
+
# Test specific journey
|
|
123
|
+
docworks check --journey authentication
|
|
90
124
|
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
- How do I deploy?
|
|
94
|
-
- Where are the runbooks?
|
|
125
|
+
# Output as JSON
|
|
126
|
+
docworks check --format json
|
|
95
127
|
```
|
|
96
128
|
|
|
97
|
-
##
|
|
98
|
-
|
|
99
|
-
**Q: What if my platform doesn't have llms.txt?**
|
|
100
|
-
A: Use local mode by pointing to your docs folder, or ask your platform to support [llmstxt.org](https://llmstxt.org)
|
|
101
|
-
|
|
102
|
-
**Q: How does it fetch online docs?**
|
|
103
|
-
A: DocWorks looks for `/llms.txt` at your docs URL, which lists all documentation pages
|
|
129
|
+
## Why DocWorks?
|
|
104
130
|
|
|
105
|
-
**
|
|
106
|
-
|
|
131
|
+
- **Real-world testing** - AI navigates docs like developers do
|
|
132
|
+
- **Actionable feedback** - Know exactly what to fix
|
|
133
|
+
- **CI/CD ready** - Catch doc regressions before merge
|
|
134
|
+
- **Progressive** - Start simple, add complexity as needed
|
|
107
135
|
|
|
108
136
|
## License
|
|
109
137
|
|
package/dist/commands/check.d.ts
CHANGED
|
@@ -1,7 +1,8 @@
|
|
|
1
1
|
export declare function check(options: {
|
|
2
2
|
config: string;
|
|
3
3
|
journey?: string;
|
|
4
|
-
|
|
5
|
-
|
|
4
|
+
format?: 'terminal' | 'json';
|
|
5
|
+
provider?: string;
|
|
6
|
+
model?: string;
|
|
6
7
|
}): Promise<void>;
|
|
7
8
|
//# sourceMappingURL=check.d.ts.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"check.d.ts","sourceRoot":"","sources":["../../src/commands/check.ts"],"names":[],"mappings":"AAMA,wBAAsB,KAAK,CAAC,OAAO,EAAE;IACnC,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,
|
|
1
|
+
{"version":3,"file":"check.d.ts","sourceRoot":"","sources":["../../src/commands/check.ts"],"names":[],"mappings":"AAMA,wBAAsB,KAAK,CAAC,OAAO,EAAE;IACnC,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,MAAM,CAAC,EAAE,UAAU,GAAG,MAAM,CAAA;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,KAAK,CAAC,EAAE,MAAM,CAAA;CACf,GAAG,OAAO,CAAC,IAAI,CAAC,CA6FhB"}
|
package/dist/commands/check.js
CHANGED
|
@@ -1,11 +1,16 @@
|
|
|
1
1
|
import { loadConfig } from '../utils/config.js';
|
|
2
|
-
import {
|
|
2
|
+
import { fetchDocumentation } from '../sources/source.js';
|
|
3
3
|
import { validateJourneys, validateQuestions } from '../core/validator.js';
|
|
4
4
|
import { formatReport, formatJSON } from '../utils/reporter.js';
|
|
5
5
|
export async function check(options) {
|
|
6
6
|
try {
|
|
7
7
|
// Load config
|
|
8
8
|
const config = await loadConfig(options.config || 'docworks.yml');
|
|
9
|
+
// Apply overrides
|
|
10
|
+
if (options.provider)
|
|
11
|
+
config.provider = options.provider;
|
|
12
|
+
if (options.model)
|
|
13
|
+
config.model = options.model;
|
|
9
14
|
// Validate API key
|
|
10
15
|
const apiKey = process.env.OPENAI_API_KEY ||
|
|
11
16
|
process.env.ANTHROPIC_API_KEY ||
|
|
@@ -19,15 +24,29 @@ export async function check(options) {
|
|
|
19
24
|
}
|
|
20
25
|
// Load documentation
|
|
21
26
|
console.log('📚 Loading documentation...');
|
|
22
|
-
const
|
|
23
|
-
console.log(`Source: ${
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
+
const { content: docs, name: sourceName } = await fetchDocumentation(config.source);
|
|
28
|
+
console.log(`Source: ${sourceName}\n`);
|
|
29
|
+
// Prepare all validations
|
|
30
|
+
const allValidations = {};
|
|
31
|
+
// Add standalone questions as implicit "general" journey
|
|
32
|
+
if (config.questions) {
|
|
33
|
+
allValidations.general = config.questions;
|
|
34
|
+
}
|
|
35
|
+
// Add explicit journeys
|
|
36
|
+
if (config.journeys) {
|
|
37
|
+
Object.assign(allValidations, config.journeys);
|
|
38
|
+
}
|
|
39
|
+
// Check if we have anything to validate
|
|
40
|
+
if (Object.keys(allValidations).length === 0) {
|
|
41
|
+
console.error('❌ No questions or journeys found in config');
|
|
42
|
+
process.exit(1);
|
|
43
|
+
}
|
|
44
|
+
// Validate
|
|
45
|
+
console.log('🔍 Validating documentation...\n');
|
|
27
46
|
let results;
|
|
28
47
|
if (options.journey) {
|
|
29
48
|
// Validate single journey
|
|
30
|
-
const questions =
|
|
49
|
+
const questions = allValidations[options.journey];
|
|
31
50
|
if (!questions) {
|
|
32
51
|
console.error(`Journey "${options.journey}" not found`);
|
|
33
52
|
process.exit(1);
|
|
@@ -35,21 +54,21 @@ export async function check(options) {
|
|
|
35
54
|
console.log(`Journey: ${options.journey}`);
|
|
36
55
|
console.log('─'.repeat(40));
|
|
37
56
|
results = {
|
|
38
|
-
[options.journey]: await validateQuestions(questions, docs, apiKey,
|
|
57
|
+
[options.journey]: await validateQuestions(questions, docs, apiKey, config),
|
|
39
58
|
};
|
|
40
59
|
}
|
|
41
60
|
else {
|
|
42
|
-
// Validate all
|
|
43
|
-
results = await validateJourneys(
|
|
61
|
+
// Validate all
|
|
62
|
+
results = await validateJourneys(allValidations, docs, apiKey, config);
|
|
44
63
|
}
|
|
45
64
|
// Format output
|
|
46
65
|
if (options.format === 'json') {
|
|
47
|
-
console.log(formatJSON(results,
|
|
66
|
+
console.log(formatJSON(results, sourceName));
|
|
48
67
|
const hasFailures = Object.values(results).some((questions) => questions.some((q) => q.answerable === 'NO'));
|
|
49
68
|
process.exit(hasFailures ? 1 : 0);
|
|
50
69
|
}
|
|
51
70
|
else {
|
|
52
|
-
const exitCode = formatReport(results
|
|
71
|
+
const exitCode = formatReport(results);
|
|
53
72
|
process.exit(exitCode);
|
|
54
73
|
}
|
|
55
74
|
}
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"check.js","sourceRoot":"","sources":["../../src/commands/check.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAA;AAC/C,OAAO,EAAE,
|
|
1
|
+
{"version":3,"file":"check.js","sourceRoot":"","sources":["../../src/commands/check.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAA;AAC/C,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAA;AACzD,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAA;AAC1E,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AAE/D,MAAM,CAAC,KAAK,UAAU,KAAK,CAAC,OAM3B;IACC,IAAI,CAAC;QACH,cAAc;QACd,MAAM,MAAM,GAAG,MAAM,UAAU,CAAC,OAAO,CAAC,MAAM,IAAI,cAAc,CAAC,CAAA;QAEjE,kBAAkB;QAClB,IAAI,OAAO,CAAC,QAAQ;YAAE,MAAM,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAA;QACxD,IAAI,OAAO,CAAC,KAAK;YAAE,MAAM,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,CAAA;QAE/C,mBAAmB;QACnB,MAAM,MAAM,GACV,OAAO,CAAC,GAAG,CAAC,cAAc;YAC1B,OAAO,CAAC,GAAG,CAAC,iBAAiB;YAC7B,MAAM,CAAC,OAAO,CAAA;QAEhB,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,OAAO,CAAC,KAAK,CAAC,sBAAsB,CAAC,CAAA;YACrC,OAAO,CAAC,KAAK,CAAC,aAAa,CAAC,CAAA;YAC5B,OAAO,CAAC,KAAK,CAAC,gCAAgC,CAAC,CAAA;YAC/C,OAAO,CAAC,KAAK,CAAC,uCAAuC,CAAC,CAAA;YACtD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;QACjB,CAAC;QAED,qBAAqB;QACrB,OAAO,CAAC,GAAG,CAAC,6BAA6B,CAAC,CAAA;QAC1C,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,UAAU,EAAE,GAAG,MAAM,kBAAkB,CAClE,MAAM,CAAC,MAAM,CACd,CAAA;QACD,OAAO,CAAC,GAAG,CAAC,WAAW,UAAU,IAAI,CAAC,CAAA;QAEtC,0BAA0B;QAC1B,MAAM,cAAc,GAA6B,EAAE,CAAA;QAEnD,yDAAyD;QACzD,IAAI,MAAM,CAAC,SAAS,EAAE,CAAC;YACrB,cAAc,CAAC,OAAO,GAAG,MAAM,CAAC,SAAS,CAAA;QAC3C,CAAC;QAED,wBAAwB;QACxB,IAAI,MAAM,CAAC,QAAQ,EAAE,CAAC;YACpB,MAAM,CAAC,MAAM,CAAC,cAAc,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAA;QAChD,CAAC;QAED,wCAAwC;QACxC,IAAI,MAAM,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC7C,OAAO,CAAC,KAAK,CAAC,4CAA4C,CAAC,CAAA;YAC3D,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;QACjB,CAAC;QAED,WAAW;QACX,OAAO,CAAC,GAAG,CAAC,kCAAkC,CAAC,CAAA;QAE/C,IAAI,OAAuB,CAAA;QAE3B,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;YACpB,0BAA0B;YAC1B,MAAM,SAAS,GAAG,cAAc,CAAC,OAAO,CAAC,OAAO,CAAC,CAAA;YACjD,IAAI,CAAC,SAAS,EAAE,CAAC;gBACf,OAAO,CAAC,KAAK,CAAC,YAAY,OAAO,CAAC,OAAO,aAAa,CAAC,CAAA;gBACvD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;YACjB,CAAC;YAED,OAAO,CAAC,GAAG,CAAC,YAAY,OAAO,CAAC,OAAO,EAAE,CAAC,CAAA;YAC1C,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAA;YAE3B,OAAO,GAAG;gBACR,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,MAAM,iBAAiB,CACxC,SAAS,EACT,IAAI,EACJ,MAAM,EACN,MAAM,CACP;aACF,CAAA;QACH,CAAC;aAAM,CAAC;YACN,eAAe;YACf,OAAO,GAAG,MAAM,gBAAgB,CAAC,cAAc,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,CAAA;QACxE,CAAC;QAED,gBAAgB;QAChB,IAAI,OAAO,CAAC,MAAM,KAAK,MAAM,EAAE,CAAC;YAC9B,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC,CAAA;YAC5C,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,EAAE,CAC5D,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,KAAK,IAAI,CAAC,CAC7C,CAAA;YACD,OAAO,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;QACnC,CAAC;aAAM,CAAC;YACN,MAAM,QAAQ,GAAG,YAAY,CAAC,OAAO,CAAC,CAAA;YACtC,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAA;QACxB,CAAC;IACH,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,CAAC,KAAK,CAAC,UAAU,EAAG,KAAe,CAAC,OAAO,CAAC,CAAA;QACnD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;IACjB,CAAC;AACH,CAAC"}
|
package/dist/commands/init.d.ts
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/commands/init.ts"],"names":[],"mappings":"
|
|
1
|
+
{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/commands/init.ts"],"names":[],"mappings":"AAsCA,wBAAsB,IAAI,CAAC,OAAO,EAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAiCxE"}
|
package/dist/commands/init.js
CHANGED
|
@@ -1,71 +1,37 @@
|
|
|
1
1
|
import fs from 'fs';
|
|
2
2
|
const TEMPLATES = {
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
source: https://docs.example.com # or ./docs for local
|
|
3
|
+
simple: `# DocWorks Configuration
|
|
4
|
+
source: https://docs.example.com
|
|
6
5
|
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
- How do I run tests?
|
|
15
|
-
- How do I debug issues?
|
|
16
|
-
- Where can I get help?
|
|
6
|
+
# Simple list of questions to validate
|
|
7
|
+
questions:
|
|
8
|
+
- How do I authenticate?
|
|
9
|
+
- What are the rate limits?
|
|
10
|
+
- How do I get started?
|
|
11
|
+
- Where can I find examples?
|
|
12
|
+
- How do I handle errors?
|
|
17
13
|
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
14
|
+
# Provider configuration (supports environment variables)
|
|
15
|
+
provider: \${PROVIDER:-openai}
|
|
16
|
+
model: \${MODEL:-gpt-4o-mini}`,
|
|
17
|
+
journeys: `# DocWorks Configuration
|
|
18
|
+
source: https://docs.example.com
|
|
22
19
|
|
|
20
|
+
# Group questions by user journey
|
|
23
21
|
journeys:
|
|
24
|
-
|
|
25
|
-
-
|
|
26
|
-
-
|
|
27
|
-
-
|
|
22
|
+
authentication:
|
|
23
|
+
- How do I get API keys?
|
|
24
|
+
- How do I authenticate requests?
|
|
25
|
+
- What auth methods are supported?
|
|
28
26
|
|
|
29
|
-
|
|
30
|
-
-
|
|
31
|
-
- How
|
|
32
|
-
-
|
|
33
|
-
|
|
34
|
-
provider: openai
|
|
35
|
-
model: gpt-4o-mini`,
|
|
36
|
-
readme: `# DocWorks Configuration - ReadMe
|
|
37
|
-
source: https://docs.yourcompany.com # Your ReadMe docs URL
|
|
38
|
-
|
|
39
|
-
journeys:
|
|
40
|
-
developer_experience:
|
|
41
|
-
- Can I try the API interactively?
|
|
42
|
-
- Are there code examples?
|
|
43
|
-
- Is versioning documented?
|
|
44
|
-
|
|
45
|
-
provider: openai
|
|
46
|
-
model: gpt-4o-mini`,
|
|
47
|
-
gitbook: `# DocWorks Configuration - GitBook
|
|
48
|
-
source: https://docs.yourcompany.com # Your GitBook URL
|
|
49
|
-
|
|
50
|
-
journeys:
|
|
51
|
-
knowledge_base:
|
|
52
|
-
- Is content organized logically?
|
|
53
|
-
- Can I search effectively?
|
|
54
|
-
- Are guides comprehensive?
|
|
55
|
-
|
|
56
|
-
provider: openai
|
|
57
|
-
model: gpt-4o-mini`,
|
|
58
|
-
local: `# DocWorks Configuration - Local Documentation
|
|
59
|
-
source: ./docs # Path to your documentation folder
|
|
60
|
-
|
|
61
|
-
journeys:
|
|
62
|
-
getting_started:
|
|
63
|
-
- How do I get started?
|
|
64
|
-
- Where are examples?
|
|
65
|
-
- What are the prerequisites?
|
|
27
|
+
error_handling:
|
|
28
|
+
- What error codes exist?
|
|
29
|
+
- How should I handle rate limits?
|
|
30
|
+
- Where are error examples?
|
|
66
31
|
|
|
67
|
-
|
|
68
|
-
|
|
32
|
+
# Provider configuration (supports environment variables)
|
|
33
|
+
provider: \${PROVIDER:-openai}
|
|
34
|
+
model: \${MODEL:-gpt-4o-mini}`,
|
|
69
35
|
};
|
|
70
36
|
export async function init(options) {
|
|
71
37
|
console.log('🚀 Initializing DocWorks...\n');
|
|
@@ -75,11 +41,11 @@ export async function init(options) {
|
|
|
75
41
|
process.exit(1);
|
|
76
42
|
}
|
|
77
43
|
// Select template
|
|
78
|
-
const templateName = options.
|
|
44
|
+
const templateName = options.template || 'simple';
|
|
79
45
|
const template = TEMPLATES[templateName];
|
|
80
46
|
if (!template) {
|
|
81
47
|
console.error(`Unknown template: ${templateName}`);
|
|
82
|
-
console.log('Available:
|
|
48
|
+
console.log('Available: simple, journeys');
|
|
83
49
|
process.exit(1);
|
|
84
50
|
}
|
|
85
51
|
// Write config
|
|
@@ -88,9 +54,11 @@ export async function init(options) {
|
|
|
88
54
|
// Next steps
|
|
89
55
|
console.log('Next steps:');
|
|
90
56
|
console.log('1. Update the source URL to your documentation');
|
|
91
|
-
console.log('2. Customize the
|
|
57
|
+
console.log('2. Customize the questions for your needs');
|
|
92
58
|
console.log('3. Set your API key:');
|
|
93
59
|
console.log(' export OPENAI_API_KEY=sk-...');
|
|
60
|
+
console.log(' # or for Anthropic:');
|
|
61
|
+
console.log(' export ANTHROPIC_API_KEY=sk-ant-...');
|
|
94
62
|
console.log('4. Run validation:');
|
|
95
63
|
console.log(' docworks check');
|
|
96
64
|
}
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"init.js","sourceRoot":"","sources":["../../src/commands/init.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,IAAI,CAAA;AAEnB,MAAM,SAAS,GAAG;IAChB,
|
|
1
|
+
{"version":3,"file":"init.js","sourceRoot":"","sources":["../../src/commands/init.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,IAAI,CAAA;AAEnB,MAAM,SAAS,GAAG;IAChB,MAAM,EAAE;;;;;;;;;;;;;8BAaoB;IAE5B,QAAQ,EAAE;;;;;;;;;;;;;;;;;8BAiBkB;CAC7B,CAAA;AAED,MAAM,CAAC,KAAK,UAAU,IAAI,CAAC,OAA8B;IACvD,OAAO,CAAC,GAAG,CAAC,+BAA+B,CAAC,CAAA;IAE5C,wBAAwB;IACxB,IAAI,EAAE,CAAC,UAAU,CAAC,cAAc,CAAC,EAAE,CAAC;QAClC,OAAO,CAAC,GAAG,CAAC,iCAAiC,CAAC,CAAA;QAC9C,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;IACjB,CAAC;IAED,kBAAkB;IAClB,MAAM,YAAY,GAAG,OAAO,CAAC,QAAQ,IAAI,QAAQ,CAAA;IACjD,MAAM,QAAQ,GAAG,SAAS,CAAC,YAAsC,CAAC,CAAA;IAElE,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,OAAO,CAAC,KAAK,CAAC,qBAAqB,YAAY,EAAE,CAAC,CAAA;QAClD,OAAO,CAAC,GAAG,CAAC,6BAA6B,CAAC,CAAA;QAC1C,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;IACjB,CAAC;IAED,eAAe;IACf,EAAE,CAAC,aAAa,CAAC,cAAc,EAAE,QAAQ,CAAC,CAAA;IAC1C,OAAO,CAAC,GAAG,CAAC,0BAA0B,CAAC,CAAA;IAEvC,aAAa;IACb,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,CAAA;IAC1B,OAAO,CAAC,GAAG,CAAC,gDAAgD,CAAC,CAAA;IAC7D,OAAO,CAAC,GAAG,CAAC,2CAA2C,CAAC,CAAA;IACxD,OAAO,CAAC,GAAG,CAAC,sBAAsB,CAAC,CAAA;IACnC,OAAO,CAAC,GAAG,CAAC,iCAAiC,CAAC,CAAA;IAC9C,OAAO,CAAC,GAAG,CAAC,wBAAwB,CAAC,CAAA;IACrC,OAAO,CAAC,GAAG,CAAC,wCAAwC,CAAC,CAAA;IACrD,OAAO,CAAC,GAAG,CAAC,oBAAoB,CAAC,CAAA;IACjC,OAAO,CAAC,GAAG,CAAC,mBAAmB,CAAC,CAAA;AAClC,CAAC"}
|
package/dist/core/validator.d.ts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { ValidationResult, JourneyResults } from '../types/config.js';
|
|
2
|
-
export declare function validateJourneys(journeys: Record<string, string[]>, docs: string, apiKey: string,
|
|
3
|
-
export declare function validateQuestions(questions: string[], docs: string, apiKey: string,
|
|
1
|
+
import { ValidationResult, JourneyResults, DocWorksConfig } from '../types/config.js';
|
|
2
|
+
export declare function validateJourneys(journeys: Record<string, string[]>, docs: string, apiKey: string, config?: DocWorksConfig): Promise<JourneyResults>;
|
|
3
|
+
export declare function validateQuestions(questions: string[], docs: string, apiKey: string, config?: DocWorksConfig): Promise<ValidationResult[]>;
|
|
4
4
|
//# sourceMappingURL=validator.d.ts.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"validator.d.ts","sourceRoot":"","sources":["../../src/core/validator.ts"],"names":[],"mappings":"
|
|
1
|
+
{"version":3,"file":"validator.d.ts","sourceRoot":"","sources":["../../src/core/validator.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gBAAgB,EAChB,cAAc,EACd,cAAc,EACf,MAAM,oBAAoB,CAAA;AAG3B,wBAAsB,gBAAgB,CACpC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,EAClC,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,MAAM,CAAC,EAAE,cAAc,GACtB,OAAO,CAAC,cAAc,CAAC,CAQzB;AAED,wBAAsB,iBAAiB,CACrC,SAAS,EAAE,MAAM,EAAE,EACnB,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,MAAM,CAAC,EAAE,cAAc,GACtB,OAAO,CAAC,gBAAgB,EAAE,CAAC,CA+B7B"}
|
package/dist/core/validator.js
CHANGED
|
@@ -1,38 +1,19 @@
|
|
|
1
|
-
import
|
|
2
|
-
|
|
3
|
-
import { getCached, setCached } from './cache.js';
|
|
4
|
-
export async function validateJourneys(journeys, docs, apiKey, useCache = true) {
|
|
1
|
+
import { callProvider } from '../providers/index.js';
|
|
2
|
+
export async function validateJourneys(journeys, docs, apiKey, config) {
|
|
5
3
|
const results = {};
|
|
6
4
|
for (const [journey, questions] of Object.entries(journeys)) {
|
|
7
|
-
results[journey] = await validateQuestions(questions, docs, apiKey,
|
|
5
|
+
results[journey] = await validateQuestions(questions, docs, apiKey, config);
|
|
8
6
|
}
|
|
9
7
|
return results;
|
|
10
8
|
}
|
|
11
|
-
export async function validateQuestions(questions, docs, apiKey,
|
|
9
|
+
export async function validateQuestions(questions, docs, apiKey, config) {
|
|
12
10
|
const results = [];
|
|
11
|
+
const provider = config?.provider || 'openai';
|
|
12
|
+
const model = config?.model || 'gpt-4o-mini';
|
|
13
13
|
for (const question of questions) {
|
|
14
|
-
//
|
|
15
|
-
const
|
|
16
|
-
|
|
17
|
-
.update(question + docs.substring(0, 1000)) // Use first 1KB for cache key
|
|
18
|
-
.digest('hex');
|
|
19
|
-
let result = null;
|
|
20
|
-
// Try cache first
|
|
21
|
-
if (useCache) {
|
|
22
|
-
result = getCached(cacheKey);
|
|
23
|
-
}
|
|
24
|
-
// If not cached, check with AI
|
|
25
|
-
if (!result) {
|
|
26
|
-
const validation = await checkAnswerability(question, docs, apiKey);
|
|
27
|
-
result = {
|
|
28
|
-
question,
|
|
29
|
-
...validation,
|
|
30
|
-
};
|
|
31
|
-
// Cache the result
|
|
32
|
-
if (useCache) {
|
|
33
|
-
setCached(cacheKey, result);
|
|
34
|
-
}
|
|
35
|
-
}
|
|
14
|
+
// Check with AI
|
|
15
|
+
const validation = await callProvider(provider, model, apiKey, question, docs);
|
|
16
|
+
const result = validation;
|
|
36
17
|
results.push(result);
|
|
37
18
|
// Show progress
|
|
38
19
|
const icon = result.answerable === 'YES'
|
|
@@ -40,7 +21,7 @@ export async function validateQuestions(questions, docs, apiKey, useCache = true
|
|
|
40
21
|
: result.answerable === 'PARTIAL'
|
|
41
22
|
? '⚠️'
|
|
42
23
|
: '❌';
|
|
43
|
-
console.log(` ${icon} ${question}`);
|
|
24
|
+
console.log(` ${icon} ${question} (${Math.round(result.confidence * 100)}%)`);
|
|
44
25
|
}
|
|
45
26
|
return results;
|
|
46
27
|
}
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"validator.js","sourceRoot":"","sources":["../../src/core/validator.ts"],"names":[],"mappings":"
|
|
1
|
+
{"version":3,"file":"validator.js","sourceRoot":"","sources":["../../src/core/validator.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAA;AAEpD,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,QAAkC,EAClC,IAAY,EACZ,MAAc,EACd,MAAuB;IAEvB,MAAM,OAAO,GAAmB,EAAE,CAAA;IAElC,KAAK,MAAM,CAAC,OAAO,EAAE,SAAS,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC5D,OAAO,CAAC,OAAO,CAAC,GAAG,MAAM,iBAAiB,CAAC,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,CAAA;IAC7E,CAAC;IAED,OAAO,OAAO,CAAA;AAChB,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,SAAmB,EACnB,IAAY,EACZ,MAAc,EACd,MAAuB;IAEvB,MAAM,OAAO,GAAuB,EAAE,CAAA;IACtC,MAAM,QAAQ,GAAG,MAAM,EAAE,QAAQ,IAAI,QAAQ,CAAA;IAC7C,MAAM,KAAK,GAAG,MAAM,EAAE,KAAK,IAAI,aAAa,CAAA;IAE5C,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;QACjC,gBAAgB;QAChB,MAAM,UAAU,GAAG,MAAM,YAAY,CACnC,QAAQ,EACR,KAAK,EACL,MAAM,EACN,QAAQ,EACR,IAAI,CACL,CAAA;QACD,MAAM,MAAM,GAAG,UAAU,CAAA;QAEzB,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;QAEpB,gBAAgB;QAChB,MAAM,IAAI,GACR,MAAM,CAAC,UAAU,KAAK,KAAK;YACzB,CAAC,CAAC,GAAG;YACL,CAAC,CAAC,MAAM,CAAC,UAAU,KAAK,SAAS;gBAC/B,CAAC,CAAC,IAAI;gBACN,CAAC,CAAC,GAAG,CAAA;QACX,OAAO,CAAC,GAAG,CACT,KAAK,IAAI,IAAI,QAAQ,KAAK,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,UAAU,GAAG,GAAG,CAAC,IAAI,CAClE,CAAA;IACH,CAAC;IAED,OAAO,OAAO,CAAA;AAChB,CAAC"}
|
package/dist/index.js
CHANGED
|
@@ -2,7 +2,6 @@
|
|
|
2
2
|
import { Command } from 'commander';
|
|
3
3
|
import { init } from './commands/init.js';
|
|
4
4
|
import { check } from './commands/check.js';
|
|
5
|
-
import { test } from './commands/test.js';
|
|
6
5
|
const program = new Command();
|
|
7
6
|
program
|
|
8
7
|
.name('docworks')
|
|
@@ -11,21 +10,16 @@ program
|
|
|
11
10
|
program
|
|
12
11
|
.command('init')
|
|
13
12
|
.description('Initialize DocWorks configuration')
|
|
14
|
-
.option('-
|
|
13
|
+
.option('-t, --template <type>', 'Template: simple or journeys', 'simple')
|
|
15
14
|
.action(init);
|
|
16
15
|
program
|
|
17
16
|
.command('check')
|
|
18
|
-
.description('Validate documentation
|
|
17
|
+
.description('Validate documentation')
|
|
19
18
|
.option('-c, --config <path>', 'Config file', 'docworks.yml')
|
|
20
19
|
.option('-j, --journey <name>', 'Check specific journey')
|
|
21
|
-
.option('--
|
|
22
|
-
.option('
|
|
20
|
+
.option('-f, --format <type>', 'Output: json or terminal', 'terminal')
|
|
21
|
+
.option('--provider <name>', 'Override provider')
|
|
22
|
+
.option('--model <name>', 'Override model')
|
|
23
23
|
.action(check);
|
|
24
|
-
program
|
|
25
|
-
.command('test')
|
|
26
|
-
.description('Test if AI can complete tasks using your docs')
|
|
27
|
-
.option('-c, --config <path>', 'Config file', 'docworks.yml')
|
|
28
|
-
.option('--ai <task>', 'Task for AI to complete')
|
|
29
|
-
.action(test);
|
|
30
24
|
program.parse();
|
|
31
25
|
//# sourceMappingURL=index.js.map
|
package/dist/index.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AACnC,OAAO,EAAE,IAAI,EAAE,MAAM,oBAAoB,CAAA;AACzC,OAAO,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAA;
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AACnC,OAAO,EAAE,IAAI,EAAE,MAAM,oBAAoB,CAAA;AACzC,OAAO,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAA;AAE3C,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAA;AAE7B,OAAO;KACJ,IAAI,CAAC,UAAU,CAAC;KAChB,WAAW,CAAC,6CAA6C,CAAC;KAC1D,OAAO,CAAC,OAAO,CAAC,CAAA;AAEnB,OAAO;KACJ,OAAO,CAAC,MAAM,CAAC;KACf,WAAW,CAAC,mCAAmC,CAAC;KAChD,MAAM,CAAC,uBAAuB,EAAE,8BAA8B,EAAE,QAAQ,CAAC;KACzE,MAAM,CAAC,IAAI,CAAC,CAAA;AAEf,OAAO;KACJ,OAAO,CAAC,OAAO,CAAC;KAChB,WAAW,CAAC,wBAAwB,CAAC;KACrC,MAAM,CAAC,qBAAqB,EAAE,aAAa,EAAE,cAAc,CAAC;KAC5D,MAAM,CAAC,sBAAsB,EAAE,wBAAwB,CAAC;KACxD,MAAM,CAAC,qBAAqB,EAAE,0BAA0B,EAAE,UAAU,CAAC;KACrE,MAAM,CAAC,mBAAmB,EAAE,mBAAmB,CAAC;KAChD,MAAM,CAAC,gBAAgB,EAAE,gBAAgB,CAAC;KAC1C,MAAM,CAAC,KAAK,CAAC,CAAA;AAEhB,OAAO,CAAC,KAAK,EAAE,CAAA"}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/providers/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAA;AAoCrD,wBAAsB,YAAY,CAChC,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,gBAAgB,CAAC,CAgE3B"}
|