@pepys/schema 0.0.0-stage → 0.0.1

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,23 @@
+// 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 DB {
+  github_pull_request: GithubPullRequestRow;
+}

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/generate-rust-types.ts

@@ -0,0 +1,269 @@
+import type { ColumnDeclaration, ConsumerDeclaration, TableDeclaration } from '@pepys/kit';
+import { toPascalCase } from '@pepys/kit/generators';
+import { match } from 'ts-pattern';
+import { toSnakeCase } from './to-snake-case.ts';
+
+export function generateRustTypes(consumers: readonly ConsumerDeclaration[]): string {
+  const items = [
+    [
+      '#[derive(Debug, Clone, Copy, PartialEq, Eq)]',
+      'pub struct ReadImport {',
+      "    pub table: &'static str,",
+      "    pub length: &'static str,",
+      "    pub into: &'static str,",
+      '}',
+    ].join('\n'),
+    [
+      '#[derive(Debug, Clone, Copy, PartialEq, Eq)]',
+      'pub enum ColumnKind {',
+      '    Text,',
+      '    Integer,',
+      '    Real,',
+      '    Boolean,',
+      '    Json,',
+      '    EntityId,',
+      '    Timestamp,',
+      '}',
+    ].join('\n'),
+    [
+      '#[derive(Debug, Clone, Copy, PartialEq, Eq)]',
+      'pub struct ColumnInfo {',
+      "    pub name: &'static str,",
+      '    pub kind: ColumnKind,',
+      '    pub nullable: bool,',
+      '}',
+    ].join('\n'),
+    [
+      '#[derive(Debug, Clone, Copy, PartialEq, Eq)]',
+      'pub struct TableInfo {',
+      "    pub name: &'static str,",
+      "    pub columns: &'static [ColumnInfo],",
+      "    pub primary_key: &'static [&'static str],",
+      '}',
+    ].join('\n'),
+    ...consumers.flatMap((consumer) => formatConsumer(consumer)),
+  ];
+
+  return `${items.join('\n\n')}\n`;
+}
+
+const derives = '#[derive(Debug, Clone, PartialEq, serde::Serialize, serde::Deserialize)]';
+
+function formatConsumer(consumer: ConsumerDeclaration): string[] {
+  const tables = Object.entries(consumer.tables);
+  const consumerName = toPascalCase(consumer.name);
+
+  return [
+    ...tables.flatMap(([name, table]) => [
+      formatStruct(`${toPascalCase(name)}Row`, table, Object.keys(table.columns)),
+      formatStruct(`${toPascalCase(name)}Key`, table, table.primaryKey),
+    ]),
+    formatTableEnum(`${consumerName}Upsert`, tables, 'Row'),
+    formatTableEnum(`${consumerName}Delete`, tables, 'Key'),
+    [
+      derives,
+      '#[serde(rename_all = "snake_case")]',
+      `pub enum ${consumerName}Operation {`,
+      `    Upsert(Box<${consumerName}Upsert>),`,
+      `    Delete(${consumerName}Delete),`,
+      '}',
+    ].join('\n'),
+    formatTables(consumer),
+    formatReads(consumer),
+  ];
+}
+
+function formatStruct(
+  structName: string,
+  table: TableDeclaration,
+  columnNames: readonly string[],
+): string {
+  const fields = columnNames.flatMap((columnName) => {
+    const column = table.columns[columnName];
+
+    return column === undefined ? [] : formatField(columnName, column);
+  });
+
+  return [derives, `pub struct ${structName} {`, ...fields, '}'].join('\n');
+}
+
+function formatField(columnName: string, column: ColumnDeclaration): string[] {
+  const snakeName = toSnakeCase(columnName);
+  const identifier = toRustIdentifier(snakeName);
+  const rename = identifier.replace(/^r#/u, '') === columnName ? [] : [columnName];
+  const type = toRustType(column);
+
+  return [
+    ...rename.map((sqlName) => `    #[serde(rename = "${sqlName}")]`),
+    `    pub ${identifier}: ${type},`,
+  ];
+}
+
+const rawIdentifiers = new Set([
+  'abstract',
+  'as',
+  'async',
+  'await',
+  'become',
+  'box',
+  'break',
+  'const',
+  'continue',
+  'do',
+  'dyn',
+  'else',
+  'enum',
+  'extern',
+  'false',
+  'final',
+  'fn',
+  'for',
+  'gen',
+  'if',
+  'impl',
+  'in',
+  'let',
+  'loop',
+  'macro',
+  'match',
+  'mod',
+  'move',
+  'mut',
+  'override',
+  'priv',
+  'pub',
+  'ref',
+  'return',
+  'static',
+  'struct',
+  'trait',
+  'true',
+  'try',
+  'type',
+  'typeof',
+  'unsafe',
+  'unsized',
+  'use',
+  'virtual',
+  'where',
+  'while',
+  'yield',
+]);
+
+const unescapableIdentifiers = new Set(['crate', 'self', 'Self', 'super']);
+
+function toRustIdentifier(name: string): string {
+  if (unescapableIdentifiers.has(name)) {
+    return `${name}_`;
+  }
+
+  return rawIdentifiers.has(name) ? `r#${name}` : name;
+}
+
+function toRustType(column: ColumnDeclaration): string {
+  const type = match(column.kind)
+    .with('text', 'entityID', 'timestamp', () => 'String')
+    .with('integer', () => 'i64')
+    .with('real', () => 'f64')
+    .with('boolean', () => 'bool')
+    .with('json', () => 'serde_json::Value')
+    .exhaustive();
+
+  return column.nullable === true ? `Option<${type}>` : type;
+}
+
+function formatTableEnum(
+  enumName: string,
+  tables: readonly (readonly [string, TableDeclaration])[],
+  payloadSuffix: 'Row' | 'Key',
+): string {
+  const variants = tables.flatMap(([name]) => [
+    `    #[serde(rename = "${name}")]`,
+    `    ${toPascalCase(name)}(${toPascalCase(name)}${payloadSuffix}),`,
+  ]);
+
+  return [derives, `pub enum ${enumName} {`, ...variants, '}'].join('\n');
+}
+
+function formatTables(consumer: ConsumerDeclaration): string {
+  const tables = Object.entries(consumer.tables);
+  const constantName = `${toSnakeCase(consumer.name).toUpperCase()}_TABLES`;
+
+  const entries = tables.flatMap(([name, table]) => [
+    'TableInfo {',
+    `    name: "${name}",`,
+    '    columns: &[',
+    ...Object.entries(table.columns).flatMap(([columnName, column]) =>
+      formatColumnInfo(columnName, column).map((line) => `        ${line}`),
+    ),
+    '    ],',
+    `    primary_key: &[${table.primaryKey.map((columnName) => `"${columnName}"`).join(', ')}],`,
+    '},',
+  ]);
+
+  // rustfmt hugs the brackets around a lone element and puts each of several on its own lines.
+  if (tables.length === 1) {
+    return [
+      `pub const ${constantName}: [TableInfo; 1] = [${entries[0]}`,
+      ...entries.slice(1, -1),
+      '}];',
+    ].join('\n');
+  }
+
+  return [
+    `pub const ${constantName}: [TableInfo; ${tables.length}] = [`,
+    ...entries.map((line) => `    ${line}`),
+    '];',
+  ].join('\n');
+}
+
+function formatColumnInfo(columnName: string, column: ColumnDeclaration): string[] {
+  const kind = match(column.kind)
+    .with('text', () => 'Text')
+    .with('integer', () => 'Integer')
+    .with('real', () => 'Real')
+    .with('boolean', () => 'Boolean')
+    .with('json', () => 'Json')
+    .with('entityID', () => 'EntityId')
+    .with('timestamp', () => 'Timestamp')
+    .exhaustive();
+
+  return [
+    'ColumnInfo {',
+    `    name: "${columnName}",`,
+    `    kind: ColumnKind::${kind},`,
+    `    nullable: ${column.nullable === true ? 'true' : 'false'},`,
+    '},',
+  ];
+}
+
+function formatReads(consumer: ConsumerDeclaration): string {
+  const constantName = `${toSnakeCase(consumer.name).toUpperCase()}_READS`;
+  const declaration = `pub const ${constantName}: [ReadImport; ${consumer.reads.length}] =`;
+
+  if (consumer.reads.length === 0) {
+    return `${declaration} [];`;
+  }
+
+  const imports = consumer.reads.map((table) =>
+    [
+      'ReadImport {',
+      `    table: "${table}",`,
+      `    length: "read${toPascalCase(table)}Length",`,
+      `    into: "read${toPascalCase(table)}Into",`,
+      '}',
+    ].join('\n'),
+  );
+
+  // rustfmt hugs the brackets around a lone element and puts each of several on its own lines.
+  if (imports.length === 1) {
+    return `${declaration} [${imports.join('')}];`;
+  }
+
+  const lines = imports
+    .map((entry) => `${entry},`)
+    .join('\n')
+    .split('\n');
+
+  return [`${declaration} [`, ...lines.map((line) => `    ${line}`), '];'].join('\n');
+}

package/src/generators/to-snake-case.ts

@@ -0,0 +1,6 @@
+export function toSnakeCase(name: string): string {
+  return name
+    .replaceAll(/(?<lower>[a-z0-9])(?<upper>[A-Z])/gu, '$<lower>_$<upper>')
+    .replaceAll(/[^A-Za-z0-9]+/gu, '_')
+    .toLowerCase();
+}

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,10 @@
+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 { generateRustTypes } from './generators/generate-rust-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' } };
+}