@lukoweb/apitogo 0.2.23 → 0.2.25

package/src/config/v2/parse.ts

@@ -1,214 +1,214 @@
-import { z } from "zod";
-import { ConfigError, type ConfigIssue } from "./errors.js";
-import { CONFIG_VERSION, type ConfigV2, ConfigV2Schema } from "./schema.js";
-
-/** Keys that existed in an earlier design and were removed on purpose, with the reason to show the tenant. */
-const REMOVED_KEYS: Readonly<Record<string, string>> = {
-  "plans.provider":
-    "plans.provider was removed. Only plans.billing.provider (stripe or none) is selectable.",
-};
-
-type PathSegment = PropertyKey;
-
-function pathToString(path: readonly PathSegment[]): string {
-  return path.reduce<string>(
-    (acc, segment) =>
-      typeof segment === "number"
-        ? `${acc}[${segment}]`
-        : acc === ""
-          ? String(segment)
-          : `${acc}.${String(segment)}`,
-    "",
-  );
-}
-
-function unwrapOptional(schema: z.core.$ZodType): z.core.$ZodType {
-  let current = schema;
-  while (current instanceof z.ZodOptional) current = current.unwrap();
-  return current;
-}
-
-function step(
-  schema: z.core.$ZodType,
-  segment: PathSegment,
-): z.core.$ZodType | undefined {
-  const current = unwrapOptional(schema);
-  if (current instanceof z.ZodObject && typeof segment === "string") {
-    return current.shape[segment];
-  }
-  if (current instanceof z.ZodArray && typeof segment === "number") {
-    return current.element;
-  }
-  return undefined;
-}
-
-/** The keys the schema accepts at `path`, used for "did you mean" hints. Empty when the path cannot be resolved. */
-function knownKeysAt(path: readonly PathSegment[]): string[] {
-  let current: z.core.$ZodType | undefined = ConfigV2Schema;
-  for (const segment of path) {
-    if (!current) return [];
-    current = step(current, segment);
-  }
-  if (!current) return [];
-  const resolved = unwrapOptional(current);
-  return resolved instanceof z.ZodObject ? Object.keys(resolved.shape) : [];
-}
-
-function editDistance(a: string, b: string): number {
-  const row = Array.from({ length: b.length + 1 }, (_, i) => i);
-  for (let i = 1; i <= a.length; i++) {
-    let previous = row[0] ?? 0;
-    row[0] = i;
-    for (let j = 1; j <= b.length; j++) {
-      const current = row[j] ?? 0;
-      row[j] = Math.min(
-        (row[j] ?? 0) + 1,
-        (row[j - 1] ?? 0) + 1,
-        previous + (a[i - 1] === b[j - 1] ? 0 : 1),
-      );
-      previous = current;
-    }
-  }
-  return row[b.length] ?? 0;
-}
-
-function unknownKeyHint(
-  fullPath: string,
-  key: string,
-  known: readonly string[],
-): string | undefined {
-  const removed = REMOVED_KEYS[fullPath];
-  if (removed) return removed;
-
-  const closest = known
-    .map((candidate) => ({
-      candidate,
-      distance: editDistance(key.toLowerCase(), candidate.toLowerCase()),
-    }))
-    .filter(({ distance }) => distance <= 2)
-    .sort((a, b) => a.distance - b.distance)[0];
-  if (closest) return `Did you mean "${closest.candidate}"?`;
-  return known.length > 0 ? `Allowed keys: ${known.join(", ")}.` : undefined;
-}
-
-function mapIssue(issue: z.core.$ZodIssue): ConfigIssue[] {
-  const path = pathToString(issue.path);
-
-  switch (issue.code) {
-    case "unrecognized_keys":
-      return issue.keys.map((key) => {
-        const fullPath = pathToString([...issue.path, key]);
-        return {
-          code: "CONFIG_UNKNOWN_KEY",
-          path: fullPath,
-          message: `Unknown key "${key}".`,
-          hint: unknownKeyHint(fullPath, key, knownKeysAt(issue.path)),
-        };
-      });
-    case "invalid_value":
-      return [
-        {
-          code: "CONFIG_INVALID_VALUE",
-          path,
-          message: `must be one of: ${issue.values.map((v) => JSON.stringify(v)).join(", ")}.`,
-        },
-      ];
-    case "custom": {
-      const code =
-        typeof issue.params?.code === "string"
-          ? issue.params.code
-          : "CONFIG_INVALID_VALUE";
-      return [{ code, path, message: issue.message ?? "is invalid." }];
-    }
-    case "invalid_type":
-      return [
-        /received undefined/.test(issue.message)
-          ? { code: "CONFIG_MISSING_FIELD", path, message: "is required." }
-          : { code: "CONFIG_INVALID_VALUE", path, message: issue.message },
-      ];
-    default:
-      return [{ code: "CONFIG_INVALID_VALUE", path, message: issue.message }];
-  }
-}
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
-/**
- * Checks that must run before the schema because the schema cannot express them well: the version gate and the
- * one legacy shape that deserves its own message. Returns the issues, the value to validate, and whether to stop.
- */
-function preflight(raw: unknown): {
-  issues: ConfigIssue[];
-  value: unknown;
-  stop: boolean;
-} {
-  if (!isRecord(raw)) {
-    return {
-      issues: [
-        {
-          code: "CONFIG_INVALID_VALUE",
-          path: "",
-          message: "The config must be a JSON object.",
-        },
-      ],
-      value: raw,
-      stop: true,
-    };
-  }
-
-  if (raw.version !== CONFIG_VERSION) {
-    const found =
-      raw.version === undefined
-        ? '"version" is missing.'
-        : `"version" is ${JSON.stringify(raw.version)}.`;
-    return {
-      issues: [
-        {
-          code: "CONFIG_VERSION_UNSUPPORTED",
-          path: "version",
-          message: `${found} This CLI reads config version ${CONFIG_VERSION}.`,
-          hint: `Set "version": ${CONFIG_VERSION}. Earlier flat configs are not supported; see the Tenant Service Model for the new shape.`,
-        },
-      ],
-      value: raw,
-      stop: true,
-    };
-  }
-
-  const issues: ConfigIssue[] = [];
-  const value = structuredClone(raw);
-  const portal = value.portal;
-  if (isRecord(portal) && Array.isArray(portal.docs)) {
-    issues.push({
-      code: "PORTAL_CONFIG_INVALID",
-      path: "portal.docs",
-      message:
-        "portal.docs is now an object. Rename the globs array to portal.docs.content.",
-      hint: 'For example: "docs": { "content": ["docs/**/*.md"] }',
-    });
-    // Reported above; keep the schema from reporting the same value again as a type error.
-    delete portal.docs;
-  }
-
-  return { issues, value, stop: false };
-}
-
-/** Validates a parsed config. Throws a {@link ConfigError} listing every problem found. */
-export function parseConfigV2(
-  raw: unknown,
-  file = "apitogo.config.json",
-): ConfigV2 {
-  const pre = preflight(raw);
-  if (pre.stop) throw new ConfigError(file, pre.issues);
-
-  const result = ConfigV2Schema.safeParse(pre.value);
-  const issues = [
-    ...pre.issues,
-    ...(result.success ? [] : result.error.issues.flatMap(mapIssue)),
-  ];
-
-  if (issues.length > 0 || !result.success) throw new ConfigError(file, issues);
-  return result.data;
-}
+import { z } from "zod";
+import { ConfigError, type ConfigIssue } from "./errors.js";
+import { CONFIG_VERSION, type ConfigV2, ConfigV2Schema } from "./schema.js";
+
+/** Keys that existed in an earlier design and were removed on purpose, with the reason to show the tenant. */
+const REMOVED_KEYS: Readonly<Record<string, string>> = {
+  "plans.provider":
+    "plans.provider was removed. Only plans.billing.provider (stripe or none) is selectable.",
+};
+
+type PathSegment = PropertyKey;
+
+function pathToString(path: readonly PathSegment[]): string {
+  return path.reduce<string>(
+    (acc, segment) =>
+      typeof segment === "number"
+        ? `${acc}[${segment}]`
+        : acc === ""
+          ? String(segment)
+          : `${acc}.${String(segment)}`,
+    "",
+  );
+}
+
+function unwrapOptional(schema: z.core.$ZodType): z.core.$ZodType {
+  let current = schema;
+  while (current instanceof z.ZodOptional) current = current.unwrap();
+  return current;
+}
+
+function step(
+  schema: z.core.$ZodType,
+  segment: PathSegment,
+): z.core.$ZodType | undefined {
+  const current = unwrapOptional(schema);
+  if (current instanceof z.ZodObject && typeof segment === "string") {
+    return current.shape[segment];
+  }
+  if (current instanceof z.ZodArray && typeof segment === "number") {
+    return current.element;
+  }
+  return undefined;
+}
+
+/** The keys the schema accepts at `path`, used for "did you mean" hints. Empty when the path cannot be resolved. */
+function knownKeysAt(path: readonly PathSegment[]): string[] {
+  let current: z.core.$ZodType | undefined = ConfigV2Schema;
+  for (const segment of path) {
+    if (!current) return [];
+    current = step(current, segment);
+  }
+  if (!current) return [];
+  const resolved = unwrapOptional(current);
+  return resolved instanceof z.ZodObject ? Object.keys(resolved.shape) : [];
+}
+
+function editDistance(a: string, b: string): number {
+  const row = Array.from({ length: b.length + 1 }, (_, i) => i);
+  for (let i = 1; i <= a.length; i++) {
+    let previous = row[0] ?? 0;
+    row[0] = i;
+    for (let j = 1; j <= b.length; j++) {
+      const current = row[j] ?? 0;
+      row[j] = Math.min(
+        (row[j] ?? 0) + 1,
+        (row[j - 1] ?? 0) + 1,
+        previous + (a[i - 1] === b[j - 1] ? 0 : 1),
+      );
+      previous = current;
+    }
+  }
+  return row[b.length] ?? 0;
+}
+
+function unknownKeyHint(
+  fullPath: string,
+  key: string,
+  known: readonly string[],
+): string | undefined {
+  const removed = REMOVED_KEYS[fullPath];
+  if (removed) return removed;
+
+  const closest = known
+    .map((candidate) => ({
+      candidate,
+      distance: editDistance(key.toLowerCase(), candidate.toLowerCase()),
+    }))
+    .filter(({ distance }) => distance <= 2)
+    .sort((a, b) => a.distance - b.distance)[0];
+  if (closest) return `Did you mean "${closest.candidate}"?`;
+  return known.length > 0 ? `Allowed keys: ${known.join(", ")}.` : undefined;
+}
+
+function mapIssue(issue: z.core.$ZodIssue): ConfigIssue[] {
+  const path = pathToString(issue.path);
+
+  switch (issue.code) {
+    case "unrecognized_keys":
+      return issue.keys.map((key) => {
+        const fullPath = pathToString([...issue.path, key]);
+        return {
+          code: "CONFIG_UNKNOWN_KEY",
+          path: fullPath,
+          message: `Unknown key "${key}".`,
+          hint: unknownKeyHint(fullPath, key, knownKeysAt(issue.path)),
+        };
+      });
+    case "invalid_value":
+      return [
+        {
+          code: "CONFIG_INVALID_VALUE",
+          path,
+          message: `must be one of: ${issue.values.map((v) => JSON.stringify(v)).join(", ")}.`,
+        },
+      ];
+    case "custom": {
+      const code =
+        typeof issue.params?.code === "string"
+          ? issue.params.code
+          : "CONFIG_INVALID_VALUE";
+      return [{ code, path, message: issue.message ?? "is invalid." }];
+    }
+    case "invalid_type":
+      return [
+        /received undefined/.test(issue.message)
+          ? { code: "CONFIG_MISSING_FIELD", path, message: "is required." }
+          : { code: "CONFIG_INVALID_VALUE", path, message: issue.message },
+      ];
+    default:
+      return [{ code: "CONFIG_INVALID_VALUE", path, message: issue.message }];
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Checks that must run before the schema because the schema cannot express them well: the version gate and the
+ * one legacy shape that deserves its own message. Returns the issues, the value to validate, and whether to stop.
+ */
+function preflight(raw: unknown): {
+  issues: ConfigIssue[];
+  value: unknown;
+  stop: boolean;
+} {
+  if (!isRecord(raw)) {
+    return {
+      issues: [
+        {
+          code: "CONFIG_INVALID_VALUE",
+          path: "",
+          message: "The config must be a JSON object.",
+        },
+      ],
+      value: raw,
+      stop: true,
+    };
+  }
+
+  if (raw.version !== CONFIG_VERSION) {
+    const found =
+      raw.version === undefined
+        ? '"version" is missing.'
+        : `"version" is ${JSON.stringify(raw.version)}.`;
+    return {
+      issues: [
+        {
+          code: "CONFIG_VERSION_UNSUPPORTED",
+          path: "version",
+          message: `${found} This CLI reads config version ${CONFIG_VERSION}.`,
+          hint: `Set "version": ${CONFIG_VERSION}. Earlier flat configs are not supported; see the Tenant Service Model for the new shape.`,
+        },
+      ],
+      value: raw,
+      stop: true,
+    };
+  }
+
+  const issues: ConfigIssue[] = [];
+  const value = structuredClone(raw);
+  const portal = value.portal;
+  if (isRecord(portal) && Array.isArray(portal.docs)) {
+    issues.push({
+      code: "PORTAL_CONFIG_INVALID",
+      path: "portal.docs",
+      message:
+        "portal.docs is now an object. Rename the globs array to portal.docs.content.",
+      hint: 'For example: "docs": { "content": ["docs/**/*.md"] }',
+    });
+    // Reported above; keep the schema from reporting the same value again as a type error.
+    delete portal.docs;
+  }
+
+  return { issues, value, stop: false };
+}
+
+/** Validates a parsed config. Throws a {@link ConfigError} listing every problem found. */
+export function parseConfigV2(
+  raw: unknown,
+  file = "apitogo.config.json",
+): ConfigV2 {
+  const pre = preflight(raw);
+  if (pre.stop) throw new ConfigError(file, pre.issues);
+
+  const result = ConfigV2Schema.safeParse(pre.value);
+  const issues = [
+    ...pre.issues,
+    ...(result.success ? [] : result.error.issues.flatMap(mapIssue)),
+  ];
+
+  if (issues.length > 0 || !result.success) throw new ConfigError(file, issues);
+  return result.data;
+}

package/src/config/v2/paths.ts

@@ -1,54 +1,54 @@
-import path from "node:path";
-import type { Layout } from "./schema.js";
-
-/** Names inside the generated-state directory (Tenant Service Model, section 4). All of it is regenerable. */
-export const STATE_FILE = "state.json";
-/** Service manifest written by `deploy` (Reference, section 4). Public values only. */
-export const MANIFEST_FILE = "services.json";
-export const GENERATED_DIR = "generated";
-export const BUILD_DIR = "build";
-
-/**
- * Directory that holds the tenant-authored content for a layout: the config's own directory for `standalone`,
- * an `apitogo/` folder next to it for `embedded`.
- */
-export function layoutRoot(configDir: string, layout: Layout): string {
-  return layout === "embedded" ? path.join(configDir, "apitogo") : configDir;
-}
-
-/**
- * Directory for generated and observed state. It carries its own `.gitignore` containing `*`, so the tenant's root
- * `.gitignore` never needs to change.
- */
-export function stateDirFor(configDir: string, layout: Layout): string {
-  return layout === "embedded"
-    ? path.join(configDir, "apitogo", ".state")
-    : path.join(configDir, ".apitogo");
-}
-
-/** Path of the service manifest inside a state directory. */
-export const manifestPathFor = (state: { dir: string }): string =>
-  path.join(state.dir, MANIFEST_FILE);
-
-export type StatePaths = {
-  dir: string;
-  /** Per-service ledger and artifact hashes. */
-  file: string;
-  /** Generated portal wrapper, resolved config snapshot, processed OpenAPI schemas. */
-  generatedDir: string;
-  /** Build output; replaces the old root `dist/`. */
-  buildDir: string;
-  /** The state directory's own ignore file. */
-  gitignore: string;
-};
-
-export function statePathsFor(configDir: string, layout: Layout): StatePaths {
-  const dir = stateDirFor(configDir, layout);
-  return {
-    dir,
-    file: path.join(dir, STATE_FILE),
-    generatedDir: path.join(dir, GENERATED_DIR),
-    buildDir: path.join(dir, BUILD_DIR),
-    gitignore: path.join(dir, ".gitignore"),
-  };
-}
+import path from "node:path";
+import type { Layout } from "./schema.js";
+
+/** Names inside the generated-state directory (Tenant Service Model, section 4). All of it is regenerable. */
+export const STATE_FILE = "state.json";
+/** Service manifest written by `deploy` (Reference, section 4). Public values only. */
+export const MANIFEST_FILE = "services.json";
+export const GENERATED_DIR = "generated";
+export const BUILD_DIR = "build";
+
+/**
+ * Directory that holds the tenant-authored content for a layout: the config's own directory for `standalone`,
+ * an `apitogo/` folder next to it for `embedded`.
+ */
+export function layoutRoot(configDir: string, layout: Layout): string {
+  return layout === "embedded" ? path.join(configDir, "apitogo") : configDir;
+}
+
+/**
+ * Directory for generated and observed state. It carries its own `.gitignore` containing `*`, so the tenant's root
+ * `.gitignore` never needs to change.
+ */
+export function stateDirFor(configDir: string, layout: Layout): string {
+  return layout === "embedded"
+    ? path.join(configDir, "apitogo", ".state")
+    : path.join(configDir, ".apitogo");
+}
+
+/** Path of the service manifest inside a state directory. */
+export const manifestPathFor = (state: { dir: string }): string =>
+  path.join(state.dir, MANIFEST_FILE);
+
+export type StatePaths = {
+  dir: string;
+  /** Per-service ledger and artifact hashes. */
+  file: string;
+  /** Generated portal wrapper, resolved config snapshot, processed OpenAPI schemas. */
+  generatedDir: string;
+  /** Build output; replaces the old root `dist/`. */
+  buildDir: string;
+  /** The state directory's own ignore file. */
+  gitignore: string;
+};
+
+export function statePathsFor(configDir: string, layout: Layout): StatePaths {
+  const dir = stateDirFor(configDir, layout);
+  return {
+    dir,
+    file: path.join(dir, STATE_FILE),
+    generatedDir: path.join(dir, GENERATED_DIR),
+    buildDir: path.join(dir, BUILD_DIR),
+    gitignore: path.join(dir, ".gitignore"),
+  };
+}