Development

Development

Contents

• Forbidden
• Work Rules
• Consequence Analysis
• Plugin Configuration
• Testing
• Validation
• Change Integrity
• Evidence Adoption

Forbidden

Read the contracts skill before changing maintained production declarations. Its common checklist owns implementation acknowledgments; scoped checklists apply by responsibility. When a failure disproves an assumption, correct its owner and remove superseded compensations in the same repair.

These four are never acceptable; choosing any one means the approach is already wrong.

• No monkey-patching or hardcoding. Don't special-case a consumer, a fixture name, or an expected value to make output match. Fix the general logic.
• No test-passing-only logic. Code exists to be correct, not to turn a check green. A branch whose only purpose is to satisfy one assertion is a bug in disguise.
• No forcing a broken design. When the same failure keeps returning under patch after patch, the design is wrong. Stop, find the root cause, and fix the design instead of looping forever on symptoms.
• No whack-a-mole. Don't patch the one case that surfaced and move on. Think expansively about every case the same root cause can produce, and seal them all with coverage so the class of failure cannot recur.

Work Rules

• Choose the principled course. Time, difficulty, and the breadth of consequences require more careful analysis and validation; they never justify a shortcut, leaving a verified consequence unaddressed, or a weaker acceptance standard.
• Match existing conventions. Before adding a file, function, or test, open a nearby peer and mirror its naming, location, and code style; don't create parallel structures.
• Respect package boundaries. The shared native transform lives under packages/typia/native; don't fork a second transform into an adapter package or reintroduce a TypeScript-side transformer.
• Keep package detection installation-safe. Resolve the target package root, as packages/typia/src/transform.ts does with require.resolve("typia/package.json"); workspace path substrings and hard-coded fixture names fail for npm consumers.
• Use the workspace catalogs. pnpm-workspace.yaml owns samchon, typescript, rolldown, and utils; the ttsc family, Evidence, tstl and tgrid use catalog:samchon, and internal package references use workspace:^.
• Keep local outputs local. Do not commit .env files or the .tgz artifacts generated under experiments/tarballs/.
• Preserve the public contract in .agents/skills/project/SKILL.md. Renaming or removing typia.*, @typia/interface types, or the plugin descriptor shape is a deliberate product change, not incidental cleanup.
• When public behavior changes, update the matching page under website/src/content/docs/** in the same change. Follow .agents/skills/documentation/SKILL.md.
• Run pnpm format only in the final pre-merge cleanup after implementation and CI repairs are complete, not before each commit or push. Commit its integrated result and require green CI on that final head before merging. If later edits require formatting, return to this final cleanup gate. Parallel issue-campaign implementation batches defer the repository-wide formatter to their dedicated Post-Campaign Cleanup pull request.

Consequence Analysis

Treat a reported example as one witness of a cause, not the complete problem statement. Before changing code, trace the same cause through:

• every caller and downstream consumer;
• normal, error, and recovery state transitions;
• concurrency, caching, and generated output;
• Windows and POSIX behavior;
• compatibility constraints and boundary inputs.

Fix the verified class of failure, not only the reported witness. Cover positive, negative, and boundary cases without expanding the user's product goal.

Plugin Configuration

ttsc discovers typia by default from the ttsc.plugin.transform entry in packages/typia/package.json. Consumer projects add a compilerOptions.plugins entry with transform: "typia/lib/transform" only when they need to set optional transform flags.

packages/typia/src/transform.ts is a JavaScript descriptor source, not a transformer. It resolves the installed typia package and returns the Go command at packages/typia/native/cmd/ttsc-typia; ttsc builds that source into the workspace cache. Keep type analysis, AST rewriting, diagnostics, and typia-owned options (functional, numeric, finite, and undefined) on the Go side.

Test workspaces normally use typia/lib/transform. Source-only workspaces such as the benchmark may point at typia/src/transform.ts, but that still loads the same descriptor and native command. Do not add a second plugin host to make a local layout pass.

Testing

Read the testing contracts for every test and the E2E contracts when it exercises a necessary real component boundary. Classify by actual execution, not language, directory name, filesystem use, or duration. Maintained helpers answer production contracts when they own implementation decisions.

One test case per file, named after what it asserts. This is the rule for new and changed cases in both languages, even where older files predate it.

Go tests

• Public and contract tests: keep black-box and exported-API coverage under packages/typia/test/**, mirroring the native concern where practical. These tests import the native module through packages/typia/test/go.mod and run with pnpm test:go:public.
• Colocated native tests: keep same-package implementation, command, transform, and emitter coverage beside the Go source as packages/typia/native/**/*_test.go. Untagged cases run with pnpm test:go:native.
• Native-internal tagged tests: use //go:build typia_native_internal only when the case requires internal-only coverage. Root pnpm test:go does not enable that tag; run go -C packages/typia/test test -tags typia_native_internal ../native/... when tagged coverage is relevant.

