chore: reduce sv API surface (#1046)

Co-authored-by: Scott Wu <sw@scottwu.ca>

Author: jycouet

.changeset/coupling-sv-and-sv-utils.md

@@ -0,0 +1,23 @@
+---
+'sv': minor
+'@sveltejs/sv-utils': minor
+---
+
+feat: decouple sv / sv-utils, explicit public API, deprecation pass
+
+**`@sveltejs/sv-utils`**
+
+- Rename file helpers: `readFile` -> `loadFile`, `writeFile` -> `saveFile`, `getPackageJson` -> `loadPackageJson`
+- Add `pnpm.onlyBuiltDependencies()` transform for `pnpm-workspace.yaml`
+- Export `YamlDocument` type from parsers
+- Remove `commonFilePaths`, `installPackages` (moved internal to `sv`)
+
+**`sv`**
+
+- `create()` signature changed to `create({ cwd, ...options })`. The old `create(cwd, options)` is deprecated and will be removed in the next major release.
+- `sv.pnpmBuildDependency()` is deprecated and will be removed in the next major release. Use `sv.file()` with `pnpm.onlyBuiltDependencies()` from `@sveltejs/sv-utils` instead.
+- `workspace.file.prettierignore`, `.prettierrc`, `.eslintConfig`, `.vscodeSettings`, `.vscodeExtensions` are deprecated and will be removed in the next major release. Use the raw strings directly (e.g. `'.prettierignore'`).
+- Add `workspace.file.findUp()` to locate files by walking up the directory tree.
+- Add `api-surface.md` snapshots (auto-generated on build) to track the public API of `sv` and `@sveltejs/sv-utils`.
+- Remove `setup`, `createProject`, `startPreview`, `addPnpmBuildDependencies` from `sv/testing` exports.
+- Make type exports explicit (no more `export type *`). Removed types that were never part of the intended public API: `PackageDefinition`, `Scripts`, `TestDefinition`.

CONTRIBUTING.md

@@ -153,6 +153,30 @@ To run svelte-migrate locally:
 node ./packages/migrate/bin.js
 ```
 
+## Deprecation
+
+Public APIs cannot be changed in a minor release since it is a breaking change. Instead, the old behaviour is marked as deprecated until the next major version, at which point they can be removed.
+
+### How to deprecate
+
+1. **Add `@deprecated` JSDoc** on the type/function - IDEs will show strikethrough:
+
+   ```ts
+   /** @deprecated use `newThing()` instead. */
+   ```
+
+2. **Emit a runtime warning** (for functions/methods) using `svDeprecated()` from `core/deprecated.ts`. Warns once per message:
+
+   ```ts
+   svDeprecated('use `newThing()` instead of `oldThing()`');
+   ```
+
+3. **Keep the old behavior working** - the deprecated API should still function correctly, just with a warning.
+
+### Before a major release
+
+Search for `svDeprecated` and `@deprecated` to find and remove all deprecated APIs.
+
 ## Generating changelogs
 
 Here is the command to generate a change set:

documentation/docs/50-api/20-sv-utils.md

@@ -137,7 +137,7 @@ Return `false` from any transform callback to abort - the original content is re
 import { transforms } from '@sveltejs/sv-utils';
 
 sv.file(
-	file.eslintConfig,
+	'eslint.config.js',
 	transforms.script(({ ast, js }) => {
 		const { value: existing } = js.exports.createDefault(ast, { fallback: myConfig });
 		if (existing !== myConfig) {

package.json

@@ -9,6 +9,7 @@
 	},
 	"scripts": {
 		"build": "tsdown",
+		"postbuild": "node scripts/generate-api-surface.js",
 		"changeset:publish": "changeset publish",
 		"check": "pnpm --parallel check",
 		"dev": "tsdown -w & pnpm --parallel check -w & wait",