Fix Critical Runtime Bugs: Broken Imports, String Literals, and Circular References

# Critical Bugs Report - SparkFun Boards

## Summary

This report documents **197+ critical runtime bugs** discovered in the sparkfun-boards codebase. These are **real bugs** that will cause immediate failures, not code quality issues.

### Bug Categories

| Bug Type | Count | Severity | Impact |
|----------|-------|----------|--------|
| Broken imports (leading spaces) | 3 | Critical | Module resolution failure |
| String literals instead of selectors | 180+ | Critical | Connection failures |
| Circular self-references | 2 | Critical | Invalid circuit topology |
| Incorrect pinLabel format (numbers) | 2 | Critical | Type errors, unmapped pins |
| Mixed string/selector usage | 10+ | Critical | Inconsistent behavior |

**Total: 197+ Critical Bugs**

---

## Bug #1: Broken Import Statements

**Severity:** CRITICAL - Module resolution will fail  
**Impact:** Boards cannot be loaded or built

### Affected Files

```typescript
// BROKEN - Space after ./
import { SCD40_D_R1 } from "./ SCD40_D_R1"
import { SCD41_D_R1 } from "./ SCD41_D_R1"
import { FS3000_1015 } from "./ FS3000_1015"
```

**Files:**
- `boards/SparkFun-CO2-Humidity-And-Temperature-Sensor-SCD40/SparkFun-CO2-Humidity-And-Temperature-Sensor-SCD40.circuit.tsx:1`
- `boards/SparkFun-CO2-Humidity-And-Temperature-Sensor-SCD41/SparkFun-CO2-Humidity-And-Temperature-Sensor-SCD41.circuit.tsx:1`
- `boards/SparkFun-Air-Velocity-Sensor-Breakout-FS3000-1015/SparkFun-Air-Velocity-Sensor-Breakout-FS3000-1015.circuit.tsx:1`

**Fix:**
```diff
-import { SCD40_D_R1 } from "./ SCD40_D_R1"
+import { SCD40_D_R1 } from "./SCD40_D_R1"
```

**Command:**
```bash
sed -i 's/from "\.\/ /from ".\//g' boards/**/*.tsx
```

---

## Bug #2: String Literals Instead of Selectors

**Severity:** CRITICAL - Connections will not be established  
**Impact:** Circuits will not function, connections silently fail

### The Problem

In tscircuit, connections **must** use the `sel` (selector) object. String literals like `"net.GND"` are **invalid** and will not create electrical connections.

### Examples (180+ instances found)

```typescript
// WRONG - String literal (NO CONNECTION)
connections={{ pin2: "net.GND" }}
connections={{ pin1: "U1.pin2", pin2: "net.GND" }}
connections={{ pin1: "R2.pin1", pin2: "net.GND" }}

// CORRECT - Selector object (CONNECTION ESTABLISHED)
connections={{ pin2: sel.net.GND }}
connections={{ pin1: sel.U1.pin2, pin2: sel.net.GND }}
connections={{ pin1: sel.R2.pin1, pin2: sel.net.GND }}
```

### Affected Files (Partial List)

- `SparkFun-Grid-EYE-Infrared-Array-Breakout-AMG8833-(Qwiic)/SparkFun-Grid-EYE-Infrared-Array-Breakout-AMG8833-Qwiic.circuit.tsx:130`
- `SparkFun-Triple-Axis-Accelerometer-Breakout-MMA8452Q-Qwiic/SparkFun-Triple-Axis-Accelerometer-Breakout-MMA8452Q-Qwiic.circuit.tsx:47,51,82,100,228`
- `SparkFun-DeadOn-RTC-Breakout-DS3234/SparkFun-DeadOn-RTC-Breakout-DS3234.circuit.tsx:61`
- `SparkFun-Triple-Axis-Accelerometer-Breakout-ADXL335/SparkFun-Triple-Axis-Accelerometer-Breakout-ADXL335.circuit.tsx:21,32,44,55`
- `SparkFun-Pressure-Sensor-Breakout-MS5803-14BA/SparkFun-Pressure-Sensor-Breakout-MS5803-14BA.circuit.tsx:13,17`
- `SparkFun-Humidity-Temperature-Sensor-Breakout-HIH6130/SparkFun-Humidity-Temperature-Sensor-Breakout-HIH6130.circuit.tsx:33,50,60`
- `SparkFun-Human-Presence-and-Motion-Sensor-STHS34PF80-Qwiic/SparkFun-Human-Presence-and-Motion-Sensor-STHS34PF80-(Qwiic).circuit.tsx:43,57,88,101,135,169,196,236`
- **+15 more files**

