smiles-js 1.0.2 → 1.0.4

package/IMPLEMENTATION_STATUS.md

@@ -1,464 +1,63 @@
 # Implementation Status
 
-## ✅ FIXED: Double Bonds in Rings Now Preserved
-
-**Double bonds in rings are now correctly preserved during parsing/regeneration.**
-
-```
-Input:  C1=CC=CC=C1   →   Output: C1=CC=CC=C1   (bonds PRESERVED)
-```
-
-### Naphthalene - WORKS
-```
-Input:  C1=CC2=CC=CC=C2C=C1
-Output: C1=CC2=CC=CC=C2C=C1
-```
-
-### Simple Benzimidazole - WORKS
-```
-Input:  C1=NC2=CC=CC=C2N1
-Output: C1=NC2=CC=CC=C2N1
-```
-
----
-
-## ✅ FIXED: Rings Inside Branches
-
-**Rings that appear inside branches (as attachments) are now correctly parsed and regenerated.**
-
-### Biphenyl in branch - WORKS
-```
-Input:  c1ccc(c2ccccc2)cc1
-Output: c1ccc(c2ccccc2)cc1
-```
-
-### Fused ring inside branch - WORKS
-```
-Input:  C(c1nc2ccccc2n1)C
-Output: C(c1nc2ccccc2n1)C
-```
-
-### Nested fused ring with trailing atom - WORKS
-```
-Input:  c1ccc(C5=NC6=CC=CC=C6N5C)cc1
-Output: c1ccc(C5=NC6=CC=CC=C6N5C)cc1
-```
-
----
-
-## ✅ FIXED: Ring Closures Inside Branches
-
-**Ring closures that occur at different branch depths than where the ring opened are now handled correctly.**
-
-### Ring closure inside branch of ring - WORKS
-```
-Input:  C1=NC2=C(CC2N1)C
-Output: C1=NC2=C(CC2N1)C
-```
-
-### Simple ring closure at different depth - WORKS
-```
-Input:  C1CC(C1)
-Output: C1CCC1   (canonical cyclobutane)
-```
-
-### Piperidine with ring closure in branch - WORKS
-```
-Input:  C1CCN(CC1)C
-Output: C1CCN(CC1)C
-```
-
----
-
-## ✅ FIXED: Full Telmisartan Structure
-
-**The full telmisartan molecule with deeply nested ring systems now parses and round-trips correctly.**
-
-### Telmisartan - WORKS
-```
-Input:  CCCC1=NC2=C(C=C(C=C2N1CC3=CC=C(C=C3)C4=CC=CC=C4C(=O)O)C5=NC6=CC=CC=C6N5C)C
-Output: CCCC1=NC2=C(C=C(C=C2N1CC3=CC=C(C=C3)C4=CC=CC=C4C(=O)O)C5=NC6=CC=CC=C6N5C)C
-```
-
----
-
-## ✅ FIXED: Steroid Polycyclic Structures
-
-**Complex polycyclic steroids with shared atoms now parse correctly. Fixed duplicate attachment bug on shared fused ring atoms.**
-
-### Cortisone - WORKS
-```
-Input:  CC12CCC(=O)C=C1CCC1C2C(O)CC2(C)C(C(=O)CO)CCC12
-Output: CC12CCC(=O)C=C1CCC1C2C(O)CC2(C)C(C(=O)CO)CCC12
-```
-
-### Hydrocortisone - WORKS
-```
-Input:  CC12CCC(=O)C=C1CCC1C2C(O)CC2(C)C(C(=O)CO)CCC12O
-Output: CC12CCC(=O)C=C1CCC1C2C(O)CC2(C)C(C(=O)CO)CCC12O
-```
-
-### Prednisone - WORKS
-```
-Input:  CC12CC(=O)C=CC1=CC(O)C1C2CCC2(C)C(C(=O)CO)CCC12
-Output: CC12CC(=O)C=CC1=CC(O)C1C2CCC2(C)C(C(=O)CO)CCC12
-```
-
-### Prednisolone - WORKS
-```
-Input:  CC12CC(=O)C=CC1=CC(O)C1C2C(O)CC2(C)C(C(=O)CO)CCC12
-Output: CC12CC(=O)C=CC1=CC(O)C1C2C(O)CC2(C)C(C(=O)CO)CCC12
-```
-
-### Methylprednisolone - WORKS
-```
-Input:  CC12CC(=O)C(C)=CC1=CC(O)C1C2C(O)CC2(C)C(C(=O)CO)CCC12
-Output: CC12CC(=O)C(C)=CC1=CC(O)C1C2C(O)CC2(C)C(C(=O)CO)CCC12
-```
-
-### Dexamethasone - WORKS
-```
-Input:  CC1CC2C3CCC4=CC(=O)C=CC4(C)C3(F)C(O)CC2(C)C1(O)C(=O)CO
-Output: CC1CC2C3CCC4=CC(=O)C=CC4(C)C3(F)C(O)CC2(C)C1(O)C(=O)CO
-```
-
----
-
-## ✅ FIXED: Opioids (Piperidine-based)
-
-**Opioids with piperidine rings that close inside branches now work correctly.**
-
-### Fentanyl - WORKS
-```
-Input:  CCC(=O)N(C1CCN(CC1)CCC2=CC=CC=C2)C3=CC=CC=C3
-Output: CCC(=O)N(C1CCN(CC1)CCC2=CC=CC=C2)C3=CC=CC=C3
-```
-
-### Tramadol - WORKS
-```
-Input:  CN(C)CC1CCCCC1(C2=CC(=CC=C2)OC)O
-Output: CN(C)CC1CCCCC1(C2=CC(=CC=C2)OC)O
-```
-
----
-
-## ✅ FIXED: Linear Chain Double Bonds
-
-**Double bonds in linear chains are now correctly preserved at their original positions.**
-
-### Anandamide - WORKS
-```
-Input:  CCCCCC=CCC=CCC=CCC=CCCCC(=O)NCCO
-Output: CCCCCC=CCC=CCC=CCC=CCCCC(=O)NCCO
-```
-
-### 2-Arachidonoylglycerol - WORKS
-```
-Input:  CCCCCC=CCC=CCC=CCC=CCCCC(=O)OC(CO)CO
-Output: CCCCCC=CCC=CCC=CCC=CCCCC(=O)OC(CO)CO
-```
-
----
-
-## 🟡 Known Limitation: toCode() for Complex Structures
-
-The `toCode()` method (generating JS constructor code from AST) does not yet fully support complex nested structures with sequential continuation rings. The SMILES parsing and serialization works correctly, but the generated JavaScript code may not reproduce the full structure.
-
----
-
-## Changes Made
-
-1. Added `bonds` array to Ring AST node (like Linear nodes)
-2. Parser now extracts bonds between ring atoms
-3. Codegen serializes bonds in ring output
-4. Fused ring codegen updated to preserve bonds
-5. Fixed rings inside branches being excluded from attachments
-6. Added branch depth normalization to fused ring codegen
-7. Fixed sequential continuation atoms for trailing atoms after ring closures
-8. Added unified iterative loop for collecting all inline positions (sequential continuations + afterBranchClose atoms)
-9. Track sequential continuation rings separately for codegen
-10. Store atom values for non-ring positions in `_atomValueMap`
-11. Store attachments for sequential continuation atoms in `_seqAtomAttachments`
-12. Fixed `lastAtomAtDepth` to clear when entering new branches (prevents cross-branch linking)
-13. Fixed duplicate attachments on shared atoms in fused rings (positionsWithAttachments tracking)
-14. Fixed ring marker placement - ring closures now come before attachments at closing position
-15. Added `buildBranchCrossingRingSMILES` for rings that traverse branch boundaries
-16. Fixed linear chain bonds - keep null values to preserve positional information
-17. Added sequential continuation ring detection for single-ring groups (celecoxib pattern)
-18. Converted all test assertions to exact value matching - no `toBeDefined()`, `typeof`, or `toHaveLength()` weak assertions
-19. Fixed deeply nested branches with multiple rings being lost (Valsartan, biphenyl patterns)
-20. Fixed sequential non-fused rings in branches being skipped (changed `atomToGroup.has()` to `atomToGroup.get() === groupIdx`)
-21. Fixed bracket atom serialization - use `atom.rawValue` instead of `atom.value.raw` to preserve `[nH]` notation
-
----
-
-## ✅ FIXED: Complex Morphinan Structures (Oxycodone)
-
-**Oxycodone and related morphinans now work correctly:**
-```
-Input:  CN1CCC23C4C(=O)CCC2(C1CC5=C3C(=C(C=C5)OC)O4)O
-Output: CN1CCC23C4C(=O)CCC2(C1CC5=C3C(=C(C=C5)OC)O4)O
-```
-
-The fix involved:
-1. Detecting "bridge rings" that share atoms with main chain rings but are at different branch depths
-2. Including these bridge rings in the fused ring group
-3. Properly excluding bridge ring atoms from being treated as attachments
-4. Updating `allRingPositions` when sequential continuation rings are discovered
-
-### All Morphinans - NOW WORKING
-```
-Morphine:      CN1CCC23C4OC5=C(O)C=CC(=C25)C(O)C=CC3C1C4
-Codeine:       CN1CCC23C4OC5=C(OC)C=CC(=C25)C(O)C=CC3C1C4
-Hydrocodone:   CN1CCC23C4OC5=C(OC)C=CC(=C25)C(=O)CCC3C1C4
-Hydromorphone: CN1CCC23C4OC5=C(O)C=CC(=C25)C(=O)CCC3C1C4
-```
-
----
-
-## ✅ FIXED: Additional NSAIDs (After Oxycodone Fix)
-
-These NSAIDs started working after the bridge ring detection fix:
-
-### Rofecoxib - NOW WORKING
-```
-Input:  CS(=O)(=O)C1=CC=C(C=C1)C2=C(C(=O)OC2)C3=CC=CC=C3
-Output: CS(=O)(=O)C1=CC=C(C=C1)C2=C(C(=O)OC2)C3=CC=CC=C3
-```
-
-### Etoricoxib - NOW WORKING
-```
-Input:  CC1=NC=C(C=C1)C2=CC=C(C=C2)S(=O)(=O)C3=CC=CC=C3
-Output: CC1=NC=C(C=C1)C2=CC=C(C=C2)S(=O)(=O)C3=CC=CC=C3
-```
-
-### Nabumetone - NOW WORKING
-```
-Input:  COC1=CC2=CC(=CC=C2C=C1)CCC(=O)C
-Output: COC1=CC2=CC(=CC=C2C=C1)CCC(=O)C
-```
-
-### Ketoprofen - NOW WORKING
-```
-Input:  CC(c1cccc(c1)C(=O)c2ccccc2)C(=O)O
-Output: CC(c1cccc(c1)C(=O)c2ccccc2)C(=O)O
-```
-
-### Ibuprofen - NOW WORKING
-```
-Input:  CC(C)Cc1ccc(cc1)C(C)C(=O)O
-Output: CC(C)Cc1ccc(cc1)C(C)C(=O)O
-```
-
-### Benzocaine - NOW WORKING
-```
-Input:  CCOC(=O)C1=CC=C(C=C1)N
-Output: CCOC(=O)C1=CC=C(C=C1)N
-```
-
----
-
-## ✅ FIXED: Sequential Continuation Rings (Celecoxib Pattern)
-
-**Rings that open inside a branch containing another ring's closure are now handled correctly.**
-
-This pattern occurs when:
-- Ring 1 closes at a certain branch depth
-- Ring 2 opens immediately after at the same branch depth
-- Ring 2 needs to be processed together with Ring 1
-
-### Celecoxib - NOW WORKING
-```
-Input:  CC1=CC=C(C=C1)C2=CC(=NN2C3=CC=C(C=C3)S(=O)(=O)N)C(F)(F)F
-Output: CC1=CC=C(C=C1)C2=CC(=NN2C3=CC=C(C=C3)S(=O)(=O)N)C(F)(F)F
-```
-
-### Minimal Pattern Example
-```
-Input:  C1CC(C1C2CCC2)C    (Ring 2 opens inside branch after Ring 1 closes)
-Output: C1CC(C1C2CCC2)C
-```
-
-The fix detects when a single ring closes at a deeper branch level and recursively includes immediately following rings that are at the same branch depth (without `afterBranchClose` flag).
-
----
-
-## ✅ FIXED: Deeply Nested Branches with Multiple Rings
-
-**Fixed issues with parser losing deeply nested branches containing rings.**
-
-### Valsartan - NOW WORKING
-```
-Input:  CCCCC(=O)N(CC1=CC=CC=C1C2=CC=CC=C2C3=NNN=N3)C(C(C)C)C(=O)O
-Output: CCCCC(=O)N(CC1=CC=CC=C1C2=CC=CC=C2C3=NNN=N3)C(C(C)C)C(=O)O
-```
-
-### Ketoprofen (Biphenyl Variant) - NOW WORKING
-```
-Input:  CC(c1ccccc1c2ccccc2)C(=O)O
-Output: CC(c1ccccc1c2ccccc2)C(=O)O
-```
-
-The fix involved two changes:
-1. **Sequential rings at different depths**: The code for handling sequential continuation atoms was excluding ALL atoms from other rings. Changed to only exclude atoms from **sibling rings** (same branch depth), while properly including atoms from **attachment rings** (deeper branch depths).
-
-2. **Sequential rings in the same branch**: The loop that skips atoms after processing a ring group was skipping atoms from ALL groups instead of just the current group. Changed `atomToGroup.has(...)` to `atomToGroup.get(...) === groupIdx` to only skip atoms in the same group.
-
----
-
-## ✅ FIXED: Cannabinoid Tricyclic Structures
-
-**All cannabinoids now work after the deeply nested branch fixes:**
-
-### THC - NOW WORKING
-```
-Input:  CCCCCC1=CC(=C2C3C=C(CCC3C(OC2=C1)(C)C)C)O
-Output: CCCCCC1=CC(=C2C3C=C(CCC3C(OC2=C1)(C)C)C)O
-```
-
-### CBD - NOW WORKING
-```
-Input:  CCCCCC1=CC(=C(C(=C1)O)C2C=C(CCC2C(=C)C)C)O
-Output: CCCCCC1=CC(=C(C(=C1)O)C2C=C(CCC2C(=C)C)C)O
-```
-
-### Nabilone - NOW WORKING
-```
-Input:  CCCCCCC(C)(C)C1=CC(=C2C3CC(=O)CCC3C(OC2=C1)(C)C)O
-Output: CCCCCCC(C)(C)C1=CC(=C2C3CC(=O)CCC3C(OC2=C1)(C)C)O
-```
-
----
-
-## ✅ FIXED: Complex Heterocyclic NSAIDs
-
-**All complex heterocyclic NSAIDs now work:**
-
-### Meloxicam - NOW WORKING
-```
-Input:  CC1=C(N=C(S1)NC(=O)C2=C(C3=CC=CC=C3S(=O)(=O)N2C)O)C
-Output: CC1=C(N=C(S1)NC(=O)C2=C(C3=CC=CC=C3S(=O)(=O)N2C)O)C
-```
-
-### Piroxicam - NOW WORKING
-```
-Input:  CN1C(=C(C2=CC=CC=C2S1(=O)=O)O)C(=O)NC3=CC=CC=N3
-Output: CN1C(=C(C2=CC=CC=C2S1(=O)=O)O)C(=O)NC3=CC=CC=N3
-```
-
-### Oxaprozin - NOW WORKING
-```
-Input:  OC(=O)CCC1=NC(=C(O1)C2=CC=CC=C2)C3=CC=CC=C3
-Output: OC(=O)CCC1=NC(=C(O1)C2=CC=CC=C2)C3=CC=CC=C3
-```
-
----
-
-## ✅ FIXED: Bracket Atom Serialization
-
-**Bracket atoms like `[nH]` are now correctly preserved during parsing/regeneration.**
-
-### Losartan - WORKS
-```
-Input:  CCCCc1nc(Cl)c(n1Cc2ccc(cc2)c3ccccc3c4n[nH]nn4)CO
-Output: CCCCc1nc(Cl)c(n1Cc2ccc(cc2)c3ccccc3c4n[nH]nn4)CO
-```
-
-The fix involved using `atom.rawValue` (which stores the full bracket notation like `"[nH]"`) instead of `atom.value.raw` (which only stores the inner content like `"nH"`).
-
----
-
 ## Test Coverage
