@suluk/stubgen 0.1.0

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@suluk/stubgen",
+  "version": "0.1.0",
+  "description": "Generate honestly-provisional backend STUBS from a NEEDS-CONTRACT gap (a tester pre-wrote a scenario the contract can't back). Emits the CONTRACT half generically (a @suluk/hono RouteContract literal with inferred Zod) and the HANDLER half through a HandlerTarget adapter seam (mirroring @suluk/deploy / the C034 runtime seam) — the first adapter is the Effect+run()+RouteError shape. Zero-dep, pure, source-text out. CANDIDATE tooling.",
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MahmoodKhalil57/suluk.git",
+    "directory": "tooling/ts/packages/stubgen"
+  },
+  "homepage": "https://github.com/MahmoodKhalil57/suluk#readme",
+  "bugs": "https://github.com/MahmoodKhalil57/suluk/issues",
+  "type": "module",
+  "main": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "devDependencies": {
+    "@types/bun": "latest"
+  },
+  "scripts": {
+    "test": "bun test",
+    "typecheck": "tsc --noEmit -p ."
+  }
+}

package/src/index.ts

@@ -0,0 +1,161 @@
+/**
+ * @suluk/stubgen — turn a NEEDS-CONTRACT gap (a tester pre-wrote a scenario the contract can't back yet) into
+ * honestly-provisional backend STUBS the maintainer then writes pragmatically.
+ *
+ * Two halves, per C040-P3:
+ *   • the CONTRACT half is GENERIC — a `@suluk/hono` RouteContract literal (method/path/name inferred from the intent;
+ *     request Zod inferred from the gap's Examples columns; responses a placeholder), every inference tagged
+ *     `// TODO: tighten` — the inferred Zod is LOSSY by construction and the maintainer owns the final schema (never
+ *     laundered as authoritative).
+ *   • the HANDLER half goes through a `HandlerTarget` ADAPTER SEAM (mirroring @suluk/deploy's DeployProvider / the C034
+ *     runtime seam), because the handler idiom is app-specific. The first adapter is `honoEffectTarget` (the toolfactory
+ *     Effect + run() + RouteError<name> shape); `honoTarget` is a framework-generic fallback.
+ *
+ * Zero-dependency + pure (source-text out): @suluk/core never imports this; this imports nothing.
+ */
+
+export interface StubField {
+  name: string;
+  /** the inferred Zod expression, e.g. `z.string()`. */
+  zod: string;
+  /** the inferred TS type, e.g. `string`. */
+  tsType: string;
+}
+
+/** The input: a gap the contract cannot back, optionally with the Examples columns that hint the request shape. */
+export interface StubGap {
+  /** the authored intent — the When step text, e.g. "I refund a charge". */
+  intent: string;
+  /** the Examples columns (request field names) + an optional sample cell for type inference. */
+  fields?: { name: string; sample?: string }[];
+  /** explicit overrides (else inferred from `intent`). */
+  name?: string;
+  method?: string;
+  path?: string;
+}
+
+/** The resolved, renderable stub. */
+export interface StubSpec {
+  name: string;
+  method: string;
+  path: string;
+  intent: string;
+  fields: StubField[];
+}
+
+const STOP = new Set(["a", "an", "the", "my", "our", "to", "of", "for", "with", "from"]);
+const VERB_METHOD: Record<string, string> = {
+  create: "post", add: "post", post: "post", submit: "post", new: "post", start: "post", send: "post", refund: "post",
+  get: "get", view: "get", list: "get", show: "get", fetch: "get", read: "get", see: "get",
+  update: "put", edit: "put", change: "put", set: "put",
+  delete: "delete", remove: "delete", cancel: "delete",
+};
+
+const words = (intent: string) => intent.replace(/^I\s+/i, "").trim().split(/\s+/).filter(Boolean);
+
+function inferName(intent: string): string {
+  const w = words(intent).filter((x) => !STOP.has(x.toLowerCase())).map((x) => x.replace(/[^A-Za-z0-9]/g, ""));
+  const parts = w.filter(Boolean);
+  if (!parts.length) return "operation";
+  return parts.map((p, i) => (i === 0 ? p.toLowerCase() : p[0].toUpperCase() + p.slice(1).toLowerCase())).join("");
+}
+
+const inferMethod = (intent: string): string => VERB_METHOD[words(intent)[0]?.toLowerCase() ?? ""] ?? "post";
+
+const kebab = (name: string) => name.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
+
+/** Infer a Zod expression + TS type from a sample cell (string default — honestly-provisional). */
+function inferField(name: string, sample?: string): StubField {
+  const s = sample?.trim();
+  if (s) {
+    if (s !== "" && Number.isFinite(Number(s))) return { name, zod: "z.number()", tsType: "number" };
+    if (s === "true" || s === "false") return { name, zod: "z.boolean()", tsType: "boolean" };
+  }
+  return { name, zod: "z.string()", tsType: "string" };
+}
+
+/** Resolve a gap to a renderable spec (inferring name/method/path/fields where not given). */
+export function stubSpec(gap: StubGap): StubSpec {
+  const name = gap.name ?? inferName(gap.intent);
+  return {
+    name,
+    method: (gap.method ?? inferMethod(gap.intent)).toLowerCase(),
+    path: gap.path ?? `/${kebab(name)}`,
+    intent: gap.intent,
+    fields: (gap.fields ?? []).map((f) => inferField(f.name, f.sample)),
+  };
+}
+
+const jsKey = (k: string) => (/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(k) ? k : JSON.stringify(k));
+
+/** Render the CONTRACT half — a `@suluk/hono` RouteContract literal to paste into `contractDoc([...])`. */
+export function renderContract(spec: StubSpec): string {
+  const lines = [
+    `// STUB contract (generated from a NEEDS-CONTRACT gap: ${JSON.stringify(spec.intent)}). Tighten Zod + responses, then implement the handler.`,
+    `{`,
+    `  method: ${JSON.stringify(spec.method)},`,
+    `  path: ${JSON.stringify(spec.path)},`,
+    `  name: ${JSON.stringify(spec.name)},`,
+    `  summary: ${JSON.stringify(`TODO: describe ${spec.name}.`)},`,
+  ];
+  if (spec.fields.length) {
+    lines.push(`  request: { json: z.object({ ${spec.fields.map((f) => `${jsKey(f.name)}: ${f.zod} /* TODO: tighten */`).join(", ")} }) },`);
+  }
+  lines.push(`  responses: [{ status: 200, schema: z.object({}) /* TODO: response shape */ }],`, `},`);
+  return lines.join("\n");
+}
+
+/** The handler-emit adapter seam — a target renders the HANDLER half in its app's idiom. */
+export interface HandlerTarget {
+  name: string;
+  emitHandler(spec: StubSpec): string;
+}
+
+/** The toolfactory idiom: an Effect program + the run() boundary + a contract-derived RouteError. The first adapter. */
+export const honoEffectTarget: HandlerTarget = {
+  name: "hono-effect",
+  emitHandler(spec) {
+    return [
+      `// STUB handler for ${spec.name} — implement the Effect program; it is wired to the route below.`,
+      `const ${spec.name}Program = (c: Context<AppCtx>): Effect.Effect<Response, RouteError<${JSON.stringify(spec.name)}>, AppServices> =>`,
+      `  Effect.gen(function* () {`,
+      `    // TODO: implement ${spec.name} (read input, do the work, return the declared 200 shape)`,
+      `    return c.json({});`,
+      `  });`,
+      ``,
+      `app.${spec.method}(${JSON.stringify(spec.path)}, (c) => run(${spec.name}Program(c), c.env));`,
+    ].join("\n");
+  },
+};
+
+/** A framework-generic Hono fallback target. */
+export const honoTarget: HandlerTarget = {
+  name: "hono",
+  emitHandler(spec) {
+    return [
+      `// STUB handler for ${spec.name}.`,
+      `app.${spec.method}(${JSON.stringify(spec.path)}, async (c) => {`,
+      `  // TODO: implement ${spec.name}`,
+      `  return c.json({});`,
+      `});`,
+    ].join("\n");
+  },
+};
+
+export interface GeneratedStub {
+  name: string;
+  spec: StubSpec;
+  contract: string;
+  handler: string;
+}
+
+/** Generate the contract + handler stub for one gap, lowered through a handler target. */
+export function generateStub(gap: StubGap, target: HandlerTarget = honoEffectTarget): GeneratedStub {
+  const spec = stubSpec(gap);
+  return { name: spec.name, spec, contract: renderContract(spec), handler: target.emitHandler(spec) };
+}
+
+/** Generate stubs for many gaps. */
+export function generateStubs(gaps: StubGap[], target: HandlerTarget = honoEffectTarget): GeneratedStub[] {
+  return gaps.map((g) => generateStub(g, target));
+}

