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 controller name, a DTO name, 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 in the same package and mirror its naming, location, and code style; don't create parallel structures.
• Respect package boundaries. The Go binary lives in @nestia/core and is shared with @nestia/sdk as a linked contributor. Don't fork a second native binary, don't give @nestia/sdk its own ttsc plugin entry, and don't reintroduce a TypeScript-side transformer.
• Keep detection general and installation-safe. The native transform must locate target packages through their resolved package root, as packages/core/native/transform.cjs does with require.resolve("@nestia/sdk/package.json", { paths }) and packages/sdk/src/transform.ts with createRequire(...).resolve("@nestia/sdk/package.json"). Workspace-only path substrings break the moment a consumer installs from npm. The same rule applies to the generators: no hard-coded DTO, controller, or feature names.
• Preserve the public contract in .agents/skills/project/SKILL.md. Decorator names, INestiaConfig options, CLI flags, and the generated SDK / Swagger / e2e surface are public; renaming or removing any of them is a deliberate product change, not incidental cleanup.
• Use the workspace catalogs. pnpm-workspace.yaml pins versions under catalog:typescript, catalog:samchon, catalog:nestjs, catalog:utils, catalog:modelcontextprotocol, and catalog:rolldown. New dependencies go through the matching catalog; internal references use workspace:^.
• Migration templates ship without interactive dependencies — generated projects stay non-interactive.
• Keep local outputs local. Do not commit .env, the tarballs under deploy/tarballs/, or any tree the harnesses regenerate (tests/test-e2e/.tmp-*, generated consumers and benchmark reports under the integrated E2E workspace).
• 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 once on the final pull-request changes before merge and include its result in that pull request. Formatting is not a prerequisite for each commit or push, including campaign commits. If later edits change a formatter target, rerun it before merge; an unchanged final snapshot needs no repeat. One invocation covers both the package and test trees, so no workspace needs formatting separately. All other validation and merge gates remain required.

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, including the generated SDK, Swagger document, mockup simulator, and e2e suite;
• normal, error, and recovery state transitions;
• both HTTP adapters — a decorator or transform change that behaves differently on Express and Fastify is two behaviors, not one;
• 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 nestia from the ttsc.plugin.transform entry in packages/core/package.json, which points at packages/core/native/transform.cjs. That descriptor owns the composition model documented in .agents/skills/project/SKILL.md: the cmd/ttsc-nestia Go source, composes: ["typia/lib/transform"], and the conditional @nestia/sdk contributor.

Keep type analysis, AST rewriting, diagnostics, and transform options on the Go side. Consumer projects add a compilerOptions.plugins entry only when they need to set optional transform flags.

Test workspaces point at @nestia/core/native/transform.cjs. Do not add a second plugin host, or a separate @nestia/sdk plugin entry, to make a local layout pass.

Testing

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. Nothing enforces it mechanically — DynamicExecutor gates on the test prefix only and will happily run a file exporting three functions or one whose export name disagrees with its filename — so the discipline is yours to keep.

Go tests

Go unit tests live in two dedicated package modules, not beside the source:

• packages/core/test, run by pnpm --filter @nestia/core test:go.
• packages/sdk/test, run by pnpm --filter @nestia/sdk test:go.

Each module carries replace directives back to ../native (and, for the SDK, to ../../core/native) plus the pinned typescript-go shim redirects. Use one Test* function per file, named after the assertion, and mirror a nearby test's package, fixture, and cleanup pattern. Exercise option, analysis and emit semantics through the owning operations in-process; reserve native-binary or installed-CLI execution for the necessary wrapper connection in the E2E population. Do not rebuild or launch a host per rule.

Generated-validator runtime connections share the SDK integration preparation. Pure option selection, diagnostics and declaration provenance belong to the core unit module; a native dispatch plus Node execution is an integration boundary even if its test file is Go. Count those actual operations separately from test-language preparation.

Native production trees contain no *_test.go; root pnpm test:go runs the two owning test/ modules. Keep new tests there unless same-package access is necessary and wire any exceptional test location into the canonical runner. Package compilation remains a prerequisite, not an additional empty test population.

