feat: export test documentation schemas from package root

cli/README.md

@@ -42,6 +42,52 @@ To publish the repository to npm (needs permission)
 1. Build for release `npm run build-prod`
 2. Publish `npm publish --access public`
 
+## Using schemas in TypeScript and JavaScript
+
+Install the package in your project with `npm install @cds-au/testdocs`.
+Import schema types and functions directly from the package:
+
+```typescript
+import type {
+  ConsumerDataRightTestCaseJSONSchema,
+  CDRTestDocumentationChangelogSchema,
+  TestCase,
+  Suite
+} from '@cds-au/testdocs';
+import { testDocSchema, changeLogSchema } from '@cds-au/testdocs';
+
+const testDocumentationSchema = testDocSchema();
+const changelogSchema = changeLogSchema();
+```
+
+The types describe test documentation and changelog data. They are erased
+during TypeScript compilation. The functions return the corresponding JSON
+schemas for use with a validator; importing a type does not validate data.
+
+JavaScript callers can use the same functions:
+
+```javascript
+const { testDocSchema, changeLogSchema } = require('@cds-au/testdocs');
+```
+
+Existing imports through `@cds-au/testdocs/dist/...` remain available.
+
+### Checking package imports
+
+After building the CLI, run these commands from `cli` in a bash-compatible
+terminal. They install the packed package in a separate consumer directory
+and check public types, runtime schemas, existing deep imports and CLI help.
+
+```bash
+consumer=$(mktemp -d)
+npm pack --pack-destination "$consumer"
+npm install --prefix "$consumer" "$consumer/cds-au-testdocs-1.0.0.tgz" --ignore-scripts
+node test/package-imports.js "$consumer"
+```
+
+Use the tarball filename reported by `npm pack` if the package version changes.
+The check uses the TypeScript dependency installed in `cli/node_modules`.
+
 ## Using the CLI Commands
 
 ### Schema Command Documentation

cli/src/index.ts

@@ -1,4 +1,6 @@
-//export * from './logic/schema';
+export * from './schemas/cdr-test-doc-schema';
+export * from './schemas/cdr-test-changelog-schema';
+export { testDocSchema, changeLogSchema } from './logic/schemas';
 export * from './logic/validate';
 export {
   markdown as markdownDocGenerator,

cli/test/package-imports.js

@@ -0,0 +1,72 @@
+const assert = require('assert');
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+const ts = require('typescript');
+
+// Run against a consumer directory with the packed package installed.
+const consumer = path.resolve(process.argv[2] || '.');
+const resolve = name => require.resolve(name, { paths: [consumer] });
+const fixtureDir = fs.mkdtempSync(path.join(consumer, 'testdocs-imports-'));
+const fixture = path.join(fixtureDir, 'imports.ts');
+
+try {
+  fs.writeFileSync(fixture, `
+import {
+  ConsumerDataRightTestCaseJSONSchema, CDRTestDocumentationChangelogSchema,
+  AssertionPredicate, TestCaseStep, TestCasePredicate, ScenarioAction,
+  Assertion, Reference, TestCase, Scenario, Suite, Change,
+  testDocSchema, changeLogSchema, validateSchema,
+  markdownDocGenerator, htmlDocGenerator
+} from '@cds-au/testdocs';
+import { ConsumerDataRightTestCaseJSONSchema as DeepTestDoc }
+  from '@cds-au/testdocs/dist/schemas/cdr-test-doc-schema';
+import { CDRTestDocumentationChangelogSchema as DeepChangelog }
+  from '@cds-au/testdocs/dist/schemas/cdr-test-changelog-schema';
+
+const document = (value: ConsumerDataRightTestCaseJSONSchema): DeepTestDoc => value;
+const changelog = (value: CDRTestDocumentationChangelogSchema): DeepChangelog => value;
+const wait: TestCaseStep = { type: 'WAIT', period: 1 };
+// @ts-expect-error The public type must still reject an invalid wait period.
+const invalidWait: TestCaseStep = { type: 'WAIT', period: 'one' };
+testDocSchema();
+changeLogSchema();
+`);
+  const program = ts.createProgram([fixture], {
+    noEmit: true,
+    strict: true,
+    skipLibCheck: true,
+    esModuleInterop: true,
+    resolveJsonModule: true,
+    target: ts.ScriptTarget.ES2016,
+    module: ts.ModuleKind.CommonJS,
+    moduleResolution: ts.ModuleResolutionKind.NodeJs
+  });
+  const diagnostics = ts.getPreEmitDiagnostics(program);
+  assert.strictEqual(diagnostics.length, 0, ts.formatDiagnosticsWithColorAndContext(diagnostics, {
+    getCanonicalFileName: name => name,
+    getCurrentDirectory: () => consumer,
+    getNewLine: () => '\n'
+  }));
+  console.log('PASS: package-root types, existing deep imports and type checking');
+
+  const api = require(resolve('@cds-au/testdocs'));
+  const deep = require(resolve('@cds-au/testdocs/dist/logic/schemas'));
+  assert.strictEqual(api.testDocSchema, deep.testDocSchema);
+  assert.strictEqual(api.changeLogSchema, deep.changeLogSchema);
+  assert.deepStrictEqual(api.testDocSchema(), require(resolve('@cds-au/testdocs/dist/schemas/cdr-test-doc-schema.json')));
+  assert.deepStrictEqual(api.changeLogSchema(), require(resolve('@cds-au/testdocs/dist/schemas/cdr-test-changelog-schema.json')));
+  for (const name of ['validateSchema', 'markdownDocGenerator', 'htmlDocGenerator']) {
+    assert.strictEqual(typeof api[name], 'function');
+  }
+  console.log('PASS: runtime schemas and existing API exports');
+
+  const help = execFileSync(process.execPath, [resolve('@cds-au/testdocs/dist/cli.js'), '--help'], { encoding: 'utf8' });
+  assert.ok(help.includes('schema <type>'));
+  assert.ok(help.includes('validate'));
+  assert.ok(help.includes('generate'));
+  console.log('PASS: installed CLI help');
+} finally {
+  if (fs.existsSync(fixture)) fs.unlinkSync(fixture);
+  fs.rmdirSync(fixtureDir);
+}