Writing an extension

 @Annotate("example.deprecated", {...})  ──┐
 .annotate("example.deprecated", {...})  ──┼─► frontend ─► Annotation ─► interpreter ─► IR node + ExtensionOf edge
                                           │                                              │
 effx.config.ts ── extensions: [ext] ──────┘                       analysis ◄─────────────┤
                                                                   generator ◄────────────┘

{
  "name": "@effx-examples/extension-openapi-tags",
  "version": "0.0.0",
  "private": true,
  "type": "module",
  "scripts": {
    "effx:check": "bun ../../scripts/effx.ts check",
    "effx:build": "bun ../../scripts/effx.ts build"
  },
  "dependencies": {
    "@effx/cli": "workspace:*",
    "@effx/compiler": "workspace:*",
    "@effx/ir": "workspace:*",
    "@effx/runtime": "workspace:*",
    "effect": "4.0.0"
  },
  "devDependencies": {
    "@effect/platform-bun": "4.0.0",
    "@effect/vitest": "4.0.0",
    "@effx/frontend-ts": "workspace:*",
    "vitest": "5.0.3"
  }
}

import { Effect, Option, Schema } from "effect";
import {
  Contribution,
  CompilerFault,
  CoreDiagnostics,
  type Extension,
  type GeneratedFile,
} from "@effx/compiler";
import { IRGraph, Node, StableId } from "@effx/ir";

const name = "example.deprecated";

const dataSchema = Schema.Struct({ reason: Schema.String });

const argsSchema = Schema.Tuple([dataSchema]);

const isData = Schema.is(dataSchema);

const stringJson = Schema.fromJsonString(Schema.String);

/** Static annotation arguments are decoded before contributing semantic IR. */
const interpretDeprecated: Extension["interpreters"][string] = (annotation, declaration, ctx) => {
  const parsed = Schema.decodeUnknownOption(argsSchema)(annotation.args);

  if (Option.isNone(parsed))
    return Contribution.diagnostics(
      CoreDiagnostics["EFFX2902"].emit({ _tag: "Arguments", subject: declaration.id }),
    );

  if (Option.isNone(ctx.operationId))
    return Contribution.diagnostics(
      CoreDiagnostics["EFFX2902"].emit({ _tag: "Operation", subject: declaration.id }),
    );

  const operationId = ctx.operationId.value;
  const id = StableId.make("ext", `${StableId.nameOf(operationId)}/deprecated`);

  const node = Node.make({
    _tag: "Extension",
    id,
    extension: name,
    tag: "Deprecated",
    data: { reason: parsed.value[0].reason },
  });

  return Contribution.make([node], [{ kind: "ExtensionOf", from: id, to: operationId }]);
};

/** Warning only: compilation may still generate the IR-derived declaration. */
const warnDeprecated: Extension["analyses"][number] = (ir, index) =>
  ir.nodes.flatMap((node) => {
    if (node._tag !== "Extension" || node.extension !== name || !isData(node.data)) return [];
    const reason = node.data.reason;

    return IRGraph.outgoing(index, node.id, "ExtensionOf").map((edge) =>
      CoreDiagnostics["EFFX2901"].emit({ operation: StableId.nameOf(edge.to), reason }),
    );
  });

