@boxxy/rules 0.0.0-stage → 0.1.3

package/src/parse/rules-file-schema.ts

@@ -0,0 +1,177 @@
+import type { Effort } from '@boxxy/model';
+import { brandSchemas } from '@boxxy/model';
+import { z } from 'zod';
+import { parseConceptEntry } from './parse-concept-entry.ts';
+
+const nameSchema = z.string().min(1);
+
+const pluginRefSchema = z.union([
+  nameSchema,
+  z.record(nameSchema, z.json()).refine((ref) => Object.keys(ref).length === 1, {
+    message: 'a plug-in reference with parameters is a map with one key, the plug-in name',
+  }),
+]);
+
+const edgeSchema = z.union([
+  z.literal('next'),
+  z.literal('again'),
+  z.strictObject({
+    to: brandSchemas.phaseName,
+    max: z.int().positive().exactOptional(),
+    resume: z.boolean().exactOptional(),
+  }),
+  z.strictObject({ end: nameSchema }),
+  z.strictObject({ hold: brandSchemas.rulesHoldReason }),
+]);
+
+// `timeoutMinutes` is optional here so that the loader refuses a step without it by its own reason
+const stepSchema = z.strictObject({
+  phase: brandSchemas.phaseName,
+  maxAttempts: z.int().positive(),
+  timeoutMinutes: z.int().positive().optional(),
+  on: z.record(nameSchema, edgeSchema),
+});
+
+const kindSchema = z.strictObject({
+  pipeline: brandSchemas.pipelineName,
+
+  // by phase, and by `<phase>/attended` for an attended session of the phase
+  recipes: z.record(nameSchema, brandSchemas.recipeName),
+});
+
+const filterSchema = z.record(nameSchema, z.union([nameSchema, z.array(nameSchema).min(1)]));
+
+const limitSchema = z.strictObject({
+  name: brandSchemas.limitName,
+  max: z.int().positive(),
+  counts: filterSchema,
+});
+
+const poolSchema = z.strictObject({
+  name: brandSchemas.poolName,
+  slots: z.never({ error: 'a pool has no slot count; a limit caps its attempts' }).optional(),
+  takes: filterSchema,
+  order: z.array(pluginRefSchema),
+});
+
+const efforts = ['low', 'medium', 'high', 'xhigh', 'max'] as const satisfies readonly Effort[];
+
+const recipeSchema = z.strictObject({
+  agent: nameSchema,
+  model: nameSchema,
+  effort: z.enum(efforts),
+  prompt: nameSchema.refine(isCheckoutPath, {
+    message: 'a prompt path runs from the checkout root, with no empty, "." or ".." folder',
+  }),
+  source: brandSchemas.sourceName,
+  skills: z.array(nameSchema),
+});
+
+const skillsPinSchema = z.strictObject({
+  source: brandSchemas.repoName,
+  ref: brandSchemas.commitSha,
+});
+
+const conceptEntrySchema = z.templateLiteral([nameSchema, '@', z.int().positive()]);
+
+const propagationLineSchema = z.strictObject({
+  value: nameSchema,
+  over: brandSchemas.relationTypeName,
+  toward: z.enum(['source', 'target']),
+});
+
+const minutesSchema = z.int().positive();
+
+export const rulesFileSchema = z
+  .strictObject({
+    version: z.literal(1),
+    concepts: z.array(conceptEntrySchema),
+    pipelines: z.record(brandSchemas.pipelineName, z.array(stepSchema).min(1)),
+    kinds: z.record(brandSchemas.itemKindName, kindSchema),
+    skills: skillsPinSchema.optional(),
+    relationTypes: z.array(brandSchemas.relationTypeName),
+    recipes: z.record(brandSchemas.recipeName, recipeSchema),
+    limits: z.array(limitSchema),
+    pools: z.array(poolSchema),
+    lead: z.array(pluginRefSchema).default([]),
+    propagation: z.array(propagationLineSchema).default([]),
+    sleep: z.strictObject({
+      afterIdleMinutes: minutesSchema,
+      afterQuietMinutes: minutesSchema,
+      afterUnattendedMinutes: minutesSchema,
+    }),
+  })
+  .superRefine((file, ctx) => {
+    for (const issue of [
+      ...collectRepeats(
+        file.concepts.map((entry) => parseConceptEntry(entry).name),
+        ['concepts'],
+        [],
+        (name) => `the concept ${name} is pinned twice`,
+      ),
+      ...collectRepeats(
+        file.pools.map((pool) => pool.name),
+        ['pools'],
+        ['name'],
+        (name) => `the pool name ${name} is used twice`,
+      ),
+      ...collectRepeats(
+        file.limits.map((limit) => limit.name),
+        ['limits'],
+        ['name'],
+        (name) => `the limit name ${name} is used twice`,
+      ),
+      ...collectRepeats(
+        file.relationTypes,
+        ['relationTypes'],
+        [],
+        (name) => `the relation type ${name} is listed twice`,
+      ),
+      ...Object.entries(file.pipelines).flatMap(([pipeline, steps]) =>
+        collectRepeats(
+          steps.map((step) => step.phase),
+          ['pipelines', pipeline],
+          ['phase'],
+          (phase) => `the pipeline ${pipeline} names the phase ${phase} twice`,
+        ),
+      ),
+      ...Object.entries(file.kinds).flatMap(([kind, rules]) =>
+        Object.hasOwn(file.pipelines, rules.pipeline)
+          ? []
+          : [
+              {
+                path: ['kinds', kind, 'pipeline'],
+                message: `the file has no pipeline ${rules.pipeline}`,
+              },
+            ],
+      ),
+    ]) {
+      ctx.addIssue({ code: 'custom', ...issue });
+    }
+  });
+
+export type ParsedRulesFile = z.output<typeof rulesFileSchema>;
+
+export type ParsedStep = z.output<typeof stepSchema>;
+
+function isCheckoutPath(path: string): boolean {
+  return path.split('/').every((segment) => segment !== '' && segment !== '.' && segment !== '..');
+}
+
+interface FileIssue {
+  readonly path: PropertyKey[];
+  readonly message: string;
+}
+
+function collectRepeats(
+  names: readonly string[],
+  listPath: readonly PropertyKey[],
+  itemPath: readonly PropertyKey[],
+  formatMessage: (name: string) => string,
+): FileIssue[] {
+  return names.flatMap((name, index) =>
+    names.indexOf(name) === index
+      ? []
+      : [{ path: [...listPath, index, ...itemPath], message: formatMessage(name) }],
+  );
+}

