@pepys/schema 0.0.0-stage → 0.1.0

package/src/consumer-manifest/types.ts

@@ -0,0 +1,64 @@
+import type { ColumnKind, ConsumerInput, LinkTypeDeclaration, VersionHash } from '@pepys/kit';
+
+// `consumers.json`, as `pepys build` writes it. Each entry is whole, so a kept version needs no file
+// but its own entry.
+export interface ConsumerBuildManifest {
+  readonly kit: 1;
+
+  // null for a plug-in built alone
+  readonly deployment: string | null;
+  readonly consumers: readonly ListedConsumer[];
+}
+
+export interface ConsumerVersion {
+  readonly name: string;
+
+  // the SHA-256 of the module's bytes
+  readonly module: VersionHash;
+
+  // enrichment champions; `{}` in v1
+  readonly pins: Readonly<Record<string, VersionHash>>;
+
+  // The SHA-256 of `module`, `pins` and `manifest` as JSON with sorted keys. The host names the
+  // version's folder by it and never computes it.
+  readonly version: VersionHash;
+  readonly manifest: ConsumerManifest;
+}
+
+export interface ListedConsumer extends ConsumerVersion {
+  // the module file, relative to `consumers.json`
+  readonly path: string;
+}
+
+export interface ConsumerManifest {
+  readonly name: string;
+  readonly input: ConsumerInput;
+
+  // the two symbols that the host calls
+  readonly exports: { readonly init: string; readonly apply: string };
+
+  // every read that the host serves the module, with its two symbols
+  readonly imports: readonly ManifestRead[];
+  readonly tables: Readonly<Record<string, ManifestTable>>;
+  readonly links: readonly LinkTypeDeclaration[];
+
+  // the consumer's tables, its indexes and its `entity` view, as the kit's SQL generator writes them
+  readonly schema: string;
+}
+
+// A `row` read serves a fact consumer one row of its own tables by key. A `scope_facts` read serves a
+// scope consumer every fact of the scope's entity.
+export type ManifestRead =
+  | { readonly kind: 'row'; readonly table: string; readonly length: string; readonly into: string }
+  | { readonly kind: 'scope_facts'; readonly length: string; readonly into: string };
+
+export interface ManifestTable {
+  readonly columns: Readonly<Record<string, ManifestColumn>>;
+  readonly primaryKey: readonly string[];
+  readonly indexes: readonly (readonly string[])[];
+}
+
+export interface ManifestColumn {
+  readonly kind: ColumnKind;
+  readonly nullable: boolean;
+}

package/src/generated/kysely-db.ts

@@ -0,0 +1,86 @@
+// Generated by `bun run schema:generate`. Do not edit.
+
+export interface GithubPullRequestRow {
+  id: string;
+  number: number;
+  repository_id: string;
+  title: string;
+  state: string;
+  is_draft: 0 | 1;
+  is_merged: 0 | 1;
+  author_id: string | null;
+  url: string;
+  merge_commit_sha: string | null;
+  created_at: string;
+  updated_at: string;
+  closed_at: string | null;
+  merged_at: string | null;
+  payload: unknown;
+}
+
+export interface GithubReleaseBumpRow {
+  pull_request_id: string;
+  release_repository: string;
+  release_tag: string;
+}
+
+export interface GithubReleaseRow {
+  id: string;
+  repository_id: string;
+  repository_full_name: string;
+  tag_name: string;
+  target_commitish: string;
+  name: string;
+  url: string;
+  is_draft: 0 | 1;
+  is_prerelease: 0 | 1;
+  created_at: string;
+  published_at: string | null;
+  updated_at: string;
+  deleted_at: string | null;
+}
+
+export interface GithubCommitRow {
+  repository_id: string;
+  sha: string;
+  committed_at: string;
+}
+
+export interface GithubDeployRow {
+  id: string;
+  repository_id: string;
+  environment: string;
+  target: string | null;
+  sha: string;
+  signal: string;
+  deployed_at: string;
+}
+
+export interface LedgerAccountRow {
+  id: string;
+  name: string | null;
+  balance: number;
+  is_closed: 0 | 1;
+  opened_at: string | null;
+  updated_at: string;
+}
+
+export interface LedgerEntryRow {
+  id: string;
+  account_id: string;
+  amount: number;
+  rate: number;
+  memo: string;
+  details: unknown;
+  posted_at: string;
+}
+
+export interface DB {
+  github_pull_request: GithubPullRequestRow;
+  github_release_bump: GithubReleaseBumpRow;
+  github_release: GithubReleaseRow;
+  github_commit: GithubCommitRow;
+  github_deploy: GithubDeployRow;
+  ledger_account: LedgerAccountRow;
+  ledger_entry: LedgerEntryRow;
+}

