tegami 0.0.0 → 0.1.0-beta.0

package/dist/index-Bhh2dJZp.d.ts

@@ -0,0 +1,460 @@
+import { TomlTable } from "smol-toml";
+import z$1, { z } from "zod";
+
+//#region src/utils/semver.d.ts
+type BumpType = "major" | "minor" | "patch";
+//#endregion
+//#region src/graph.d.ts
+/** Package discovered in the workspace. */
+declare abstract class WorkspacePackage {
+  abstract readonly name: string;
+  abstract readonly path: string;
+  abstract readonly manager: string;
+  abstract readonly version: string;
+  get id(): string;
+  private opts;
+  /** note: this will only be available after package graph is resolved */
+  getPackageOptions(): PackageOptions;
+  setPackageOptions(options: PackageOptions): void;
+  /** create an empty draft plan. */
+  onPlan(_context: TegamiContext): PackagePlan;
+}
+interface PackageGroup {
+  name: string;
+  options: GroupOptions;
+  packages: WorkspacePackage[];
+}
+/** Dependency graph for discovered workspace packages. */
+declare class PackageGraph {
+  private readonly packages;
+  private readonly groups;
+  constructor(packages?: WorkspacePackage[]);
+  getPackages(): WorkspacePackage[];
+  /** Get a package by exact id. */
+  get(id: string): WorkspacePackage | undefined;
+  /** Get packages by id, `group:name`, or every package matching a name. */
+  getByName(nameOrId: string): WorkspacePackage[];
+  /** scan package into graph, if the package id already exists, replace the existing one in graph */
+  add(pkg: WorkspacePackage): void;
+  delete(id: string): void;
+  getPackageGroup(pkgId: string): PackageGroup | undefined;
+  getGroups(): PackageGroup[];
+  getGroup(name: string): PackageGroup | undefined;
+  registerGroup(name: string, options: GroupOptions): PackageGroup;
+  addGroupMember(groupId: string, id: string): void;
+  removeGroupMember(group: string, id: string): void;
+  unregisterGroup(name: string): void;
+}
+//#endregion
+//#region src/changelog/parse.d.ts
+interface ChangelogEntry {
+  id: string;
+  /** file name like `my-change.md` */
+  filename: string;
+  subject?: string;
+  packages: Set<string>;
+  type: BumpType;
+  title: string;
+  content: string;
+}
+//#endregion
+//#region src/plans/draft.d.ts
+interface PackagePlan {
+  type?: BumpType;
+  bumpReasons?: Set<string>;
+  changelogs?: ChangelogEntry[];
+  prerelease?: string;
+  publish?: boolean;
+  npm?: {
+    /** npm dist-tag used when publishing. */distTag?: string;
+  };
+  /** get the bumped version of a package */
+  bumpVersion: (pkg: WorkspacePackage) => string;
+}
+declare class DraftPlan {
+  #private;
+  private readonly context;
+  private readonly packages;
+  private readonly changelogs;
+  private readonly policies;
+  constructor(context: TegamiContext);
+  getPackagePlans(): Map<string, PackagePlan>;
+  getPackagePlan(id: string): PackagePlan | undefined;
+  bumpPackage(pkg: WorkspacePackage, {
+    type,
+    reason
+  }: {
+    type: BumpType;
+    reason?: string;
+  }): PackagePlan;
+  hasPending(): boolean;
+  getChangelogs(): ChangelogEntry[];
+  getChangelog(id: string): ChangelogEntry | undefined;
+  addChangelog(entry: ChangelogEntry): void;
+  deleteChangelog(id: string): boolean;
+  private initPackagePlan;
+  /** Apply the publish plan: update package versions, write the plan file, and consume changelog files. */
+  applyPlan(): Promise<void>;
+  addPolicy(policy: PlanPolicy): void;
+  removePolicy(policy: PlanPolicy): void;
+  canApply(): boolean;
+  private appendChangelog;
+  /** {@link applyPlan} but for `await using` syntax */
+  [Symbol.asyncDispose](): Promise<void>;
+}
+interface PlanPolicy {
+  id: string;
+  onUpdate?: (this: DraftPlan, opts: {
+    plan: PackagePlan;
+    pkg: WorkspacePackage;
+  }) => void;
+}
+type CleanupResult = {
+  state: "removed";
+} | {
+  state: "skipped";
+  reason: "missing" | "pending";
+};
+//#endregion
+//#region src/plans/store.d.ts
+declare const packagePlanStoreSchema: z$1.ZodObject<{
+  type: z$1.ZodOptional<z$1.ZodEnum<{
+    major: "major";
+    minor: "minor";
+    patch: "patch";
+  }>>;
+  changelogIds: z$1.ZodOptional<z$1.ZodArray<z$1.ZodString>>;
+  bumpReasons: z$1.ZodOptional<z$1.ZodArray<z$1.ZodString>>;
+  npm: z$1.ZodOptional<z$1.ZodObject<{
+    distTag: z$1.ZodOptional<z$1.ZodString>;
+  }, z$1.core.$strip>>;
+  publish: z$1.ZodBoolean;
+}, z$1.core.$strip>;
+/** the persisted plan data for actual publishing */
+declare const planStoreSchema: z$1.ZodCodec<z$1.ZodString, z$1.ZodObject<{
+  id: z$1.ZodString;
+  createdAt: z$1.ZodISODateTime;
+  version: z$1.ZodDefault<z$1.ZodLiteral<"0.0.0">>;
+  changelogs: z$1.ZodRecord<z$1.ZodString, z$1.ZodObject<{
+    filename: z$1.ZodString;
+    subject: z$1.ZodOptional<z$1.ZodString>;
+    packages: z$1.ZodArray<z$1.ZodString>;
+    type: z$1.ZodEnum<{
+      major: "major";
+      minor: "minor";
+      patch: "patch";
+    }>;
+    title: z$1.ZodString;
+    content: z$1.ZodString;
+  }, z$1.core.$strip>>;
+  packages: z$1.ZodRecord<z$1.ZodString, z$1.ZodObject<{
+    type: z$1.ZodOptional<z$1.ZodEnum<{
+      major: "major";
+      minor: "minor";
+      patch: "patch";
+    }>>;
+    changelogIds: z$1.ZodOptional<z$1.ZodArray<z$1.ZodString>>;
+    bumpReasons: z$1.ZodOptional<z$1.ZodArray<z$1.ZodString>>;
+    npm: z$1.ZodOptional<z$1.ZodObject<{
+      distTag: z$1.ZodOptional<z$1.ZodString>;
+    }, z$1.core.$strip>>;
+    publish: z$1.ZodBoolean;
+  }, z$1.core.$strip>>;
+}, z$1.core.$strip>>;
+type PlanStore = z$1.output<typeof planStoreSchema>;
+type PackagePlanStore = z$1.output<typeof packagePlanStoreSchema>;
+//#endregion
+//#region src/publish.d.ts
+interface PublishOptions {
+  /** Validate the publish plan without publishing packages, creating tags, or running release plugins. */
+  dryRun?: boolean;
+}
+type PublishResult = {
+  state: "created";
+  packages: PackagePublishResult[]; /** the persisted plan object. This is not a public API, can be changed without notice */
+  _rawPlan: PlanStore;
+} | {
+  state: "failed";
+  error?: string;
+  packages: PackagePublishResult[]; /** the persisted plan object. This is not a public API, can be changed without notice */
+  _rawPlan: PlanStore;
+} | {
+  state: "skipped";
+};
+type PackagePublishResult = ({
+  state: "failed";
+  error?: string;
+} | {
+  state: "success";
+}) & {
+  id: string;
+  name: string;
+  version: string;
+  npm?: {
+    distTag?: string;
+  }; /** added by the `git` plugin */
+  gitTag?: string;
+  changelogs: ChangelogEntry[];
+};
+//#endregion
+//#region src/schemas.d.ts
+declare const packageManifestSchema: z.ZodObject<{
+  name: z.ZodString;
+  version: z.ZodOptional<z.ZodString>;
+  private: z.ZodOptional<z.ZodBoolean>;
+  publishConfig: z.ZodOptional<z.ZodObject<{
+    access: z.ZodOptional<z.ZodEnum<{
+      public: "public";
+      restricted: "restricted";
+    }>>;
+    registry: z.ZodOptional<z.ZodString>;
+    tag: z.ZodOptional<z.ZodString>;
+  }, z.core.$loose>>;
+  workspaces: z.ZodOptional<z.ZodArray<z.ZodString>>;
+  dependencies: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+  devDependencies: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+  peerDependencies: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+  optionalDependencies: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, z.core.$loose>;
+type PackageManifest = z.infer<typeof packageManifestSchema>;
+//#endregion
+//#region src/providers/npm.d.ts
+declare const DEP_FIELDS$1: readonly ["dependencies", "devDependencies", "peerDependencies", "optionalDependencies"];
+declare class NpmPackage extends WorkspacePackage {
+  readonly path: string;
+  readonly manifest: PackageManifest;
+  readonly manager = "npm";
+  constructor(path: string, manifest: PackageManifest);
+  get name(): string;
+  get version(): string;
+  write(): Promise<void>;
+  onPlan(context: TegamiContext): PackagePlan;
+}
+type NpmClient = "npm" | "pnpm";
+declare class NpmRegistryClient implements RegistryClient {
+  #private;
+  private readonly cwd;
+  private readonly client;
+  readonly id = "npm";
+  constructor(cwd: string, client: NpmClient, _graph: PackageGraph);
+  supports(pkg: WorkspacePackage): boolean;
+  isPackagePublished(pkg: NpmPackage): Promise<boolean>;
+  publish(pkg: NpmPackage, {
+    packageStore
+  }: {
+    store: PlanStore;
+    packageStore: PackagePlanStore;
+  }): Promise<void>;
+}
+type DependencySpec = {
+  protocol: "npm";
+  alias: string;
+  range: string;
+  linked?: WorkspacePackage;
+} | {
+  protocol?: "workspace";
+  range: string;
+  linked?: WorkspacePackage;
+};
+interface NpmPluginOptions {
+  /** Package manager command used for npm registry operations. */
+  client?: NpmClient;
+  /**
+   * Decide how to bump the dependents of a bumped package.
+   */
+  bumpDep?: (opts: {
+    kind: (typeof DEP_FIELDS$1)[number];
+    name: string;
+    spec: DependencySpec;
+  }) => BumpType | false;
+  /**
+   * What to do when a workspace dependency's version has gone beyond peer dependency constraints:
+   *
+   * - `set` (default): set to the current version (won't preserve prefix).
+   * - `error`: throw error.
+   * - `ignore`: do nothing.
+   *
+   * Note: `workspace:` protocols are not included.
+   */
+  onBreakPeerDep?: "set" | "error" | "ignore";
+}
+declare function npm({
+  client: defaultClient,
+  onBreakPeerDep,
+  bumpDep: getBumpDepType
+}?: NpmPluginOptions): TegamiPlugin;
+//#endregion
+//#region src/providers/cargo.d.ts
+declare const DEP_FIELDS: readonly ["dependencies", "dev-dependencies", "build-dependencies"];
+declare class CargoPackage extends WorkspacePackage {
+  readonly path: string;
+  readonly manifest: TomlTable;
+  private readonly workspaceManifest?;
+  readonly manager = "cargo";
+  constructor(path: string, manifest: TomlTable, workspaceManifest?: TomlTable | undefined);
+  get name(): string;
+  get version(): string;
+  onPlan(context: TegamiContext): PackagePlan;
+  write(): Promise<void>;
+  get packageInfo(): TomlTable;
+  private get workspaceVersion();
+}
+declare class CargoRegistryClient implements RegistryClient {
+  #private;
+  readonly id = "cargo";
+  constructor(_graph: PackageGraph);
+  supports(pkg: WorkspacePackage): boolean;
+  isPackagePublished(pkg: CargoPackage): Promise<boolean>;
+  publish(pkg: CargoPackage): Promise<void>;
+}
+interface CargoPluginOptions {
+  bumpDep?: (opts: {
+    kind: (typeof DEP_FIELDS)[number];
+    name: string;
+    version: string;
+  }) => BumpType | false;
+}
+declare function cargo({
+  bumpDep: getBumpDepType
+}?: CargoPluginOptions): TegamiPlugin;
+//#endregion
+//#region src/types.d.ts
+/** Generates changelog content for a package release. */
+interface LogGenerator {
+  generate(this: TegamiContext, opts: {
+    packageId: string;
+    packageName: string;
+    version: string;
+    changelogs: ChangelogEntry[];
+    plan: PackagePlan;
+    _draft: DraftPlan;
+  }): string | Promise<string>;
+}
+interface TegamiOptions<Groups extends string = string> {
+  /** Workspace root. Defaults to the current working directory. */
+  cwd?: string;
+  /** Directory containing pending changelog markdown files. */
+  changelogDir?: string;
+  /** Path to the publish plan file. */
+  planPath?: string;
+  /** Changelog generator used when applying a publish plan. */
+  generator?: LogGenerator;
+  /** Per-package release and publish options keyed by package name. */
+  packages?: Record<string, PackageOptions<NoInfer<Groups>>>;
+  plugins?: TegamiPluginOption[];
+  groups?: Record<Groups, GroupOptions>;
+  /** Package names, ids, or regex patterns to exclude from the dependency graph. */
+  ignore?: (string | RegExp)[];
+  npm?: NpmPluginOptions;
+  cargo?: CargoPluginOptions;
+}
+interface GroupOptions {
+  /** Prerelease identifier appended to bumped versions (e.g. `alpha` → `1.1.0-alpha.0`). */
+  prerelease?: string;
+  /** all member packages will share the same type of version bump (e.g. when one package is bumped by a minor, other member packages will also be bumped by a minor) */
+  syncBump?: boolean;
+  /** when multiple packages in the group are published, only one git tag will be created (as well as GitHub release) */
+  syncGitTag?: boolean;
+}
+interface PackageOptions<Group extends string = string> {
+  /** Prerelease identifier appended to bumped versions (e.g. `alpha` → `1.1.0-alpha.0`). */
+  prerelease?: string;
+  /** Set to false to keep this package out of npm publishing. */
+  publish?: boolean;
+  /** the group of this package, ignored if the group doesn't exist */
+  group?: Group;
+  /** npm-specific options. */
+  npm?: {
+    /** npm dist-tag used when publishing. */distTag?: string;
+  };
+}
+type TegamiPluginOption = TegamiPlugin | TegamiPluginOption[];
+interface TegamiPlugin {
+  name: string;
+  enforce?: "pre" | "default" | "post";
+  /** when Tegami initializes */
+  init?(this: TegamiContext): Awaitable<void>;
+  /** Resolve workspace packages and dependency metadata into the shared graph. */
+  resolve?(this: TegamiContext): Awaitable<void>;
+  /** Register registry clients used to handle packages for different package managers. */
+  createRegistryClient?(this: TegamiContext): Awaitable<RegistryClient | RegistryClient[] | void | undefined>;
+  /** Called when Tegami creates an empty draft plan. */
+  initPlan?(this: TegamiContext, plan: DraftPlan): Awaitable<DraftPlan | void | undefined>;
+  /** Called when Tegami applies the draft plan. */
+  applyPlan?(this: TegamiContext, draft: DraftPlan): Awaitable<void>;
+  /** resolve the plan status, crucial to check if the plan is finished successfully, or needs retries */
+  resolvePlanStatus?(this: TegamiContext, status: PublishPlanStatus, env: {
+    plan: PlanStore;
+  }): Awaitable<PublishPlanStatus>;
+  /** Called after publishing finishes. */
+  afterPublish?(this: TegamiContext & {
+    publishOptions: PublishOptions;
+  }, result: PublishResult): Awaitable<PublishResult | void | undefined>;
+  /** CLI lifecycle hooks. */
+  cli?: {
+    /** Called once before a CLI command runs. */init?(this: TegamiContext): Awaitable<void>; /** Called after `tegami version` returns a draft plan. */
+    publishPlanCreated?(this: TegamiContext, draft: DraftPlan): Awaitable<void>; /** Called after `tegami version` applies a publish plan. */
+    publishPlanApplied?(this: TegamiContext, draft: DraftPlan): Awaitable<void>;
+  };
+}
+type Awaitable<T> = T | Promise<T>;
+interface PublishPlanStatus {
+  state: "pending" | "success" | "missing";
+}
+interface RegistryClient {
+  id: string;
+  supports(pkg: WorkspacePackage): boolean;
+  isPackagePublished(pkg: WorkspacePackage): Promise<boolean>;
+  publish(pkg: WorkspacePackage, env: {
+    store: PlanStore;
+    packageStore: PackagePlanStore;
+  }): Promise<void>;
+}
+//#endregion
+//#region src/context.d.ts
+interface TegamiContext {
+  cwd: string;
+  changelogDir: string;
+  planPath: string;
+  options: TegamiOptions;
+  plugins: TegamiPlugin[];
+  graph: PackageGraph;
+  /** error if doesn't exist */
+  getRegistryClient(pkgOrId: WorkspacePackage | string): RegistryClient;
+}
+//#endregion
+//#region src/changelog/create.d.ts
+interface CreateChangelogOptions {
+  /** Start revision. Defaults to the latest reachable git tag, or all history if none exists. */
+  from?: string;
+  /** End revision. Defaults to HEAD. */
+  to?: string;
+}
+interface CreatedChangelog {
+  filename: string;
+  path: string;
+  packages: string[];
+  changes: number;
+}
+//#endregion
+//#region src/index.d.ts
+interface Tegami {
+  /** Create pending changelog files from git commit history. */
+  generateChangelog(options?: CreateChangelogOptions): Promise<CreatedChangelog[]>;
+  /** Build a draft from pending changelog files. */
+  draft(): Promise<DraftPlan>;
+  /** Publish the current publish plan. */
+  publish(options?: PublishOptions): Promise<PublishResult>;
+  /** Remove the publish plan file after it has finished successfully. */
+  cleanup(): Promise<CleanupResult>;
+  /** Internal APIs, do not use it unless you know what you are doing */
+  _internal: {
+    context(): Promise<TegamiContext>;
+    graph(): Promise<PackageGraph>;
+    options: TegamiOptions;
+  };
+}
+/** Create a Tegami project handle. */
+declare function tegami<const Groups extends string = string>(options?: TegamiOptions<Groups>): Tegami;
+//#endregion
+export { PublishResult as C, PackageGroup as D, PackageGraph as E, WorkspacePackage as O, PublishOptions as S, PackagePlan as T, NpmPackage as _, Awaitable as a, npm as b, PackageOptions as c, TegamiPlugin as d, TegamiPluginOption as f, cargo as g, CargoRegistryClient as h, CreatedChangelog as i, RegistryClient as l, CargoPluginOptions as m, tegami as n, GroupOptions as o, CargoPackage as p, CreateChangelogOptions as r, LogGenerator as s, Tegami as t, TegamiOptions as u, NpmPluginOptions as v, DraftPlan as w, PackagePublishResult as x, NpmRegistryClient as y };

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+import { C as PublishResult, D as PackageGroup, E as PackageGraph, O as WorkspacePackage, S as PublishOptions, T as PackagePlan, c as PackageOptions, d as TegamiPlugin, f as TegamiPluginOption, i as CreatedChangelog, l as RegistryClient, n as tegami, o as GroupOptions, r as CreateChangelogOptions, s as LogGenerator, t as Tegami, u as TegamiOptions, w as DraftPlan, x as PackagePublishResult } from "./index-Bhh2dJZp.js";
+export { type CreateChangelogOptions, type CreatedChangelog, type DraftPlan, type GroupOptions, type LogGenerator, type PackageGraph, type PackageGroup, type PackageOptions, type PackagePlan, type PackagePublishResult, type PublishOptions, type PublishResult, type RegistryClient, Tegami, type TegamiOptions, type TegamiPlugin, type TegamiPluginOption, type WorkspacePackage, tegami };