package/src/registry/build-registry.ts

@@ -0,0 +1,67 @@
+import type { ConceptPin, LoadRejection, Registry } from '@boxxy/model';
+import { buildRejection } from '../loading/build-rejection.ts';
+import type { PinnedConcept } from '../types.ts';
+
+export function buildRegistry(
+  pinned: readonly PinnedConcept[],
+  pins: readonly ConceptPin[],
+): { readonly value: Registry; readonly rejections: readonly LoadRejection[] } {
+  const signal = collectByName(pinned, (concept) => concept.signals ?? []);
+  const gate = collectByName(pinned, (concept) => concept.gates ?? []);
+  const waiver = collectByName(pinned, (concept) => concept.waivers ?? []);
+  const filterField = collectByName(pinned, (concept) => concept.filterFields ?? []);
+
+  const lever = collectByName(pinned, (concept) =>
+    (concept.levers ?? []).map((kind) => ({ name: kind, kind })),
+  );
+
+  return {
+    value: {
+      signal: signal.byName,
+      gate: gate.byName,
+      admission: new Map(),
+      waiver: waiver.byName,
+      'filter-field': filterField.byName,
+      lever: lever.byName,
+      view: new Map(),
+      pins,
+    },
+    rejections: [
+      ...signal.rejections,
+      ...gate.rejections,
+      ...waiver.rejections,
+      ...filterField.rejections,
+      ...lever.rejections,
+    ],
+  };
+}
+
+function collectByName<T extends { readonly name: string }>(
+  pinned: readonly PinnedConcept[],
+  pluginsOf: (concept: PinnedConcept['concept']) => readonly T[],
+): { readonly byName: ReadonlyMap<string, T>; readonly rejections: readonly LoadRejection[] } {
+  const byName = new Map<string, T>();
+  const owners = new Map<string, string>();
+
+  const rejections: LoadRejection[] = [];
+
+  for (const entry of pinned) {
+    for (const plugin of pluginsOf(entry.concept)) {
+      const owner = owners.get(plugin.name);
+
+      if (owner === undefined) {
+        byName.set(plugin.name, plugin);
+        owners.set(plugin.name, entry.concept.name);
+      } else {
+        rejections.push(
+          buildRejection(['concepts', entry.entryIndex], {
+            kind: 'invalid',
+            message: `the concepts ${owner} and ${entry.concept.name} both register ${plugin.name}`,
+          }),
+        );
+      }
+    }
+  }
+
+  return { byName, rejections };
+}

