Official documentation

Documentation audit

Technical reference for Documentation audit — Joss language and Joss Red ecosystem.

CLI Syntax GitHub

Comprehensive Audit and Documentation Reconstruction Report for Joss

Before: Contributing to Joss. After: 2026 Technical Audit. General index: Joss Documentation.

1. Introduction and purpose of the audit

This report documents the exhaustive audit and deep reconstruction of the Joss programming language documentation.

The absolute guiding principle of this work has been:

The source code and its executed tests are the single source of truth.

All documentation was cross-checked against the actual behavior of the lexical analyzer (pkg/parser/lexer.go), the Pratt parser (pkg/parser), the abstract syntax tree AST (pkg/parser/ast*.go), the type and inference system (pkg/typesystem), the semantic analyzer (pkg/analyzer), the Go evaluator and execution engine (pkg/core), the native compiler (pkg/ir, pkg/backend/native), the registered native classes and functions, and the automated test suite.

2. Initial state diagnosis and documentation debt

At the start of the audit, existing documentation showed both technical and pedagogical gaps relative to the actual capabilities of the codebase:

A. Pedagogical and beginner onboarding gap

  • The entry point in PRIMEROS_PASOS.md taught users to manually create folders with mkdir instead of leveraging the official generator joss new console mi-primer-joss.
  • The course order introduced FUNCIONES.md before COLECCIONES.md, even though functions used lists and spread operators (...$numeros), and placed ERRORES.md after CLASES.md even though functions already required understanding throw.
  • Explicit explanations were missing for the structure generated by joss new console (public class Main { Init main() { ... } }), the difference between declaring a variable for the first time (var $x = 1) and reassigning it ($x = 2), and the difference between interpreting (joss run) and compiling to a native binary (joss build).

B. Code-implemented features incorporated into the guides

During the line-by-line inspection of the source code, the following features were documented and integrated into the learning path and reference: 1. The Pipeline operator (|>): - Implemented in pkg/parser/parser.go (PIPE_OP precedence), pkg/parser/parser_expressions.go, and evaluated in pkg/core/evaluator_pipeline.go. - Allows composing functions from left to right: " ada " |> trim |> strtoupper. 2. guard and defer statements: - guard (condición) : { return ... } statically validated with JOSS-FLOW-005 for early returns and smart cast narrowing. - defer { ... } for LIFO deferred execution when the function frame exits. 3. Immutable records (public record Nombre(...)) and Generic Classes (class Caja<T>): - Nominal validation and automatic field immutability (JOSS-CONST-001). 4. The Elvis operator (?:), null coalescing (??), null-coalescing assignment (??=), and null-safe navigation (?->): - Documented with their exact evaluation and type-narrowing rules. 5. Concurrent channel consumption via foreach and multiplexing with select: - Producer-consumer patterns and lazy generators with yield. 6. Unified project discovery (semanticanalyzer.LoadProject and ExecutePrepared): - joss analyze, joss run, joss server, and joss build uniformly load main.joss, routes.joss, api.joss, and all subdirectories under app/ (including app/libs) into a single PreparedProgram.

C. Technical precision fixes

  • Exact numeric promotion: Corrected in SISTEMA_TIPOS.md that the only implicit numeric promotion between distinct types is int → decimal; mixing int and float or float and decimal requires explicit conversion (JOSS-ARITH-003).
  • Mandatory variable declaration: Updated all documentation examples to declare variables with var, an explicit type, mixed, or const before reassigning them, complying with JOSS-SYM-001 / JOSS-DECL-007.
  • Exact diagnostic codes: Aligned CLASES.md and DIAGNOSTICOS.md with pkg/analyzer/validation_nominal.go and member_resolution.go (JOSS-DECL-003 for duplicate methods, JOSS-DECL-004 for nominal conflicts and unfulfilled interface contracts, JOSS-DECL-005 for unimplemented abstract methods, and JOSS-DECL-006 for abstract class instantiation or let transition).

3. Project documentation architecture (Course vs. Reference separation)

The documentation was structured to clearly distinguish the Progressive course from the Formal technical reference:

flowchart TD
    COURSE["1. APRENDER JOSS (Capítulos 0 al 9 — Curso Progresivo: PRIMEROS_PASOS a PROYECTO_WEB + GLOSARIO)"] --> REF["2. REFERENCIA TÉCNICA (SISTEMA_TIPOS, SINTAXIS, GRAMATICA, DIAGNOSTICOS, FUNCIONES_GLOBALES, MODULOS_NATIVOS, CLI)"]
    REF --> APPS["3. DESARROLLO DE APLICACIONES (ESTRUCTURA_PROYECTO, SERVIDOR, CONTROLADORES, MIDDLEWARE, VISTAS, MODELOS, MIGRACIONES)"]
    APPS --> INT["4. INTERNALS Y CONTRIBUIDORES (ARQUITECTURA, CONTRIBUIR, AUDITORIAS Y NOVEDADES)"]

4. Engine technical details recorded for reference

During the source-code audit and test execution, the following runtime behaviors were recorded and explained with technical honesty in the documentation:

  1. Detection of break / continue inside conditional blocks within loops:
    • The loop plan optimizer (pkg/runtime/plan/callable.go) inspects direct statements of the loop body (BlockHasBreakOrContinue). If break or continue is nested inside a ternary in a top-level loop where hasControl is false, the jump is not intercepted by executeLoopBodyProtected.
  2. Non-mutating behavior of array_pop and array_shift:
    • Global functions array_pop($arr) and array_shift($arr) return the last or first element without shrinking the length of the original slice, unlike the mutating method $arr->pop().
  3. Differences between published metadata and dynamic return values in some built-ins:
    • Certain legacy functions (boolval, json, microtime, strpos, base64_decode, array_merge) have simplified static signatures in builtins.go even though at runtime they return composite or boolean values on failure.

5. Formal verification and executed tests

To guarantee that no document contains broken links, outdated examples, or inconsistencies with the runtime, the full validation suite is executed:

  1. Catalog, native documentation, and internationalization (i18n) verification: 
    
go run ./tools/cataloggen --check
go run ./tools/docgen --check
go run ./tools/docsi18n --check
  2. Unit and integration test suite: 
    
go vet ./...
go test ./...
  3. Contract and navigation verification (TestDocumentationNavigationAndPublicMirror and TestDocumentationContracts):
    • Checking all local Markdown links across documents.
    • Verifying byte-for-byte parity between docs/*.md and ejemplos/Joss-Red-JosSecurity/assets/docs/*.md.
    • Executing and analyzing all blocks tagged with <!-- joss-run: ... -->, <!-- joss-check: ... -->, and <!-- joss-error: ... -->.

6. Conclusion

With this reconstruction, Joss documentation combines a progressive pedagogical path (capable of guiding from absolute scratch with joss new console up to web applications and native binaries with joss build) with a rigorous technical reference, 100% synchronized and verified against the source code.