# Pureline Specification 1.5: Crystal + Core ## Definition **Pureline** is an opinionated coding style focused on linear control flow, explicit intent, compact formatting, small units, clear ownership, and minimal syntactic or architectural noise. Pureline does not aim to minimize characters. It aims to minimize **unnecessary code**. The preferred reading direction is: ```text Input ↓ Validation ↓ Transformation ↓ Execution ↓ Result ``` Not: ```text if └─ if └─ else └─ if └─ callback └─ branch ``` The central Pureline principles are: > **Linear Flow. Explicit Intent. Minimal Noise. Small Units. Clear Ownership. Cohesion over Size.** **Version 1.5:** Adds the idiomatic Rust profile (`PL-RS-001` through `PL-RS-020`) while preserving all existing rule IDs and the 1.4 Cohesion over Size principle. --- > Extract of the complete specification (pureline-1.5-full.md): Crystal + Core. # 1. Pureline Core These rules apply to all supported languages where the language allows them naturally. | ID | Rule | |---|---| | PL-CORE-001 | Control flow should be as linear as possible | | PL-CORE-002 | Avoid `else` | | PL-CORE-003 | Prefer guard clauses | | PL-CORE-004 | Use the clearest control-flow form for the language; brace-based languages use explicit blocks | | PL-CORE-005 | Idiomatic language-native shorthand is allowed when it remains immediately readable | | PL-CORE-006 | Functions should be small and focused | | PL-CORE-007 | Names must carry meaning | | PL-CORE-008 | Avoid unnecessary abstractions | | PL-CORE-009 | Avoid God Classes and God Modules | | PL-CORE-010 | Prefer immutable state | | PL-CORE-011 | Prefer modern language features where they improve clarity | | PL-CORE-012 | Avoid unnecessary vertical formatting | | PL-CORE-013 | Comments must not compensate for unclear code | | PL-CORE-014 | Handle invalid and error states early | | PL-CORE-015 | Keep important side effects visible | | PL-CORE-016 | Resources must have a clear lifecycle | | PL-CORE-017 | Prefer framework-native APIs | | PL-CORE-018 | Avoid magic values | | PL-CORE-019 | Make dependencies explicit | | PL-CORE-020 | Optimize hot paths deliberately, not accidentally | | PL-CORE-021 | Keep packages and source folders small enough to scan at a glance | | PL-CORE-022 | Cohesion over Size: prefer one coherent responsibility over arbitrary class line limits | --- # 2. Control Flow Control flow is one of the most important parts of Pureline. Pureline standardizes **clarity and structure, not identical syntax across languages**. Java, JavaScript, TypeScript, Go, and Emvus use explicit blocks for control flow. Languages with established readable shorthand, such as Crystal postfix guards, may use that shorthand when the condition and action remain simple. ## PL-CF-001 — Prefer Guard Clauses Preferred: ```java if (request == null) { return Result.empty(); } if (!request.valid()) { return Result.invalid(); } var session = sessions.create(request.user()); return executor.execute(session, request); ``` Avoid: ```java if (request != null) { if (request.valid()) { var session = sessions.create(request.user()); return executor.execute(session, request); } else { return Result.invalid(); } } return Result.empty(); ``` The happy path should remain as close to the base indentation level as possible. ## PL-CF-002 — Avoid `else` Avoid: ```java if (valid) { execute(); } else { reject(); } ``` Prefer: ```java if (!valid) { reject(); return; } execute(); ``` A ternary expression may be used for simple value selection: ```java var state = valid ? State.READY : State.INVALID; ``` Complex nested ternaries are not Pureline. ## PL-CF-003 — Explicit Blocks in Brace-Based Languages In Java, JavaScript, TypeScript, Go, and other brace-based languages, control-flow bodies use explicit blocks. Not Pureline: ```java if (!valid) return; ``` Also not Pureline: ```java if (!valid) return; ``` Pureline: ```java if (!valid) { return; } ``` The same principle applies to `for`, `while`, and comparable control-flow constructs. This rule does **not** ban idiomatic shorthand in languages where that shorthand is a normal, readable part of the language. Crystal postfix guards such as `return unless valid` are Pureline-compliant when kept simple. --- # 3. Naming ## PL-NAME-001 — Names Must Be Meaningful Good: ```text request session player packet handler storage result connection worker ``` Avoid: ```text r s p x tmp obj data2 thing ``` Also avoid names that are unnecessarily long: ```text currentIncomingPlayerConnectionRequestObject ``` The rule is: > **As short as possible, as explicit as necessary.** Exceptions are allowed for established local conventions such as loop counters: ```java for (int i = 0; i < size; i++) { } ``` --- # 4. Functions ## PL-FN-001 — One Clear Responsibility Preferred names: ```text validateRequest() createSession() sendPacket() loadUser() closeConnection() ``` Avoid vague names: ```text handleEverything() process() doStuff() executeAll() ``` A function should normally represent one clearly identifiable action. ### Size guidance ```text ~5–30 lines → normal ~30–50 lines → review 50+ lines → usually split ``` These are heuristics, not absolute limits. --- # 5. Classes and Modules ## PL-STRUCT-001 — One Clear Responsibility Avoid structures like: ```text ServerManager ├─ database ├─ players ├─ packets ├─ commands ├─ configuration ├─ HTTP └─ logging ``` Prefer: ```text server/ ServerRuntime network/ Connection PacketRegistry PacketDispatcher session/ Session SessionService storage/ UserStorage SessionStorage ``` A class has one clear responsibility when its members and internal state contribute to one cohesive concern. **Line count alone does not determine whether a class is well designed.** See `PL-STRUCT-003` for size guidance. # 5.1 Package and Folder Density ## PL-STRUCT-002 — Keep Namespaces Small Enough to Scan Pureline treats file and type density as part of code readability. A package or source folder should be small enough that a developer can understand its contents at a glance without searching through a long flat list of unrelated files. When the limit is exceeded, split the package or folder by responsibility instead of allowing it to become a dumping ground. ### Default limits | Language | Pureline default | |---|---| | Java | Maximum 8 production top-level types/source files per package | | Emvus | Maximum 8 production `.ev` source files per package/source folder | | JavaScript | Maximum 10 production source modules per feature/source folder | | TypeScript | Maximum 10 production source modules per feature/source folder | | Go | Maximum 12 non-test, non-generated `.go` files per package directory | | Crystal | Maximum 10 production `.cr` files per source/namespace folder | | Rust | Maximum 10 hand-maintained production `.rs` files per feature/source folder | These files do not count toward the limit: - tests and specs - generated source files - metadata-only files - `package-info.java` - `module-info.java` - JavaScript/TypeScript barrel files such as `index.ts` or `index.js` - generated bindings or protocol output - migration snapshots and comparable machine-generated artifacts The purpose of this rule is not to force arbitrary folder nesting. A split should introduce a real responsibility boundary. Bad: ```text network/ Connection.java ConnectionFactory.java ConnectionState.java Packet.java PacketCodec.java PacketDecoder.java PacketEncoder.java PacketRegistry.java PacketDispatcher.java PacketHandler.java PacketQueue.java PacketMetrics.java SocketConfig.java SocketRuntime.java ``` Preferred: ```text network/ Connection.java ConnectionFactory.java ConnectionState.java network/packet/ Packet.java PacketCodec.java PacketDecoder.java PacketEncoder.java PacketRegistry.java PacketDispatcher.java network/runtime/ PacketQueue.java PacketMetrics.java SocketConfig.java SocketRuntime.java ``` A project may override these thresholds through a future Pureline configuration file, but the default rule should remain intentionally strict. --- # 5.2 Cohesion over Size ## PL-STRUCT-003 — Cohesion over Size (Zusammengehörigkeit vor Zeilenbegrenzung) > **Cohesion over Size — Zusammengehörigkeit vor Zeilenbegrenzung.** The preferred maximum class size is **guidance, never a hard limit**. Keep strongly related logic together when splitting it would make the code harder to read, maintain, test, or reason about. A larger cohesive class is preferable to multiple artificial classes connected by unnecessary delegation. ### Class size guidance | Class size | Pureline recommendation | |---|---| | Up to 200 lines | Preferred normal case | | 201–400 lines | Unproblematic when the class has a clear responsibility | | 401–600 lines | Deliberate architectural decision; keep its cohesion understandable | | More than 600 lines | Review recommended, **not prohibited** | The ranges are **heuristics, not hard limits**. Crossing a threshold must not, by itself, produce a style violation or require a split. ### When larger classes are justified - **Parsers and lexers:** A cohesive state machine may become more complicated when its states and transitions are scattered across artificial abstractions. - **Algorithms:** Tightly coupled processing phases can be easier to understand and optimize when kept together. - **Central data structures:** Methods sharing the same invariants and internal state can belong in one class. - **Complex but cohesive logic:** Splitting is counterproductive when it adds indirection, unnecessary delegation, or more coordination than clarity. ### When to split anyway Split by **real responsibility boundaries**, not by line count. Indicators include distinct subsystems evolving independently, unrelated reasons to change, weak coupling among groups of methods, or separate lifecycles that are obscured by one class. **Tooling rule:** Pureline Checker and IDE inspections may show an informational size notice with a cohesion-review suggestion, particularly above 600 lines. They must not treat the number of lines as sufficient evidence of a violation, automatically extract classes, or require suppressions merely to keep a cohesive class intact. This principle applies to **all Pureline language profiles**, including Java, JavaScript, TypeScript, Go, Crystal, Rust, and Emvus. Language-specific syntax and idioms continue to take precedence. --- # 6. Formatting ## PL-FMT-001 — Prefer Compact Horizontal Calls Preferred: ```java var box = Block.box(min, min, max, max, max, 16); ``` Avoid unnecessary vertical expansion: ```java var box = Block.box( min, min, max, max, max, 16 ); ``` Vertical formatting is allowed when it reveals meaningful semantic structure. Example: ```java var server = Server.builder() .host(config.host()) .port(config.port()) .executor(executor) .build(); ``` Pureline distinguishes between unnecessary vertical expansion and meaningful semantic grouping. --- # 7. Comments ## PL-DOC-001 — Comments Explain Why, Not What Avoid: ```java // Check if the player exists if (player == null) { return; } ``` Useful comments explain things such as protocol constraints, workarounds, external bugs, non-obvious mathematical behavior, or unusual performance constraints. Code should explain **what** happens. Comments should explain **why** something unusual is necessary. --- # 12. Crystal Profile Crystal keeps its own language identity while following Pureline principles. ## PL-CR-001 — Idiomatic Postfix Guards Are Allowed Crystal postfix conditions are Pureline-compliant when they express a short, obvious guard. Good: ```crystal return unless valid return if closed ``` They fit Pureline well because they can keep guard logic compact and preserve a linear happy path. Use an explicit block when either the condition or the guarded action becomes more complex: ```crystal if session.closed? || session.expired? logger.info("Session is no longer usable") return end ``` The rule is not "avoid postfix conditions." The rule is: use the form that keeps the intent immediately obvious. ## PL-CR-002 — Avoid `else` Avoid: ```crystal if valid execute else reject end ``` Prefer: ```crystal if !valid reject return end execute ``` ## PL-CR-003 — Idiomatic Naming Variables and methods use `snake_case`: ```crystal session_service packet_registry load_user create_session ``` Types use PascalCase: ```crystal SessionService PacketRegistry UserStorage ``` ## PL-CR-004 — Prefer Type Inference Preferred: ```crystal session = create_session(user) ``` Avoid redundant annotations: ```crystal session : Session = create_session(user) ``` when Crystal can infer the type clearly. ## PL-CR-005 — Explicit Nil Guards Preferred: ```crystal user = users.find(id) if user.nil? return end session = create_session(user) ``` Avoid burying expected nil handling inside deeply nested chains. ## PL-CR-006 — Exceptions Are for Exceptional States Expected outcomes should preferably use normal domain modeling such as `nil`, union types, result-like structures, or enums. Exceptions should represent exceptional failure, not ordinary branching. ## PL-CR-007 — Avoid Macro Cleverness Without Need Crystal macros are powerful, but Pureline avoids hiding ordinary behavior behind metaprogramming unless the abstraction produces a clear architectural benefit. Generated behavior should remain predictable and discoverable. --- ## PL-CR-008 — Folder Density A Crystal source or namespace folder may contain at most **10 production `.cr` files** by default. Specs, generated files, bindings, and metadata-only files do not count. When the limit is exceeded, split the namespace by responsibility while preserving idiomatic Crystal structure. --- # 15. Abstraction Rules ## PL-ARCH-001 — Abstraction Requires a Reason Avoid abstractions such as: ```text AbstractBaseFactoryManagerProvider ``` merely to reduce duplication. Good reasons for abstraction include: ```text multiple real implementations clear API boundaries platform-specific implementations test seams dependency inversion shared domain contracts ``` --- # 16. Architecture Pureline prefers clear dependency direction. Example: ```text domain ↓ service ↓ infrastructure ``` or feature-oriented modules: ```text session/ network/ storage/ command/ runtime/ api/ ``` Avoid cycles such as: ```text network → session → storage → network ``` --- # 17. Side Effects Important side effects should remain visible. Preferred: ```java var user = users.load(id); var session = sessions.create(user); sessions.save(session); events.publish(new SessionCreated(session.id())); ``` Potentially misleading: ```java sessions.createAndPersistAndNotify(user); ``` if persistence and event publication are important externally observable actions. Pureline does not require exposing every internal operation. It requires avoiding surprising hidden behavior. --- # 18. Immutability Prefer immutable values by default. Mutation should be intentional, local, and easy to identify. Preferred examples include Java records, TypeScript readonly data, `const` in JavaScript, immutable value objects, and short-lived mutable local state. Avoid shared mutable state where practical. --- # 19. Dependencies Dependencies should be visible in constructors, function parameters, or explicit module wiring. Avoid hidden global access patterns and unnecessary service locators. Dependency injection is encouraged where it improves architecture, but Pureline does not require a heavy DI framework. --- # 20. Performance Pureline prioritizes readability by default, but performance-sensitive paths should be written deliberately. In hot paths: - avoid unnecessary allocations - avoid repeated reflection - cache expensive resolution - use appropriate collections - avoid hidden blocking - reduce unnecessary copying - keep ownership clear Performance optimizations must remain understandable. --- # 23. Pureline Summary Pureline code should feel: - linear - explicit - compact - modern - low-noise - modular - cohesive regardless of line count - predictable - easy to scan - easy to refactor - hard to misunderstand The core rule remains: > **Code without noise.** A second principle governs every language profile: > **Pureline standardizes principles, not syntax.** A language should remain idiomatic. Pureline removes unnecessary noise without stripping away the features that make Java, JavaScript, TypeScript, Go, Crystal, Rust, or Emvus effective in the first place.