lgtm-specs 0.0.4

package/rules/laws/go/GO-00016-test-libraries.md

@@ -0,0 +1,35 @@
+# Test Libraries (GO-00016)
+
+**Source**: [Unit Testing Guidelines](../../../docs/meta/languages/go/07-testing.md#4-libraries)
+**Tags**: #operational #go #testing #libraries
+**Related**: [Test Structure](GO-00015-aaa-pattern.md)
+
+## Definition
+
+Use standard libraries to enforce fail-fast behavior.
+
+## Requirements
+
+1.  **Require over Assert**: Use `testify/require` by default. This stops the test immediately on failure, preventing noisy/invalid subsequent errors.
+2.  **Assert usage**: Use `testify/assert` ONLY when you explicitly want to collect multiple failures (e.g., checking 10 independent fields of a struct).
+
+## Anti-Patterns
+
+- **Manual Checks**: `if got != want { t.Errorf(...) }`. Use the library for better diffs.
+- **Panic in Test**: Using `panic` instead of `t.Fatal`.
+
+## Examples
+
+**Bad:**
+
+```go
+assert.NoError(t, err) // Continues if err != nil, causing a panic later
+result.DoSomething()   // PANIC: result is nil
+```
+
+**Good:**
+
+```go
+require.NoError(t, err) // Stops test here
+result.DoSomething()    // Safe
+```

package/rules/laws/go/GO-00017-comments.md

@@ -0,0 +1,37 @@
+# Comments & Godoc (GO-00017)
+
+**Source**: [API Design](../../../docs/meta/languages/go/02-api-design.md#3-documentation-godoc)
+**Tags**: #operational #go #documentation
+**Related**: [Clean Packages](GO-00006-packages.md)
+
+## Definition
+
+Go documentation is a contract. It must be complete, formatted, and readable by `godoc`.
+
+## Requirements
+
+1.  **Format**: Comments for `func Foo` must start with `// Foo ...`.
+2.  **Exported Symbols**: Every exported function, type, and constant MUST have a comment.
+3.  **Directives**: Use `//go:generate` or `//Deprecated:` on separate lines.
+
+## Anti-Patterns
+
+- **Stutter**: `// Foo does foo.` (Add value or don't comment).
+- **Disconnect**: `// Returns error` when the function signature changed to return `bool`.
+
+## Examples
+
+**Bad:**
+
+```go
+// NewService ...
+func NewService() *Service
+```
+
+**Good:**
+
+```go
+// NewService initializes the backend and connects to the DB.
+// It returns ErrConfigMissing if the config is nil.
+func NewService() *Service
+```

package/rules/laws/go/GO-00018-test-isolation.md

@@ -0,0 +1,38 @@
+# Test Isolation (GO-00018)
+
+**Source**: [Unit Testing Guidelines](../../../docs/meta/languages/go/07-testing.md#3-standalone-tests)
+**Tags**: #operational #go #testing #isolation
+**Related**: [AAA Pattern](GO-00015-aaa-pattern.md)
+
+## Definition
+
+Each test must verify a single concept and be independent.
+
+## Requirements
+
+1.  **One Concept**: Verify one specific behavior or edge case per test function.
+2.  **Standalone**: Use separate `Test` functions when setup logic differs. Do not force disjoint cases into a single table.
+3.  **Independence**: Tests must not depend on state left by other tests.
+
+## Anti-Patterns
+
+- **Complex Tables**: Adding `if` statements inside a table loop to handle different mocks.
+- **Coupling**: Relying on global state modified by a previous test.
+
+## Examples
+
+**Bad:**
+
+```go
+func TestProcess(t *testing.T) {
+  // Tests success AND failure in one function
+  // ...
+}
+```
+
+**Good:**
+
+```go
+func TestProcess_Success(t *testing.T) { ... }
+func TestProcess_Failure_Network(t *testing.T) { ... }
+```

package/rules/laws/go/GO-00019-test-comments.md

@@ -0,0 +1,36 @@
+# Test Documentation (GO-00019)
+
+**Source**: [Unit Testing Guidelines](../../../docs/meta/languages/go/07-testing.md#5-documentation)
+**Tags**: #operational #go #testing #documentation
+**Related**: [Documentation](../../constitution/CONS-00032-documentation.md)
+
+## Definition
+
+Tests must document _how_ they verify the system.
+
+## Requirements
+
+1.  **Phase Comments**: Use `// Arrange`, `// Act`, `// Assert` (or descriptive equivalents) to label sections.
+2.  **Descriptive**: Prefer descriptive comments like `// Setup service with valid config` over just `// Arrange`.
+3.  **Docstring**: Complex tests should have a docstring explaining the scenario being tested.
+
+## Anti-Patterns
+
+- **Superficial**: Using `// Act` labels without explaining _what_ is being tested if the code isn't obvious.
+- **No Comments**: A complex mock setup with no explanation of why those values were chosen.
+
+## Examples
+
+**Bad:**
+
+```go
+// Act
+result := do()
+```
+
+**Good:**
+
+```go
+// Act: Attempt to run the main loop with a cancelled context
+result := do(ctx)
+```

package/rules/laws/go/GO-00020-mocking.md

@@ -0,0 +1,36 @@
+# Mocking Strategy (GO-00020)
+
+**Source**: [Unit Testing Guidelines](../../../docs/meta/languages/go/07-testing.md#6-mocking)
+**Tags**: #operational #go #testing #mocking
+**Related**: [Test Isolation](GO-00018-test-isolation.md)
+
+## Definition
+
+Use mocks to isolate the unit under test from its dependencies.
+
+## Requirements
+
+1.  **Interfaces**: Mock at the interface level.
+2.  **Generation**: Use tools like `mockery` or `gomock` to generate mocks from interfaces.
+3.  **Expectations**: Explicitly define expected calls and return values in the Arrange phase.
+
+## Anti-Patterns
+
+- **Real IO**: Connecting to a real database in a unit test.
+- **Partial Mocks**: Mocking only some methods of a struct (leads to flaky behavior).
+
+## Examples
+
+**Bad:**
+
+```go
+s := &Service{db: &RealDB{}} // Uses real DB
+```
+
+**Good:**
+
+```go
+mockDB := new(MockDB)
+mockDB.On("Get", "id").Return(nil, nil)
+s := &Service{db: mockDB}
+```

package/rules/laws/go/GO-00021-configuration.md

@@ -0,0 +1,36 @@
+# Configuration (GO-00021)
+
+**Source**: [12-Factor App](../../../docs/meta/languages/go/08-config-layout.md#3-configuration-12-factor)
+**Tags**: #operational #go #configuration
+**Related**: [Clean Packages](GO-00006-packages.md)
+
+## Definition
+
+Configuration should be strict, explicit, and sourced from the environment.
+
+## Requirements
+
+1.  **Environment Source**: Config comes from Env Vars, not hardcoded constants.
+2.  **Explicit Loading**: Use `viper` or `env` to load config into a struct at startup.
+3.  **Defaults**: Define sensible defaults in code.
+
+## Anti-Patterns
+
+- **Global Config**: `config.Get("key")` scattered in code. Pass config struct explicitly.
+- **Hardcoded Secrets**: API keys committed in source.
+
+## Examples
+
+**Bad:**
+
+```go
+const Timeout = 30 * time.Second
+```
+
+**Good:**
+
+```go
+type Config struct {
+  Timeout time.Duration `env:"TIMEOUT" envDefault:"30s"`
+}
+```

package/rules/laws/go/GO-00022-observability.md

@@ -0,0 +1,34 @@
+# Observability (GO-00022)
+
+**Source**: [Resilience Patterns](../../../docs/meta/languages/go/03-resilience.md#4-observability-slog)
+**Tags**: #operational #go #logging #observability
+**Related**: [Transparency](../../constitution/CONS-00027-transparency.md)
+
+## Definition
+
+Use structured logging to provide machine-readable insights.
+
+## Requirements
+
+1.  **Library**: Use `log/slog` (Standard Library) or `zap`.
+2.  **Structure**: Log key-value pairs, not formatted strings.
+3.  **Levels**: Use `Info` for state changes, `Error` for failures requiring action, `Debug` for tracing.
+
+## Anti-Patterns
+
+- **Print Debugging**: `fmt.Println("here")`.
+- **String Formatting**: `log.Printf("User %s failed", user)`. (Hard to query).
+
+## Examples
+
+**Bad:**
+
+```go
+log.Printf("Processed item %d in %v", id, duration)
+```
+
+**Good:**
+
+```go
+slog.Info("item processed", "id", id, "duration", duration)
+```

package/rules/laws/go/GO-00023-dependency-management.md

@@ -0,0 +1,28 @@
+# Dependency Management (GO-00023)
+
+**Source**: [Go Modules](../../../docs/meta/languages/go/08-config-layout.md#2-dependency-management)
+**Tags**: #operational #go #modules #security
+**Related**: [Clean Packages](GO-00006-packages.md)
+
+## Definition
+
+Manage dependencies explicitly using Go Modules.
+
+## Requirements
+
+1.  **Modules**: Use `go.mod` and `go.sum` for reproducible builds.
+2.  **MVS**: Understand Minimal Version Selection. To upgrade, explicit `go get` is needed.
+3.  **Vendoring**: Use `go mod vendor` if hermetic builds are required (e.g., critical infra).
+
+## Anti-Patterns
+
+- **GOPATH**: Relying on legacy GOPATH workspace.
+- **Direct Modification**: Editing `go.mod` manually without running `go mod tidy`.
+
+## Examples
+
+**Bad:**
+Importing code from GitHub without a version tag in `go.mod`.
+
+**Good:**
+`require github.com/pkg/errors v0.9.1`

package/rules/laws/go/GO-00024-project-layout.md

@@ -0,0 +1,30 @@
+# Project Layout (GO-00024)
+
+**Source**: [Standard Go Project Layout](../../../docs/meta/languages/go/08-config-layout.md#1-the-standard-layout)
+**Tags**: #structural #go #architecture #layout
+**Related**: [Clean Packages](GO-00006-packages.md)
+
+## Definition
+
+Adhere to the Standard Go Project Layout to separate concerns and enforce visibility.
+
+## Requirements
+
+1.  **Cmd**: Entry points go in `/cmd/<appname>/main.go`. No business logic here.
+2.  **Internal**: Private logic goes in `/internal`. This compiler-enforced boundary prevents accidental API leakage.
+3.  **Pkg**: Public library code goes in `/pkg`. This is a commitment to stability.
+
+## Anti-Patterns
+
+- **Root Dump**: Putting `main.go`, `utils.go`, and `model.go` all in the root directory (except for trivial CLIs).
+- **Src Folder**: Using a `/src` directory (Java/Node style). Go does not use this standard.
+
+## Examples
+
+**Bad:**
+`/main.go`
+`/utils/helper.go`
+
+**Good:**
+`/cmd/server/main.go`
+`/internal/auth/login.go`

package/rules/laws/go/GO-00025-concurrency-patterns.md

@@ -0,0 +1,39 @@
+# Concurrency Patterns (GO-00025)
+
+**Source**: [Concurrency Architecture](../../../docs/meta/languages/go/01-concurrency.md#2-patterns)
+**Tags**: #runtime #go #concurrency #patterns
+**Related**: [Actor Model](GO-00001-actor-model.md)
+
+## Definition
+
+Use structured patterns to manage concurrency complexity.
+
+## Requirements
+
+1.  **Pipeline**: Break processing into linear stages connected by channels (`Source -> Process -> Sink`).
+2.  **Fan-Out**: Distribute work to a fixed pool of workers.
+3.  **Bounded**: All channels must be bounded (or the number of goroutines fixed) to prevent memory exhaustion.
+
+## Anti-Patterns
+
+- **Unbounded Goroutines**: `go func()` in a loop without a semaphore or worker pool.
+- **Leaky Pipeline**: A stage that fails to close its output channel on exit, deadlocking the next stage.
+
+## Examples
+
+**Bad:**
+
+```go
+for job := range jobs {
+  go process(job) // Spawns infinite goroutines
+}
+```
+
+**Good:**
+
+```go
+// Fan-out to 10 workers
+for i := 0; i < 10; i++ {
+  go worker(jobs)
+}
+```

package/rules/laws/go/README.md

@@ -0,0 +1,45 @@
+# The Law of Go
+
+These rules define the engineering standards for Go development within the LGTM organization.
+
+## Index
+
+### Concurrency & Core
+
+- [GO-00001: The Actor Model](GO-00001-actor-model.md): Communicate via channels; isolate state in goroutines.
+- [GO-00004: Context Propagation](GO-00004-context.md): First argument is `ctx`; use `errgroup` for management.
+- [GO-00008: Concurrency Safety](GO-00008-safety.md): Maps/Slices are unsafe; use Mutex or Atomic.
+- [GO-00025: Concurrency Patterns](GO-00025-concurrency-patterns.md): Pipelines, Fan-Out, and Bounded Concurrency.
+
+### API & Architecture
+
+- [GO-00002: API Design](GO-00002-api-design.md): Accept Interfaces, Return Structs.
+- [GO-00006: Clean Packages](GO-00006-packages.md): Purpose-driven naming; no `utils`; use Standard Layout.
+- [GO-00017: Comments & Godoc](GO-00017-comments.md): Document exported symbols; explain intent.
+- [GO-00021: Configuration](GO-00021-configuration.md): Use Env Vars; explicit struct loading (12-Factor).
+- [GO-00023: Dependency Management](GO-00023-dependency-management.md): Use Modules, MVS, and Vendoring.
+- [GO-00024: Project Layout](GO-00024-project-layout.md): `/cmd`, `/internal`, `/pkg`.
+
+### Resilience & Reliability
+
+- [GO-00003: Error Handling](GO-00003-error-handling.md): Wrap with `%w`; check with `errors.Is`.
+- [GO-00007: Circuit Breakers](GO-00007-circuit-breakers.md): Fail fast on external dependencies.
+- [GO-00011: Retry Strategy](GO-00011-retry.md): Exponential backoff with jitter for transient errors.
+- [GO-00012: Rate Limiting](GO-00012-rate-limiting.md): Protect resources with `rate.Limiter`.
+- [GO-00022: Observability & Slog](GO-00022-observability.md): Structured key-value logging.
+
+### Performance & Optimization
+
+- [GO-00005: Runtime Performance](GO-00005-performance.md): Pre-allocate slices; reduce allocations.
+- [GO-00010: Escape Analysis](GO-00010-escape-analysis.md): Keep variables on stack to reduce GC.
+- [GO-00013: I/O Buffering](GO-00013-io-buffering.md): Use `bufio` to minimize system calls.
+- [GO-00014: Memory Layout](GO-00014-memory-layout.md): Order structs largest-to-smallest for alignment.
+
+### Testing
+
+- [GO-00009: Table-Driven Tests](GO-00009-table-driven-test.md): Data-only structs; identical execution loop.
+- [GO-00015: AAA Pattern](GO-00015-aaa-pattern.md): Arrange, Act, Assert structure.
+- [GO-00016: Test Libraries](GO-00016-test-libraries.md): Use `testify/require` (Fail Fast).
+- [GO-00018: Test Isolation](GO-00018-test-isolation.md): One concept per test; no shared state.
+- [GO-00019: Test Documentation](GO-00019-test-comments.md): Descriptive phase comments.
+- [GO-00020: Mocking Strategy](GO-00020-mocking.md): Mock interfaces; use generation tools.

package/rules/laws/typescript/README.md

@@ -0,0 +1,14 @@
+# The Law of TypeScript
+
+These rules define the engineering standards for TypeScript development within the LGTM organization.
+
+## Index
+
+- [TS-00001: Ban Any](TS-00001-no-any.md): Forbidden `any`; use `unknown` and narrowing.
+- [TS-00002: Immutability](TS-00002-immutability.md): Use `const` and `readonly` by default.
+- [TS-00003: Async Hygiene](TS-00003-async.md): `async/await` only; no floating promises.
+- [TS-00004: Strict Null Checks](TS-00004-strict-null.md): Explicit handling of `null` and `undefined`.
+- [TS-00005: Discriminated Unions](TS-00005-unions.md): Use `kind` field for exhaustive switching.
+- [TS-00006: Interface vs Type](TS-00006-interface.md): Use `interface` for public APIs.
+- [TS-00007: Generics](TS-00007-generics.md): Constrain generics (`T extends X`).
+- [TS-00008: Module Organization](TS-00008-modules.md): Group by Feature, not Type; use Barrels.

package/rules/laws/typescript/TS-00001-no-any.md

@@ -0,0 +1,39 @@
+# Ban Any (TS-00001)
+
+**Source**: [The Law of TypeScript](../../../docs/meta/languages/typescript/01-strictness.md#1-no-any)
+**Tags**: #behavioral #typescript #safety #type-system
+**Related**: [Safety](../../constitution/CONS-00015-safety.md)
+
+## Definition
+
+The usage of `any` is strictly forbidden. It defeats the purpose of the type system.
+
+## Requirements
+
+1.  **Unknown**: Use `unknown` for uncertain data.
+2.  **Validation**: Validate `unknown` with Zod or Type Guards before usage.
+3.  **Generics**: Use Generics for reusable functions, not `any`.
+
+## Anti-Patterns
+
+- **Lazy Typing**: `func(data: any)` because "I don't know the shape yet."
+- **Implicit Any**: Disabling `noImplicitAny` in tsconfig.
+
+## Examples
+
+**Bad:**
+
+```typescript
+function process(data: any) {
+  return data.id;
+}
+```
+
+**Good:**
+
+```typescript
+function process(data: unknown) {
+  if (isUser(data)) return data.id;
+  throw new Error("Invalid data");
+}
+```

package/rules/laws/typescript/TS-00002-immutability.md

@@ -0,0 +1,36 @@
+# Immutability (TS-00002)
+
+**Source**: [The Law of TypeScript](../../../docs/meta/languages/typescript/02-immutability.md#immutability--state)
+**Tags**: #behavioral #typescript #state #safety
+**Related**: [Safety](../../constitution/CONS-00015-safety.md)
+
+## Definition
+
+Mutation is a common source of bugs. Default to immutability.
+
+## Requirements
+
+1.  **Const**: Use `const` by default. `let` is allowed only for counters/accumulators.
+2.  **Readonly**: Use `readonly` for array and object properties where possible.
+3.  **Spread**: Use spread syntax (`{...old, new}`) instead of mutation (`obj.key = val`).
+
+## Anti-Patterns
+
+- **Push**: `arr.push(x)` (mutates). Prefer `[...arr, x]`.
+- **Var**: Never use `var`.
+
+## Examples
+
+**Bad:**
+
+```typescript
+const list = [1, 2];
+list.push(3);
+```
+
+**Good:**
+
+```typescript
+const list = [1, 2];
+const newList = [...list, 3];
+```

package/rules/laws/typescript/TS-00003-async.md

@@ -0,0 +1,35 @@
+# Async Hygiene (TS-00003)
+
+**Source**: [The Law of TypeScript](../../../docs/meta/languages/typescript/03-async.md#1-asyncawait)
+**Tags**: #runtime #typescript #async #control-flow
+**Related**: [Deep Modules](../../constitution/CONS-00009-deep-modules.md)
+
+## Definition
+
+Asynchronous code must be explicit and linear.
+
+## Requirements
+
+1.  **Async/Await**: Use `async/await` exclusively.
+2.  **No Floating Promises**: Do not leave promises un-awaited.
+3.  **Void**: Use `void` operator if the result is intentionally ignored.
+
+## Anti-Patterns
+
+- **Then Chains**: `.then().catch()` (Legacy).
+- **Mix**: Mixing callbacks with Promises.
+
+## Examples
+
+**Bad:**
+
+```typescript
+fetch(url).then((res) => res.json());
+```
+
+**Good:**
+
+```typescript
+const res = await fetch(url);
+const data = await res.json();
+```

package/rules/laws/typescript/TS-00004-strict-null.md

@@ -0,0 +1,38 @@
+# Strict Null Checks (TS-00004)
+
+**Source**: [The Law of TypeScript](../../../docs/meta/languages/typescript/01-strictness.md#2-strict-null-checks)
+**Tags**: #behavioral #typescript #safety #null
+**Related**: [Safety](../../constitution/CONS-00015-safety.md)
+
+## Definition
+
+`null` and `undefined` are distinct values and must be handled explicitly.
+
+## Requirements
+
+1.  **Strict Mode**: `strictNullChecks` must be enabled.
+2.  **No Bang**: Avoid non-null assertion (`!`) unless absolutely necessary.
+3.  **Optional Chaining**: Use `?.` for safe access.
+
+## Anti-Patterns
+
+- **Blind Access**: `user.address.city` when address can be undefined.
+- **Implicit undefined**: Assuming a value exists because "it should be there."
+
+## Examples
+
+**Bad:**
+
+```typescript
+function getLength(s: string | null) {
+  return s.length; // Error: Object is possibly 'null'
+}
+```
+
+**Good:**
+
+```typescript
+function getLength(s: string | null) {
+  return s?.length ?? 0;
+}
+```

package/rules/laws/typescript/TS-00005-unions.md

@@ -0,0 +1,35 @@
+# Discriminated Unions (TS-00005)
+
+**Source**: [The Law of TypeScript](../../../docs/meta/languages/typescript/05-control-flow.md#1-discriminated-unions)
+**Tags**: #structural #typescript #types #patterns
+**Related**: [Safety](../../constitution/CONS-00015-safety.md)
+
+## Definition
+
+Use a shared literal field to distinguish between variants of a union type.
+
+## Requirements
+
+1.  **Discriminant**: Add a `type` or `kind` field to every member of a union.
+2.  **Exhaustiveness**: Switch statements should cover all cases (or use `default: assertNever()`).
+
+## Anti-Patterns
+
+- **Type Guard Soup**: Checking `if ('prop' in obj)` to distinguish types.
+- **Partial Unions**: Unions where members overlap ambiguously.
+
+## Examples
+
+**Bad:**
+
+```typescript
+type Result = { data?: string; error?: Error }; // Ambiguous
+```
+
+**Good:**
+
+```typescript
+type Result =
+  | { status: "success"; data: string }
+  | { status: "error"; error: Error };
+```

package/rules/laws/typescript/TS-00006-interface.md

@@ -0,0 +1,38 @@
+# Interface vs Type (TS-00006)
+
+**Source**: [The Law of TypeScript](../../../docs/meta/languages/typescript/04-design.md#1-interface-vs-type)
+**Tags**: #structural #typescript #design
+**Related**: [API Design](../go/GO-00002-api-design.md)
+
+## Definition
+
+Use `interface` for object shapes and public APIs; use `type` for unions and primitives.
+
+## Requirements
+
+1.  **Interfaces**: Use for defining the shape of objects, classes, and service contracts.
+2.  **Types**: Use for Union types (`A | B`), Intersection types, and Primitives.
+3.  **Consistency**: Stick to one convention per project if not specified.
+
+## Anti-Patterns
+
+- **Empty Interface**: `interface Empty {}` (matches anything).
+- **Type for Objects**: `type User = { id: string }` (Interfaces provide better error messages).
+
+## Examples
+
+**Bad:**
+
+```typescript
+type Service = {
+  run(): void;
+};
+```
+
+**Good:**
+
+```typescript
+interface Service {
+  run(): void;
+}
+```

package/rules/laws/typescript/TS-00007-generics.md

@@ -0,0 +1,38 @@
+# Generics (TS-00007)
+
+**Source**: [The Law of TypeScript](../../../docs/meta/languages/typescript/04-design.md#2-generics)
+**Tags**: #structural #typescript #generics #reusability
+**Related**: [DRY](../../constitution/CONS-00006-dry.md)
+
+## Definition
+
+Use generics to create reusable components, but constrain them to ensure safety.
+
+## Requirements
+
+1.  **Constraints**: Always use `extends` to constrain generics (`T extends object`).
+2.  **Defaults**: Provide defaults (`T = string`) if appropriate.
+3.  **Naming**: Use meaningful names (`TData`, `TResponse`) or standard single letters (`T`, `U`) for abstract util types.
+
+## Anti-Patterns
+
+- **Unconstrained**: `func<T>(arg: T)` when `T` must have a `.id` property.
+- **Over-Generic**: Making a function generic when it only accepts `string | number`.
+
+## Examples
+
+**Bad:**
+
+```typescript
+function getId<T>(item: T) {
+  return item.id; // Error
+}
+```
+
+**Good:**
+
+```typescript
+function getId<T extends { id: string }>(item: T) {
+  return item.id;
+}
+```