docs(packages): add @example blocks to packages module exports (#175)

* docs(env): add @example blocks to env module exports

* docs(packages): add @example blocks to packages module exports

Author: jdalton

src/packages/edit.ts

@@ -167,6 +167,13 @@ function getUtil() {
 
 /**
  * Get the EditablePackageJson class for package.json manipulation.
+ *
+ * @example
+ * ```typescript
+ * const EditablePackageJson = getEditablePackageJsonClass()
+ * const pkg = await EditablePackageJson.load('/tmp/my-project')
+ * console.log(pkg.content.name)
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function getEditablePackageJsonClass(): EditablePackageJsonConstructor {
@@ -467,6 +474,11 @@ export function getEditablePackageJsonClass(): EditablePackageJsonConstructor {
 
 /**
  * Convert a package.json object to an editable instance.
+ *
+ * @example
+ * ```typescript
+ * const editable = pkgJsonToEditable({ name: 'my-pkg', version: '1.0.0' })
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function pkgJsonToEditable(
@@ -485,6 +497,14 @@ export function pkgJsonToEditable(
 
 /**
  * Convert package.json to editable instance with file persistence.
+ *
+ * @example
+ * ```typescript
+ * const editable = await toEditablePackageJson(
+ *   { name: 'my-pkg', version: '1.0.0' },
+ *   { path: '/tmp/my-project' }
+ * )
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export async function toEditablePackageJson(
@@ -519,6 +539,14 @@ export async function toEditablePackageJson(
 
 /**
  * Convert package.json to editable instance with file persistence synchronously.
+ *
+ * @example
+ * ```typescript
+ * const editable = toEditablePackageJsonSync(
+ *   { name: 'my-pkg', version: '1.0.0' },
+ *   { path: '/tmp/my-project' }
+ * )
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function toEditablePackageJsonSync(

src/packages/exports.ts

@@ -9,6 +9,13 @@ import { isObject, isObjectObject } from '../objects'
 
 /**
  * Find types definition for a specific subpath in package exports.
+ *
+ * @example
+ * ```typescript
+ * const exports = { '.': { types: './dist/index.d.ts', import: './dist/index.js' } }
+ * const types = findTypesForSubpath(exports, './dist/index.js')
+ * // types === './dist/index.d.ts'
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function findTypesForSubpath(
@@ -53,6 +60,12 @@ export function findTypesForSubpath(
 
 /**
  * Get subpaths from package exports.
+ *
+ * @example
+ * ```typescript
+ * const exports = { '.': './index.js', './utils': './utils.js' }
+ * getSubpaths(exports) // ['.', './utils']
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function getSubpaths(entryExports: unknown): string[] {
@@ -67,6 +80,12 @@ export function getSubpaths(entryExports: unknown): string[] {
 
 /**
  * Get file paths from package exports.
+ *
+ * @example
+ * ```typescript
+ * const exports = { '.': './dist/index.js', './utils': './dist/utils.js' }
+ * getExportFilePaths(exports) // ['./dist/index.js', './dist/utils.js']
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function getExportFilePaths(entryExports: unknown): string[] {
@@ -119,6 +138,12 @@ export function getExportFilePaths(entryExports: unknown): string[] {
 
 /**
  * Check if package exports use conditional patterns (e.g., import/require).
+ *
+ * @example
+ * ```typescript
+ * isConditionalExports({ import: './index.mjs', require: './index.cjs' }) // true
+ * isConditionalExports({ '.': './index.js' })                            // false
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function isConditionalExports(entryExports: unknown): boolean {
@@ -145,6 +170,12 @@ export function isConditionalExports(entryExports: unknown): boolean {
 
 /**
  * Check if package exports use subpath patterns (keys starting with '.').
+ *
+ * @example
+ * ```typescript
+ * isSubpathExports({ '.': './index.js', './utils': './utils.js' }) // true
+ * isSubpathExports({ import: './index.mjs' })                     // false
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function isSubpathExports(entryExports: unknown): boolean {
@@ -165,6 +196,15 @@ export function isSubpathExports(entryExports: unknown): boolean {
 
 /**
  * Normalize package.json exports field to canonical format.
+ *
+ * @example
+ * ```typescript
+ * resolvePackageJsonEntryExports('./index.js')
+ * // { '.': './index.js' }
+ *
+ * resolvePackageJsonEntryExports({ '.': './index.js' })
+ * // { '.': './index.js' }
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function resolvePackageJsonEntryExports(entryExports: unknown): unknown {

src/packages/licenses.ts

@@ -74,6 +74,13 @@ export interface LicenseVisitor {
 
 /**
  * Collect licenses that are incompatible (copyleft).
+ *
+ * @example
+ * ```typescript
+ * const nodes = [{ license: 'MIT' }, { license: 'GPL-3.0' }]
+ * const incompatible = collectIncompatibleLicenses(nodes)
+ * // incompatible contains only the GPL-3.0 node
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function collectIncompatibleLicenses(
@@ -91,6 +98,12 @@ export function collectIncompatibleLicenses(
 
 /**
  * Collect warnings from license nodes.
+ *
+ * @example
+ * ```typescript
+ * const nodes = [{ license: 'UNLICENSED' }]
+ * collectLicenseWarnings(nodes) // ['Package is unlicensed']
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function collectLicenseWarnings(licenseNodes: LicenseNode[]): string[] {
@@ -112,6 +125,13 @@ export function collectLicenseWarnings(licenseNodes: LicenseNode[]): string[] {
 
 /**
  * Create an AST node from a raw node.
+ *
+ * @example
+ * ```typescript
+ * const raw = { license: 'MIT' }
+ * const node = createAstNode(raw)
+ * // node.type === 'License'
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function createAstNode(rawNode: SpdxAstNode): InternalAstNode {
@@ -122,6 +142,17 @@ export function createAstNode(rawNode: SpdxAstNode): InternalAstNode {
 
 /**
  * Create a binary operation AST node.
+ *
+ * @example
+ * ```typescript
+ * const raw = {
+ *   left: { license: 'MIT' },
+ *   conjunction: 'OR' as const,
+ *   right: { license: 'Apache-2.0' }
+ * }
+ * const node = createBinaryOperationNode(raw)
+ * // node.type === 'BinaryOperation'
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function createBinaryOperationNode(
@@ -156,6 +187,12 @@ export function createBinaryOperationNode(
 
 /**
  * Create a license AST node.
+ *
+ * @example
+ * ```typescript
+ * const node = createLicenseNode({ license: 'MIT' })
+ * // node.type === 'License' && node.license === 'MIT'
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function createLicenseNode(
@@ -170,6 +207,12 @@ export function createLicenseNode(
 
 /**
  * Parse an SPDX license expression into an AST.
+ *
+ * @example
+ * ```typescript
+ * const ast = parseSpdxExp('MIT OR Apache-2.0')
+ * // ast is a BinaryOperation node with MIT and Apache-2.0 leaves
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function parseSpdxExp(spdxExp: string): SpdxAstNode | undefined {
@@ -184,6 +227,12 @@ export function parseSpdxExp(spdxExp: string): SpdxAstNode | undefined {
 
 /**
  * Parse package license field into structured license nodes.
+ *
+ * @example
+ * ```typescript
+ * const nodes = resolvePackageLicenses('MIT', '/tmp/my-project')
+ * // [{ license: 'MIT' }]
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function resolvePackageLicenses(
@@ -238,6 +287,16 @@ export function resolvePackageLicenses(
 
 /**
  * Traverse SPDX license AST and invoke visitor callbacks for each node.
+ *
+ * @example
+ * ```typescript
+ * const ast = parseSpdxExp('MIT OR Apache-2.0')
+ * const licenses: string[] = []
+ * if (ast) {
+ *   visitLicenses(ast, { License(node) { licenses.push(node.license) } })
+ * }
+ * // licenses === ['MIT', 'Apache-2.0']
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function visitLicenses(ast: SpdxAstNode, visitor: LicenseVisitor): void {

src/packages/manifest.ts

@@ -32,6 +32,14 @@ const pkgScopePrefixRegExp = /^@socketregistry\//
 
 /**
  * Create a package.json object for a Socket registry package.
+ *
+ * @example
+ * ```typescript
+ * const pkgJson = createPackageJson('is-number', 'packages/npm/is-number', {
+ *   version: '1.0.0',
+ *   description: 'Check if a value is a number'
+ * })
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function createPackageJson(
@@ -125,6 +133,11 @@ export function createPackageJson(
 
 /**
  * Fetch the manifest for a package.
+ *
+ * @example
+ * ```typescript
+ * const manifest = await fetchPackageManifest('lodash@4.17.21')
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export async function fetchPackageManifest(
@@ -170,6 +183,11 @@ export async function fetchPackageManifest(
 
 /**
  * Fetch the packument (package document) for a package.
+ *
+ * @example
+ * ```typescript
+ * const packument = await fetchPackagePackument('lodash')
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export async function fetchPackagePackument(

src/packages/normalize.ts

@@ -25,6 +25,12 @@ function getEscapedScopeRegExp(): RegExp {
 
 /**
  * Normalize a package.json object with standard npm package normalization.
+ *
+ * @example
+ * ```typescript
+ * const pkgJson = { name: 'my-pkg', version: '1.0.0' }
+ * const normalized = normalizePackageJson(pkgJson)
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function normalizePackageJson(
@@ -67,6 +73,12 @@ export function normalizePackageJson(
 
 /**
  * Extract escaped scope from a Socket registry package name.
+ *
+ * @example
+ * ```typescript
+ * resolveEscapedScope('babel__core') // 'babel__'
+ * resolveEscapedScope('lodash')      // undefined
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function resolveEscapedScope(
@@ -79,6 +91,11 @@ export function resolveEscapedScope(
 
 /**
  * Resolve original package name from Socket registry package name.
+ *
+ * @example
+ * ```typescript
+ * resolveOriginalPackageName('@socketregistry/is-number') // 'is-number'
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function resolveOriginalPackageName(sockRegPkgName: string): string {
@@ -93,6 +110,11 @@ export function resolveOriginalPackageName(sockRegPkgName: string): string {
 
 /**
  * Convert escaped scope to standard npm scope format.
+ *
+ * @example
+ * ```typescript
+ * unescapeScope('babel__') // '@babel'
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function unescapeScope(escapedScope: string): string {