android-sdd 1.0.0

package/skills/Build System/Module Dependency Graph Validation/SKILL.md

@@ -0,0 +1,223 @@
+---
+name: module-dependency-graph-validation
+description: >
+  Validating and enforcing module dependency rules in Android multi-module projects.
+  Load this skill when enforcing architecture boundaries between modules,
+  preventing circular dependencies, or visualizing the module dependency graph.
+---
+
+# Module Dependency Graph Validation
+
+## Overview
+In a multi-module Android project, modules must depend on each other in a controlled, directed way. Without enforcement, modules accumulate arbitrary dependencies — creating cycles, slow builds, and architectural drift. Dependency graph validation catches violations at build time.
+
+---
+
+## Core Principles
+
+- Module dependencies must be **directed and acyclic** — no cycles ever
+- Feature modules must **not depend on other feature modules**
+- Only `:app` can depend on all feature modules — it's the composition root
+- Core modules can be depended upon by everyone but depend on nothing above them
+- Validate the graph **at build time** — not in code reviews alone
+
+---
+
+## Module Layer Architecture
+
+```
+:app
+ ├── :feature:home
+ ├── :feature:auth
+ ├── :feature:profile
+ │
+ ├── :core:ui
+ ├── :core:network
+ ├── :core:database
+ ├── :core:domain
+ └── :core:common
+
+Rules:
+- :feature:* → :core:* ✅
+- :feature:* → :feature:* ❌
+- :core:domain → :core:common ✅
+- :core:network → :core:domain ❌ (domain must be pure)
+- :app → everything ✅
+```
+
+---
+
+## Dependency Guard Plugin
+
+```toml
+# libs.versions.toml
+[plugins]
+dependency-guard = { id = "com.dropbox.dependency-guard", version = "0.5.0" }
+```
+
+```kotlin
+// app/build.gradle.kts
+plugins {
+    alias(libs.plugins.dependency.guard)
+}
+
+dependencyGuard {
+    configuration("releaseRuntimeClasspath")
+}
+
+// ✅ Generate baseline
+// ./gradlew dependencyGuard
+
+// ✅ Verify on CI — fails if deps changed without updating baseline
+// ./gradlew dependencyGuardVerify
+```
+
+---
+
+## Module Graph Plugin
+
+```toml
+[plugins]
+module-graph = { id = "com.jraska.module.graph.assertion", version = "2.5.0" }
+```
+
+```kotlin
+// root build.gradle.kts
+plugins {
+    alias(libs.plugins.module.graph)
+}
+
+moduleGraphAssert {
+    maxHeight = 4  // max allowed module depth
+
+    // ✅ Assert no feature-to-feature dependencies
+    restricted = arrayOf(
+        ":feature:.* -> :feature:.*"  // regex: feature modules can't depend on each other
+    )
+
+    // ✅ Assert specific allowed paths
+    allowed = arrayOf(
+        ":feature:.* -> :core:.*",    // features can use core
+        ":app -> :.*"                  // app can use everything
+    )
+}
+
+// ✅ Run validation
+// ./gradlew assertModuleGraph
+```
+
+---
+
+## Custom Gradle Task Validation
+
+```kotlin
+// build-logic/convention/src/main/kotlin/ModuleGraphValidationPlugin.kt
+class ModuleGraphValidationPlugin : Plugin<Project> {
+    override fun apply(target: Project) {
+        target.tasks.register("validateModuleDependencies") {
+            group = "verification"
+            description = "Validates module dependency rules"
+
+            doLast {
+                val violations = mutableListOf<String>()
+                val featureModules = target.rootProject.subprojects
+                    .filter { it.path.startsWith(":feature:") }
+
+                featureModules.forEach { featureModule ->
+                    featureModule.configurations
+                        .filter { it.name == "implementation" }
+                        .flatMap { it.dependencies }
+                        .filterIsInstance<ProjectDependency>()
+                        .filter { it.dependencyProject.path.startsWith(":feature:") }
+                        .forEach { dep ->
+                            violations.add(
+                                "${featureModule.path} -> ${dep.dependencyProject.path} " +
+                                "(feature-to-feature dependency not allowed)"
+                            )
+                        }
+                }
+
+                if (violations.isNotEmpty()) {
+                    throw GradleException(
+                        "Module dependency violations:\n${violations.joinToString("\n")}"
+                    )
+                }
+            }
+        }
+
+        // ✅ Run before every build
+        target.tasks.named("preBuild") {
+            dependsOn("validateModuleDependencies")
+        }
+    }
+}
+```
+
+---
+
+## Visualizing the Module Graph
+
+```bash
+# ✅ Generate dependency graph image (requires graphviz)
+./gradlew generateModuleGraph
+
+# ✅ Using project-report plugin
+./gradlew projectDependencies > module-deps.txt
+
+# ✅ Using gradle-dependency-graph-generator plugin
+plugins {
+    id("com.vanniktech.dependency.graph.generator") version "0.8.0"
+}
+# ./gradlew generateProjectDependencyGraph
+# Output: build/reports/dependency-graph/
+```
+
+---
+
+## Detecting Cycles
+
+```kotlin
+// ✅ Gradle detects cycles automatically — build fails with:
+// "Circular dependency between the following tasks: ..."
+
+// For module-level cycle detection — custom task
+fun detectCycles(modules: List<Project>): List<List<String>> {
+    val graph = buildDependencyGraph(modules)
+    return findCycles(graph)
+}
+
+// ✅ Or use: ./gradlew dependencies
+// Circular module dependencies cause Gradle to fail immediately
+```
+
+---
+
+## Enforcing in CI
+
+```yaml
+# .github/workflows/build.yml
+- name: Validate module graph
+  run: ./gradlew assertModuleGraph
+
+- name: Verify dependency guard
+  run: ./gradlew dependencyGuardVerify
+```
+
+---
+
+## Anti-Patterns
+
+- Feature modules importing other feature modules — breaks independent build and test
+- No automated enforcement — violations accumulate silently
+- `:core:network` depending on `:core:domain` — domain must be framework-free
+- Circular dependencies — Gradle fails but error message can be cryptic
+- Skipping graph validation in CI — local dev can bypass it
+
+---
+
+## Related Skills
+- `modularization` — multi-module architecture design
+- `multi-module-architecture` — module structure patterns
+- `gradle` — Gradle build configuration
+- `dependency-management` — managing what modules depend on
+- `build-orchestration` — building modules in the right order

