@savvy-web/silk-effects 0.6.0 → 1.0.0

package/README.md

@@ -13,6 +13,7 @@ Shared [Effect](https://effect.website/) library providing Silk Suite convention
 - Discover and resolve CLI tools globally or locally with version enforcement and caching
 - Detect versioning strategy and format git tags from changeset configuration
 - Locate config files and keep Biome schema URLs in sync across workspaces
+- Inspect a Turborepo read-only — diagnose per-package cache hits, derive the task graph and compute affected packages, all over `turbo --dry`
 
 ## Install
 
@@ -36,17 +37,21 @@ import {
 } from "@savvy-web/silk-effects";
 ```
 
-`SilkPublishability.detect` is a pure static — no layers, no Effect runtime. Pass a package name and the raw `package.json` and get back the publish targets the silk rules resolve:
+`SilkPublishability.detect` is a pure static — no layers, no Effect runtime. Pass a package name, the raw `package.json` and the bundler's resolved target binding (or `null` before the prod build has run) and get back the publish targets the silk rules resolve:
 
 ```typescript
 import { SilkPublishability } from "@savvy-web/silk-effects";
 
-const targets = SilkPublishability.detect("@my-org/my-package", {
-  private: true,
-  publishConfig: { access: "public", targets: ["npm", "github"] },
-});
-// => [PublishTarget { name: "@my-org/my-package", registry: "https://registry.npmjs.org/", ... },
-//     PublishTarget { name: "@my-org/my-package", registry: "https://npm.pkg.github.com/", ... }]
+const targets = SilkPublishability.detect(
+  "@my-org/my-package",
+  {
+    private: true,
+    publishConfig: { access: "public", targets: { npm: true, github: true } },
+  },
+  null, // pre-build: one count-accurate placeholder per declared target key
+);
+// => [PublishTarget { name: "@my-org/my-package", registry: "https://registry.npmjs.org", ... },
+//     PublishTarget { name: "@my-org/my-package", registry: "https://npm.pkg.github.com", ... }]
 ```
 
 ## Services
@@ -61,23 +66,27 @@ These services are pure logic — no filesystem or shell access needed.
 
 #### SilkPublishability
 
-Apply silk publishability rules to a raw `package.json` and resolve its publish targets. Targets are `PublishTarget` records from `workspaces-effect` with `name`, `registry`, `directory`, `access` and `provenance` fields. The static `detect`, `expandShorthand` and `resolveTargetAccess` helpers are pure; `resolveTargets` and `listPublishable` are Effects that read from disk (see below).
+Apply silk publishability rules to a raw `package.json` and the bundler's resolved target binding, and resolve the publish targets. Targets are `PublishTarget` records from `workspaces-effect` with `name`, `registry`, `directory`, `access` and `provenance` fields. The static `detect` helper is pure; `resolveTargets` and `listPublishable` are Effects that read from disk (see below), and `readTargetsBinding` reads the binding `detect` consumes.
 
-In silk mode `private: true` is the norm on workspace `package.json` files. Publishability is derived from `publishConfig`, with the `private` flag consulted only as a last-resort default.
+In silk mode `private: true` is the norm on workspace `package.json` files. Publishability is derived from `publishConfig`, with the `private` flag consulted only as a last-resort default. Publish targets are declared as the bundler's keyed `publishConfig.targets` map; the legacy array form is no longer supported.
 
 ```typescript
 import { SilkPublishability } from "@savvy-web/silk-effects";
 
-// Targets-first: one PublishTarget per surviving publishConfig.targets entry
-const targets = SilkPublishability.detect("@my-org/pkg", {
-  private: true,
-  publishConfig: { access: "public", targets: ["npm", "github"] },
-});
-// => [PublishTarget { registry: "https://registry.npmjs.org/", access: "public", ... },
-//     PublishTarget { registry: "https://npm.pkg.github.com/", access: "public", ... }]
+// Targets-first: one PublishTarget per declared publishConfig.targets key
+const targets = SilkPublishability.detect(
+  "@my-org/pkg",
+  {
+    private: true,
+    publishConfig: { access: "public", targets: { npm: true, github: true } },
+  },
+  null, // pre-build placeholder; pass the dist/prod/targets.json binding post-build
+);
+// => [PublishTarget { registry: "https://registry.npmjs.org", access: "public", ... },
+//     PublishTarget { registry: "https://npm.pkg.github.com", access: "public", ... }]
 
 // Not publishable -> empty array
-const none = SilkPublishability.detect("@my-org/internal", { private: true });
+const none = SilkPublishability.detect("@my-org/internal", { private: true }, null);
 // => []
 ```
 
@@ -379,6 +388,28 @@ const biome = yield* td.require(
 );
 ```
 
+#### TurboInspector
+
+Read-only Turborepo inspection. Every method shells out to `turbo` with `--dry=json`, so no task ever runs. `diagnoseCache(task, cwd)` reports a per-package cache HIT/MISS breakdown for a task, `taskGraph(cwd, task?)` derives the task graph and its critical path and `affected(cwd, base?)` lists the packages affected relative to `base` (default `main`). It resolves the `turbo` binary through `ToolDiscovery` and fails with a tagged error when `turbo` is missing or the directory is not a Turborepo. The service tag and its layer are exported under the `Turbo` namespace.
+
+```typescript
+import { Effect } from "effect";
+import { NodeContext } from "@effect/platform-node";
+import { Turbo, ToolDiscoveryLive } from "@savvy-web/silk-effects";
+
+const diagnosis = await Effect.runPromise(
+  Effect.gen(function* () {
+    const turbo = yield* Turbo.TurboInspector;
+    return yield* turbo.diagnoseCache("build:dev", process.cwd());
+  }).pipe(
+    Effect.provide(Turbo.TurboInspectorLive),
+    Effect.provide(ToolDiscoveryLive),
+    Effect.provide(NodeContext.layer),
+  ),
+);
+// => CacheDiagnosis: per-package HIT/MISS breakdown for the task
+```
+
 ## Documentation
 
 - [Overview](./docs/overview.md) — what the library is, its design philosophy and platform-layer model

package/_virtual/_rolldown/runtime.js

@@ -0,0 +1,18 @@
+//#region \0rolldown/runtime.js
+var __defProp = Object.defineProperty;
+var __exportAll = (all, no_symbols) => {
+	let target = {};
+	for (var name in all) {
+		__defProp(target, name, {
+			get: all[name],
+			enumerable: true
+		});
+	}
+	if (!no_symbols) {
+		__defProp(target, Symbol.toStringTag, { value: "Module" });
+	}
+	return target;
+};
+
+//#endregion
+export { __exportAll };

package/changesets/api/categories.js

@@ -0,0 +1,247 @@
+import { BREAKING_CHANGES, BUG_FIXES, BUILD_SYSTEM, CATEGORIES, CI, DEPENDENCIES, DOCUMENTATION, FEATURES, MAINTENANCE, OTHER, PERFORMANCE, REFACTORING, REVERTS, TESTS, allHeadings, fromHeading, isValidHeading, resolveCommitType } from "../categories/index.js";
+
+//#region src/changesets/api/categories.ts
+/**
+* Class-based API wrapper for section categories.
+*
+* Provides a static class interface that bridges to the underlying
+* Effect-native category functions for higher-level consumers.
+*
+* @internal
+*/
+/**
+* Static class wrapper for section category operations.
+*
+* Provides methods for resolving conventional commit types to changelog
+* section categories, validating section headings, and accessing the
+* canonical set of 13 section categories used throughout the pipeline.
+*
+* @remarks
+* This class wraps the pure functions and constants from the internal
+* `categories/` module. Each {@link SectionCategory} is defined by the
+* {@link SectionCategorySchema} Effect Schema, which provides runtime
+* validation at system boundaries. The class itself is stateless; all
+* methods and properties are `static`.
+*
+* Categories control how changelog entries are grouped and ordered.
+* Lower priority numbers appear first in the output. The 13 built-in
+* categories cover all conventional commit types plus special cases
+* like dependency updates and breaking changes.
+*
+* @example Looking up categories from commit metadata
+* ```typescript
+* import { Categories } from "\@savvy-web/changesets";
+* import type { SectionCategory } from "\@savvy-web/changesets";
+*
+* // Resolve a conventional commit type to its category
+* const feature: SectionCategory = Categories.fromCommitType("feat");
+* // feature.heading === "Features"
+* // feature.priority === 2
+*
+* // Breaking changes always win regardless of commit type
+* const breaking: SectionCategory = Categories.fromCommitType("fix", undefined, true);
+* // breaking.heading === "Breaking Changes"
+* // breaking.priority === 1
+*
+* // The special scope "deps" on "chore" maps to Dependencies
+* const deps: SectionCategory = Categories.fromCommitType("chore", "deps");
+* // deps.heading === "Dependencies"
+* ```
+*
+* @example Validating section headings
+* ```typescript
+* import { Categories } from "\@savvy-web/changesets";
+*
+* const headings: readonly string[] = Categories.allHeadings();
+* // ["Breaking Changes", "Features", "Bug Fixes", ...]
+*
+* const valid: boolean = Categories.isValidHeading("Bug Fixes");
+* // true
+*
+* const unknown: boolean = Categories.isValidHeading("Miscellaneous");
+* // false
+* ```
+*
+* @example Reverse-lookup from heading text
+* ```typescript
+* import { Categories } from "\@savvy-web/changesets";
+* import type { SectionCategory } from "\@savvy-web/changesets";
+*
+* const category: SectionCategory | undefined = Categories.fromHeading("Features");
+* if (category) {
+*   const commitTypes: readonly string[] = category.commitTypes;
+*   // ["feat"]
+* }
+* ```
+*
+* @see {@link SectionCategory} for the category shape (heading, priority, commitTypes, description)
+* @see {@link SectionCategorySchema} for the Effect Schema that validates category data
+*
+* @public
+*/
+var Categories = class {
+	constructor() {}
+	/**
+	* Breaking changes -- backward-incompatible changes (priority 1).
+	*
+	* @remarks
+	* Mapped from any commit type when the `breaking` flag is `true`.
+	* Always appears first in changelog output.
+	*/
+	static BREAKING_CHANGES = BREAKING_CHANGES;
+	/**
+	* Features -- new functionality (priority 2).
+	*
+	* @remarks
+	* Mapped from the `feat` commit type.
+	*/
+	static FEATURES = FEATURES;
+	/**
+	* Bug Fixes -- bug corrections (priority 3).
+	*
+	* @remarks
+	* Mapped from the `fix` commit type.
+	*/
+	static BUG_FIXES = BUG_FIXES;
+	/**
+	* Performance -- performance improvements (priority 4).
+	*
+	* @remarks
+	* Mapped from the `perf` commit type.
+	*/
+	static PERFORMANCE = PERFORMANCE;
+	/**
+	* Documentation -- documentation changes (priority 5).
+	*
+	* @remarks
+	* Mapped from the `docs` commit type.
+	*/
+	static DOCUMENTATION = DOCUMENTATION;
+	/**
+	* Refactoring -- code restructuring (priority 6).
+	*
+	* @remarks
+	* Mapped from the `refactor` commit type.
+	*/
+	static REFACTORING = REFACTORING;
+	/**
+	* Tests -- test additions or modifications (priority 7).
+	*
+	* @remarks
+	* Mapped from the `test` commit type.
+	*/
+	static TESTS = TESTS;
+	/**
+	* Build System -- build configuration changes (priority 8).
+	*
+	* @remarks
+	* Mapped from the `build` commit type.
+	*/
+	static BUILD_SYSTEM = BUILD_SYSTEM;
+	/**
+	* CI -- continuous integration changes (priority 9).
+	*
+	* @remarks
+	* Mapped from the `ci` commit type.
+	*/
+	static CI = CI;
+	/**
+	* Dependencies -- dependency updates (priority 10).
+	*
+	* @remarks
+	* Mapped from `chore(deps)` and similar dependency-scoped commits.
+	*/
+	static DEPENDENCIES = DEPENDENCIES;
+	/**
+	* Maintenance -- general maintenance (priority 11).
+	*
+	* @remarks
+	* Mapped from the `chore` commit type (without the `deps` scope).
+	*/
+	static MAINTENANCE = MAINTENANCE;
+	/**
+	* Reverts -- reverted changes (priority 12).
+	*
+	* @remarks
+	* Mapped from the `revert` commit type.
+	*/
+	static REVERTS = REVERTS;
+	/**
+	* Other -- uncategorized changes (priority 13).
+	*
+	* @remarks
+	* Fallback category for unrecognized commit types. Always appears
+	* last in changelog output.
+	*/
+	static OTHER = OTHER;
+	/**
+	* All 13 categories ordered by priority (ascending, 1-13).
+	*
+	* @remarks
+	* This array is frozen and sorted from highest priority (Breaking Changes)
+	* to lowest (Other). Useful for iterating over categories in display order.
+	*/
+	static ALL = CATEGORIES;
+	/**
+	* Resolve a conventional commit type to its section category.
+	*
+	* @remarks
+	* Resolution follows a precedence chain:
+	*
+	* 1. If `breaking` is `true`, always returns {@link Categories.BREAKING_CHANGES}
+	* 2. If `type` is `"chore"` and `scope` is `"deps"`, returns {@link Categories.DEPENDENCIES}
+	* 3. Otherwise, looks up `type` in the `commitTypes` arrays of all categories
+	* 4. Falls back to {@link Categories.OTHER} for unrecognized types
+	*
+	* @param type - The conventional commit type (e.g., `"feat"`, `"fix"`, `"chore"`)
+	* @param scope - Optional commit scope (e.g., `"deps"` from `chore(deps):`)
+	* @param breaking - Whether the commit includes a breaking change indicator (`!`)
+	* @returns The resolved {@link SectionCategory}
+	*/
+	static fromCommitType(type, scope, breaking) {
+		return resolveCommitType(type, scope, breaking);
+	}
+	/**
+	* Look up a category by its section heading text.
+	*
+	* @remarks
+	* Comparison is case-insensitive. For example, both `"Bug Fixes"` and
+	* `"bug fixes"` will match {@link Categories.BUG_FIXES}.
+	*
+	* @param heading - The heading text (e.g., `"Features"`, `"Bug Fixes"`)
+	* @returns The matching {@link SectionCategory}, or `undefined` if the heading
+	*   does not correspond to any known category
+	*/
+	static fromHeading(heading) {
+		return fromHeading(heading);
+	}
+	/**
+	* Get all valid section heading strings in priority order.
+	*
+	* @remarks
+	* Returns the `heading` field from each category in {@link Categories.ALL},
+	* preserving priority order. Useful for building validation sets or
+	* rendering category pickers.
+	*
+	* @returns Readonly array of heading strings (e.g., `["Breaking Changes", "Features", ...]`)
+	*/
+	static allHeadings() {
+		return allHeadings();
+	}
+	/**
+	* Check whether a heading string matches a known category.
+	*
+	* @remarks
+	* Comparison is case-insensitive. Equivalent to
+	* `Categories.fromHeading(heading) !== undefined`.
+	*
+	* @param heading - The heading text to validate
+	* @returns `true` if the heading matches a known category, `false` otherwise
+	*/
+	static isValidHeading(heading) {
+		return isValidHeading(heading);
+	}
+};
+
+//#endregion
+export { Categories };

package/changesets/api/changelog.js

@@ -0,0 +1,134 @@
+import changelogFunctions from "../changelog/index.js";
+
+//#region src/changesets/api/changelog.ts
+/**
+* Class-based API wrapper for changelog formatting.
+*
+* Provides a static class interface that delegates to the underlying
+* Changesets API-compatible default export.
+*
+* @internal
+*/
+/**
+* Static class wrapper for changelog formatting operations.
+*
+* Delegates to the Changesets-compatible `getReleaseLine` and
+* `getDependencyReleaseLine` functions. Internally, these use the
+* {@link ChangelogService} Effect service layer, which coordinates
+* the {@link GitHubService} (for commit/PR metadata) and
+* {@link MarkdownService} (for AST manipulation) to produce
+* structured changelog entries.
+*
+* @remarks
+* This class provides the same formatting capabilities as the
+* `\@savvy-web/changesets/changelog` subpath export, but through a
+* class-based API rather than the Changesets default-export convention.
+* The underlying formatter parses conventional commit prefixes from the
+* changeset summary to determine the section category (via
+* {@link Categories}), resolves GitHub metadata (authors, PR links,
+* commit hashes), and produces markdown output grouped by category.
+*
+* The `options` parameter must include a `repo` field in `"owner/repo"`
+* format (e.g., `"savvy-web/changesets"`) so that GitHub links can be
+* constructed. Additional options are defined by {@link ChangesetOptionsSchema}.
+*
+* @example Formatting a single changeset release line
+* ```typescript
+* import { Changelog } from "\@savvy-web/changesets";
+*
+* const changeset = {
+*   id: "brave-pandas-learn",
+*   summary: "feat: add token refresh endpoint",
+*   releases: [{ name: "\@savvy-web/auth", type: "minor" as const }],
+*   commit: "abc1234567890abcdef1234567890abcdef123456",
+* };
+*
+* const line: string = await Changelog.formatReleaseLine(changeset, "minor", {
+*   repo: "savvy-web/auth",
+* });
+* // line contains a markdown bullet under the "Features" section heading
+* ```
+*
+* @example Formatting dependency update lines
+* ```typescript
+* import { Changelog } from "\@savvy-web/changesets";
+*
+* const changesets = [
+*   {
+*     id: "cool-dogs-fly",
+*     summary: "chore(deps): update effect to 3.20.0",
+*     releases: [{ name: "\@savvy-web/core", type: "patch" as const }],
+*     commit: "def4567890abcdef1234567890abcdef456789ab",
+*   },
+* ];
+*
+* const dependenciesUpdated = [
+*   {
+*     name: "\@savvy-web/utils",
+*     type: "patch" as const,
+*     oldVersion: "1.2.0",
+*     newVersion: "1.2.1",
+*     changesets: ["cool-dogs-fly"],
+*     packageJson: { name: "\@savvy-web/utils", version: "1.2.1" },
+*   },
+* ];
+*
+* const depLines: string = await Changelog.formatDependencyReleaseLine(
+*   changesets,
+*   dependenciesUpdated,
+*   { repo: "savvy-web/core" },
+* );
+* // depLines contains a markdown table of dependency changes
+* ```
+*
+* @see {@link ChangelogService} for the underlying Effect service
+* @see {@link Categories} for how commit types map to section headings
+* @see {@link ChangesetOptionsSchema} for the full options schema
+*
+* @public
+*/
+var Changelog = class {
+	/* v8 ignore next -- private constructor prevents direct instantiation */
+	constructor() {}
+	/**
+	* Format a single changeset into a changelog release line.
+	*
+	* @remarks
+	* Parses the changeset summary for a conventional commit prefix
+	* (e.g., `"feat: ..."`, `"fix!: ..."`), resolves the corresponding
+	* {@link SectionCategory}, and produces a markdown bullet item with
+	* optional GitHub metadata (author, PR link, commit hash).
+	*
+	* @param changeset - The changeset to format, including its `id`, `summary`,
+	*   `releases` array, and optional `commit` hash
+	* @param versionType - The semantic version bump type (`"major"`, `"minor"`, or `"patch"`)
+	* @param options - Configuration object; must include `repo` in `"owner/repo"` format.
+	*   Pass `null` to use defaults (no GitHub link resolution).
+	* @returns A promise resolving to the formatted markdown string
+	*/
+	static formatReleaseLine(changeset, versionType, options) {
+		return changelogFunctions.getReleaseLine(changeset, versionType, options);
+	}
+	/**
+	* Format dependency update release lines into a markdown table.
+	*
+	* @remarks
+	* Generates a structured dependency table showing package names,
+	* version transitions, and dependency types. The table is placed
+	* under the "Dependencies" section heading in the changelog.
+	*
+	* @param changesets - The changesets that triggered the dependency updates
+	* @param dependenciesUpdated - Array of updated dependencies with their
+	*   old/new versions and package metadata
+	* @param options - Configuration object; must include `repo` in `"owner/repo"` format.
+	*   Pass `null` to use defaults.
+	* @returns A promise resolving to the formatted markdown string containing
+	*   the dependency update table
+	*/
+	static formatDependencyReleaseLine(changesets, dependenciesUpdated, options) {
+		return changelogFunctions.getDependencyReleaseLine(changesets, dependenciesUpdated, options);
+	}
+};
+
+//#endregion
+export { Changelog };

package/changesets/api/dependency-table.js

@@ -0,0 +1,163 @@
+import { collapseDependencyRows, parseDependencyTable, serializeDependencyTable, serializeDependencyTableToMarkdown, sortDependencyRows } from "../utils/dependency-table.js";
+
+//#region src/changesets/api/dependency-table.ts
+/**
+* Static class for dependency table manipulation.
+*
+* Wraps the internal utility functions that operate on dependency tables --
+* the structured markdown tables that appear in the "Dependencies" section
+* of changelogs. Each row in a dependency table represents a single package
+* change with its name, type, action, and version transition.
+*
+* @remarks
+* The typical workflow for processing dependency tables is:
+*
+* 1. **Parse** an mdast `Table` node into typed {@link DependencyTableRow} objects
+* 2. **Collapse** duplicate rows (same package updated multiple times) into single entries
+* 3. **Sort** rows by dependency type, then alphabetically by package name
+* 4. **Serialize** back to an mdast `Table` node or directly to a markdown string
+*
+* The {@link DependencyTable.aggregate} method combines the collapse and sort
+* steps into a single call, which is the most common usage pattern.
+*
+* Each {@link DependencyTableRow} is validated by the {@link DependencyTableRowSchema}
+* Effect Schema at system boundaries, ensuring that dependency names, types,
+* actions, and version strings conform to expected formats.
+*
+* @example Parse, aggregate, and serialize a dependency table
+* ```typescript
+* import { DependencyTable } from "\@savvy-web/changesets";
+* import type { DependencyTableRow } from "\@savvy-web/changesets";
+* import type { Table } from "mdast";
+*
+* // Given an mdast Table node from a parsed CHANGELOG
+* declare const tableNode: Table;
+*
+* // Parse into typed rows
+* const rows: DependencyTableRow[] = DependencyTable.parse(tableNode);
+*
+* // Collapse duplicates and sort by type, then name
+* const aggregated: DependencyTableRow[] = DependencyTable.aggregate(rows);
+*
+* // Serialize back to an mdast Table node for further AST manipulation
+* const outputNode: Table = DependencyTable.serialize(aggregated);
+*
+* // Or serialize directly to a markdown string
+* const markdown: string = DependencyTable.toMarkdown(aggregated);
+* ```
+*
+* @example Step-by-step collapse and sort
+* ```typescript
+* import { DependencyTable } from "\@savvy-web/changesets";
+* import type { DependencyTableRow } from "\@savvy-web/changesets";
+*
+* declare const rows: DependencyTableRow[];
+*
+* // Collapse duplicate entries (same package appears multiple times)
+* const collapsed: DependencyTableRow[] = DependencyTable.collapse(rows);
+*
+* // Sort by dependency type, then alphabetically by name
+* const sorted: DependencyTableRow[] = DependencyTable.sort(collapsed);
+* ```
+*
+* @see {@link DependencyTableRow} for the row shape (dependency, type, action, from, to)
+* @see {@link DependencyTableRowSchema} for the Effect Schema that validates row data
+* @see {@link DependencyTableSchema} for the non-empty array schema
+*
+* @public
+*/
+var DependencyTable = class {
+	/* v8 ignore next -- private constructor prevents direct instantiation */
+	constructor() {}
+	/**
+	* Parse an mdast `Table` node into typed dependency table rows.
+	*
+	* @remarks
+	* Extracts the text content from each table cell and maps it to the
+	* corresponding {@link DependencyTableRow} fields. The first row is
+	* treated as the header and skipped. Rows that do not have the expected
+	* number of columns are ignored.
+	*
+	* @param tableNode - An mdast `Table` node from a parsed markdown AST
+	* @returns Array of {@link DependencyTableRow} objects, one per data row
+	*/
+	static parse(tableNode) {
+		return parseDependencyTable(tableNode);
+	}
+	/**
+	* Serialize typed dependency table rows into an mdast `Table` node.
+	*
+	* @remarks
+	* Produces a well-formed mdast `Table` with a header row
+	* (`Dependency | Type | Action | From | To`) followed by one data row
+	* per input entry. The resulting node can be inserted into a remark AST
+	* for further processing or stringification.
+	*
+	* @param rows - Array of {@link DependencyTableRow} objects to serialize
+	* @returns An mdast `Table` node ready for AST insertion
+	*/
+	static serialize(rows) {
+		return serializeDependencyTable(rows);
+	}
+	/**
+	* Serialize typed dependency table rows directly to a markdown string.
+	*
+	* @remarks
+	* Convenience method that combines {@link DependencyTable.serialize} with
+	* remark stringification. Produces a GFM-compatible markdown table string.
+	*
+	* @param rows - Array of {@link DependencyTableRow} objects to render
+	* @returns A markdown string containing the formatted table
+	*/
+	static toMarkdown(rows) {
+		return serializeDependencyTableToMarkdown(rows);
+	}
+	/**
+	* Collapse duplicate dependency rows into single entries.
+	*
+	* @remarks
+	* When a package appears in multiple rows (e.g., updated in separate
+	* changesets), this method merges them by keeping the earliest `from`
+	* version and the latest `to` version, producing a single row that
+	* represents the net change.
+	*
+	* @param rows - Array of {@link DependencyTableRow} objects, possibly with duplicates
+	* @returns A new array with duplicate packages collapsed into single rows
+	*/
+	static collapse(rows) {
+		return collapseDependencyRows(rows);
+	}
+	/**
+	* Sort dependency rows by action, type, and package name.
+	*
+	* @remarks
+	* Applies a three-level stable sort:
+	* 1. **Action** — `removed` first, then `updated`, then `added`
+	* 2. **Type** — alphabetically (e.g., `config` before `dependency`)
+	* 3. **Dependency name** — alphabetically within each action+type group
+	*
+	* @param rows - Array of {@link DependencyTableRow} objects to sort
+	* @returns A new array sorted by action, type, then name
+	*/
+	static sort(rows) {
+		return sortDependencyRows(rows);
+	}
+	/**
+	* Collapse duplicate rows and then sort the result.
+	*
+	* @remarks
+	* Equivalent to calling {@link DependencyTable.collapse} followed by
+	* {@link DependencyTable.sort}. This is the recommended method for
+	* preparing dependency table data for final output, as it produces
+	* a clean, deduplicated, and consistently ordered table.
+	*
+	* @param rows - Array of {@link DependencyTableRow} objects to aggregate
+	* @returns A new array with duplicates collapsed and rows sorted
+	*/
+	static aggregate(rows) {
+		return sortDependencyRows(collapseDependencyRows(rows));
+	}
+};
+
+//#endregion
+export { DependencyTable };