ignotum 0.0.13 → 0.0.15

package/src/cli/route-static.ts

@@ -0,0 +1,710 @@
+import { Effect, FileSystem, Path, Predicate, Schema } from "effect";
+import { parseSync, type Node, type Expression, type Program } from "oxc-parser";
+import {
+  LayoutMetadata,
+  StaticMetadata,
+  UrlValueDescriptor,
+} from "@ignotum/contracts/app-definition";
+
+export class InvalidRouteSource extends Schema.TaggedError<InvalidRouteSource>()(
+  "InvalidRouteSource",
+  {
+    path: Schema.String,
+    code: Schema.optional(Schema.Literal("MissingExport")),
+    field: Schema.String,
+    line: Schema.Int,
+    column: Schema.Int,
+    message: Schema.String,
+  },
+) {}
+
+interface SourceModule {
+  readonly path: string;
+  readonly source: string;
+  readonly program: Program;
+}
+export type StaticValue =
+  | string
+  | number
+  | boolean
+  | null
+  | ReadonlyArray<StaticValue>
+  | { readonly [key: string]: StaticValue };
+export interface SourceExpression {
+  readonly module: SourceModule;
+  readonly node: Expression;
+}
+export type SourceResolver = (
+  specifier: string,
+  importer: string,
+) => Effect.Effect<string, InvalidRouteSource>;
+const unwrap = (node: Expression): Expression => {
+  switch (node.type) {
+    case "TSAsExpression":
+    case "TSSatisfiesExpression":
+    case "TSNonNullExpression":
+    case "ParenthesizedExpression":
+      return unwrap(node.expression);
+    default:
+      return node;
+  }
+};
+const propertyName = (node: Node): string | undefined =>
+  node.type === "Identifier"
+    ? node.name
+    : node.type === "Literal" && Predicate.isString(node.value)
+      ? node.value
+      : undefined;
+const children = (node: Node): ReadonlyArray<Node> =>
+  Object.values(node).flatMap((value) => {
+    const values = Array.isArray(value) ? value : [value];
+    // OXC owns these AST objects. Positions and node tags distinguish children from scalar fields.
+    return values.filter(
+      (child): child is Node => Predicate.isObject(child) && "type" in child && "start" in child,
+    );
+  });
+const walk = (node: Node, visit: (node: Node) => void): void => {
+  visit(node);
+  for (const child of children(node)) walk(child, visit);
+};
+const identifiers = (node: Node): Set<string> => {
+  const names = new Set<string>();
+  const visit = (child: Node): void => {
+    if (child.type === "Identifier") {
+      names.add(child.name);
+      return;
+    }
+    if (child.type === "MemberExpression") {
+      visit(child.object);
+      if (child.computed) visit(child.property);
+      return;
+    }
+    if (child.type === "Property") {
+      if (child.computed) visit(child.key);
+      visit(child.value);
+      return;
+    }
+    for (const nested of children(child)) visit(nested);
+  };
+  visit(node);
+  return names;
+};
+export const sourceError = (
+  module: Pick<SourceModule, "path" | "source">,
+  node: Pick<Node, "start">,
+  field: string,
+  detail: string,
+  code?: "MissingExport",
+) => {
+  const prefix = module.source.slice(0, node.start);
+  const line = prefix.split("\n").length;
+  const column = node.start - prefix.lastIndexOf("\n");
+  return new InvalidRouteSource({
+    path: module.path,
+    code,
+    field,
+    line,
+    column,
+    message: `${module.path}:${line}:${column}: ${field}: ${detail}`,
+  });
+};
+
+export const createRouteExtractor = Effect.fn("Routes.createExtractor")(function* (
+  appDirectory: string,
+  resolve: SourceResolver,
+) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const modules = new Map<string, SourceModule>();
+  const dependencies = new Set<string>();
+  const load = Effect.fn("Routes.loadSource")(function* (
+    file: string,
+  ): Effect.fn.Return<SourceModule, InvalidRouteSource> {
+    const fail = (detail: string) =>
+      sourceError({ path: file, source: "" }, { start: 0 }, "module", detail);
+    const real = yield* fs
+      .realPath(file)
+      .pipe(Effect.mapError(() => fail("Cannot read source module.")));
+    if (
+      !real.startsWith(`${appDirectory}/`) ||
+      real.startsWith(`${appDirectory}/server/`) ||
+      !/\.(ts|tsx)$/.test(real) ||
+      real.endsWith(".d.ts")
+    )
+      return yield* fail(
+        "Static configuration must come from TypeScript app modules outside server/.",
+      );
+    dependencies.add(real);
+    const cached = modules.get(real);
+    if (cached !== undefined) return cached;
+    const source = yield* fs
+      .readFileString(real)
+      .pipe(Effect.mapError(() => fail("Cannot read source module.")));
+    const parsed = parseSync(real, source, {
+      lang: "tsx",
+      sourceType: "module",
+      preserveParens: true,
+      showSemanticErrors: true,
+    });
+    const error = parsed.errors[0];
+    if (error !== undefined)
+      return yield* sourceError(
+        { path: real, source },
+        { start: error.labels[0]?.start ?? 0 },
+        "module",
+        error.message,
+      );
+    const module = { path: real, source, program: parsed.program };
+    modules.set(real, module);
+    return module;
+  });
+  const imported = Effect.fn("Routes.importedSource")(function* (
+    module: SourceModule,
+    specifier: string,
+  ) {
+    return yield* load(yield* resolve(specifier, module.path));
+  });
+  const helper = Effect.fn("Routes.helper")(function* (
+    module: SourceModule,
+    local: string,
+    expected: string,
+  ) {
+    for (const statement of module.program.body) {
+      if (statement.type !== "ImportDeclaration" || statement.importKind === "type") continue;
+      for (const specifier of statement.specifiers) {
+        if (
+          specifier.type !== "ImportSpecifier" ||
+          specifier.importKind === "type" ||
+          specifier.local.name !== local ||
+          propertyName(specifier.imported) !== expected
+        )
+          continue;
+        const target = yield* resolve(statement.source.value, module.path);
+        if (path.normalize(target) === path.join(appDirectory, "_generated/client.ts")) return true;
+      }
+    }
+    return false;
+  });
+  // Track aliases as well as direct writes. A const object is not immutable if it escapes to a call.
+  const auditBinding = Effect.fn("Routes.auditBinding")(function* (
+    module: SourceModule,
+    name: string,
+    field: string,
+    object: boolean,
+  ) {
+    const aliases = new Set([name]);
+    let changed = object;
+    while (changed) {
+      changed = false;
+      walk(module.program, (node) => {
+        if (node.type !== "VariableDeclarator" || node.init == null) return;
+        if (![...identifiers(node.init)].some((id) => aliases.has(id))) return;
+        for (const alias of identifiers(node.id))
+          if (!aliases.has(alias)) {
+            aliases.add(alias);
+            changed = true;
+          }
+      });
+    }
+    const operations: Node[] = [];
+    walk(module.program, (node) => {
+      if (
+        node.type === "AssignmentExpression" ||
+        node.type === "UpdateExpression" ||
+        (node.type === "UnaryExpression" && node.operator === "delete")
+      )
+        operations.push(node);
+      if (object && (node.type === "CallExpression" || node.type === "NewExpression"))
+        operations.push(node);
+    });
+    for (const node of operations) {
+      const target =
+        node.type === "AssignmentExpression"
+          ? node.left
+          : node.type === "UpdateExpression" || node.type === "UnaryExpression"
+            ? node.argument
+            : node;
+      if (![...identifiers(target)].some((id) => aliases.has(id))) continue;
+      if (
+        node.type === "CallExpression" &&
+        node.callee.type === "Identifier" &&
+        ((yield* helper(module, node.callee.name, "route")) ||
+          (yield* helper(module, node.callee.name, "layout")))
+      )
+        continue;
+      if (node.type === "CallExpression" && node.callee.type === "MemberExpression") {
+        let base: Expression = node.callee.object;
+        while (base.type === "CallExpression" && base.callee.type === "MemberExpression")
+          base = base.callee.object;
+        if (base.type === "Identifier" && (yield* helper(module, base.name, "values"))) continue;
+      }
+      return yield* sourceError(
+        module,
+        node,
+        field,
+        `Constant '${name}' is mutated or escapes to unsupported code.`,
+      );
+    }
+  });
+  const binding = Effect.fn("Routes.binding")(function* (
+    module: SourceModule,
+    name: string,
+    field: string,
+    trail: ReadonlySet<string>,
+  ): Effect.fn.Return<SourceExpression, InvalidRouteSource> {
+    const key = `${module.path}:${name}`;
+    if (trail.has(key) || trail.size > 96)
+      return yield* sourceError(
+        module,
+        module.program,
+        field,
+        `Cyclic or excessively deep constant '${name}'.`,
+      );
+    const next = new Set([...trail, key]);
+    for (const statement of module.program.body) {
+      const declaration =
+        statement.type === "ExportNamedDeclaration" ? statement.declaration : statement;
+      if (declaration?.type === "VariableDeclaration") {
+        for (const item of declaration.declarations) {
+          if (item.id.type !== "Identifier" || item.id.name !== name) continue;
+          if (declaration.kind !== "const" || item.init == null)
+            return yield* sourceError(
+              module,
+              item,
+              field,
+              `Binding '${name}' must be an initialized const.`,
+            );
+          const expression = yield* dereference({ module, node: item.init }, field, next);
+          yield* auditBinding(
+            module,
+            name,
+            field,
+            !["Literal", "TemplateLiteral", "UnaryExpression"].includes(expression.node.type),
+          );
+          return expression;
+        }
+      }
+      if (statement.type === "ImportDeclaration" && statement.importKind !== "type") {
+        for (const specifier of statement.specifiers) {
+          if (specifier.local.name !== name) continue;
+          const target = yield* imported(module, statement.source.value);
+          const exportedName =
+            specifier.type === "ImportSpecifier" && specifier.importKind !== "type"
+              ? propertyName(specifier.imported)
+              : specifier.type === "ImportDefaultSpecifier"
+                ? "default"
+                : undefined;
+          if (exportedName === undefined) continue;
+          const expression = yield* exported(target, exportedName, field, next);
+          yield* auditBinding(
+            module,
+            name,
+            field,
+            !["Literal", "TemplateLiteral", "UnaryExpression"].includes(expression.node.type),
+          );
+          return expression;
+        }
+      }
+    }
+    return yield* sourceError(
+      module,
+      module.program,
+      field,
+      `No immutable constant '${name}' found.`,
+    );
+  });
+  const exported = Effect.fn("Routes.exportedConstant")(function* (
+    module: SourceModule,
+    name: string,
+    field: string,
+    trail: ReadonlySet<string>,
+  ): Effect.fn.Return<SourceExpression, InvalidRouteSource> {
+    const key = `${module.path}:export:${name}`;
+    if (trail.has(key) || trail.size > 96)
+      return yield* sourceError(
+        module,
+        module.program,
+        field,
+        `Cyclic or excessively deep re-export '${name}'.`,
+      );
+    const next = new Set([...trail, key]);
+    for (const statement of module.program.body) {
+      if (statement.type === "ExportDefaultDeclaration" && name === "default") {
+        if (statement.declaration.type === "Identifier")
+          return yield* binding(module, statement.declaration.name, field, next);
+        const declaration = statement.declaration;
+        if (
+          declaration.type === "FunctionDeclaration" ||
+          declaration.type === "ClassDeclaration" ||
+          declaration.type === "TSInterfaceDeclaration"
+        )
+          return yield* sourceError(
+            module,
+            declaration,
+            field,
+            "Default metadata exports must be static values.",
+          );
+        return yield* dereference({ module, node: declaration }, field, next);
+      }
+      if (statement.type !== "ExportNamedDeclaration" || statement.exportKind === "type") continue;
+      if (
+        statement.declaration?.type === "VariableDeclaration" &&
+        statement.declaration.declarations.some(
+          (item) => item.id.type === "Identifier" && item.id.name === name,
+        )
+      )
+        return yield* binding(module, name, field, next);
+      for (const specifier of statement.specifiers) {
+        if (specifier.exportKind === "type" || propertyName(specifier.exported) !== name) continue;
+        const local = propertyName(specifier.local)!;
+        return statement.source == null
+          ? yield* binding(module, local, field, next)
+          : yield* exported(yield* imported(module, statement.source.value), local, field, next);
+      }
+    }
+    const stars = module.program.body.filter(
+      (s) => s.type === "ExportAllDeclaration" && s.exportKind !== "type" && s.exported == null,
+    );
+    const matches: SourceExpression[] = [];
+    for (const star of stars) {
+      if (star.type !== "ExportAllDeclaration" || name === "default") continue;
+      const candidate = yield* exported(
+        yield* imported(module, star.source.value),
+        name,
+        field,
+        next,
+      ).pipe(Effect.result);
+      if (candidate._tag === "Success") {
+        if (
+          !matches.some(
+            (match) =>
+              match.module.path === candidate.success.module.path &&
+              match.node.start === candidate.success.node.start,
+          )
+        )
+          matches.push(candidate.success);
+      } else if (candidate.failure.code !== "MissingExport") return yield* candidate.failure;
+    }
+    if (matches.length === 1) return matches[0]!;
+    return yield* sourceError(
+      module,
+      module.program,
+      field,
+      `${matches.length > 1 ? "Ambiguous export" : "No export"} '${name}'.`,
+      matches.length > 1 ? undefined : "MissingExport",
+    );
+  });
+  const dereference = Effect.fn("Routes.dereference")(function* (
+    input: SourceExpression,
+    field: string,
+    trail: ReadonlySet<string> = new Set(),
+  ): Effect.fn.Return<SourceExpression, InvalidRouteSource> {
+    const node = unwrap(input.node);
+    if (
+      node.type === "MemberExpression" &&
+      !node.computed &&
+      !node.optional &&
+      node.object.type === "Identifier" &&
+      node.property.type === "Identifier"
+    ) {
+      const namespace = node.object.name;
+      for (const statement of input.module.program.body) {
+        if (
+          statement.type !== "ImportDeclaration" ||
+          statement.importKind === "type" ||
+          !statement.specifiers.some(
+            (specifier) =>
+              specifier.type === "ImportNamespaceSpecifier" && specifier.local.name === namespace,
+          )
+        )
+          continue;
+        yield* auditBinding(input.module, namespace, field, true);
+        return yield* exported(
+          yield* imported(input.module, statement.source.value),
+          node.property.name,
+          field,
+          trail,
+        );
+      }
+    }
+    return node.type === "Identifier"
+      ? yield* binding(input.module, node.name, field, trail)
+      : { module: input.module, node };
+  });
+  const properties = Effect.fn("Routes.properties")(function* (
+    input: SourceExpression,
+    field: string,
+    trail: ReadonlySet<string> = new Set(),
+  ): Effect.fn.Return<Map<string, SourceExpression>, InvalidRouteSource> {
+    const expression = yield* dereference(input, field, trail);
+    const { module, node } = expression;
+    const key = `${module.path}:${node.start}:${field}`;
+    if (trail.has(key) || trail.size > 96)
+      return yield* sourceError(module, node, field, "Cyclic or excessively deep configuration.");
+    const next = new Set([...trail, key]);
+    if (node.type !== "ObjectExpression")
+      return yield* sourceError(module, node, field, "Expected a statically extractable object.");
+    const output = new Map<string, SourceExpression>();
+    for (const property of node.properties) {
+      if (property.type === "SpreadElement") {
+        for (const [name, value] of yield* properties(
+          { module, node: property.argument },
+          field,
+          next,
+        ))
+          output.set(name, value);
+      } else {
+        const name = propertyName(property.key);
+        if (property.computed || property.method || property.kind !== "init" || name === undefined)
+          return yield* sourceError(
+            module,
+            property,
+            field,
+            "Computed keys, methods, and getters are unsupported.",
+          );
+        output.set(name, { module, node: property.value });
+      }
+    }
+    return output;
+  });
+  const value = Effect.fn("Routes.staticValue")(function* (
+    input: SourceExpression,
+    field: string,
+    trail: ReadonlySet<string> = new Set(),
+  ): Effect.fn.Return<StaticValue, InvalidRouteSource> {
+    const { module, node } = yield* dereference(input, field, trail);
+    const key = `${module.path}:${node.start}`;
+    if (trail.has(key) || trail.size > 96)
+      return yield* sourceError(module, node, field, "Cyclic or excessively deep configuration.");
+    const next = new Set([...trail, key]);
+    if (
+      node.type === "Literal" &&
+      (node.value === null ||
+        Predicate.isString(node.value) ||
+        Predicate.isNumber(node.value) ||
+        Predicate.isBoolean(node.value))
+    )
+      return node.value;
+    if (node.type === "TemplateLiteral" && node.expressions.length === 0)
+      return node.quasis[0]?.value.cooked ?? "";
+    if (
+      node.type === "UnaryExpression" &&
+      node.operator === "-" &&
+      node.argument.type === "Literal" &&
+      Predicate.isNumber(node.argument.value)
+    )
+      return -node.argument.value;
+    if (node.type === "ArrayExpression") {
+      const output: StaticValue[] = [];
+      for (const element of node.elements) {
+        if (element == null || element.type === "SpreadElement")
+          return yield* sourceError(
+            module,
+            node,
+            field,
+            "Array holes and spreads are unsupported.",
+          );
+        output.push(yield* value({ module, node: element }, field, next));
+      }
+      return output;
+    }
+    if (node.type === "ObjectExpression") {
+      const output: [string, StaticValue][] = [];
+      for (const [name, expression] of yield* properties({ module, node }, field))
+        output.push([name, yield* value(expression, `${field}.${name}`, next)]);
+      return Object.fromEntries(output);
+    }
+    return yield* sourceError(
+      module,
+      node,
+      field,
+      `Unsupported ${node.type}; configuration is never executed.`,
+    );
+  });
+  const descriptor = Effect.fn("Routes.urlDescriptor")(function* (
+    input: SourceExpression,
+    field: string,
+    depth = 0,
+  ): Effect.fn.Return<UrlValueDescriptor, InvalidRouteSource> {
+    const { module, node } = yield* dereference(input, field);
+    if (depth > 32) return yield* sourceError(module, node, field, "URL definition is too deep.");
+    if (
+      node.type !== "CallExpression" ||
+      node.optional ||
+      node.typeArguments != null ||
+      node.callee.type !== "MemberExpression" ||
+      node.callee.computed ||
+      node.callee.optional ||
+      node.callee.property.type !== "Identifier"
+    )
+      return yield* sourceError(module, node, field, "Expected a supported values validator.");
+    const method = node.callee.property.name;
+    const args: SourceExpression[] = [];
+    for (const argument of node.arguments) {
+      if (argument.type === "SpreadElement")
+        return yield* sourceError(
+          module,
+          argument,
+          field,
+          "Validator argument spreads are unsupported.",
+        );
+      args.push({ module, node: argument });
+    }
+    let output: StaticValue;
+    if (method === "default") {
+      if (args.length !== 1)
+        return yield* sourceError(module, node, field, "default requires one value.");
+      output = {
+        type: "default",
+        value: yield* descriptor({ module, node: node.callee.object }, field, depth + 1),
+        default: yield* value(args[0]!, field),
+      };
+    } else {
+      if (
+        node.callee.object.type !== "Identifier" ||
+        !(yield* helper(module, node.callee.object.name, "values"))
+      )
+        return yield* sourceError(
+          module,
+          node,
+          field,
+          "Use values imported from _generated/client.",
+        );
+      if (["string", "number", "integer", "boolean"].includes(method) && args.length === 0)
+        output = { type: method };
+      else if (method === "id" && args.length === 1)
+        output = { type: method, table: yield* value(args[0]!, field) };
+      else if (method === "literal" && args.length === 1)
+        output = { type: method, value: yield* value(args[0]!, field) };
+      else if (method === "literals" && args.length > 0)
+        output = { type: method, values: yield* Effect.forEach(args, (arg) => value(arg, field)) };
+      else if ((method === "array" || method === "optional") && args.length === 1)
+        output = { type: method, value: yield* descriptor(args[0]!, field, depth + 1) };
+      else
+        return yield* sourceError(
+          module,
+          node,
+          field,
+          `Unsupported URL validator '${method}' or argument count.`,
+        );
+    }
+    return yield* Schema.decodeUnknownEffect(UrlValueDescriptor)(output).pipe(
+      Effect.mapError((error) =>
+        sourceError(module, node, field, `Invalid ${method} URL descriptor: ${String(error)}`),
+      ),
+    );
+  });
+  const extract = Effect.fn("Routes.extractModule")(function* (
+    file: string,
+    kind: "route" | "layout",
+  ) {
+    const module = yield* load(file);
+    const defaults = module.program.body.filter((node) => node.type === "ExportDefaultDeclaration");
+    const call = defaults[0]?.declaration;
+    if (
+      defaults.length !== 1 ||
+      call?.type !== "CallExpression" ||
+      call.optional ||
+      call.typeArguments != null ||
+      call.callee.type !== "Identifier" ||
+      !(yield* helper(module, call.callee.name, kind)) ||
+      call.arguments.length !== 1 ||
+      call.arguments[0] === undefined ||
+      call.arguments[0].type === "SpreadElement" ||
+      unwrap(call.arguments[0]).type !== "ObjectExpression"
+    )
+      return yield* sourceError(
+        module,
+        call ?? module.program,
+        "default",
+        `Expected one direct default ${kind}({...}) call imported from _generated/client.`,
+      );
+    const registrations: Node[] = [];
+    walk(module.program, (node) => {
+      if (node.type === "CallExpression" && node !== call) registrations.push(node);
+    });
+    for (const registration of registrations) {
+      if (
+        registration.type === "CallExpression" &&
+        registration.callee.type === "Identifier" &&
+        ((yield* helper(module, registration.callee.name, "route")) ||
+          (yield* helper(module, registration.callee.name, "layout")))
+      )
+        return yield* sourceError(
+          module,
+          registration,
+          "default",
+          "A source module cannot register additional routes or layouts.",
+        );
+    }
+    const fields = yield* properties({ module, node: call.arguments[0] }, kind);
+    const allowed =
+      kind === "route"
+        ? ["params", "searchParams", "title", "meta", "component", "error", "invalid"]
+        : ["title", "titleTemplate", "meta", "component", "error", "invalid", "notFound"];
+    for (const [name, expression] of fields)
+      if (!allowed.includes(name))
+        return yield* sourceError(
+          expression.module,
+          expression.node,
+          name,
+          `Unsupported ${kind} field.`,
+        );
+    if (!fields.has("component"))
+      return yield* sourceError(module, call, "component", "A component is required.");
+    const metadata: [string, StaticValue][] = [];
+    for (const name of ["title", "titleTemplate", "meta"]) {
+      const expression = fields.get(name);
+      if (expression === undefined) continue;
+      const extracted = yield* value(expression, name);
+      const validate =
+        name === "meta"
+          ? Schema.decodeUnknownEffect(StaticMetadata.fields.meta)(extracted).pipe(Effect.asVoid)
+          : name === "titleTemplate"
+            ? Schema.decodeUnknownEffect(LayoutMetadata.fields.titleTemplate)(extracted).pipe(
+                Effect.asVoid,
+              )
+            : Schema.decodeUnknownEffect(StaticMetadata.fields.title)(extracted).pipe(
+                Effect.asVoid,
+              );
+      yield* validate.pipe(
+        Effect.mapError((error) =>
+          sourceError(expression.module, expression.node, name, String(error)),
+        ),
+      );
+      metadata.push([name, extracted]);
+    }
+    const decodedMetadata = yield* Schema.decodeUnknownEffect(
+      kind === "route" ? StaticMetadata : LayoutMetadata,
+    )(Object.fromEntries(metadata)).pipe(
+      Effect.mapError((error) => sourceError(module, call, "metadata", String(error))),
+    );
+    const urls = new Map<
+      string,
+      ReadonlyArray<{ readonly name: string; readonly value: UrlValueDescriptor }>
+    >();
+    for (const name of ["params", "searchParams"]) {
+      const expression = fields.get(name);
+      if (expression === undefined) continue;
+      const entries: { name: string; value: UrlValueDescriptor }[] = [];
+      for (const [key, validator] of yield* properties(expression, name))
+        entries.push({ name: key, value: yield* descriptor(validator, `${name}.${key}`) });
+      urls.set(
+        name,
+        entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0)),
+      );
+    }
+    return {
+      module,
+      metadata: decodedMetadata,
+      params: urls.get("params"),
+      searchParams: urls.get("searchParams") ?? [],
+      boundaries: {
+        error: fields.has("error"),
+        invalid: fields.has("invalid"),
+        notFound: fields.has("notFound"),
+      },
+    };
+  });
+  return { extract, dependencies };
+});