Core Module

const content = 'Hello World'
const withBom = addBom(content)
// => '\ufeffHello World'

const fileBuffer = readFileSync('./config.json')
const content = bufferToString(fileBuffer)
// => '{"key": "value"}'

// In tests
afterEach(() => {
  clearAllCaches()
})

// Basic cache
const cache = createCache<string, number>()
cache.set('answer', 42)
cache.get('answer') // 42

// Cache with TTL (expires after 60 seconds)
const ttlCache = createCache<string, object>({ ttl: 60000 })

// Cache with max size (evicts oldest when full)
const lruCache = createCache<string, object>({ maxSize: 100 })

// Combined options
const configCache = createCache<string, object>({
  ttl: 30000,
  maxSize: 50
})

throw createConfigError(
  'Invalid port number',
  'CONFIG_INVALID_PORT',
  { configFile: './app.config.json', value: -1 }
)

// Create nested directories
createDirectory('./output/reports/2024')

// Create single directory without parents
createDirectory('./logs', { recursive: false })

throw createFileSystemError(
  'Cannot read file',
  'FS_READ_ERROR',
  { path: './missing.txt', operation: 'read' }
)

throw createFsError(
  'Configuration file not found',
  'ENOENT',
  { path: './missing.json', operation: 'read' }
)

throw createParseError(
  'Invalid JSON syntax',
  'JSON_PARSE_ERROR',
  { file: './config.json', line: 42, column: 15 }
)

const logger = createScopedLogger('project-scope')
logger.setLogLevel('debug')

// Basic logging
logger.info('Starting analysis', { path: './project' })

// Sensitive data is automatically redacted
logger.debug('Config loaded', { apiKey: 'secret123' })
// Output: [project-scope] Config loaded {"apiKey":"[REDACTED]"}

import { createStructuredError } from '@hyperfrontend/project-scope'

throw createStructuredError(
  'Configuration file not found',
  'CONFIG_NOT_FOUND',
  { path: './config.json', searched: ['./config.json', './settings.json'] }
)

throw createValidationError(
  'Email format is invalid',
  'INVALID_EMAIL',
  { field: 'email', value: 'not-an-email' }
)

if (detectCaseSensitivity()) {
  // Linux: 'File.ts' and 'file.ts' are different files
} else {
  // Windows/macOS: treat as same file
}

const buffer = readFileSync('./data.txt')
const encoding = detectEncoding(buffer)
const content = buffer.toString(encoding)

const buffer = readFileSync('./document.txt')
const info = detectEncodingInfo(buffer)
if (info.type === 'text') {
  console.log(`Encoding: ${info.encoding}, BOM: ${info.hasBom}`)
}

const ending = detectLineEnding('line1\nline2\n')
// => 'lf'

const mixed = detectLineEnding('line1\r\nline2\nline3')
// => 'mixed'

const platform = detectPlatform()
if (platform.isWindows) {
  // Windows-specific handling
}

ensureDir('./output/reports')
// Directory now exists (created if missing)

ensureTrailingSlash('src/components')
// => 'src/components/'

ensureTrailingSlash('already/has/')
// => 'already/has/'

if (exists('./config.json')) {
  const config = readJsonFile('./config.json')
}

// Find directory with a specific config
const configDir = findUpwardWhere('./deep/nested/path', (dir) =>
  existsSync(join(dir, '.eslintrc.js'))
)

getBasename('src/components/Button.tsx')
// => 'Button.tsx'

getBasename('src/components/Button.tsx', '.tsx')
// => 'Button'

const count = getCacheCount()
// => 3 (number of active caches)

getDirname('src/components/Button.tsx')
// => 'src/components'

getExtension('src/utils/helpers.ts')
// => '.ts'

getExtension('package.json')
// => '.json'

getFileNameWithoutExtension('src/utils/helpers.ts')
// => 'helpers'