+- **468 tests passing** across 18 test files
+- 778 expect() calls with exact value matching
+- All tests run in ~173ms
 
-- 457 tests passing across 25 test files
-- 0 tests skipped
-- Tests cover parsing, code generation, and round-trip validation
-- All test assertions use exact value matching (`.toEqual()`, `.toBe()`) - no weak assertions
+## Supported Molecule Classes
 
----
+| Category | Examples | Status |
+|----------|----------|--------|
+| NSAIDs | Ibuprofen, Naproxen, Celecoxib, Meloxicam, Piroxicam | ✅ |
+| Opioids | Fentanyl, Tramadol, Morphine, Codeine, Oxycodone | ✅ |
+| Steroids | Cortisone, Hydrocortisone, Prednisone, Dexamethasone | ✅ |
+| Cannabinoids | THC, CBD, Nabilone | ✅ |
+| Hypertension | Losartan, Valsartan, Telmisartan | ✅ |
+| Analgesics | Acetaminophen, Phenacetin, Gabapentin, Pregabalin | ✅ |
+| Endocannabinoids | Anandamide, 2-AG | ✅ |
 
-## Production Readiness: ✅ READY FOR v1.0.0
+## API Completeness
 
-**Audit Date**: 2026-01-30
-**Status**: All planned features implemented and tested
+**Constructors**: Ring, Linear, FusedRing, Molecule, Fragment
 
