@deftai/directive-content 0.55.0

package/languages/javascript.md

@@ -0,0 +1,163 @@
+# JavaScript Standards
+
+Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
+
+**⚠️ See also**: [main.md](../../main.md) | [PROJECT.md](../../PROJECT.md) | [telemetry.md](../tools/telemetry.md)
+
+**Stack**: ES2022+, Node 20+; Build: Vite/esbuild; Testing: Vitest/Jest; Lint: ESLint + Prettier; Web: React/Next.js
+
+**Note**: For TypeScript projects, prefer [typescript.md](./typescript.md). Use JavaScript only when TypeScript is not feasible.
+
+## Standards
+
+### Documentation
+- ! JSDoc comments for all exported functions, classes, and constants
+- ! Document `@param`, `@returns`, `@throws` on public functions
+- ~ Use `@typedef` and `@type` for complex shapes when not using TypeScript
+
+### Testing
+See [testing.md](../coding/testing.md).
+
+- ! Use Vitest (or Jest) + coverage
+- Files: `*.spec.js` or `*.test.js`
+
+### Coverage
+- ! ≥85% coverage
+- ! Count src/\*
+- ! Exclude entry points, scripts, generated code, config files
+
+### Style
+- ! Use ESLint + Prettier (project configs required, checked in)
+- ! Use `"use strict"` in CommonJS; ESM is strict by default
+- ~ Prefer ESM (`import`/`export`) over CommonJS (`require`/`module.exports`)
+
+### Types & Safety
+- ! Use `===` / `!==`; ⊗ `==` / `!=` (type coercion bugs)
+- ! Use `const` by default; `let` when reassignment needed; ⊗ `var`
+- ! Use template literals over string concatenation
+- ~ Use optional chaining (`?.`) and nullish coalescing (`??`)
+- ⊗ Rely on implicit type coercion for logic (truthiness traps)
+- ~ Use JSDoc + `// @ts-check` for type-checked JavaScript when TS is not available
+
+### Error Handling
+- ! Use `try..catch` for async operations; always handle promise rejections
+- ! Throw `Error` instances (or subclasses), not strings or plain objects
+- ⊗ Swallow errors (empty catch blocks)
+- ~ Create domain-specific error classes extending `Error`
+- ~ Use `.catch()` or `try..catch` with `await`; ⊗ unhandled promise rejections
+
+### Async
+- ! Use `async`/`await` over raw Promises/callbacks for readability
+- ! Handle all promise rejections
+- ⊗ Mix callbacks and promises in the same API
+- ⊗ Use `new Promise()` when `async`/`await` suffices (promise constructor anti-pattern)
+- ~ Use `AbortController` / `AbortSignal` for cancellable operations
+- ~ Use `Promise.allSettled()` when partial failures are acceptable
+
+### Modules & Imports
+- ! One module per file; name file after the primary export
+- ! Use named exports for most cases; default exports for React components / main entry
+- ⊗ Circular imports
+- ~ Use barrel files (`index.js`) sparingly — only for public API surfaces
+
+### Security
+- ⊗ Use `eval()`, `Function()`, or `innerHTML` with untrusted data
+- ⊗ Hardcode secrets in source
+- ! Sanitize/validate all external input
+- ~ Use Content Security Policy (CSP) headers in web applications
+
+### Telemetry
+- See [telemetry.md](../tools/telemetry.md)
+- ~ Structured logging (pino, winston) for production
+- ~ Sentry.io for error tracking
+- ? OpenTelemetry for distributed tracing
+
+## Commands
+
+See [commands.md](./commands.md).
+
+## Patterns
+
+### Testing
+```javascript
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { createUser } from "./user-service.js";
+
+describe("createUser", () => {
+  const mockRepo = { save: vi.fn() };
+
+  beforeEach(() => { vi.clearAllMocks(); });
+
+  it("saves user and returns id", async () => {
+    mockRepo.save.mockResolvedValue({ id: 42 });
+    const result = await createUser(mockRepo, { name: "Alice" });
+    expect(result.id).toBe(42);
+    expect(mockRepo.save).toHaveBeenCalledWith({ name: "Alice" });
+  });
+
+  it("throws on invalid name", async () => {
+    await expect(createUser(mockRepo, { name: "" }))
+      .rejects.toThrow("name is required");
+  });
+});
+```
+
+### Error Handling
+```javascript
+class NotFoundError extends Error {
+  constructor(entity, id) {
+    super(`${entity} not found: ${id}`); this.name = "NotFoundError";
+  }
+}
+
+async function getUser(id) {
+  const res = await fetch(`/api/users/${id}`, { signal: AbortSignal.timeout(5000) });
+  if (!res.ok) throw new NotFoundError("User", id);
+  return await res.json();
+}
+```
+
+### Modern Patterns
+```javascript
+function createConfig({ host = "localhost", port = 3000, debug = false } = {}) { return { host, port, debug }; }
+const city = user?.address?.city ?? "Unknown";
+const [users, orders] = await Promise.all([fetchUsers(), fetchOrders()]);
+const activeEmails = users.filter(u => u.active).map(u => u.email);
+```
+
+## Anti-Patterns
+
+Items marked ⊗ in Standards above are not repeated here.
+
+- ≉ **`for...in` on arrays**: Use `for...of` or array methods
+- ≉ **Barrel re-exports everywhere**: Hurts tree-shaking
+- ≉ **God modules**: Keep files <300 lines
+
+## Hygiene
+
+**Types:**
+- ~ Use JSDoc `@type` annotations or `// @ts-check` to surface weak types without migrating to TypeScript
+- ⊗ Untyped `.json()` parse results passed directly to callers without shape validation
+
+**Error handling:**
+- ⊗ Empty `catch` blocks — handle the specific error or re-throw
+- ⊗ Unhandled promise rejections — every `Promise` must be `.catch()`-ed or returned
+- ⊗ `catch (e) { console.log(e) }` without re-throw — log-and-continue hides failures from callers
+
+**Dead code:**
+- ~ Run `knip` to detect unused exports, files, and dependencies
+- ~ Add `knip` as a `task hygiene` target
+
+**Circular dependencies:**
+- ~ Run `madge --circular --exit-code src/` to detect cycles
+- ⊗ Circular imports — restructure or extract shared code to a lower-level module
+
+## Compliance Checklist
+
+- ! JSDoc on all exported APIs
+- ! See [testing.md](../coding/testing.md) for testing requirements
+- ! ESLint + Prettier configured and enforced
+- ! `const`/`let` only; `===`/`!==` only
+- ! All promises handled; `async`/`await` for I/O
+- ⊗ `var`, `eval()`, loose equality, unhandled rejections
+- ! Run `task check` before commit