package/src/generators/collect-tables.ts

@@ -0,0 +1,17 @@
+import type { ConsumerDeclaration, TableDeclaration } from '@pepys/kit';
+
+export interface TableEntry {
+  consumer: string;
+  name: string;
+  table: TableDeclaration;
+}
+
+export function collectTables(consumers: readonly ConsumerDeclaration[]): TableEntry[] {
+  return consumers.flatMap((consumer) =>
+    Object.entries(consumer.tables).map(([name, table]) => ({
+      consumer: consumer.name,
+      name,
+      table,
+    })),
+  );
+}

package/src/generators/format-typescript-row.ts

@@ -0,0 +1,16 @@
+import type { TableDeclaration } from '@pepys/kit';
+import { toPascalCase } from '@pepys/kit/generators';
+import { toTypeScriptType } from './to-typescript-type.ts';
+import type { TypeScriptTypeNames } from './to-typescript-type.ts';
+
+export function formatTypeScriptRow(
+  tableName: string,
+  table: TableDeclaration,
+  names: TypeScriptTypeNames,
+): string {
+  const fields = Object.entries(table.columns).map(
+    ([name, column]) => `  ${name}: ${toTypeScriptType(column, names)};`,
+  );
+
+  return [`export interface ${toPascalCase(tableName)}Row {`, ...fields, '}'].join('\n');
+}

package/src/generators/generate-kysely-types.ts

@@ -0,0 +1,21 @@
+import type { ConsumerDeclaration } from '@pepys/kit';
+import { toPascalCase } from '@pepys/kit/generators';
+import { collectTables } from './collect-tables.ts';
+import { formatTypeScriptRow } from './format-typescript-row.ts';
+
+export function generateKyselyTypes(consumers: readonly ConsumerDeclaration[]): string {
+  const tables = collectTables(consumers);
+
+  // SQLite has no boolean type, so the driver reads a boolean column back as 0 or 1
+  const rows = tables.map((entry) =>
+    formatTypeScriptRow(entry.name, entry.table, { entityID: 'string', boolean: '0 | 1' }),
+  );
+
+  const database = [
+    'export interface DB {',
+    ...tables.map((entry) => `  ${entry.name}: ${toPascalCase(entry.name)}Row;`),
+    '}',
+  ].join('\n');
+
+  return `${[...rows, database].join('\n\n')}\n`;
+}

package/src/generators/to-typescript-type.ts

@@ -0,0 +1,19 @@
+import type { ColumnDeclaration } from '@pepys/kit';
+import { match } from 'ts-pattern';
+
+export interface TypeScriptTypeNames {
+  entityID: string;
+  boolean: string;
+}
+
+export function toTypeScriptType(column: ColumnDeclaration, names: TypeScriptTypeNames): string {
+  const type = match(column.kind)
+    .with('text', 'timestamp', () => 'string')
+    .with('integer', 'real', () => 'number')
+    .with('boolean', () => names.boolean)
+    .with('json', () => 'unknown')
+    .with('entityID', () => names.entityID)
+    .exhaustive();
+
+  return column.nullable === true && column.kind !== 'json' ? `${type} | null` : type;
+}

package/src/index.ts

@@ -0,0 +1,9 @@
+export { consumerBuildManifestSchema } from './consumer-manifest/consumer-build-manifest-schema.ts';
+export type * from './consumer-execution/types.ts';
+export type * from './consumer-manifest/types.ts';
+export { generateKyselyTypes } from './generators/generate-kysely-types.ts';
+export type { DB } from './generated/kysely-db.ts';
+export { isEntityOfKind } from './link-registry/is-entity-of-kind.ts';
+export type * from './link-registry/link-registry.ts';
+export { makeShutdownHandler } from './service/make-shutdown-handler.ts';
+export { parsePort } from './service/parse-port.ts';

package/src/link-registry/is-entity-of-kind.ts

