Move docs/ package mirror into document-navigator plugin
Relocate the ~6k-file docs tree from the repo root into plugins/document-navigator/docs/ so the plugin is self-contained and portable. docs/superpowers/ (specs and plans) stays at the repo root. Moved via cp+rm rather than git mv because directory rename() fails with EPERM on this WSL /mnt DrvFs mount; git rename-detection pairs the identical-content files at commit time. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,81 @@
|
||||
# @suaveplan/api-graphql — abstract GraphQL contract for the Suaveplan API plugin system. Owns the GraphqlRegistry / Resolver / LoaderFactory / SubscriptionResolver re-exports, federation SDL merger with collision detection + plugin namespace wrapping, @auth + @rateLimit directive descriptors, the GraphqlEngine lifecycle interface, the GRAPHQL_CODES registry, and the runGraphqlEngineConformance harness. No concrete engine — Yoga / Apollo land packages and implement the contract.
|
||||
|
||||
Stage-1 abstract GraphQL contract for the Suaveplan API plugin system.
|
||||
|
||||
Plugins contribute SDL + resolvers via a small abstract surface; the host
|
||||
federates a single schema across every plugin and dispatches via a
|
||||
swappable engine. Concrete engines (`api-graphql-yoga` default,
|
||||
`api-graphql-apollo` alternative) live and implement the
|
||||
`GraphqlEngine` contract published from this package.
|
||||
|
||||
<!-- begin:auto-docs -->
|
||||
## Documentation tree
|
||||
|
||||
- [directives](./src/directives/directives.md) — Host-supplied GraphQL directive descriptors that engine adapters install at schema-build time. The contract layer ships…
|
||||
- [directives](./src/directives/directives.md) — Host-supplied GraphQL directive descriptors that engine adapters install at schema-build time. The contract layer ships…
|
||||
- [error-codes](./src/error-codes/error-codes.md) — Stable error-code registry for `@suaveplan/api-graphql`. Every public failure path raises a `GraphqlError` carrying one…
|
||||
- [error-codes](./src/error-codes/error-codes.md) — Stable error-code registry for `@suaveplan/api-graphql`. Every public failure path raises a `GraphqlError` carrying one…
|
||||
- [merge-sdl](./src/federation/merge-sdl.md) — Federate one or more plugin SDL contributions into a single merged schema. This is the engine-agnostic federation step…
|
||||
- [namespace](./src/federation/namespace.md) — Apply the `graphql.namespace` wrapper to a plugin's parsed SDL blocks. Plugins that declare `namespace: "Billing"` in t…
|
||||
- [parse-sdl](./src/federation/parse-sdl.md) — Minimal SDL parser used by the federation merger to locate `type Name { ... }` and `extend type Name { ... }` blocks pl…
|
||||
- [registry](./src/registry/registry.md) — Concrete accumulator-style `GraphqlRegistry` implementation. The host hands each plugin one of these during the GraphQL…
|
||||
- [registry](./src/registry/registry.md) — Concrete accumulator-style `GraphqlRegistry` implementation. The host hands each plugin one of these during the GraphQL…
|
||||
- [subscription](./src/subscription/subscription.md) — Validate incoming `graphql-ws` subscription envelopes and surface a typed "transport unavailable" failure when `api-ws`…
|
||||
- [subscription](./src/subscription/subscription.md) — Validate incoming `graphql-ws` subscription envelopes and surface a typed "transport unavailable" failure when `api-ws`…
|
||||
- [testing](./src/testing/conformance.md) — `runGraphqlEngineConformance` is the cross-engine test harness every concrete GraphQL engine (`api-graphql-yoga`, `api-…
|
||||
- [conformance](./src/testing/conformance.md) — `runGraphqlEngineConformance` is the cross-engine test harness every concrete GraphQL engine (`api-graphql-yoga`, `api-…
|
||||
- [validators](./src/validators/validators.md) — Pre-build validators concrete GraphQL engines call after `registry.freeze()` and before `buildSchema`. The contract lay…
|
||||
- [validators](./src/validators/validators.md) — Pre-build validators concrete GraphQL engines call after `registry.freeze()` and before `buildSchema`. The contract lay…
|
||||
<!-- end:auto-docs -->
|
||||
|
||||
## Surface
|
||||
|
||||
- [`./registry`](./src/registry/registry.md) — abstract `GraphqlRegistry`
|
||||
accumulator (`addTypes` / `addResolvers` / `addLoader`) + `freeze()`.
|
||||
- [`./resolver`](./src/resolver/resolver.types.ts) — `Resolver` (re-exported
|
||||
from `@suaveplan/api-types`) and the keyed `ResolverMap` / `ResolverFieldMap`.
|
||||
- [`./loader`](./src/loader/loader.types.ts) — `LoaderFactory`
|
||||
(re-exported) and the `BatchFn` signature.
|
||||
- [`./subscription`](./src/subscription/subscription.md) —
|
||||
`SubscriptionResolver` (re-exported) + Zod-validated `graphql-ws`
|
||||
envelope + transport-availability assertion.
|
||||
- [`./federation`](./src/federation/merge-sdl.md) — `mergeSdl` collision
|
||||
detector + `graphql.namespace` wrapper + minimal SDL parser.
|
||||
- [`./directives`](./src/directives/directives.md) — `@auth(scope: String!)`
|
||||
and `@rateLimit(rpm: Int!)` descriptors + `HOST_DIRECTIVES` lookup.
|
||||
- [`./engine`](./src/engine/engine.types.ts) — abstract `GraphqlEngine`
|
||||
lifecycle interface implemented by Stage-7 packages.
|
||||
- [`./capability-id`](./src/capability-id/capability-id.types.ts) —
|
||||
re-export of `"graphql"` literal + `GRAPHQL_CAPABILITY_ID` runtime
|
||||
constant.
|
||||
- [`./error-codes`](./src/error-codes/error-codes.md) — `GRAPHQL_CODES`
|
||||
registry + `GraphqlError` class.
|
||||
- [`./validators`](./src/validators/validators.md) —
|
||||
`validateResolvers`, `lookupDirective`, `lookupLoader` pre-build checks.
|
||||
- [`./testing`](./src/testing/conformance.md) —
|
||||
`runGraphqlEngineConformance` cross-engine harness.
|
||||
|
||||
## Error codes (`GRAPHQL.*`)
|
||||
|
||||
| Code | When |
|
||||
| --- | --- |
|
||||
| `SCHEMA_COLLISION` | Two plugins declare the same `Type.field`. |
|
||||
| `RESOLVER_MISSING` | SDL declares a root field with no resolver. |
|
||||
| `LOADER_DUPLICATE_NAME` | Two `addLoader` calls registered the same name. |
|
||||
| `LOADER_NOT_REGISTERED` | Request references an unknown loader. |
|
||||
| `DIRECTIVE_UNKNOWN` | SDL references an uninstalled directive. |
|
||||
| `SUBSCRIPTION_TRANSPORT_UNAVAILABLE` | Subscriptions used without `api-ws`. |
|
||||
| `NAMESPACE_REQUIRED` | Strict-mode federation missing namespace. |
|
||||
|
||||
## Stage
|
||||
|
||||
Contracts. No concrete GraphQL engine; Yoga / Apollo / GraphiQL /
|
||||
Altair packages land .
|
||||
|
||||
## Dependencies
|
||||
|
||||
- `@suaveplan/api-types` — type-level contract surface.
|
||||
- `@suaveplan/error` — `defineCodes` + `SuaveplanError` base.
|
||||
- `zod` — subscription protocol envelope validation.
|
||||
- `tslib` — TypeScript helper functions.
|
||||
|
||||
Reference in New Issue
Block a user