ts-procedures 10.1.2 → 10.2.1

package/build/implementations/http/doc-registry.js

@@ -0,0 +1,96 @@
+import { PROCEDURE_REGISTRATION_ERROR_DOC, defaultErrorTaxonomy, taxonomyToErrorDocs, } from './error-taxonomy.js';
+function isTaxonomy(input) {
+    return !Array.isArray(input);
+}
+/**
+ * Dedupes ErrorDocs by `name`, last occurrence wins. Map insertion order
+ * preserves the latest position of each name.
+ */
+function dedupeByName(docs) {
+    const byName = new Map();
+    for (const doc of docs)
+        byName.set(doc.name, doc);
+    return Array.from(byName.values());
+}
+export class DocRegistry {
+    basePath;
+    headers;
+    errors;
+    sources = [];
+    constructor(config) {
+        this.basePath = config?.basePath ?? '';
+        this.headers = config?.headers ?? [];
+        const includeDefaults = config?.includeDefaults ?? true;
+        const userErrors = config?.errors
+            ? isTaxonomy(config.errors)
+                ? taxonomyToErrorDocs(config.errors)
+                : config.errors
+            : [];
+        // Precedence: defaults come first, user errors override via dedupe
+        // (last-write-wins). Matches runtime resolution order.
+        const merged = includeDefaults
+            ? [...DocRegistry.defaultErrors(), ...userErrors]
+            : userErrors;
+        this.errors = dedupeByName(merged);
+    }
+    from(source) {
+        this.sources.push(source);
+        return this;
+    }
+    /**
+     * Adds one or more {@link ErrorDoc} entries to the envelope. Use for errors
+     * outside your runtime taxonomy — middleware-level errors, infrastructure
+     * errors (502/503/504), or doc-only meta errors.
+     *
+     * Deduped by `name` — last write wins.
+     */
+    documentError(...docs) {
+        this.errors = dedupeByName([...this.errors, ...docs]);
+        return this;
+    }
+    toJSON(options) {
+        let routes = this.sources.flatMap((source) => source.docs);
+        if (options?.filter) {
+            routes = routes.filter(options.filter);
+        }
+        // Surface coverage gaps — when a builder skipped procedures (e.g. a
+        // streaming procedure registered with HonoRPCAppBuilder), the per-builder
+        // warning fires once at `build()` time, but consumers who only call
+        // `registry.toJSON()` (e.g. to dump the envelope to disk for codegen)
+        // wouldn't see it without this aggregate. Single warning per call,
+        // suppressed when the env var is set so CI pipelines stay quiet.
+        if (process.env.TS_PROCEDURES_SUPPRESS_COVERAGE_WARNINGS !== '1') {
+            const skipped = this.sources.flatMap((source) => source.skippedProcedures ?? []);
+            if (skipped.length > 0) {
+                const lines = skipped.map(({ name, reason }) => `  - "${name}": ${reason}`);
+                console.warn(`[ts-procedures DocRegistry] ${skipped.length} procedure(s) registered with a builder but not served — they will be missing from the doc envelope:\n${lines.join('\n')}\n` +
+                    `(Suppress with TS_PROCEDURES_SUPPRESS_COVERAGE_WARNINGS=1)`);
+            }
+        }
+        const envelope = {
+            basePath: this.basePath,
+            headers: [...this.headers],
+            errors: [...this.errors],
+            routes,
+        };
+        if (options?.transform) {
+            return options.transform(envelope);
+        }
+        return envelope;
+    }
+    /**
+     * Framework error defaults — derived from {@link defaultErrorTaxonomy} plus
+     * `ProcedureRegistrationError` (which is thrown only at registration time
+     * and therefore lives in the catalog, not the runtime taxonomy).
+     *
+     * Most consumers do not need to call this directly — the `DocRegistry`
+     * constructor auto-includes these unless `includeDefaults: false` is passed.
+     */
+    static defaultErrors() {
+        return [
+            ...taxonomyToErrorDocs(defaultErrorTaxonomy),
+            PROCEDURE_REGISTRATION_ERROR_DOC,
+        ];
+    }
+}
+//# sourceMappingURL=doc-registry.js.map

package/build/implementations/http/doc-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"doc-registry.js","sourceRoot":"","sources":["../../../src/implementations/http/doc-registry.ts"],"names":[],"mappings":"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"}

package/build/implementations/http/doc-registry.test.d.ts

@@ -0,0 +1 @@
+export {};

package/build/implementations/http/doc-registry.test.js