@@ -0,0 +1,12 @@
+import { parseEntityID } from '@pepys/kit';
+import type { EntityID, EntityKind } from '@pepys/kit';
+import type { KindedID } from './link-registry.ts';
+
+export function isEntityOfKind<Kind extends EntityKind>(
+  id: EntityID,
+  kinds: readonly Kind[],
+): id is KindedID<Kind> {
+  const parsed = parseEntityID(id);
+
+  return parsed.ok && kinds.some((kind) => kind === `${parsed.value.source}:${parsed.value.kind}`);
+}

package/src/link-registry/link-registry.ts

@@ -0,0 +1,65 @@
+import type {
+  ClientID,
+  EntityID,
+  EntityKind,
+  FactID,
+  LinkTypeDeclaration,
+  Reference,
+} from '@pepys/kit';
+
+// A plain string key, not a symbol: scriptc refuses the type-fest import that a symbol brand
+// needs, and the brand a consumer generates must have the same shape.
+export type KindedID<Kind extends EntityKind> = EntityID & { readonly '~entityKind': Kind };
+
+export type LinkRegistry = Readonly<
+  Record<string, { readonly from: readonly EntityKind[]; readonly to: readonly EntityKind[] }>
+>;
+
+export type LinkRegistryOf<Declaration extends LinkTypeDeclaration> = {
+  readonly [Entry in Declaration as Entry['name']]: {
+    readonly from: Entry['from'];
+    readonly to: Entry['to'];
+  };
+};
+
+export type LinkTypeName<Registry extends LinkRegistry> = keyof Registry & string;
+
+export type LinkTypeSources<
+  Registry extends LinkRegistry,
+  Name extends LinkTypeName<Registry>,
+> = Registry[Name]['from'][number];
+
+export type LinkTypeTargets<
+  Registry extends LinkRegistry,
+  Name extends LinkTypeName<Registry>,
+> = Registry[Name]['to'][number];
+
+export type LinkTarget<To extends EntityKind> =
+  | { kind: 'entity'; id: KindedID<To> }
+  | { kind: 'reference'; reference: Reference };
+
+export type LinkOrigin =
+  | { kind: 'consumer'; name: string }
+  | { kind: 'manual'; client: ClientID; fact: FactID };
+
+// A mapped union, not one object type: `Omit` over a union of link types loses the pairing of each
+// type name with the kinds it allows.
+export type LinkEnds<Registry extends LinkRegistry> = {
+  [Name in LinkTypeName<Registry>]: {
+    type: Name;
+    from: KindedID<LinkTypeSources<Registry, Name>>;
+    to: LinkTarget<LinkTypeTargets<Registry, Name>>;
+  };
+}[LinkTypeName<Registry>];
+
+export interface LinkDetails {
+  scope: string | null;
+  confidence: number;
+  evidence: string;
+}
+
+export type Link<Registry extends LinkRegistry> = LinkEnds<Registry> & LinkDetails;
+
+export type EffectiveLink<Registry extends LinkRegistry> = Link<Registry> & { origin: LinkOrigin };
+
+export type LinkRetraction<Registry extends LinkRegistry> = LinkEnds<Registry>;

package/src/service/make-shutdown-handler.ts

@@ -0,0 +1,28 @@
+interface ShutdownSteps {
+  stop: () => Promise<void>;
+  logError: (message: string, error: unknown) => void;
+  exit: (code: number) => void;
+}
+
+export function makeShutdownHandler(steps: ShutdownSteps): () => Promise<void> {
+  let shutdown: Promise<void> | undefined;
+
+  return () => {
+    shutdown ??= runShutdown(steps);
+
+    return shutdown;
+  };
+}
+
+async function runShutdown(steps: ShutdownSteps): Promise<void> {
+  try {
+    await steps.stop();
+  } catch (error: unknown) {
+    steps.logError('shutdown failed', error);
+    steps.exit(1);
+
+    return;
+  }
+
+  steps.exit(0);
+}

package/src/service/parse-port.ts

@@ -0,0 +1,13 @@
+import type { Result } from '@pepys/kit';
+
+const digitsPattern = /^[0-9]+$/u;
+
+export function parsePort(text: string): Result<number, { reason: 'not-a-port' }> {
+  const port = digitsPattern.test(text) ? Number(text) : Number.NaN;
+
+  if (port >= 1 && port <= 65_535) {
+    return { ok: true, value: port };
+  }
+
+  return { ok: false, failure: { reason: 'not-a-port' } };
+}