@akanjs/devkit 3.1.1-rc.9 → 3.1.2-rc.0

package/storeAccessScanner.ts

@@ -0,0 +1,71 @@
+import ts from "typescript";
+import { ComponentSizeScanner } from "./componentSizeScanner";
+import type { WritingActionIndex } from "./writingActionIndex";
+
+export interface StoreAccessCount {
+  component: string;
+  line: number;
+  accessCount: number;
+}
+
+//? A generated form setter only binds a field to its control: a long form is a size breach, not a busy component.
+export class StoreAccessScanner {
+  static readonly #formSetter = /^(?:(?:set|add|sub|addOrSub|upload)[A-Z]\w*On|writeOn)[A-Z]\w*$/;
+  readonly #index: WritingActionIndex;
+
+  constructor(index: WritingActionIndex) {
+    this.#index = index;
+  }
+
+  static stNamesOf(sourceFile: ts.SourceFile) {
+    return StoreAccessScanner.localNamesOf(sourceFile, "st");
+  }
+
+  static localNamesOf(sourceFile: ts.SourceFile, imported: string) {
+    const names = new Set<string>();
+    for (const statement of sourceFile.statements) {
+      if (!ts.isImportDeclaration(statement) || statement.importClause?.isTypeOnly) continue;
+      const bindings = statement.importClause?.namedBindings;
+      if (!bindings || !ts.isNamedImports(bindings)) continue;
+      for (const element of bindings.elements)
+        if (!element.isTypeOnly && (element.propertyName ?? element.name).text === imported)
+          names.add(element.name.text);
+    }
+    return names;
+  }
+
+  measure(sourceFile: ts.SourceFile): StoreAccessCount[] {
+    const stNames = StoreAccessScanner.stNamesOf(sourceFile);
+    if (!stNames.size) return [];
+    return ComponentSizeScanner.componentsAndHooksOf(sourceFile).map(({ name, node }) => {
+      let accessCount = 0;
+      const visit = (child: ts.Node) => {
+        if (
+          ts.isPropertyAccessExpression(child) &&
+          ts.isIdentifier(child.expression) &&
+          stNames.has(child.expression.text) &&
+          !this.#isFormSetter(child)
+        )
+          accessCount += 1;
+        ts.forEachChild(child, visit);
+      };
+      visit(node);
+      return {
+        component: name,
+        line: sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile)).line + 1,
+        accessCount,
+      };
+    });
+  }
+
+  #isFormSetter(access: ts.PropertyAccessExpression) {
+    const action = access.parent;
+    return (
+      access.name.text === "do" &&
+      ts.isPropertyAccessExpression(action) &&
+      action.expression === access &&
+      StoreAccessScanner.#formSetter.test(action.name.text) &&
+      !this.#index.isWritingAction(action.name.text)
+    );
+  }
+}

package/storeSource.ts

