@shipfox/api-definitions 2.0.0

package/src/core/workflow-yaml/README.md

@@ -0,0 +1,77 @@
+# Workflow YAML
+
+This module reads workflow files written in YAML.
+
+## What it does
+
+- **`parseWorkflowYaml(source)`**: Reads YAML source text and returns a
+  `WorkflowDocument`.
+- **`parseWorkflowYamlWithLocations(source)`**: Reads YAML source text and
+  returns both the `WorkflowDocument` and source line ranges for authored
+  `jobs.*.steps[]` entries.
+- **`InvalidWorkflowYamlError`**: Reports bad YAML and roots that are not
+  objects.
+- **Document checks**: Sends parsed objects to
+  `@shipfox/workflow-document`.
+
+Use this module when file text has to become the shared document shape. It is
+small on purpose. It reads text, checks that the root is an object, and passes
+that object to the document package.
+
+This keeps the first step easy to test. Code that has found a file can call this
+part and then pass the result to the next step. Keep new rules out of this part
+unless they are about how YAML text is read or where authored YAML nodes appeared
+in the source.
+
+If a rule needs to know about jobs, ids, or run order beyond extracting a YAML
+node's source range, put that rule in a later part. This part should stay easy
+to read and easy to change.
+
+That keeps the next part clear too.
+
+## Installation / Setup
+
+This code is part of `@shipfox/api-definitions`. It is not a standalone package.
+
+```json
+{
+  "dependencies": {
+    "@shipfox/workflow-document": "workspace:*",
+    "js-yaml": "^4.1.0",
+    "yaml": "^2.8.3"
+  }
+}
+```
+
+## Usage
+
+```ts
+import {parseWorkflowYaml} from '#core/workflow-yaml/index.js';
+
+const document = parseWorkflowYaml(`
+name: simple build
+jobs:
+  build:
+    steps:
+      - run: npm test
+`);
+
+console.log(document.jobs.build.steps[0]?.run);
+```
+
+## Behavior Notes
+
+The parser owns only YAML concerns. It does not set defaults. It does not change
+job ids. It does not build job graphs. It does not check expressions.
+
+## Development
+
+```sh
+turbo check --filter=@shipfox/api-definitions
+turbo type --filter=@shipfox/api-definitions
+turbo test --filter=@shipfox/api-definitions
+```
+
+## License
+
+MIT

package/src/core/workflow-yaml/index.ts

@@ -0,0 +1,11 @@
+export {
+  InvalidWorkflowYamlError,
+  type InvalidWorkflowYamlReason,
+  invalidWorkflowYamlErrorCode,
+  type WorkflowYamlLocation,
+} from './invalid-workflow-yaml-error.js';
+export {
+  type ParsedWorkflowYaml,
+  parseWorkflowYaml,
+  parseWorkflowYamlWithLocations,
+} from './parse-workflow-yaml.js';

package/src/core/workflow-yaml/invalid-workflow-yaml-error.ts

@@ -0,0 +1,23 @@
+export const invalidWorkflowYamlErrorCode = 'invalid-workflow-yaml';
+
+export type InvalidWorkflowYamlReason = 'syntax' | 'non-object-root';
+
+export interface WorkflowYamlLocation {
+  readonly line: number;
+  readonly column: number;
+}
+
+export class InvalidWorkflowYamlError extends Error {
+  readonly code = invalidWorkflowYamlErrorCode;
+  readonly location: WorkflowYamlLocation | undefined;
+
+  constructor(
+    readonly reason: InvalidWorkflowYamlReason,
+    message: string,
+    options: {cause?: unknown; location?: WorkflowYamlLocation | undefined} = {},
+  ) {
+    super(message, {cause: options.cause});
+    this.name = 'InvalidWorkflowYamlError';
+    this.location = options.location;
+  }
+}

package/src/core/workflow-yaml/parse-workflow-yaml.test.ts

