docworks 0.15.0 → 0.17.0-next.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Caio Pizzol
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -27,6 +27,8 @@ DocWorks tests documentation the way developers actually use it - by having AI s
 
 ## Configuration
 
+See [`schema.yaml`](./schema.yaml) for the complete configuration schema with validation rules.
+
 ### Simple Questions
 
 ```yaml
@@ -38,7 +40,7 @@ questions:
   - What are the rate limits?
   - Where are code examples?
 
-provider: openai
+provider: openai # Currently only OpenAI supported
 model: gpt-4o-mini
 ```
 
@@ -61,6 +63,28 @@ provider: openai
 model: gpt-4o-mini
 ```
 
+### Configurable Thresholds
+
+Set pass/fail criteria to match your documentation maturity:
+
+```yaml
+source: https://docs.yourcompany.com
+
+# Global threshold - fail if less than 85% questions are answerable
+threshold: 85
+
+journeys:
+  authentication:
+    threshold: 100 # Critical path - must be perfect
+    questions:
+      - How do I get API keys?
+      - How do I authenticate?
+
+  examples: # Uses global 85% threshold
+    - Where are code samples?
+    - Are there tutorials?
+```
+
 ## Rich Feedback
 
 Instead of simple YES/NO, get actionable insights:
@@ -72,40 +96,59 @@ Instead of simple YES/NO, get actionable insights:
    Missing:
      - API key generation steps
      - Token refresh documentation
+
+Journey: authentication
+  Score: 75% (Threshold: 100%)
+  ❌ FAILED - Below required threshold
 ```
 
-## Multi-Model Testing
+## CI/CD Integration
 
-Test against multiple AI models using CI/CD:
+### Progressive Validation
+
+Different thresholds for different environments:
 
 ```yaml
 # .github/workflows/docs.yml
 name: Documentation Validation
-on: [pull_request]
+on: [pull_request, push]
 
 jobs:
-  validate:
-    strategy:
-      matrix:
-        include:
-          - provider: openai
-            model: gpt-4o
-          - provider: openai
-            model: gpt-4o-mini
-          - provider: anthropic
-            model: claude-3-opus
+  validate-pr:
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Validate PR docs (lenient)
+        run: npx docworks check --threshold 70
+        env:
+          DOCWORKS_SOURCE: https://preview-${{ github.event.pull_request.number }}.docs.example.com
+          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
 
+  validate-production:
+    if: github.ref == 'refs/heads/main'
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v3
-      - run: npx docworks check
+
+      - name: Validate production docs (strict)
+        run: npx docworks check --threshold 95
         env:
-          PROVIDER: ${{ matrix.provider }}
-          MODEL: ${{ matrix.model }}
+          DOCWORKS_SOURCE: https://docs.example.com
           OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
-          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
 ```
 