@@ -0,0 +1,160 @@
+import { modelNames } from "akanjs/common";
+import ts from "typescript";
+import type { SourceFileInfo } from "./qualityScanner";
+
+export interface StoreClass {
+  name: string;
+  refName: string | null;
+}
+
+export interface StoreMethod {
+  store: string;
+  name: string;
+  isStatic: boolean;
+  body: ts.Block;
+}
+
+export type StoreCallTarget =
+  | { kind: "fetch"; name: string }
+  | { kind: "action"; name: string; isOwn: boolean }
+  | { kind: "static"; store: string; name: string };
+
+export class StoreSource {
+  readonly file: string;
+  readonly stores: StoreClass[] = [];
+  readonly methods: StoreMethod[] = [];
+  readonly #fetchNames: Set<string>;
+  readonly #ownActionsByStore = new Map<string, Set<string>>();
+  readonly #rootAliasesByMethod = new Map<StoreMethod, Set<string>>();
+
+  //? The actions `store()` generates that send a mutation; `upload<Field>On<Model>` only stages a file the form saves.
+  static generatedWritesOf(refName: string) {
+    const names = modelNames(refName);
+    return [
+      names.createModel,
+      names.updateModel,
+      names.removeModel,
+      names.mergeModel,
+      names.createModelInForm,
+      names.updateModelInForm,
+      names.submitModel,
+    ];
+  }
+
+  constructor({ file, sourceFile }: Pick<SourceFileInfo, "file" | "sourceFile">) {
+    this.file = file;
+    this.#fetchNames = StoreSource.#fetchBindingsOf(sourceFile);
+    for (const statement of sourceFile.statements) {
+      if (!ts.isClassDeclaration(statement) || !statement.name) continue;
+      const refName = StoreSource.#refNameOf(statement);
+      if (refName === undefined) continue;
+      const store = statement.name.text;
+      this.stores.push({ name: store, refName });
+      const ownActions = new Set(refName ? StoreSource.generatedWritesOf(refName) : []);
+      for (const member of statement.members) {
+        if (!ts.isMethodDeclaration(member) || !member.body) continue;
+        const isStatic = !!ts.getModifiers(member)?.some(({ kind }) => kind === ts.SyntaxKind.StaticKeyword);
+        const name = member.name.getText(sourceFile);
+        if (!isStatic) ownActions.add(name);
+        const method = { store, name, isStatic, body: member.body };
+        this.methods.push(method);
+        this.#rootAliasesByMethod.set(method, StoreSource.#rootAliasesIn(member));
+      }
+      this.#ownActionsByStore.set(store, ownActions);
+    }
+  }
+
+  targetsIn(method: StoreMethod) {
+    const targets: StoreCallTarget[] = [];
+    const visit = (node: ts.Node) => {
+      const target = ts.isCallExpression(node) ? this.targetOf(method, node) : null;
+      if (target) targets.push(target);
+      ts.forEachChild(node, visit);
+    };
+    visit(method.body);
+    return targets;
+  }
+
+  targetOf(method: StoreMethod, call: ts.CallExpression): StoreCallTarget | null {
+    const callee = call.expression;
+    if (!ts.isPropertyAccessExpression(callee) && !ts.isElementAccessExpression(callee)) return null;
+    const name = ts.isPropertyAccessExpression(callee)
+      ? callee.name.text
+      : ts.isStringLiteralLike(callee.argumentExpression)
+        ? callee.argumentExpression.text
+        : null;
+    if (name === null) return null;
+    const receiver = StoreSource.#unwrap(callee.expression);
+    const isThis = receiver.kind === ts.SyntaxKind.ThisKeyword;
+    if (isThis && method.isStatic) return { kind: "static", store: method.store, name };
+    if (!isThis && !ts.isIdentifier(receiver)) return null;
+    if (ts.isIdentifier(receiver) && this.#fetchNames.has(receiver.text)) return { kind: "fetch", name };
+    if (isThis || (ts.isIdentifier(receiver) && this.#rootAliasesByMethod.get(method)?.has(receiver.text)))
+      return { kind: "action", name, isOwn: !!this.#ownActionsByStore.get(method.store)?.has(name) };
+    return ts.isIdentifier(receiver) ? { kind: "static", store: receiver.text, name } : null;
+  }
+
+  //? `this`, cast to `RootStore` or not, an alias of it, or a `RootStore` parameter reaches every store's action.
+  static #rootAliasesIn(method: ts.MethodDeclaration) {
+    const aliases = new Set<string>();
+    const visit = (node: ts.Node) => {
+      if (ts.isParameter(node) && ts.isIdentifier(node.name) && StoreSource.#isRootStoreType(node.type))
+        aliases.add(node.name.text);
+      if (
+        ts.isVariableDeclaration(node) &&
+        ts.isIdentifier(node.name) &&
+        node.initializer &&
+        StoreSource.#unwrap(node.initializer).kind === ts.SyntaxKind.ThisKeyword
+      )
+        aliases.add(node.name.text);
+      ts.forEachChild(node, visit);
+    };
+    visit(method);
+    return aliases;
+  }
+
+  static #isRootStoreType(type: ts.TypeNode | undefined) {
+    return (
+      !!type && ts.isTypeReferenceNode(type) && ts.isIdentifier(type.typeName) && type.typeName.text === "RootStore"
+    );
+  }
+
+  static #unwrap(expression: ts.Expression) {
+    let current = expression;
+    while (
+      ts.isParenthesizedExpression(current) ||
+      ts.isAsExpression(current) ||
+      ts.isTypeAssertionExpression(current) ||
+      ts.isSatisfiesExpression(current) ||
+      ts.isNonNullExpression(current)
+    )
+      current = current.expression;
+    return current;
+  }
+
+  static #refNameOf(statement: ts.ClassDeclaration) {
+    for (const clause of statement.heritageClauses ?? []) {
+      if (clause.token !== ts.SyntaxKind.ExtendsKeyword) continue;
+      for (const { expression } of clause.types) {
+        if (!ts.isCallExpression(expression) || !ts.isIdentifier(expression.expression)) continue;
+        if (expression.expression.text !== "store") continue;
+        const sig = expression.arguments[0];
+        return sig && ts.isPropertyAccessExpression(sig) ? sig.name.text : null;
+      }
+    }
+    return undefined;
+  }
+
+  static #fetchBindingsOf(sourceFile: ts.SourceFile) {
+    const names = new Set<string>();
+    for (const statement of sourceFile.statements) {
+      if (!ts.isImportDeclaration(statement) || statement.importClause?.isTypeOnly) continue;
+      const bindings = statement.importClause?.namedBindings;
+      if (!bindings || !ts.isNamedImports(bindings)) continue;
+      for (const element of bindings.elements)
+        if (!element.isTypeOnly && (element.propertyName ?? element.name).text === "fetch")
+          names.add(element.name.text);
+    }
+    return names;
+  }
+}