-### Implementation Roadmap Status: 21/21 Checkpoints Complete ✅
+**Ring Methods**: attach, substitute, substituteMultiple, fuse, concat, clone
 
-| Checkpoint | Feature | Status | Verification |
-|------------|---------|--------|--------------|
-| 0 | Foundation (AST types, constructors) | ✅ DONE | Files exist, tests passing |
-| 1 | Ring Constructor | ✅ DONE | `Ring({ atoms: 'c', size: 6 }).smiles === 'c1ccccc1'` |
-| 2 | Linear Constructor | ✅ DONE | `Linear(['C', 'C', 'C']).smiles === 'CCC'` |
-| 3 | Ring.attach() | ✅ DONE | `benzene.attach(methyl, 1).smiles` works |
-| 4 | Ring.substitute() | ✅ DONE | `benzene.substitute(5, 'n').smiles === 'c1cccnc1'` |
-| 5 | Molecule Constructor | ✅ DONE | `Molecule([propyl, benzene]).smiles` works |
-| 6 | FusedRing Constructor | ✅ DONE | Naphthalene round-trips correctly |
-| 7 | SMILES Code Generator | ✅ DONE | `src/codegen.js` complete, all `.smiles` getters work |
-| 8 | Ring Manipulation Methods | ✅ DONE | All methods implemented: `substituteMultiple`, `fuse`, `concat`, `clone` |
-| 9 | FusedRing Manipulation | ✅ DONE | All methods implemented: `addRing`, `getRing`, `substituteInRing`, etc. |
-| 10 | Linear & Molecule Manipulation | ✅ DONE | All methods implemented: `attach`, `branch`, `concat`, `append`, etc. |
-| 11 | Tokenizer (Phase 1) | ✅ DONE | `tokenize()` works, 29 tests passing |
-| 12 | Parser Pass 1 - Linear Scan | ✅ DONE | `buildAtomList()` implemented |
-| 13 | Parser Pass 2 - AST Building | ✅ DONE | Complex molecules (telmisartan) parse correctly |
-| 14 | Fragment Integration | ✅ DONE | `Fragment('c1ccccc1')` works with new parser |
-| 15 | Round-Trip Validation | ✅ DONE | 457 tests verify round-trip fidelity |
-| 16 | Decompiler - Basic | ✅ DONE | `decompile()` works for simple structures |
-| 17 | Decompiler - Complete | ✅ DONE | All node types decompile (with documented limitation) |
-| 18 | Decompiler - Fragment Integration | ✅ DONE | `fragment.toCode()` method works |
-| 19 | Documentation & Examples | ✅ DONE | README, docs/, inline comments, 32+ molecule examples |
-| 20 | Performance & Optimization | ✅ DONE | 457 tests run in ~163ms, efficient parsing |
-| 21 | Final Testing & Release | ✅ DONE | 100% test pass rate, edge cases covered |
+**Linear Methods**: attach, concat, branch, branchAt, clone
 