Use one Test* function per test file and mirror a nearby test's package, fixture, and cleanup pattern. Command-level transform regressions belong near packages/typia/native/cmd/ttsc-typia; public contract probes belong under packages/typia/test.

TypeScript suites

pnpm test:packages starts every tests/test-* workspace. They have these shapes:

• Function-per-file: test-typia-schema, test-langchain, test-mcp, test-vercel, and test-utils discover src/features/**/test_*.ts through DynamicExecutor. Export exactly one test_<snake_case> function from a matching filename. DynamicExecutor selects and reports a test by its exported name, so a name that disagrees with its file makes the test unreachable by that file's name. test-utils, test-mcp, test-langchain, test-vercel, and test-jev additionally run portable unit cases from src/unit/features/**/test_*.ts, registered explicitly through node:test without the native plugin (pnpm --filter ./tests/<workspace> test:unit); they follow the same one-function-per-file naming rule.
• Generated matrices: test-typia-automated and test-utils-automated delete and regenerate src/features/** when they run. Do not hand-edit those trees. Change the controller/template metadata or @typia/template; keep the committed ObjectSimple composite layer in test-typia-automated/src/composite/** hand-maintained.
• Transform rejection: test-error compiles invalid call sites and asserts the diagnostics that reject them. A failed build publishes no output, so the suite reads no emitted JavaScript: it requires the build to fail, every fixture to typecheck, and every fixture to be named by a typia diagnostic. Add cases beside their feature group, and keep each fixture valid TypeScript that only typia rejects — a type error aborts the build before the transform runs and would leave the suite with nothing to observe.
• Type compilation: test-interface is a compile-only TypeScript tsc --noEmit suite for @typia/interface type contracts and public typia signatures; type-only factory checks execute no factory.

Use TestValidator and DynamicExecutor from @nestia/e2e, @typia/template structures and TestServant, and each suite's local internal/ helpers. Do not reach into another suite's internals or duplicate a reusable structure inside one test workspace.

Assert structural equality with TestEquality from @typia/template/equality. Its equals is symmetric and compares Date, Map, and Set by content; use subset only when an assertion pins some fields of a larger result on purpose, with the expected value first. Never call TestValidator.equals: it walks only its first argument's keys and sees no content in dates, maps, or sets, so it passes whatever the actual lost (#2401). Never call TestValidator.error either: on a synchronous task it swallows its own failure and passes whether or not the task throws (#2460). Assert a synchronous throw by comparing TestEquality.thrown(task) with the expected message, and an asynchronous one by awaiting task().then(() => undefined, (error: unknown) => error) and comparing what it rejects with. Compare prototypes and other identities with ===.

Open every new or materially changed case with a doc comment in the same three-part shape: a one-line Verifies ... headline, a short paragraph stating the non-obvious why (which branch or regression is being pinned), and a 2+-step numbered list summarizing the scenario.

/**
 * Verifies typia.llm.schema emits `anyOf` for a discriminated union.
 *
 * Locks the union branch of the LLM schema converter. A regression in branch
 * selection would silently emit one variant and lose the other from the
 * function-calling schema.
 *
 * 1. Declare two object variants with a shared discriminator.
 * 2. Generate the LLM schema for their union.
 * 3. Assert both variants remain in the emitted `anyOf`.
 */
export const test_llm_schema_anyof = (): void => {
  /* ... */
};

Coverage, not happy paths

A test that only feeds a transform its ordinary successful input and asserts that the result is accepted proves one path, not correctness. The native transformer spans validators, serializers, schemas, decoders, diagnostics, and generated helpers; each predicate or branch needs more than its happy path:

• The transformation direction. When a call should be rewritten, assert observable emitted or runtime behavior that differs from the untransformed stub. For generators, start from hand-written input and verify the generated output, not only that an existing output compiles.
• A negative twin for every positive. Wherever a predicate accepts, rewrites, narrows, serializes, or reports a diagnostic, pin an adjacent case one property away where it must not do so. An over-match stays invisible until the counter-example exists.
• Boundaries. Cover the empty case, the single-element case, recursion limits, optional and nullable members, exact numeric limits, deepest nesting, and the tag or compiler option that flips the decision.
• Oracle-derived expectations. Take expected behavior from TypeScript semantics and the authoritative JSON Schema, OpenAPI, Protocol Buffer, or adapter contract, never from whatever the current code happens to emit. A snapshot written against the implementation's own output locks its bugs in.

This is not a validator-only rule. The same happy-path bias hides serializer corruption, schema loss, compiler-process failures, and native diagnostic regressions, so every feature carries the burden.