@starci/hfs 1.0.0 → 2.0.0

package/emit/operations-worker.mjs

@@ -0,0 +1,24 @@
+// The child process of `hfs emit-contracts` for the OPERATIONS of ONE app: `node operations-worker.mjs <repoRoot> <app>`.
+// Prints the OpenAPI 3.1 document of the app's typed operation table on stdout; exit 3 when the app has no `apps/<app>/src/operations.ts`.
+// Loads the repository's own typescript (resolved from the repository, never from hfs). Nothing of the repository is executed.
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import path from 'node:path';
+import { compilerOptionsOf } from './compiler.mjs';
+import { openApiText, operationsPath, readOperations } from './operations.mjs';
+
+const [rootArgument, app] = process.argv.slice(2);
+const repoRoot = path.resolve(rootArgument);
+const file = path.join(repoRoot, operationsPath(app));
+if (!fs.existsSync(file)) process.exit(3);
+const ts = createRequire(path.join(repoRoot, 'package.json'))('typescript');
+const options = compilerOptionsOf(ts, repoRoot, (message) => process.stderr.write(`stand-in ${message}\n`));
+const program = ts.createProgram({ rootNames: [file], options });
+try {
+  const { operations, components } = readOperations({ ts, program, file });
+  process.stdout.write(openApiText({ app, operations, components }));
+} catch (error) {
+  process.stderr.write(`${error.message}
+`);
+  process.exit(1);
+}

package/emit/operations.mjs

@@ -0,0 +1,126 @@
+/**
+ * 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/operations.yaml, BE-OPERATIONS-1):
+ * `apps/<app>/src/operations.ts` exports `OPERATIONS`, made by `defineOperations({ "<id>@<version>": operation<Input, Output,
+ * RefusalCode>("query" | "mutation") })`. The types come from the TypeScript checker; nothing is executed. An input, an output or a
+ * refusal set the checker cannot express (`any`, `unknown`, `Record<string, unknown>`, an unbound generic, `string` as a refusal code)
+ * is an error naming 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';
+
+/** The export of `apps/<app>/src/operations.ts` that holds the table. */
+export 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');
+
+/**
+ * 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 }) {
+  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 builder = createSchemaBuilder({ ts, checker });
+  const table = checker.getTypeOfSymbol(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"');
+    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 guard = (label, type) => {
+      try {
+        return builder.schemaOf(type, label);
+      } catch (error) {
+        return fail(error.message);
+      }
+    };
+    const input = guard('input', member('input'));
+    const output = guard('output', member('output'));
+    const refusalType = member('refusal');
+    let refusal = [];
+    if (!(refusalType.flags & ts.TypeFlags.Never)) {
+      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 });
+  }
+  if (operations.length === 0) throw new Error(`${file}: ${OPERATIONS_EXPORT} declares no operation`);
+  return { operations, components: builder.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 };
+  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',
+      required: ['input', 'operation', 'requestId'],
+      properties: { input: operation.input, operation: { const: operation.id }, requestId: { type: 'string', minLength: 1 } },
+      'x-kind': operation.kind,
+      'x-operation': operation.id,
+    };
+    schemas[`Operation.${stem}.Reply`] = {
+      type: 'object',
+      required: ['operation', 'outcome', 'requestId'],
+      properties: { operation: { const: operation.id }, outcome: operation.refusal.length ? { oneOf: [okOutcome, refusedOutcome] } : okOutcome, requestId: { type: 'string' } },
+      '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',
+    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 } } } } },
+        },
+      },
+    },
+    components: { schemas },
+  };
+  return `${JSON.stringify(stable(document), null, 2)}\n`;
+}

package/emit/schema-worker.mjs

@@ -0,0 +1,117 @@
+// The child process of `hfs emit-contracts` for ONE app: `node schema-worker.mjs <repoRoot> <app>`.
+// Prints the schema the app serves on stdout; exit 3 when the app's module graph has no GraphQL server.
+// Loads the repository's own typescript, @nestjs/* and graphql (resolved from the repository, never from hfs).
+//
+// Two steps: (1) the module graph of the app root is read from source (static-graph.mjs) and yields the resolver classes the
+// GraphQL server would collect; (2) only those classes are loaded, and Nest's own GraphQLSchemaFactory builds the schema.
+// Step 2 loads code through the repository's own TypeScript; a dependency of a resolver that cannot load here (configuration
+// read at import time, a native addon, an ES-only package; only requires written in the repository's own source) is replaced by a stand-in and reported on stderr, because the
+// schema depends on the resolver and type classes, never on what they call. A stand-in that is a GraphQL type fails the build.
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import path from 'node:path';
+import { aliasTarget, aliasesOf, appModulePath } from './contracts.mjs';
+import { compilerOptionsOf } from './compiler.mjs';
+import { createGraphReader } from './static-graph.mjs';
+
+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;
+  },
+};
+let composition;
+try {
+  composition = createGraphReader({ ts, host }).compose(path.join(repoRoot, appModulePath(app)));
+} catch (error) {
+  process.stderr.write(`${error.message}
+`);
+  process.exit(1);
+}
+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 resolveFilename = Module._resolveFilename;
+Module._resolveFilename = function resolve(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
+// union is `String`), which a per-file transpile cannot know and which decides GraphQL field types.
+const options = compilerOptionsOf(ts, repoRoot, (message) => process.stderr.write(`stand-in ${message}
+`));
+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;
+};
+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;
+  }
+};
+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;
+};
+
+// 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' };
+const graphql = require(FROM_REPOSITORY.nestGraphql);
+// the constants and the scalar factory are internals of the package: reached by file, its `exports` map hides them
+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 includeModules = composition.include.map(classOf);
+
+const { NestFactory } = require(FROM_REPOSITORY.nestCore);
+const { GraphQLSchemaBuilderModule, GraphQLSchemaFactory } = graphql;
+const { lexicographicSortSchema, printSchema } = require(FROM_REPOSITORY.graphql);
+const context = await NestFactory.createApplicationContext(GraphQLSchemaBuilderModule, { logger: false });
+const schema = await context.get(GraphQLSchemaFactory).create(resolvers, { scalarsMap, includeModules });
+process.stdout.write(printSchema(lexicographicSortSchema(schema)));
+await context.close();