soulcraft/brainy
1
0
Fork 0
Code Issues 1 Pull requests Projects Releases 335 Packages Wiki Activity Actions

feat: add import API validation and v4.x migration guide

Browse source 
Add comprehensive migration support for v4.x import API changes:

- Runtime validation that rejects deprecated v3.x options with clear errors
- Configurable error verbosity (detailed in dev, concise in prod)
- Complete migration guide (docs/guides/migrating-to-v4.md)
- Enhanced CHANGELOG with breaking changes documentation
- TypeScript type safety using 'never' types for deprecated options
- Comprehensive JSDoc with deprecation warnings and examples

Deprecated v3.x options now throw helpful errors:
- extractRelationships → enableRelationshipInference
- createFileStructure → vfsPath
- autoDetect → (removed - always enabled)
- excelSheets → (removed - all sheets processed)
- pdfExtractTables → (removed - always enabled)

Resolves Workshop team import issues where incorrect option names
disabled all intelligent features, causing generic entity creation.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
David Snelling 2025-10-21 15:25:12 -07:00
parent 1001af9a34
commit a1a0576d04
4 changed files with 822 additions and 24 deletions
Download patch file Download diff file Expand all files Collapse all files

102
CHANGELOG.md
View file

@ -223,22 +223,110 @@ $ brainy import ./research-papers --extract-concepts --progress
### ⚠️ Breaking Changes
**NONE** - v4.0.0 is 100% backward compatible!
#### 💥 Import API Redesign
All v4.0.0 features are:
The import API has been redesigned for clarity and better feature control. **Old v3.x option names are no longer recognized** and will throw errors.
**What Changed:**
| v3.x Option | v4.x Option | Action Required |
|-------------|-------------|-----------------|
| `extractRelationships` | `enableRelationshipInference` | **Rename option** |
| `autoDetect` | *(removed)* | **Delete option** (always enabled) |
| `createFileStructure` | `vfsPath` | **Replace** with VFS path |
| `excelSheets` | *(removed)* | **Delete option** (all sheets processed) |
| `pdfExtractTables` | *(removed)* | **Delete option** (always enabled) |
| - | `enableNeuralExtraction` | **Add option** (new in v4.x) |
| - | `enableConceptExtraction` | **Add option** (new in v4.x) |
| - | `preserveSource` | **Add option** (new in v4.x) |
**Why These Changes?**
1. **Clearer option names**: `enableRelationshipInference` explicitly indicates AI-powered relationship inference
2. **Separation of concerns**: Neural extraction, relationship inference, and VFS are now separate, explicit options
3. **Better defaults**: Auto-detection and AI features are enabled by default
4. **Reduced confusion**: Removed redundant options like `autoDetect` and format-specific options
**Migration Examples:**
<details>
<summary>Example 1: Basic Excel Import</summary>
```typescript
// v3.x (OLD - Will throw error)
await brain.import('./glossary.xlsx', {
extractRelationships: true,
createFileStructure: true
})
// v4.x (NEW - Use this)
await brain.import('./glossary.xlsx', {
enableRelationshipInference: true,
vfsPath: '/imports/glossary'
})
```
</details>
<details>
<summary>Example 2: Full-Featured Import</summary>
```typescript
// v3.x (OLD - Will throw error)
await brain.import('./data.xlsx', {
extractRelationships: true,
autoDetect: true,
createFileStructure: true
})
// v4.x (NEW - Use this)
await brain.import('./data.xlsx', {
enableNeuralExtraction: true, // Extract entity names
enableRelationshipInference: true, // Infer semantic relationships
enableConceptExtraction: true, // Extract entity types
vfsPath: '/imports/data', // VFS directory
preserveSource: true // Save original file
})
```
</details>
**Error Messages:**
If you use old v3.x options, you'll get a clear error message:
```
❌ Invalid import options detected (Brainy v4.x breaking changes)
The following v3.x options are no longer supported:
❌ extractRelationships
→ Use: enableRelationshipInference
→ Why: Option renamed for clarity in v4.x
📖 Migration Guide: https://brainy.dev/docs/guides/migrating-to-v4
```
**Other v4.0.0 Features (Non-Breaking):**
All other v4.0.0 features are:
- ✅ Opt-in (lifecycle, compression, batch operations)
- ✅ Additive (new CLI commands, new methods)
- ✅ Non-breaking (existing code continues to work)
### 📝 Migration
**No migration required!** All v4.0.0 features are optional enhancements.
**Import API migration required** if you use `brain.import()` with the old v3.x option names.
To use new features:
#### Required Changes:
1. Update to v4.0.0: `npm install @soulcraft/brainy@4.0.0`
2. Enable lifecycle policies: `brainy storage lifecycle set`
3. Use batch operations: `brainy storage batch-delete entities.txt`
4. See `docs/MIGRATION-V3-TO-V4.md` for full feature documentation
2. Update import calls to use new option names (see table above)
3. Test your imports - you'll get clear error messages if you use old options
#### Optional Enhancements:
- Enable lifecycle policies: `brainy storage lifecycle set`
- Use batch operations: `brainy storage batch-delete entities.txt`
- See full migration guide: `docs/guides/migrating-to-v4.md`
**Complete Migration Guide:** [docs/guides/migrating-to-v4.md](./docs/guides/migrating-to-v4.md)
### 🎓 What This Means

