Skip to content

Commit 00debe2

Browse files
author
Sascha Losko
committed
Prepare v1.0.0 release
1 parent cc58982 commit 00debe2

File tree

108 files changed

+11669
-187
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

108 files changed

+11669
-187
lines changed

‎.github/ISSUE_TEMPLATE/bug_report.md‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
---
2+
name: Bug report
3+
about: Report a defect in parsing, layout, rendering, identifiers, or descriptors
4+
title: "[Bug] "
5+
labels: ["bug"]
6+
assignees: []
7+
---
8+
9+
## Summary
10+
11+
Describe the problem clearly and concisely.
12+
13+
## Environment
14+
15+
- Package version/tag:
16+
- Swift version:
17+
- macOS version:
18+
- Host architecture: (Apple Silicon / Intel)
19+
20+
## Reproduction
21+
22+
1. Input format:
23+
2. Input data (smallest reproducer):
24+
3. API call path:
25+
4. Observed behavior:
26+
5. Expected behavior:
27+
28+
## Impact
29+
30+
Explain why this matters (incorrect chemistry result, crash, performance issue, etc.).
31+
32+
## Additional context
33+
34+
Include logs, screenshots, or references to upstream CDK behavior if relevant.

‎.github/ISSUE_TEMPLATE/config.yml‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
blank_issues_enabled: false
2+
contact_links:
3+
- name: Security report
4+
url: https://github.com/<your-org-or-user>/CDKSwiftNativePort/security/policy
5+
about: Report vulnerabilities privately using the security policy.

‎.github/ISSUE_TEMPLATE/feature_request.md‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
---
2+
name: Feature request
3+
about: Propose a new capability or parity enhancement
4+
title: "[Feature] "
5+
labels: ["enhancement"]
6+
assignees: []
7+
---
8+
9+
## Summary
10+
11+
Describe the requested feature.
12+
13+
## Motivation
14+
15+
Explain the chemistry or workflow problem this solves.
16+
17+
## Proposed behavior
18+
19+
Describe expected API behavior and output.
20+
21+
## CDK parity notes
22+
23+
If this is parity-related, include:
24+
25+
- Upstream CDK class or module:
26+
- Expected reference behavior:
27+
- Known test cases:
28+
29+
## Acceptance criteria
30+
31+
List objective checks for completion.

‎.github/pull_request_template.md‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
## Summary
2+
3+
Describe what changed and why.
4+
5+
## Type of Change
6+
7+
- [ ] Bug fix
8+
- [ ] New feature
9+
- [ ] Refactor
10+
- [ ] Documentation
11+
- [ ] Test-only
12+
13+
## Validation
14+
15+
- [ ] `swift test` passes locally
16+
- [ ] Added/updated tests for behavior changes
17+
- [ ] No app-level coupling introduced in package sources
18+
19+
## CDK Parity Notes
20+
21+
If this changes CDK-derived behavior, include:
22+
- upstream CDK reference class/test
23+
- parity gaps that remain (if any)
24+
25+
## Docs
26+
27+
- [ ] `README.md` updated (if needed)
28+
- [ ] `Documentation/API.md` updated (if needed)
29+
- [ ] `CHANGELOG.md` updated

‎.github/workflows/ci.yml‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
name: CI
2+
3+
on:
4+
push:
5+
branches: ["main"]
6+
pull_request:
7+
branches: ["main"]
8+
9+
jobs:
10+
test:
11+
runs-on: macos-latest
12+
steps:
13+
- name: Checkout
14+
uses: actions/checkout@v4
15+
16+
- name: Select Xcode
17+
run: sudo xcode-select -s /Applications/Xcode.app
18+
19+
- name: Build and test
20+
run: swift test

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
.DS_Store
22
.build/
3+
build/
34
.swiftpm/
45
Package.resolved
56
*.xcodeproj/xcuserdata/

‎CHANGELOG.md‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
# Changelog
2+
3+
All notable changes to this project are documented in this file.
4+
5+
The format is based on Keep a Changelog and this project follows Semantic Versioning.
6+
7+
## [Unreleased]
8+
9+
- No entries yet.
10+
11+
## [1.0.0] - 2026-02-19
12+
13+
### Added
14+
15+
- Unified import/export dispatch APIs (`CDKFileImporter`, `CDKFileExporter`) across MDL, SMILES, InChI, MOL2, PDB, XYZ, CML, RXN, RDF, SVG.
16+
- CDK-derived layout/depiction pipeline, including scene generation and style controls.
17+
- Native Swift InChI parse/generate path and InChIKey generation service.
18+
- Molecular property service and descriptor set including XLogP and Rule-of-Five helpers.
19+
- Expanded CDK parity-oriented test suite and metadata tests.
20+
- Package boundary guard tests to prevent app-level coupling from entering package sources.
21+
- Release documentation set (`Documentation/API.md`, `CONTRIBUTING.md`, `SECURITY.md`).
22+
23+
### Changed
24+
25+
- Removed package source coupling to app-specific identifiers and app-branded defaults.
26+
- Replaced app-scoped content-type identifiers in package IO metadata with package-neutral/common identifiers.
27+
- Cleaned renderer dependency surface by removing `AppKit` import from package rendering implementation.
28+
29+
### Notes
30+
31+
- This package contains CDK-derived functionality and remains licensed under LGPL-2.1-or-later.