/** Keep authored text inside a single JSDoc line even if the IR contains a newline or closing comment. */
const jsdocText = (reason: string): string => reason.replace(/\s+/gu, " ").replace(/\*\//gu, "* /");

/** Generated bytes are a pure projection of IR and its index, never of the application module. */
const generateDeprecated: Extension["generators"][number] = (ir, index) =>
  Effect.gen(function* () {
    const lines: Array<string> = [];
    let ordinal = 0;

    for (const node of ir.nodes) {
      if (node._tag !== "Extension" || node.extension !== name || !isData(node.data)) continue;

      for (const edge of IRGraph.outgoing(index, node.id, "ExtensionOf")) {
        const owner = IRGraph.nodeOf(index, edge.to);

        if (Option.isNone(owner) || owner.value._tag !== "Operation") continue;

        const encoded = yield* Schema.encodeEffect(stringJson)(owner.value.name).pipe(
          Effect.mapError(
            (cause) =>
              new CompilerFault({
                stage: "generate",
                message: "cannot encode deprecated operation name",
                cause,
              }),
          ),
        );

        lines.push(
          `/** @deprecated ${jsdocText(node.data.reason)} */`,
          `export const deprecated_${ordinal++} = ${encoded} as const;`,
        );
      }
    }

    const files: ReadonlyArray<GeneratedFile> =
      lines.length === 0 ? [] : [{ path: "deprecated.ts", contents: lines.join("\n") + "\n" }];

    return files;
  });

/** No application import: this module is safe to evaluate as a selected config dependency. */
export const deprecatedExtension: Extension = {
  name,
  interpreters: { [name]: interpretDeprecated },
  analyses: [warnDeprecated],
  generators: [generateDeprecated],
};

import { defineConfig } from "@effx/cli/config";
import { deprecatedExtension } from "./deprecated-extension.ts";

// Only the selected config and its extension are evaluated by the CLI.
// Neither imports src/operations.ts or its handler.
export default defineConfig({
  project: "tsconfig.json",
  extensions: [deprecatedExtension],
  generators: { http: false, rpc: false, cli: false, client: false, foldkit: false },
});

cd examples/extension-openapi-tags
bun ../../scripts/effx.ts check --project tsconfig.json

  EFFX0001 warning  effx analyses with TypeScript 6.0.3 but the project pins typescript 7.0.2; tsc/tsgo remains the authoritative type gate
  EFFX2204 warning  Example.Lookup: no schema-addressable errors inferred; boundary will expose none
  EFFX2901 warning  Example.Lookup is deprecated: Use Example.Find instead
0 error(s), 3 warning(s), 0 info

/** @deprecated Use Example.Find instead */
export const deprecated_0 = "Example.Lookup" as const;

/**
 * @title Declaring an annotation
 *
 * `Annotation.define` declares a user annotation once: its name, where it may attach and the
 * argument shape. The derived decorator and builder argument are typed from `args`, and the
 * compiler lowers and decodes the same description. Keep this file a leaf module: it may
 * import only `effect` and `@effx/runtime` (spec 0020, EFFX1306), so loading it never loads
 * application code.
 */
import { A, Annotation } from "@effx/runtime";
import { Context } from "effect";

// An Effect annotation key: the generated HttpApi endpoint carries the value, typed by `tsc`, and a
// hand-written middleware reads it back with `Context.getOption(endpoint.annotations, RateLimitPolicy)`.
// The literal id is what a static lift matches (spec 0020 section 4).
export class RateLimitPolicy extends Context.Service<
  RateLimitPolicy,
  { readonly perMinute: number; readonly burst?: number }
>()("app/RateLimit") {}

export const RateLimit = Annotation.define({
  // Namespaced and unique across all extensions (EFFX1302 on a clash).
  name: "app.RateLimit",
  // v1 user annotations attach to operations only (spec 0020 section 0.4).
  target: "operation",
  // `A.*` is the closed set of argument shapes the TypeScript frontend can read from source
  // without running your code. `tsc` checks the shape at the use site; value constraints such as a
  // minimum are decoded by the compiler (EFFX1102).
  args: { perMinute: A.int, burst: A.optional(A.int) },
  // The compiler rejects a second `@RateLimit` on one operation.
  cardinality: "one",
  // Optional default writer: generated endpoints get `.annotate(RateLimit.effect.key, { ... })`.
  // `tsc` checks the written value against the key's shape in the generated file.
  effect: { target: "endpoint", key: RateLimitPolicy },
});

/**
 * @title Giving a declared annotation meaning
 *
 * `implement` is the compiler half. With no `read` it records the arguments as a declarative
 * `Extension` node `ext:<name>/<operation>` linked by `ExtensionOf`; analyses and generators add
 * checks and files. `extension` bundles implementations into an ordinary `Extension`, the value
 * you list in `effx.config.ts`.
 *
 * An optional `lift.recognize` is a pure, synchronous inverse of a source `.annotate` site. It reads
 * the frontend's neutral Term, returns typed `ReadArgs<D>`, and reports a non-match with a closed error;
 * the core validates the result with the definition's own cached plan codec. Pass the selected
 * extension registry explicitly to `lift(model, input, registry)`.
 */
import {
  CoreDiagnostics,
  type DefinitionLift,
  type Diagnostic,
  dataOf,
  extension,
  implement,
} from "@effx/compiler";
import { IRGraph } from "@effx/ir";
import { Option, Predicate, Result } from "effect";
import { RateLimit } from "./03_define-annotation.ts";

const recognizeRateLimit: DefinitionLift<typeof RateLimit>["recognize"] = (site) => {
  if (site.value._tag !== "Obj")
    return Result.fail({ _tag: "Unsupported", construct: "a literal RateLimit object" });

  const entries = site.value.entries;
  const count = (name: string) => entries.filter((entry) => entry.key === name).length;

  const integer = (name: string) => {
    const value = entries.find((entry) => entry.key === name)?.value;

    return value?._tag === "Lit" && Predicate.isNumber(value.json) && Number.isInteger(value.json)
      ? value.json
      : undefined;
  };

  const perMinute = integer("perMinute");
  const burst = integer("burst");
  const burstCount = count("burst");

  if (
    perMinute === undefined ||
    count("perMinute") !== 1 ||
    burstCount > 1 ||
    (burstCount === 1 && burst === undefined) ||
    entries.some((entry) => entry.key !== "perMinute" && entry.key !== "burst")
  )
    return Result.fail({ _tag: "Unsupported", construct: "a literal RateLimit object" });

  const args = burst === undefined ? { perMinute } : { perMinute, burst };

  return Result.succeed([args]);
};

const rateLimit = implement(RateLimit, {
  lift: { recognize: recognizeRateLimit },
  // Analyses read the normalized IR and return diagnostics (data, not failures).
  analyze: (ir, index) =>
    ir.nodes.flatMap((node): ReadonlyArray<Diagnostic> => {
      if (node._tag !== "Operation") return [];

      // `dataOf` decodes the declarative node with the same schema the compiler derived from `args`.
      const limit = dataOf(RateLimit, ir, node.id);

      if (Option.isNone(limit)) return [];

      const [options] = limit.value;

      const exposed = IRGraph.outgoing(index, node.id, "ExposedAs").some(
        (edge) => edge.qualifier === "http",
      );

      if (!exposed) {
        return [CoreDiagnostics["EFFX9101"].emit({ subject: node.name })];
      }

      return options.perMinute > 10_000
        ? [CoreDiagnostics["EFFX9102"].emit({ subject: node.name, perMinute: options.perMinute })]
        : [];
    }),
});

// An ordinary `Extension`. List it in `effx.config.ts`: the CLI compiles with the built-ins
// followed by the config's extensions (spec 0015), and lowers `@RateLimit(...)` by the plan of
// the definition it carries (spec 0020).
export const appExtension = extension("app", [rateLimit]);