package/src/registry/resolve-plugin.ts

@@ -0,0 +1,51 @@
+import type { JsonValue } from '@boxxy/content-hash';
+import type { ParamKindName, Registered, Resolved } from '@boxxy/model';
+import { formatKeyPath } from '@boxxy/model';
+import type { z } from 'zod';
+import { buildRejection } from '../loading/build-rejection.ts';
+import type { Checked } from '../types.ts';
+
+export function resolvePlugin<K extends ParamKindName>(
+  registered: Registered<K>,
+  params: JsonValue,
+  key: string,
+  path: readonly PropertyKey[],
+): Checked<Resolved<K>> {
+  return registered.open((plugin): Checked<Resolved<K>> => {
+    const checked = plugin.params.safeParse(params);
+
+    if (!checked.success) {
+      return {
+        value: null,
+        rejections: [
+          buildRejection(path, {
+            kind: 'bad-plugin-params',
+            pluginKind: registered.kind,
+            name: registered.name,
+            message: formatIssues(checked.error.issues),
+          }),
+        ],
+      };
+    }
+
+    const parsedParams = checked.data;
+
+    return {
+      value: {
+        kind: registered.kind,
+        name: registered.name,
+        key,
+        open: (use) => use(plugin, parsedParams),
+      },
+      rejections: [],
+    };
+  });
+}
+
+function formatIssues(issues: readonly z.core.$ZodIssue[]): string {
+  return issues
+    .map((issue) =>
+      issue.path.length > 0 ? `${formatKeyPath(issue.path)}: ${issue.message}` : issue.message,
+    )
+    .join('; ');
+}

package/src/registry/resolve-signal-ref.ts

@@ -0,0 +1,43 @@
+import type { JsonValue } from '@boxxy/content-hash';
+import type { Registry, SignalRef } from '@boxxy/model';
+import { signalKey } from '@boxxy/model';
+import invariant from 'tiny-invariant';
+import { buildRejection } from '../loading/build-rejection.ts';
+import type { Checked, ResolvedSignal } from '../types.ts';
+import { resolvePlugin } from './resolve-plugin.ts';
+
+export function resolveSignalRef(
+  ref: SignalRef,
+  path: readonly PropertyKey[],
+  registry: Registry,
+): Checked<ResolvedSignal> {
+  const parts = toPluginRefParts(ref);
+  const registered = registry.signal.get(parts.name);
+
+  if (registered === undefined) {
+    return {
+      value: null,
+      rejections: [buildRejection(path, { kind: 'unknown-signal', signal: parts.name })],
+    };
+  }
+
+  const key = signalKey(parts.name, parts.params);
+  const checked = resolvePlugin(registered, parts.params, key, path);
+
+  return {
+    value: checked.value === null ? null : { key, resolved: checked.value },
+    rejections: checked.rejections,
+  };
+}
+
+function toPluginRefParts(ref: SignalRef): { readonly name: string; readonly params: JsonValue } {
+  if (typeof ref === 'string') {
+    return { name: ref, params: {} };
+  }
+
+  const [entry] = Object.entries(ref);
+
+  invariant(entry, 'the rules file schema gives a plug-in reference with parameters one key');
+
+  return { name: entry[0], params: entry[1] };
+}