const stats = getFileStat('./package.json')
if (stats) {
  console.log(`Size: ${stats.size} bytes`)
  console.log(`Modified: ${stats.modified}`)
}

setGlobalLogLevel('debug')
const level = getGlobalLogLevel()
// => 'debug'

const eol = getLineEnding()
const lines = ['line1', 'line2', 'line3']
const content = lines.join(eol)

const sep = getPathSeparator()
const fullPath = ['src', 'utils', 'helpers.ts'].join(sep)

const info = getPlatformInfo()
console.log(info.os)           // => 'linux'
console.log(info.pathSeparator) // => '/'
console.log(info.lineEnding)    // => '\n'

const buffer = readFileSync('./file.txt')
if (hasBom(buffer)) {
  // Strip BOM before processing
}

isAbsolute('/workspace/src/index.ts')
// => true

isAbsolute('./src/index.ts')
// => false

const caseSensitive = isCaseSensitiveFs()
// => true on Linux, false on Windows/macOS

if (isDirectory('./src')) {
  // Path exists and is a directory
}

if (isFile('./package.json')) {
  // Path exists and is a regular file
}

if (isSymlink('./node_modules/.bin/tsc')) {
  // Path is a symbolic link
}

const buffer = readFileSync('./unknown-file')
if (isTextFile(buffer)) {
  const content = buffer.toString('utf-8')
}

if (isWindows()) {
  // Use Windows-specific paths or commands
}

const fullPath = join('src', 'components', 'Button.tsx')
// => 'src/components/Button.tsx' (or 'src\\components\\Button.tsx' on Windows)

joinPath('src', 'components', 'Button.tsx')
// => 'src/components/Button.tsx'

const configPath = joinPosix('config', 'settings', 'app.json')
// => 'config/settings/app.json'

// Find project root by looking for common marker files
const projectRoot = locateByMarkers('./src/components', [
  'package.json',
  'nx.json',
  'tsconfig.base.json'
])
// => '/workspace/my-project'

const ignorePatterns = ['*.log', 'node_modules/**', '*.tmp']
const shouldIgnore = matchesAnyPattern('debug.log', ignorePatterns)
// => true

matchesExact('package.json', 'package.json')
// => true

matchesExact('src/package.json', 'package.json')
// => false

import { matchGlobPattern } from '@hyperfrontend/project-scope'

matchGlobPattern('src/utils/helper.ts', '\*\*/*.ts')     // true
matchGlobPattern('test.spec.ts', '\*.spec.ts')          // true
matchGlobPattern('config.json', '\*.{json,yaml}')       // true
matchGlobPattern('src/index.ts', 'src/\*.ts')           // true

// Memoize a detection function
const detectTechStackMemo = memoize(
  (path: string) => expensiveDetection(path),
  { ttl: 60000 }
)

const result1 = detectTechStackMemo('/path/to/project')
const result2 = detectTechStackMemo('/path/to/project') // Returns cached

// Clear the cache
detectTechStackMemo.cache.clear()

// Normalize to Unix line endings
const normalized = normalizeLineEndings('line1\r\nline2\r\n', 'lf')
// => 'line1\nline2\n'

// Use platform default
const platformNormalized = normalizeLineEndings(content, 'auto')

const path = normalizePath('src\\components\\Button.tsx')
// => 'src/components/Button.tsx'

const path = normalizeToForwardSlashes('./src/../lib/utils')
// => 'lib/utils'

const path = normalizeToNative('src/components/Button.tsx')
// => 'src\\components\\Button.tsx' on Windows
// => 'src/components/Button.tsx' on Unix

offsetFromRoot('libs/utils/src')
// => '../../../'

offsetFromRoot('apps')
// => '../'

const parsed = parsePath('/workspace/src/index.ts')
// => { root: '/', dir: '/workspace/src', base: 'index.ts', ext: '.ts', name: 'index' }

pathSegments('src/components/Button.tsx')
// => ['src', 'components', 'Button.tsx']