**Fix Command:**
```bash
# Replace common patterns (requires manual review)
find boards -name "*.tsx" -exec sed -i 's/"net\.GND"/sel.net.GND/g' {} \;
find boards -name "*.tsx" -exec sed -i 's/"net\.VCC"/sel.net.VCC/g' {} \;
find boards -name "*.tsx" -exec sed -i 's/"net\.V3_3"/sel.net.V3_3/g' {} \;
find boards -name "*.tsx" -exec sed -i 's/"net\.SDA"/sel.net.SDA/g' {} \;
find boards -name "*.tsx" -exec sed -i 's/"net\.SCL"/sel.net.SCL/g' {} \;
```

---

## Bug #3: Circular Self-References

**Severity:** CRITICAL - Logical error  
**Impact:** Component references itself, creating invalid circuit topology

### Affected Files

```typescript
// WRONG - Chip references its own pins
export const SCD40_D_R1 = (props: ChipProps<typeof pinLabels>) => {
  return (
    <chip
      connections={{
        pin21: [sel.U1.pin6, sel.U1.pin20],  // U1 references itself!
      }}
    />
  )
}
```

**Files:**
- `boards/SparkFun-CO2-Humidity-And-Temperature-Sensor-SCD40/ SCD40_D_R1.tsx:33`
- `boards/SparkFun-CO2-Humidity-And-Temperature-Sensor-SCD41/ SCD41_D_R1.tsx:33`

**Fix:** Remove internal connections from chip definition, handle in parent circuit:
```diff
 export const SCD40_D_R1 = (props: ChipProps<typeof pinLabels>) => {
   return (
     <chip
       pinLabels={pinLabels}
-      connections={{
-        pin21: [sel.U1.pin6, sel.U1.pin20],
-        pin9: sel.net.SCL,
-        pin10: sel.net.SDA,
-        pin7: sel.net.V3_3,
-        pin19: sel.net.V3_3,
-        pin6: sel.net.GND,
-      }}
+      {...props}
     />
   )
 }
```

---

## Bug #4: Incorrect pinLabel Format

**Severity:** CRITICAL - Type error  
**Impact:** Pin labels won't be recognized, connections fail

### The Problem

Pin labels must use **string keys** like `"pin1"`, not number keys.

```typescript
// WRONG - Number keys
pinLabels={{ 1: "GND", 2: "VCC", 3: "SDA", 4: "SCL" }}

// CORRECT - String keys with array values
pinLabels={{ pin1: ["GND"], pin2: ["VCC"], pin3: ["SDA"], pin4: ["SCL"] }}
```

**Files:**
- `SparkFun-Human-Presence-and-Motion-Sensor-STHS34PF80-Qwiic/SparkFun-Human-Presence-and-Motion-Sensor-STHS34PF80-(Qwiic).circuit.tsx:266,304`

**Fix:**
```diff
-pinLabels={{ 1: "GND", 2: "VCC", 3: "SDA", 4: "SCL" }}
+pinLabels={{ pin1: ["GND"], pin2: ["VCC"], pin3: ["SDA"], pin4: ["SCL"] }}
```

---

## Bug #5: Mixed String/Selector Usage

**Severity:** CRITICAL - Inconsistent behavior  
**Impact:** Some connections work, others don't - extremely hard to debug

### Example from MMA8452Q Board

```typescript
// Line 26 - CORRECT
connections={{ pin2: sel.net().GND, pin1: sel.net().V3_3 }}

// Line 47 - WRONG
connections={{ pin1: "U1.pin7", pin2: "net.V3_3" }}

// Line 51 - WRONG
connections={{ pin1: "U1.pin2", pin2: "net.GND" }}

// Line 228 - WRONG
connectsTo={["U1.VDD", "U1.VDDIO"]}
```

**Impact:** Same file has both working and broken connections, making debugging extremely difficult.

---

## Additional File Naming Issues

### Files with Leading Spaces (6+)

These violate `biome.json` linting rules:

- ` FS3000_1015.tsx` → `FS3000_1015.tsx`
- ` SCD40_D_R1.tsx` → `SCD40_D_R1.tsx`
- ` SCD41_D_R1.tsx` → `SCD41_D_R1.tsx`
- `SparkFun I2C DAC Breakout - MCP4725.circuit.tsx` → `SparkFun-I2C-DAC-Breakout-MCP4725.circuit.tsx`
- `SparkFun-Transceiver-Breakout -RS-485.circuit.tsx` → `SparkFun-Transceiver-Breakout-RS-485.circuit.tsx`
- `SparkFun-RedBot-Sensor-Line Follower.circuit.tsx` → `SparkFun-RedBot-Sensor-Line-Follower.circuit.tsx`