package/storeWriteScanner.test.ts

@@ -0,0 +1,292 @@
+import { describe, expect, test } from "bun:test";
+import ts from "typescript";
+import type { SourceFileInfo } from "./qualityScanner";
+import { SignalMutationIndex } from "./signalMutationIndex";
+import { StoreWriteScanner } from "./storeWriteScanner";
+import { WritingActionIndex } from "./writingActionIndex";
+
+const fileOf = (file: string, content: string): SourceFileInfo => ({
+  file,
+  absolutePath: `/repo/${file}`,
+  content,
+  sourceFile: ts.createSourceFile(file, content, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS),
+});
+
+const signal = fileOf(
+  "apps/demo/lib/court/court.signal.ts",
+  `
+export class CourtSlice extends slice(srv.court, { guards: { root: Admin, get: Public, cru: User } }, () => ({})) {}
+export class CourtEndpoint extends endpoint(srv.court, ({ query, mutation }) => ({
+  assignCourtPc: mutation(cnst.Court, { guards: [User] }).param("courtId", ID).exec(async function (courtId) {
+    return await this.courtService.assignPc(courtId);
+  }),
+  pushPcCommand: mutation(Boolean, { guards: [User] }).param("courtId", ID).exec(async function (courtId) {
+    return await this.courtService.pushPcCommand(courtId);
+  }),
+  courtCount: query(Int, { guards: [User] }).exec(async function () {
+    return 0;
+  }),
+})) {}
+`,
+);
+
+const storeOf = (body: string) =>
+  fileOf(
+    "apps/demo/lib/court/court.store.ts",
+    `import { store } from "akanjs/store";\nimport * as cnst from "../cnst";\nimport { fetch, sig } from "../useClient";\n\nexport class CourtStore extends store(sig.court, () => ({ count: 0 })) {\n${body}\n}\n`,
+  );
+
+const scan = (store: SourceFileInfo, otherStores: SourceFileInfo[] = []) =>
+  new StoreWriteScanner(new WritingActionIndex(new SignalMutationIndex([signal]), [store, ...otherStores])).scan(store);
+
+const pushStore = fileOf(
+  "apps/demo/lib/push/push.store.ts",
+  `import { fetch, sig } from "../useClient";
+export class PushStore extends store(sig.push, () => ({})) {
+  async pushCommandOnPc(courtId: string) {
+    await fetch.pushPcCommand(courtId);
+  }
+  async countPushes() {
+    return await fetch.courtCount();
+  }
+}
+`,
+);
+
+describe("StoreWriteScanner", () => {
+  test("reports an action sending two mutations at the second one", () => {
+    const writes = scan(
+      storeOf(`  async assignCourtPcOnCourt(courtId: string) {
+    const court = await fetch.assignCourtPc(courtId);
+    await fetch.pushPcCommand(court.id);
+    this.setCourt(court);
+  }`),
+    );
+    expect(writes).toEqual([
+      {
+        action: "assignCourtPcOnCourt",
+        line: 8,
+        writes: ["fetch.assignCourtPc", "fetch.pushPcCommand"],
+        writeCount: 2,
+        isRootChain: false,
+      },
+    ]);
+  });
+
+  test("reads a mutation and a query, or a model read, as one write", () => {
+    const writes = scan(
+      storeOf(`  async refreshCourt(courtId: string) {
+    const court = await fetch.assignCourtPc(courtId);
+    this.set({ count: await fetch.courtCount() });
+    this.setCourt(await fetch.court(court.id));
+  }`),
+    );
+    expect(writes).toEqual([]);
+  });
+
+  test("reads writes on exclusive branches as one", () => {
+    const writes = scan(
+      storeOf(`  async pushOnCourt(courtId: string, many: boolean) {
+    if (many) await fetch.assignCourtPc(courtId);
+    else await fetch.pushPcCommand(courtId);
+  }`),
+    );
+    expect(writes).toEqual([]);
+  });
+
+  test("counts the generated CRUD and a write inside a nested callback", () => {
+    const writes = scan(
+      storeOf(`  async mergeCourts(courtIds: string[]) {
+    await Promise.all(courtIds.map(async (courtId) => fetch.mergeCourt(courtId, {})));
+    setTimeout(() => void fetch["pushPcCommand"](courtIds[0]), 0);
+  }`),
+    );
+    expect(writes.map(({ action, writes }) => ({ action, writes }))).toEqual([
+      { action: "mergeCourts", writes: ["fetch.mergeCourt (per item)", 'fetch["pushPcCommand"]'] },
+    ]);
+  });
+
+  test("reads one write per item as two, in a loop or a per-element callback, but not the list it loops over", () => {
+    const writes = scan(
+      storeOf(`  async removeCourts(courtIds: string[]) {
+    for (const courtId of courtIds) await fetch.mergeCourt(courtId, {});
+  }
+  async pushToEach(courtIds: string[]) {
+    await Promise.all(courtIds.map((courtId) => fetch.pushPcCommand(courtId)));
+  }
+  async assignOnce(courtId: string) {
+    for (const pc of [await fetch.assignCourtPc(courtId)]) this.setCourt(pc);
+  }`),
+    );
+    expect(writes.map(({ action, writes, writeCount }) => ({ action, writes, writeCount }))).toEqual([
+      { action: "removeCourts", writes: ["fetch.mergeCourt (per item)"], writeCount: 2 },
+      { action: "pushToEach", writes: ["fetch.pushPcCommand (per item)"], writeCount: 2 },
+    ]);
+  });
+
+  test("counts a call to another writing action of the same store", () => {
+    const writes = scan(
+      storeOf(`  async pushCommandOnCourt(courtId: string) {
+    await fetch.pushPcCommand(courtId);
+  }
+  async readCourt(courtId: string) {
+    return fetch.court(courtId);
+  }
+  async assignCourtPcOnCourt(courtId: string) {
+    await this.readCourt(courtId);
+    await fetch.assignCourtPc(courtId);
+    await this.pushCommandOnCourt(courtId);
+  }`),
+    );
+    expect(writes).toEqual([
+      {
+        action: "assignCourtPcOnCourt",
+        line: 15,
+        writes: ["fetch.assignCourtPc", "this.pushCommandOnCourt"],
+        writeCount: 2,
+        isRootChain: false,
+      },
+    ]);
+  });
+
+  test("counts a generated CRUD action of the store's own model as its own write", () => {
+    const writes = scan(
+      storeOf(`  async createAndPushCourt(courtId: string) {
+    await this.createCourt({ name: courtId });
+    await fetch.pushPcCommand(courtId);
+  }`),
+    );
+    expect(writes).toMatchObject([
+      { action: "createAndPushCourt", writes: ["this.createCourt", "fetch.pushPcCommand"] },
+    ]);
+    expect(writes[0]?.isRootChain).toBe(false);
+  });
+
+  test("reads another store's writing action through the RootStore cast, an alias of it or a RootStore parameter", () => {
+    const writes = scan(
+      storeOf(`  async assignAndPush(courtId: string) {
+    await fetch.assignCourtPc(courtId);
+    await (this as unknown as RootStore).pushCommandOnPc(courtId);
+  }
+  async assignThroughAlias(courtId: string) {
+    const root = this as unknown as RootStore;
+    await root.countPushes();
+    await fetch.assignCourtPc(courtId);
+    await root.pushCommandOnPc(courtId);
+  }
+  static async assignFrom(root: RootStore, courtId: string) {
+    await root.assignCourtPcOnCourt(courtId);
+    await root.pushCommandOnPc(courtId);
+  }
+  async assignCourtPcOnCourt(courtId: string) {
+    await fetch.assignCourtPc(courtId);
+  }`),
+      [pushStore],
+    );
+    expect(writes.map(({ action, writes, isRootChain }) => ({ action, writes, isRootChain }))).toEqual([
+      {
+        action: "assignAndPush",
+        writes: ["fetch.assignCourtPc", "(this as unknown as RootStore).pushCommandOnPc"],
+        isRootChain: true,
+      },
+      { action: "assignThroughAlias", writes: ["fetch.assignCourtPc", "root.pushCommandOnPc"], isRootChain: true },
+      { action: "assignFrom", writes: ["root.assignCourtPcOnCourt", "root.pushCommandOnPc"], isRootChain: true },
+    ]);
+  });
+
+  test("counts a call to a writing static helper, and the writes a callback hands it", () => {
+    const writes = scan(
+      storeOf(`  static async guarded(root: RootStore, write: () => Promise<void>) {
+    await write();
+    void root.countPushes();
+  }
+  static async assignOnce(root: RootStore, courtId: string) {
+    await fetch.assignCourtPc(courtId);
+  }
+  async assignAndPush(courtId: string) {
+    const root = this as unknown as RootStore;
+    await CourtStore.assignOnce(root, courtId);
+    await CourtStore.guarded(root, () => root.pushCommandOnPc(courtId));
+  }`),
+      [pushStore],
+    );
+    expect(writes).toMatchObject([
+      {
+        action: "assignAndPush",
+        writes: ["CourtStore.assignOnce", "root.pushCommandOnPc"],
+        isRootChain: true,
+      },
+    ]);
+  });
+
+  test("reads the store's own writing static as its own write, not a chain through another store", () => {
+    const writes = scan(
+      storeOf(`  static async assignOnce(courtId: string) {
+    await fetch.assignCourtPc(courtId);
+  }
+  async assignAndPush(courtId: string) {
+    await CourtStore.assignOnce(courtId);
+    await fetch.pushPcCommand(courtId);
+  }`),
+    );
+    expect(writes).toMatchObject([
+      { action: "assignAndPush", writes: ["CourtStore.assignOnce", "fetch.pushPcCommand"], isRootChain: false },
+    ]);
+  });
+
+  test("reads a recursive call as no write, and a static helper's own writes as a chain", () => {
+    const writes = scan(
+      storeOf(`  async undoOnCourt(courtId: string) {
+    await fetch.assignCourtPc(courtId);
+    await this.undoOnCourt(courtId);
+  }
+  static async sync(courtId: string) {
+    await fetch.assignCourtPc(courtId);
+    await fetch.pushPcCommand(courtId);
+  }`),
+    );
+    expect(writes.map(({ action, isRootChain }) => ({ action, isRootChain }))).toEqual([
+      { action: "sync", isRootChain: false },
+    ]);
+  });
+
+  test("ignores getters, class-property arrows and classes that are not stores", () => {
+    const writes = scan(
+      fileOf(
+        "apps/demo/lib/court/court.store.ts",
+        `import { fetch, sig } from "../useClient";
+export class CourtStore extends store(sig.court, () => ({})) {
+  get both() {
+    void fetch.assignCourtPc("a");
+    void fetch.pushPcCommand("a");
+    return true;
+  }
+  assignBoth = async (courtId: string) => {
+    await fetch.assignCourtPc(courtId);
+    await fetch.pushPcCommand(courtId);
+  };
+}
+export class Helper extends Base {
+  async run(courtId: string) {
+    await fetch.assignCourtPc(courtId);
+    await fetch.pushPcCommand(courtId);
+  }
+}`,
+      ),
+    );
+    expect(writes).toEqual([]);
+  });
+
+  test("reads nothing from a store that does not import fetch", () => {
+    const store = fileOf(
+      "apps/demo/lib/court/court.store.ts",
+      `export class CourtStore extends store(sig.court, () => ({})) {
+  async run(courtId: string) {
+    await fetch.assignCourtPc(courtId);
+    await fetch.pushPcCommand(courtId);
+  }
+}`,
+    );
+    expect(scan(store)).toEqual([]);
+  });
+});