package/test/stubgen.test.ts

@@ -0,0 +1,72 @@
+import { test, expect, describe } from "bun:test";
+import { stubSpec, renderContract, generateStub, honoEffectTarget, honoTarget, type StubGap } from "../src/index";
+
+/**
+ * C040-P3 — @suluk/stubgen turns a NEEDS-CONTRACT gap into a generic RouteContract stub + a handler via an adapter seam.
+ * The inferred Zod is honestly-provisional (`// TODO: tighten`); the maintainer owns the final schema.
+ */
+
+describe("stubSpec — inference from intent + Examples columns", () => {
+  const gap: StubGap = { intent: "I refund a charge", fields: [{ name: "chargeId", sample: "ch_123" }, { name: "amountCents", sample: "500" }, { name: "full", sample: "true" }] };
+  const spec = stubSpec(gap);
+
+  test("name drops the leading I + stop-words and camelCases", () => {
+    expect(spec.name).toBe("refundCharge");
+  });
+  test("method is inferred from the verb; path is the kebab of the name", () => {
+    expect(spec.method).toBe("post");
+    expect(spec.path).toBe("/refund-charge");
+  });
+  test("field Zod is inferred from the sample cell (number/boolean/string)", () => {
+    const byName = Object.fromEntries(spec.fields.map((f) => [f.name, f.zod]));
+    expect(byName.chargeId).toBe("z.string()");
+    expect(byName.amountCents).toBe("z.number()");
+    expect(byName.full).toBe("z.boolean()");
+  });
+
+  test("a get-verb intent infers method get", () => {
+    expect(stubSpec({ intent: "I view the receipt" }).method).toBe("get");
+    expect(stubSpec({ intent: "I delete a key" }).method).toBe("delete");
+  });
+
+  test("explicit overrides win over inference", () => {
+    const s = stubSpec({ intent: "I do a thing", name: "customName", method: "PUT", path: "/x/y" });
+    expect(s).toMatchObject({ name: "customName", method: "put", path: "/x/y" });
+  });
+});
+
+describe("renderContract — a paste-ready @suluk/hono RouteContract literal", () => {
+  const contract = renderContract(stubSpec({ intent: "I refund a charge", fields: [{ name: "chargeId", sample: "ch_1" }] }));
+  test("carries method/path/name + the inferred request Zod + a TODO", () => {
+    expect(contract).toContain('method: "post"');
+    expect(contract).toContain('name: "refundCharge"');
+    expect(contract).toContain("request: { json: z.object({ chargeId: z.string() /* TODO: tighten */ }) }");
+    expect(contract).toContain("/* TODO: response shape */");
+  });
+  test("a fieldless gap emits no request block", () => {
+    expect(renderContract(stubSpec({ intent: "I ping" }))).not.toContain("request:");
+  });
+});
+
+describe("HandlerTarget seam", () => {
+  const spec = stubSpec({ intent: "I refund a charge" });
+  test("honoEffectTarget emits the Effect + run() + RouteError idiom, wired to the route", () => {
+    const h = honoEffectTarget.emitHandler(spec);
+    expect(h).toContain("const refundChargeProgram = (c: Context<AppCtx>): Effect.Effect<Response, RouteError<\"refundCharge\">, AppServices>");
+    expect(h).toContain('app.post("/refund-charge", (c) => run(refundChargeProgram(c), c.env));');
+  });
+  test("honoTarget emits a framework-generic handler", () => {
+    const h = honoTarget.emitHandler(spec);
+    expect(h).toContain('app.post("/refund-charge", async (c) => {');
+    expect(h).not.toContain("Effect");
+  });
+});
+
+describe("generateStub — contract + handler, default target", () => {
+  const g = generateStub({ intent: "I create a subscription", fields: [{ name: "plan", sample: "pro" }] });
+  test("returns the inferred name + both halves", () => {
+    expect(g.name).toBe("createSubscription");
+    expect(g.contract).toContain('name: "createSubscription"');
+    expect(g.handler).toContain("createSubscriptionProgram");
+  });
+});