package/languages/julia.md

@@ -0,0 +1,175 @@
+# Julia Standards
+
+Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
+
+**⚠️ See also**: [main.md](../../main.md) | [PROJECT.md](../../PROJECT.md)
+
+**Stack**: Julia 1.10+; Packages: Pkg.jl; Testing: `Test` stdlib + Aqua.jl; Docs: Documenter.jl; Format: JuliaFormatter.jl; Lint: JET.jl / Aqua.jl
+
+## Standards
+
+### Documentation
+- ! Docstrings (triple-quoted `"""..."""`) on all exported functions, types, and modules
+- ! Document arguments, return values, and examples in docstrings
+- ! Use Documenter.jl for package documentation with `makedocs()`
+- ~ Use `jldoctest` blocks for testable examples in docstrings
+- ~ Cross-reference with `` [`OtherFunction`](@ref) `` syntax
+
+### Testing
+See [testing.md](../coding/testing.md).
+
+- ! Use `Test` standard library (`@test`, `@testset`, `@test_throws`)
+- ! Place tests in `test/runtests.jl` (entry point) with modular test files
+- ! Test type stability with `@inferred` for performance-critical functions
+- ~ Use Aqua.jl for package quality checks (ambiguities, unbound args, piracy)
+- ~ Use `@test_logs` for testing logging output
+
+### Coverage
+- ! ≥80% coverage (measured via Coverage.jl or Codecov integration)
+- ! Count src/**
+- ! Exclude scripts, notebooks, generated code
+
+### Style
+- ! Use JuliaFormatter.jl with project `.JuliaFormatter.toml` checked in
+- ! 4-space indentation
+- ! Line length ≤92 characters (Julia convention)
+- ! Follow [Julia Style Guide](https://docs.julialang.org/en/v1/manual/style-guide/)
+- ~ Use `BlueStyle` or `SciMLStyle` formatting preset
+
+### Naming Conventions
+- ! `snake_case` for functions and variables: `compute_mean`, `max_iterations`
+- ! `PascalCase` for types (structs), modules, and abstract types: `DataProcessor`, `AbstractModel`
+- ! `SCREAMING_SNAKE_CASE` for global constants
+- ! Mutating functions end with `!`: `sort!`, `push!`, `normalize!`
+- ! Predicate functions start with `is`/`has`: `isvalid`, `haskey`
+- ! Type parameters: single uppercase letters or short descriptive: `T`, `S`, `ElType`
+- ⊗ Prefixing types with `Abstract` — use `Abstract` as a prefix for abstract types only
+
+### Type System
+- ! Use abstract types to define interfaces and hierarchies
+- ! Use parametric types for generic data structures
+- ! Annotate function arguments with types for public API (dispatch + documentation)
+- ! Use `Union{T, Nothing}` instead of sentinel values for optional data
+- ~ Use `Val{x}` for compile-time dispatch on values
+- ≉ Over-constraining argument types — accept the broadest useful type
+- ≉ Type annotations on local variables (let inference work)
+
+### Multiple Dispatch
+- ! Design functions around multiple dispatch: define methods for different type combinations
+- ! Keep method signatures specific; avoid `::Any` arguments in exported functions
+- ! Use dispatch instead of `if typeof(x) == ...` branches
+- ⊗ Type piracy (adding methods to types you don't own for functions you don't own)
+- ~ Use trait-based dispatch patterns for interface polymorphism
+
+### Performance
+- ! Write type-stable functions (verify with `@code_warntype`)
+- ! Avoid global variables in hot paths; use `const` or pass as arguments
+- ! Pre-allocate output arrays; use in-place operations (`mul!`, `ldiv!`)
+- ! Use `@views` for array slicing to avoid copies
+- ~ Use `@inbounds` only after bounds-checking correctness is verified
+- ~ Profile with `@time`, `@allocated`, `BenchmarkTools.@btime`
+- ≉ Abstract-typed containers (`Vector{Any}`) in performance-critical code
+- ⊗ Type-unstable code in inner loops
+
+### Modules & Packages
+- ! One module per package; module name matches package name
+- ! Use `export` for public API; keep internal functions unexported
+- ! Use `Pkg.jl` for dependency management; `Project.toml` + `Manifest.toml`
+- ! Specify compat bounds in `Project.toml` for all dependencies
+- ~ Use submodules for large packages
+- ⊗ `using PackageName` in package code — use `import` or qualified access
+
+### Error Handling
+- ! Use exceptions (`throw`, `error`) for exceptional conditions
+- ! Define custom exception types inheriting from `Exception`
+- ! Use `try`/`catch`/`finally` with specific exception types
+- ⊗ Catching `Exception` broadly without rethrowing
+- ~ Use return values (`nothing`, `Union{T, Nothing}`) for expected missing data
+
+### Reproducibility
+- ! Commit `Manifest.toml` for applications (not for packages)
+- ! Use `Pkg.instantiate()` for reproducible environments
+- ! Set random seeds (`Random.seed!`) for stochastic code; document in scripts
+- ~ Use DrWatson.jl for scientific project management
+
+### Security
+- ⊗ Hardcode secrets or credentials in source
+- ! Validate all external inputs (file paths, user data, network)
+- ~ Use environment variables for secrets (`ENV["API_KEY"]`)
+
+### Telemetry
+- ~ Use `Logging` stdlib (`@info`, `@warn`, `@error`) with structured messages
+- ~ Use `LoggingExtras.jl` for log routing and formatting
+- ? OpenTelemetry via HTTP/REST bridge for distributed systems
+
+## Commands
+
+See [commands.md](./commands.md).
+
+## Patterns
+
+### Multiple Dispatch
+```julia
+struct Circle radius::Float64 end
+struct Rectangle width::Float64; height::Float64 end
+
+area(c::Circle) = π * c.radius^2
+area(r::Rectangle) = r.width * r.height
+```
+
+### Testing
+```julia
+using Test
+@testset "area" begin
+    @test area(Circle(1.0)) ≈ π
+    @test area(Rectangle(3.0, 4.0)) == 12.0
+    @inferred area(Circle(1.0))  # type stability
+end
+```
+
+### Parametric Types
+```julia
+struct BoundedBuffer{T}
+    data::Vector{T}; capacity::Int
+    function BoundedBuffer{T}(cap::Int) where {T}
+        cap > 0 || throw(ArgumentError("capacity must be positive"))
+        new{T}(Vector{T}(), cap)
+    end
+end
+
+function push!(buf::BoundedBuffer{T}, item::T) where {T}
+    length(buf.data) >= buf.capacity && throw(OverflowError("buffer full"))
+    Base.push!(buf.data, item)
+end
+```
+
+### In-Place Operations
+```julia
+"Normalize vector `v` in-place."
+function normalize!(v::AbstractVector{<:AbstractFloat})
+    n = norm(v)
+    n == 0 && throw(ArgumentError("cannot normalize zero vector"))
+    v ./= n
+end
+```
+
+## Anti-Patterns
+
+Items marked ⊗ in Standards above are not repeated here.
+
+- ≉ **Over-constrained argument types**: Accept broadest useful type
+- ≉ **`eval`/`@eval` at runtime**: Prefer compile-time metaprogramming
+- ≉ **Non-`const` globals**: Forces runtime type checks
+- ≉ **Array slicing without `@views`**: Creates unnecessary copies
+
+## Compliance Checklist
+
+- ! Docstrings on all exported functions/types with examples
+- ! See [testing.md](../coding/testing.md) for testing requirements
+- ! `Test` stdlib + Aqua.jl; ≥80% coverage
+- ! JuliaFormatter + JET.jl enforced
+- ! Julia style guide; `snake_case` functions; `!` suffix for mutating
+- ! Type-stable code; verified with `@code_warntype`
+- ! Compat bounds in `Project.toml` for all dependencies
+- ⊗ Type piracy, type-unstable loops, `Vector{Any}`, `using` in packages
+- ! Run `task check` before commit

package/languages/kotlin.md

@@ -0,0 +1,193 @@
+# Kotlin Standards
+
+Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
+
+**⚠️ See also**: [main.md](../../main.md) | [PROJECT.md](../../PROJECT.md)
+
+**Stack**: Kotlin 2.0+; Build: Gradle (Kotlin DSL); Testing: JUnit 5 + kotest; Lint: detekt; Format: ktfmt/ktlint; Docs: KDoc
+
+## Standards
+
+### Documentation
+- ! KDoc (`/** */`) on all public classes, functions, properties, and interfaces
+- ! Document `@param`, `@return`, `@throws`, `@sample` for public API
+- ! Module-level `package-info.kt` or `README.md` per module
+- ~ Use `@see` for cross-references; `@sample` for linking to example code
+
+### Testing
+See [testing.md](../coding/testing.md).
+
+- ! Use JUnit 5 (`@Test`, assertions) or kotest (spec-style)
+- ! Place tests in `src/test/kotlin/` mirroring source package structure
+- ! Test edge cases: nulls, empty collections, boundary values
+- ~ Use MockK for mocking; avoid PowerMock
+- ~ Use kotest property-based testing for algorithmic code
+
+### Coverage
+- ! ≥80% coverage (measured via JaCoCo or Kover)
+- ! Count src/main/kotlin/**
+- ! Exclude entry points, generated code, DI configuration
+
+### Style
+- ! Follow [Kotlin Coding Conventions](https://kotlinlang.org/docs/coding-conventions.html)
+- ! Use detekt for static analysis (project `detekt.yml` checked in)
+- ! Use ktfmt or ktlint for formatting
+- ! 4-space indentation, no tabs
+- ! Line length ≤120 characters
+
+### Naming Conventions
+- ! `camelCase` for functions, properties, local variables, parameters
+- ! `PascalCase` for classes, interfaces, objects, type aliases, enums
+- ! `SCREAMING_SNAKE_CASE` for `const val` and compile-time constants
+- ! `camelCase` for enum values (Kotlin convention) or `SCREAMING_SNAKE_CASE` if Java-interop heavy
+- ! Prefix backing properties with `_`: `private val _items` → `val items`
+- ⊗ Hungarian notation or type prefixes (`strName`, `iCount`)
+
+### Null Safety
+- ! Use Kotlin's type system: `T` for non-null, `T?` for nullable
+- ! Prefer safe calls (`?.`) and Elvis (`?:`) over `!!`
+- ⊗ `!!` (non-null assertion) in production code without precondition check
+- ! Use `requireNotNull()` / `checkNotNull()` with descriptive messages
+- ~ Use `let`/`also`/`run` scoping functions for null-safe chaining
+- ≉ Platform types (`T!`) leaking into public API — annotate explicitly
+
+### Idiomatic Kotlin
+- ! Use data classes for value objects (immutable DTOs)
+- ! Use sealed classes/interfaces for restricted hierarchies
+- ! Use `when` expression (exhaustive) over `if-else` chains for type/enum dispatch
+- ! Use extension functions to add behavior without inheritance
+- ! Use `val` (immutable) by default; `var` only when mutation is required
+- ! Use scope functions (`let`, `apply`, `with`, `run`, `also`) appropriately
+- ⊗ Java-style getters/setters — use Kotlin properties
+- ≉ `companion object` as a dumping ground — extract to top-level or utility
+
+### Coroutines & Concurrency
+- ! Use structured concurrency: `coroutineScope`, `supervisorScope`
+- ! Never launch unstructured coroutines (`GlobalScope.launch`)
+- ! Use `Dispatchers.IO` for I/O, `Dispatchers.Default` for CPU
+- ! Use `Flow` for reactive streams; `StateFlow`/`SharedFlow` for state
+- ⊗ `GlobalScope` — always use a structured scope
+- ⊗ `runBlocking` in production code (except at top-level entry points)
+- ~ Use `withContext` for dispatcher switching inside a coroutine
+- ~ Cancel coroutines cooperatively; check `isActive` in long computations
+
+### Error Handling
+- ! Use exceptions for exceptional conditions; `Result` or sealed classes for expected failures
+- ! Define custom exception hierarchies for domain errors
+- ! Always catch specific exceptions, not `Exception` or `Throwable`
+- ⊗ Catching `Throwable` (swallows `CancellationException`, `OutOfMemoryError`)
+- ⊗ Empty catch blocks
+- ~ Use `runCatching` for functional error handling where appropriate
+
+### Dependencies
+- ! Use Gradle Kotlin DSL (`build.gradle.kts`)
+- ! Pin dependency versions via version catalogs (`libs.versions.toml`)
+- ! Minimize transitive dependencies; use `implementation` not `api` by default
+- ~ Use `dependencyUpdates` plugin for version management
+- ⊗ `compile` (deprecated) — use `implementation` or `api`
+
+### Interop (Java)
+- ! Annotate public API with `@JvmStatic`, `@JvmOverloads`, `@JvmField` where Java callers exist
+- ! Use `@Nullable` / `@NotNull` annotations on Java code consumed by Kotlin
+- ~ Keep Java interop surface minimal in Kotlin-first projects
+
+### Security
+- ⊗ Hardcode secrets or credentials in source
+- ! Validate all external inputs
+- ~ Use sealed classes for security-sensitive state machines (auth, permissions)
+
+### Telemetry
+- ~ Use SLF4J + Logback (or kotlin-logging) for structured logging
+- ~ Use Micrometer for metrics
+- ? OpenTelemetry for distributed tracing
+
+## Commands
+
+See [commands.md](./commands.md).
+
+## Patterns
+
+### Data Class + Sealed Hierarchy
+```kotlin
+data class User(val id: Long, val email: String, val name: String, val role: Role)
+
+sealed interface Result<out T> {
+    data class Success<T>(val data: T) : Result<T>
+    data class Failure(val error: DomainError) : Result<Nothing>
+}
+
+sealed class DomainError(val message: String) {
+    class NotFound(msg: String) : DomainError(msg)
+    class Validation(msg: String) : DomainError(msg)
+}
+```
+
+### Coroutines & Testing
+```kotlin
+class UserService(private val userRepo: UserRepository, private val audit: AuditLogService) {
+    suspend fun getUser(id: Long): User = coroutineScope {
+        val user = async { userRepo.findById(id) }
+        val log = async { audit.log("user:read", id) }
+        log.await(); user.await() ?: throw UserNotFoundException(id)
+    }
+}
+
+// MockK test
+class UserServiceTest {
+    private val userRepo = mockk<UserRepository>()
+    private val audit = mockk<AuditLogService>(relaxed = true)
+    private val sut = UserService(userRepo, audit)
+
+    @Test fun `returns user when found`() = runTest {
+        coEvery { userRepo.findById(1L) } returns User(1L, "a@b.com", "Vis", Role.ADMIN)
+        assertEquals("Vis", sut.getUser(1L).name)
+    }
+
+    @Test fun `throws when not found`() = runTest {
+        coEvery { userRepo.findById(99L) } returns null
+        assertThrows<UserNotFoundException> { sut.getUser(99L) }
+    }
+}
+```
+
+### Extension Functions
+```kotlin
+fun String.toSlug() = lowercase().replace(Regex("[^a-z0-9\\s-]"), "").replace(Regex("\\s+"), "-").trim('-')
+fun <T> List<T>.secondOrNull(): T? = if (size >= 2) this[1] else null
+```
+
+## Anti-Patterns
+
+Items marked ⊗ in Standards above are not repeated here.
+
+- ≉ **`var` by default**: Use `val`; mutate only when necessary
+- ≉ **`companion object` as dumping ground**: Use top-level functions
+- ≉ **`if-else` for sealed dispatch**: Use exhaustive `when`
+- ≉ **String templates in logging**: Use parameterized logging
+
+## Hygiene
+
+**Types:**
+- ⊗ `Any` as parameter or return type where a concrete type or bounded generic is knowable
+- ⊗ `!!` (non-null assertion) outside tests without a documented invariant proving non-null at that point
+- ~ Use sealed classes/interfaces over `Any`-typed discriminated unions
+
+**Error handling:**
+- ⊗ Empty `catch` blocks or catching `Throwable` — already in Standards; treat as a hygiene blocker in review
+- ⊗ `runCatching { }.getOrNull()` to silently discard failures — inspect the `Failure` case
+
+**Dead code:**
+- ~ detekt rules `UnusedPrivateMember` and `UnusedImports` detect dead code; enable in CI
+- ~ Run `gradle dependencies` to audit unused or duplicate dependencies
+- ⊗ `@Suppress("unused")` to hide dead code from detekt instead of deleting it
+
+## Compliance Checklist
+
+- ! KDoc on all public API
+- ! See [testing.md](../coding/testing.md) for testing requirements
+- ! JUnit 5 or kotest; ≥80% coverage via Kover/JaCoCo
+- ! detekt + ktfmt/ktlint configured and enforced
+- ! Kotlin coding conventions; null safety via type system
+- ! Structured concurrency; no `GlobalScope`
+- ⊗ `!!`, `GlobalScope`, catching `Throwable`, empty catches, `var` by default
+- ! Run `task check` before commit