@@ -0,0 +1,71 @@
+import {readFile} from 'node:fs/promises';
+import {fileURLToPath} from 'node:url';
+import {InvalidWorkflowDocumentError} from '@shipfox/workflow-document';
+import {InvalidWorkflowYamlError} from './invalid-workflow-yaml-error.js';
+import {parseWorkflowYaml} from './parse-workflow-yaml.js';
+
+async function readFixture(path: string): Promise<string> {
+  const fixtureUrl = import.meta.resolve(`#test/fixtures/workflow-yaml/${path}`);
+  return await readFile(fileURLToPath(fixtureUrl), 'utf8');
+}
+
+describe('parseWorkflowYaml', () => {
+  it('parses valid workflow YAML into a workflow document', async () => {
+    const source = await readFixture('valid/simple-build.yaml');
+    const expected = JSON.parse(await readFixture('valid/simple-build.document.json')) as unknown;
+
+    const document = parseWorkflowYaml(source);
+
+    expect(document).toEqual(expected);
+  });
+
+  it('throws a typed YAML error for YAML syntax errors', async () => {
+    const source = await readFixture('invalid/invalid-yaml-syntax.yaml');
+
+    try {
+      parseWorkflowYaml(source);
+      expect.fail('Expected InvalidWorkflowYamlError');
+    } catch (error) {
+      expect(error).toBeInstanceOf(InvalidWorkflowYamlError);
+      expect(error).toMatchObject({
+        code: 'invalid-workflow-yaml',
+        reason: 'syntax',
+      });
+      expect((error as InvalidWorkflowYamlError).location?.line).toBeGreaterThanOrEqual(1);
+      expect((error as InvalidWorkflowYamlError).location?.column).toBeGreaterThanOrEqual(1);
+      expect((error as Error).message).toContain('Invalid workflow YAML syntax:');
+      expect((error as Error).cause).toBeDefined();
+    }
+  });
+
+  it.each([
+    ['array root', '- npm test'],
+    ['scalar root', '42'],
+    ['empty input', ''],
+  ])('throws a typed YAML error for %s', (_name, source) => {
+    try {
+      parseWorkflowYaml(source);
+      expect.fail('Expected InvalidWorkflowYamlError');
+    } catch (error) {
+      expect(error).toBeInstanceOf(InvalidWorkflowYamlError);
+      expect(error).toMatchObject({
+        code: 'invalid-workflow-yaml',
+        reason: 'non-object-root',
+      });
+    }
+  });
+
+  it('delegates workflow document validation to the shared document package', async () => {
+    const source = await readFixture('invalid/missing-step-run.yaml');
+
+    try {
+      parseWorkflowYaml(source);
+      expect.fail('Expected InvalidWorkflowDocumentError');
+    } catch (error) {
+      expect(error).toBeInstanceOf(InvalidWorkflowDocumentError);
+      expect((error as InvalidWorkflowDocumentError).validationError.issues[0]).toMatchObject({
+        path: ['jobs', 'build', 'steps', 0],
+      });
+    }
+  });
+});

package/src/core/workflow-yaml/parse-workflow-yaml.ts