package/src/test-utils/build-example-load-input.ts

@@ -0,0 +1,90 @@
+import { contentHash } from '@boxxy/content-hash';
+import type { Concept, ConceptName, ConceptPin } from '@boxxy/model';
+import { defineGate, defineSignal } from '@boxxy/model';
+import { z } from 'zod';
+import buildPrompt from '../../example/prompts/build-v1.md' with { type: 'text' };
+import designAttendedPrompt from '../../example/prompts/design-attended-v1.md' with { type: 'text' };
+import designPrompt from '../../example/prompts/design-v1.md' with { type: 'text' };
+import reviewPrompt from '../../example/prompts/review-v1.md' with { type: 'text' };
+import triagePrompt from '../../example/prompts/triage-v1.md' with { type: 'text' };
+import exampleRules from '../../example/rules.yaml' with { type: 'text' };
+
+interface ExampleLoadInput {
+  readonly checkout: {
+    readonly commit: string;
+    readonly files: ReadonlyMap<string, Uint8Array>;
+  };
+  readonly concepts: readonly Concept[];
+  readonly pins: ReadonlyMap<ConceptName, ConceptPin>;
+}
+
+// The example rules file with its prompts, and stand-ins for the three concepts it pins. The
+// caller adds the phase kinds.
+export function buildExampleLoadInput(): ExampleLoadInput {
+  const encoder = new TextEncoder();
+
+  const prompts = [
+    ['triage-v1', triagePrompt],
+    ['design-v1', designPrompt],
+    ['design-attended-v1', designAttendedPrompt],
+    ['build-v1', buildPrompt],
+    ['review-v1', reviewPrompt],
+  ] as const;
+
+  return {
+    checkout: {
+      commit: '3f2a1c0',
+      files: new Map([
+        ['rules.yaml', encoder.encode(z.string().parse(exampleRules))],
+        ...prompts.map(([name, text]): [string, Uint8Array] => [
+          `prompts/${name}.md`,
+          encoder.encode(z.string().parse(text)),
+        ]),
+      ]),
+    },
+    concepts: buildStandInConcepts(),
+    pins: new Map<string, ConceptPin>([
+      ['pool', { ref: 'pool@2', sourceHash: contentHash('pool source') }],
+      ['defer', { ref: 'defer@1', sourceHash: contentHash('defer source') }],
+      ['expedite', { ref: 'expedite@1', sourceHash: contentHash('expedite source') }],
+    ]),
+  };
+}
+
+function buildStandInConcepts(): Concept[] {
+  return [
+    {
+      name: 'pool',
+      version: 2,
+      signals: [defineSignal({ name: 'oldest', params: z.object({}), value: () => null })],
+      filterFields: [
+        { name: 'phase', value: () => null },
+        { name: 'kind', value: () => null },
+        { name: 'repo', value: () => null },
+        { name: 'designMode', value: () => null },
+      ],
+    },
+    {
+      name: 'defer',
+      version: 1,
+      gates: [
+        defineGate({ name: 'defer', liftable: true, params: z.object({}), hold: () => null }),
+      ],
+      waivers: [{ name: 'expedite-lifts-defer', lifts: 'defer', lift: () => null }],
+      levers: ['plan.defer', 'plan.undefer'],
+    },
+    {
+      name: 'expedite',
+      version: 1,
+      signals: [
+        defineSignal({
+          name: 'expedite',
+          params: z.object({}),
+          value: () => null,
+          combine: (left, right) => Math.min(left, right),
+        }),
+      ],
+      levers: ['plan.expedite', 'plan.unexpedite'],
+    },
+  ];
+}

package/src/test-utils/load-mock-rules.ts

