@starci/hfs 4.11.22 → 4.12.0

package/emit/operations.mjs

@@ -1,162 +1,153 @@
-/**
- * The versioned operations of an api app, read from its typed operation table and printed as OpenAPI 3.1.
- *
- * The table is the canon's one declaration of an app's operation surface (knowledge/patterns/be/api.yaml, BE-OPERATIONS-1):
- * `apps/<app>/src/operations.ts` exports `OPERATIONS`, made by `defineOperations({ "<id>@<version>": query({ input, output }) })`.
- * Input and output are exported zod schemas from *.schema.ts. Only schema modules are evaluated, never app modules; the app's
- * z.toJSONSchema carries their constraints into OpenAPI. Open schemas and unrepresentable wire values are refused; the
- * TypeScript checker separately proves closed parsed input/output types and refusal codes. A failure always names the operation.
- *
- * The wire is one route, `POST /operations`: the body is `{ operation, requestId, input }` and the answer is `{ operation, requestId,
- * outcome }`, `outcome` being `{ kind: "ok", value }` or `{ kind: "refused", code, params? }`. Each operation contributes one request
- * and one reply component carrying `x-operation: "<id>@<version>"`; the route's body and answer are the oneOf over them.
- */
 import { createSchemaBuilder, stable } from './type-schema.mjs';
 import { INPUT_BOUNDS_OPENAPI_EXTENSION, INPUT_BOUNDS_VERSION } from './input-bounds.mjs';
 import { operationSchemaReader } from './operation-schemas.mjs';
 import path from 'node:path';
-
 /** The export of `apps/<app>/src/operations.ts` that holds the table. */
 const OPERATIONS_EXPORT = 'OPERATIONS';
-
 /** The repository-relative path of an app's operation table. */
 export const operationsPath = (app) => `apps/${app}/src/operations.ts`;
-
 /** The repository-relative path of an app's OpenAPI contract. */
 export const openapiPath = (app) => `contracts/${app}/openapi.json`;
-
 const ID = /^[a-z][A-Za-z0-9.]*@[1-9][0-9]*$/;
-
 /** The component name stem of an operation id: `sales.policy@1` gives `sales.policy.v1`. */
 const stemOf = (id) => id.replace('@', '.v');