+## Supported Providers
+
+| Provider  | Status         | Models                             |
+| --------- | -------------- | ---------------------------------- |
+| OpenAI    | ✅ Supported   | gpt-4o, gpt-4o-mini                |
+| Anthropic | 🚧 Coming Soon | claude-3.7-sonnet, claude-4-sonnet |
+| Google    | 🚧 Coming Soon | gemini-pro                         |
+
+**Want to add a provider?** PRs welcome! See [`src/providers/index.ts`](./src/providers/index.ts).
+
 ## Supported Documentation
 
 - **Public docs** - Any site with [llms.txt](https://llmstxt.org)
@@ -117,23 +160,62 @@ jobs:
 # Initialize config
 docworks init
 
-# Validate all journeys
+# Validate all journeys (uses config threshold or defaults to 100%)
 docworks check
 
+# Override threshold via command line
+docworks check --threshold 80
+
 # Test specific journey
 docworks check --journey authentication
 
-# Output as JSON
+# Output as JSON (includes threshold data)
 docworks check --format json
 ```
 
+## Exit Codes
+
+- `0` - All thresholds met ✅
+- `1` - Below threshold ❌
+
+```bash
+# Strict validation - fail on any missing docs
+docworks check --threshold 100
+
+# Allow 20% missing during initial setup
+docworks check --threshold 80
+```
+
+## Progressive Adoption
+
+Start lenient and increase strictness as your documentation improves:
+
+1. **Initial Setup** - `threshold: 60` (allow gaps while building)
+2. **Development** - `threshold: 80` (most questions answered)
+3. **Staging** - `threshold: 90` (nearly complete)
+4. **Production** - `threshold: 95-100` (comprehensive docs)
+
+## Requirements
+
+- Node.js 16+
+- OpenAI API key with web search capabilities
+
+## Contributing
+
+Contributions welcome! We're especially looking for:
+
+- Additional provider implementations (Anthropic, Google)
+- Documentation platform integrations
+- Journey templates for common use cases
+
 ## Why DocWorks?
 
 - **Real-world testing** - AI navigates docs like developers do
+- **Configurable strictness** - Match your documentation maturity
 - **Actionable feedback** - Know exactly what to fix
-- **CI/CD ready** - Catch doc regressions before merge
+- **CI/CD ready** - Different thresholds for PR vs production
 - **Progressive** - Start simple, add complexity as needed
 
 ## License
 
-MIT
+MIT - See [LICENSE](./LICENSE) for details

package/dist/providers/index.d.ts.map

@@ -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"}
+{"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,CAkE3B"}

package/dist/providers/index.js

@@ -83,10 +83,10 @@ Instructions:
                 };
             }
         }
-        case 'anthropic': {
-            // Similar implementation
-            throw new Error('Anthropic not yet implemented');
-        }
+        // Future providers - PRs welcome!
+        case 'anthropic':
+        case 'google':
+            throw new Error(`${provider} provider coming soon. Currently only 'openai' is supported.`);
         default:
             throw new Error(`Unknown provider: ${provider}`);
     }

package/dist/providers/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/providers/index.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,QAAQ,CAAA;AAG3B,MAAM,iBAAiB,GAAG;IACxB,IAAI,EAAE,aAAsB;IAC5B,IAAI,EAAE,gBAAgB;IACtB,MAAM,EAAE;QACN,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE;YACV,UAAU,EAAE;gBACV,IAAI,EAAE,QAAQ;gBACd,IAAI,EAAE,CAAC,KAAK,EAAE,SAAS,EAAE,IAAI,CAAC;aAC/B;YACD,UAAU,EAAE;gBACV,IAAI,EAAE,QAAQ;gBACd,WAAW,EAAE,sBAAsB;aACpC;YACD,IAAI,EAAE;gBACJ,IAAI,EAAE,OAAO;gBACb,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;gBACzB,WAAW,EAAE,6BAA6B;aAC3C;YACD,MAAM,EAAE;gBACN,IAAI,EAAE,QAAQ;gBACd,WAAW,EAAE,mBAAmB;aACjC;YACD,OAAO,EAAE;gBACP,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC;gBACvB,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;gBACzB,WAAW,EAAE,mDAAmD;aACjE;SACF;QACD,QAAQ,EAAE,CAAC,YAAY,EAAE,YAAY,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,CAAC;QACnE,oBAAoB,EAAE,KAAK;KAC5B;CACF,CAAA;AAED,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,QAAgB,EAChB,KAAa,EACb,MAAc,EACd,QAAgB,EAChB,IAAY;IAEZ,MAAM,MAAM,GAAG;EACf,IAAI;;sCAEgC,QAAQ;;;;;;qCAMT,CAAA;IAEnC,QAAQ,QAAQ,EAAE,CAAC;QACjB,KAAK,QAAQ,CAAC,CAAC,CAAC;YACd,MAAM,MAAM,GAAG,IAAI,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC,CAAA;YAErC,IAAI,CAAC;gBACH,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC;oBAC7C,KAAK;oBACL,KAAK,EAAE,MAAM;oBACb,KAAK,EAAE;wBACL;4BACE,IAAI,EAAE,oBAAoB;yBAC3B;qBACF;oBACD,WAAW,EAAE,UAAU;oBACvB,IAAI,EAAE;wBACJ,MAAM,EAAE,iBAAiB;qBAC1B;iBACF,CAAC,CAAA;gBAEF,MAAM,OAAO,GAAG,QAAQ,CAAC,WAAW,CAAA;gBACpC,IAAI,CAAC,OAAO,EAAE,CAAC;oBACb,MAAM,IAAI,KAAK,CAAC,iCAAiC,CAAC,CAAA;gBACpD,CAAC;gBAED,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAA;gBAElC,OAAO;oBACL,QAAQ;oBACR,GAAG,MAAM;iBACV,CAAA;YACH,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,OAAO,CAAC,KAAK,CAAC,mBAAmB,EAAE,KAAK,CAAC,CAAA;gBACzC,oBAAoB;gBACpB,OAAO;oBACL,QAAQ;oBACR,UAAU,EAAE,IAAI;oBAChB,UAAU,EAAE,CAAC;oBACb,IAAI,EAAE,EAAE;oBACR,MAAM,EAAE,qCAAqC;oBAC7C,OAAO,EAAE,CAAC,+BAA+B,CAAC;iBAC3C,CAAA;YACH,CAAC;QACH,CAAC;QAED,KAAK,WAAW,CAAC,CAAC,CAAC;YACjB,yBAAyB;YACzB,MAAM,IAAI,KAAK,CAAC,+BAA+B,CAAC,CAAA;QAClD,CAAC;QAED;YACE,MAAM,IAAI,KAAK,CAAC,qBAAqB,QAAQ,EAAE,CAAC,CAAA;IACpD,CAAC;AACH,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/providers/index.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,QAAQ,CAAA;AAG3B,MAAM,iBAAiB,GAAG;IACxB,IAAI,EAAE,aAAsB;IAC5B,IAAI,EAAE,gBAAgB;IACtB,MAAM,EAAE;QACN,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE;YACV,UAAU,EAAE;gBACV,IAAI,EAAE,QAAQ;gBACd,IAAI,EAAE,CAAC,KAAK,EAAE,SAAS,EAAE,IAAI,CAAC;aAC/B;YACD,UAAU,EAAE;gBACV,IAAI,EAAE,QAAQ;gBACd,WAAW,EAAE,sBAAsB;aACpC;YACD,IAAI,EAAE;gBACJ,IAAI,EAAE,OAAO;gBACb,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;gBACzB,WAAW,EAAE,6BAA6B;aAC3C;YACD,MAAM,EAAE;gBACN,IAAI,EAAE,QAAQ;gBACd,WAAW,EAAE,mBAAmB;aACjC;YACD,OAAO,EAAE;gBACP,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC;gBACvB,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;gBACzB,WAAW,EAAE,mDAAmD;aACjE;SACF;QACD,QAAQ,EAAE,CAAC,YAAY,EAAE,YAAY,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,CAAC;QACnE,oBAAoB,EAAE,KAAK;KAC5B;CACF,CAAA;AAED,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,QAAgB,EAChB,KAAa,EACb,MAAc,EACd,QAAgB,EAChB,IAAY;IAEZ,MAAM,MAAM,GAAG;EACf,IAAI;;sCAEgC,QAAQ;;;;;;qCAMT,CAAA;IAEnC,QAAQ,QAAQ,EAAE,CAAC;QACjB,KAAK,QAAQ,CAAC,CAAC,CAAC;YACd,MAAM,MAAM,GAAG,IAAI,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC,CAAA;YAErC,IAAI,CAAC;gBACH,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC;oBAC7C,KAAK;oBACL,KAAK,EAAE,MAAM;oBACb,KAAK,EAAE;wBACL;4BACE,IAAI,EAAE,oBAAoB;yBAC3B;qBACF;oBACD,WAAW,EAAE,UAAU;oBACvB,IAAI,EAAE;wBACJ,MAAM,EAAE,iBAAiB;qBAC1B;iBACF,CAAC,CAAA;gBAEF,MAAM,OAAO,GAAG,QAAQ,CAAC,WAAW,CAAA;gBACpC,IAAI,CAAC,OAAO,EAAE,CAAC;oBACb,MAAM,IAAI,KAAK,CAAC,iCAAiC,CAAC,CAAA;gBACpD,CAAC;gBAED,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAA;gBAElC,OAAO;oBACL,QAAQ;oBACR,GAAG,MAAM;iBACV,CAAA;YACH,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,OAAO,CAAC,KAAK,CAAC,mBAAmB,EAAE,KAAK,CAAC,CAAA;gBACzC,oBAAoB;gBACpB,OAAO;oBACL,QAAQ;oBACR,UAAU,EAAE,IAAI;oBAChB,UAAU,EAAE,CAAC;oBACb,IAAI,EAAE,EAAE;oBACR,MAAM,EAAE,qCAAqC;oBAC7C,OAAO,EAAE,CAAC,+BAA+B,CAAC;iBAC3C,CAAA;YACH,CAAC;QACH,CAAC;QAED,kCAAkC;QAClC,KAAK,WAAW,CAAC;QACjB,KAAK,QAAQ;YACX,MAAM,IAAI,KAAK,CACb,GAAG,QAAQ,8DAA8D,CAC1E,CAAA;QAEH;YACE,MAAM,IAAI,KAAK,CAAC,qBAAqB,QAAQ,EAAE,CAAC,CAAA;IACpD,CAAC;AACH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docworks",
-  "version": "0.15.0",
+  "version": "0.17.0-next.1",
   "description": "Ensure your docs work for developers and AI",
   "type": "module",
   "main": "dist/index.js",