Every test:go script passes -count=1, and so should a hand-run go test. Cacheable mode instruments the test binary to record every file a test opens, and these tests open the whole TypeScript program and its node_modules typings, which on Windows made one package take minutes instead of seconds. A cached pass would also be stale, because the tests read the pnpm-installed toolchain and fixtures outside Go's view.

TypeScript suites

The TypeScript workspaces are test-benchmark, test-cli, test-e2e, test-editor, test-migrate and test-sdk. tests/test-e2e contains only direct units of packages/e2e; do not place SDK, migration or other integration cases there. SDK and migration workspaces separate their direct unit entries from necessary integration connections. test-transform-options is retired: native option semantics belong to the owning Go units and necessary installed-loader/runtime connections share the SDK integration preparation. Empty legacy entries must not produce a vacuous pass.

Classify by the real call path. Consumer installation, separate product compilation, Nest application creation, HTTP hosts, worker sessions and CLI/IPC processes are integration preparation. Running TypeScript test source is language preparation; directly calling a parser, composer or writer with authored input remains unit logic when it does not create those integration boundaries. Loading an already-built internal operation by absolute path does not itself make the direct unit E2E.

Function-per-file unit entries use DynamicExecutor under src/features/**; editor browser cases use src/browser/features/** in a separate process to prevent DOM-dependent initialization leaking into SSR. Export exactly one test_<snake_case> function from a matching filename. Name helpers outside the discovered prefix, derive the source extension from __filename and reject zero discoveries.

The sole E2E entry owns shared preparation and teardown. Combine compatible connections into one rich authored input program and one generated consumer, using public ttsc/ttsx or TtscCompiler. Do not preserve per-feature compiler contexts behind two Node processes, create arbitrary shards, invoke the old workspace starts or introduce a dedicated SDK Go host. Transfer exact pure name/schema/option judgments to their owning units when independent-program premises conflict with a shared fixture.

Record every original valid assertion's owning operation, independent oracle, normal/error controls, unit or integration destination and preparation costs before replacing its execution path. Rich migration inputs must retain request/response, security, multipart, plain-text and schema distinctions; lowering fixture thresholds or treating compile success as those assertions is invalid. Failed preparation and tests retain their first result, and cleanup must cover partial startup.

Keep code under a JSDoc @example unfenced. The JSDoc formatter can emit a closing fence with a trailing semicolon and move acknowledgment tags behind it, making the checker read those tags as example code. Use a description-level fenced block when a displayed fence is needed, and separate acknowledgment tags from prose with a blank comment line.

Use the shared helpers in @nestia/e2e and each suite's local internal/ helpers. Do not reach into another suite's internals.

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 @TypedBody with `validate: "assertPrune"` strips extras from both
 * input and return value.
 *
 * Locks the assertPrune branch of the native body validator. Other validate
 * modes pass the input through untouched; only the Prune family removes
 * extras, and the transform has to pick the matching typia helper. A
 * regression in helper selection would silently fall back to a non-pruning
 * validator and let extra properties through.
 *
 * 1. Build a controller method with `@TypedBody()` and `validate: "assertPrune"`.
 * 2. Send a payload carrying an extra property.
 * 3. Assert the extra is missing from both the input and the return value.
 */
export const test_body_config_assertPrune_strips_extras = (): void => {
  /* ... */
};

Coverage, not happy paths

A test that only feeds a controller its ordinary valid input and asserts a 200 proves one path, not correctness. The transform spans validators, serializers, Swagger metadata, SDK emit, mockup simulators, and diagnostics; 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 the generators, start from a hand-written controller and verify the generated SDK, Swagger, or e2e output — not merely that an existing output still 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. Rejected authored inputs in the owning unit or shared E2E fixture supply the same negative controls.
• Boundaries. Cover the empty case, the single-element case, recursion limits, optional and nullable members, exact numeric limits, deepest nesting, and the decorator option or compiler flag that flips the decision.
• Oracle-derived expectations. Take expected behavior from TypeScript semantics, the NestJS contract, and the authoritative OpenAPI specification — never from whatever the current code happens to emit. A snapshot written against the implementation's own output locks its bugs in.