Clarify security package compatibility notes

packages/security/README.md

@@ -59,6 +59,23 @@ This option was renamed from `password` to `passwordHash`. Callers must update
 both methods when upgrading. The token format is unchanged, so existing reset
 tokens remain valid with the same stored hash, site secret, and expiry.
 
+### Module imports
+
+CommonJS root and deep imports remain supported:
+
+```js
+const security = require('@tryghost/security');
+const tokens = require('@tryghost/security/lib/tokens');
+```
+
+Deep `lib/*` modules expose named exports. Use named or namespace imports when
+transpiling ES module syntax. In version 4, the compiled deep modules set
+`__esModule`, so transpiler-generated default imports can resolve to `undefined`.
+
+```js
+import { resetToken } from '@tryghost/security/lib/tokens';
+```
+
 ## Development
 
 Source lives in `index.ts` and `lib/*.ts`. `pnpm build` emits CommonJS JavaScript

packages/security/lib/string.ts

@@ -1,9 +1,6 @@
 import { slugify } from '@tryghost/string';
 
-/**
- * @param {string} string
- * @param {{importing?: boolean}} [options]
- */
+/** Normalizes slugs, treating null or omitted values as an empty string. */
 export function safe(string?: string | null, options: { importing?: boolean } = {}): string {
     return slugify(string, { requiredChangesOnly: options.importing === true });
 }

packages/security/types/tryghost-string.d.ts

@@ -1,4 +1,5 @@
 // @tryghost/string does not publish declarations. Only its consumed API is modeled here.
+// TODO: Remove this shim when @tryghost/string publishes its own declarations.
 declare module '@tryghost/string' {
     export function slugify(
         value: string | null | undefined,

packages/security/vitest.config.ts

@@ -6,6 +6,7 @@ export default mergeConfig(
     defineConfig({
         test: {
             coverage: {
+                // Measure the compiled JavaScript exercised by tests and shipped to consumers.
                 include: ['lib/**/*.js'],
                 exclude: ['**/*.ts', '**/*.d.ts'],
             },