@@ -0,0 +1,74 @@
+import {parseWorkflowDocument, type WorkflowDocument} from '@shipfox/workflow-document';
+import yaml from 'js-yaml';
+import type {WorkflowStepSourceLocationMap} from '../entities/workflow-model.js';
+import {
+  InvalidWorkflowYamlError,
+  type WorkflowYamlLocation,
+} from './invalid-workflow-yaml-error.js';
+import {extractWorkflowStepSourceLocations} from './source-locations.js';
+
+export interface ParsedWorkflowYaml {
+  document: WorkflowDocument;
+  stepSourceLocations: WorkflowStepSourceLocationMap;
+}
+
+export function parseWorkflowYaml(source: string): WorkflowDocument {
+  return parseWorkflowDocument(loadWorkflowYaml(source));
+}
+
+export function parseWorkflowYamlWithLocations(source: string): ParsedWorkflowYaml {
+  const parsed = loadWorkflowYaml(source);
+
+  return {
+    document: parseWorkflowDocument(parsed),
+    stepSourceLocations: extractWorkflowStepSourceLocations(source),
+  };
+}
+
+function loadWorkflowYaml(source: string): Record<string, unknown> {
+  let parsed: unknown;
+  try {
+    parsed = yaml.load(source);
+  } catch (error) {
+    throw new InvalidWorkflowYamlError(
+      'syntax',
+      `Invalid workflow YAML syntax: ${yamlErrorMessage(error)}`,
+      {cause: error, location: yamlErrorLocation(error)},
+    );
+  }
+
+  if (!isRecord(parsed)) {
+    throw new InvalidWorkflowYamlError('non-object-root', 'Workflow YAML must parse to an object.');
+  }
+
+  return parsed;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function yamlErrorMessage(error: unknown): string {
+  if (
+    error !== null &&
+    typeof error === 'object' &&
+    typeof (error as {reason?: unknown}).reason === 'string'
+  ) {
+    return (error as {reason: string}).reason;
+  }
+
+  return error instanceof Error ? error.message : String(error);
+}
+
+function yamlErrorLocation(error: unknown): WorkflowYamlLocation | undefined {
+  if (error === null || typeof error !== 'object') return undefined;
+
+  const mark = (error as {mark?: unknown}).mark;
+  if (mark === null || typeof mark !== 'object') return undefined;
+
+  const line = (mark as {line?: unknown}).line;
+  const column = (mark as {column?: unknown}).column;
+  if (typeof line !== 'number' || typeof column !== 'number') return undefined;
+
+  return {line: line + 1, column: column + 1};
+}

package/src/core/workflow-yaml/source-locations.ts

@@ -0,0 +1,62 @@
+import {isMap, isNode, isScalar, isSeq, LineCounter, parseDocument, type YAMLMap} from 'yaml';
+import type {
+  WorkflowSourceLocation,
+  WorkflowStepSourceLocationMap,
+} from '../entities/workflow-model.js';
+
+export function extractWorkflowStepSourceLocations(source: string): WorkflowStepSourceLocationMap {
+  const lineCounter = new LineCounter();
+  const document = parseDocument(source, {lineCounter});
+  if (document.errors.length > 0 || !isMap(document.contents)) return new Map();
+
+  const jobs = getMapValue(document.contents, 'jobs');
+  if (!isMap(jobs)) return new Map();
+
+  const locations = new Map<string, Map<number, WorkflowSourceLocation>>();
+
+  for (const jobPair of jobs.items) {
+    const jobName = scalarString(jobPair.key);
+    if (jobName === undefined || !isMap(jobPair.value)) continue;
+
+    const steps = getMapValue(jobPair.value, 'steps');
+    if (!isSeq(steps)) continue;
+
+    const stepLocations = new Map<number, WorkflowSourceLocation>();
+    for (const [index, step] of steps.items.entries()) {
+      const location = sourceLocationFor(step, lineCounter);
+      if (location) stepLocations.set(index, location);
+    }
+
+    if (stepLocations.size > 0) locations.set(jobName, stepLocations);
+  }
+
+  return locations;
+}
+
+function getMapValue(map: YAMLMap, key: string): unknown {
+  for (const item of map.items) {
+    if (scalarString(item.key) === key) return item.value;
+  }
+
+  return undefined;
+}
+
+function scalarString(node: unknown): string | undefined {
+  return isScalar(node) && typeof node.value === 'string' ? node.value : undefined;
+}
+
+function sourceLocationFor(
+  node: unknown,
+  lineCounter: LineCounter,
+): WorkflowSourceLocation | undefined {
+  if (!isNode(node)) return undefined;
+  const range = node?.range;
+  if (!range) return undefined;
+
+  const start = lineCounter.linePos(range[0]);
+  const end = lineCounter.linePos(range[1]);
+  if (!start || !end) return undefined;
+
+  const endLine = end.col === 1 && end.line > start.line ? end.line - 1 : end.line;
+  return {startLine: start.line, endLine: Math.max(start.line, endLine)};
+}

package/src/db/db.ts

@@ -0,0 +1,18 @@
+import {drizzle, type NodePgDatabase} from '@shipfox/node-drizzle';
+import {pgClient} from '@shipfox/node-postgres';
+import {workflowDefinitions} from './schema/definitions.js';
+import {definitionsOutbox} from './schema/outbox.js';
+import {definitionSyncStates} from './schema/sync-states.js';
+
+export const schema = {workflowDefinitions, definitionsOutbox, definitionSyncStates};
+
+let _db: NodePgDatabase<typeof schema> | undefined;
+
+export function db() {
+  if (!_db) _db = drizzle(pgClient(), {schema});
+  return _db;
+}
+
+export function closeDb(): void {
+  _db = undefined;
+}

package/src/db/definition-triggers.test.ts

@@ -0,0 +1,95 @@
+import type {WorkflowModel, WorkflowModelTrigger} from '#core/entities/workflow-model.js';
+import {definitionTriggersFor} from './definition-triggers.js';
+
+function workflowModelWithTriggers(triggers: readonly WorkflowModelTrigger[]): WorkflowModel {
+  return {
+    kind: 'workflow',
+    name: 'Test',
+    triggers,
+    jobs: [],
+    dependencies: [],
+  };
+}
+
+describe('definitionTriggersFor', () => {
+  it('projects model triggers to the public outbox trigger DTO shape', () => {
+    const model = workflowModelWithTriggers([
+      {
+        id: 'push',
+        key: 'push',
+        source: 'github',
+        event: 'push',
+        inputs: {branch: 'main'},
+        filter: 'event.ref == "refs/heads/main"',
+      },
+    ]);
+
+    const result = definitionTriggersFor(model);
+
+    expect(result).toEqual({
+      push: {
+        source: 'github',
+        event: 'push',
+        with: {branch: 'main'},
+        filter: 'event.ref == "refs/heads/main"',
+      },
+    });
+    expect(result.push).not.toHaveProperty('on');
+  });
+
+  it('omits absent optional trigger fields', () => {
+    const model = workflowModelWithTriggers([
+      {
+        id: 'manual',
+        key: 'manual',
+        source: 'manual',
+        event: 'fire',
+      },
+    ]);
+
+    const result = definitionTriggersFor(model);
+
+    expect(result).toEqual({
+      manual: {
+        source: 'manual',
+        event: 'fire',
+      },
+    });
+  });
+
+  it('projects cron config to the public outbox trigger DTO shape', () => {
+    const model = workflowModelWithTriggers([
+      {
+        id: 'nightly',
+        key: 'nightly',
+        source: 'cron',
+        event: 'tick',
+        config: {
+          schedule: '0 2 * * *',
+          timezone: 'UTC',
+        },
+      },
+    ]);
+
+    const result = definitionTriggersFor(model);
+
+    expect(result).toEqual({
+      nightly: {
+        source: 'cron',
+        event: 'tick',
+        config: {
+          schedule: '0 2 * * *',
+          timezone: 'UTC',
+        },
+      },
+    });
+  });
+
+  it('returns an empty object when the model has no triggers', () => {
+    const model = workflowModelWithTriggers([]);
+
+    const result = definitionTriggersFor(model);
+
+    expect(result).toEqual({});
+  });
+});

package/src/db/definition-triggers.ts

@@ -0,0 +1,17 @@
+import type {TriggerDto} from '@shipfox/api-definitions-dto';
+import type {WorkflowModel} from '#core/entities/workflow-model.js';
+
+export function definitionTriggersFor(model: WorkflowModel): Record<string, TriggerDto> {
+  return Object.fromEntries(
+    model.triggers.map((trigger) => {
+      const dto: TriggerDto = {
+        source: trigger.source,
+        event: trigger.event,
+      };
+      if (trigger.inputs !== undefined) dto.with = trigger.inputs;
+      if (trigger.filter !== undefined) dto.filter = trigger.filter;
+      if (trigger.config !== undefined) dto.config = trigger.config;
+      return [trigger.key, dto];
+    }),
+  );
+}