@@ -0,0 +1,84 @@
+import type { JsonValue, LoadedRules } from '@boxxy/model';
+import { buildMockPhaseKind } from '@boxxy/model/test-utils/build-mock-phase-kind';
+import invariant from 'tiny-invariant';
+import { loadRules } from '../loading/load-rules.ts';
+
+interface MockRulesInput {
+  // the steps of the `standard` pipeline, as the rules file writes them
+  readonly steps: readonly JsonValue[];
+
+  // the item kinds and the pipeline name each uses; one `core.issue` kind on `standard` when left out
+  readonly kinds?: Readonly<Record<string, string>>;
+}
+
+const phaseOutcomes: Readonly<Record<string, readonly string[]>> = {
+  triage: ['accepted', 'duplicate', 'declined'],
+  build: ['built', 'blocked', 'abandoned'],
+  review: ['passed', 'changes-requested'],
+};
+
+// A rules file with the three phases triage, build and review, loaded through the real loader
+export function loadMockRules(input: MockRulesInput): LoadedRules {
+  const recipes = Object.fromEntries(
+    Object.keys(phaseOutcomes).map((phase) => [phase, `${phase}-v1`]),
+  );
+
+  const file = {
+    version: 1,
+    concepts: [],
+    pipelines: { standard: input.steps },
+    kinds: Object.fromEntries(
+      Object.entries(input.kinds ?? { 'core.issue': 'standard' }).map(([kind, pipeline]) => [
+        kind,
+        { pipeline, recipes },
+      ]),
+    ),
+    relationTypes: ['blocks'],
+    limits: [{ name: 'workers', max: 7, counts: {} }],
+    pools: [],
+    recipes: Object.fromEntries(
+      Object.keys(phaseOutcomes).map((phase) => [
+        `${phase}-v1`,
+        {
+          agent: 'claude',
+          model: 'example-model',
+          effort: 'high',
+          prompt: `prompts/${phase}-v1.md`,
+          source: 'subscription',
+          skills: [],
+        },
+      ]),
+    ),
+    sleep: { afterIdleMinutes: 30, afterQuietMinutes: 60, afterUnattendedMinutes: 240 },
+  };
+
+  const encoder = new TextEncoder();
+
+  const phases = Object.entries(phaseOutcomes).map(([name, outcomes]) =>
+    buildMockPhaseKind({ name, outcomes }),
+  );
+
+  const promptFiles = Object.keys(phaseOutcomes).map((phase): [string, Uint8Array] => [
+    `prompts/${phase}-v1.md`,
+    encoder.encode(`Do the ${phase} of {{title}}.\n`),
+  ]);
+
+  const rulesFile: [string, Uint8Array] = ['rules.yaml', encoder.encode(JSON.stringify(file))];
+
+  const result = loadRules({
+    checkout: {
+      commit: '3f2a1c0',
+      files: new Map([rulesFile, ...promptFiles]),
+    },
+    concepts: [],
+    pins: new Map(),
+    phases,
+  });
+
+  invariant(
+    result.kind === 'loaded',
+    `the mock rules file failed to load: ${JSON.stringify(result)}`,
+  );
+
+  return result.rules;
+}

package/src/types.ts

@@ -0,0 +1,45 @@
+import type {
+  Concept,
+  ItemId,
+  ItemView,
+  LoadRejection,
+  Position,
+  Resolved,
+  RetryLever,
+  Settled,
+  SignalKey,
+} from '@boxxy/model';
+
+export interface Checked<T> {
+  readonly value: T | null;
+  readonly rejections: readonly LoadRejection[];
+}
+
+export interface ResolvedSignal {
+  readonly key: SignalKey;
+  readonly resolved: Resolved<'signal'>;
+}
+
+export interface PinnedConcept {
+  readonly concept: Concept;
+  readonly entryIndex: number;
+}
+
+export interface RulesDryRunLine {
+  readonly item: ItemId;
+
+  // under the rules the server runs
+  readonly now: Position;
+
+  // under the proposed rules
+  readonly then: Position;
+  readonly moved: boolean;
+}
+
+export interface DryRunItem {
+  readonly item: ItemView;
+
+  // the item's settled attempts, oldest first
+  readonly attempts: readonly Settled[];
+  readonly retries: readonly RetryLever[];
+}