@@ -0,0 +1,516 @@
+import { describe, expect, it, test, vi, afterEach } from 'vitest';
+import { v } from 'suretype';
+import { Procedures } from '../../index.js';
+import { HonoRPCAppBuilder } from './hono-rpc/index.js';
+import { DocRegistry } from './doc-registry.js';
+import { defineErrorTaxonomy } from './error-taxonomy.js';
+// ---------------------------------------------------------------------------
+// Helpers — minimal doc fixtures
+// ---------------------------------------------------------------------------
+const rpcDoc = {
+    kind: 'rpc',
+    name: 'Echo',
+    path: '/echo/1',
+    method: 'post',
+    scope: 'echo',
+    version: 1,
+    jsonSchema: { body: { type: 'object' } },
+};
+const apiDoc = {
+    kind: 'api',
+    name: 'GetUser',
+    path: '/users/:id',
+    method: 'get',
+    fullPath: '/api/users/:id',
+    jsonSchema: { pathParams: { type: 'object' } },
+};
+const streamDoc = {
+    kind: 'stream',
+    name: 'Feed',
+    path: '/feed/1',
+    methods: ['get'],
+    streamMode: 'sse',
+    scope: 'feed',
+    version: 1,
+    jsonSchema: { yieldType: { type: 'object' } },
+};
+function makeSource(docs) {
+    return { docs };
+}
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+describe('DocRegistry', () => {
+    // --------------------------------------------------------------------------
+    // Constructor
+    // --------------------------------------------------------------------------
+    describe('constructor', () => {
+        test('uses defaults when no config provided', () => {
+            const registry = new DocRegistry({ includeDefaults: false });
+            const out = registry.toJSON();
+            expect(out.basePath).toBe('');
+            expect(out.headers).toEqual([]);
+            expect(out.errors).toEqual([]);
+        });
+        test('accepts partial config', () => {
+            const registry = new DocRegistry({ basePath: '/v1', includeDefaults: false });
+            const out = registry.toJSON();
+            expect(out.basePath).toBe('/v1');
+            expect(out.headers).toEqual([]);
+            expect(out.errors).toEqual([]);
+        });
+        test('accepts full config', () => {
+            const headers = [{ name: 'Authorization', description: 'Bearer token', required: true }];
+            const errors = [{ name: 'Unauthorized', statusCode: 401, description: 'Missing token' }];
+            const registry = new DocRegistry({ basePath: '/api', headers, errors, includeDefaults: false });
+            const out = registry.toJSON();
+            expect(out.basePath).toBe('/api');
+            expect(out.headers).toEqual(headers);
+            expect(out.errors).toEqual(errors);
+        });
+    });
+    // --------------------------------------------------------------------------
+    // from()
+    // --------------------------------------------------------------------------
+    describe('from()', () => {
+        test('returns this for chaining', () => {
+            const registry = new DocRegistry();
+            const result = registry.from(makeSource([rpcDoc]));
+            expect(result).toBe(registry);
+        });
+        test('accepts RPC builder source', () => {
+            const registry = new DocRegistry().from(makeSource([rpcDoc]));
+            expect(registry.toJSON().routes).toEqual([rpcDoc]);
+        });
+        test('accepts API builder source', () => {
+            const registry = new DocRegistry().from(makeSource([apiDoc]));
+            expect(registry.toJSON().routes).toEqual([apiDoc]);
+        });
+        test('accepts Stream builder source', () => {
+            const registry = new DocRegistry().from(makeSource([streamDoc]));
+            expect(registry.toJSON().routes).toEqual([streamDoc]);
+        });
+        test('accepts plain { docs } object', () => {
+            const plain = { docs: [rpcDoc, apiDoc] };
+            const registry = new DocRegistry().from(plain);
+            expect(registry.toJSON().routes).toHaveLength(2);
+        });
+        test('builder not yet built returns empty routes', () => {
+            const emptySource = makeSource([]);
+            const registry = new DocRegistry().from(emptySource);
+            expect(registry.toJSON().routes).toEqual([]);
+        });
+        test('same builder twice duplicates routes', () => {
+            const source = makeSource([rpcDoc]);
+            const registry = new DocRegistry().from(source).from(source);
+            expect(registry.toJSON().routes).toHaveLength(2);
+            expect(registry.toJSON().routes[0]).toEqual(registry.toJSON().routes[1]);
+        });
+        test('reads docs lazily at toJSON() time', () => {
+            const mutableDocs = [];
+            const source = { get docs() { return mutableDocs; } };
+            const registry = new DocRegistry().from(source);
+            expect(registry.toJSON().routes).toHaveLength(0);
+            mutableDocs.push(rpcDoc);
+            expect(registry.toJSON().routes).toHaveLength(1);
+        });
+    });
+    // --------------------------------------------------------------------------
+    // toJSON()
+    // --------------------------------------------------------------------------
+    describe('toJSON()', () => {
+        test('returns correct DocEnvelope shape', () => {
+            const registry = new DocRegistry({ basePath: '/api' });
+            const out = registry.toJSON();
+            expect(out).toHaveProperty('basePath');
+            expect(out).toHaveProperty('headers');
+            expect(out).toHaveProperty('errors');
+            expect(out).toHaveProperty('routes');
+        });
+        test('collects routes from all sources', () => {
+            const registry = new DocRegistry()
+                .from(makeSource([rpcDoc]))
+                .from(makeSource([apiDoc]))
+                .from(makeSource([streamDoc]));
+            const out = registry.toJSON();
+            expect(out.routes).toHaveLength(3);
+            expect(out.routes).toEqual([rpcDoc, apiDoc, streamDoc]);
+        });
+        test('empty when no sources', () => {
+            const out = new DocRegistry().toJSON();
+            expect(out.routes).toEqual([]);
+        });
+        test('headers and errors are copies', () => {
+            const headers = [{ name: 'X-Custom' }];
+            const errors = [{ name: 'E', statusCode: 500, description: 'd' }];
+            const registry = new DocRegistry({ headers, errors, includeDefaults: false });
+            const out = registry.toJSON();
+            expect(out.headers).toEqual(headers);
+            expect(out.headers).not.toBe(headers);
+            expect(out.errors).toEqual(errors);
+            expect(out.errors).not.toBe(errors);
+        });
+    });
+    // --------------------------------------------------------------------------
+    // toJSON() filter
+    // --------------------------------------------------------------------------
+    describe('toJSON() filter', () => {
+        test('excludes routes by name', () => {
+            const registry = new DocRegistry()
+                .from(makeSource([rpcDoc]))
+                .from(makeSource([apiDoc]));
+            const out = registry.toJSON({ filter: (r) => r.name !== 'Echo' });
+            expect(out.routes).toHaveLength(1);
+            expect(out.routes[0].name).toBe('GetUser');
+        });
+        test('excludes routes by type field', () => {
+            const registry = new DocRegistry()
+                .from(makeSource([rpcDoc]))
+                .from(makeSource([apiDoc]));
+            const out = registry.toJSON({
+                filter: (r) => 'method' in r && r.method === 'post' && 'scope' in r,
+            });
+            expect(out.routes).toHaveLength(1);
+            expect(out.routes[0].name).toBe('Echo');
+        });
+        test('all filtered returns empty routes array', () => {
+            const registry = new DocRegistry().from(makeSource([rpcDoc]));
+            const out = registry.toJSON({ filter: () => false });
+            expect(out.routes).toEqual([]);
+        });
+    });
+    // --------------------------------------------------------------------------
+    // toJSON() transform
+    // --------------------------------------------------------------------------
+    describe('toJSON() transform', () => {
+        test('adds fields', () => {
+            const registry = new DocRegistry({ basePath: '/api' }).from(makeSource([rpcDoc]));
+            const out = registry.toJSON({
+                transform: (envelope) => ({ ...envelope, version: '2.0' }),
+            });
+            expect(out.version).toBe('2.0');
+            expect(out.basePath).toBe('/api');
+        });
+        test('reshapes envelope', () => {
+            const registry = new DocRegistry().from(makeSource([rpcDoc]));
+            const out = registry.toJSON({
+                transform: (envelope) => ({ count: envelope.routes.length }),
+            });
+            expect(out).toEqual({ count: 1 });
+        });
+        test('runs after filter', () => {
+            const registry = new DocRegistry()
+                .from(makeSource([rpcDoc]))
+                .from(makeSource([apiDoc]));
+            const out = registry.toJSON({
+                filter: (r) => r.name === 'Echo',
+                transform: (envelope) => ({ ...envelope, filteredCount: envelope.routes.length }),
+            });
+            expect(out.filteredCount).toBe(1);
+            expect(out.routes).toHaveLength(1);
+        });
+    });
+    // --------------------------------------------------------------------------
+    // defaultErrors()
+    // --------------------------------------------------------------------------
+    describe('defaultErrors()', () => {
+        test('returns 4 entries', () => {
+            const errors = DocRegistry.defaultErrors();
+            expect(errors).toHaveLength(4);
+        });
+        test('has correct error names', () => {
+            const names = DocRegistry.defaultErrors().map((e) => e.name);
+            // Runtime errors come from the taxonomy (topologically sorted —
+            // subclasses first), followed by the doc-only registration error.
+            expect(names).toEqual([
+                'ProcedureValidationError',
+                'ProcedureYieldValidationError',
+                'ProcedureError',
+                'ProcedureRegistrationError',
+            ]);
+        });
+        test('has correct status codes', () => {
+            const byName = Object.fromEntries(DocRegistry.defaultErrors().map((e) => [e.name, e.statusCode]));
+            expect(byName.ProcedureError).toBe(500);
+            expect(byName.ProcedureValidationError).toBe(400);
+            expect(byName.ProcedureYieldValidationError).toBe(500);
+            expect(byName.ProcedureRegistrationError).toBe(500);
+        });
+        test('each entry has schema', () => {
+            for (const err of DocRegistry.defaultErrors()) {
+                expect(err.schema).toBeDefined();
+                expect(err.schema.type).toBe('object');
+            }
+        });
+        test('returns a new array each call', () => {
+            const a = DocRegistry.defaultErrors();
+            const b = DocRegistry.defaultErrors();
+            expect(a).not.toBe(b);
+            expect(a).toEqual(b);
+        });
+    });
+    // --------------------------------------------------------------------------
+    // taxonomy input + auto-defaults + dedupe (v6.0.1 simplification)
+    // --------------------------------------------------------------------------
+    describe('errors: ErrorTaxonomy (polymorphic constructor input)', () => {
+        test('accepts an ErrorTaxonomy directly and converts to ErrorDoc[]', () => {
+            const taxonomy = defineErrorTaxonomy({
+                AuthError: {
+                    class: class AuthError extends Error {
+                    },
+                    statusCode: 401,
+                    description: 'unauthenticated',
+                },
+            });
+            const envelope = new DocRegistry({ errors: taxonomy }).toJSON();
+            const auth = envelope.errors.find((e) => e.name === 'AuthError');
+            expect(auth).toBeDefined();
+            expect(auth?.statusCode).toBe(401);
+            expect(auth?.description).toBe('unauthenticated');
+        });
+        test('auto-includes framework defaults when errors is a taxonomy', () => {
+            const taxonomy = defineErrorTaxonomy({
+                AuthError: { class: class AuthError extends Error {
+                    }, statusCode: 401 },
+            });
+            const names = new DocRegistry({ errors: taxonomy }).toJSON().errors.map((e) => e.name);
+            expect(names).toContain('AuthError');
+            expect(names).toContain('ProcedureValidationError');
+            expect(names).toContain('ProcedureYieldValidationError');
+            expect(names).toContain('ProcedureError');
+            expect(names).toContain('ProcedureRegistrationError');
+        });
+        test('auto-includes framework defaults when errors is ErrorDoc[]', () => {
+            const custom = { name: 'CustomThing', statusCode: 418, description: 'teapot' };
+            const names = new DocRegistry({ errors: [custom] }).toJSON().errors.map((e) => e.name);
+            expect(names).toContain('CustomThing');
+            expect(names).toContain('ProcedureValidationError');
+        });
+        test('includeDefaults: false omits framework defaults', () => {
+            const taxonomy = defineErrorTaxonomy({
+                AuthError: { class: class AuthError extends Error {
+                    }, statusCode: 401 },
+            });
+            const names = new DocRegistry({ errors: taxonomy, includeDefaults: false })
+                .toJSON()
+                .errors.map((e) => e.name);
+            expect(names).toEqual(['AuthError']);
+        });
+        test('user taxonomy entry with same name as default overrides default (dedupe, user wins)', () => {
+            const taxonomy = defineErrorTaxonomy({
+                ProcedureError: {
+                    class: Error,
+                    statusCode: 418,
+                    description: 'custom override',
+                },
+            });
+            const envelope = new DocRegistry({ errors: taxonomy }).toJSON();
+            const proc = envelope.errors.filter((e) => e.name === 'ProcedureError');
+            expect(proc).toHaveLength(1);
+            expect(proc[0].statusCode).toBe(418);
+            expect(proc[0].description).toBe('custom override');
+        });
+        test('user ErrorDoc with same name as default overrides default (dedupe, user wins)', () => {
+            const custom = {
+                name: 'ProcedureError',
+                statusCode: 418,
+                description: 'custom override',
+            };
+            const envelope = new DocRegistry({ errors: [custom] }).toJSON();
+            const proc = envelope.errors.filter((e) => e.name === 'ProcedureError');
+            expect(proc).toHaveLength(1);
+            expect(proc[0].statusCode).toBe(418);
+            expect(proc[0].description).toBe('custom override');
+        });
+        test('empty errors config still returns framework defaults', () => {
+            const names = new DocRegistry().toJSON().errors.map((e) => e.name);
+            expect(names).toContain('ProcedureError');
+            expect(names).toContain('ProcedureValidationError');
+            expect(names).toContain('ProcedureYieldValidationError');
+            expect(names).toContain('ProcedureRegistrationError');
+        });
+        test('includeDefaults: false with no errors produces empty error list', () => {
+            const envelope = new DocRegistry({ includeDefaults: false }).toJSON();
+            expect(envelope.errors).toEqual([]);
+        });
+    });
+    // --------------------------------------------------------------------------
+    // .documentError() fluent extension
+    // --------------------------------------------------------------------------
+    describe('.documentError()', () => {
+        test('adds a single ErrorDoc to the envelope', () => {
+            const registry = new DocRegistry({ includeDefaults: false }).documentError({
+                name: 'RateLimitExceeded',
+                statusCode: 429,
+                description: 'too many requests',
+            });
+            const names = registry.toJSON().errors.map((e) => e.name);
+            expect(names).toEqual(['RateLimitExceeded']);
+        });
+        test('accepts multiple docs via variadic args', () => {
+            const registry = new DocRegistry({ includeDefaults: false }).documentError({ name: 'A', statusCode: 400, description: 'a' }, { name: 'B', statusCode: 500, description: 'b' });
+            const names = registry.toJSON().errors.map((e) => e.name);
+            expect(names).toEqual(['A', 'B']);
+        });
+        test('returns this for chaining', () => {
+            const registry = new DocRegistry();
+            const returned = registry.documentError({
+                name: 'Foo',
+                statusCode: 500,
+                description: 'x',
+            });
+            expect(returned).toBe(registry);
+        });
+        test('composes with taxonomy input — extends docs without replacing', () => {
+            const taxonomy = defineErrorTaxonomy({
+                AuthError: { class: class AuthError extends Error {
+                    }, statusCode: 401 },
+            });
+            const envelope = new DocRegistry({ errors: taxonomy })
+                .documentError({ name: 'RateLimitExceeded', statusCode: 429, description: 'x' })
+                .toJSON();
+            const names = envelope.errors.map((e) => e.name);
+            expect(names).toContain('AuthError');
+            expect(names).toContain('RateLimitExceeded');
+            expect(names).toContain('ProcedureValidationError');
+        });
+        test('dedupes against existing errors (last write wins)', () => {
+            const registry = new DocRegistry({ includeDefaults: false })
+                .documentError({ name: 'Foo', statusCode: 400, description: 'first' })
+                .documentError({ name: 'Foo', statusCode: 500, description: 'second' });
+            const foo = registry.toJSON().errors.filter((e) => e.name === 'Foo');
+            expect(foo).toHaveLength(1);
+            expect(foo[0].statusCode).toBe(500);
+            expect(foo[0].description).toBe('second');
+        });
+    });
+    // --------------------------------------------------------------------------
+    // kind discriminant
+    // --------------------------------------------------------------------------
+    describe('kind discriminant', () => {
+        it('rpcDoc fixture requires kind field', () => {
+            const doc = rpcDoc;
+            expect(doc.kind).toBe('rpc');
+        });
+        it('apiDoc fixture requires kind field', () => {
+            const doc = apiDoc;
+            expect(doc.kind).toBe('api');
+        });
+        it('streamDoc fixture requires kind field', () => {
+            const doc = streamDoc;
+            expect(doc.kind).toBe('stream');
+        });
+        it('narrows AnyHttpRouteDoc union via kind', () => {
+            const routes = [rpcDoc, apiDoc, streamDoc];
+            for (const route of routes) {
+                expect(route.kind).toBeDefined();
+            }
+        });
+    });
+    // --------------------------------------------------------------------------
+    // Integration
+    // --------------------------------------------------------------------------
+    describe('integration', () => {
+        test('multiple builder types composed', () => {
+            const registry = new DocRegistry({
+                basePath: '/api',
+                headers: [{ name: 'Authorization', description: 'Bearer token', required: false }],
+            })
+                .from(makeSource([rpcDoc]))
+                .from(makeSource([apiDoc]))
+                .from(makeSource([streamDoc]));
+            const out = registry.toJSON();
+            expect(out.basePath).toBe('/api');
+            expect(out.headers).toHaveLength(1);
+            expect(out.errors).toHaveLength(4);
+            expect(out.routes).toHaveLength(3);
+        });
+        test('filter + transform combined', () => {
+            const registry = new DocRegistry({ basePath: '/api' })
+                .from(makeSource([rpcDoc]))
+                .from(makeSource([apiDoc]))
+                .from(makeSource([streamDoc]));
+            const out = registry.toJSON({
+                filter: (r) => r.name !== 'Feed',
+                transform: (envelope) => ({
+                    ...envelope,
+                    generatedAt: '2026-01-01',
+                }),
+            });
+            expect(out.routes).toHaveLength(2);
+            expect(out.routes.map((r) => r.name)).toEqual(['Echo', 'GetUser']);
+            expect(out.generatedAt).toBe('2026-01-01');
+        });
+        test('output is JSON.stringify-safe', () => {
+            const registry = new DocRegistry({
+                basePath: '/api',
+                headers: [{ name: 'X-Request-Id', example: 'abc-123' }],
+            })
+                .from(makeSource([rpcDoc]))
+                .from(makeSource([apiDoc]));
+            const out = registry.toJSON();
+            const str = JSON.stringify(out);
+            expect(() => JSON.parse(str)).not.toThrow();
+            expect(JSON.parse(str)).toEqual(out);
+        });
+        test('JSON.stringify(registry) produces default envelope', () => {
+            const registry = new DocRegistry({ basePath: '/api' })
+                .from(makeSource([rpcDoc]));
+            const str = JSON.stringify(registry);
+            const parsed = JSON.parse(str);
+            expect(parsed.basePath).toBe('/api');
+            expect(parsed.routes).toHaveLength(1);
+            expect(parsed.routes[0].name).toBe('Echo');
+        });
+        describe('coverage warnings via skippedProcedures', () => {
+            afterEach(() => {
+                vi.restoreAllMocks();
+                delete process.env.TS_PROCEDURES_SUPPRESS_COVERAGE_WARNINGS;
+            });
+            test('warns when sources expose skippedProcedures entries', () => {
+                const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => { });
+                const sourceWithSkipped = {
+                    docs: [rpcDoc],
+                    skippedProcedures: [
+                        { name: 'StreamProc', reason: 'wrong builder' },
+                    ],
+                };
+                new DocRegistry().from(sourceWithSkipped).toJSON();
+                expect(warnSpy).toHaveBeenCalledOnce();
+                const message = warnSpy.mock.calls[0][0];
+                expect(message).toContain('1 procedure(s)');
+                expect(message).toContain('StreamProc');
+                expect(message).toContain('wrong builder');
+            });
+            test('does not warn when sources have no skippedProcedures', () => {
+                const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => { });
+                new DocRegistry().from(makeSource([rpcDoc])).toJSON();
+                expect(warnSpy).not.toHaveBeenCalled();
+            });
+            test('TS_PROCEDURES_SUPPRESS_COVERAGE_WARNINGS=1 silences the warning', () => {
+                process.env.TS_PROCEDURES_SUPPRESS_COVERAGE_WARNINGS = '1';
+                const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => { });
+                const source = {
+                    docs: [rpcDoc],
+                    skippedProcedures: [{ name: 'X', reason: 'y' }],
+                };
+                new DocRegistry().from(source).toJSON();
+                expect(warnSpy).not.toHaveBeenCalled();
+            });
+        });
+        test('accepts a real HonoRPCAppBuilder as source', () => {
+            const RPC = Procedures();
+            RPC.Create('Ping', { scope: 'ping', version: 1, schema: { params: v.object({ msg: v.string() }) } }, async (_ctx, params) => params);
+            const builder = new HonoRPCAppBuilder();
+            builder.register(RPC, () => ({ userId: '123' }));
+            builder.build();
+            const registry = new DocRegistry({ basePath: '/rpc' }).from(builder);
+            const out = registry.toJSON();
+            expect(out.basePath).toBe('/rpc');
+            expect(out.routes).toHaveLength(1);
+            expect(out.routes[0].name).toBe('Ping');
+            expect(out.routes[0]).toHaveProperty('jsonSchema');
+        });
+    });
+});
+//# sourceMappingURL=doc-registry.test.js.map