package/storeWriteScanner.ts

@@ -0,0 +1,50 @@
+import type ts from "typescript";
+import type { SourceFileInfo } from "./qualityScanner";
+import { type StoreCallTarget, StoreSource } from "./storeSource";
+import { WritePath } from "./writePath";
+import type { WritingActionIndex } from "./writingActionIndex";
+
+export interface StoreMultiWrite {
+  action: string;
+  line: number;
+  writes: string[];
+  writeCount: number;
+  isRootChain: boolean;
+}
+
+export class StoreWriteScanner {
+  readonly #index: WritingActionIndex;
+
+  constructor(index: WritingActionIndex) {
+    this.#index = index;
+  }
+
+  scan({ file, sourceFile }: Pick<SourceFileInfo, "file" | "sourceFile">): StoreMultiWrite[] {
+    const source = new StoreSource({ file, sourceFile });
+    return source.methods.flatMap((method) => {
+      const targets = new Map<ts.CallExpression, StoreCallTarget>();
+      const path = new WritePath((call) => {
+        const target = this.#index.writeOf(source, method, call);
+        if (target) targets.set(call, target);
+        return !!target;
+      });
+      const writes = path.along(method.body);
+      const writeCount = path.countOf(writes);
+      const second = writes[1] ?? writes[0];
+      if (writeCount < 2 || !second) return [];
+      return [
+        {
+          action: method.name,
+          line: sourceFile.getLineAndCharacterOfPosition(second.getStart(sourceFile)).line + 1,
+          writes: writes.map((call) => path.labelOf(call, sourceFile)),
+          writeCount,
+          isRootChain: writes.some((call) => StoreWriteScanner.#crossesStores(targets.get(call), method.store)),
+        },
+      ];
+    });
+  }
+
+  static #crossesStores(target: StoreCallTarget | undefined, ownStore: string) {
+    return (target?.kind === "static" && target.store !== ownStore) || (target?.kind === "action" && !target.isOwn);
+  }
+}

