docs(misc): add @example blocks to remaining module exports

src/argv/flags.ts

@@ -39,6 +39,13 @@ export type FlagInput = FlagValues | string[] | readonly string[] | undefined
  * Get the appropriate log level based on flags.
  * Returns 'silent', 'error', 'warn', 'info', 'verbose', or 'debug'.
  * Accepts FlagValues object, process.argv array, or undefined (uses process.argv).
+ *
+ * @example
+ * ```typescript
+ * getLogLevel()  // 'info' (default)
+ * getLogLevel({ quiet: true })  // 'silent'
+ * getLogLevel(['--debug'])  // 'debug'
+ * ```
  */
 export function getLogLevel(input?: FlagInput): string {
   if (isQuiet(input)) {
@@ -56,6 +63,12 @@ export function getLogLevel(input?: FlagInput): string {
 /**
  * Check if all flag is set.
  * Accepts FlagValues object, process.argv array, or undefined (uses process.argv).
+ *
+ * @example
+ * ```typescript
+ * isAll({ all: true })  // true
+ * isAll(['--all'])  // true
+ * ```
  */
 export function isAll(input?: FlagInput): boolean {
   if (!input) {
@@ -70,6 +83,12 @@ export function isAll(input?: FlagInput): boolean {
 /**
  * Check if changed files mode is enabled.
  * Accepts FlagValues object, process.argv array, or undefined (uses process.argv).
+ *
+ * @example
+ * ```typescript
+ * isChanged({ changed: true })  // true
+ * isChanged(['--changed'])  // true
+ * ```
  */
 export function isChanged(input?: FlagInput): boolean {
   if (!input) {
@@ -85,6 +104,12 @@ export function isChanged(input?: FlagInput): boolean {
  * Check if coverage mode is enabled.
  * Checks both 'coverage' and 'cover' flags.
  * Accepts FlagValues object, process.argv array, or undefined (uses process.argv).
+ *
+ * @example
+ * ```typescript
+ * isCoverage({ coverage: true })  // true
+ * isCoverage(['--cover'])  // true
+ * ```
  */
 export function isCoverage(input?: FlagInput): boolean {
   if (!input) {
@@ -99,6 +124,12 @@ export function isCoverage(input?: FlagInput): boolean {
 /**
  * Check if debug mode is enabled.
  * Accepts FlagValues object, process.argv array, or undefined (uses process.argv).
+ *
+ * @example
+ * ```typescript
+ * isDebug({ debug: true })  // true
+ * isDebug(['--debug'])  // true
+ * ```
  */
 export function isDebug(input?: FlagInput): boolean {
   if (!input) {
@@ -113,6 +144,12 @@ export function isDebug(input?: FlagInput): boolean {
 /**
  * Check if dry-run mode is enabled.
  * Accepts FlagValues object, process.argv array, or undefined (uses process.argv).
+ *
+ * @example
+ * ```typescript
+ * isDryRun({ 'dry-run': true })  // true
+ * isDryRun(['--dry-run'])  // true
+ * ```
  */
 export function isDryRun(input?: FlagInput): boolean {
   if (!input) {
@@ -127,6 +164,12 @@ export function isDryRun(input?: FlagInput): boolean {
 /**
  * Check if fix/autofix mode is enabled.
  * Accepts FlagValues object, process.argv array, or undefined (uses process.argv).
+ *
+ * @example
+ * ```typescript
+ * isFix({ fix: true })  // true
+ * isFix(['--fix'])  // true
+ * ```
  */
 export function isFix(input?: FlagInput): boolean {
   if (!input) {
@@ -141,6 +184,12 @@ export function isFix(input?: FlagInput): boolean {
 /**
  * Check if force mode is enabled.
  * Accepts FlagValues object, process.argv array, or undefined (uses process.argv).
+ *
+ * @example
+ * ```typescript
+ * isForce({ force: true })  // true
+ * isForce(['--force'])  // true
+ * ```
  */
 export function isForce(input?: FlagInput): boolean {
   if (!input) {
@@ -155,6 +204,12 @@ export function isForce(input?: FlagInput): boolean {
 /**
  * Check if help flag is set.
  * Accepts FlagValues object, process.argv array, or undefined (uses process.argv).
+ *
+ * @example
+ * ```typescript
+ * isHelp({ help: true })  // true
+ * isHelp(['-h'])  // true
+ * ```
  */
 export function isHelp(input?: FlagInput): boolean {
   if (!input) {
@@ -169,6 +224,12 @@ export function isHelp(input?: FlagInput): boolean {
 /**
  * Check if JSON output is requested.
  * Accepts FlagValues object, process.argv array, or undefined (uses process.argv).
+ *
+ * @example
+ * ```typescript
+ * isJson({ json: true })  // true
+ * isJson(['--json'])  // true
+ * ```
  */
 export function isJson(input?: FlagInput): boolean {
   if (!input) {
@@ -183,6 +244,12 @@ export function isJson(input?: FlagInput): boolean {
 /**
  * Check if quiet/silent mode is enabled.
  * Accepts FlagValues object, process.argv array, or undefined (uses process.argv).
+ *
+ * @example
+ * ```typescript
+ * isQuiet({ quiet: true })  // true
+ * isQuiet(['--silent'])  // true
+ * ```
  */
 export function isQuiet(input?: FlagInput): boolean {
   if (!input) {
@@ -197,6 +264,12 @@ export function isQuiet(input?: FlagInput): boolean {
 /**
  * Check if staged files mode is enabled.
  * Accepts FlagValues object, process.argv array, or undefined (uses process.argv).
+ *
+ * @example
+ * ```typescript
+ * isStaged({ staged: true })  // true
+ * isStaged(['--staged'])  // true
+ * ```
  */
 export function isStaged(input?: FlagInput): boolean {
   if (!input) {
@@ -211,6 +284,12 @@ export function isStaged(input?: FlagInput): boolean {
 /**
  * Check if update mode is enabled (for snapshots, dependencies, etc).
  * Accepts FlagValues object, process.argv array, or undefined (uses process.argv).
+ *
+ * @example
+ * ```typescript
+ * isUpdate({ update: true })  // true
+ * isUpdate(['-u'])  // true
+ * ```
  */
 export function isUpdate(input?: FlagInput): boolean {
   if (!input) {
@@ -225,6 +304,12 @@ export function isUpdate(input?: FlagInput): boolean {
 /**
  * Check if verbose mode is enabled.
  * Accepts FlagValues object, process.argv array, or undefined (uses process.argv).
+ *
+ * @example
+ * ```typescript
+ * isVerbose({ verbose: true })  // true
+ * isVerbose(['--verbose'])  // true
+ * ```
  */
 export function isVerbose(input?: FlagInput): boolean {
   if (!input) {
@@ -239,6 +324,12 @@ export function isVerbose(input?: FlagInput): boolean {
 /**
  * Check if watch mode is enabled.
  * Accepts FlagValues object, process.argv array, or undefined (uses process.argv).
+ *
+ * @example
+ * ```typescript
+ * isWatch({ watch: true })  // true
+ * isWatch(['-w'])  // true
+ * ```
  */
 export function isWatch(input?: FlagInput): boolean {
   if (!input) {

src/argv/parse.ts

@@ -97,6 +97,17 @@ export interface ParsedArgs<T = Record<string, unknown>> {
 /**
  * Parse command-line arguments with a Node.js parseArgs-compatible API.
  * Uses yargs-parser internally for robust argument parsing.
+ *
+ * @example
+ * ```typescript
+ * const { values, positionals } = parseArgs({
+ *   args: ['--force', '--quiet', 'file.ts'],
+ *   options: {
+ *     force: { type: 'boolean' },
+ *     quiet: { type: 'boolean', short: 'q' },
+ *   },
+ * })
+ * ```
  */
 export function parseArgs<T = Record<string, unknown>>(
   config: ParseArgsConfig = {},
@@ -206,6 +217,14 @@ export function parseArgs<T = Record<string, unknown>>(
 /**
  * Parse command-line arguments with Socket defaults.
  * Provides sensible defaults for Socket CLI applications.
+ *
+ * @example
+ * ```typescript
+ * const { values, positionals } = parseArgsWithDefaults({
+ *   args: ['--force', 'file.ts'],
+ *   options: { force: { type: 'boolean' } },
+ * })
+ * ```
  */
 export function parseArgsWithDefaults<T = Record<string, unknown>>(
   config: ParseArgsConfig = {},
@@ -239,6 +258,12 @@ export const commonParseArgsConfig: ParseArgsConfig = {
 /**
  * Extract positional arguments from process.argv.
  * Useful for commands that accept file paths or other positional parameters.
+ *
+ * @example
+ * ```typescript
+ * // process.argv = ["node", "script.js", "src", "lib", "--verbose"]
+ * getPositionalArgs()  // ["src", "lib"]
+ * ```
  */
 export function getPositionalArgs(startIndex = 2): string[] {
   const args = process.argv.slice(startIndex)
@@ -260,6 +285,12 @@ export function getPositionalArgs(startIndex = 2): string[] {
 
 /**
  * Check if a specific flag is present in argv.
+ *
+ * @example
+ * ```typescript
+ * hasFlag('verbose')  // true if --verbose is in process.argv
+ * hasFlag('force', ['--force', '--quiet'])  // true
+ * ```
  */
 export function hasFlag(flag: string, argv = process.argv): boolean {
   return argv.includes(`--${flag}`)

src/cacache.ts

@@ -41,6 +41,12 @@ export interface RemoveOptions {
 
 /**
  * Get the cacache module for cache operations.
+ *
+ * @example
+ * ```typescript
+ * const cacache = getCacache()
+ * const entries = await cacache.ls(cacheDir)
+ * ```
  */
 export function getCacache() {
   // cacache is imported at the top
@@ -167,6 +173,12 @@ export async function clear(
  * Get data from the Socket shared cache by key.
  * @throws {Error} When cache entry is not found.
  * @throws {TypeError} If key contains wildcards (*)
+ *
+ * @example
+ * ```typescript
+ * const entry = await get('socket-sdk:scans:abc123')
+ * console.log(entry.data.toString('utf8'))
+ * ```
  */
 export async function get(
   key: string,
@@ -186,6 +198,11 @@ export async function get(
  * Put data into the Socket shared cache with a key.
  *
  * @throws {TypeError} If key contains wildcards (*)
+ *
+ * @example
+ * ```typescript
+ * await put('socket-sdk:scans:abc123', Buffer.from('result data'))
+ * ```
  */
 export async function put(
   key: string,
@@ -206,6 +223,11 @@ export async function put(
  * Remove an entry from the Socket shared cache by key.
  *
  * @throws {TypeError} If key contains wildcards (*)
+ *
+ * @example
+ * ```typescript
+ * await remove('socket-sdk:scans:abc123')
+ * ```
  */
 export async function remove(key: string): Promise<unknown> {
   if (key.includes('*')) {
@@ -220,6 +242,14 @@ export async function remove(key: string): Promise<unknown> {
 
 /**
  * Get data from the Socket shared cache by key without throwing.
+ *
+ * @example
+ * ```typescript
+ * const entry = await safeGet('socket-sdk:scans:abc123')
+ * if (entry) {
+ *   console.log(entry.data.toString('utf8'))
+ * }
+ * ```
  */
 export async function safeGet(
   key: string,
@@ -234,6 +264,14 @@ export async function safeGet(
 
 /**
  * Execute a callback with a temporary directory for cache operations.
+ *
+ * @example
+ * ```typescript
+ * const result = await withTmp(async (tmpDir) => {
+ *   // Use tmpDir for temporary cache work
+ *   return 'done'
+ * })
+ * ```
  */
 export async function withTmp<T>(
   callback: (tmpDirPath: string) => Promise<T>,

src/cover/formatters.ts

@@ -23,6 +23,12 @@ const COVERAGE_EMOJI_THRESHOLDS = [
 
 /**
  * Get emoji for coverage percentage.
+ *
+ * @example
+ * ```typescript
+ * getCoverageEmoji(95)  // ' \u{1F3AF}'
+ * getCoverageEmoji(50)  // ' \u{1F528}'
+ * ```
  */
 export function getCoverageEmoji(percent: number): string {
   const entry = COVERAGE_EMOJI_THRESHOLDS.find(
@@ -33,6 +39,18 @@ export function getCoverageEmoji(percent: number): string {
 
 /**
  * Format coverage data for console output.
+ *
+ * @example
+ * ```typescript
+ * const output = formatCoverage({
+ *   code: {
+ *     statements: { percent: '85.00' },
+ *     branches: { percent: '80.00' },
+ *     functions: { percent: '90.00' },
+ *     lines: { percent: '88.00' },
+ *   },
+ * })
+ * ```
  */
 export function formatCoverage(options: FormatCoverageOptions): string {
   const opts = {

src/debug.ts

@@ -360,6 +360,12 @@ function debugCacheNs(
 
 /**
  * Cache debug function with caller info.
+ *
+ * @example
+ * ```typescript
+ * debugCache('hit', 'socket-sdk:scans:abc123')
+ * debugCache('miss', 'socket-sdk:scans:xyz', { ttl: 60000 })
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function debugCache(

src/effects/pulse-frames.ts

@@ -28,6 +28,12 @@ export type SocketFramesOptions = {
  * Returns a spinner definition compatible with cli-spinners format.
  *
  * @see https://github.com/sindresorhus/cli-spinners/blob/main/spinners.json
+ *
+ * @example
+ * ```typescript
+ * const { frames, interval } = generateSocketSpinnerFrames()
+ * console.log(frames.length, interval) // 18 50
+ * ```
  */
 export function generateSocketSpinnerFrames(
   options?: SocketFramesOptions | undefined,