// On case-insensitive filesystem (Windows/macOS)
pathsEqual('src/App.tsx', 'src/app.tsx')
// => true

// On case-sensitive filesystem (Linux)
pathsEqual('src/App.tsx', 'src/app.tsx')
// => false

import { readDirectory } from '@hyperfrontend/project-scope'

const entries = readDirectory('./src')
for (const entry of entries) {
  console.log(entry.name, entry.isFile ? 'file' : 'directory')
}

import { readDirectoryRecursive } from '@hyperfrontend/project-scope'

// List all files up to 3 levels deep
const entries = readDirectoryRecursive('./src', { maxDepth: 3 })

// Include hidden files
const allEntries = readDirectoryRecursive('./project', { includeHidden: true })

const buffer = readFileBuffer('./image.png')
console.log(buffer.length) // File size in bytes

import { readFileContent } from '@hyperfrontend/project-scope'

const content = readFileContent('./package.json')
console.log(content) // JSON string

const content = readFileIfExists('./optional-config.json')
if (content) {
  // File existed, use content
}

import { readJsonFile } from '@hyperfrontend/project-scope'

// Read with type inference
interface Config { port: number }
const config = readJsonFile<Config>('./config.json')

// Read with default fallback
const settings = readJsonFile('./settings.json', { default: {} })

interface UserSettings { theme: string }
const settings = readJsonFileIfExists<UserSettings>('./user-settings.json')
const theme = settings?.theme ?? 'default'

relativePath('/workspace/src/utils', '/workspace/lib/helpers')
// => '../../lib/helpers'

// Remove directory and all contents
removeDirectory('./temp', { recursive: true })

// Safe removal (no error if missing)
removeDirectory('./cache', { recursive: true, force: true })

removeTrailingSlash('src/components/')
// => 'src/components'

removeTrailingSlash('path\\to\\dir\\')
// => 'path\\to\\dir'

setGlobalLogLevel('debug')
// ... perform debugging ...
resetGlobalLogLevel()
// Global override removed, loggers use individual levels

const configPath = resolveFromWorkspace('/workspace', 'config', 'app.json')
// => '/workspace/config/app.json'

const absPath = resolvePath('src', 'components', 'Button.tsx')
// => '/workspace/project/src/components/Button.tsx'

const realPath = resolveRealPath('./node_modules/.bin/tsc')
// => '/workspace/node_modules/typescript/bin/tsc'

const config = { apiKey: 'secret123', endpoint: 'https://api.example.com' }
const safe = sanitize(config)
// => { apiKey: '[REDACTED]', endpoint: 'https://api.example.com' }

import { setGlobalLogLevel } from '@hyperfrontend/project-scope/core'

// Enable debug logging for all project-scope modules
setGlobalLogLevel('debug')

const withBom = '\ufeffHello World'
const clean = stripBom(withBom)
// => 'Hello World'

const buffer = Buffer.from('Hello', 'utf-8')
const text = toUtf8(buffer)
// => 'Hello'

// Find first directory containing a README
const readmeDir = traverseUpward('./src/utils', (dir) =>
  existsSync(join(dir, 'README.md'))
)
// => '/project' or null

const myCache = createCache<string, number>({ name: 'temp-cache' })
const wasRemoved = unregisterCache(myCache)
// => true

const imageBuffer = Buffer.from([0x89, 0x50, 0x4e, 0x47])
writeFileBuffer('./output/image.png', imageBuffer)

import { writeFileContent } from '@hyperfrontend/project-scope'

// Write a simple text file
writeFileContent('./output/data.txt', 'Hello, World!')

// Write with custom encoding
writeFileContent('./output/data.txt', 'Content', { encoding: 'utf-8' })

import { writeJsonFile } from '@hyperfrontend/project-scope'

// Write object to JSON file
writeJsonFile('./config.json', { port: 3000, debug: true })

// Write with custom indentation
writeJsonFile('./config.json', data, { indent: 4 })