@cosmicdrift/kumiko-framework 0.276.0 → 0.277.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.276.0",
+  "version": "0.277.0",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -198,7 +198,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-types": "0.276.0",
+    "@cosmicdrift/kumiko-types": "0.277.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.13.1",
@@ -214,7 +214,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.276.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.277.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.277.0",
+    "type": "improvement",
+    "title": "Changesets are the single source for upgrade changelog entries",
+    "detail": "The release step folds structured Changeset metadata into changes.json with the actual published version."
+  },
   {
     "version": "0.276.0",
     "type": "improvement",

package/src/engine/__tests__/changeset-changes.test.ts

@@ -0,0 +1,55 @@
+import { describe, expect, test } from "bun:test";
+import { parseChangesetChanges } from "../changeset-changes";
+
+describe("parseChangesetChanges", () => {
+  test("parses a structured change and derives detail from the body", () => {
+    const changes = parseChangesetChanges(
+      `---\n"@cosmicdrift/kumiko-framework": minor\n---\n\nAdds the new upgrade flow.\n\nMore detail.\n\n<!-- kumiko-changes\nfeature: framework\ntype: improvement\ntitle: Adds the new upgrade flow\n-->`,
+      ".changeset/upgrade-flow.md",
+    );
+
+    expect(changes).toEqual([
+      {
+        feature: "framework",
+        type: "improvement",
+        title: "Adds the new upgrade flow",
+        detail: "More detail.",
+        source: ".changeset/upgrade-flow.md",
+      },
+    ]);
+  });
+
+  test("parses multiple blocks with multiline migration", () => {
+    const changes = parseChangesetChanges(
+      `---\n"@cosmicdrift/kumiko-framework": minor\n---\n\n<!-- kumiko-changes\nfeature: framework\ntype: breaking\ntitle: Removes the old flow\nmigration: |\n  Replace the old call.\n  Then run the migration.\n-->\n\n<!-- kumiko-changes\nfeature: sessions\ntype: fix\ntitle: Fixes session cleanup\n-->`,
+      ".changeset/two-features.md",
+    );
+
+    expect(changes.map(({ feature, type, migration }) => ({ feature, type, migration }))).toEqual([
+      {
+        feature: "framework",
+        type: "breaking",
+        migration: "Replace the old call.\nThen run the migration.",
+      },
+      { feature: "sessions", type: "fix", migration: undefined },
+    ]);
+  });
+
+  test("rejects a breaking change without migration", () => {
+    expect(() =>
+      parseChangesetChanges(
+        `---\n"@cosmicdrift/kumiko-framework": minor\n---\n\n<!-- kumiko-changes\nfeature: framework\ntype: breaking\ntitle: Removes the old flow\n-->`,
+        ".changeset/breaking.md",
+      ),
+    ).toThrow('breaking change "Removes the old flow" missing migration field');
+  });
+
+  test("rejects an unknown type", () => {
+    expect(() =>
+      parseChangesetChanges(
+        `---\n"@cosmicdrift/kumiko-framework": patch\n---\n\n<!-- kumiko-changes\nfeature: framework\ntype: feature\ntitle: Invalid\n-->`,
+        ".changeset/invalid.md",
+      ),
+    ).toThrow("type must be breaking, improvement, or fix");
+  });
+});

package/src/engine/changeset-changes.ts

@@ -0,0 +1,104 @@
+import { type ChangelogType, validateChangelog } from "./feature-changelog";
+
+export type PendingChange = {
+  readonly feature: string;
+  readonly type: ChangelogType;
+  readonly title: string;
+  readonly detail?: string;
+  readonly migration?: string;
+  readonly codemod?: string;
+  readonly source: string;
+};
+
+const BLOCK_RE = /<!--\s*kumiko-changes\s*\n([\s\S]*?)\n\s*-->/g;
+const TYPE_VALUES = new Set<ChangelogType>(["breaking", "improvement", "fix"]);
+const KEY_RE = /^(feature|type|title|detail|migration|codemod):(?:\s(.*))?$/;
+
+function requiredField(fields: ReadonlyMap<string, string>, field: string, source: string): string {
+  const value = fields.get(field)?.trim();
+  if (!value) throw new Error(`${source}: kumiko-changes ${field} is required`);
+  return value;
+}
+
+function parseBlock(raw: string, source: string): ReadonlyMap<string, string> {
+  const fields = new Map<string, string>();
+  const lines = raw.split("\n");
+
+  for (let index = 0; index < lines.length; index++) {
+    const line = lines[index] ?? "";
+    if (line.trim() === "") continue;
+    const match = KEY_RE.exec(line.trim());
+    if (!match) throw new Error(`${source}: invalid kumiko-changes line "${line.trim()}"`);
+
+    const key = match[1];
+    if (!key) throw new Error(`${source}: invalid kumiko-changes field`);
+    if (fields.has(key)) throw new Error(`${source}: duplicate kumiko-changes field "${key}"`);
+    const value = match[2];
+    if (value === "|") {
+      const continuation: string[] = [];
+      while (index + 1 < lines.length && (lines[index + 1]?.startsWith("  ") ?? false)) {
+        index++;
+        const continuationLine = lines[index];
+        if (continuationLine) continuation.push(continuationLine.slice(2));
+      }
+      fields.set(key, continuation.join("\n").trim());
+      continue;
+    }
+    fields.set(key, value ?? "");
+  }
+
+  return fields;
+}
+
+function proseWithoutMetadata(markdown: string): string[] {
+  const withoutFrontmatter = markdown.replace(/^\s*---\n[\s\S]*?\n---\s*/, "");
+  return withoutFrontmatter
+    .replace(BLOCK_RE, "")
+    .split("\n")
+    .map((line) => line.trim())
+    .filter((line) => line !== "");
+}
+
+/** Parse structured upgrade metadata embedded in a Changeset body. */
+export function parseChangesetChanges(markdown: string, source: string): readonly PendingChange[] {
+  const changes: PendingChange[] = [];
+  const prose = proseWithoutMetadata(markdown);
+  BLOCK_RE.lastIndex = 0;
+  let match = BLOCK_RE.exec(markdown);
+  while (match !== null) {
+    const block = match[1];
+    if (!block) throw new Error(`${source}: empty kumiko-changes block`);
+    const fields = parseBlock(block, source);
+    const feature = requiredField(fields, "feature", source);
+    const rawType = requiredField(fields, "type", source);
+    if (!TYPE_VALUES.has(rawType as ChangelogType)) {
+      throw new Error(`${source}: kumiko-changes type must be breaking, improvement, or fix`);
+    }
+    const title = fields.get("title")?.trim() || prose[0];
+    if (!title) throw new Error(`${source}: kumiko-changes title is required`);
+
+    const detail =
+      fields.get("detail")?.trim() ||
+      prose
+        .slice(prose.length > 0 ? 1 : 0)
+        .join("\n")
+        .trim();
+    const migration = fields.get("migration")?.trim();
+    const codemod = fields.get("codemod")?.trim();
+    const change: PendingChange = {
+      feature,
+      type: rawType as ChangelogType,
+      title,
+      ...(detail ? { detail } : {}),
+      ...(migration ? { migration } : {}),
+      ...(codemod ? { codemod } : {}),
+      source,
+    };
+    const validation = validateChangelog({ version: "0.0.0", ...change });
+    if (validation.length > 0) throw new Error(`${source}: ${validation.join("; ")}`);
+    changes.push(change);
+    match = BLOCK_RE.exec(markdown);
+  }
+
+  return changes;
+}

package/src/engine/index.ts

@@ -24,6 +24,7 @@ export {
   SETTINGS_HUB_WORKSPACE,
 } from "./build-config-feature-schema";
 export { buildTarget } from "./build-target";
+export { type PendingChange, parseChangesetChanges } from "./changeset-changes";
 export {
   access,
   createSeed,

package/src/event-store/__tests__/unscoped-stream-primitives.guard.test.ts

@@ -13,6 +13,9 @@ const ALLOWED_FILES = new Set([
   "packages/bundled-features/src/tenant/seeding.ts",
   "packages/bundled-features/src/tier-engine/feature.ts",
   "packages/framework/src/event-store/__tests__/unscoped-stream-primitives.guard.test.ts",
+  // Fixtures of the AST guard that enforces this same restriction.
+  "packages/guards/src/__tests__/guard-fires.test.ts",
+  "packages/guards/src/__tests__/guard-restricted-symbols.test.ts",
 ]);
 
 const REPO_ROOT = `${import.meta.dir}/../../../../..`;