@kirrosh/zond 0.22.0 → 0.26.0

package/src/cli/commands/api/annotate/resources.ts

@@ -0,0 +1,91 @@
+/**
+ * ARV-187 / resources: parser + expected shape for orphan-clustering.
+ */
+
+import { z } from "zod";
+import type { ResourceYaml } from "../../discover.ts";
+
+const EndpointMapSchema = z.object({
+  list: z.string().optional(),
+  create: z.string().optional(),
+  read: z.string().optional(),
+  update: z.string().optional(),
+  delete: z.string().optional(),
+});
+
+const FkSchema = z.object({
+  var: z.string(),
+  param: z.string(),
+  in: z.enum(["path", "body"]),
+  ownerResource: z.string().nullable(),
+});
+
+const ExtensionSchema = z.object({
+  resource: z.string(),
+  basePath: z.string(),
+  itemPath: z.string(),
+  idParam: z.string(),
+  captureField: z.string().optional(),
+  hasFullCrud: z.boolean().optional(),
+  endpoints: EndpointMapSchema,
+  fkDependencies: z.array(FkSchema).default([]),
+  confidence: z.enum(["low", "medium", "high"]),
+  rationale: z.string().optional(),
+});
+
+const ResponseSchema = z.object({
+  extensions: z.array(ExtensionSchema).default([]),
+  rationale: z.string().optional(),
+});
+
+export const EXPECTED_OUTPUT_SHAPE = {
+  extensions: [{
+    resource: "slug",
+    basePath: "/v1/<collection>",
+    itemPath: "/v1/<collection>/{<id_param>}",
+    idParam: "string",
+    captureField: "string (optional, default 'id')",
+    hasFullCrud: "boolean (optional)",
+    endpoints: { list: "GET /...", create: "POST /...", read: "GET /...", update: "PATCH /...", delete: "DELETE /..." },
+    fkDependencies: "FkRef[] (usually [])",
+    confidence: "low | medium | high (only 'high' is accepted by zond)",
+    rationale: "string (optional)",
+  }],
+  rationale: "string (optional)",
+};
+
+export interface ResourcesParseResult {
+  extensions: ResourceYaml[];
+  audit: {
+    proposed: number;
+    droppedLowConfidence: number;
+    rationale?: string;
+  };
+}
+
+export function parseResourcesResponse(parsed: unknown): ResourcesParseResult {
+  const validated = ResponseSchema.safeParse(parsed);
+  if (!validated.success) {
+    throw new Error(`resources response failed schema: ${validated.error.message}`);
+  }
+  const v = validated.data;
+  let dropped = 0;
+  const extensions: ResourceYaml[] = [];
+  for (const ext of v.extensions) {
+    if (ext.confidence !== "high") { dropped++; continue; }
+    extensions.push({
+      resource: ext.resource,
+      basePath: ext.basePath,
+      itemPath: ext.itemPath,
+      idParam: ext.idParam,
+      captureField: ext.captureField,
+      hasFullCrud: ext.hasFullCrud,
+      endpoints: ext.endpoints,
+      fkDependencies: ext.fkDependencies,
+    });
+  }
+  return {
+    extensions,
+    audit: { proposed: v.extensions.length, droppedLowConfidence: dropped, rationale: v.rationale },
+  };
+}

package/src/cli/commands/api/annotate/seed-bodies.ts

@@ -0,0 +1,61 @@
+/**
+ * ARV-187 / seed-bodies: parser + schema-shape. zond does NOT
+ * formulate prompts — that's the agent's job. zond exposes the spec
+ * slice and the expected response shape; the agent decides how to ask
+ * its LLM.
+ */
+
+import { z } from "zod";
+import type { ResourcePatch } from "./overlay.ts";
+import type { ResourceSlice } from "./prompts.ts";
+
+const SeedBodySchema = z.object({
+  content_type: z.string().optional(),
+  body: z.record(z.string(), z.unknown()),
+});
+
+const ResponseSchema = z.object({
+  resource: z.string(),
+  seed_body: SeedBodySchema.nullable(),
+  rationale: z.string().optional(),
+  confidence: z.enum(["low", "medium", "high"]).optional(),
+});
+
+export const EXPECTED_OUTPUT_SHAPE = {
+  resource: "string (echo input)",
+  seed_body: {
+    content_type: "string (optional; defaults to spec's requestBodyContentType)",
+    body: "object (minimal-required field-set the create endpoint accepts)",
+  },
+  rationale: "string (optional, one sentence)",
+  confidence: "low | medium | high",
+  null_form: "if endpoint cannot be seeded statically, return { resource, seed_body: null, rationale }",
+};
+
+export function parseSeedBodyResponse(parsedYaml: unknown, slice: ResourceSlice): { patch: ResourcePatch; audit: Record<string, unknown> } {
+  const validated = ResponseSchema.safeParse(parsedYaml);
+  if (!validated.success) {
+    throw new Error(`seed_body response failed schema for ${slice.resource}: ${validated.error.message}`);
+  }
+  const v = validated.data;
+  if (v.seed_body == null) {
+    return {
+      patch: { resource: slice.resource },
+      audit: { resource: slice.resource, rationale: v.rationale, confidence: v.confidence, dropped: "agent judged endpoint not seedable" },
+    };
+  }
+  return {
+    patch: {
+      resource: slice.resource,
+      seed_body: {
+        content_type: v.seed_body.content_type ?? slice.endpoints.create?.requestBody?.contentType,
+        body: v.seed_body.body,
+      },
+    },
+    audit: { resource: slice.resource, rationale: v.rationale, confidence: v.confidence },
+  };
+}
+
+export function isApplicable(slice: ResourceSlice): boolean {
+  return Boolean(slice.endpoints.create);
+}