Repository navigation
test: check the code samples in the docs against the SDKs and policies - #126
Merged
Merged
Conversation
No test ran the docs' code samples, and the page by page audit found samples that could never have worked. Two tests now check what such samples get wrong, without requiring every fragment to be a whole program: - tests/architecture/docs-code-samples.test.ts: TypeScript samples that import @parmana/sdk are type checked against the built SDK (only missing exports, methods, properties and wrong arguments fail); every policy a request sample names exists and declares a human approval; every signal it sends is declared by that policy. - python/tests/test_docs_code_samples.py: Python samples that import parmana are checked with mypy for the same kinds of mismatch. Both were checked against a deliberately broken sample (each kind of mistake is reported) and pass on the docs after fixing what they found: vendor-payment 2.0.0 in the Python SDK page and a stale captured output in the TypeScript quickstart (captured again, 2026-10-02), and health()["status"] in the Python production guide (health() returns a dict). The Python workflow now also runs on docs changes. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Automations to automatically generate PRs for you. |
This branch was successfully deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
The docs' code samples were not run or type checked by anything, and the page by page audit (#119 to #125) found samples that could never have worked. Two tests now check what such samples get wrong, without requiring every fragment to be a complete program.
tests/architecture/docs-code-samples.test.ts(runs withnpm test):@parmana/sdk(40+) are type checked against the built SDK in memory. Only diagnostics meaning the sample disagrees with the SDK fail: missing export, method or property, unknown option, wrong arguments. A name the fragment assumes is in scope does not. No DOM lib, soeventorfetchin a sample is not the browser's.nameandversion, in TypeScript, JSON orPolicyReference(...)) exists and declaresapprovalSignals, so it loads.approvalArtifact).python/tests/test_docs_code_samples.py(runs in the Python SDK workflow): Python samples that importparmanaare checked with mypy;attr-defined,call-arg,arg-typeandunion-attrfail.docs/site/**changes.Checked both ways
apiKy,apikey), a missing method (executeTransaction,executeee),customer-refund1.0.0, and an undeclared signal (customerVerified).vendor-payment2.0.0 (refused) on the Python SDK page; a captured output in the TypeScript quickstart from 2026-09-14 under 2.0.0, captured again from example 06 on 2026-10-02; andhealth.statusin the Python production guide, wherehealth()returns a dict.🤖 Generated with Claude Code