argsbarg 7.1.1 → 7.1.3

package/src/cli-tool/create.test.ts

@@ -10,6 +10,7 @@ import {
   applyCreate,
   type CreateOptions,
   classNameFromKey,
+  DEV_ONLY_MARKER,
   diffCreate,
   diffCreateDetails,
   renderCreateTree,
@@ -38,6 +39,19 @@ function baseOpts(overrides: Partial<CreateOptions> = {}): CreateOptions {
 
 /** Tests for argsbarg create. */
 describe("argsbarg create", () => {
+  test("in-repo example templates match their own create output", () => {
+    for (const example of ["full-example", "full-example-json", "mcp-plugin"]) {
+      const dir = join(import.meta.dir, "../../examples", example);
+      expect({ example, drift: diffCreate(dir, { check: true }) }).toEqual({ example, drift: [] });
+    }
+  });
+
+  test("drops argsbarg-dev-only lines outside the in-repo template", () => {
+    const content = `setup:\n    bun install\n    ln -sf a b ${DEV_ONLY_MARKER}: fix link\n    just schemagen\n`;
+    expect(substituteTemplateContent(content, baseOpts())).toBe("setup:\n    bun install\n    just schemagen\n");
+    expect(substituteTemplateContent(content, baseOpts({ devTemplate: true }))).toBe(content);
+  });
+
   test("substitutes {key} tokens", () => {
     const out = substituteTemplateContent(
       "key={key} class={className} env={envPrefix}_API_TOKEN tap={tap} org={tapOrg}",

package/src/cli-tool/create.ts

@@ -263,6 +263,12 @@ function tokenMap(opts: CreateOptions): Record<string, string> {
   };
 }
 
+/**
+ * Trailing comment marking a template line that only makes sense inside the argsbarg repo (e.g. the
+ * `.bin/argsbarg` symlink fix for `file:../..` installs). `create` drops these lines from new projects.
+ */
+export const DEV_ONLY_MARKER = "# argsbarg-dev-only";
+
 /** Substitute \`{key}\`-style placeholders; also replace template identity literals. */
 export function substituteTemplateContent(content: string, opts: CreateOptions): string {
   const tmpl = templateIdentity(opts.templateId);
@@ -303,6 +309,9 @@ export function substituteTemplateContent(content: string, opts: CreateOptions):
 
   if (!opts.devTemplate) {
     out = out
+      .split("\n")
+      .filter((line) => !line.includes(DEV_ONLY_MARKER))
+      .join("\n")
       .replace(/"argsbarg":\s*"workspace:\*"/, `"argsbarg": "^${argsbargVersion}"`)
       .replace(/"argsbarg":\s*"file:\.\.\/\.\."/, `"argsbarg": "^${argsbargVersion}"`);
   }

package/src/cli-tool/main.ts

@@ -1,5 +1,5 @@
 #!/usr/bin/env bun
-/** Argsbarg package CLI (`bunx argsbarg`) — bootstrap and tooling; library API is `import from "argsbarg"`. */
+/** Argsbarg package CLI (`bun x argsbarg`) — bootstrap and tooling; library API is `import from "argsbarg"`. */
 
 import { Cli } from "../index.ts";
 import { program } from "./program.ts";

package/src/cli-tool/schemagen/run.ts

@@ -5,6 +5,7 @@ Generate JSON Schema artifacts under __generated__/ and write index.ts re-export
 import { mkdirSync, writeFileSync } from "node:fs";
 import { dirname, join, relative } from "node:path";
 import { createGenerator } from "ts-json-schema-generator";
+import { resolveJsonPointer } from "../../core/json-pointer.ts";
 import { cleanStaleGenerated } from "./cleanup.ts";
 import { discoverSchemaRoots, type SchemaRoot } from "./discover-schema-roots.ts";
 import { GENERATED_DIR, schemaExportName, schemaJsonBasename, schemaJsonImportVar } from "./names.ts";
@@ -46,11 +47,49 @@ function generateJson(projectRoot: string, tsconfigPath: string, root: SchemaRoo
     jsDoc: "extended",
     additionalProperties: false,
   });
-  const schema = generator.createSchema(root.typeName) as Record<string, unknown>;
-  schema.additionalProperties = false;
+  const schema = hoistRootRef(generator.createSchema(root.typeName) as Record<string, unknown>, root.typeName);
+  // Only object roots: on a union root with no root `properties`, this would reject every property.
+  if (schema.type === "object") {
+    schema.additionalProperties = false;
+  }
   return schema;
 }
 
+/**
+ * Replaces a root `$ref` with the definition it names, following alias chains
+ * (`export type Input = Inner` emits `{ $ref: "#/definitions/Inner" }` even with `topRef: false`).
+ * Keeps `definitions` so nested and recursive references still resolve.
+ */
+function hoistRootRef(
+  /** Schema from ts-json-schema-generator. */
+  schema: Record<string, unknown>,
+  /** Root type name, for error messages. */
+  typeName: string,
+): Record<string, unknown> {
+  let target = schema;
+  const seen = new Set<string>();
+  while (typeof target.$ref === "string") {
+    const ref = target.$ref;
+    if (seen.has(ref)) {
+      throw new Error(`schemagen: ${typeName} root $ref cycle at ${ref}`);
+    }
+    seen.add(ref);
+    const next = resolveJsonPointer(schema, ref);
+    if (typeof next !== "object" || next === null || Array.isArray(next)) {
+      throw new Error(`schemagen: ${typeName} root $ref does not resolve: ${ref}`);
+    }
+    target = next as Record<string, unknown>;
+  }
+  if (target === schema) {
+    return schema;
+  }
+  return {
+    ...(schema.$schema === undefined ? {} : { $schema: schema.$schema }),
+    ...target,
+    ...(schema.definitions === undefined ? {} : { definitions: schema.definitions }),
+  };
+}
+
 function writeGeneratedIndex(generatedDir: string, roots: SchemaRoot[]): void {
   const sorted = [...roots].sort((left, right) => left.typeName.localeCompare(right.typeName));
   const lines = ["// Auto-generated by argsbarg schemagen — do not edit by hand.", ""];

package/src/cli-tool/schemagen/schemagen.test.ts

@@ -48,7 +48,12 @@ function writeSrcFile(root: string, relPath: string, body: string): void {
 describe("schemagen", () => {
   test("discovers @sg types in full-example-json", () => {
     const roots = discoverSchemaRoots(exampleRoot);
-    expect(roots.map((r) => r.typeName).sort()).toEqual(["RenderJsonInput", "StatusJsonOutput", "WorkspaceNameInput"]);
+    expect(roots.map((r) => r.typeName).sort()).toEqual([
+      "RenderJsonInput",
+      "ShapeAreaInput",
+      "StatusJsonOutput",
+      "WorkspaceNameInput",
+    ]);
   });
 
   test("maps type names to __generated__ filenames and export names", () => {
@@ -58,7 +63,7 @@ describe("schemagen", () => {
 
   test("runSchemagen writes __generated__ artifacts in full-example-json", () => {
     const counts = runSchemagen({ projectRoot: exampleRoot });
-    expect(counts).toEqual({ schemas: 3 });
+    expect(counts).toEqual({ schemas: 4 });
   });
 
   test("discovers @sg roots and writes named schema artifacts", () => {
@@ -230,4 +235,84 @@ export interface DupType {
 
     expect(() => discoverSchemaRoots(root)).toThrow("duplicate schema root type DupType");
   });
+
+  describe("root normalization", () => {
+    /** Writes one `@sg` type (plus helper types) and returns its generated schema. */
+    function generate(typeName: string, body: string): Record<string, unknown> {
+      const root = makeTempProject();
+      writeSrcFile(root, "src/commands/demo/types.ts", body);
+      runSchemagen({ projectRoot: root });
+      const path = join(root, "src/commands/demo/__generated__", schemaJsonBasename(typeName));
+      return JSON.parse(readFileSync(path, "utf8")) as Record<string, unknown>;
+    }
+
+    test("hoists an alias root $ref to an object root", () => {
+      const schema = generate(
+        "AliasInput",
+        `export interface Inner {
+  name: string;
+}
+/** @sg */
+export type AliasInput = Inner;
+`,
+      );
+      expect(schema.$ref).toBeUndefined();
+      expect(schema.type).toBe("object");
+      expect(schema.properties).toEqual({ name: { type: "string" } });
+      expect(schema.additionalProperties).toBe(false);
+    });
+
+    test("follows alias chains and percent-encoded generic refs", () => {
+      const chain = generate(
+        "ChainInput",
+        `export interface Inner {
+  name: string;
+}
+export type Mid = Inner;
+/** @sg */
+export type ChainInput = Mid;
+`,
+      );
+      expect(chain.type).toBe("object");
+      expect(chain.properties).toEqual({ name: { type: "string" } });
+
+      const generic = generate(
+        "GenericInput",
+        `export interface Box<T> {
+  value: T;
+}
+/** @sg */
+export type GenericInput = Box<string>;
+`,
+      );
+      expect(generic.type).toBe("object");
+      expect(generic.properties).toEqual({ value: { type: "string" } });
+    });
+
+    test("keeps definitions so recursive references still resolve", () => {
+      const schema = generate(
+        "TreeInput",
+        `export interface Tree {
+  name: string;
+  children?: Tree[];
+}
+/** @sg */
+export type TreeInput = Tree;
+`,
+      );
+      expect(schema.type).toBe("object");
+      expect((schema.definitions as Record<string, unknown>).Tree).toBeDefined();
+    });
+
+    test("leaves union roots without a root additionalProperties", () => {
+      const schema = generate(
+        "UnionInput",
+        `/** @sg */
+export type UnionInput = { kind: "a"; a: string } | { kind: "b"; b: number };
+`,
+      );
+      expect(Array.isArray(schema.anyOf)).toBe(true);
+      expect(schema.additionalProperties).toBeUndefined();
+    });
+  });
 });

package/src/config/validate.test.ts

@@ -51,6 +51,163 @@ describe("config/validate", () => {
     expect(result.valid).toBe(false);
   });
 
+  describe("discriminated unions", () => {
+    const stepSchema = {
+      $schema: "http://json-schema.org/draft-07/schema#",
+      type: "object",
+      properties: { steps: { type: "array", items: { $ref: "#/definitions/Step" } } },
+      required: ["steps"],
+      additionalProperties: false,
+      definitions: {
+        Step: {
+          anyOf: [
+            {
+              type: "object",
+              properties: { kind: { const: "alpha" }, title: { type: "string" } },
+              required: ["kind", "title"],
+              additionalProperties: false,
+            },
+            {
+              type: "object",
+              properties: { kind: { enum: ["beta", "bravo"] }, count: { type: "number" } },
+              required: ["kind"],
+              additionalProperties: false,
+            },
+            {
+              type: "object",
+              properties: { kind: { const: "gamma" }, flag: { type: "boolean" } },
+              required: ["kind"],
+              additionalProperties: false,
+            },
+          ],
+        },
+      },
+    };
+
+    test("valid mix of branches passes", () => {
+      const result = validateConfigDocument(
+        {
+          steps: [
+            { kind: "alpha", title: "x" },
+            { kind: "beta", count: 3 },
+          ],
+        },
+        stepSchema,
+      );
+      expect(result.valid).toBe(true);
+      expect(result.errors).toEqual([]);
+    });
+
+    test("unknown property in the matched branch reports only that branch", () => {
+      const result = validateConfigDocument({ steps: [{ kind: "alpha", titel: "x" }] }, stepSchema);
+      expect(result.errors).toEqual([
+        'steps.0: missing required property "title"',
+        'steps.0: unknown property "titel" (allowed: kind, title)',
+      ]);
+    });
+
+    test("unmapped discriminator value reports one synthetic error", () => {
+      const result = validateConfigDocument({ steps: [{ kind: "alfa" }] }, stepSchema);
+      expect(result.errors).toEqual(['steps.0.kind: unknown kind "alfa" (expected one of: alpha, beta, bravo, gamma)']);
+    });
+
+    test("missing discriminator reports one synthetic error", () => {
+      const result = validateConfigDocument({ steps: [{ title: "x" }] }, stepSchema);
+      expect(result.errors).toEqual(['steps.0: missing "kind" (expected one of: alpha, beta, bravo, gamma)']);
+    });
+
+    test("non-object instance reports one synthetic error", () => {
+      const result = validateConfigDocument({ steps: ["alpha"] }, stepSchema);
+      expect(result.errors).toEqual(['steps.0: expected an object with "kind" (one of: alpha, beta, bravo, gamma)']);
+    });
+
+    test("type mismatch in the matched branch reports only that field", () => {
+      const result = validateConfigDocument({ steps: [{ kind: "beta", count: "x" }] }, stepSchema);
+      expect(result.errors).toEqual(["steps.0.count: must be number (got string)"]);
+    });
+
+    test("a non-discriminated union still reports errors from every branch", () => {
+      const nonDiscriminatedSchema = {
+        type: "object",
+        properties: {
+          x: {
+            anyOf: [
+              { type: "object", properties: { a: { type: "string" } }, required: ["a"], additionalProperties: false },
+              { type: "object", properties: { b: { type: "number" } }, required: ["b"], additionalProperties: false },
+            ],
+          },
+        },
+        additionalProperties: false,
+      };
+      const result = validateConfigDocument({ x: {} }, nonDiscriminatedSchema);
+      expect(result.errors).toEqual(['x: missing required property "a"', 'x: missing required property "b"']);
+    });
+
+    test("collects one error per bad step, in order, without cross-contamination between array indices", () => {
+      const result = validateConfigDocument({ steps: [{ kind: "alfa" }, { kind: "beta", count: "x" }] }, stepSchema);
+      expect(result.errors).toEqual([
+        'steps.0.kind: unknown kind "alfa" (expected one of: alpha, beta, bravo, gamma)',
+        "steps.1.count: must be number (got string)",
+      ]);
+    });
+
+    test("resolves discriminators through $ref'd branches (ts-json-schema-generator output shape)", () => {
+      // ts-json-schema-generator (and similar tools) write each anyOf branch as a bare `{ $ref }` pointing
+      // into `definitions`, rather than inlining the branch schema. This is the shape gdocsmith's real
+      // `run` tool schema uses for its 27 step kinds, and it silently defeated discriminator detection
+      // (every branch looked property-less) until unionDiscriminator started resolving branch refs.
+      const refBranchSchema = {
+        $schema: "http://json-schema.org/draft-07/schema#",
+        type: "object",
+        properties: {
+          steps: { type: "array", items: { anyOf: [{ $ref: "#/definitions/A" }, { $ref: "#/definitions/B" }] } },
+        },
+        required: ["steps"],
+        additionalProperties: false,
+        definitions: {
+          A: {
+            type: "object",
+            properties: { kind: { const: "alpha" }, title: { type: "string" } },
+            required: ["kind", "title"],
+            additionalProperties: false,
+          },
+          B: {
+            type: "object",
+            properties: { kind: { const: "beta" }, count: { type: "number" } },
+            required: ["kind"],
+            additionalProperties: false,
+          },
+        },
+      };
+      const result = validateConfigDocument({ steps: [{ kind: "alfa" }] }, refBranchSchema);
+      expect(result.errors).toEqual(['steps.0.kind: unknown kind "alfa" (expected one of: alpha, beta)']);
+    });
+
+    test("caps at 10 errors plus a count of the remainder", () => {
+      const manySchema = {
+        type: "object",
+        properties: {
+          steps: {
+            type: "array",
+            items: {
+              type: "object",
+              properties: { kind: { enum: ["a"] } },
+              required: ["kind"],
+              additionalProperties: false,
+            },
+          },
+        },
+        additionalProperties: false,
+      };
+      const result = validateConfigDocument({ steps: Array.from({ length: 12 }, () => ({})) }, manySchema);
+      expect(result.errors).toHaveLength(11);
+      expect(result.errors.slice(0, 10)).toEqual(
+        Array.from({ length: 10 }, (_, i) => `steps.${i}: missing required property "kind"`),
+      );
+      expect(result.errors[10]).toBe("…and 2 more errors");
+    });
+  });
+
   test("parseConfigSetValue coerces number and boolean", () => {
     expect(parseConfigSetValue("5", { type: "integer" }, rootSchema, false)).toBe(5);
     expect(parseConfigSetValue("true", { type: "boolean" }, rootSchema, false)).toBe(true);