-### API Completeness: 100% ✅
+**FusedRing Methods**: addRing, getRing, substituteInRing, attachToRing, renumber, concat, clone
 
-**Construction API**: Ring ✅ | Linear ✅ | FusedRing ✅ | Molecule ✅
-**Ring Manipulation**: attach ✅ | substitute ✅ | substituteMultiple ✅ | fuse ✅ | concat ✅ | clone ✅
-**Linear Manipulation**: attach ✅ | concat ✅ | branch ✅ | branchAt ✅ | clone ✅
-**FusedRing Manipulation**: addRing ✅ | getRing ✅ | substituteInRing ✅ | attachToRing ✅ | renumber ✅ | concat ✅ | clone ✅
-**Molecule Manipulation**: append ✅ | prepend ✅ | concat ✅ | getComponent ✅ | replaceComponent ✅ | clone ✅
-**Parsing/Serialization**: tokenize ✅ | parse ✅ | buildSMILES ✅ | decompile ✅ | .smiles getters ✅ | .toCode() ✅
+**Molecule Methods**: append, prepend, concat, getComponent, replaceComponent, clone
 
-### Quality Metrics ✅
+**Parsing**: tokenize, parse, buildSMILES, decompile, .smiles getters, .toCode()
 
-- **Test Coverage**: 457/457 tests passing (100%)
-- **Test Files**: 25 files with comprehensive coverage
-- **Assertions**: 694 exact assertions (no weak checks)
-- **Complex Molecules Verified**: 32+ drugs (steroids, opioids, NSAIDs, cannabinoids)
-- **Round-Trip Fidelity**: All structures round-trip correctly
-- **Code Quality**: Clean architecture, immutable operations, no global state
-- **Documentation**: README + design docs + API examples + inline comments
+## Implementation Checkpoints: 21/21 ✅
 
