Coding Directives

Coding Directives

Apply tested's established Go style: prefer cohesive types with methods, small consumer-owned interfaces, explicit package ownership, standard-library building blocks, wrapped errors, and focused table-driven tests.

File and package discipline

• Add the repository Apache License 2.0 copyright header to every new Go source and test file. Match the wording and year convention already present in the repository.
• Put orchestration and exit policy in pkg/app, command grammar in pkg/cli, child lifecycle in pkg/runner, wire decoding in pkg/protocol, normalized state in pkg/result, profile semantics in pkg/coverage, projections in pkg/report, durable process outcome in pkg/runstatus, and managed publication in pkg/artifact.
• Keep main.go limited to process setup, app invocation, and final exit.
• Keep exported surfaces minimal. Export a symbol only when another package needs the contract; keep helpers and concrete adapters unexported.
• Store report-owned HTML, CSS, and JavaScript sources under pkg/report/assets/, compile them with the standard embed package, and parse them from the embedded filesystem. Return asset parse/assembly errors from renderer construction; never depend on runtime asset paths or hide whole pages in Go raw-string literals.
• Avoid import cycles and convenience packages that mix unrelated ownership. Move a shared primitive only when its ownership is genuinely cross-domain.
• Keep repository-wide serialization-tag policy and the exported-struct census in internal/tag. Register every new exported production struct: validate canonical snake_case names for each supported format, or record a concise exemption reason for runtime-only, custom-decoded, or format-specific types. Avoid custom-build-tag-only exported structs; a platform-only exported type requires a matching platform-specific compliance registry entry and native CI coverage.

Design types around behavior

• Use cohesive structs with methods for runners, framers, aggregators, profile sets, renderers, publishers, and application services.
• Keep each struct responsible for one lifecycle or policy. Split types that simultaneously execute, parse, aggregate, render, and publish.
• Define small interfaces in the consuming package. Prefer the concrete type when substitution is unnecessary, and compose behavior instead of creating a broad framework interface.
• Use utility functions only for stateless, narrowly scoped transformations that do not naturally belong to a type.
• Pass configuration through constructors or explicit option structs. Validate required dependencies and bounds before starting external work.
• Avoid package-global mutable state. Treat reusable renderers and parsers as immutable or create them per run.

Context, processes, and concurrency

• Place context.Context first on operations that execute, wait, stream, publish, or may block. Propagate it unchanged unless a documented child lifetime requires a derived context.
• Start commands from an argv slice with exec.CommandContext or a package abstraction that preserves argv boundaries. Never build a shell command from user-controlled arguments.
• Own every goroutine, pipe, timer, and process. Provide a finite completion path, propagate cancellation, drain streams, stop timers, close owned files, and wait for goroutines before returning.
• Isolate platform-specific process-tree behavior behind small files or types with build constraints. Preserve the same cancellation contract on every supported platform.
• Avoid channels without a documented producer, consumer, close owner, and bounded buffering policy.

Errors and status

• Return errors instead of panicking. Permit panic only in a test helper whose sole purpose is to fail test setup immediately.
• Wrap errors at ownership boundaries with %w and useful operation context: for example, start Go tests, decode an event, parse a profile, render JUnit, or publish an artifact.
• Preserve typed or inspectable causes for child exit, signal, cancellation, framing, coverage, threshold, rendering, and publication failures. Do not reduce all failures to strings.
• Keep cleanup errors when they affect evidence integrity. When several causes occur, retain them with errors.Join or an explicit result while applying the app's status precedence separately.
• Do not use a later report error to overwrite a child failure. Do not return success merely because a partial report was written.

Evidence and security

• Write captured child bytes before parsing them. Do not trim, normalize, recolor, redact, or re-encode the compatibility JSONL evidence.
• Create managed directories with 0700 and files with 0600; apply explicit modes rather than relying on a permissive umask.
• Resolve and validate managed paths beneath the output root. Reject traversal, symlink escapes, special-file targets, and unsafe replacement boundaries.
• Escape text for its actual destination: terminal controls, HTML, JSON, XML, Markdown, and filesystem metadata have different rules.
• Apply configured redaction to live and derived presentations. Keep exact raw evidence private and make its sensitivity explicit in the manifest rather than silently altering it.
• Avoid logging environment values, command secrets, raw test payloads, or unredacted diagnostics outside the secured evidence boundary.

Determinism and data modeling

• Sort map-derived output with explicit stable keys. Preserve source order only when source order is part of the contract.
• Represent package, test, action, occurrence ordinal, terminal state, diagnostic provenance, and duration quality explicitly. Avoid sentinel text for semantic states.
• Distinguish absent, zero, incomplete, and malformed values. Do not convert a missing duration to a measured zero or missing coverage to zero percent.
• Use integer statement weights and counts for coverage calculations; convert to a percentage only at the presentation boundary with documented rounding.
• Make serialization schemas versionable and keep optional fields meaningful. Avoid timestamps, random IDs, host paths, or map order that make equivalent result fixtures differ unnecessarily.

Standard library first

Prefer os/exec, context, encoding/json, encoding/xml, html/template, io, bufio, path/filepath, errors, time, and crypto/sha256 before adding dependencies. Add an external module only when it materially improves a required contract, review its license and maintenance posture, and keep it behind a package-owned boundary.

Tests and verification

• Add table-driven tests beside the owning package. Name cases by behavior and cover success, boundary values, malformed input, cancellation, and cleanup.
• Use t.TempDir, t.Setenv, deterministic clocks/readers, and fake consumer-facing interfaces. Do not depend on the developer's module cache, global environment, terminal, or network.
• Exercise real subprocess helpers only through controlled test binaries and time-bounded contexts. Verify process-tree cleanup without leaving children.
• Add golden files only for stable user-visible formats. Normalize permitted variability, compare exact bytes, and require an explicit update action.
• Test escaping and redaction with hostile HTML, XML, Markdown, ANSI, path, and secret-shaped inputs. Test modes and symlink rejection on supported systems.
• Run gofmt on every changed Go file, focused package tests, and go test ./.... Before integration, run race-enabled tests and cross-build the supported operating-system and architecture matrix.
• Treat go vet, race, and cross-build failures as implementation defects or explicitly documented platform exclusions; do not hide them in automation.