‎CONTRIBUTING.md‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
# Contributing
2+
3+
Thanks for contributing to `CDKSwiftNativePort`.
4+
5+
## Development Setup
6+
7+
1. Install Xcode with Swift 5.9+ toolchain.
8+
2. Clone the repository.
9+
3. Run:
10+
11+
```bash
12+
swift test
13+
```
14+
15+
## Contribution Rules
16+
17+
1. Keep package boundaries clean.
18+
2. Do not add app-level dependencies into package source code.
19+
3. Keep CDK-derived logic in CDK-like structure under `Sources/CDKSwiftNativePort/CDK/...`.
20+
4. Add or update tests for every functional change.
21+
5. Keep public API changes intentional and documented in `CHANGELOG.md` and `Documentation/API.md`.
22+
23+
## Package Boundary Policy
24+
25+
Package source code must not depend on:
26+
- Spotlight APIs (`CoreSpotlight`)
27+
- Quick Look APIs (`QuickLook`, `QuickLookThumbnailing`)
28+
- app-specific bundle identifiers, app names, or app settings
29+
30+
If integration with an app is needed, that integration belongs in the app repository, not in this package.
31+
32+
## Testing
33+
34+
Run the complete suite before opening a PR:
35+
36+
```bash
37+
swift test
38+
```
39+
40+
The suite includes:
41+
- parser/writer round-trip tests
42+
- CDK parity metadata tests
43+
- depiction/layout behavior tests
44+
- package boundary guard tests
45+
46+
## Pull Request Checklist
47+
48+
- [ ] Tests pass locally (`swift test`)
49+
- [ ] New behavior has test coverage
50+
- [ ] No app-level coupling introduced
51+
- [ ] Documentation updated (`README.md`, `Documentation/API.md`, `CHANGELOG.md`)
52+
- [ ] License/attribution implications checked for CDK-derived code

‎Documentation/API.md‎