package/skills/Build System/Specialized/C++/SKILL.md

@@ -0,0 +1,308 @@
+---
+name: c++
+description: >
+  C++ patterns and best practices for Android NDK development.
+  Load this skill when writing C++ code for Android native libraries,
+  using modern C++17 features, managing memory safely, handling
+  concurrency in native code, or structuring native C++ modules.
+---
+
+# C++
+
+## Overview
+Modern C++ (C++17) for Android NDK focuses on safety, expressiveness, and performance. Android's Clang toolchain fully supports C++17. Using RAII, smart pointers, and the standard library eliminates most memory management bugs that plague native Android code.
+
+---
+
+## Core Principles
+
+- **C++17** is the minimum target — use structured bindings, `std::optional`, `std::variant`
+- **RAII everywhere** — resources are always tied to object lifetime
+- **Smart pointers** instead of raw `new`/`delete` — `unique_ptr`, `shared_ptr`
+- **`std::string` not `char*`** — except at JNI boundaries
+- **No raw arrays** — use `std::vector`, `std::array`, `std::span`
+- **const-correctness** — mark everything `const` that doesn't need to change
+
+---
+
+## Memory Management
+
+```cpp
+// ✅ unique_ptr — single ownership
+std::unique_ptr<AESContext> ctx = std::make_unique<AESContext>(key);
+ctx->encrypt(data);   // auto-deleted when ctx goes out of scope
+
+// ✅ shared_ptr — shared ownership
+std::shared_ptr<KeyStore> keyStore = std::make_shared<KeyStore>();
+auto cipher = std::make_shared<AESCipher>(keyStore);
+
+// ✅ RAII wrapper for Android resources
+class AssetGuard {
+public:
+    explicit AssetGuard(AAsset* asset) : asset_(asset) {}
+    ~AssetGuard() {
+        if (asset_) AAsset_close(asset_);
+    }
+    // Disable copy
+    AssetGuard(const AssetGuard&) = delete;
+    AssetGuard& operator=(const AssetGuard&) = delete;
+    // Enable move
+    AssetGuard(AssetGuard&& other) noexcept : asset_(other.asset_) {
+        other.asset_ = nullptr;
+    }
+
+    AAsset* get() const { return asset_; }
+    bool valid() const { return asset_ != nullptr; }
+
+private:
+    AAsset* asset_;
+};
+
+// Usage
+AssetGuard asset(AAssetManager_open(mgr, "config.json", AASSET_MODE_BUFFER));
+if (!asset.valid()) return {};
+// asset is auto-closed when AssetGuard leaves scope
+```
+
+---
+
+## Modern C++17 Features
+
+```cpp
+// ✅ Structured bindings
+std::map<std::string, int> scores = {{"ali", 90}, {"sara", 85}};
+for (const auto& [name, score] : scores) {
+    LOGI("%s: %d", name.c_str(), score);
+}
+
+// ✅ std::optional — nullable without pointers
+std::optional<std::string> findKey(const std::string& id) {
+    auto it = keyMap.find(id);
+    if (it == keyMap.end()) return std::nullopt;
+    return it->second;
+}
+
+auto key = findKey("user_key");
+if (key.has_value()) {
+    encrypt(data, *key);
+}
+
+// ✅ std::variant — type-safe union
+using Result = std::variant<std::vector<uint8_t>, std::string>;
+
+Result encrypt(const std::vector<uint8_t>& data) {
+    if (data.empty()) return std::string("Empty input");
+    return performEncryption(data);
+}
+
+auto result = encrypt(data);
+std::visit([](auto&& val) {
+    using T = std::decay_t<decltype(val)>;
+    if constexpr (std::is_same_v<T, std::vector<uint8_t>>) {
+        // success path
+    } else {
+        LOGE("Error: %s", val.c_str());
+    }
+}, result);
+
+// ✅ if constexpr — compile-time branching
+template<typename T>
+void logValue(T value) {
+    if constexpr (std::is_integral_v<T>) {
+        LOGI("int: %lld", static_cast<long long>(value));
+    } else if constexpr (std::is_floating_point_v<T>) {
+        LOGI("float: %f", static_cast<double>(value));
+    }
+}
+
+// ✅ std::string_view — zero-copy string reference
+void processName(std::string_view name) {
+    LOGI("Processing: %.*s", static_cast<int>(name.size()), name.data());
+}
+```
+
+---
+
+## Error Handling
+
+```cpp
+// ✅ Return std::expected-like result (C++23) or use std::optional / std::variant
+struct Error {
+    int code;
+    std::string message;
+};
+
+// Custom Result type for C++17
+template<typename T>
+class Result {
+public:
+    static Result<T> ok(T value) {
+        Result r;
+        r.value_ = std::move(value);
+        return r;
+    }
+    static Result<T> err(Error error) {
+        Result r;
+        r.error_ = std::move(error);
+        return r;
+    }
+
+    bool isOk() const { return value_.has_value(); }
+    bool isErr() const { return error_.has_value(); }
+    const T& value() const { return *value_; }
+    const Error& error() const { return *error_; }
+
+private:
+    std::optional<T> value_;
+    std::optional<Error> error_;
+};
+
+// Usage
+Result<std::vector<uint8_t>> encryptData(const std::vector<uint8_t>& data) {
+    if (data.empty()) {
+        return Result<std::vector<uint8_t>>::err({-1, "Empty input"});
+    }
+    auto encrypted = performEncryption(data);
+    return Result<std::vector<uint8_t>>::ok(std::move(encrypted));
+}
+```
+
+---
+
+## Concurrency
+
+```cpp
+#include <mutex>
+#include <thread>
+#include <atomic>
+
+// ✅ Thread-safe cache with mutex
+class KeyCache {
+public:
+    std::optional<std::vector<uint8_t>> get(const std::string& id) {
+        std::lock_guard<std::mutex> lock(mutex_);
+        auto it = cache_.find(id);
+        if (it == cache_.end()) return std::nullopt;
+        return it->second;
+    }
+
+    void set(const std::string& id, std::vector<uint8_t> key) {
+        std::lock_guard<std::mutex> lock(mutex_);
+        cache_[id] = std::move(key);
+    }
+
+    void clear() {
+        std::lock_guard<std::mutex> lock(mutex_);
+        cache_.clear();
+    }
+
+private:
+    std::mutex mutex_;
+    std::unordered_map<std::string, std::vector<uint8_t>> cache_;
+};
+
+// ✅ Atomic for simple counters
+std::atomic<int> requestCount{0};
+requestCount.fetch_add(1, std::memory_order_relaxed);
+```
+
+---
+
+## Containers and Algorithms
+
+```cpp
+// ✅ Prefer standard containers
+std::vector<uint8_t> buffer(1024);        // dynamic array
+std::array<uint8_t, 16> iv{};            // fixed-size array
+std::unordered_map<std::string, Key> keys; // hash map
+std::string_view view = "hello";          // non-owning string ref
+
+// ✅ Range-based algorithms
+#include <algorithm>
+#include <numeric>
+
+std::vector<int> values = {3, 1, 4, 1, 5, 9};
+
+// Sort
+std::sort(values.begin(), values.end());
+
+// Find
+auto it = std::find(values.begin(), values.end(), 5);
+if (it != values.end()) { /* found */ }
+
+// Transform
+std::vector<std::string> names;
+std::transform(values.begin(), values.end(),
+    std::back_inserter(names),
+    [](int v) { return std::to_string(v); });
+
+// Accumulate
+int sum = std::accumulate(values.begin(), values.end(), 0);
+```
+
+---
+
+## Secure Memory Handling
+
+```cpp
+// ✅ Zero sensitive memory before freeing
+void secureClear(std::vector<uint8_t>& data) {
+    volatile uint8_t* ptr = data.data();
+    for (size_t i = 0; i < data.size(); i++) {
+        ptr[i] = 0;
+    }
+    data.clear();
+}
+
+// ✅ Secure string for passwords
+class SecureString {
+public:
+    explicit SecureString(std::string s) : data_(std::move(s)) {}
+    ~SecureString() {
+        volatile char* ptr = &data_[0];
+        for (size_t i = 0; i < data_.size(); i++) ptr[i] = '\0';
+    }
+    const std::string& get() const { return data_; }
+    SecureString(const SecureString&) = delete;
+    SecureString& operator=(const SecureString&) = delete;
+private:
+    std::string data_;
+};
+```
+
+---
+
+## Logging Macro
+
+```cpp
+#include <android/log.h>
+
+#define LOG_TAG "NativeLib"
+#define LOGD(...) __android_log_print(ANDROID_LOG_DEBUG, LOG_TAG, __VA_ARGS__)
+#define LOGI(...) __android_log_print(ANDROID_LOG_INFO,  LOG_TAG, __VA_ARGS__)
+#define LOGW(...) __android_log_print(ANDROID_LOG_WARN,  LOG_TAG, __VA_ARGS__)
+#define LOGE(...) __android_log_print(ANDROID_LOG_ERROR, LOG_TAG, __VA_ARGS__)
+
+// Usage
+LOGI("Initialized with key size: %zu", keySize);
+LOGE("Failed to decrypt: error code %d", errorCode);
+```
+
+---
+
+## Anti-Patterns
+
+- Raw `new`/`delete` — use `make_unique` / `make_shared`
+- `char*` for strings in business logic — use `std::string` or `std::string_view`
+- `int` for sizes and indices — use `size_t` or `std::ptrdiff_t`
+- Ignoring return values of security functions — always check errors
+- `std::endl` in log-heavy code — use `"\n"`; `endl` flushes and is slow
+- Capturing `this` in lambdas stored beyond object lifetime — dangling reference
+
+---
+
+## Related Skills
+- `jni` — JNI bridge between C++ and Kotlin
+- `ndk` — NDK toolchain and build system
+- `cryptography` — native crypto implementations
+- `reverse-engineering-resistance` — native code as security layer