{"schemaVersion":1,"title":"Compatibility evidence","url":"https://appgram.github.io/docsy/versions/current/es/guides/reference/compatibility","markdownUrl":"https://appgram.github.io/docsy/format-md/versions/current/es/guides/reference/compatibility","jsonUrl":"https://appgram.github.io/docsy/agent/pages/versions/current/es/guides/reference/compatibility.json","version":"current","locale":"es","markdown":"# Compatibility evidence\n\nReproduce real-library imports and understand exactly what the tests do and do not establish.\n\nWritten by: [nedimf](https://github.com/nedimf), [AppGram](https://appgram.dev)\n\nDocsy distinguishes **format coverage** from **production compatibility**. Twenty-language teaching fixtures are genuine generator output, but they cannot establish that every real library or generator version works.\n\n## Larger real-library imports\n\nRun this inside the private template checkout after `npm ci`:\n\n```bash\nnpm run test:imports:real\n```\n\nThe script copies installed upstream sources without modifying them, invokes actual TypeDoc/JSDoc generators, imports the resulting artifacts through Docsy's native adapters, and asserts representative symbols, declarations, parameters, and unique IDs. It also builds a standalone test portal with all three references and checks the rendered site's links and anchors. Source/output hashes and commands are written to `.docsy/real-projects/report.json`; large outputs remain local and ignored by Git.\n\n| Project tested | Actual input | Generator | Imported symbols | Imported examples |\n| --- | --- | --- | ---: | ---: |\n| Zod 3.25.76 | Complete v3 source entry and dependencies | TypeDoc 0.28.20 | 2,497 | 0 |\n| YAML 2.9.1 | Published declaration entry and dependencies | TypeDoc 0.28.20 | 617 | 0 |\n| Lodash 4.18.1 | Complete distributed `lodash.js` | JSDoc 4.0.5 | 393 | 303 |\n\nCounts describe these pinned inputs, not a guaranteed count for future versions. Zod and YAML expose no `@example` blocks through these entry points; Docsy does not invent examples. TypeDoc uses `skipErrorChecking` for artifact generation: this is an ingestion test, not certification of upstream type-checking. Upstream licenses remain in the copied input trees.\n\nSource snapshots under `sources/` are ingestion data, excluded from the portal's TypeScript project. They may reference files that are not part of the docs export. Validate and type-check the actual SDK in its own build pipeline; portal validation does not replace that work.\n\nThese tests cover three substantial JavaScript/TypeScript libraries and two native formats. The other eighteen source languages still rely on smaller real-generator fixtures. Expand external-project coverage before promising broad production compatibility. Imported examples are not automatically executed.\n\nThe stress build also exposes a current scaling limit: a complete SDK is rendered as one reference page. Zod's test page is roughly 6.9 MB of uncompressed HTML, YAML 1.6 MB, and Lodash 2.3 MB. A successful build is not a page-performance endorsement; large SDKs need carefully scoped inputs today, and symbol-level pagination is still future work.\n\n## Migration evidence\n\nThe public [Mintlify starter](https://github.com/mintlify/starter/tree/8dc589095a85335165d18ed0aa5d273360dffd04) was tested at commit `8dc589095a85335165d18ed0aa5d273360dffd04`: two articles, two local logos, internal links, Tip, Cards, Steps, and original-path redirects. The importer converts supported components and reports manual mapping for global/header/SEO behavior. This proves that bounded starter export, not all Mintlify sites. See **Migrate from Mintlify**.\n\n## Maintenance evidence and boundary\n\nMaintenance tests exercise structural OpenAPI changes, stale-example detection, edit-scope guards, local assertion commands, and draft-PR publishing against a local test remote.\n\nThe real-library case adopts Zod's bundled v4 compatibility export instead of v3 in `zod@3.25.76`: `.errors` is absent while `.issues` remains. The actual agent corrected a stale JavaScript example, updated onboarding, and added source-grounded migration notes. Independent verification executed the exact reviewed example against `zod/v4`, checked the allowed diff, built the site, and produced a rendered local preview and reviewable patch/PR body. Compact evidence is retained under `docs/evidence/` in the private repository. This is a real API-family change within the pinned package, not an invented package release or a production customer case study.\n\nReproduce with `npm run test:maintenance:real` in the template checkout. It requires your authenticated agent and may consume quota. No GitHub PR is opened and no preview is published during the private-release hold. The remote draft-publishing path is covered separately against a local test remote; a live GitHub case remains a release-readiness check.\n\nUser-defined `maintenance.exampleChecks` can execute selected offline/local examples, and static CI runs attach rendered review artifacts. Neither a successful build nor an agent's statement proves all examples are correct. This case executes one explicitly reviewed example, not every imported example or language client.\n\n","contentLocale":"en","isFallback":true,"authorship":{"authors":[{"name":"nedimf","kind":"human","github":"nedimf","avatar":"/docsy/assets/authors/nedimf.png","role":"AppGram","id":"nedimf","url":"https://github.com/nedimf"},{"name":"AppGram","kind":"organization","github":"AppGram","url":"https://appgram.dev","avatar":"/docsy/assets/ag-logo.svg","id":"appgram"}],"contributors":[],"reviewedBy":[]},"editUrl":"https://github.com/AppGram/docsy/edit/main/content/reference/compatibility.md"}