Lines changed: 133 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,133 @@
1+
# API Reference (High-Level)
2+
3+
This document summarizes the primary public API surface of `CDKSwiftNativePort`.
4+
5+
## 1) Core Model
6+
7+
Defined in `Sources/CDKSwiftNativePort/Molecule.swift`.
8+
9+
- `Molecule`
10+
- `Atom`
11+
- `Bond`
12+
- `BondOrder`
13+
- `BondStereo`
14+
- `AtomChirality`
15+
- `ChemFormat`
16+
- `ChemError`
17+
18+
Useful methods on `Molecule` include:
19+
- graph neighborhood/bond lookup helpers
20+
- ring/cycle helpers
21+
- implicit hydrogen helpers
22+
- geometry helpers (`boundingBox`, normalization-friendly traversal utilities)
23+
24+
## 2) Layout and Depiction
25+
26+
- `Depiction2DGenerator.generate(for:)`
27+
- applies CDK-style 2D coordinate generation.
28+
- `CDKDepictionGenerator.toSVG(...)`
29+
- produces SVG depictions.
30+
- `CDKMetalDepictionSceneBuilder.build(...)`
31+
- builds a render-agnostic scene representation suitable for Metal-style renderers.
32+
- `CDKStandardGenerator.draw(...)`
33+
- SwiftUI `GraphicsContext` drawing path.
34+
35+
Style controls:
36+
- `RenderStyle`
37+
- `CDKAtomColoringMode`
38+
- `CDKAromaticDisplayMode`
39+
40+
## 3) Import APIs
41+
42+
Generic dispatch:
43+
- `CDKFileImporter.readMolecules(from:)`
44+
- `CDKFileImporter.readMolecules(text:fileExtension:)`
45+
- `CDKFileImporter.preferredInputFormat(...)`
46+
47+
Format-specific readers:
48+
- MDL: `CDKMDLReader`, `CDKMDLV2000Reader`, `CDKMDLV3000Reader`, `CDKIteratingSDFReader`
49+
- SMILES: `CDKSMILESReader`
50+
- InChI: `CDKInChIReader`
51+
- MOL2: `CDKMol2Reader`
52+
- PDB: `CDKPDBReader`
53+
- XYZ: `CDKXYZReader`
54+
- CML: `CDKCMLReader`
55+
- RXN/RDF: `CDKRXNReader`, `CDKRDFReader`
56+
57+
## 4) Export APIs
58+
59+
Generic dispatch:
60+
- `CDKFileExporter.write(...)`
61+
- `CDKFileExporter.write(..., to:as:options:)`
62+
- `CDKFileExportFormat`
63+
- `CDKFileExportOptions`
64+
65+
Format-specific writers:
66+
- MDL/SDF: `CDKMDLV2000Writer`, `CDKSDFWriter`
67+
- SMILES: `CDKSMILESWriter`
68+
- InChI: `CDKInChIWriter`
69+
- MOL2: `CDKMol2Writer`
70+
- PDB: `CDKPDBWriter`
71+
- XYZ: `CDKXYZWriter`
72+
- CML: `CDKCMLWriter`
73+
- RXN/RDF: `CDKRXNWriter`, `CDKRDFWriter`
74+
75+
## 5) SMILES APIs
76+
77+
- Parsing:
78+
- `CDKSmilesParser`
79+
- `CDKSmilesParserFactory`
80+
- `CDKCxSmilesParser`
81+
- `CDKSmilesReactionParser`
82+
- Generation:
83+
- `CDKSmilesGenerator`
84+
- `CDKSmilesGeneratorFactory`
85+
- `CDKSmiFlavor`
86+
87+
## 6) InChI APIs
88+
89+
- `CDKInChIToStructure`
90+
- `CDKInChIGenerator`
91+
- `CDKInChIGeneratorFactory`
92+
- `CDKInChIStatus`
93+
94+
Facade:
95+
- `CDKMoleculeIdentifierService.compute(for:)`
96+
- returns `CDKMoleculeIdentifiers` (SMILES, ISO SMILES, InChI, InChIKey).
97+
98+
## 7) Descriptors and Property Services
99+
100+
Facade:
101+
- `CDKMoleculePropertyService.compute(for:)`
102+
- returns `CDKMolecularProperties`.
103+
104+
Rule-of-Five helpers:
105+
- `CDKRuleOfFiveDescriptor`
106+
- `CDKRuleOfFiveResult`
107+
108+
Descriptors:
109+
- `CDKMolecularFormulaDescriptor`
110+
- `CDKMolecularWeightDescriptor`
111+
- `CDKExactMassDescriptor`
112+
- `CDKHeavyAtomCountDescriptor`
113+
- `CDKHBondDonorCountDescriptor`
114+
- `CDKHBondAcceptorCountDescriptor`
115+
- `CDKRotatableBondsCountDescriptor`
116+
- `CDKRingCountDescriptor`
117+
- `CDKXLogPDescriptor`
118+
- `CDKMannholdLogPDescriptor`
119+
120+
## 8) Error Handling
121+
122+
Most parsing and writing APIs throw `ChemError`:
123+
- `.emptyInput`
124+
- `.unsupported(String)`
125+
- `.parseFailed(String)`
126+
127+
Call sites should use `do / try / catch` and surface `LocalizedError.errorDescription` where appropriate.
128+
129+
## 9) Stability Notes
130+
131+
- Public symbols listed above are intended as the stable integration surface for application use.
132+
- Internals under the `CDK/...` tree may evolve as parity with upstream CDK improves.
133+
- For release history and compatibility notes, see `CHANGELOG.md`.

‎Documentation/ARCHITECTURE.md‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
# Architecture Overview
2+
3+
## Top-level Layout
4+
5+
- `Sources/CDKSwiftNativePort/Molecule.swift`
6+
- core domain model and shared error types.
7+
- `Sources/CDKSwiftNativePort/CDK/Common`
8+
- service facades and shared utilities.
9+
- `Sources/CDKSwiftNativePort/CDK/Smiles`
10+
- SMILES/CXSMILES/reaction parse + generation.
11+
- `Sources/CDKSwiftNativePort/CDK/InChI`
12+
- InChI parse/generate services.
13+
- `Sources/CDKSwiftNativePort/CDK/Layout`
14+
- structure diagram generation and placement heuristics.
15+
- `Sources/CDKSwiftNativePort/CDK/Rendering`
16+
- depiction, style resolution, clipping, scene generation.
17+
- `Sources/CDKSwiftNativePort/CDK/IO`
18+
- format-specific readers/writers and unified importer/exporter APIs.
19+
- `Sources/CDKSwiftNativePort/CDK/QSAR`
20+
- descriptors and molecular property calculations.
21+
22+
## Boundary Principles
23+
24+
`CDKSwiftNativePort` is intentionally independent from any host app.
25+
26+
Not allowed in package source:
27+
- app bundle identifiers/names
28+
- Spotlight/Quick Look integration logic
29+
- app window/session state management
30+
31+
App integrations belong in host projects and should consume this package through public APIs.
32+
33+
## Testing Strategy
34+
35+
- Unit tests grouped by chemistry area (`Smiles`, `InChI`, `MDL`, `Rendering`, `Layout`, `QSAR`).
36+
- Parity metadata tests track links to upstream CDK tests.
37+
- Round-trip tests validate IO reader/writer consistency.
38+
- Boundary guard tests detect app-level coupling markers in source files.

0 commit comments

Comments
 (0)