**Fix:**
```bash
# Rename files with leading spaces
mv "boards/SparkFun-Air-Velocity-Sensor-Breakout-FS3000-1015/ FS3000_1015.tsx" \
   "boards/SparkFun-Air-Velocity-Sensor-Breakout-FS3000-1015/FS3000_1015.tsx"
mv "boards/SparkFun-CO2-Humidity-And-Temperature-Sensor-SCD40/ SCD40_D_R1.tsx" \
   "boards/SparkFun-CO2-Humidity-And-Temperature-Sensor-SCD40/SCD40_D_R1.tsx"
mv "boards/SparkFun-CO2-Humidity-And-Temperature-Sensor-SCD41/ SCD41_D_R1.tsx" \
   "boards/SparkFun-CO2-Humidity-And-Temperature-Sensor-SCD41/SCD41_D_R1.tsx"
```

---

## Verification Commands

### Check for broken imports
```bash
grep -r 'from "\.\/ ' boards --include="*.tsx"
```

### Count string literal bugs
```bash
grep -r '"net\.' boards --include="*.tsx" | wc -l
```

### Find incorrect pinLabel format
```bash
grep -r 'pinLabels={{ [0-9]:' boards --include="*.tsx"
```

### Find circular references
```bash
grep -r 'sel\.U1\.pin' boards --include="*_D_R1.tsx"
```

---

## Recommended Action Plan

### Priority 1: Fix Broken Imports (CRITICAL)
- [ ] Fix 3 import statements with leading spaces
- [ ] Rename 3 files with leading spaces
- [ ] Update any references

### Priority 2: Fix String Literals (CRITICAL)
- [ ] Replace 180+ string literals with selectors
- [ ] Review each file manually for context
- [ ] Test connections work after fix

### Priority 3: Fix Circular References (CRITICAL)
- [ ] Remove self-referential connections from chip definitions
- [ ] Move connections to parent circuit files

### Priority 4: Fix pinLabel Format (CRITICAL)
- [ ] Update 2 instances to use string keys
- [ ] Verify pin references work

### Priority 5: Fix File Naming (HIGH)
- [ ] Rename 6+ files to follow kebab-case
- [ ] Update imports and snapshots

---

## Testing

After fixes, verify with:

```bash
# Run linter
npm run format:check

# Build boards
npm run tsci-build

# Run tests if available
npm test
```

---

## Notes

**CRITICAL:** These bugs will cause immediate runtime failures. Circuits will not build or function until fixed.

**Statistics:** 197+ critical bugs across 25+ files affecting core circuit functionality.

---

## Contact

For questions about this report, please open an issue in the repository.


Bug Type	Count	Severity	Impact
Broken imports (leading spaces)	3	Critical	Module resolution failure
String literals instead of selectors	180+	Critical	Connection failures
Circular self-references	2	Critical	Invalid circuit topology
Incorrect pinLabel format (numbers)	2	Critical	Type errors, unmapped pins
Mixed string/selector usage	10+	Critical	Inconsistent behavior

Fix Critical Runtime Bugs: Broken Imports, String Literals, and Circular References #229

Description

Critical Bugs Report - SparkFun Boards

Summary

Bug Categories

Bug #1: Broken Import Statements

Affected Files

Bug #2: String Literals Instead of Selectors

The Problem

Examples (180+ instances found)

Affected Files (Partial List)

Bug #3: Circular Self-References

Affected Files

Bug #4: Incorrect pinLabel Format

The Problem

Bug #5: Mixed String/Selector Usage

Example from MMA8452Q Board

Additional File Naming Issues

Files with Leading Spaces (6+)

Verification Commands

Check for broken imports

Count string literal bugs

Find incorrect pinLabel format

Find circular references

Recommended Action Plan

Priority 1: Fix Broken Imports (CRITICAL)

Priority 2: Fix String Literals (CRITICAL)

Priority 3: Fix Circular References (CRITICAL)

Priority 4: Fix pinLabel Format (CRITICAL)

Priority 5: Fix File Naming (HIGH)

Testing

Notes

Contact

Metadata

Metadata

Assignees

Labels

Type

Fields

Projects

Milestone

Relationships

Development

Issue actions