-### Known Limitation ⚠️
+All planned features implemented:
+- Foundation (AST types, constructors)
+- Ring/Linear/FusedRing/Molecule constructors and manipulation
+- SMILES tokenizer and parser
+- Code generator (AST → SMILES)
+- Decompiler (AST → JavaScript)
+- Fragment integration
+- Round-trip validation
+- Documentation and examples
 
-**toCode() for Sequential Continuation Patterns**: The decompiler has a documented limitation when generating JavaScript code for certain complex nested structures. This does NOT affect parsing or serialization - only code generation.
+## Known Limitation
 
-**What works perfectly**:
+**toCode() for complex nested structures**: The decompiler cannot generate JavaScript code for certain sequential continuation patterns. This does NOT affect:
 - ✅ Parsing SMILES → AST
 - ✅ Serializing AST → SMILES
-- ✅ Round-trip fidelity (SMILES → AST → SMILES)
-
-**What has limitations**:
-- ⚠️ Generating JS code for sequential continuation patterns (AST → JavaScript)
-
-**Assessment**: Acceptable for v1.0.0 because:
-1. Core functionality (parse/serialize) is perfect
-2. Limitation only affects developer tooling
-3. Clearly documented
-4. Most users will use programmatic API directly
-
-### Production Deployment Checklist ✅
-
-- [x] All planned features implemented (21/21 checkpoints)
-- [x] Comprehensive test suite (457 tests, 0 failures)
-- [x] Documentation complete (README, design docs, examples)
-- [x] Known limitations documented
-- [x] API stable and consistent
-- [x] Performance validated (~163ms for 457 tests)
-- [x] Complex real-world molecules tested
-- [x] Round-trip validation verified
-- [x] Code quality high (modular, immutable, clean)
-- [x] No critical bugs
-
-### Recommendation: Ship v1.0.0 ✅
-
-The library is **production ready** and suitable for v1.0.0 release. All core features are implemented, tested, and documented. The single known limitation (toCode() for complex patterns) is clearly documented and does not affect primary use cases.
+- ✅ Round-trip fidelity
+
+## Key Fixes Implemented
+
+1. Double bonds in rings preserved
+2. Rings inside branches handled correctly
+3. Ring closures at different branch depths
+4. Steroid polycyclic structures (shared atoms)
+5. Sequential continuation rings (celecoxib pattern)
+6. Deeply nested branches with multiple rings
+7. Bracket atom serialization (`[nH]`)
+8. Linear chain double bond positions
+9. Bridge ring detection for morphinans

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "smiles-js",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "description": "A JavaScript library for building molecules using composable fragments",
   "type": "module",
   "main": "src/index.js",