package/test/wall.test.ts

@@ -0,0 +1,19 @@
+import { test, expect } from "bun:test";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+/**
+ * @suluk/stubgen is a zero-dependency leaf — it emits SOURCE TEXT, so it needs no runtime deps, and @suluk/core never
+ * imports it (the C027 module-boundary rule: the deterministic core stays free of the higher tooling layers). This pins
+ * both: src/index.ts imports nothing, and @suluk/core's barrel does not import @suluk/stubgen.
+ */
+test("src/index.ts is self-contained: no imports at all (zero-dep leaf)", () => {
+  const body = readFileSync(join(import.meta.dir, "..", "src", "index.ts"), "utf8");
+  expect(/^\s*import\s/m.test(body)).toBe(false);
+  expect(/from\s+["']/.test(body)).toBe(false);
+});
+
+test("@suluk/core does not import @suluk/stubgen (the matcher stays free of the stub layer)", () => {
+  const coreIndex = readFileSync(join(import.meta.dir, "..", "..", "core", "src", "index.ts"), "utf8");
+  expect(coreIndex.includes("@suluk/stubgen")).toBe(false);
+});

package/tsconfig.json

@@ -0,0 +1 @@
+{ "extends": "../../tsconfig.base.json", "compilerOptions": { "types": ["bun"] }, "include": ["src", "test"] }