491
docs/guides/migrating-to-v4.md Normal file
View file

@ -0,0 +1,491 @@
# Migrating from Brainy v3.x to v4.x
**Brainy v4.0.0** introduces breaking changes to the import API for improved clarity, better defaults, and more powerful features.
This guide will help you migrate your code quickly and painlessly.
---
## 🎯 Quick Migration Checklist
If you just want to fix your code fast, here's what to do:
- [ ] Replace `extractRelationships` with `enableRelationshipInference`
- [ ] Remove `autoDetect` (auto-detection is now always enabled)
- [ ] Replace `createFileStructure: true` with `vfsPath: '/your/path'`
- [ ] Remove `excelSheets` (all sheets are now processed automatically)
- [ ] Remove `pdfExtractTables` (table extraction is now automatic)
- [ ] Add `enableNeuralExtraction: true` to enable AI entity extraction
- [ ] Add `preserveSource: true` if you want to keep the original file
---
## 📋 Option Name Changes
### Complete Mapping Table
| v3.x Option | v4.x Option | Action Required |
|-------------|-------------|-----------------|
| `extractRelationships` | `enableRelationshipInference` | **Rename option** |
| `autoDetect` | *(removed)* | **Delete option** (always enabled) |
| `createFileStructure` | `vfsPath` | **Replace** with VFS directory path |
| `excelSheets` | *(removed)* | **Delete option** (all sheets processed) |
| `pdfExtractTables` | *(removed)* | **Delete option** (always enabled) |
| - | `enableNeuralExtraction` | **Add option** (new in v4.x) |
| - | `enableConceptExtraction` | **Add option** (new in v4.x) |
| - | `preserveSource` | **Add option** (new in v4.x) |
---
## 🔄 Migration Examples
### Example 1: Basic Excel Import
**Before (v3.x):**
```typescript
const result = await brain.import('./glossary.xlsx', {
extractRelationships: true,
createFileStructure: true,
groupBy: 'type'
})
```
**After (v4.x):**
```typescript
const result = await brain.import('./glossary.xlsx', {
enableRelationshipInference: true, // ✅ Renamed
vfsPath: '/imports/glossary', // ✅ Replaced createFileStructure
groupBy: 'type' // ✅ No change
})
```
---
### Example 2: Full-Featured Import
**Before (v3.x):**
```typescript
const result = await brain.import('./data.xlsx', {
extractRelationships: true,
autoDetect: true,
createFileStructure: true,
groupBy: 'type',
enableDeduplication: true
})
```
**After (v4.x):**
```typescript
const result = await brain.import('./data.xlsx', {
// AI features
enableNeuralExtraction: true, // ✅ NEW - Extract entity names
enableRelationshipInference: true, // ✅ Renamed from extractRelationships
enableConceptExtraction: true, // ✅ NEW - Extract entity types
// VFS features
vfsPath: '/imports/data', // ✅ Replaced createFileStructure
groupBy: 'type', // ✅ No change
preserveSource: true, // ✅ NEW - Save original file
// Performance
enableDeduplication: true // ✅ No change
})
```
---
### Example 3: Simple Import (Defaults)
**Before (v3.x):**
```typescript
const result = await brain.import('./data.csv', {
autoDetect: true,
extractRelationships: true
})
```
**After (v4.x):**
```typescript
// Auto-detection is always enabled now
// Just enable the features you want
const result = await brain.import('./data.csv', {
enableRelationshipInference: true
})
// Or use all defaults (AI features enabled)
const result = await brain.import('./data.csv')
```
---
### Example 4: PDF Import
**Before (v3.x):**
```typescript
const result = await brain.import('./document.pdf', {
pdfExtractTables: true,
extractRelationships: true,
createFileStructure: true
})
```
**After (v4.x):**
```typescript
const result = await brain.import('./document.pdf', {
// pdfExtractTables removed - always enabled
enableRelationshipInference: true,
vfsPath: '/imports/documents'
})
```
---
## 💡 Why These Changes?
### Clearer Option Names
**v3.x naming was ambiguous:**
- `extractRelationships` → Could mean "create relationships" or "infer relationships"
- `createFileStructure` → Doesn't explain what structure or where
**v4.x naming is explicit:**
- `enableRelationshipInference` → Clearly means "use AI to infer semantic relationships"
- `vfsPath` → Explicitly sets the virtual filesystem directory path
- `enableNeuralExtraction` → Clearly indicates AI-powered entity extraction
### Separation of Concerns
**v4.x separates import features into clear categories:**
1. **Neural/AI Features:**
- `enableNeuralExtraction` - Extract entity names and metadata
- `enableRelationshipInference` - Infer semantic relationships
- `enableConceptExtraction` - Extract entity types and concepts
2. **VFS Features:**
- `vfsPath` - Virtual filesystem directory
- `groupBy` - Grouping strategy
- `preserveSource` - Keep original file
3. **Performance Features:**
- `enableDeduplication` - Merge similar entities
- `confidenceThreshold` - AI confidence threshold
- `onProgress` - Progress callbacks
### Better Defaults
**v3.x required explicit enabling:**
```typescript
// Had to enable everything manually
await brain.import(file, {
autoDetect: true,
extractRelationships: true,
createFileStructure: true
})
```
**v4.x has smart defaults:**
```typescript
// Auto-detection and AI features enabled by default
await brain.import(file)
// Or customize specific features
await brain.import(file, {
vfsPath: '/my/data',
confidenceThreshold: 0.8
})
```
---
## 🆕 New Features in v4.x
### Neural Entity Extraction
Extract entity names, types, and metadata using AI:
```typescript
const result = await brain.import('./glossary.xlsx', {
enableNeuralExtraction: true, // Extract entity names from "Term" column
enableConceptExtraction: true, // Detect entity types (Place, Person, etc.)
confidenceThreshold: 0.7 // Minimum AI confidence (0-1)
})
// Result includes rich entity metadata
result.entities.forEach(entity => {
console.log(`${entity.name} (${entity.type})`)
console.log(`Confidence: ${entity.confidence}`)
})
```
### VFS Integration
Imported data is organized in a virtual filesystem:
```typescript
const result = await brain.import('./data.xlsx', {
vfsPath: '/projects/myproject/data',
groupBy: 'type', // Group by entity type
preserveSource: true // Save original .xlsx file
})
// Access via VFS
const vfs = brain.vfs()
const files = await vfs.readdir('/projects/myproject/data')
// ['Places/', 'Characters/', 'Concepts/', '_source.xlsx', '_metadata.json']
// Read entity file
const content = await vfs.readFile('/projects/myproject/data/Places/Talifar.json')
```
### Semantic Relationship Inference
AI infers relationship types from context:
```typescript
const result = await brain.import('./glossary.xlsx', {
enableRelationshipInference: true
})
// Instead of generic "contains" relationships,
// you get semantic verbs like:
// - "capital_of"
// - "located_in"
// - "guards"
// - "part_of"
// - "related_to"
const relations = await brain.getRelations({ limit: 100 })
const types = new Set(relations.map(r => r.label))
console.log(types)
// Set { 'capital_of', 'guards', 'located_in', 'related_to' }
```
---
## 🔍 What Breaks & How to Fix It
### Error: "Invalid import options: 'extractRelationships'"
**Cause:** Using v3.x option name
**Fix:**
```typescript
// Before
await brain.import(file, { extractRelationships: true })
// After
await brain.import(file, { enableRelationshipInference: true })
```
---
### Error: "Invalid import options: 'autoDetect'"
**Cause:** Using v3.x option that's been removed
**Fix:**
```typescript
// Before
await brain.import(file, { autoDetect: true })
// After - just remove it (auto-detection always enabled)
await brain.import(file)
```
---
### Error: "Invalid import options: 'createFileStructure'"
**Cause:** Using v3.x option name
**Fix:**
```typescript
// Before
await brain.import(file, { createFileStructure: true })
// After - specify VFS path explicitly
await brain.import(file, { vfsPath: '/imports/mydata' })
```
---
### Issue: Import succeeds but entities have generic names like "Entity_144"
**Cause:** Neural extraction is disabled
**Fix:**
```typescript
// Ensure AI features are enabled
await brain.import(file, {
enableNeuralExtraction: true, // ✅ Extract entity names
enableRelationshipInference: true, // ✅ Infer relationships
enableConceptExtraction: true // ✅ Extract types
})
```
---
### Issue: All relationships are type "contains"
**Cause:** Relationship inference is disabled
**Fix:**
```typescript
// Enable relationship inference
await brain.import(file, {
enableRelationshipInference: true // ✅ Use AI to detect semantic relationships
})
```
---
### Issue: VFS directory doesn't exist in filesystem
**This is NORMAL!** VFS is virtual - it uses Brainy entities, not physical files.
**How to access VFS:**
```typescript
// DON'T do this:
// ls brainy-data/vfs/ ❌ Won't work
// DO this instead:
const vfs = brain.vfs()
await vfs.init()
const files = await vfs.readdir('/imports') // ✅ Correct
```
---
## 📦 TypeScript Users
### Compile-Time Errors
If you're using TypeScript, you'll get compile-time errors when using deprecated options:
```typescript
// TypeScript will show error:
// "Type 'true' is not assignable to type 'never'"
await brain.import(file, {
extractRelationships: true // ❌ Type error
})
// Fix: Use correct option name
await brain.import(file, {
enableRelationshipInference: true // ✅ Type correct
})
```
### IDE Autocomplete
Your IDE will show deprecation warnings and suggest the correct option names:
```typescript
await brain.import(file, {
extract... // IDE suggests: enableNeuralExtraction, enableRelationshipInference
})
```
---
## 🎓 Best Practices for v4.x
### 1. Enable All AI Features by Default
```typescript
// Good: Enable all intelligent features
await brain.import('./data.xlsx', {
enableNeuralExtraction: true,
enableRelationshipInference: true,
enableConceptExtraction: true,
vfsPath: '/imports/data'
})
```
### 2. Use VFS for Organization
```typescript
// Good: Organize by project
await brain.import('./project-A.xlsx', {
vfsPath: '/projects/project-a/data'
})
await brain.import('./project-B.csv', {
vfsPath: '/projects/project-b/data'
})
```
### 3. Preserve Source Files
```typescript
// Good: Keep original files for reference
await brain.import('./important-data.xlsx', {
preserveSource: true, // Saves original .xlsx in VFS
vfsPath: '/archives/2025'
})
```
### 4. Tune Confidence Threshold
```typescript
// For high-quality data: Lower threshold
await brain.import('./curated-glossary.xlsx', {
confidenceThreshold: 0.5 // Extract more entities
})
// For noisy data: Higher threshold
await brain.import('./scraped-data.csv', {
confidenceThreshold: 0.8 // Only high-confidence entities
})
```
### 5. Disable Deduplication for Large Imports
```typescript
// For small imports: Keep deduplication
await brain.import('./small-data.xlsx', {
enableDeduplication: true
})
// For large imports (>1000 rows): Disable for performance
await brain.import('./huge-database.csv', {
enableDeduplication: false // Much faster
})
```
---
## 🚀 Migration Automation (Future)
We're working on an automated migration tool:
```bash
# Coming soon
npx @soulcraft/brainy-migrate
# Will scan your code and automatically update:
# - Option names
# - TypeScript types
# - Import patterns
```
---
## 📚 Additional Resources
- **API Documentation:** [https://brainy.dev/docs/api/import](https://brainy.dev/docs/api/import)
- **Examples:** [examples/import-excel/](../../examples/import-excel/)
- **Changelog:** [CHANGELOG.md](../../CHANGELOG.md)
- **Support:** [GitHub Issues](https://github.com/soulcraft/brainy/issues)
---
## 💬 Need Help?
If you're stuck migrating:
1. Check the error message - it includes migration hints
2. Review the examples in this guide
3. Open an issue on GitHub with your use case
4. Join our Discord community for real-time help
---
**Happy migrating! 🎉**

90
src/brainy.ts
View file

@ -1863,33 +1863,91 @@ export class Brainy<T = any> implements BrainyInterface<T> {
}
/**
* Import files with auto-detection and dual storage (VFS + Knowledge Graph)
* Import files with intelligent extraction and dual storage (VFS + Knowledge Graph)
*
* Unified import system that:
* - Auto-detects format (Excel, PDF, CSV, JSON, Markdown)
* - Extracts entities and relationships
* - Extracts entities with AI-powered name/type detection
* - Infers semantic relationships from context
* - Stores in both VFS (organized files) and Knowledge Graph (connected entities)
* - Links VFS files to graph entities
*
* @example
* // Import from file path
* const result = await brain.import('/path/to/file.xlsx')
* @since 4.0.0
*
* @example
* // Import from buffer
* @example Quick Start (All AI features enabled by default)
* ```typescript
* const result = await brain.import('./glossary.xlsx')
* // Auto-detects format, extracts entities, infers relationships
* ```
*
* @example Full-Featured Import (v4.x)
* ```typescript
* const result = await brain.import('./data.xlsx', {
* // AI features
* enableNeuralExtraction: true, // Extract entity names/metadata
* enableRelationshipInference: true, // Detect semantic relationships
* enableConceptExtraction: true, // Extract types/concepts
*
* // VFS features
* vfsPath: '/imports/my-data', // Store in VFS directory
* groupBy: 'type', // Organize by entity type
* preserveSource: true, // Keep original file
*
* // Progress tracking
* onProgress: (p) => console.log(p.message)
* })
* ```
*
* @example Performance Tuning (Large Files)
* ```typescript
* const result = await brain.import('./huge-file.csv', {
* enableDeduplication: false, // Skip dedup for speed
* confidenceThreshold: 0.8, // Higher threshold = fewer entities
* onProgress: (p) => console.log(`${p.processed}/${p.total}`)
* })
* ```
*
* @example Import from Buffer or Object
* ```typescript
* // From buffer
* const result = await brain.import(buffer, { format: 'pdf' })
*
* @example
* // Import JSON object
* // From object
* const result = await brain.import({ entities: [...] })
* ```
*
* @example
* // Custom VFS path and grouping
* const result = await brain.import(buffer, {
* vfsPath: '/my-imports/data',
* groupBy: 'type',
* onProgress: (progress) => console.log(progress.message)
* })
* @throws {Error} If invalid options are provided (v4.x breaking changes)
*
* @see {@link https://brainy.dev/docs/api/import API Documentation}
* @see {@link https://brainy.dev/docs/guides/migrating-to-v4 Migration Guide}
*
* @remarks
* **⚠️ Breaking Changes from v3.x:**
*
* The import API was redesigned in v4.0.0 for clarity and better feature control.
* Old v3.x option names are **no longer recognized** and will throw errors.
*
* **Option Changes:**
* - ❌ `extractRelationships` → ✅ `enableRelationshipInference`
* - ❌ `createFileStructure` → ✅ `vfsPath: '/your/path'`
* - ❌ `autoDetect` → ✅ *(removed - always enabled)*
* - ❌ `excelSheets` → ✅ *(removed - all sheets processed)*
* - ❌ `pdfExtractTables` → ✅ *(removed - always enabled)*
*
* **New Options:**
* - ✅ `enableNeuralExtraction` - Extract entity names via AI
* - ✅ `enableConceptExtraction` - Extract entity types via AI
* - ✅ `preserveSource` - Save original file in VFS
*
* **If you get an error:**
* The error message includes migration instructions and examples.
* See the complete migration guide for all details.
*
* **Why these changes?**
* - Clearer option names (explicitly describe what they do)
* - Separation of concerns (neural, relationships, VFS are separate)
* - Better defaults (AI features enabled by default)
* - Reduced confusion (removed redundant options)
*/
async import(
source: Buffer | string | object,

163
src/import/ImportCoordinator.ts
View file

@ -36,7 +36,10 @@ export interface ImportSource {
filename?: string
}
export interface ImportOptions {
/**
* Valid import options for v4.x
*/
export interface ValidImportOptions {
/** Force specific format (skip auto-detection) */
format?: SupportedFormat
@ -86,6 +89,51 @@ export interface ImportOptions {
onProgress?: (progress: ImportProgress) => void
}
/**
* Deprecated import options from v3.x
* Using these will cause TypeScript compile errors
*
* @deprecated These options are no longer supported in v4.x
* @see {@link https://brainy.dev/docs/guides/migrating-to-v4 Migration Guide}
*/
export interface DeprecatedImportOptions {
/**
* @deprecated Use `enableRelationshipInference` instead
* @see {@link https://brainy.dev/docs/guides/migrating-to-v4 Migration Guide}
*/
extractRelationships?: never
/**
* @deprecated Removed in v4.x - auto-detection is now always enabled
* @see {@link https://brainy.dev/docs/guides/migrating-to-v4 Migration Guide}
*/
autoDetect?: never
/**
* @deprecated Use `vfsPath` to specify the directory path instead
* @see {@link https://brainy.dev/docs/guides/migrating-to-v4 Migration Guide}
*/
createFileStructure?: never
/**
* @deprecated Removed in v4.x - all sheets are now processed automatically
* @see {@link https://brainy.dev/docs/guides/migrating-to-v4 Migration Guide}
*/
excelSheets?: never
/**
* @deprecated Removed in v4.x - table extraction is now automatic for PDF imports
* @see {@link https://brainy.dev/docs/guides/migrating-to-v4 Migration Guide}
*/
pdfExtractTables?: never
}
/**
* Complete import options interface
* Combines valid v4.x options with deprecated v3.x options (which cause TypeScript errors)
*/
export type ImportOptions = ValidImportOptions & DeprecatedImportOptions
export interface ImportProgress {
stage: 'detecting' | 'extracting' | 'storing-vfs' | 'storing-graph' | 'relationships' | 'complete'
/** Phase of import - extraction or relationship building (v3.49.0) */
@ -211,6 +259,9 @@ export class ImportCoordinator {
const startTime = Date.now()
const importId = uuidv4()
// Validate options (v4.0.0+: Reject deprecated v3.x options)
this.validateOptions(options)
// Normalize source
const normalizedSource = this.normalizeSource(source, options.format)
@ -800,4 +851,114 @@ export class ImportCoordinator {
// Fallback: return as-is
return result
}
/**
* Validate options and reject deprecated v3.x options (v4.0.0+)
* Throws clear errors with migration guidance
*/
private validateOptions(options: any): void {
const invalidOptions: Array<{ old: string; new: string; message: string }> = []
// Check for v3.x deprecated options
if ('extractRelationships' in options) {
invalidOptions.push({
old: 'extractRelationships',
new: 'enableRelationshipInference',
message: 'Option renamed for clarity in v4.x - explicitly indicates AI-powered relationship inference'
})
}
if ('autoDetect' in options) {
invalidOptions.push({
old: 'autoDetect',
new: '(removed)',
message: 'Auto-detection is now always enabled - no need to specify this option'
})
}
if ('createFileStructure' in options) {
invalidOptions.push({
old: 'createFileStructure',
new: 'vfsPath',
message: 'Use vfsPath to explicitly specify the virtual filesystem directory path'
})
}
if ('excelSheets' in options) {
invalidOptions.push({
old: 'excelSheets',
new: '(removed)',
message: 'All sheets are now processed automatically - no configuration needed'
})
}
if ('pdfExtractTables' in options) {
invalidOptions.push({
old: 'pdfExtractTables',
new: '(removed)',
message: 'Table extraction is now automatic for PDF imports'
})
}
// If invalid options found, throw error with detailed message
if (invalidOptions.length > 0) {
const errorMessage = this.buildValidationErrorMessage(invalidOptions)
throw new Error(errorMessage)
}
}
/**
* Build detailed error message for invalid options
* Respects LOG_LEVEL for verbosity (detailed in dev, concise in prod)
*/
private buildValidationErrorMessage(
invalidOptions: Array<{ old: string; new: string; message: string }>
): string {
// Check environment for verbosity level
const verbose =
process.env.LOG_LEVEL === 'debug' ||
process.env.LOG_LEVEL === 'verbose' ||
process.env.NODE_ENV === 'development' ||
process.env.NODE_ENV === 'dev'
if (verbose) {
// DETAILED mode (development)
const optionDetails = invalidOptions
.map(
(opt) => `
❌ ${opt.old}
→ Use: ${opt.new}
→ Why: ${opt.message}`
)
.join('\n')
return `
❌ Invalid import options detected (Brainy v4.x breaking changes)
The following v3.x options are no longer supported:
${optionDetails}
📖 Migration Guide: https://brainy.dev/docs/guides/migrating-to-v4
💡 Quick Fix Examples:
Before (v3.x):
await brain.import(file, {
extractRelationships: true,
createFileStructure: true
})
After (v4.x):
await brain.import(file, {
enableRelationshipInference: true,
vfsPath: '/imports/my-data'
})
🔗 Full API docs: https://brainy.dev/docs/api/import
`.trim()
} else {
// CONCISE mode (production)
const optionsList = invalidOptions.map((o) => `'${o.old}'`).join(', ')
return `Invalid import options: ${optionsList}. See https://brainy.dev/docs/guides/migrating-to-v4`
}
}
}