package/subspace.test.ts

@@ -513,6 +513,16 @@ describe("SubspaceConfig", () => {
     ).toThrow(/duplicate subspace/);
   });
 
+  test("refuses a subspace name that is not a plain folder name", () => {
+    for (const name of ["..", "../outside", "a/b", ".hidden", "-x", "a b"])
+      expect(() => new SubspaceConfig({ subspaces: [{ name, repo: "a.git", apps: ["one"] }] })).toThrow(
+        /subspace name .* takes letters, digits/,
+      );
+    expect(
+      new SubspaceConfig({ subspaces: [{ name: "acme.v2_beta-1", repo: "a.git", apps: ["one"] }] }).subspaces,
+    ).toHaveLength(1);
+  });
+
   test("refuses two subspaces on one cloud workspace, and takes a declaration with none", () => {
     expect(
       () =>

package/subspaceClone.ts

@@ -5,7 +5,7 @@ import { Executor, WorkspaceExecutor } from "./executors";
 import { FileSys } from "./fileSys";
 import { LibSource } from "./libSource";
 import { type SlicePlan, SlicePlanner } from "./slicePlanner";
-import type { SubspaceDeclaration } from "./subspaceConfig";
+import { SubspaceConfig, type SubspaceDeclaration } from "./subspaceConfig";
 import type { PackageJson } from "./types";
 
 export class SubspaceClone {
@@ -43,6 +43,8 @@ export class SubspaceClone {
   constructor(workspace: WorkspaceExecutor, declaration: SubspaceDeclaration) {
     this.#workspace = workspace;
     this.#declaration = declaration;
+    if (!SubspaceConfig.namePattern.test(declaration.name))
+      throw new Error(`Subspace name "${declaration.name}" cannot name a folder under .akan/subspace.`);
     this.#clonePath = path.join(workspace.workspaceRoot, ".akan/subspace", declaration.name);
     this.#clone = new Executor(`subspace-${declaration.name}`, this.#clonePath);
   }

package/subspaceConfig.ts

@@ -7,6 +7,7 @@ export type { SubspaceConfigInput, SubspaceDeclaration };
 export class SubspaceConfig {
   static readonly source = "subspace in the workspace root akan.config.ts";
   static readonly defaultPushableBranches = ["main", "develop", "debug"];
+  static readonly namePattern = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
 
   static async from(workspace: WorkspaceExecutor): Promise<SubspaceConfig | null> {
     const { subspace } = await workspace.getConfig();
@@ -31,6 +32,11 @@ export class SubspaceConfig {
     for (const subspace of this.subspaces) {
       if (!subspace.name || !subspace.repo)
         throw new Error(`${SubspaceConfig.source}: every subspace needs a name and a repo`);
+      //? The name is the clone folder under .akan/subspace, which a fresh clone empties first.
+      if (!SubspaceConfig.namePattern.test(subspace.name))
+        throw new Error(
+          `${SubspaceConfig.source}: subspace name "${subspace.name}" takes letters, digits, ".", "_" and "-", starting with a letter or digit`,
+        );
       if (seenNames.has(subspace.name))
         throw new Error(`${SubspaceConfig.source}: duplicate subspace "${subspace.name}"`);
       seenNames.add(subspace.name);