@boxxy/rules 0.1.0 → 0.1.3

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

@@ -1,4 +1,14 @@
-import type { Concept, LoadRejection, Resolved, SignalKey } from '@boxxy/model';
+import type {
+  Concept,
+  ItemId,
+  ItemView,
+  LoadRejection,
+  Position,
+  Resolved,
+  RetryLever,
+  Settled,
+  SignalKey,
+} from '@boxxy/model';
 
 export interface Checked<T> {
   readonly value: T | null;
@@ -14,3 +24,22 @@ 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[];
+}

package/dist/rules-file-schema.d.ts

@@ -1,49 +0,0 @@
-import type { PipelineStep } from '@boxxy/model';
-import { z } from 'zod';
-export declare const rulesFileSchema: z.ZodObject<{
-    version: z.ZodLiteral<1>;
-    concepts: z.ZodArray<z.ZodTemplateLiteral<`${string}@${number}`>>;
-    kinds: z.ZodRecord<z.core.$ZodBranded<z.ZodString, "ItemKindName", "out">, z.ZodPipe<z.ZodObject<{
-        pipeline: z.ZodArray<z.core.$ZodBranded<z.ZodString, "PhaseName", "out">>;
-        maxAttempts: z.ZodRecord<z.core.$ZodBranded<z.ZodString, "PhaseName", "out">, z.ZodInt>;
-        recipes: z.ZodRecord<z.core.$ZodBranded<z.ZodString, "PhaseName", "out">, z.core.$ZodBranded<z.ZodString, "RecipeName", "out">>;
-    }, z.core.$strict>, z.ZodTransform<{
-        pipeline: (string & z.$brand<"PhaseName">)[];
-        maxAttempts: Record<string & z.$brand<"PhaseName">, number>;
-        recipes: Record<string & z.$brand<"PhaseName">, string & z.$brand<"RecipeName">>;
-        steps: PipelineStep[];
-    }, {
-        pipeline: (string & z.$brand<"PhaseName">)[];
-        maxAttempts: Record<string & z.$brand<"PhaseName">, number>;
-        recipes: Record<string & z.$brand<"PhaseName">, string & z.$brand<"RecipeName">>;
-    }>>>;
-    pools: z.ZodArray<z.ZodObject<{
-        name: z.core.$ZodBranded<z.ZodString, "PoolName", "out">;
-        slots: z.ZodInt;
-        takes: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
-        order: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodJSONSchema>]>>;
-    }, z.core.$strict>>;
-    lead: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodJSONSchema>]>>;
-    propagation: z.ZodArray<z.ZodObject<{
-        value: z.ZodString;
-        over: z.core.$ZodBranded<z.ZodString, "LinkTypeName", "out">;
-        toward: z.ZodEnum<{
-            source: "source";
-            target: "target";
-        }>;
-    }, z.core.$strict>>;
-    recipes: z.ZodRecord<z.core.$ZodBranded<z.ZodString, "RecipeName", "out">, z.ZodObject<{
-        agent: z.ZodString;
-        model: z.ZodString;
-        effort: z.ZodEnum<{
-            high: "high";
-            low: "low";
-            max: "max";
-            medium: "medium";
-            xhigh: "xhigh";
-        }>;
-        prompt: z.ZodString;
-        source: z.core.$ZodBranded<z.ZodString, "SourceName", "out">;
-    }, z.core.$strict>>;
-}, z.core.$strict>;
-export type ParsedRulesFile = z.output<typeof rulesFileSchema>;

package/src/rules-file-schema.ts

@@ -1,112 +0,0 @@
-import type { Effort, PipelineStep, RulesFile } 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 kindSchema = z
-  .strictObject({
-    pipeline: z.array(brandSchemas.phaseName).min(1),
-    maxAttempts: z.record(brandSchemas.phaseName, z.int().positive()),
-    recipes: z.record(brandSchemas.phaseName, brandSchemas.recipeName),
-  })
-  .transform((kind, ctx) => {
-    const steps: PipelineStep[] = [];
-
-    for (const phase of kind.pipeline) {
-      const maxAttempts = Object.hasOwn(kind.maxAttempts, phase)
-        ? kind.maxAttempts[phase]
-        : undefined;
-
-      if (maxAttempts === undefined) {
-        ctx.issues.push({
-          code: 'custom',
-          input: kind.maxAttempts,
-          path: ['maxAttempts', phase],
-          message: `the pipeline phase ${phase} has no maxAttempts`,
-        });
-      } else {
-        steps.push({ phase, maxAttempts });
-      }
-    }
-
-    return { ...kind, steps };
-  });
-
-const takesValueSchema = z.union([nameSchema, z.array(nameSchema).min(1)]);
-
-const poolSchema = z.strictObject({
-  name: brandSchemas.poolName,
-  slots: z.int().positive(),
-  takes: z.record(nameSchema, takesValueSchema),
-  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,
-});
-
-const conceptEntrySchema = z.templateLiteral([nameSchema, '@', z.int().positive()]);
-
-const propagationLineSchema = z.strictObject({
-  value: nameSchema,
-  over: brandSchemas.linkTypeName,
-  toward: z.enum(['source', 'target']),
-});
-
-export const rulesFileSchema = z
-  .strictObject({
-    version: z.literal(1),
-    concepts: z.array(conceptEntrySchema),
-    kinds: z.record(brandSchemas.itemKindName, kindSchema),
-    pools: z.array(poolSchema),
-    lead: z.array(pluginRefSchema),
-    propagation: z.array(propagationLineSchema),
-    recipes: z.record(brandSchemas.recipeName, recipeSchema),
-  })
-  .superRefine((file, ctx) => {
-    const conceptNames = file.concepts.map((entry) => parseConceptEntry(entry).name);
-    const poolNames: string[] = file.pools.map((pool) => pool.name);
-
-    for (const [index, name] of conceptNames.entries()) {
-      if (conceptNames.indexOf(name) !== index) {
-        ctx.addIssue({
-          code: 'custom',
-          path: ['concepts', index],
-          message: `the concept ${name} is pinned twice`,
-        });
-      }
-    }
-
-    for (const [index, name] of poolNames.entries()) {
-      if (poolNames.indexOf(name) !== index) {
-        ctx.addIssue({
-          code: 'custom',
-          path: ['pools', index, 'name'],
-          message: `the pool name ${name} is used twice`,
-        });
-      }
-    }
-  }) satisfies z.ZodType<RulesFile>;
-
-export type ParsedRulesFile = z.output<typeof rulesFileSchema>;
-
-function isCheckoutPath(path: string): boolean {
-  return path.split('/').every((segment) => segment !== '' && segment !== '.' && segment !== '..');
-}