diff --git a/ABI-FFI-README.md b/ABI-FFI-README.adoc similarity index 74% rename from ABI-FFI-README.md rename to ABI-FFI-README.adoc index 8bcbf07..309bf55 100644 --- a/ABI-FFI-README.md +++ b/ABI-FFI-README.adoc @@ -1,19 +1,22 @@ -{{~ Aditionally delete this line and fill out the template below ~}} +\{\{~ Aditionally delete this line and fill out the template below ~}} -# {{PROJECT}} ABI/FFI Documentation +== \{\{PROJECT}} ABI/FFI Documentation -## Overview +=== Overview -This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design: +This library follows the *Hyperpolymath RSR Standard* for ABI and FFI +design: -- **ABI (Application Binary Interface)** defined in **Idris2** with formal proofs -- **FFI (Foreign Function Interface)** implemented in **Zig** for C compatibility -- **Generated C headers** bridge Idris2 ABI to Zig FFI -- **Any language** can call through standard C ABI +* *ABI (Application Binary Interface)* defined in *Idris2* with formal +proofs +* *FFI (Foreign Function Interface)* implemented in *Zig* for C +compatibility +* *Generated C headers* bridge Idris2 ABI to Zig FFI +* *Any language* can call through standard C ABI -## Architecture +=== Architecture -``` +.... ┌─────────────────────────────────────────────┐ │ ABI Definitions (Idris2) │ │ src/abi/ │ @@ -45,11 +48,11 @@ This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design: │ Any Language via C ABI │ │ - Rust, , Julia, Python, etc. │ └─────────────────────────────────────────────┘ -``` +.... -## Directory Structure +=== Directory Structure -``` +.... {{project}}/ ├── src/ │ ├── abi/ # ABI definitions (Idris2) @@ -77,15 +80,17 @@ This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design: ├── rust/ ├── / └── julia/ -``` +.... -## Why Idris2 for ABI? +=== Why Idris2 for ABI? -### 1. **Formal Verification** +==== 1. *Formal Verification* -Idris2's dependent types allow proving properties about the ABI at compile-time: +Idris2’s dependent types allow proving properties about the ABI at +compile-time: -```idris +[source,idris] +---- -- Prove struct size is correct public export exampleStructSize : HasSize ExampleStruct 16 @@ -97,13 +102,14 @@ fieldAligned : Divides 8 (offsetOf ExampleStruct.field) -- Prove ABI is platform-compatible public export abiCompatible : Compatible (ABI 1) (ABI 2) -``` +---- -### 2. **Type Safety** +==== 2. *Type Safety* Encode invariants that C/Zig cannot express: -```idris +[source,idris] +---- -- Non-null pointer guaranteed at type level data Handle : Type where MkHandle : (ptr : Bits64) -> {auto 0 nonNull : So (ptr /= 0)} -> Handle @@ -111,13 +117,14 @@ data Handle : Type where -- Array with length proof data Buffer : (n : Nat) -> Type where MkBuffer : Vect n Byte -> Buffer n -``` +---- -### 3. **Platform Abstraction** +==== 3. *Platform Abstraction* Platform-specific types with compile-time selection: -```idris +[source,idris] +---- CInt : Platform -> Type CInt Linux = Bits32 CInt Windows = Bits32 @@ -125,13 +132,14 @@ CInt Windows = Bits32 CSize : Platform -> Type CSize Linux = Bits64 CSize Windows = Bits64 -``` +---- -### 4. **Safe Evolution** +==== 4. *Safe Evolution* Prove that new ABI versions are backward-compatible: -```idris +[source,idris] +---- -- Compiler enforces compatibility abiUpgrade : ABI 1 -> ABI 2 abiUpgrade old = MkABI2 { @@ -140,71 +148,78 @@ abiUpgrade old = MkABI2 { -- Can add new fields new_features = defaults } -``` +---- -## Why Zig for FFI? +=== Why Zig for FFI? -### 1. **C ABI Compatibility** +==== 1. *C ABI Compatibility* Zig exports C-compatible functions naturally: -```zig +[source,zig] +---- export fn library_function(param: i32) i32 { return param * 2; } -``` +---- -### 2. **Memory Safety** +==== 2. *Memory Safety* Compile-time safety without runtime overhead: -```zig +[source,zig] +---- // Null check enforced at compile time const handle = init() orelse return error.InitFailed; defer free(handle); -``` +---- -### 3. **Cross-Compilation** +==== 3. *Cross-Compilation* Built-in cross-compilation to any platform: -```bash +[source,bash] +---- zig build -Dtarget=x86_64-linux zig build -Dtarget=aarch64-macos zig build -Dtarget=x86_64-windows -``` +---- -### 4. **Zero Dependencies** +==== 4. *Zero Dependencies* No runtime, no libc required (unless explicitly needed): -```zig +[source,zig] +---- // Minimal binary size pub const lib = @import("std"); // Only includes what you use -``` +---- -## Building +=== Building -### Build FFI Library +==== Build FFI Library -```bash +[source,bash] +---- cd ffi/zig zig build # Build debug zig build -Doptimize=ReleaseFast # Build optimized zig build test # Run tests -``` +---- -### Generate C Header from Idris2 ABI +==== Generate C Header from Idris2 ABI -```bash +[source,bash] +---- cd src/abi idris2 --cg c-header Types.idr -o ../../generated/abi/{{project}}.h -``` +---- -### Cross-Compile +==== Cross-Compile -```bash +[source,bash] +---- cd ffi/zig # Linux x86_64 @@ -215,13 +230,14 @@ zig build -Dtarget=aarch64-macos # Windows x86_64 zig build -Dtarget=x86_64-windows -``` +---- -## Usage +=== Usage -### From C +==== From C -```c +[source,c] +---- #include "{{project}}.h" int main() { @@ -237,16 +253,19 @@ int main() { {{project}}_free(handle); return 0; } -``` +---- Compile with: -```bash + +[source,bash] +---- gcc -o example example.c -l{{project}} -L./zig-out/lib -``` +---- -### From Idris2 +==== From Idris2 -```idris +[source,idris] +---- import {{PROJECT}}.ABI.Foreign main : IO () @@ -259,11 +278,12 @@ main = do free handle putStrLn "Success" -``` +---- -### From Rust +==== From Rust -```rust +[source,rust] +---- #[link(name = "{{project}}")] extern "C" { fn {{project}}_init() -> *mut std::ffi::c_void; @@ -282,11 +302,12 @@ fn main() { {{project}}_free(handle); } } -``` +---- -### From Julia +==== From Julia -```julia +[source,julia] +---- const lib{{project}} = "lib{{project}}" function init() @@ -312,27 +333,30 @@ try finally cleanup(handle) end -``` +---- -## Testing +=== Testing -### Unit Tests (Zig) +==== Unit Tests (Zig) -```bash +[source,bash] +---- cd ffi/zig zig build test -``` +---- -### Integration Tests +==== Integration Tests -```bash +[source,bash] +---- cd ffi/zig zig build test-integration -``` +---- -### ABI Verification (Idris2) +==== ABI Verification (Idris2) -```idris +[source,idris] +---- -- Compile-time verification %runElab verifyABI @@ -342,44 +366,44 @@ main = do verifyLayouorrect verifyAlignmenorrect putStrLn "ABI verification passed" -``` +---- -## Contributing +=== Contributing When modifying the ABI/FFI: -1. **Update ABI first** (`src/abi/*.idr`) - - Modify type definitions - - Update proofs - - Ensure backward compatibility - -2. **Generate C header** - ```bash - idris2 --cg c-header src/abi/Types.idr -o generated/abi/{{project}}.h - ``` - -3. **Update FFI implementation** (`ffi/zig/src/main.zig`) - - Implement new functions - - Match ABI types exactly - -4. **Add tests** - - Unit tests in Zig - - Integration tests - - ABI verification tests - -5. **Update documentation** - - Function signatures - - Usage examples - - Migration guide (if breaking changes) - -## License +[arabic] +. *Update ABI first* (`+src/abi/*.idr+`) +* Modify type definitions +* Update proofs +* Ensure backward compatibility +. *Generate C header* ++ +[source,bash] +---- +idris2 --cg c-header src/abi/Types.idr -o generated/abi/{{project}}.h +---- +. *Update FFI implementation* (`+ffi/zig/src/main.zig+`) +* Implement new functions +* Match ABI types exactly +. *Add tests* +* Unit tests in Zig +* Integration tests +* ABI verification tests +. *Update documentation* +* Function signatures +* Usage examples +* Migration guide (if breaking changes) + +=== License PMPL-1.0-or-later -## See Also +=== See Also -- [Idris2 Documentation](https://idris2.readthedocs.io) -- [Zig Documentation](https://ziglang.org/documentation/master/) -- [Rhodium Standard Repositories](https://github.com/hyperpolymath/rhodium-standard-repositories) -- [FFI Migration Guide](../ffi-migration-guide.md) -- [ABI Migration Guide](../abi-migration-guide.md) +* https://idris2.readthedocs.io[Idris2 Documentation] +* https://ziglang.org/documentation/master/[Zig Documentation] +* https://github.com/hyperpolymath/rhodium-standard-repositories[Rhodium +Standard Repositories] +* link:../ffi-migration-guide.md[FFI Migration Guide] +* link:../abi-migration-guide.md[ABI Migration Guide] diff --git a/ACCESSIBILITY.adoc b/ACCESSIBILITY.adoc new file mode 100644 index 0000000..090dc27 --- /dev/null +++ b/ACCESSIBILITY.adoc @@ -0,0 +1,295 @@ +== Accessibility Guidelines + +*UbiCity Accessibility Commitment* *Version*: 1.0 *Standard*: WCAG 2.1 +Level AA (where applicable) + +=== Overview + +UbiCity is a CLI-first tool for learning capture. While traditional web +accessibility (WCAG) focuses on visual interfaces, we ensure our +command-line tools are accessible to all users, including those using +screen readers, alternative input devices, and assistive technologies. + +''''' + +=== Accessibility Principles + +==== 1. Perceivable + +*Users can perceive the information being presented* + +===== CLI Output + +* ✅ *Plain text output* (screen reader compatible) +* ✅ *Unicode symbols with text fallbacks* (`+✅+` → "`Success`") +* ✅ *Structured output* (headings, lists) +* ✅ *No color-only information* (use symbols + color) + +===== Visual Representations + +* ✅ *Visualization HTML* includes alt text for images +* ✅ *High contrast* (4.5:1 minimum for text) +* ✅ *Resize-able text* (HTML reports) + +==== 2. Operable + +*Users can operate the interface* + +===== Keyboard Navigation + +* ✅ *Keyboard-only operation* (no mouse required) +* ✅ *Tab navigation* in interactive prompts +* ✅ *Escape key exits* prompts +* ✅ *Arrow keys* for history/autocomplete + +===== Timing + +* ✅ *No time limits* on input +* ✅ *Pausable operations* (Ctrl+C to cancel) + +==== 3. Understandable + +*Users can understand the information and operation* + +===== Language + +* ✅ *Simple, clear language* (no jargon) +* ✅ *Internationalization (i18n)* support (`+src/i18n/+`) +* ✅ *Error messages* are actionable +* ✅ *Help text* for all commands + +===== Predictable Behavior + +* ✅ *Consistent prompts* across captures +* ✅ *Confirmation before destructive actions* +* ✅ *Undo/rollback* for mistakes + +==== 4. Robust + +*Content can be interpreted by assistive technologies* + +===== Standards Compliance + +* ✅ *UTF-8 encoding* throughout +* ✅ *ANSI escape codes* for terminal colors (widely supported) +* ✅ *HTML5 semantic elements* in visualizations +* ✅ *ARIA labels* for interactive HTML elements + +''''' + +=== CLI Accessibility Features + +==== Screen Reader Compatibility + +*Tested With*: - NVDA (Windows) - JAWS (Windows) - Orca (Linux) - +VoiceOver (macOS) + +*Best Practices*: + +[source,bash] +---- +# Good: Screen reader announces "Success: Experience captured" +echo "✅ Success: Experience captured" + +# Bad: Screen reader announces "Green check. Experience captured" +echo -e "\e[32m✅ Experience captured\e[0m" # Color-only info +---- + +==== Alternative Input Methods + +===== Voice Control (Dragon, VoiceOver) + +* ✅ Commands are short and memorable +* ✅ Autocomplete reduces typing +* ✅ Tab completion for file paths + +===== Switch Access + +* ✅ Sequential navigation (Tab through options) +* ✅ Single-key shortcuts where possible + +==== Reduced Motion + +*For visualizations*: + +[source,css] +---- +@media (prefers-reduced-motion: reduce) { + * { + animation-duration: 0.01ms !important; + transition-duration: 0.01ms !important; + } +} +---- + +==== High Contrast Mode + +[source,bash] +---- +# Detect terminal capabilities +if [ "$TERM" = "linux" ]; then + # High contrast for Linux console + export UBICITY_COLOR=off +fi +---- + +''''' + +=== Internationalization (i18n) + +==== Supported Languages + +* English (en) - Primary +* Spanish (es) - Community +* [More coming soon] + +==== Language Selection + +[source,bash] +---- +# Set language via environment variable +export UBICITY_LANG=es +ubicity capture + +# Or inline +UBICITY_LANG=es ubicity capture +---- + +==== Translation Guidelines + +*For Contributors*: 1. All user-facing strings in `+src/i18n/*.json+` 2. +Use placeholders for dynamic content: `+{learner_name}+` 3. Respect +cultural context (dates, names, formality) 4. Test with native speakers + +*Example*: + +[source,json] +---- +{ + "capture": { + "success": "✅ Experience captured successfully!" + } +} +---- + +''''' + +=== Documentation Accessibility + +==== README & Guides + +* ✅ *Headings hierarchy* (H1 → H2 → H3, no skipping) +* ✅ *Link text is descriptive* ("`Read getting started guide`" not +"`Click here`") +* ✅ *Alt text for images/diagrams* +* ✅ *Code blocks* have syntax labels +* ✅ *Tables* have header rows + +==== API Documentation + +* ✅ *Function signatures* clearly explained +* ✅ *Parameter types* documented +* ✅ *Examples* for every function +* ✅ *Error conditions* listed + +''''' + +=== Testing for Accessibility + +==== Manual Testing Checklist + +* [ ] Run CLI with screen reader (NVDA/Orca/VoiceOver) +* [ ] Navigate using keyboard only (no mouse) +* [ ] Test with terminal color disabled (`+NO_COLOR=1+`) +* [ ] Resize terminal to 80x24 (minimum) +* [ ] Test with slow network (if network features added) +* [ ] Test in high contrast mode +* [ ] Verify error messages are actionable + +==== Automated Testing + +[source,bash] +---- +# HTML reports (axe-core) +npm install -g @axe-core/cli +axe ./visualizations/report.html + +# Color contrast (pa11y) +npm install -g pa11y +pa11y --standard WCAG2AA ./visualizations/report.html +---- + +''''' + +=== Privacy & Accessibility Intersection + +==== Data Minimization + +*Accessibility Benefit*: Less data = simpler interfaces + +* ✅ WHO/WHERE/WHAT protocol keeps prompts short +* ✅ No multi-page forms +* ✅ Fast capture (< 1 minute) + +==== Privacy-Preserving Exports + +*Accessibility Benefit*: Simple export formats + +* ✅ CSV (readable in spreadsheets with screen readers) +* ✅ GeoJSON (standard for mapping tools) +* ✅ Markdown (semantic headings, screen reader friendly) + +''''' + +=== Known Limitations + +==== Current (v0.3) + +* ❌ *No GUI* - CLI only (but this is by design: "`tools not +platforms`") +* ❌ *English-first* - Translations incomplete +* ❌ *Emoji in output* - May not render in all terminals + +==== Future Enhancements + +* 🔮 *TUI (Text User Interface)* with full keyboard navigation +* 🔮 *Audio feedback* (optional beeps on success/error) +* 🔮 *Simplified mode* (fewer prompts, more defaults) +* 🔮 *Screen reader optimizations* (verbose mode) + +''''' + +=== Reporting Accessibility Issues + +*How to Report*: 1. GitHub Issues: +https://github.com/Hyperpolymath/ubicity/issues 2. Label: +`+accessibility+` 3. Describe: Assistive tech used, expected behavior, +actual behavior + +*Response Time*: - Critical (blocks usage): 48 hours - High (degrades +experience): 7 days - Medium (improvement): Next release + +''''' + +=== References + +* https://www.w3.org/WAI/WCAG21/quickref/[WCAG 2.1] +* https://inclusivedesignprinciples.org/[Inclusive Design Principles] +* https://www.a11yproject.com/[The A11Y Project] +* https://cli-a11y.dev/[CLI Accessibility Best Practices] + +''''' + +=== Commitment + +*UbiCity Accessibility Promise*: > Learning happens for everyone, +everywhere. Our tools must be accessible to all learners, regardless of +ability. We commit to maintaining and improving accessibility with every +release. + +*Contact*: accessibility@ubicity.example.org + +''''' + +*Document Owner*: Maintainers *Last Review*: 2025-11-22 *Next Review*: +2026-02-22 (quarterly) diff --git a/ACCESSIBILITY.md b/ACCESSIBILITY.md deleted file mode 100644 index 5a8d9d1..0000000 --- a/ACCESSIBILITY.md +++ /dev/null @@ -1,269 +0,0 @@ -# Accessibility Guidelines - -**UbiCity Accessibility Commitment** -**Version**: 1.0 -**Standard**: WCAG 2.1 Level AA (where applicable) - -## Overview - -UbiCity is a CLI-first tool for learning capture. While traditional web accessibility (WCAG) focuses on visual interfaces, we ensure our command-line tools are accessible to all users, including those using screen readers, alternative input devices, and assistive technologies. - ---- - -## Accessibility Principles - -### 1. Perceivable -**Users can perceive the information being presented** - -#### CLI Output -- ✅ **Plain text output** (screen reader compatible) -- ✅ **Unicode symbols with text fallbacks** (`✅` → "Success") -- ✅ **Structured output** (headings, lists) -- ✅ **No color-only information** (use symbols + color) - -#### Visual Representations -- ✅ **Visualization HTML** includes alt text for images -- ✅ **High contrast** (4.5:1 minimum for text) -- ✅ **Resize-able text** (HTML reports) - -### 2. Operable -**Users can operate the interface** - -#### Keyboard Navigation -- ✅ **Keyboard-only operation** (no mouse required) -- ✅ **Tab navigation** in interactive prompts -- ✅ **Escape key exits** prompts -- ✅ **Arrow keys** for history/autocomplete - -#### Timing -- ✅ **No time limits** on input -- ✅ **Pausable operations** (Ctrl+C to cancel) - -### 3. Understandable -**Users can understand the information and operation** - -#### Language -- ✅ **Simple, clear language** (no jargon) -- ✅ **Internationalization (i18n)** support (`src/i18n/`) -- ✅ **Error messages** are actionable -- ✅ **Help text** for all commands - -#### Predictable Behavior -- ✅ **Consistent prompts** across captures -- ✅ **Confirmation before destructive actions** -- ✅ **Undo/rollback** for mistakes - -### 4. Robust -**Content can be interpreted by assistive technologies** - -#### Standards Compliance -- ✅ **UTF-8 encoding** throughout -- ✅ **ANSI escape codes** for terminal colors (widely supported) -- ✅ **HTML5 semantic elements** in visualizations -- ✅ **ARIA labels** for interactive HTML elements - ---- - -## CLI Accessibility Features - -### Screen Reader Compatibility - -**Tested With**: -- NVDA (Windows) -- JAWS (Windows) -- Orca (Linux) -- VoiceOver (macOS) - -**Best Practices**: -```bash -# Good: Screen reader announces "Success: Experience captured" -echo "✅ Success: Experience captured" - -# Bad: Screen reader announces "Green check. Experience captured" -echo -e "\e[32m✅ Experience captured\e[0m" # Color-only info -``` - -### Alternative Input Methods - -#### Voice Control (Dragon, VoiceOver) -- ✅ Commands are short and memorable -- ✅ Autocomplete reduces typing -- ✅ Tab completion for file paths - -#### Switch Access -- ✅ Sequential navigation (Tab through options) -- ✅ Single-key shortcuts where possible - -### Reduced Motion - -**For visualizations**: -```css -@media (prefers-reduced-motion: reduce) { - * { - animation-duration: 0.01ms !important; - transition-duration: 0.01ms !important; - } -} -``` - -### High Contrast Mode - -```bash -# Detect terminal capabilities -if [ "$TERM" = "linux" ]; then - # High contrast for Linux console - export UBICITY_COLOR=off -fi -``` - ---- - -## Internationalization (i18n) - -### Supported Languages -- English (en) - Primary -- Spanish (es) - Community -- [More coming soon] - -### Language Selection -```bash -# Set language via environment variable -export UBICITY_LANG=es -ubicity capture - -# Or inline -UBICITY_LANG=es ubicity capture -``` - -### Translation Guidelines - -**For Contributors**: -1. All user-facing strings in `src/i18n/*.json` -2. Use placeholders for dynamic content: `{learner_name}` -3. Respect cultural context (dates, names, formality) -4. Test with native speakers - -**Example**: -```json -{ - "capture": { - "success": "✅ Experience captured successfully!" - } -} -``` - ---- - -## Documentation Accessibility - -### README & Guides - -- ✅ **Headings hierarchy** (H1 → H2 → H3, no skipping) -- ✅ **Link text is descriptive** ("Read getting started guide" not "Click here") -- ✅ **Alt text for images/diagrams** -- ✅ **Code blocks** have syntax labels -- ✅ **Tables** have header rows - -### API Documentation - -- ✅ **Function signatures** clearly explained -- ✅ **Parameter types** documented -- ✅ **Examples** for every function -- ✅ **Error conditions** listed - ---- - -## Testing for Accessibility - -### Manual Testing Checklist - -- [ ] Run CLI with screen reader (NVDA/Orca/VoiceOver) -- [ ] Navigate using keyboard only (no mouse) -- [ ] Test with terminal color disabled (`NO_COLOR=1`) -- [ ] Resize terminal to 80x24 (minimum) -- [ ] Test with slow network (if network features added) -- [ ] Test in high contrast mode -- [ ] Verify error messages are actionable - -### Automated Testing - -```bash -# HTML reports (axe-core) -npm install -g @axe-core/cli -axe ./visualizations/report.html - -# Color contrast (pa11y) -npm install -g pa11y -pa11y --standard WCAG2AA ./visualizations/report.html -``` - ---- - -## Privacy & Accessibility Intersection - -### Data Minimization -**Accessibility Benefit**: Less data = simpler interfaces - -- ✅ WHO/WHERE/WHAT protocol keeps prompts short -- ✅ No multi-page forms -- ✅ Fast capture (< 1 minute) - -### Privacy-Preserving Exports -**Accessibility Benefit**: Simple export formats - -- ✅ CSV (readable in spreadsheets with screen readers) -- ✅ GeoJSON (standard for mapping tools) -- ✅ Markdown (semantic headings, screen reader friendly) - ---- - -## Known Limitations - -### Current (v0.3) -- ❌ **No GUI** - CLI only (but this is by design: "tools not platforms") -- ❌ **English-first** - Translations incomplete -- ❌ **Emoji in output** - May not render in all terminals - -### Future Enhancements -- 🔮 **TUI (Text User Interface)** with full keyboard navigation -- 🔮 **Audio feedback** (optional beeps on success/error) -- 🔮 **Simplified mode** (fewer prompts, more defaults) -- 🔮 **Screen reader optimizations** (verbose mode) - ---- - -## Reporting Accessibility Issues - -**How to Report**: -1. GitHub Issues: https://github.com/Hyperpolymath/ubicity/issues -2. Label: `accessibility` -3. Describe: Assistive tech used, expected behavior, actual behavior - -**Response Time**: -- Critical (blocks usage): 48 hours -- High (degrades experience): 7 days -- Medium (improvement): Next release - ---- - -## References - -- [WCAG 2.1](https://www.w3.org/WAI/WCAG21/quickref/) -- [Inclusive Design Principles](https://inclusivedesignprinciples.org/) -- [The A11Y Project](https://www.a11yproject.com/) -- [CLI Accessibility Best Practices](https://cli-a11y.dev/) - ---- - -## Commitment - -**UbiCity Accessibility Promise**: -> Learning happens for everyone, everywhere. Our tools must be accessible to all learners, regardless of ability. We commit to maintaining and improving accessibility with every release. - -**Contact**: accessibility@ubicity.example.org - ---- - -**Document Owner**: Maintainers -**Last Review**: 2025-11-22 -**Next Review**: 2026-02-22 (quarterly) diff --git a/API.md b/API.adoc similarity index 73% rename from API.md rename to API.adoc index 511ff4b..1fddb2c 100644 --- a/API.md +++ b/API.adoc @@ -1,14 +1,15 @@ -# UbiCity API Reference +== UbiCity API Reference -Developer documentation for the UbiCity modules. +Developer documentation for the UbiCity modules. -## Overview +=== Overview -UbiCity is implemented in (compiles to JavaScript). All modules are in `src-/` and compile to `*.res.js` files. +UbiCity is implemented in (compiles to JavaScript). All modules are in +`+src-/+` and compile to `+*.res.js+` files. -### Module Architecture +==== Module Architecture -``` +.... UbiCity.res - Core domain types ├── Decoder.res - JSON validation ├── Mapper.res - Data indexing and queries @@ -18,12 +19,13 @@ UbiCity.res - Core domain types ├── Visualization.res - HTML generation ├── Capture.res - CLI capture logic └── CaptureCLI.res - CLI entry point -``` +.... -## Core Types (UbiCity.res) +=== Core Types (UbiCity.res) -### Coordinates -``` +==== Coordinates + +.... type t = { latitude: float, longitude: float, @@ -31,10 +33,11 @@ type t = { let make: (~latitude: float, ~longitude: float) => option let isValid: t => bool -``` +.... + +==== Location -### Location -``` +.... type t = { name: string, coordinates: option, @@ -49,10 +52,11 @@ let make: ( ~address: option=?, unit, ) => result -``` +.... + +==== Learner -### Learner -``` +.... type t = { id: string, name: option, @@ -65,10 +69,11 @@ let make: ( ~interests: option>=?, unit, ) => result -``` +.... -### LearningExperience -``` +==== LearningExperience + +.... type t = { id: string, timestamp: string, @@ -92,27 +97,33 @@ let make: ( ~version: option=?, unit, ) => t -``` +.... + +=== Data Access (Mapper.res) -## Data Access (Mapper.res) +==== Creating a Mapper -### Creating a Mapper -```javascript +[source,javascript] +---- import { make } from './src-/Mapper.res.js'; const mapper = await make(); -``` +---- + +==== Storing Experiences -### Storing Experiences -```javascript +[source,javascript] +---- import { captureExperience } from './src-/Mapper.res.js'; const result = await captureExperience(mapper, experience); // Returns: Ok(experienceId) | Error(message) -``` +---- -### Querying -```javascript +==== Querying + +[source,javascript] +---- // Get all experiences const allExperiences = await loadAll(mapper); @@ -127,12 +138,14 @@ const aliceExperiences = getByLearner(mapper, "alice-maker"); // Identify hotspots const hotspots = identifyHotspots(mapper); -``` +---- + +=== Analysis (Analysis.res) -## Analysis (Analysis.res) +==== Temporal Analysis -### Temporal Analysis -```javascript +[source,javascript] +---- import { TemporalAnalyzer } from './src-/Analysis.res.js'; // Analyze by time of day @@ -145,18 +158,22 @@ const byDay = TemporalAnalyzer.analyzeByDayOfWeek(experiences); // Detect learning streaks const streaks = TemporalAnalyzer.detectStreaks(experiences, 7); // Returns: [{ startDate, endDate, dayCount, experienceCount }] -``` +---- + +==== Network Analysis -### Network Analysis -```javascript +[source,javascript] +---- import { CollaborativeNetworkAnalyzer } from './src-/Analysis.res.js'; const network = CollaborativeNetworkAnalyzer.buildCollaborationNetwork(experiences); // Returns: { nodes: [{id, size}], edges: [{source, target, weight}] } -``` +---- -### Recommendations -```javascript +==== Recommendations + +[source,javascript] +---- import { RecommendationEngine } from './src-/Analysis.res.js'; // Similar learners @@ -179,12 +196,14 @@ const domains = RecommendationEngine.recommendDomains( "alice-maker", 5 ); -``` +---- + +=== Privacy (Privacy.res) -## Privacy (Privacy.res) +==== Anonymization -### Anonymization -```javascript +[source,javascript] +---- import { anonymizeLearner, anonymizeLocation, @@ -205,10 +224,12 @@ const anonLocation = anonymizeLocation(experience, { // Full anonymization const fully = fullyAnonymize(experience); -``` +---- + +==== PII Removal -### PII Removal -```javascript +[source,javascript] +---- import { removePII, sanitizeText } from './src-/Privacy.res.js'; // Remove emails, phone numbers, URLs from text @@ -217,10 +238,12 @@ const cleaned = sanitizeText("Contact me at alice@example.com or 555-1234"); // Remove PII from entire experience const cleaned = removePII(experience); -``` +---- -### Shareable Datasets -```javascript +==== Shareable Datasets + +[source,javascript] +---- import { generateShareableDataset } from './src-/Privacy.res.js'; const dataset = generateShareableDataset(experiences, { @@ -229,46 +252,56 @@ const dataset = generateShareableDataset(experiences, { removePII: true, includePrivate: false, }); -``` +---- + +=== Export (Export.res) -## Export (Export.res) +==== CSV Export -### CSV Export -```javascript +[source,javascript] +---- import { exportToCSV } from './src-/Export.res.js'; const csv = exportToCSV(experiences); // Returns CSV string with proper escaping -``` +---- + +==== GeoJSON Export -### GeoJSON Export -```javascript +[source,javascript] +---- import { exportToGeoJSON } from './src-/Export.res.js'; const geojson = exportToGeoJSON(experiences); // Returns RFC 7946 compliant GeoJSON FeatureCollection -``` +---- -### DOT/Graphviz Export -```javascript +==== DOT/Graphviz Export + +[source,javascript] +---- import { exportToDOT } from './src-/Export.res.js'; const network = { nodes: [...], edges: [...] }; const dot = exportToDOT(network); // Returns: "digraph G { ... }" // Visualize with: dot -Tpng domains.dot -o domains.png -``` +---- + +==== Markdown Export -### Markdown Export -```javascript +[source,javascript] +---- import { exportJourneysToMarkdown } from './src-/Export.res.js'; const markdown = exportJourneysToMarkdown(experiences); // Returns learner journey timelines in Markdown format -``` +---- + +==== Universal Export -### Universal Export -```javascript +[source,javascript] +---- import { exportData } from './src-/Export.res.js'; // Auto-routes to appropriate exporter @@ -277,12 +310,14 @@ const data = exportData(experiences, "geojson"); const data = exportData(experiences, "dot", network); const data = exportData(experiences, "markdown"); const data = exportData(experiences, "json"); -``` +---- -## Visualization (Visualization.res) +=== Visualization (Visualization.res) -### HTML Generation -```javascript +==== HTML Generation + +[source,javascript] +---- import { generateHTML } from './src-/Visualization.res.js'; const html = generateHTML( @@ -292,12 +327,14 @@ const html = generateHTML( coordsCount // number of locations with GPS ); // Returns complete HTML document with CSS and JavaScript -``` +---- + +=== JSON Decoding (Decoder.res) -## JSON Decoding (Decoder.res) +==== Decode Experiences -### Decode Experiences -```javascript +[source,javascript] +---- import { decodeExperiences } from './src-/Decoder.res.js'; const rawData = JSON.parse(fs.readFileSync('data.json', 'utf-8')); @@ -309,19 +346,20 @@ if (result.TAG === "Ok") { } else { console.error("Validation errors:", result._0); } -``` +---- + +==== Legacy Format Support -### Legacy Format Support -The decoder handles legacy JSON formats: -- `lat`/`lon` → `latitude`/`longitude` -- Missing `id`/`timestamp`/`version` (auto-generated) -- String variants → polymorphic variants +The decoder handles legacy JSON formats: - `+lat+`/`+lon+` → +`+latitude+`/`+longitude+` - Missing `+id+`/`+timestamp+`/`+version+` +(auto-generated) - String variants → polymorphic variants -## Error Handling +=== Error Handling -All validation functions return `Result` types: +All validation functions return `+Result+` types: -```javascript +[source,javascript] +---- // Result type in compiled JS: // Ok: { TAG: "Ok", _0: value } // Error: { TAG: "Error", _0: errorMessage } @@ -334,40 +372,45 @@ if (result.TAG === "Ok") { const error = result._0; // Handle error } -``` +---- -## Type Safety +=== Type Safety -UbiCity is written in for type safety. The compiled JavaScript includes runtime checks. Types are validated at: -1. **Compile time** ( type checker) -2. **Runtime** (Decoder module for JSON) -3. **API boundaries** (validation on user input) +UbiCity is written in for type safety. The compiled JavaScript includes +runtime checks. Types are validated at: 1. *Compile time* ( type +checker) 2. *Runtime* (Decoder module for JSON) 3. *API boundaries* +(validation on user input) -## Examples +=== Examples -See `examples/` directory: -- `populate-examples.js` - Sample data generation -- `api-usage.js` - API usage patterns +See `+examples/+` directory: - `+populate-examples.js+` - Sample data +generation - `+api-usage.js+` - API usage patterns -## Development +=== Development -### Compile -```bash +==== Compile + +[source,bash] +---- npm run res:build -``` +---- + +==== Watch Mode -### Watch Mode -```bash +[source,bash] +---- npm run res:dev -``` +---- + +==== Tests -### Tests -```bash +[source,bash] +---- npm test # Unit tests npm run test:integration # Integration tests npm run test:all # Both -``` +---- ---- +''''' -**UbiCity v1.0.0 API Reference** +*UbiCity v1.0.0 API Reference* diff --git a/ARCHITECTURE.adoc b/ARCHITECTURE.adoc new file mode 100644 index 0000000..1c0a7a6 --- /dev/null +++ b/ARCHITECTURE.adoc @@ -0,0 +1,48 @@ +== Architecture + +=== Overview + +This repository follows a modular, maintainable architecture designed +for clarity, scalability, and long-term sustainability. + +=== Directory Structure + +.... +. +├── src/ # Source code +├── tests/ # Test suites +├── docs/ # Documentation +├── scripts/ # Utility scripts +├── config/ # Configuration files +├── LICENSE # License file +├── LICENSES/ # Full license texts +└── README.adoc # Project documentation +.... + +=== Design Principles + +* *Separation of Concerns*: Each module has a single responsibility +* *Testability*: Code is written to be easily testable +* *Documentation*: All public APIs are documented +* *Configuration*: Environment-specific settings are externalized + +=== Dependencies + +* External dependencies are minimized and clearly declared +* Version pinning is used for reproducibility + +=== Security Considerations + +* Sensitive data is never committed to the repository +* Secrets are managed through environment variables or secure vaults +* Regular dependency audits are performed + +=== Maintainability + +* Code follows consistent style guidelines +* Pull requests require review and CI checks +* Issues and discussions are tracked transparently + +''''' + +_Last updated: 2026-07-18_ diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md deleted file mode 100644 index 607e3d8..0000000 --- a/ARCHITECTURE.md +++ /dev/null @@ -1,47 +0,0 @@ -# Architecture - -## Overview - -This repository follows a modular, maintainable architecture designed for clarity, scalability, and long-term sustainability. - -## Directory Structure - -``` -. -├── src/ # Source code -├── tests/ # Test suites -├── docs/ # Documentation -├── scripts/ # Utility scripts -├── config/ # Configuration files -├── LICENSE # License file -├── LICENSES/ # Full license texts -└── README.adoc # Project documentation -``` - -## Design Principles - -- **Separation of Concerns**: Each module has a single responsibility -- **Testability**: Code is written to be easily testable -- **Documentation**: All public APIs are documented -- **Configuration**: Environment-specific settings are externalized - -## Dependencies - -- External dependencies are minimized and clearly declared -- Version pinning is used for reproducibility - -## Security Considerations - -- Sensitive data is never committed to the repository -- Secrets are managed through environment variables or secure vaults -- Regular dependency audits are performed - -## Maintainability - -- Code follows consistent style guidelines -- Pull requests require review and CI checks -- Issues and discussions are tracked transparently - ---- - -*Last updated: 2026-07-18* diff --git a/ARCHITECTURE_V3.md b/ARCHITECTURE_V3.adoc similarity index 51% rename from ARCHITECTURE_V3.md rename to ARCHITECTURE_V3.adoc index edcdeed..1c4d63d 100644 --- a/ARCHITECTURE_V3.md +++ b/ARCHITECTURE_V3.adoc @@ -1,49 +1,51 @@ -# UbiCity v0.3 Architecture +== UbiCity v0.3 Architecture -## Executive Summary +=== Executive Summary -v0.3 represents a complete architectural transformation: -- **100x faster** validation (WASM vs Zod) -- **10x faster** network generation (WASM vs JavaScript) -- **60% less** memory usage ( optimization) -- **Type-safe** business logic () -- **Zero config** deployment () -- **100% compatible** with v0.2 data +v0.3 represents a complete architectural transformation: - *100x faster* +validation (WASM vs Zod) - *10x faster* network generation (WASM vs +JavaScript) - *60% less* memory usage ( optimization) - *Type-safe* +business logic () - *Zero config* deployment () - *100% compatible* with +v0.2 data ---- +''''' -## Technology Stack +=== Technology Stack -### Runtime: -- Built-in support -- Secure by default (explicit permissions) -- Modern standard library -- No node_modules -- URL-based imports +==== Runtime: -### Business Logic: -- Functional programming -- Compile-time type safety -- OCaml-inspired syntax -- Excellent JS interop -- Optimized output +* Built-in support +* Secure by default (explicit permissions) +* Modern standard library +* No node_modules +* URL-based imports -### Performance: WASM (Rust) -- 10-100x faster than JavaScript -- Memory-safe -- Zero-cost abstractions -- Ahead-of-time compilation +==== Business Logic: -### Glue Layer: -- Type-safe integration -- APIs for I/O -- Bridge to and WASM +* Functional programming +* Compile-time type safety +* OCaml-inspired syntax +* Excellent JS interop +* Optimized output ---- +==== Performance: WASM (Rust) -## Architecture Diagram +* 10-100x faster than JavaScript +* Memory-safe +* Zero-cost abstractions +* Ahead-of-time compilation -``` +==== Glue Layer: + +* Type-safe integration +* APIs for I/O +* Bridge to and WASM + +''''' + +=== Architecture Diagram + +.... ┌──────────────────────────────────────────────────────────┐ │ User Interface │ │ ┌─────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ @@ -70,61 +72,54 @@ v0.3 represents a complete architectural transformation: │ • UbiCity.res.js │ │ • ubicity_bg.wasm │ └────────────────────────────┘ -``` +.... ---- +''''' -## Component Responsibilities +=== Component Responsibilities -### Layer () +==== Layer () -**Purpose**: I/O, CLI, integration +*Purpose*: I/O, CLI, integration -**Files**: -- `src/storage.ts` - File system operations -- `src/cli.ts` - Command-line interface -- `src/wasm-bridge.ts` - WASM integration -- `src/-bridge.ts` - integration +*Files*: - `+src/storage.ts+` - File system operations - `+src/cli.ts+` +- Command-line interface - `+src/wasm-bridge.ts+` - WASM integration - +`+src/-bridge.ts+` - integration -**Why **: 's native language, great for I/O and glue code +*Why *: ’s native language, great for I/O and glue code -### Layer +==== Layer -**Purpose**: Type-safe business logic +*Purpose*: Type-safe business logic -**Files**: -- `src-/UbiCity.res` - Domain model and analysis +*Files*: - `+src-/UbiCity.res+` - Domain model and analysis -**Compiles to**: `src-/UbiCity.res.js` (optimized ES6) +*Compiles to*: `+src-/UbiCity.res.js+` (optimized ES6) -**Why **: -- Functional programming (immutability, pure functions) -- Compile-time type safety (no runtime errors) -- Excellent optimization (smaller, faster code) -- OCaml heritage (proven type system) +*Why *: - Functional programming (immutability, pure functions) - +Compile-time type safety (no runtime errors) - Excellent optimization +(smaller, faster code) - OCaml heritage (proven type system) -### WASM Layer (Rust) +==== WASM Layer (Rust) -**Purpose**: Performance-critical operations +*Purpose*: Performance-critical operations -**Files**: -- `wasm/src/lib.rs` - Validation, network generation, similarity +*Files*: - `+wasm/src/lib.rs+` - Validation, network generation, +similarity -**Compiles to**: `wasm/pkg/ubicity_bg.wasm` +*Compiles to*: `+wasm/pkg/ubicity_bg.wasm+` -**Why WASM**: -- 10-100x faster than JavaScript -- Memory-safe (no garbage collection pauses) -- AOT compilation (predictable performance) -- Perfect for algorithms and computation +*Why WASM*: - 10-100x faster than JavaScript - Memory-safe (no garbage +collection pauses) - AOT compilation (predictable performance) - Perfect +for algorithms and computation ---- +''''' -## Performance Architecture +=== Performance Architecture -### Hot Path Optimization +==== Hot Path Optimization -``` +.... User Input │ ▼ @@ -150,56 +145,54 @@ User Input │Network Generation│ ◄── WASM (5ms for 1000 exp) │ (WASM Rust) │ └─────────────────┘ -``` +.... -### Cold Path (Less Critical) +==== Cold Path (Less Critical) -- Visualization generation → (not performance-critical) -- File exports → (I/O bound, not CPU bound) -- CLI formatting → (user interaction, not bottleneck) +* Visualization generation → (not performance-critical) +* File exports → (I/O bound, not CPU bound) +* CLI formatting → (user interaction, not bottleneck) ---- +''''' -## Build Process +=== Build Process -### Development Build +==== Development Build -```bash +[source,bash] +---- just build -``` +---- -Runs: -1. ` build` → Compile to JavaScript -2. `cargo build --release --target wasm32-unknown-unknown` → Compile Rust to WASM -3. `wasm-opt -Oz` → Optimize WASM for size +Runs: 1. `+build+` → Compile to JavaScript 2. +`+cargo build --release --target wasm32-unknown-unknown+` → Compile Rust +to WASM 3. `+wasm-opt -Oz+` → Optimize WASM for size -Output: -- `src-/UbiCity.res.js` - Optimized JavaScript -- `wasm/pkg/ubicity_bg.wasm` - Optimized WASM binary +Output: - `+src-/UbiCity.res.js+` - Optimized JavaScript - +`+wasm/pkg/ubicity_bg.wasm+` - Optimized WASM binary -### Production Build +==== Production Build -```bash +[source,bash] +---- just compile -``` +---- -Runs: -1. `just build` ( + WASM) -2. ` compile` → Create standalone executables +Runs: 1. `+just build+` ( + WASM) 2. `+compile+` → Create standalone +executables -Output: -- `bin/ubicity` - Standalone CLI binary -- `bin/ubicity-capture` - Standalone capture tool +Output: - `+bin/ubicity+` - Standalone CLI binary - +`+bin/ubicity-capture+` - Standalone capture tool -**No runtime needed!** Fully self-contained. +*No runtime needed!* Fully self-contained. ---- +''''' -## Type Safety Layers +=== Type Safety Layers -### Layer 1: Compile-Time +==== Layer 1: Compile-Time -``` +.... // Won't compile if types don't match let experience = LearningExperience.make( ~learner=learner, // Must be Learner.t @@ -207,40 +200,41 @@ let experience = LearningExperience.make( ~experience=exp, // Must be ExperienceData.t () ) -``` +.... -Catches errors: **Before runtime** +Catches errors: *Before runtime* -### Layer 2: WASM Runtime Validation +==== Layer 2: WASM Runtime Validation -```rust +[source,rust] +---- pub fn validate(&self, json: &str) -> Result { let result: Result = serde_json::from_str(json); // Fast deserialization + validation } -``` +---- -Catches errors: **At validation (fast)** +Catches errors: *At validation (fast)* -### Layer 3: Glue +==== Layer 3: Glue -``` +.... // ensures correct bridge usage export function validateExperienceWasm(experience: unknown): { valid: boolean; errors: string[]; } -``` +.... -Catches errors: **At integration points** +Catches errors: *At integration points* ---- +''''' -## Memory Architecture +=== Memory Architecture -### Before (v0.2 - Node.js + Zod) +==== Before (v0.2 - Node.js + Zod) -``` +.... ┌──────────────────────────────────┐ │ Node.js Heap (~50MB) │ │ ┌────────────────────────────┐ │ @@ -249,11 +243,11 @@ Catches errors: **At integration points** │ │ + Indices (Maps) │ │ │ └────────────────────────────┘ │ └──────────────────────────────────┘ -``` +.... -### After (v0.3 - + + WASM) +==== After (v0.3 - + + WASM) -``` +.... ┌──────────────────────────────────┐ │ Heap (~20MB) │ │ ┌────────────────────────────┐ │ @@ -268,19 +262,20 @@ Catches errors: **At integration points** │ │ (no GC overhead) │ │ │ └────────────────────────────┘ │ └──────────────────────────────────┘ -``` +.... -**Total**: 25MB vs 50MB = **50% reduction** +*Total*: 25MB vs 50MB = *50% reduction* ---- +''''' -## Security Model +=== Security Model -### Permissions +==== Permissions Explicit, granular permissions: -```bash +[source,bash] +---- # Read-only access to data directory run --allow-read=./ubicity-data src/cli.ts stats @@ -289,50 +284,50 @@ Explicit, granular permissions: # Pre-configured in .json tasks task capture # Permissions already set -``` +---- -### WASM Sandboxing +==== WASM Sandboxing -WASM runs in isolated linear memory: -- Cannot access file system -- Cannot make network requests -- Cannot execute arbitrary code +WASM runs in isolated linear memory: - Cannot access file system - +Cannot make network requests - Cannot execute arbitrary code -**Perfect for untrusted data validation** +*Perfect for untrusted data validation* ---- +''''' -## Deployment Options +=== Deployment Options -### 1. Runtime +==== 1. Runtime -```bash +[source,bash] +---- # Install on server curl -fsSL https:///install.sh | sh # Run directly task report -``` +---- -**Pros**: Easy updates, dynamic -**Cons**: Requires runtime +*Pros*: Easy updates, dynamic *Cons*: Requires runtime -### 2. Compiled Binaries +==== 2. Compiled Binaries -```bash +[source,bash] +---- # Compile once just compile # Deploy standalone binary ./bin/ubicity report -``` +---- -**Pros**: No runtime needed, fast startup -**Cons**: Platform-specific, larger file +*Pros*: No runtime needed, fast startup *Cons*: Platform-specific, +larger file -### 3. Docker Container +==== 3. Docker Container -```dockerfile +[source,dockerfile] +---- FROM denoland/:alpine WORKDIR /app @@ -342,18 +337,17 @@ RUN task build RUN cache src/index.ts CMD ["", "task", "cli"] -``` +---- -**Pros**: Consistent environment -**Cons**: Docker overhead +*Pros*: Consistent environment *Cons*: Docker overhead ---- +''''' -## Testing Strategy +=== Testing Strategy -### Unit Tests ( Test) +==== Unit Tests ( Test) -``` +.... // tests/validation.test.ts import { assertEquals } from '@std/assert'; @@ -364,97 +358,97 @@ import { assertEquals } from '@std/assert'; assert(duration < 1); // Sub-millisecond }); -``` +.... -### Integration Tests +==== Integration Tests -```bash +[source,bash] +---- test --allow-read --allow-write tests/ -``` +---- -### Benchmarks +==== Benchmarks -```bash +[source,bash] +---- bench --allow-read --allow-write benchmarks/ -``` +---- ---- +''''' -## Future Optimizations +=== Future Optimizations -### Potential Improvements +==== Potential Improvements -1. **WASM SIMD**: Vectorized operations for network generation -2. **Parallel Processing**: Multi-threaded WASM -3. **GPU Acceleration**: WebGPU for large-scale analysis -4. **Incremental Compilation**: Faster rebuilds -5. **Link-Time Optimization**: Cross-language optimization +[arabic] +. *WASM SIMD*: Vectorized operations for network generation +. *Parallel Processing*: Multi-threaded WASM +. *GPU Acceleration*: WebGPU for large-scale analysis +. *Incremental Compilation*: Faster rebuilds +. *Link-Time Optimization*: Cross-language optimization -### Not Planned (Against Philosophy) +==== Not Planned (Against Philosophy) -- ❌ Web framework integration (tools not platforms) -- ❌ Database layer (file-based is intentional) -- ❌ Authentication system (local-first) -- ❌ Cloud sync (privacy by default) +* ❌ Web framework integration (tools not platforms) +* ❌ Database layer (file-based is intentional) +* ❌ Authentication system (local-first) +* ❌ Cloud sync (privacy by default) ---- +''''' -## Philosophy Alignment +=== Philosophy Alignment Despite radical architectural change, v0.3 preserves: -✅ **Minimal Viable Protocol** - Still WHO/WHERE/WHAT -✅ **Tools not Platforms** - Still CLI-first, no server -✅ **Data First** - 100% compatible JSON files -✅ **Constraint Mechanism** - Same 4-week experiment -✅ **Privacy by Default** - Local storage, no cloud -✅ **Zero Bloat** - Even fewer dependencies (no npm!) +✅ *Minimal Viable Protocol* - Still WHO/WHERE/WHAT ✅ *Tools not +Platforms* - Still CLI-first, no server ✅ *Data First* - 100% +compatible JSON files ✅ *Constraint Mechanism* - Same 4-week experiment +✅ *Privacy by Default* - Local storage, no cloud ✅ *Zero Bloat* - Even +fewer dependencies (no npm!) + +The architecture changed. The philosophy didn’t. + +''''' + +=== Learning Resources + +==== -The architecture changed. The philosophy didn't. +* Official Guide: https://docs..com +* Standard Library: https:///std ---- +==== -## Learning Resources +* Language Manual: https://-lang.org +* Belt stdlib: https://-lang.org/docs/manual/latest/api/belt -### -- Official Guide: https://docs..com -- Standard Library: https:///std +==== WASM + Rust -### -- Language Manual: https://-lang.org -- Belt stdlib: https://-lang.org/docs/manual/latest/api/belt +* Rust Book: https://doc.rust-lang.org/book/ +* wasm-bindgen: https://rustwasm.github.io/wasm-bindgen/ -### WASM + Rust -- Rust Book: https://doc.rust-lang.org/book/ -- wasm-bindgen: https://rustwasm.github.io/wasm-bindgen/ +==== Build Tool -### Build Tool -- Just: https://just.systems/man/en/ +* Just: https://just.systems/man/en/ ---- +''''' -## Conclusion +=== Conclusion -v0.3 is a **performance rewrite** that maintains **100% data compatibility**. +v0.3 is a *performance rewrite* that maintains *100% data +compatibility*. -**Use v0.3 if you**: -- Want maximum performance -- Need type safety -- Prefer modern tooling -- Deploy to production +*Use v0.3 if you*: - Want maximum performance - Need type safety - +Prefer modern tooling - Deploy to production -**Use v0.2 if you**: -- Want zero build step -- Prefer simplicity over performance -- Don't need type safety -- Are just experimenting +*Use v0.2 if you*: - Want zero build step - Prefer simplicity over +performance - Don’t need type safety - Are just experimenting Both are maintained. Your choice. ---- +''''' -**Architecture Questions?** +*Architecture Questions?* -See: `MIGRATION_V3.md` for migration steps -See: `justfile` for all build commands -See: `.json` for configuration details +See: `+MIGRATION_V3.md+` for migration steps See: `+justfile+` for all +build commands See: `+.json+` for configuration details diff --git a/CODE_OF_CONDUCT.adoc b/CODE_OF_CONDUCT.adoc new file mode 100644 index 0000000..948d9ab --- /dev/null +++ b/CODE_OF_CONDUCT.adoc @@ -0,0 +1,169 @@ +== Code of Conduct + +=== Our Pledge + +We as members, contributors, and leaders pledge to make participation in +UbiCity a harassment-free experience for everyone, regardless of age, +body size, visible or invisible disability, ethnicity, sex +characteristics, gender identity and expression, level of experience, +education, socio-economic status, nationality, personal appearance, +race, caste, color, religion, or sexual identity and orientation. + +We pledge to act and interact in ways that contribute to an open, +welcoming, diverse, inclusive, and healthy community. + +=== Our Standards + +==== Positive Behavior + +* Using welcoming and inclusive language +* Being respectful of differing viewpoints and experiences +* Gracefully accepting constructive criticism +* Focusing on what is best for the community +* Showing empathy towards other community members +* Respecting the *Minimal Viable Protocol* philosophy +* Recognizing and valuing *emotional safety* in technical work +* Supporting *reversibility* in design decisions + +==== Unacceptable Behavior + +* The use of sexualized language or imagery +* Trolling, insulting/derogatory comments, and personal or political +attacks +* Public or private harassment +* Publishing others’ private information without explicit permission +* Conduct which could reasonably be considered inappropriate in a +professional setting +* *Feature creep advocacy* that undermines constraint mechanisms +* *Platform thinking* instead of tools thinking +* *Surveillance capitalism* patterns or suggestions + +=== Philosophy-Specific Standards + +==== Tools Not Platforms + +* *Encouraged*: Suggestions that increase user autonomy +* *Discouraged*: Features that create lock-in or control users + +==== Data First + +* *Encouraged*: Focus on capturing and analyzing real experiences +* *Discouraged*: Building infrastructure before validating need + +==== Privacy by Default + +* *Encouraged*: Local-first, offline-capable features +* *Discouraged*: Cloud sync, analytics, tracking + +==== Emotional Safety + +* *Encouraged*: Acknowledging uncertainty, offering multiple approaches +* *Discouraged*: Authoritarian certainty, one-size-fits-all solutions + +=== Enforcement Responsibilities + +Community leaders (see MAINTAINERS.md) are responsible for clarifying +and enforcing our standards of acceptable behavior and will take +appropriate and fair corrective action in response to any behavior that +they deem inappropriate, threatening, offensive, or harmful. + +Community leaders have the right and responsibility to remove, edit, or +reject comments, commits, code, wiki edits, issues, and other +contributions that are not aligned to this Code of Conduct, and will +communicate reasons for moderation decisions when appropriate. + +=== Scope + +This Code of Conduct applies within all community spaces (GitHub +repository, discussions, pull requests, issues, email) and also applies +when an individual is officially representing the community in public +spaces. + +=== Enforcement + +==== Reporting + +Instances of abusive, harassing, or otherwise unacceptable behavior may +be reported to the community leaders responsible for enforcement at: + +*Email*: conduct@ubicity.example.org + +*Response Time*: Within 48 hours + +*Privacy*: All complaints will be reviewed and investigated promptly and +fairly. + +==== Enforcement Guidelines + +Community leaders will follow these guidelines: + +===== 1. Correction + +*Community Impact*: Use of inappropriate language or other +unprofessional behavior. + +*Consequence*: A private, written warning, providing clarity around the +nature of the violation and an explanation of why the behavior was +inappropriate. A public apology may be requested. + +===== 2. Warning + +*Community Impact*: A violation through a single incident or series of +actions. + +*Consequence*: A warning with consequences for continued behavior. No +interaction with the people involved for a specified period. This +includes avoiding interactions in community spaces as well as external +channels. Violating these terms may lead to a temporary or permanent +ban. + +===== 3. Temporary Ban + +*Community Impact*: A serious violation, including sustained +inappropriate behavior. + +*Consequence*: A temporary ban from any sort of interaction or public +communication with the community for a specified period. No public or +private interaction with the people involved is allowed during this +period. Violating these terms may lead to a permanent ban. + +===== 4. Permanent Ban + +*Community Impact*: Demonstrating a pattern of violation, including +sustained inappropriate behavior, harassment, or aggression toward +individuals or classes of individuals. + +*Consequence*: A permanent ban from any sort of public interaction +within the community. + +=== Appeals + +If you believe you have been falsely or unfairly accused of violating +this Code of Conduct, you may appeal to: + +*Email*: appeals@ubicity.example.org + +Include: 1. Description of the incident 2. Why you believe the +enforcement was unfair 3. Any supporting evidence + +Appeals will be reviewed by maintainers not involved in the original +incident. + +=== Attribution + +This Code of Conduct is adapted from: - +https://www.contributor-covenant.org/version/2/1/code_of_conduct.html[Contributor +Covenant v2.1] - https://cccp.example.org[CCCP (Community Code of +Conduct Pledge)] - Emotional safety principles - UbiCity philosophical +constraints + +=== Questions? + +Email: conduct@ubicity.example.org + +''''' + +For answers to common questions about this code of conduct, see: +https://www.contributor-covenant.org/faq + +Last updated: 2025-11-22 diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md deleted file mode 100644 index bb0cf2a..0000000 --- a/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,134 +0,0 @@ -# Code of Conduct - -## Our Pledge - -We as members, contributors, and leaders pledge to make participation in UbiCity a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation. - -We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community. - -## Our Standards - -### Positive Behavior - -- Using welcoming and inclusive language -- Being respectful of differing viewpoints and experiences -- Gracefully accepting constructive criticism -- Focusing on what is best for the community -- Showing empathy towards other community members -- Respecting the **Minimal Viable Protocol** philosophy -- Recognizing and valuing **emotional safety** in technical work -- Supporting **reversibility** in design decisions - -### Unacceptable Behavior - -- The use of sexualized language or imagery -- Trolling, insulting/derogatory comments, and personal or political attacks -- Public or private harassment -- Publishing others' private information without explicit permission -- Conduct which could reasonably be considered inappropriate in a professional setting -- **Feature creep advocacy** that undermines constraint mechanisms -- **Platform thinking** instead of tools thinking -- **Surveillance capitalism** patterns or suggestions - -## Philosophy-Specific Standards - -### Tools Not Platforms - -- **Encouraged**: Suggestions that increase user autonomy -- **Discouraged**: Features that create lock-in or control users - -### Data First - -- **Encouraged**: Focus on capturing and analyzing real experiences -- **Discouraged**: Building infrastructure before validating need - -### Privacy by Default - -- **Encouraged**: Local-first, offline-capable features -- **Discouraged**: Cloud sync, analytics, tracking - -### Emotional Safety - -- **Encouraged**: Acknowledging uncertainty, offering multiple approaches -- **Discouraged**: Authoritarian certainty, one-size-fits-all solutions - -## Enforcement Responsibilities - -Community leaders (see MAINTAINERS.md) are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful. - -Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate. - -## Scope - -This Code of Conduct applies within all community spaces (GitHub repository, discussions, pull requests, issues, email) and also applies when an individual is officially representing the community in public spaces. - -## Enforcement - -### Reporting - -Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at: - -**Email**: conduct@ubicity.example.org - -**Response Time**: Within 48 hours - -**Privacy**: All complaints will be reviewed and investigated promptly and fairly. - -### Enforcement Guidelines - -Community leaders will follow these guidelines: - -#### 1. Correction - -**Community Impact**: Use of inappropriate language or other unprofessional behavior. - -**Consequence**: A private, written warning, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested. - -#### 2. Warning - -**Community Impact**: A violation through a single incident or series of actions. - -**Consequence**: A warning with consequences for continued behavior. No interaction with the people involved for a specified period. This includes avoiding interactions in community spaces as well as external channels. Violating these terms may lead to a temporary or permanent ban. - -#### 3. Temporary Ban - -**Community Impact**: A serious violation, including sustained inappropriate behavior. - -**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period. No public or private interaction with the people involved is allowed during this period. Violating these terms may lead to a permanent ban. - -#### 4. Permanent Ban - -**Community Impact**: Demonstrating a pattern of violation, including sustained inappropriate behavior, harassment, or aggression toward individuals or classes of individuals. - -**Consequence**: A permanent ban from any sort of public interaction within the community. - -## Appeals - -If you believe you have been falsely or unfairly accused of violating this Code of Conduct, you may appeal to: - -**Email**: appeals@ubicity.example.org - -Include: -1. Description of the incident -2. Why you believe the enforcement was unfair -3. Any supporting evidence - -Appeals will be reviewed by maintainers not involved in the original incident. - -## Attribution - -This Code of Conduct is adapted from: -- [Contributor Covenant v2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct.html) -- [CCCP (Community Code of Conduct Pledge)](https://cccp.example.org) - Emotional safety principles -- UbiCity philosophical constraints - -## Questions? - -Email: conduct@ubicity.example.org - ---- - -For answers to common questions about this code of conduct, see: -https://www.contributor-covenant.org/faq - -Last updated: 2025-11-22 diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc new file mode 100644 index 0000000..f332189 --- /dev/null +++ b/CONTRIBUTING.adoc @@ -0,0 +1,305 @@ +== Contributing to UbiCity + +Welcome! UbiCity follows the *Tri-Perimeter Contribution Framework +(TPCF)*. + +=== TPCF Perimeter Designation + +*Current Perimeter: 3 (Community Sandbox)* + +==== What This Means + +* ✅ *Fully Open Contribution*: Anyone can contribute via standard +GitHub workflow +* ✅ *No CLA Required*: No contributor license agreements +* ✅ *Democratic Review*: Pull requests reviewed by maintainers and +community +* ✅ *Transparent Governance*: Decisions documented in GitHub +Issues/Discussions + +==== Perimeter Comparison + +[width="100%",cols="33%,17%,22%,28%",options="header",] +|=== +|Perimeter |Name |Access |Use Case +|1 |Core Maintainer |Maintainers only |Security-critical code + +|2 |Trusted Contributor |Invited contributors |Stable feature +development + +|3 |*Community Sandbox* |*Public GitHub* |*UbiCity (current)* +|=== + +*Why Perimeter 3?* UbiCity is a community project. We welcome +contributions from anyone who aligns with our values. + +=== How to Contribute + +==== Quick Start + +[arabic] +. *Fork* the repository +. *Create a branch*: `+git checkout -b feature/your-feature+` +. *Make changes* (see below for guidelines) +. *Test*: `+just test+` (or `+task test+`) +. *Commit*: Clear commit messages +. *Push*: `+git push origin feature/your-feature+` +. *Pull Request*: Open PR with description + +==== Before You Start + +* Read the link:CODE_OF_CONDUCT.md[Code of Conduct] +* Check https://github.com/Hyperpolymath/ubicity/issues[existing issues] +* Discuss major changes in an issue first + +=== Contribution Types + +==== 🐛 Bug Reports + +[source,markdown] +---- +**Description**: Brief description +**Steps to Reproduce**: +1. Step one +2. Step two +**Expected**: What should happen +**Actual**: What actually happened +**Environment**: +- OS: +- version: +- UbiCity version: +---- + +==== ✨ Feature Requests + +[source,markdown] +---- +**Problem**: What problem does this solve? +**Solution**: Proposed solution +**Alternatives**: Other approaches considered +**Philosophy Alignment**: How does this align with UbiCity's values? +---- + +==== 🔧 Code Contributions + +===== Type Safety Required + +* ****: For business logic (compile-time type safety) +* *Rust (WASM)*: For performance-critical code +* ****: For glue layer and I/O + +===== Code Style + +[source,bash] +---- +# Format code +just fmt # or: fmt + +# Lint code +just lint # or: lint + +# Type check +just check # or: check src/**/*.ts +---- + +===== Testing + +[source,bash] +---- +# Run all tests +just test # or: task test + +# Tests must pass +# Aim for >80% coverage for new code +---- + +===== Documentation + +* Update README.md if adding features +* Add JSDoc comments for +* Update CHANGELOG.md (see format below) +* Add examples to `+examples/+` if helpful + +==== 📚 Documentation + +* Fix typos, improve clarity +* Add examples or tutorials +* Translate documentation (future) + +=== Development Setup + +==== Prerequisites + +[source,bash] +---- +# Required +curl -fsSL https:///install.sh | sh # +curl https://sh.rustup.rs -sSf | sh # Rust +npm install -g # + +# Optional (but recommended) +cargo install just # just +---- + +==== Build + +[source,bash] +---- +just setup # One-time setup +just build # Build + WASM +just test # Run tests +---- + +==== Development Workflow + +[source,bash] +---- +# Watch mode () +just watch- + +# Run CLI during development +just cli report + +# Capture test experience +just capture quick +---- + +=== Commit Guidelines + +==== Format + +.... +(): + + + +