-
 /** Preserve R95 on parsed values even when an input transform still has a closed JSON wire representation. */
 function assertParsedTypes(builder, member, fail) {
-  for (const label of ['input', 'output']) {
-    const type = member(label);
-    try {
-      builder.schemaOf(type, `parsed ${label}`);
-    } catch (error) {
-      fail(error.message);
+    for (const label of ['input', 'output']) {
+        const type = member(label);
+        try {
+            builder.schemaOf(type, `parsed ${label}`);
+        }
+        catch (error) {
+            fail(error.message); // not instanceof: schema modules run in a vm realm, whose errors are not this realm's Error
+        }
     }
-  }
 }
-
 /**
  * Reads the operation table of a source file of a program. Answers null when the file is not in the program; throws when it
  * exports no `OPERATIONS` or an operation is not decidable.
  */
 export function readOperations({ ts, program, file, repoRoot = path.resolve(path.dirname(file), '../../..') }) {
-  const checker = program.getTypeChecker();
-  const sourceFile = program.getSourceFile(file);
-  if (!sourceFile) return null;
-  const moduleSymbol = checker.getSymbolAtLocation(sourceFile);
-  const exported = moduleSymbol ? checker.getExportsOfModule(moduleSymbol).find((symbol) => symbol.getName() === OPERATIONS_EXPORT) : null;
-  if (!exported) throw new Error(`${file} does not export ${OPERATIONS_EXPORT}, the app's operation table`);
-  const readSchema = operationSchemaReader({ ts, program, repoRoot });
-  const parsedTypes = createSchemaBuilder({ ts, checker, schemaBacked: true });
-  const table = checker.getTypeOfSymbol(exported.flags & ts.SymbolFlags.Alias ? checker.getAliasedSymbol(exported) : exported);
-  const operations = [];
-  for (const prop of [...checker.getPropertiesOfType(table)].sort((a, b) => (a.getName() < b.getName() ? -1 : 1))) {
-    const id = prop.getName();
-    const fail = (why) => {
-      throw new Error(`operation ${id}: ${why}`);
-    };
-    if (!ID.test(id)) fail('the key must be "<name>@<positive version>", for example "sales.policy@1"');
-    if (id.length > 128) fail('the operation id exceeds the runtime envelope limit of 128 characters');
-    const contract = checker.getTypeOfSymbol(prop);
-    const kindType = contract.getProperty('kind') ? checker.getTypeOfSymbol(contract.getProperty('kind')) : null;
-    const kind = kindType?.isStringLiteral() ? kindType.value : null;
-    if (kind !== 'query' && kind !== 'mutation') fail('kind must be the literal "query" or "mutation"');
-    const typesProp = contract.getProperty('types');
-    if (!typesProp) fail('the value is not an OperationContract (it has no types member)');
-    const typesType = checker.getNonNullableType(checker.getTypeOfSymbol(typesProp));
-    const member = (name) => {
-      const symbol = typesType.getProperty(name);
-      if (!symbol) fail(`the contract has no ${name} type`);
-      return checker.getTypeOfSymbol(symbol);
-    };
-    const schema = (label) => {
-      try {
-        return readSchema(prop, label);
-      } catch (error) {
-        return fail(`${label} schema: ${error.message}`);
-      }
-    };
-    const input = schema('input');
-    const output = schema('output');
-    // This check never supplies emitted schemas: z.toJSONSchema remains the wire authority.
-    assertParsedTypes(parsedTypes, member, fail);
-    const refusalType = member('refusal');
-    let refusal = [];
-    if ((refusalType.flags & ts.TypeFlags.Never) === 0) {
-      const members = refusalType.isUnion() ? refusalType.types : [refusalType];
-      if (!members.every((each) => each.isStringLiteral())) fail(`refusal must be a closed union of string literals, found ${checker.typeToString(refusalType)}`);
-      refusal = members.map((each) => each.value).sort();
+    const checker = program.getTypeChecker();
+    const sourceFile = program.getSourceFile(file);
+    if (!sourceFile)
+        return null;
+    const moduleSymbol = checker.getSymbolAtLocation(sourceFile);
+    const exported = moduleSymbol ? checker.getExportsOfModule(moduleSymbol).find((symbol) => symbol.getName() === OPERATIONS_EXPORT) : null;
+    if (!exported)
+        throw new Error(`${file} does not export ${OPERATIONS_EXPORT}, the app's operation table`);
+    const readSchema = operationSchemaReader({ ts, program, repoRoot });
+    const parsedTypes = createSchemaBuilder({ ts, checker, schemaBacked: true });
+    const table = checker.getTypeOfSymbol(exported.flags & ts.SymbolFlags.Alias ? checker.getAliasedSymbol(exported) : exported);
+    const operations = [];
+    for (const prop of [...checker.getPropertiesOfType(table)].sort((a, b) => (a.getName() < b.getName() ? -1 : 1))) {
+        const id = prop.getName();
+        const fail = (why) => {
+            throw new Error(`operation ${id}: ${why}`);
+        };
+        if (!ID.test(id))
+            fail('the key must be "<name>@<positive version>", for example "sales.policy@1"');
+        if (id.length > 128)
+            fail('the operation id exceeds the runtime envelope limit of 128 characters');
+        const contract = checker.getTypeOfSymbol(prop);
+        const kindSymbol = contract.getProperty('kind');
+        const kindType = kindSymbol ? checker.getTypeOfSymbol(kindSymbol) : null;
+        const kind = kindType?.isStringLiteral() ? kindType.value : null;
+        if (kind !== 'query' && kind !== 'mutation')
+            fail('kind must be the literal "query" or "mutation"');
+        const typesProp = contract.getProperty('types');
+        if (!typesProp)
+            fail('the value is not an OperationContract (it has no types member)');
+        const typesType = checker.getNonNullableType(checker.getTypeOfSymbol(typesProp));
+        const member = (name) => {
+            const symbol = typesType.getProperty(name);
+            if (!symbol)
+                fail(`the contract has no ${name} type`);
+            return checker.getTypeOfSymbol(symbol);
+        };
+        const schema = (label) => {
+            try {
+                return readSchema(prop, label);
+            }
+            catch (error) {
+                return fail(`${label} schema: ${error.message}`);
+            }
+        };
+        const input = schema('input');
+        const output = schema('output');
+        // This check never supplies emitted schemas: z.toJSONSchema remains the wire authority.
+        assertParsedTypes(parsedTypes, member, fail);
+        const refusalType = member('refusal');
+        let refusal = [];
+        if ((refusalType.flags & ts.TypeFlags.Never) === 0) {
+            const members = refusalType.isUnion() ? refusalType.types : [refusalType];
+            if (!members.every((each) => each.isStringLiteral()))
+                fail(`refusal must be a closed union of string literals, found ${checker.typeToString(refusalType)}`);
+            refusal = members.map((each) => each.value).sort();
+        }
+        operations.push({ id, kind, input, output, refusal });
     }
-    operations.push({ id, kind, input, output, refusal });
-  }
-  if (operations.length === 0) throw new Error(`${file}: ${OPERATIONS_EXPORT} declares no operation`);
-  return { operations, components: {} };
+    if (operations.length === 0)
+        throw new Error(`${file}: ${OPERATIONS_EXPORT} declares no operation`);
+    return { operations, components: {} };
 }
-
 /** The OpenAPI 3.1 document of an app's operations, as sorted-key JSON text with one final newline. */
 export function openApiText({ app, operations, components }) {
-  const schemas = { ...components };
-  schemas['Operation.InvalidRequest'] = {
-    type: 'object',
-    additionalProperties: false,
-    required: ['code', 'kind', 'message', 'params'],
-    properties: {
-      code: { const: 'OPERATIONS_INVALID_REQUEST' },
-      kind: { const: 'invalid' },
-      message: { type: 'string', description: 'The localized canonical error message.' },
-      params: { type: 'object', additionalProperties: false },
-    },
-  };
-  const requests = [];
-  const replies = [];
-  for (const operation of operations) {
-    const stem = stemOf(operation.id);
-    const okOutcome = { type: 'object', required: ['kind', 'value'], properties: { kind: { const: 'ok' }, value: operation.output } };
-    const refusedOutcome = { type: 'object', required: ['code', 'kind'], properties: { code: { enum: operation.refusal, type: 'string' }, kind: { const: 'refused' }, params: { type: 'object', additionalProperties: { type: ['string', 'number', 'boolean'] } } } };
-    schemas[`Operation.${stem}.Request`] = {
-      type: 'object',
-      additionalProperties: false,
-      required: ['input', 'operation', 'requestId'],
-      properties: { input: operation.input, operation: { const: operation.id }, requestId: { type: 'string', minLength: 1, maxLength: 128 } },
-      'x-kind': operation.kind,
-      'x-operation': operation.id,
-    };
-    schemas[`Operation.${stem}.Reply`] = {
-      type: 'object',
-      additionalProperties: false,
-      required: ['operation', 'outcome', 'requestId'],
-      properties: { operation: { const: operation.id }, outcome: operation.refusal.length ? { oneOf: [okOutcome, refusedOutcome] } : okOutcome, requestId: { type: 'string', minLength: 1, maxLength: 128 } },
-      'x-kind': operation.kind,
-      'x-operation': operation.id,
+    const schemas = { ...components };
+    schemas['Operation.InvalidRequest'] = {
+        type: 'object',
+        additionalProperties: false,
+        required: ['code', 'kind', 'message', 'params'],
+        properties: {
+            code: { const: 'OPERATIONS_INVALID_REQUEST' },
+            kind: { const: 'invalid' },
+            message: { type: 'string', description: 'The localized canonical error message.' },
+            params: { type: 'object', additionalProperties: false },
+        },
     };
-    requests.push({ $ref: `#/components/schemas/Operation.${stem}.Request` });
-    replies.push({ $ref: `#/components/schemas/Operation.${stem}.Reply` });
-  }
-  const document = {
-    openapi: '3.1.0',
-    [INPUT_BOUNDS_OPENAPI_EXTENSION]: INPUT_BOUNDS_VERSION,
-    info: { title: `${app} operations`, version: '1' },
-    'x-operations': operations.map((operation) => ({ id: operation.id, kind: operation.kind })),
-    paths: {
-      '/operations': {
-        post: {
-          operationId: 'invokeOperation',
-          requestBody: { required: true, content: { 'application/json': { schema: { oneOf: requests } } } },
-          responses: {
-            200: { description: 'The reply of the invoked operation: its outcome is ok or a declared refusal.', content: { 'application/json': { schema: { oneOf: replies } } } },
-            400: { description: 'The envelope, operation id or input failed runtime schema validation before dispatch.', content: { 'application/json': { schema: { $ref: '#/components/schemas/Operation.InvalidRequest' } } } },
-          },
+    const requests = [];
+    const replies = [];
+    for (const operation of operations) {
+        const stem = stemOf(operation.id);
+        const okOutcome = { type: 'object', required: ['kind', 'value'], properties: { kind: { const: 'ok' }, value: operation.output } };
+        const refusedOutcome = { type: 'object', required: ['code', 'kind'], properties: { code: { enum: operation.refusal, type: 'string' }, kind: { const: 'refused' }, params: { type: 'object', additionalProperties: { type: ['string', 'number', 'boolean'] } } } };
+        schemas[`Operation.${stem}.Request`] = {
+            type: 'object',
+            additionalProperties: false,
+            required: ['input', 'operation', 'requestId'],
+            properties: { input: operation.input, operation: { const: operation.id }, requestId: { type: 'string', minLength: 1, maxLength: 128 } },
+            'x-kind': operation.kind,
+            'x-operation': operation.id,
+        };
+        schemas[`Operation.${stem}.Reply`] = {
+            type: 'object',
+            additionalProperties: false,
+            required: ['operation', 'outcome', 'requestId'],
+            properties: { operation: { const: operation.id }, outcome: operation.refusal.length ? { oneOf: [okOutcome, refusedOutcome] } : okOutcome, requestId: { type: 'string', minLength: 1, maxLength: 128 } },
+            'x-kind': operation.kind,
+            'x-operation': operation.id,
+        };
+        requests.push({ $ref: `#/components/schemas/Operation.${stem}.Request` });
+        replies.push({ $ref: `#/components/schemas/Operation.${stem}.Reply` });
+    }
+    const document = {
+        openapi: '3.1.0',
+        [INPUT_BOUNDS_OPENAPI_EXTENSION]: INPUT_BOUNDS_VERSION,
+        info: { title: `${app} operations`, version: '1' },
+        'x-operations': operations.map((operation) => ({ id: operation.id, kind: operation.kind })),
+        paths: {
+            '/operations': {
+                post: {
+                    operationId: 'invokeOperation',
+                    requestBody: { required: true, content: { 'application/json': { schema: { oneOf: requests } } } },
+                    responses: {
+                        200: { description: 'The reply of the invoked operation: its outcome is ok or a declared refusal.', content: { 'application/json': { schema: { oneOf: replies } } } },
+                        400: { description: 'The envelope, operation id or input failed runtime schema validation before dispatch.', content: { 'application/json': { schema: { $ref: '#/components/schemas/Operation.InvalidRequest' } } } },
+                    },
+                },
+            },
         },
-      },
-    },
-    components: { schemas },
-  };
-  return `${JSON.stringify(stable(document), null, 2)}\n`;
+        components: { schemas },
+    };
+    return `${JSON.stringify(stable(document), null, 2)}\n`;
 }

package/emit/schema-worker.d.mts

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

package/emit/schema-worker.mjs

@@ -14,49 +14,50 @@ import { aliasTarget, aliasesOf, appModulePath } from './contracts.mjs';
 import { compilerOptionsOf } from './compiler.mjs';
 import { createGraphReader } from './static-graph.mjs';
 import { graphqlInputBounds, withInputBounds } from './graphql-input-bounds.mjs';
-
+// The parent (contracts.mts) always passes the repository root and the app.
 const [rootArgument, app] = process.argv.slice(2);
 const repoRoot = path.resolve(rootArgument);
 const require = createRequire(path.join(repoRoot, 'package.json'));
 const ts = require('typescript');
-
 const config = ts.readConfigFile(path.join(repoRoot, 'tsconfig.json'), ts.sys.readFile).config ?? {};
 const aliases = aliasesOf(config.compilerOptions?.paths, repoRoot);
-
 // ---- step 1: the graph, from source ----
 const isFile = (candidate) => fs.existsSync(candidate) && fs.statSync(candidate).isFile();
 const host = {
-  read: (file) => (fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : null),
-  resolve(from, specifier) {
-    const aliased = aliasTarget(aliases, specifier);
-    if (aliased === null && !specifier.startsWith('.')) return null;
-    const base = (aliased ?? path.resolve(path.dirname(from), specifier)).replace(/\.js$/, '');
-    const found = [base, `${base}.ts`, path.join(base, 'index.ts')].find(isFile);
-    if (!found) throw new Error(`${from}: cannot resolve ${specifier}`);
-    return found;
-  },
+    read: (file) => (fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : null),
+    resolve(from, specifier) {
+        const aliased = aliasTarget(aliases, specifier);
+        if (aliased === null && !specifier.startsWith('.'))
+            return null;
+        const base = (aliased ?? path.resolve(path.dirname(from), specifier)).replace(/\.js$/, '');
+        const found = [base, `${base}.ts`, path.join(base, 'index.ts')].find(isFile);
+        if (!found)
+            throw new Error(`${from}: cannot resolve ${specifier}`);
+        return found;
+    },
 };
 let composition;
 try {
-  composition = createGraphReader({ ts, host }).compose(path.join(repoRoot, appModulePath(app)));
-} catch (error) {
-  process.stderr.write(`${error.message}
+    composition = createGraphReader({ ts, host }).compose(path.join(repoRoot, appModulePath(app)));
+}
+catch (error) {
+    process.stderr.write(`${error.message}
 `);
-  process.exit(1);
+    process.exit(1);
 }
-if (composition === null) process.exit(3);
+if (composition === null)
+    process.exit(3);
 require('reflect-metadata');
-
 // ---- step 2: the classes, loaded ----
 const Module = require('node:module');
-const stand = new Proxy(function standIn() {}, {
-  get: (_, key) => (key === '__esModule' ? true : key === 'then' ? undefined : key === Symbol.toPrimitive ? () => '' : stand),
-  apply: () => stand,
-  construct: () => stand,
+const stand = new Proxy(function standIn() { }, {
+    get: (_, key) => (key === '__esModule' ? true : key === 'then' ? undefined : key === Symbol.toPrimitive ? () => '' : stand),
+    apply: () => stand,
+    construct: () => stand,
 });
 const resolveFilename = Module._resolveFilename;
 Module._resolveFilename = function resolve(request, ...rest) {
-  return resolveFilename.call(this, aliasTarget(aliases, request) ?? request, ...rest);
+    return resolveFilename.call(this, aliasTarget(aliases, request) ?? request, ...rest);
 };
 // The code is compiled the way `tsc` compiles it (a Program over the resolver files and what they import), not file by file:
 // `emitDecoratorMetadata` writes the type of a decorated property from the type checker (`facet: Facet` with a string-literal
@@ -66,34 +67,40 @@ const options = compilerOptionsOf(ts, repoRoot, (message) => process.stderr.writ
 const roots = [...composition.resolvers, ...composition.scalars, ...composition.include].map(({ file }) => file);
 const program = ts.createProgram({ rootNames: [...new Set(roots)], options });
 const compile = (filename) => {
-  const sourceFile = program.getSourceFile(filename);
-  if (!sourceFile) return ts.transpileModule(fs.readFileSync(filename, 'utf8'), { fileName: filename, compilerOptions: options }).outputText;
-  let output = '';
-  program.emit(sourceFile, (name, text) => { if (name.endsWith('.js')) output = text; });
-  return output;
+    const sourceFile = program.getSourceFile(filename);
+    if (!sourceFile)
+        return ts.transpileModule(fs.readFileSync(filename, 'utf8'), { fileName: filename, compilerOptions: options }).outputText;
+    let output = '';
+    program.emit(sourceFile, (name, text) => { if (name.endsWith('.js'))
+        output = text; });
+    return output;
 };
+// reason: Module#_compile is Node's internal compile hook; the typings of Module do not declare it.
 require.extensions['.ts'] = (module, filename) => module._compile(compile(filename), filename);
 let depth = 0;
 const load = Module._load;
 Module._load = function tolerantLoad(request, parent, isMain) {
-  depth += 1;
-  try {
-    return load.call(this, request, parent, isMain);
-  } catch (error) {
-    const fromSource = typeof parent?.filename === 'string' && parent.filename.startsWith(repoRoot) && !parent.filename.includes(`${path.sep}node_modules${path.sep}`);
-    if (depth === 1 || !fromSource) throw error;
-    process.stderr.write(`stand-in ${request} (from ${parent?.filename ?? '?'}): ${String(error?.message ?? error).split('\n')[0]}\n`);
-    return stand;
-  } finally {
-    depth -= 1;
-  }
+    depth += 1;
+    try {
+        return load.call(this, request, parent, isMain);
+    }
+    catch (error) {
+        const fromSource = typeof parent?.filename === 'string' && parent.filename.startsWith(repoRoot) && !parent.filename.includes(`${path.sep}node_modules${path.sep}`);
+        if (depth === 1 || !fromSource)
+            throw error;
+        process.stderr.write(`stand-in ${request} (from ${parent?.filename ?? '?'}): ${String(error?.message ?? error).split('\n')[0]}\n`);
+        return stand;
+    }
+    finally {
+        depth -= 1;
+    }
 };
 const classOf = ({ file, name }) => {
-  const exported = require(file)[name];
-  if (typeof exported !== 'function') throw new Error(`${file} does not export the class ${name}`);
-  return exported;
+    const exported = require(file)[name];
+    if (typeof exported !== 'function')
+        throw new Error(`${file} does not export the class ${name}`);
+    return exported;
 };
-
 // The packages of the repository under emission, resolved from it (never from hfs, which declares none of them).
 const FROM_REPOSITORY = { nestGraphql: '@nestjs/graphql', nestCore: '@nestjs/core', graphql: 'graphql', classValidator: 'class-validator' };
 const graphql = require(FROM_REPOSITORY.nestGraphql);
@@ -101,14 +108,12 @@ const graphql = require(FROM_REPOSITORY.nestGraphql);
 const graphqlDist = path.dirname(require.resolve(FROM_REPOSITORY.nestGraphql));
 const { SCALAR_NAME_METADATA, SCALAR_TYPE_METADATA } = require(path.join(graphqlDist, 'graphql.constants.js'));
 const { createScalarType } = require(path.join(graphqlDist, 'utils', 'scalar-types.utils.js'));
-
 const resolvers = composition.resolvers.map(classOf);
 const scalarsMap = composition.scalars.map(classOf).map((cls) => {
-  const typeRef = Reflect.getMetadata(SCALAR_TYPE_METADATA, cls);
-  return { type: (typeof typeRef === 'function' && typeRef()) || cls, scalar: createScalarType(Reflect.getMetadata(SCALAR_NAME_METADATA, cls), new cls(...Array.from({ length: cls.length }, () => stand))) };
+    const typeRef = Reflect.getMetadata(SCALAR_TYPE_METADATA, cls);
+    return { type: (typeof typeRef === 'function' && typeRef()) || cls, scalar: createScalarType(Reflect.getMetadata(SCALAR_NAME_METADATA, cls), new cls(...Array.from({ length: cls.length }, () => stand))) };
 });
 const includeModules = composition.include.map(classOf);
-
 const { NestFactory } = require(FROM_REPOSITORY.nestCore);
 const { GraphQLSchemaBuilderModule, GraphQLSchemaFactory } = graphql;
 const { lexicographicSortSchema, parse, print, printSchema } = require(FROM_REPOSITORY.graphql);
@@ -119,9 +124,11 @@ const { TypeMetadataStorage } = require(path.join(graphqlDist, 'schema-builder',
 // A repository without class-validator has no validators, hence no bounds: only that package's absence is tolerated.
 let validationStorage = { getTargetValidationMetadatas: () => [] };
 try {
-  validationStorage = require(FROM_REPOSITORY.classValidator).getMetadataStorage();
-} catch (error) {
-  if (error?.code !== 'MODULE_NOT_FOUND' || !String(error.message).includes(`'${FROM_REPOSITORY.classValidator}'`)) throw error;
+    validationStorage = require(FROM_REPOSITORY.classValidator).getMetadataStorage();
+}
+catch (error) {
+    if (error?.code !== 'MODULE_NOT_FOUND' || !String(error.message).includes(`'${FROM_REPOSITORY.classValidator}'`))
+        throw error;
 }
 const bounds = graphqlInputBounds({ schema, typeStorage: TypeMetadataStorage, validationStorage });
 const document = parse(printed);

package/emit/static-graph.d.mts

@@ -0,0 +1,48 @@
+/**
+ * What a Nest application serves over GraphQL, read from its SOURCE: the module graph an app root composes and the resolver
+ * classes Nest GraphQL's explorers would collect from it. Nothing is executed and no configuration is needed: the app root and
+ * every module it reaches are parsed with the TypeScript compiler API and their `@Module` metadata and static registration
+ * methods (`register`, `forRoot`, ...) are interpreted symbolically. The interpretation is lazy and only follows what decides
+ * the graph: module imports, providers, `forwardRef`, spreads, conditionals (both branches are taken: the contract is the
+ * superset a deployment can serve), static methods called with the options of a deployment (unknown values), the options of
+ * `GraphQLModule.forRoot` / `forRootAsync`.
+ *
+ * Mirrors Nest: a module's providers are the `@Module({ providers })` of its class plus the `providers` of a dynamic module;
+ * likewise its imports. A GraphQL server reads the providers of EVERY module of the application unless its options carry
+ * `include`, which whitelists module classes and their transitive imports (Nest's `BaseExplorerService.getModules`).
+ *
+ * Anything the interpreter cannot decide in a position that decides the graph (a module import or a provider list) is an
+ * error naming the file and line: an answer is exact or it is not given.
+ *
+ * Injected: `ts` (the TypeScript module), `host.read(file)` (text or null) and `host.resolve(fromFile, specifier)` (an
+ * absolute file of the repository, or null for an external package). Pure of the file system otherwise.
+ */
+import type TypeScript from 'typescript';
+/** The file system seen by the reader: `read` answers text or null, `resolve` an absolute repository file or null for a package. */
+export interface GraphHost {
+    read(file: string): string | null;
+    resolve(from: string, specifier: string): string | null;
+}
+/** A class the composition names, by file and name. */
+export interface ClassRef {
+    readonly file: string;
+    readonly name: string;
+}
+/** What a composed app serves over GraphQL. */
+export interface Composition {
+    readonly resolvers: ClassRef[];
+    readonly scalars: ClassRef[];
+    readonly include: ClassRef[];
+}
+/**
+ * JavaScript's abstract equality (`==`) for the literal kinds this graph forces - string, number, boolean - without
+ * the `==` operator: one type compares strictly, a boolean compares as its number, and a number meets a string as
+ * Number(string), exactly as the language coerces them (so '' == 0, '1' == true, NaN never equals).
+ */
+export declare function looseLiteralEqual(x: string | number | boolean, y: string | number | boolean): boolean;
+export declare function createGraphReader({ ts, host }: {
+    ts: typeof TypeScript;
+    host: GraphHost;
+}): {
+    compose(appFile: string, exportName?: string): Composition | null;
+};